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's | Con'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 manifests | Manifests 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's | Con'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 ..
- (API-Reference) Create a
DashManifest
Object - (API-Reference) Add a
Period
to it which will hold all the resources below - (API-Reference) Add a
VideoAdaptationSet
to thatPeriod
- (API-Reference) Add a
fmp4Representation
for each video representation to theVideoAdaptationSet
you want to be available to a player for bitrate adaptation - (API-Reference) Add a
AudioAdaptationSet
to thatPeriod
- (API-Reference) Add a
fmp4Representation
for each video representation to theAudioAdaptationSet
you want to be available to a player for bitrate adaptation - (API-Reference) Start the manifest creation
Pro's | Con's |
---|---|
Build manifests to meet the needs for custom video delivery workflows | Either 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 it | Encoding 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.
Updated 6 days ago