[object Object] Icon

Encoding
Learn how to create, start, manage and modify Encodings

[object Object] Icon

Player
Learn how to create, start, manage and modify Players

[object Object] Icon

Analytics
Learn how to create, start, manage and modify Analyticss

Docs Home
User shortcuts for search
Focus by pressing f
Hide results by pressing Esc
Navigate via   keys

Tue Dec 14 2021

Simple Encoding API

Tue Dec 14 2021

OverviewLink Icon

Simple Encoding Jobs are quick and easy way to convert your input files into streamable content that gets automatically optimized for efficient and quality-optimized DASH/HLS delivery. All you need is a single API call that provides the input and output location details.

RequirementsLink Icon

  • SDK Version: 1.98.0 or higher
  • Encoder Version: STABLE only
  • Content Type: VoD only

Supported FeaturesLink Icon

Input Sources:

  • HTTP(S), (S)FTP, S3, GCS, Azure Blob Storage (ABS), Akamai NetStorage

Output Destinations:

  • S3, GCS, Azure Blob Storage (ABS), Akamai NetStorage

Input Characteristics:

  • 1 Video Input (required)
  • 0 or more audio inputs
    • Subtitles: external subtitle files (SRT, TTML, WebVTT), if supplied

Output Characteristics:

  • Video: H264 only, segmented fMP4, renditions determined by our Per-Title algorithm
  • Audio: AAC only, segmented fMP4, one rendition per audio input
  • Manifests: DASH / HLS
  • Subtitles: WebVTT

Thumbnails: (every 5s)

  • low-res
  • high-res

Sprites (every 5s)


Known LimitationsLink Icon

  • Encoding Templates: H264 only at the moment
  • Unsupported Input Types: Anamorphic inputs(where DAR/SAR requires configuration), 3D/VR content, HDR content
  • Audio
    • Only the first audio track is extracted from an input file
    • Channel Layout is going to be STEREO (2.0), regardless what is used by the input file.
  • Video
    • Filters/Transformations aren’t supported nor automatically applied (e.g. interlaced content remains interlaced)
  • Webhooks: Once a Simple Encoding Job was successfully started, standard generic encoding webhooks can be used to track the progress of the encoding.

IntroductionLink Icon

A Simple Encoding Job is defined by an

  • Input Source, and an
  • Output Destination
  • (Encoding Template)

that’s it :) Once a Simple Encoding Job is started, it will create an actual encoding out of the given configuration and encoding template. The latter is a pre-defined set of configurations the encoding shall be executed with. At the moment only one template is available (for H264) and therefore used by default.

Like an encoding, a Simple Encoding Job has to be started in order to kick of its processing which is described by the following states:

  • CREATED: Job has been created is waiting to be started.
  • EXECUTING: Job is currently being executed and creating an encoding
  • FAILURE: Job could not create an encoding, check the errors property for more information
  • RUNNING: Job created an encoding and is awaiting it to be executed
  • At this time, an encoding-ID is available and the encoding itself is either in state QUEUED or RUNNING
  • FINISHED: The encoding created by this job finished successfully
  • ERROR: The encoding created by this job failed, check the errors property for more information
  • CANCELED: The encoding has been started but has been canceled manually by the user

Create a Simple Encoding JobLink Icon

The following is a code example based on the Bitmovin OpenAPI Java SDK:

1// define input
2var input = new SimpleEncodingVodJobUrlInput();
3input.setUrl("s3://my-bucket/path/file.mp4");
4
5// input credentials
6var inputCredentials = new SimpleEncodingVodJobAccessKeyCredentials();
7inputCredentials.setAccessKey(S3_INPUT_ACCESS_KEY);
8inputCredentials.setSecretKey(S3_INPUT_SECRET_KEY);
9input.setCredentials(inputCredentials);
10
11// define output
12var output = new SimpleEncodingVodJobUrlOutput();
13output.setUrl("s3://my-bucket/path/to/destination/folder/");
14
15// output credentials
16var outputCredentials = new SimpleEncodingVodJobAccessKeyCredentials();
17outputCredentials.setAccessKey(S3_OUTPUT_ACCESS_KEY);
18outputCredentials.setSecretKey(S3_OUTPUT_SECRET_KEY);
19output.setCredentials(outputCredentials);
20
21// put it all together
22SimpleEncodingVodJobRequest simpleEncodingJob = new SimpleEncodingVodJobRequest();
23simpleEncodingJob.addInputsItem(input);
24simpleEncodingJob.addOutputsItem(output);
25
26// call API
27api.simple.jobs.vod.create(simpleEncodingJob);

Input TypesLink Icon

Video & Audio

As inputs you can provide file that provide video+audio, audio only and subtitle files. At least one Input is required that provides a video track to process. If no dedicated type is provided, the video track and audio track(if present) will be processed by default.

Audio Language (Optional): Even though it is not mandatory, we recommend always setting language on audio input (and input without an inputType specified) to indicate to the players in the manifest which one to choose from. The language code must be compliant with BCP 47.

Single Input

1var input = new SimpleEncodingVodJobUrlInput();
2input.setUrl("s3://my-bucket/path/file.mp4");
3input.setLanguage("en");

Multiple Inputs

If you want to process more than one input (e.g. multiple audio tracks in addition to the video track), you have to specify which input type each file provides by stating VIDEO, or AUDIO. Any audio tracks present in VIDEO inputs will be ignored.

1var videoInput = new SimpleEncodingVodJobUrlInput();
2videoInput.setUrl("https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov");
3videoInput.setInputType(SimpleEncodingVodJobInputType.VIDEO);
4
5// define audio input
6var audioInput1 = new SimpleEncodingVodJobUrlInput();
7audioInput1.setUrl("https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov");
8audioInput1.setInputType(SimpleEncodingVodJobInputType.AUDIO);
9audioInput1.setLanguage("en");
10
11// define audio input
12var audioInput2 = new SimpleEncodingVodJobUrlInput();
13audioInput2.setUrl("https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov");
14audioInput2.setInputType(SimpleEncodingVodJobInputType.AUDIO);
15audioInput2.setLanguage("de");

Subtitles & Closed Captions

SUBTITLE 's and CLOSED_CAPTION 's are also supported input types. What is the difference though? Both work in a very similar way but there is a distinction in their usage, intent and goal for the viewer.

  • Subtitles are mostly used to translate spoken audio as text on the screen (usually into a different language), closed captions are specifically used to support and improve the accessibility for the hearing-impaired audience (also in the same language as the audio track).
  • Closed Captions usually include additionally indications of sound effects and other noises - for example car honks - or speaker changes (person A speaks followed by person B answering), thus supporting deaf and hard-of-hearing people in following the content.

Both input types have to be either SRT, TTML, or WebVTT indicated by their file extensions .srt, .ttml, or .vtt. It is required to specify their inputType as well as a language for each. The language code must be compliant with BCP 47. The Simple Encoding Job will convert all provided subtitles/closed captions to WebVTT and add them to the DASH and HLS manifest using the language as label.

1// define closed captions
2var closedCaptionsInputEn = new SimpleEncodingVodJobUrlInput();
3closedCaptionsInputEn.setUrl("https://download.blender.org/demo/movies/ToS/subtitles/TOS-en.srt");
4closedCaptionsInputEn.setLanguage("en");
5closedCaptionsInputEn.setInputType(SimpleEncodingVodJobInputType.CLOSED_CAPTION);
6
7// define subtitles
8var subtitleInputEn = new SimpleEncodingVodJobUrlInput();
9subtitleInputEn.setUrl("https://download.blender.org/demo/movies/ToS/subtitles/TOS-en.srt");
10subtitleInputEn.setLanguage("en");
11subtitleInputEn.setInputType(SimpleEncodingVodJobInputType.SUBTITLE);

Inputs & OutputsLink Icon

The structure of both input and output is very similar, consisting of a property url and an - depending on the scheme optional - credentials:

1{
2 "url": "scheme://path",
3 "credentials": {...}
4}

While an input path URL has to point to a FILE, an output path URL has to point to a destination folder where all the generated output files will be stored in (please see Output Folder Structure for more details).


HTTP/HTTPS (Input only)

  • http://<host>[:<port>]/path/file.mp4
  • https://<host>[:<port>]/path/file.mp4

The port is defaulted to 80 if it's not provided. It’s possible to either provide no credentials(unauthenticated access) or username/password for Basic Authentication.

Unauthenticated:

1var input = new SimpleEncodingVodJobUrlInput();
2input.setUrl("https://<host>[:<port>]/path/file.mp4");

BasicAuth:

1var inputCredentials = new SimpleEncodingVodJobUsernamePasswordCredentials();
2inputCredentials.setUsername("USERNAME");
3inputCredentials.setPassword("PASSWORD");
4
5//define an input
6var input = new SimpleEncodingVodJobUrlInput();
7input.setUrl("https://<host>[:<port>]/path/file.mp4");
8input.setCredentials(inputCredentials);

(S)FTP (Input only)

  • ftp://<host>[:<port>]/path/file.mp4
  • sftp://<host>[:<port>]/path/file.mp4

The port is defaulted to 21 (ftp) or 22 (sftp) if it's not provided. It’s possible to either provide no credentials (unauthenticated access) or username/password.

Unauthenticated:

1var input = new SimpleEncodingVodJobUrlInput();
2input.setUrl("ftp://<host>[:<port>]/path/file.mp4");

BasicAuth:

1var inputCredentials = new SimpleEncodingVodJobUsernamePasswordCredentials();
2inputCredentials.setUsername("USERNAME");
3inputCredentials.setPassword("PASSWORD");
4
5//define an input
6var input = new SimpleEncodingVodJobUrlInput();
7input.setUrl("ftp://<host>[:<port>]/path/file.mp4");
8input.setCredentials(inputCredentials);

AWS S3

  • s3://<my-bucket>/path/file.mp4

Credentials for S3 URLs are mandatory and can be provided via accessKey/secretKey or role-based authentication. Generic S3 is currently NOT supported.

Unauthenticated:

1var input = new SimpleEncodingVodJobUrlInput();
2input.setUrl("s3://my-bucket/path/file.mp4");

Access/Secret Key:

1var keyCredentials = new SimpleEncodingVodJobAccessKeyCredentials();
2keyCredentials.setAccessKey("ACCESSKEYHERE");
3keyCredentials.setSecretKey("SECRETKEYHERE");
4input.setCredentials(keyCredentials);
5
6//define an input
7var input = new SimpleEncodingVodJobUrlInput();
8input.setUrl("s3://my-bucket/path/file.mp4");
9input.setCredentials(keyCredentials);
10
11//define an output
12var output = new SimpleEncodingVodJobUrlOutput();
13output.setUrl("s3://my-bucket/path/to/destination/folder/");
14output.setCredentials(keyCredentials);

Role-based:

1var roleBasedCredentials = new SimpleEncodingVodJobS3RoleBasedCredentials();
2roleBasedCredentials.setRoleArn("arn:aws:iam::123456789012:role/OurS3AccessRole");
3roleBasedCredentials.setUseExternalId(true);
4
5//define an input
6var input = new SimpleEncodingVodJobUrlInput();
7input.setUrl("s3://my-bucket/path/file.mp4");
8input.setCredentials(roleBasedCredentials);
9
10//define an output
11var output = new SimpleEncodingVodJobUrlOutput();
12output.setUrl("s3://my-bucket/path/to/destination/folder/");
13output.setCredentials(roleBasedCredentials);

useExternalId is an optional property and controls if the customer’s orgId should be used as externalId when assuming the AWS role, or if no such externalId should be used. See S3 Role-Based Input for details about the externalId, note that the simple encoding API only supports the externalIdMode GLOBAL.


Google Cloud Storage (GCS)

  • gcs://<my-bucket>/path/file.mp4

Credentials for GCS URLs are mandatory and can be provided via accessKey/secretKey or a service account.

Unauthenticated:

1var input = new SimpleEncodingVodJobUrlInput();
2input.setUrl("gcs://my-bucket/path/file.mp4");

Access/Secret Key: var keyCredentials = new SimpleEncodingVodJobAccessKeyCredentials(); keyCredentials.setAccessKey("GOOGLEACCESSKEYHERE"); keyCredentials.setSecretKey("GOOGLESECRETKEYHERE");

//define an input var input = new SimpleEncodingVodJobUrlInput(); input.setUrl("gcs://my-bucket/path/file.mp4"); input.setCredentials(keyCredentials);

//define an output var output = new SimpleEncodingVodJobUrlOutput(); output.setUrl("gcs://my-bucket/path/to/destination/folder/"); output.setCredentials(keyCredentials);

Service-Account:

1var serviceAccountCredentials = new SimpleEncodingVodJobGcsServiceAccountCredentials();
2serviceAccountCredentials.setServiceAccountCredentials("YOUR_SERVICE_ACCOUNT_JSON_STRING");
3
4var input = new SimpleEncodingVodJobUrlInput();
5input.setUrl("gcs://my-bucket/path/file.mp4");
6input.setCredentials(serviceAccountCredentials);
7
8var output = new SimpleEncodingVodJobUrlOutput();
9output.setUrl("gcs://my-bucket/path/to/destination/folder/");
10output.setCredentials(serviceAccountCredentials);

Check out GCS Service Account Input for more information.


Azure Blob Storage

  • https://<account>.blob.core.windows.net/<container>/path/file.mp4

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

1var azureInputCredentials = new SimpleEncodingVodJobAzureCredentials();
2azureInputCredentials.setKey("YOUR_AZURE_KEY");
3
4//define an input
5var input = new SimpleEncodingVodJobUrlInput();
6input.setUrl("https://<account>.blob.core.windows.net/<container>/path/file.mp4");
7input.setCredentials(azureInputCredentials);
8
9//define an output
10 var output = new ReducedEncodingVodJobUrlOutput();
11output.setUrl("https://<account>.blob.core.windows.net/<container>/path/to/destination/folder/);
12output.setCredentials(azureOutputCredentials);

Akamai NetStorage

  • https://<host>-nsu.akamaihd.net/<CP-code>/path/file.mp4

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

1var authenticationCredentials = new SimpleEncodingVodJobUsernamePasswordCredentials();
2authenticationCredentials.setUsername("YOURAKAMAINETSTORAGEUSERNAME");
3authenticationCredentials.setPassword("YOURAKAMAINETSTORAGEPASSWORD");
4
5//define an input
6var input = new SimpleEncodingVodJobUrlInput();
7input.setUrl("https://my-akamai-host-nsu.akamaihd.net/123456/path/file.mp4");
8input.setCredentials(authenticationCredentials);
9
10//define an output
11var output = new ReducedEncodingVodJobUrlOutput();
12output.setUrl("https://my-akamai-host-nsu.akamaihd.net/path/to/destination/folder/");
13output.setCredentials(authenticationCredentials);

Output Folder StructureLink Icon

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:

  • /video
    • /h264/{width}x{height}_{bitrate}/ (multiple subfolders containing different output renditions)
  • /audio
    • /aac/{language}/ - if language is unique (subfolder containing audio output files)
    • /aac/{language}_{index}/ - if language is not unique (subfolder containing audio output files)
  • /subtitles (subfolder containing subtitles files)
  • /captions (subfolder containing captions files)
  • /sprites (subfolder containing generated sprites)
  • /thumbnails (subfolder containing generated thumbnails)
  • /index.m3u8 (HLS manifest file)
  • /stream.mpd (DASH manifest file)

fb11638a-f5f3-43b3-86c6-c192a207b8ae

Give us feedback