PlaylistCreator tool

The PlaylistCreator tool is an additional tool to create top level manifest for packaged content. You can use the tool to create top level manifest for both HDS and HLS.

The rationale for having set level manifest creation as a different step is that Offline Packager has a flat configuration structure (to enable input through the command-line or an XML file). For this reason, rendition-specific options cannot be specified while packaging. Each rendition must be packaged separately with its individual option. The set-level manifest creation must be performed later as a different step separate from packaging.The PlaylistCreator tool is a command line tool to enable you to develop scripts for the set-level manifest creation step.

The following configuration parameters are added for the PlaylistCreator tool:

Parameter name Description Data type Type
create_group Option/flag to only create groups for the given set of playlist files. NA
create_playlist Option/flag to create set level manifest/master playlist file NA
conf_path Specify path of configuration file to be used for parameters. String Optional
in_path Comma separated list of file-paths of input playlists. This should be the path of packaged contents. String Mandatory
out_path Out path for playlist/group file. String Mandatory
out_type Set output type. Available types: hds/hls. String Mandatory
top_level_prefix Filename prefix of set level manifest/master playlist. String Optional. Default "setLevel"
base_path Base file path for list of files given in in_path. String Mandatory
id Id for the group to be created to be used for HLS variant playlist. String Valid and mandatory for -create_group option.
default HLS only parameter for -create_group option.List of media-index (1-based index in the -in_path list) to be marked as DEFAULT in the group. String Optional
auto HLS only parameter for -create_group option.List of media-index (1-based index in the -in_path list) to be marked as AUTOSELECT in the group. String Optional
group_file_name Name of the output group file for -create_group option. String Valid and mandatory for -create_group option.
alternate HDS only parameter.List of media-index (1-based index in the -in_path list) to be marked as alternate. String Optional
group_files HLS only parameter. Comma separated list of file-path of the group files for -create_playlist option.This path has to be either absolute or relative to the base_path. String Optional

The following is a sample usage of the tool: 

Command:
java -jar PlaylistCreator.jar -create_playlist -in_path media1.f4m,media2.f4m,media3.f4m -out_type hds -out_path ~/Test/Output/hds -base_path ~/Test/Output/hds/media

Output:
This will create file setLevel.f4m at ~/Test/Output/hds:
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns="http://ns.adobe.com/f4m/2.0" version="2.0">
    <media bitrate="500" href="media1.f4m"> </media>    
				<media bitrate="1000" href="media2.f4m"> </media>
    <media bitrate="1500" href="media3.f4m"> </media>
</manifest>

Configuration file

Optionally, you can specify the configuration in a config.xml file. The parameter names to be used in the config.xml file are the same as the command line parameter names. For the command line flags(command line parameters which do not take any argument), to enable the flag in config file, just the tag should be provided.

java -jar PlaylistCreator.jar -conf_path path_of_conf_file

A sample configuration file for HDS (for the above example): 

<config>
<create_playlist/>
<in_path>media1.f4m,media2.f4m,media3.f4m</in_path>
<out_type>hds</out_type>
<out_path>~/Test/Output/hds</out_path>
<base_path>~/Test/Output/hds/media</base_path>
</config>

You can specify both the config.xml file and the command line arguments. The command line arguments take precedence over those in the config file. Users can use this feature to put the common config for different output types in a single config file. For example, to create AAXS protected HLS output using same certificates, content protection config can be put in a single xml and then that config xml can be used for HLS packaging and set level creation.

Sample common content protection config.xml: 

<config>
<drm/>
<lic_svr_cer>/Certificates/phds_license_server.der</lic_svr_cer>
<lic_svr_pfx>/Certificates/phds_license_server.pfx</lic_svr_pfx>
<lic_svr_pfx_pwd>FbsdseTCIZM=</lic_svr_pfx_pwd>
<pkgr_pfx>/Certificates/phds_production_packager.pfx</pkgr_pfx>
<pkgr_pfx_pwd>FbPMscTCIZM=</pkgr_pfx_pwd>
<transport_cer>/Certificates/phds_production_transport.der</transport_cer>
<common_key>/Certificates/commonkey.bin </common_key>
<policy_file>/Certificates/phds_24hr_policy.pol</policy_file>
<rec_cer>/Certificates/sd</rec_cer>
<content_id>primetime_demo_content</content_id>
</config>

You can now create an HLS set level playlist using the following command: 

Command:
-java -jar PlaylistCreator.jar -create_playlist -base_path ~/Test/Output -in_path ~/Test/Output/hls/30Sec/30Sec.m3u8 -out_path ~/Test/Output -out_type hls -top_level_prefix hlsTest -conf_path ~/Test/config.xml
Output: hlsTest.m3u8
 
#EXTM3U
#EXT-X-VERSION:4
#EXT-X-FAXS-CM:URI="hls/30Sec/30Sec.drm"
#EXT-X-STREAM-INF:BANDWIDTH=2095422,PROGRAM-ID=1,CODECS="mp4a,avc1"
hls/30Sec/30Sec.m3u8

For the command line flags, the precedence rule is different in the sense that the flag is considered turned on if it's present in either the config.xml file or on the command line. It is considered off if and only if it is missing from both the config file and the command line.

Note: PlaylistCreator tool depends on the .properties file to create top level manifest/playlist (for meta-data like language,label, bitrate etc.). The tool returns an error if no properties file is found at the in_path. Users are supposed to run OfflinePackager with -properties_only option to create a properties file before using the tool. If a user wants to customize any of the metadata values, the same needs to be manually edited in the respective properties file before running the tool.

Specify alternate media for HDS

To specify alternate media, -alternate option can be used. The value is a list of media index from the -in_path value. Sample config.xml for packaging two MBR renditions with one alternate audio for HDS: 

<config>
<create_playlist/>
<in_path>sample1.f4m,sample2.f4m,aud1/audioTrack.f4m</in_path>
<out_type>hds</out_type>
<out_path>~/Test/Output/hds</out_path>
<base_path>~/Test/Output/hds/altAudio</base_path>
<alternate>3</alternate>
</config>

For this configuration, the playlist creator will generate the following HDS set level manifest at the out_path with the name setLevel.f4m (default name as no top_level_prefix was provided): 

Command:
java -jar PlaylistCreator.jar -conf_path ~/Test/config.xml
 
Output:
The set level manifest created is:
 
<?xml version="1.0" encoding="UTF-8"?><manifest xmlns="http://ns.adobe.com/f4m/2.0" version="2.0">
<media bitrate="1039" href="sample1.f4m"> </media>
<media bitrate="1039" href="sample2.f4m"> </media>
<media alternate="true" bitrate="128" href="aud1/audioTrack.f4m" label="spanish" lang="spa" type="audio"> </media>
</manifest>

Specify alternate media for HLS

Alternate media feature in HLS allows a provider to specify one of a set of variant playlists as an "override" (alternate) of the main presentation. The client will only play the alternate media (audio or video), and suppress any media of the same type from the main presentation, if present.

A new EXT-X-MEDIA tag has been defined for the variant playlist that identifies a media selection group. A set of EXT-X-MEDIA tags with the same GROUP-ID value forms a group of renditions. Each member of the group must represent an alternative rendition of the same content. In addition, two new attributes have been defined for the EXT-X-STREAM-INF tag. AUDIO specifies the audio media group and VIDEO specifies the video media group. These define the media options available while playing the stream. The ASTREAM-INF variant can indicate that it offers a choice of audio (or video) with an AUDIO (or VIDEO) attribute. This value is a group-id shared by every MEDIA tag that can be chosen.

For HLS, the Playlist creator tool lets you create groups using the -create_group option.

The following is a sample config.xml file (~/Test/config.xml) to create an audio group with two alternates: 

<config>
<create_group/>
<in_path>aud1/input_2v_2a_2cc.m3u8,/aud2/input_2v_2a_2cc.m3u8</in_path>
<out_type>hls</out_type>
<out_path>~/Test/Output/hls</out_path>
<base_path>~/Test/Output/hls/altAudio</base_path>
<id>group1</id>
<default>1</default>
<auto>1</auto>
<group_file_name>groups.xml</group_file_name>
</config>

The following is a sample groups.xml file: 

Command:
java -jar PlaylistCreator.jar -conf_path ~/Test/config.xml
  
Output:
This will create a groups.xml file at the out_path. If such a file already exists, a new group child tag is appended at the end of the file.
 
<?xml version="1.0" encoding="UTF-8"?>
<groups>
    <group id="group1">
        <media autoselect="YES" codec="mp4a" default="YES" lang="eng" name="input_aud1" type="AUDIO" uri="/aud1/input_2v_2a_2cc.m3u8"/>
        <media autoselect="NO" codec="mp4a" default="NO" lang="spa" name="input_aud2" type="AUDIO" uri="/aud2/input_2v_2a_2cc.m3u8"/>
    </group>
</groups>

Creating variant playlist

You can create a variant playlist with an optional group file (using param -group_files) using the following configuration file: 

<config>
<create_playlist/>
<in_path>sample1.m3u8,sample2.m3u8,sample3.m3u8</in_path>
<out_type>hls</out_type>
<out_path>~/Test/Output/hls</out_path>
<base_path>~/Test/Output/hls/test</base_path>
<top_level_prefix>test</top_level_prefix>
<group_files>groups.xml</group_files>
</config>
Command:
java -jar PlaylistCreator.jar -conf_path ~/Test/config.xml
 
Output:
The variant playlist created is:
 
#EXTM3U
#EXT-X-VERSION:4
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="group1",NAME="input_aud1",AUTOSELECT=YES,DEFAULT=YES,LANGUAGE="eng",URI="/aud1/input_2v_2a_2cc.m3u8"
#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="group1",NAME="input_aud2",AUTOSELECT=NO,DEFAULT=NO,LANGUAGE="spa",URI="/aud2/input_2v_2a_2cc.m3u8"
#EXT-X-STREAM-INF:BANDWIDTH=1136773,PROGRAM-ID=1,AUDIO="group1"
sample1.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=137227,PROGRAM-ID=1,AUDIO="group1"
sample2.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=137528,PROGRAM-ID=1,AUDIO="group1"
sample3.m3u8