Simple Encoding API - Live

Simple Live Encoding Jobs are quick and easy way to transcode your RTMP or SRT Input into a best practise bitrate ladder for efficient and high-quality using DASH/HLS delivery to your audience. All you need is a single API call that provides the input type you want to use, and output destination details where to store the encoded live content.

1. Encoder Version: STABLE
2. SDK Version: v 1.106.0 or higher
3. Input: SRT or RTMP (push only)

• Input Sources: RTMP, SRT
• Encoding Profile: INCREASED_QUALITY or LOWER_LATENCY
• Output Destinations: AWS S3, Google Cloud Storage (GCS), Azure Blob Storage (ABS), Akamai NetStorage
  • Output Characteristics:
    At least one Output Destination
    Video: H264, segmented fMP4, fixed rendition ladder (240p, 360p, 480p, 720p, 1080p)
    Audio: AAC, segmented fMP4, one audio rendition only
    Highest Resolution selectable (SD = up to 480p, HD up to 720p, FULL_HD up to 1080p)
    * Manifests: DASH/HLS
• Auto-shutdown: When the ingest is disconnected for more the 10 minutes the live encoding will be shut down. The Simple Live Encoding will not be shut down if no stream was ever connected.

A Simple Live Encoding Job is defined by an

• An input source
• An output destination
• An encoding profile
• A cloud region.

that’s it! :)

Once a Simple Encoding Job is started, the template is converted into an actual Encoding, adapted to the input and output definition.

Job lifecycle

After starting the Simple Live Encoding Job, it goes through the following stages:

• CREATED: Job has been created is waiting to be started.
• EXECUTING: Job is currently being executed and creating an Live Encoding
• FAILURE: Job could not create an Live Encoding, errors property for more information
• RUNNING: Job created an Live Encoding. At this time, an encoding-ID is available and the Live Encoding itself is either in state QUEUED or RUNNING and provides the details needed to configure an input source (e.g. OBS Studio, hardware encoders, etc) to push their signal to the Live Encoding.
• FINISHED: The Encoding created by this job finished successfully
• ERROR: The Encoding created by this job failed, errors property for more information
• CANCELED: The Encoding has been started but has been canceled manually by the user.

You can retrieve status information with the Job details endpoint

Note that the Encoding created and managed by the Job has its own statuses, documented in this FAQ, and queried through the Encoding Status endpoint.

REST API Call

The simplest way to create a simple encoding is a plain HTTP POST request sent to the Bitmovin API or try it with this Postman Collection.

1curl --location --request POST 'https://api.bitmovin.com/v1/encoding/simple/jobs/live' \
2--header 'x-api-key: YOUR_BITMOVIN_API_KEY' \
3--header 'Content-Type: application/json' \
4--data-raw '{
5    "cloudRegion": "EUROPE",
6    "encodingProfile": "INCREASED_QUALITY",
7    "input": {
8        "inputType": "RTMP"
9    },
10    "outputs": [
11        {
12            "url": "s3://yourbucket/path/to/your/live-folder/{uuid}/",
13            "credentials": {
14                "accessKey": "S3_OUTPUT_ACCESS_KEY",
15                "secretKey": "S3_OUTPUT_SECRET_KEY"
16            },
17            "makePublic": true,
18            "maxResolution": "FULL_HD"
19        }
20    ]
21}'

Bitmovin OpenAPI SDK

Beyond a plain HTTP POST, you can use any of the Bitmovin SDKs to start your job. The following code sample is the equivalent of the REST API call above, but using the Bitmovin OpenAPI Java SDK.

1var input = new SimpleEncodingLiveJobInput();
2input.setInputType(SimpleEncodingLiveJobInputType.RTMP);
3
4var outputCredentials = new SimpleEncodingLiveJobAccessKeyCredentials();
5outputCredentials.setAccessKey("AccessKey");
6outputCredentials.setSecretKey("SecretKey");
7
8var output = new SimpleEncodingLiveJobUrlOutput();
9output.setUrl("s3://yourbucket/path/to/your/live-folder/{uuid}/");
10output.setCredentials(outputCredentials);
11output.setMakePublic(true);
12output.setMaxResolution(SimpleEncodingLiveMaxResolution.FULL_HD);
13
14SimpleEncodingLiveJobRequest job = new SimpleEncodingLiveJobRequest();
15job.setCloudRegion(SimpleEncodingLiveCloudRegion.EUROPE);
16job.setEncodingProfile(SimpleEncodingLiveProfile.INCREASED_QUALITY);
17job.setInput(input);
18job.addOutputsItem(output);
19
20var jobResponse = api.simple.jobs.live.create(job);
21do {
22  Thread.sleep(5000);
23  jobResponse = api.simple.jobs.live.get(jobResponse.getId());
24} while (jobResponse.getStatus() != SimpleEncodingLiveJobStatus.RUNNING);
25
26//Stop the Live Encoding
27api.encodings.live.stop(jobResponse.getEncodingId());

A list of all available cloudRegion values can be found in our API-Reference.

RTMP

• Encoder URL: rtmp://<EXTERNAL_IP>/live/<STREAM_KEY>

This URL you will have to enter into the configuration of your RTMP Encoder, so it can push your livestream input stream to your Bitmovin Simple Live Encoding. The <EXTERNAL_IP> and <STREAM_KEY> become available as soon as the Live Encoding is in status RUNNING. They can be obtained either

• ... by viewing the details of the Live Encoding in the Bitmovin dashboard, or
• ... by querying the details of the Simple Live Encoding Job from the API, and extracting its externalIp and streamKey property.

Code Sample (Bitmovin OpenAPI Java SDK):

1var input = new SimpleEncodingLiveJobInput();
2input.setInputType(SimpleEncodingLiveJobInputType.RTMP);

SRT

• Encoder URL: srt://<EXTERNAL_IP>:2088

This URL you will have to enter into the configuration of your SRT Encoder, so it can push your livestream input stream to your Bitmovin Simple Live Encoding. The <External_IP> for the Live Encoding Ingest Endpoint becomes available as soon as the Live Encoding is in status RUNNING. It can be obtained either

• ... by viewing the details of an Live Encoding in the Bitmovin dashboard, or
• ... by querying the details of the Simple Live Encoding Job from the API

Code Sample (Bitmovin OpenAPI Java SDK):

1var input = new SimpleEncodingLiveJobInput();
2input.setInputType(SimpleEncodingLiveJobInputType.SRT_LISTENER);

In order to ensure that the output path is unique for all your Live Encodings, and avoid files being overridden, we recommend that you add a {uuid} placeholder in the path, which will be replaced with a unique identifier at run-time.

Folder Structure

Simple Encoding Jobs will create the following folder structure at the given destination. The output files can be found in the following locations on every configured output:

<scheme>://<bucket>/path/to/your/live-folder/{uuid}/

• video/{width}x{height}_{bitrate}/ (multiple subfolders containing different output renditions)
• audio/ (folder containing audio output files)
• index.m3u8 (HLS manifest file)
• stream.mpd (DASH manifest file)

AWS S3

• s3://<my-bucket>/path/to/live/{uuid}/

Credentials for S3 URLs are mandatory and can be provided via AWS access/secret keys or role-based authentication. Generic S3 is currently not supported.

AWS Access/Secret Keys

1var keyCredentials = new SimpleEncodingLiveJobAccessKeyCredentials();
2keyCredentials.setAccessKey("ACCESSKEYHERE");
3keyCredentials.setSecretKey("SECRETKEYHERE");
4input.setCredentials(keyCredentials);
5
6var output = new SimpleEncodingLiveJobUrlOutput();
7output.setUrl("s3://my-bucket/{uuid}/path/to/destination/folder/");
8output.setCredentials(keyCredentials);

Role-based

1var roleBasedCredentials = new SimpleEncodingLiveJobS3RoleBasedCredentials();
2roleBasedCredentials.setRoleArn("arn:aws:iam::123456789012:role/OurS3AccessRole");
3roleBasedCredentials.setUseExternalId(true);
4
5var output = new SimpleEncodingLiveJobUrlOutput();
6output.setUrl("s3://my-bucket/path/to/destination/folder/");
7output.setCredentials(roleBasedCredentials);

useExternalId (default: false) is an optional property and controls if the customer’s orgId should be used as externalId when assuming the AWS role, or not. Its an additional security measure to prevent unauthorized users assume a role by obtaining the role ARN somehow. For more details, please see S3 Role-Based Input for details about the externalId, and be aware that the simple encoding API only supports the externalIdMode GLOBAL.

Google Cloud Storage (GCS)

• gcs://<my-bucket>/path/to/live/{uuid}/

Credentials for GCS URLs are mandatory and can be provided as HMAC keys or a service account.

HMAC Keys

1var keyCredentials = new SimpleEncodingLiveJobAccessKeyCredentials();
2keyCredentials.setAccessKey("ACCESS_ID");
3keyCredentials.setSecretKey("SECRET");
4
5var output = new SimpleEncodingLiveJobUrlOutput();
6output.setUrl("gcs://my-bucket/path/to/destination/folder/");
7output.setCredentials(keyCredentials);

Service-Account

Note that the service credentials provided in the following snippet are just for example. You need to obtain your service credentials from your GCP account.

1var serviceAccountCredentials = new SimpleEncodingLiveJobGcsServiceAccountCredentials();
2serviceAccountCredentials.setServiceAccountCredentials("{\n"
3    + "    \"type\": \"service_account\",\n"
4    + "    \"project_id\": \"bitmovin\",\n"
5    + "    \"private_key_id\": \"abcdefghijklmnopqrstuvwxyz\",\n"
6    + "    \"private_key\": \"-----BEGIN PRIVATE KEY-----\\nOwdXyjRT9F4A==\\n-----END PRIVATE KEY-----\\n\",\n"
7    + "    \"client_email\": \"[email protected]\",\n"
8    + "    \"client_id\": \"10440564562784234997\",\n"
9    + "    \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n"
10    + "    \"token_uri\": \"https://oauth2.googleapis.com/token\",\n"
11    + "    \"auth_provider_x509_cert_url\": \"https://www.googleapis.com/oauth2/v1/certs\",\n"
12    + "    \"client_x509_cert_url\": \"https://www.googleapis.com/robot/v1/metadata/x509/bitmovin%40bitmovin.iam.gserviceaccount.com\"\n"
13    + "}");
14
15var output = new SimpleEncodingLiveJobUrlOutput();
16output.setUrl("gcs://my-bucket/path/to/destination/folder/");
17output.setCredentials(serviceAccountCredentials);

Azure Blob Storage

• https://<account>.blob.core.windows.net/<container>/path/to/live/{uuid}/

Credentials for Azure Blob Storage URLs are mandatory and can be provided via the storage account accesss key credentials.

1var azureCredentials = new SimpleEncodingLiveJobAzureCredentials();
2azureCredentials.setKey("STORAGE_KEY");
3
4var output = new SimpleEncodingLiveJobUrlOutput();
5output.setUrl("https://.blob.core.windows.net//path/to/destination/folder/);
6output.setCredentials(azureCredentials);

Akamai NetStorage

• https://<host>-nsu.akamaihd.net/<CP-code>/path/to/live/{uuid}/

Credentials for Akamai NetStorage URLs are mandatory and can be provided via username and password

1var authenticationCredentials = new SimpleEncodingLiveJobUsernamePasswordCredentials();
2authenticationCredentials.setUsername("USERNAME");
3authenticationCredentials.setPassword("PASSWORD");
4
5var output = new SimpleEncodingLiveJobUrlOutput();
6output.setUrl("akamai-ns://my-akamai-host-nsu.akamaihd.net/path/to/destination/folder/");
7output.setCredentials(authenticationCredentials);

• DRM Protection is not available.
• Audio
  • Only the first audio track is extracted from an input file
  • The Output Channel Layout is going to be STEREO (2.0), regardless of what is provided by the input stream.
• Webhooks: Once a Simple Live Encoding Job is successfully started, standard generic Live Encoding webhooks can be used to track the progress of the live encoding.