Packager Documentation¶
Shaka Packager is a tool and a media packaging SDK for DASH and HLS packaging and encryption. It can transmux input media files from one container to another container.
Note
Shaka Packager does not do transcoding. Content must be pre-encoded before passing to packager.
Packager operates in streams, described by stream_descriptor. The streams can be read from the same “file” or different “files”, which can be regular files, pipes, udp streams, etc.
This page is the documentation on using the packager tool. If you are interested in integrating packager library into your own tool, please see Shaka Packager Library.
Getting Shaka Packager¶
There are several ways you can get Shaka Packager.
- Using Docker. Instructions are available at Using Docker.
- Get prebuilt binaries from release.
- Built from source, see Build Instructions for details.
Synopsis¶
$ packager {stream_descriptor} [{stream_descriptor}] ... \
[--dump_stream_info] \
[Chunking Options] \
[MP4 Output Options] \
[encryption / decryption options] \
[DASH options] \
[HLS options]
Stream descriptors¶
There can be multiple stream_descriptor with input from the same “file” or multiple different “files”.
Stream is of the form:
{field}={value}[,{field}={value}]...
These are the available fields:
| input (in): | input/source media “file” path, which can be regular files, pipes, udp streams. See UDP file options on additional options for UDP files. |
|---|---|
| stream_selector (stream): | |
| Required field with value ‘audio’, ‘video’, ‘text’ or stream number (zero based). | |
| output (out): | Required output file path (single file). |
| init_segment: | initialization segment path (multiple file). |
| segment_template (segment): | |
| Optional value which specifies the naming pattern for the segment files, and that the stream should be split into multiple files. Its presence should be consistent across streams. See Segment template formatting. | |
| bandwidth (bw): | Optional value which contains a user-specified content bit rate for the stream, in bits/sec. If specified, this value is propagated to (HLS) EXT-X-STREAM-INF:BANDWIDTH or (DASH) Representation@bandwidth and the $Bandwidth$ template parameter for segment names. If not specified, the bandwidth value is estimated from content bitrate. Note that it only affects the generated manifests/playlists; it has no effect on the media content itself. |
| language (lang): | |
| Optional value which contains a user-specified language tag. If specified, this value overrides any language metadata in the input stream. | |
| output_format (format): | |
| Optional value which specifies the format of the output files (MP4 or WebM). If not specified, it will be derived from the file extension of the output file. | |
| skip_encryption=0|1: | |
| Optional. Defaults to 0 if not specified. If it is set to 1, no encryption of the stream will be made. | |
| trick_play_factor (tpf): | |
| Optional value which specifies the trick play, a.k.a. trick mode, stream sampling rate among key frames. If specified, the output is a trick play stream. | |
HLS specific stream descriptor fields¶
| hls_name: | Required for audio when outputting HLS. name of the output stream. This is not (necessarily) the same as output. This is used as the NAME attribute for EXT-X-MEDIA. |
|---|---|
| hls_group_id: | Required for audio when outputting HLS. The group ID for the output stream. This is used as the GROUP-ID attribute for EXT-X-MEDIA. |
| playlist_name: | Required for HLS output. Name of the playlist for the stream. Usually ends with ‘.m3u8’. |
Chunking options¶
| --segment_duration <seconds> | |
| Segment duration in seconds. If single_segment is specified, this parameter sets the duration of a subsegment; otherwise, this parameter sets the duration of a segment. Actual segment durations may not be exactly as requested. | |
| --fragment_duration <seconds> | |
| Fragment duration in seconds. Should not be larger than the segment duration. Actual fragment durations may not be exactly as requested. | |
| --segment_sap_aligned | |
| Force segments to begin with stream access points. Default enabled. | |
| --fragment_sap_aligned | |
| Force fragments to begin with stream access points. This flag implies segment_sap_aligned. Default enabled. | |
MP4 output options¶
| --mp4_include_pssh_in_stream | |
| MP4 only: include pssh in the encrypted stream. Default enabled. | |
| --mp4_use_decoding_timestamp_in_timeline | |
| If set, decoding timestamp instead of presentation timestamp will be used when generating media timeline, e.g. timestamps in sidx and mpd. This is to workaround a Chromium bug that decoding timestamp is used in buffered range, https://crbug.com/398130. Default false. | |
| --num_subsegments_per_sidx <number> | |
| Set the number of subsegments in each SIDX box. If 0, a single SIDX box is used per segment; if -1, no SIDX box is used; Otherwise, the muxer packs N subsegments in the root SIDX of the segment, with segment_duration/N/fragment_duration fragments per subsegment. | |
DASH options¶
| --generate_static_mpd | |
| If enabled, generates static mpd. If segment_template is specified in stream descriptors, shaka-packager generates dynamic mpd by default; if this flag is enabled, shaka-packager generates static mpd instead. Note that if segment_template is not specified, shaka-packager always generates static mpd regardless of the value of this flag. | |
| --mpd_output <file_path> | |
| MPD output file name. | |
| --base_urls <comma separated url> | |
| Comma separated BaseURLs for the MPD. The values will be added as <BaseURL> element(s) immediately under the <MPD> element. | |
| --min_buffer_time <seconds> | |
| Specifies, in seconds, a common duration used in the definition of the MPD Representation data rate. | |
| --minimum_update_period <seconds> | |
| Indicates to the player how often to refresh the media presentation description in seconds. This value is used for dynamic MPD only. | |
| --time_shift_buffer_depth <seconds> | |
| Guaranteed duration of the time shifting buffer for dynamic media presentations, in seconds. | |
| --suggested_presentation_delay <seconds> | |
| Specifies a delay, in seconds, to be added to the media presentation time. This value is used for dynamic MPD only. | |
| --default_language <language> | |
| Any tracks tagged with this language will have <Role ... value=”main” /> in the manifest. This allows the player to choose the correct default language for the content. | |
HLS options¶
| --hls_master_playlist_output <file_path> | |
| Output path for the master playlist for HLS. This flag must be used to output HLS. | |
| --hls_base_url <url> | |
| The base URL for the Media Playlists and media files listed in the playlists. This is the prefix for the files. | |
| --hls_playlist_type <type> | |
| VOD, EVENT, or LIVE. This defines the EXT-X-PLAYLIST-TYPE in the HLS specification. For hls_playlist_type of LIVE, EXT-X-PLAYLIST-TYPE tag is omitted. | |
Encryption / decryption options¶
Shaka Packager supports three different types of key providers:
- Raw key (fixed key): keys are provided in command line
- Widevine: fetches keys from Widevine key server
- Playready: fetches keys from Playready key server
Different key providers cannot be specified at the same time.
[--enable_widevine_encryption {Widevine Encryption Options}] \
[--enable_widevine_decryption {Widevine Decryption Options}] \
[--enable_fixed_key_encryption {Fixed Key Encryption Options}] \
[--enable_fixed_key_decryption {Fixed Key Decryption Options}] \
[--enable_playready_encryption {Playready Encryption Options}]
General encryption options¶
| --protection_scheme <scheme> | |
| Specify a protection scheme, ‘cenc’ or ‘cbc1’ or pattern-based protection schemes ‘cens’ or ‘cbcs’. | |
| --vp9_subsample_encryption, --novp9_subsample_encryption | |
| Enable / disable VP9 subsample encryption. Enabled by default. | |
| --clear_lead <seconds> | |
| Clear lead in seconds if encryption is enabled. | |
Raw key encryption options¶
| --enable_fixed_key_encryption | |
| Enable encryption with fixed key. | |
| --enable_fixed_key_decryption | |
| Enable decryption with fixed key. | |
| --key_id <32-digit hex string> | |
| The key id in hex string format. HEX. | |
| --key <32-digit hex string> | |
| The key in hex string format. | |
| --iv <16-digit or 32-digit hex string> | |
| IV in hex string format. If not specified, a random IV will be generated. This flag should only be used for testing. IV must be either 8 bytes (16 digits HEX) or 16 bytes (32 digits in HEX). | |
| --pssh <hex string> | |
| One or more concatenated PSSH boxes in hex string format. If not specified, a v1 common PSSH box will be generated. | |
Widevine encryption options¶
| --enable_widevine_encryption | |
| Enable encryption with Widevine key server. User should provide either AES signing key (–aes_signing_key, –aes_signing_iv) or RSA signing key (–rsa_signing_key_path). | |
| --enable_widevine_decryption | |
| Enable decryption with Widevine key server. User should provide either AES signing key (–aes_signing_key, –aes_signing_iv) or RSA signing key (–rsa_signing_key_path). | |
| --include_common_pssh | |
| When using Widevine encryption, include an additional v1 PSSH box for the common system ID that includes the key IDs. See https://goo.gl/s8RIhr. | |
| --key_server_url <url> | |
| Key server url. Required for Widevine encryption and decryption. | |
| --content_id <hex> | |
| Content identifier that uniquely identifies the content. | |
| --policy <policy> | |
| The name of a stored policy, which specifies DRM content rights. | |
| --max_sd_pixels <pixels> | |
| The video track is considered SD if its max pixels per frame is no higher than max_sd_pixels. Default: 442368 (768 x 576). | |
| --max_hd_pixels <pixels> | |
| The video track is considered HD if its max pixels per frame is higher than max_sd_pixels, but no higher than max_hd_pixels. Default: 2073600 (1920 x 1080). | |
| --max_uhd1_pixels <pixels> | |
| The video track is considered UHD1 if its max pixels per frame is higher than max_hd_pixels, but no higher than max_uhd1_pixels. Otherwise it is UHD2. Default: 8847360 (4096 x 2160). | |
| --signer <signer> | |
| The name of the signer. | |
| --aes_signing_key <hex> | |
| AES signing key in hex string. aes_signing_iv is required if aes_signing_key is specified. This option is exclusive with rsa_signing_key_path. | |
| --aes_signing_iv <hex> | |
| AES signing iv in hex string. | |
| --rsa_signing_key_path <file path> | |
| Path to the file containing PKCS#1 RSA private key for request signing. This option is exclusive with aes_signing_key. | |
| --crypto_period_duration <seconds> | |
| Defines how often key rotates. If it is non-zero, key rotation is enabled. | |
| --group_id <hex> | |
| Identifier for a group of licenses. | |
Playready encryption options¶
| --enable_playready_encryption | |
| Enable encryption with playready key. | |
| --playready_server_url <url> | |
| Playready packaging server url. | |
| --program_identifier <program_identifier> | |
| Program identifier for packaging request. | |
| --playready_key_id <hex> | |
| Playready key id in hex. | |
| --playready_key <hex> | |
| Playready key in hex. | |
| --ca_file <file path> | |
| Absolute path to the certificate authority file for the server cert. PEM format. | |
| --client_cert_file <file path> | |
| Absolute path to client certificate file. | |
| --client_cert_private_key_file <file path> | |
| Absolute path to the private key file. | |
| --client_cert_private_key_password <string> | |
| Password to the private key file. | |