diff --git a/docs/source/options/chunking_options.rst b/docs/source/options/chunking_options.rst new file mode 100644 index 0000000000..560a2a7cc8 --- /dev/null +++ b/docs/source/options/chunking_options.rst @@ -0,0 +1,23 @@ +Chunking options +^^^^^^^^^^^^^^^^ + +--segment_duration + + 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 + + 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. diff --git a/docs/source/options/dash_options.rst b/docs/source/options/dash_options.rst new file mode 100644 index 0000000000..749e68def4 --- /dev/null +++ b/docs/source/options/dash_options.rst @@ -0,0 +1,45 @@ +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 + + MPD output file name. + +--base_urls + + Comma separated BaseURLs for the MPD. The values will be added as + element(s) immediately under the element. + +--min_buffer_time + + Specifies, in seconds, a common duration used in the definition of the MPD + Representation data rate. + +--minimum_update_period + + 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 + + Guaranteed duration of the time shifting buffer for dynamic media + presentations, in seconds. + +--suggested_presentation_delay + + Specifies a delay, in seconds, to be added to the media presentation time. + This value is used for dynamic MPD only. + +--default_language + + Any tracks tagged with this language will have + in the manifest. This allows the player to choose the correct default + language for the content. diff --git a/docs/source/options/general_encryption_options.rst b/docs/source/options/general_encryption_options.rst new file mode 100644 index 0000000000..654b2a163c --- /dev/null +++ b/docs/source/options/general_encryption_options.rst @@ -0,0 +1,15 @@ +General encryption options +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +--protection_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 + + Clear lead in seconds if encryption is enabled. diff --git a/docs/source/options/hls_options.rst b/docs/source/options/hls_options.rst new file mode 100644 index 0000000000..d36e28dc85 --- /dev/null +++ b/docs/source/options/hls_options.rst @@ -0,0 +1,18 @@ +HLS options +^^^^^^^^^^^ + +--hls_master_playlist_output + + Output path for the master playlist for HLS. This flag must be used to + output HLS. + +--hls_base_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 + + 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. diff --git a/docs/source/options/hls_stream_descriptors.rst b/docs/source/options/hls_stream_descriptors.rst new file mode 100644 index 0000000000..384df1d1cb --- /dev/null +++ b/docs/source/options/hls_stream_descriptors.rst @@ -0,0 +1,18 @@ +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'. diff --git a/docs/source/options/mp4_output_options.rst b/docs/source/options/mp4_output_options.rst new file mode 100644 index 0000000000..7b9ad64715 --- /dev/null +++ b/docs/source/options/mp4_output_options.rst @@ -0,0 +1,20 @@ +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 + + 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. diff --git a/docs/source/options/playready_encryption_options.rst b/docs/source/options/playready_encryption_options.rst new file mode 100644 index 0000000000..78b5740b20 --- /dev/null +++ b/docs/source/options/playready_encryption_options.rst @@ -0,0 +1,39 @@ +Playready encryption options +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +--enable_playready_encryption + + Enable encryption with playready key. + +--playready_server_url + + Playready packaging server url. + +--program_identifier + + Program identifier for packaging request. + +--playready_key_id + + Playready key id in hex. + +--playready_key + + Playready key in hex. + +--ca_file + + Absolute path to the certificate authority file for the server cert. + PEM format. + +--client_cert_file + + Absolute path to client certificate file. + +--client_cert_private_key_file + + Absolute path to the private key file. + +--client_cert_private_key_password + + Password to the private key file. diff --git a/docs/source/options/raw_key_encryption_options.rst b/docs/source/options/raw_key_encryption_options.rst new file mode 100644 index 0000000000..2e34d1d6c8 --- /dev/null +++ b/docs/source/options/raw_key_encryption_options.rst @@ -0,0 +1,30 @@ +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 + + One or more concatenated PSSH boxes in hex string format. If not specified, + a `v1 common PSSH box `_ will be generated. diff --git a/docs/source/options/segment_template_formatting.rst b/docs/source/options/segment_template_formatting.rst new file mode 100644 index 0000000000..0f05c2efb1 --- /dev/null +++ b/docs/source/options/segment_template_formatting.rst @@ -0,0 +1,51 @@ +Segment template formatting +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The implementation is based on *Template-based Segment URL construction* +described in ISO/IEC 23009-1:2014. + +.. table:: Supported identifiers + + ============== ============================== ============================== + $$ Substitution parameter Format + ============== ============================== ============================== + $$ is an escape sequence, i.e. Not applicable. + "$$" is replaced with a single + "$". + $Number$ This identifier is substitued The format tag may be present. + with the *number* of the + corresponding Segment. If no format tag is present, a + default format tag with + *width*\=1 shall be used. + $Time$ This identifier is substituted The format tag may be present. + with the value of the + **SegmentTimeline@t** If no format tag is present, a + attribute for the Segment default format tag with + being accessed. Either *width*\=1 shall be used. + $Number$ or $Time$ may be used + but not both at the same time. + ============== ============================== ============================== + +.. note:: + + Identifiers $RepresentationID$ and $Bandwidth$ are not supported in this + version. Please file an `issue + `_ if you want it to be + supported. + +In each URL, the identifiers shall be replaced by the substitution parameter +per the definition in the above table. Identifier matching is case-sensitive. + +Each identifier may be suffixed, within the enclosing '$' characters, with an +additional format tag aligned with the *printf* format tag as defined in IEEE +1003.1-2008 following this prototype:: + + %0[width]d + +The *width* parameter is an unsigned integer that provides the minimum number +of characters to be printed. If the value to be printed is shorter than this +number, the result shall be padded with zeros. The value is not truncated even +if the result is larger. + +Strings outside identifiers shall only contain characters that are permitted +within URLs according to RFC 3986. diff --git a/docs/source/options/stream_descriptors.rst b/docs/source/options/stream_descriptors.rst new file mode 100644 index 0000000000..ad0fcc6305 --- /dev/null +++ b/docs/source/options/stream_descriptors.rst @@ -0,0 +1,71 @@ +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 :doc:`/options/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 + :doc:`/options/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. + +.. include:: /options/hls_stream_descriptors.rst diff --git a/docs/source/options/udp_file_options.rst b/docs/source/options/udp_file_options.rst new file mode 100644 index 0000000000..05de7102dd --- /dev/null +++ b/docs/source/options/udp_file_options.rst @@ -0,0 +1,18 @@ +UDP file options +^^^^^^^^^^^^^^^^ + +UDP file is of the form udp://ip:port[?options]. Here is the list of supported +options: + +:reuse=0|1: + + Allow or disallow reusing UDP sockets. + +:interface=, source=: + + Multicast group interface address. Only the packets sent to this address is + received. + +:timeout=: + + UDP timeout in microseconds. diff --git a/docs/source/options/widevine_encryption_options.rst b/docs/source/options/widevine_encryption_options.rst new file mode 100644 index 0000000000..78b9a3a8dd --- /dev/null +++ b/docs/source/options/widevine_encryption_options.rst @@ -0,0 +1,75 @@ +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 + + Key server url. Required for Widevine encryption and decryption. + +--content_id + + Content identifier that uniquely identifies the content. + +--policy + + The name of a stored policy, which specifies DRM content rights. + +--max_sd_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 + + 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 + + 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 + + The name of the signer. + +--aes_signing_key + + 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 + + AES signing iv in hex string. + +--rsa_signing_key_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 + + Defines how often key rotates. If it is non-zero, key rotation is enabled. + +--group_id + + Identifier for a group of licenses.