How to create Manifests for your Encodings

Overview

Encoding your content into a streamable format is the first big step to improve your VoD experience for your viewers. The second most important one is to create an HLS and/or MPEG-DASH manifest so an HTML5 ABR Player can play the content.Our Service provides multiple ways to create these manifests, so you can select the most suitable one for your workflow.

You can either have them generated automatically as part of the encoding process itself or after the encoding finished successfully, or you can create customized manifests on your own. The Pro's and Con's of each approach will be explained below as well as how to create them.

Requirements

Supported Streaming Formats: MPEG-DASH, HLS, SMOOTH

Supported Workflows: VOD, LIVE-2-VOD

The requirements vary for each available option. Please see its section for more details.

Option 1 - NEW - Automatically create manifests as part of the encoding process

Requirements

  • Encoder Version: 2.86 or higher
  • API SDK: v1.81 or higher
  • ManifestGenerator Version: V2 or higher

(Recommended) One of the most common use-cases for manifests is to create one that references all the content that is created by an encoding (video/audio renditions, subtitles, thumbnail tracks, etc). The DefaultManifest resources simply allow you to do that. That you can easily achieve by providing a simple manifest configuration to the /start API call (API Reference) for each of your desired streaming formats.

Doing so, instead of having to wait for the encoding to finish and then to create the manifest, you can have it created implicitly as part of the encoding process. So, once the encoding is finished its content and all desired manifests were successfully written to the configured output storage.

Pro'sCon's
Simple workflow as you don't need to start the manifest creation process separately after an encoding.If the manifest creation fails (e.g. can't be transferred), the whole encoding fails
No polling/webhooks required - When the encoding is finished, so are its manifestsManifests can't include results from other encodings
Create multiple DASH/HLS/SMOOTH Manifests with one API call

DefaultManifests.java Example (Github)

...
DashManifest dashManifest = createDefaultDashManifest(encoding, output, "/");
HlsManifest hlsManifest = createDefaultHlsManifest(encoding, output, "/");

StartEncodingRequest startEncodingRequest = new StartEncodingRequest();
startEncodingRequest.setPerTitle(buildPerTitleStartRequest());

startEncodingRequest.setManifestGenerator(ManifestGenerator.V2);
startEncodingRequest.addVodDashManifestsItem(buildManifestResource(dashManifest));
startEncodingRequest.addVodHlsManifestsItem(buildManifestResource(hlsManifest));

executeEncoding(encoding, startEncodingRequest);
...

Option 2 - Create Default Manifests after an encoding

Default Manifests are great way to create manifests that reference generated outputs of one finished encoding only.

It doesn't require you to add each muxing of your encoding manually, but automatically discovers all outputs that were created by an encoding and references them in its generated manifest.

So, you only have to create the DefaultManifest Object, provide it with the ID of the encoding, and manifest output destination, and start its creation.

Pro'sCon's
Automatically discovers all outputs created by an encoding and references them in its manifest.Manifests can't include results from other encodings
Encoding has to be finished first, before a manifest can be created for it

Example: (Github)

...
executeEncoding(encoding);

generateDashManifest(encoding, output, "/");
generateHlsManifest(encoding, output, "/");

...

private static void generateDashManifest(Encoding encoding, Output output, String outputPath) throws Exception {
    DashManifestDefault dashManifestDefault = new DashManifestDefault();
    dashManifestDefault.setEncodingId(encoding.getId());
    dashManifestDefault.setManifestName("stream.mpd");
    dashManifestDefault.addOutputsItem(buildEncodingOutput(output, outputPath));

    dashManifestDefault = bitmovinApi.encoding.manifests.dash.defaultapi.create(dashManifestDefault);
    executeDashManifestCreation(dashManifestDefault); //Start manifest creation, and wait until its state is either FINISHED, or ERROR
}

private static void generateHlsManifest(Encoding encoding, Output output, String outputPath) throws Exception {
    HlsManifestDefault hlsManifestDefault = new HlsManifestDefault();
    hlsManifestDefault.setEncodingId(encoding.getId());
    hlsManifestDefault.addOutputsItem(buildEncodingOutput(output, outputPath));
    hlsManifestDefault.setName("master.m3u8");
    hlsManifestDefault.setVersion(HlsManifestDefaultVersion.V1);
    
    hlsManifestDefault = bitmovinApi.encoding.manifests.hls.defaultapi.create(hlsManifestDefault);
    executeHlsManifestCreation(hlsManifestDefault); //Start manifest creation, and poll status until its state is either FINISHED, or ERROR
}

Option 3 - Manually Create a Manifest

While being the most flexible approach, its also the most advanced one as you are creating a manifest from scratch. However, it does enable you to deal with use-cases that are often encountered in post-production workflows, or to meet the needs of custom workflow like creating ...

  • specialized manifests for different platforms,
  • manifests with a limited set of renditions of SD-subscribers of your service,
  • Re-creating manifests for contents where an additional audio/video/subtitle track became available (these tracks have to be encoded in the same way as the already exisiting ones, otherwise they won't comply with manifest requirements)
  • and more.

So, creating a manifest manually, enables you to utilize the flexibility of streaming formats, and cross-reference the outputs of different encodings, and create them exactly how you want them to be. You do need to know how MPEG-DASH or HLS manifests are structured and work, in order to do that as you have to create their structure as needed.

To create a common DASH Manifest (with some video and audio rendtions) you have to ..

  1. (API-Reference) Create a DashManifest Object
  2. (API-Reference) Add a Period to it which will hold all the resources below
  3. (API-Reference) Add a VideoAdaptationSet to that Period
  4. (API-Reference) Add a fmp4Representation for each video representation to the VideoAdaptationSet you want to be available to a player for bitrate adaptation
  5. (API-Reference) Add a AudioAdaptationSet to that Period
  6. (API-Reference) Add a fmp4Representation for each video representation to the AudioAdaptationSet you want to be available to a player for bitrate adaptation
  7. (API-Reference) Start the manifest creation
Pro'sCon's
Build manifests to meet the needs for custom video delivery workflowsEither requires to store necessary metadata like streamIds, muxingIds, drmIds, etc to, or to iterate through each encoding to obtain them to build a manifest from scratch
Re-create manifests and add additional content (e.g. new language track) to itEncoding has to be finished first, before manifest can be created
Reference contents from multiple different encodings within one single manifest

Example:

//Dedicated examples to build a manifest manually, will follow soon.