mp4dash
mp4dash is a tool that is used to package one or more MP4 media files into an MPEG DASH (and/or Smooth Streaming) presentation.
For an overview of MPEG DASH, and usage guide for mp4dash, please consult the MPEG DASH Overview
page.
Running the tool without any argument will print out a summary of the tool’s command line options and parameters.
Usage
Usage: mp4-dash.py [options] [ ...]
Each is the path to a fragmented MP4 file, optionally prefixed
with a stream selector delimited by [ and ]. The same input MP4 file may be
repeated, provided that the stream selector prefixes select different streams.
Version 2.0.0 r632
Options:
-h, --help show this help message and exit
-v, --verbose Be verbose
-d, --debug Print out debugging information
-o , --output-dir=
Output directory
-f, --force Allow output to an existing directory
--mpd-name=
MPD file name
--profiles=
Comma-separated list of one or more profile(s).
Complete profile names can be used, or profile aliases
('live'='urn:mpeg:dash:profile:isoff-live:2011', 'on-
demand'='urn:mpeg:dash:profile:isoff-on-demand:2011',
'hbbtv-1.5='urn:hbbtv:dash:profile:isoff-live:2012')
--no-media Do not output media files (MPD/Manifests only)
--rename-media Use a file name pattern instead of the base name of
input files for output media files.
--media-prefix=
Use this prefix for prefixed media file names (instead
of the default prefix "media")
--init-segment=
Initialization segment name
--no-split Do not split the file into individual segment files
--use-segment-list Use segment lists instead of segment templates
--use-segment-template-number-padding
Use padded numbers in segment URL/filename templates
--use-segment-timeline
Use segment timelines (necessary if segment durations
vary)
--min-buffer-time=
Minimum buffer time (in seconds)
--max-playout-rate=
Max Playout Rate setting strategy for trick-play
support. Supported strategies: lowest:X
--language-map=:[,...]
Remap language code to . Multiple
mappings can be specified, separated by ','
--always-output-lang Always output an @lang attribute for audio tracks even
when the language is undefined
--subtitles Enable Subtitles
--attributes=
Specify the attributes of a set of tracks. This option
may be used multiple times, once per attribute set.
--smooth Produce an output compatible with Smooth Streaming
--smooth-client-manifest-name=
Smooth Streaming Client Manifest file name
--smooth-server-manifest-name=
Smooth Streaming Server Manifest file name
--smooth-h264-fourcc=
Smooth Streaming FourCC value for H.264 video
(default=H264) [some older players use AVC1]
--hls Output HLS playlists in addition to MPEG DASH
--hls-key-url= HLS key URL (default: key.bin)
--hls-master-playlist-name=
HLS master playlist name (default: master.m3u8)
--hls-media-playlist-name=
HLS media playlist name (default: media.m3u8)
--hls-iframes-playlist-name=
HLS I-Frames playlist name (default: iframes.m3u8)
--hippo Produce an output compatible with the Hippo Media
Server
--hippo-server-manifest-name=
Hippo Media Server Manifest file name
--use-compat-namespace
Use the original DASH MPD namespace as it was
specified in the first published specification
--encryption-key=
Encrypt some or all tracks with MPEG CENC (AES-128),
where specifies the KID(s) and Key(s) to
use, using one of the following forms: (1) :
or :: with (and if
specififed) as a 32-character hex string and
either a 32-character hex string or the character '#'
followed by a base64-encoded key seed; or (2) @ where is an expression of one
of the supported key locator schemes. Each entry may
be prefixed with an optional track filter, and
multiple entries can be used, separated by
','. (see online docs for details)
--encryption-cenc-scheme=
MPEG Common Encryption scheme (cenc, cbc1, cens or
cbcs). (default: cenc)
--encryption-args=
Pass additional command line arguments to mp4encrypt
(separated by spaces)
--eme-signaling=
Add EME-compliant signaling in the MPD and PSSH boxes
(valid options are 'pssh-v0' and 'pssh-v1')
--merge-keys Merge all keys in a single set used for all
elements
--marlin Add Marlin signaling to the MPD (requires an encrypted
input, or the --encryption-key option)
--marlin-add-pssh Add an (optional) Marlin 'pssh' box in the init
segment(s)
--playready Add PlayReady signaling to the MPD (requires an
encrypted input, or the --encryption-key option)
--playready-version=PLAYREADY_VERSION
PlayReady version to use (4.0, 4.1, 4.2, 4.3),
defaults to 4.0
--playready-header=
Add a PlayReady PRO element in the MPD and a PlayReady
PSSH box in the init segments. The use of this option
implies the --playready option. The
argument can be either: (1) the character '@' followed
by the name of a file containing a PlayReady XML
Rights Management Header () or a PlayReady
Header Object (PRO) in binary form, or (2) the
character '#' followed by a PlayReady Header Object
encoded in Base64, or (3) one or more :
pair(s) (separated by '#' if more than one) specifying
fields of a PlayReady Header Object (field names
include LA_URL, LUI_URL and DS_ID)
--playready-add-pssh Store the PlayReady header in a 'pssh' box in the init
segment(s) [deprecated: this is now implicitly on by
default when the --playready or --playready-header
option is used]
--playready-no-pssh Do not store the PlayReady header in a 'pssh' box in
the init segment(s)
--widevine Add Widevine signaling to the MPD (requires an
encrypted input, or the --encryption-key option)
--widevine-header=
Add a Widevine entry in the MPD, and a Widevine PSSH
box in the init segments. The use of this option
implies the --widevine option. The
argument can be either: (1) the character '#' followed
by a Widevine header encoded in Base64, or (2) one or
more : pair(s) (separated by '#' if more
than one) specifying fields of a Widevine header
(field names include 'provider' [string], 'content_id'
[byte array in hex], 'policy' [string])
--primetime Add Primetime signaling to the MPD (requires an
encrypted input, or the --encryption-key option)
--primetime-metadata=
Add Primetime metadata in a PSSH box in the init
segments. The use of this option implies the
--primetime option. The argument can
be either: (1) the character '@' followed by the name
of a file containing the Primetime Metadata to use, or
(2) the character '#' followed by the Primetime
Metadata encoded in Base64
--fairplay-key-uri=FAIRPLAY_KEY_URI
Specify the key URI to use for FairPlay Streaming key
delivery (only valid with --hls option)
--clearkey Add Clear Key signaling to the MPD (requires an
encrypted input, or the --encryption-key option))
--clearkey-license-uri=CLEARKEY_LICENSE_URI
Specify the license/key URI to use for Clear Key (only
valid with --clearkey option)
--exec-dir=
Directory where the Bento4 executables are located
(use '-' to look for executable in the current PATH) Command line options detailed documentation
media files arguments
mp4dash takes as input one or more media files. Each media file is the path to a fragmented MP4 file that will be used as input. Each media file name may be preceded by a selector, delimited by [ and ].
When no selector is used, all the audio tracks and the first video track of each input file will be used. If more than one track with the same language is found (which is common when multiple input files are used in a multi-bitrate scenario, and that each input has its own copy of the shared audio track), only the first one will be used (it is assumed that they are all copies of each other).
The syntax for a selector is a list of one or more specifiers, separated by commas (,).
A specifier may be a filter, in which case it has the form name=value, or it may be a “setter”, in which case it has the form +name=value (it starts with a + character).
Filters and setters can be combined in a single selector (ex: [track=3])
filters
A filter selects a subset or one or more tracks from an input file. Supported filters are: type, track, and language. When the filter name is type, the value can be audio to select only the audio track(s) from the input, or video for the video track. When the filter name is track, the value is the ID of the track to select (could be audio or video). When the filter name is language the value is an audio language code (2 or 3 letter code as defined by the DASH specification). It is possible to combine the language selector with a type selector, by separating the two by a comma (ex: [type=audio,language=fr]. If the language selector is used by itself without a type selector, the video track as well as the matching audio track will be selected.
setters
A setter sets a property or attribute for the track(s) selected by the filter (or all the tracks if the selector doesn’t include a filter). This may be used to set or override a track’s language, or set DASH-specific attributes like Role, Rating or Viewpoint. The name of a setter always starts with a + character.
NOTE there are currently no setters defined. This syntax is reserved for future use.
command line arguments
-h, --help
Print out a short summary of the command line options and arguments usage.
-v, --verbose
Produce a more verbose output. Useful for debugging.
-o <output-dir>, --output-dir=<output-dir>
Specify the output directory where the files will be written. If omitted, the output directory is named output.
-f, --force
Allow output to an existing directory.
--mpd-name=<filename>
Specify the name of the MPD file (default: stream.mpd)
--profiles=<profiles>
Comma-separated list of one or more profile(s). Complete profile names can be used, or profile aliases.
Profile aliaes include:
* live as an alias for urn:mpeg:dash:profile:isoff-live:2011
* on-demand as an alias for urn:mpeg:dash:profile:isoff-on-demand:2011
* hbbtv-1.5 as an alias for urn:hbbtv:dash:profile:isoff-live:2012
If no profiles are specified, the default is to use the single profile urn:mpeg:dash:profile:isoff-live:2011.
--no-media
Do not output media files (MPD/Manifests only). This may be useful if you want to re-generate an MPD without re-processing the media files.
--rename-media
Use a file name pattern instead of the base name of input files for output media files (this option is only relevant when also using the --no-split option)
For example, running:
mp4dash --no-split video.mp4
will produce an output directory with the files: stream.mpd and video.mp4
Whereas with the --rename-media option:
mp4dash --no-split --rename-media video.mp4
will produce an output directory with the files: stream.mpd and media-01.mp4 (the input file name video.mp4 is renamed to media-XX.mp4)
--media-prefix=<prefix>
When combined with the --rename-media option, use this prefix for prefixed media file names (instead of the default prefix media)
For example, mp4dash --no-split --rename-media --media-prefix foobar video.mp4
will produce an output directory with the files: stream.mpd and foobar-01.mp4 (the input file name video.mp4 is renamed to foobar-XX.mp4)
--init-segment=<filename>
Specify an Initialization Segment name instead of the default ('init.mp4)
--no-split
Do not split the file into individual segment files. This option produces a single output file for each input file. Since with most MPEG DASH MPDs, each media segment has its own URL, the use of this option requires that the HTTP server be able to “virtualize” URLs (i.e map segment URLs to byte ranges within the stored, non-split, media file)
--use-segment-list
Use segment lists instead of segment templates.
For DASH presentation that follow the isoff-live profile (the defaut profile used by mp4dash), the default mode is to use a shared template for the segment URL. When using --use-segment-list, an explicit list of all segments and their respective URLs will be used in the MPD.
--use-segment-template-number-padding
Use padded numbers in segment URL/filename templates. For example, with padding, segment 1 would be named seg-0001.m4f instead of seg-1.m4f.
--use-segment-timeline
Use segment timelines.
For DASH presentation that follow the isoff-live profile (the defaut profile used by mp4dash), the default mode is to use a shared template for the segment information. This is efficient, as it keeps the size of the MPD small. But when the input media where the fragments/segments are not all of the same duration, this does not work, since when using templates, there is a single duration value shared by all segments. So in that case, the --use-segment-list option tells mp4dash to use an explicit segment list where each segment has its own duration.
--min-buffer-time=<duration>
Minimum buffer time (in seconds).
By default, mp4dash automatically computes the minimum buffer time. Use this option to override the default.
--max-playout-rate=<strategy>
Max Playout Rate setting strategy for trick-play support. Supported strategies: lowest:X
--language-map=<lang_from>:<lang_to>[,...]
Remap language code <lang_from> to <lang_to>. Multiple mappings can be specified, separated by “,”
--always-output-lang
Always output an @lang attribute for audio tracks even when the language is undefined.
This option is automatically enabled when the hbbtv-1.5 profile is part of the profiles list.
--subtitles
Enable subtitles.
-g, --group
This option may be used to define the attributes and properties for a media group. Each input media belongs to one or more groups. By default, all the audio tracks belong to the group named audio, all the video tracks belong to the group named video and all the subtitle tracks belong to the group named subtitles. In addition, an audio track with language xxx belong to the group named audio/xxx. For instance, an audio track with an undefined language (language code und) will belong to the group audio/und.
The syntax for a group definition is: group_name:group_attributes, where group_attributes is one or more {attribute_namespace}attribute_name=attribute_value attributes, separated by ,.
To set the DASH Role, Accessibility, Rating or Viewpoint attributes, use the attribute name, prefixed with its namespace (schemeIdUri in the DASH specification) delimited by curly braces ({ and }). For the Role attribute, the namespace may be omitted, in which case it will default to urn:mpeg:dash:role:2011. The attribute name may be written as it appears in the DASH specification, or in lowercase for convenience.
For example, role=main sets the Role attribute for a group, and {urn:mpeg:dash:viewpoint:2011}viewpoint sets the Viewpoint attribute.
More than one --group option may be used, each with a different group name.
Examples
mp4dash --group audio:role=main --group video:{urn:mpeg:dash:role:2011}viewpoint=vp1 video.mp4
mp4dash --group audio:role=main --group video:{urn:mpeg:dash:role:2011}viewpoint=vp1 video.mp4
mp4dash --group audio:role=main --group video:{urn:scte:dash:cc:cea-608:2015}accessibility=eng,{urn:mpeg:dash:role:2011}viewpoint=vp2 video.mp4
--smooth
Produce an output compatible with Microsoft Smooth Streaming.
--smooth-client-manifest-name=<filename>
Smooth Streaming Client Manifest file name. (default=stream.ismc)
--smooth-server-manifest-name=<filename>
Smooth Streaming Server Manifest file name. (default=stream.ism)
--smooth-h264-fourcc=<fourcc>
Smooth Streaming FourCC value for H.264 video. (default=AVC1)
--hippo
Produce an output compatible with the Hippo Media Server.
--hippo-server-manifest-name=<filename>
Hippo Media Server Manifest file name.
--encryption-key=<key-spec>
Encrypt all audio and video tracks with MPEG CENC (Common Encryption, with AES-128).
<key-spec> specifies the KID and Key to use, using one of the following ways:
1. <KID>:<key> with <KID> as a 32-character hex string and <key> either a 32-character hex string or the character # followed by a base64-encoded key seed.
2. @<key-locator> where <key-locator> is an expression of one of the supported key locator schemes.
Example
--encryption-key=000102030405060708090a0b0c0d0e0f:00112233445566778899aabbccddeeff
--encryption-args=<cmdline-arguments>
Pass additional command line arguments to mp4encrypt (separated by spaces).
This option can be used to precisely control certain options supported by mp4encrypt.
--use-compat-namespace
Use the original DASH MPD namespace as it was specified in the first published specification.
--marlin
Add Marlin signaling to the MPD (requires an encrypted input, or the --encryption-key option)
--marlin-add-pssh
Add an (optional) Marlin ‘pssh’ box in the init segment(s)
--playready
Add PlayReady signaling to the MPD (requires an encrypted input, or the --encryption-key option)
--playready-header=<playready-header>
Add a PlayReady PRO element in the MPD and a PlayReady PSSH box in the init segments. The use of this option implies the --playready option.
The <playready-header> argument can be either:
1. The character @ followed by the name of a file containing a PlayReady XML Rights Management Header (<WRMHEADER>) or a PlayReady Header Object (PRO) in binary form
2. The character #' followed by a PlayReady Header Object encoded in Base64
3. One or more <name>:<value> pair(s) (separated by # if more than one) specifying fields of a PlayReady Header Object (field names include LA_URL, LUI_URL and DS_ID)
Example: --playready-header=LA_URL=http://myplayreadyserver.com/license.asmx
--playready-no-pssh
Do not store the PlayReady header in a ‘pssh’ box in the init segment(s).
--widevine
Add Widevine signaling to the MPD (requires an encrypted input, or the --encryption-key option)
--widevine-header=<widevine-header>
Add a Widevine entry in the MPD, and a Widevine PSSH box in the init segments. The use of this option implies the --widevine option.
The <widevine-header> argument can be:
1. The character # followed by a Widevine header encoded in Base64
2. One or more <name>:<value> pair(s) (separated by # if more than one) specifying fields of a Widevine header (field names include provider [string], content_id [byte array in hex], and policy [string])
Examples
--widevine-header=provider:myprovidername#content_id:2a
--widevine-header=#CAESEBycOU9s3lZopG92JeLT54EaDXdpZGV2aW5lX3Rlc3QiBAEjRWc=
--primetime
Add Primetime DRM signaling to the MPD (requires an encrypted input, or the –encryption-key option)
--primetime-metadata=<primetime-metadata>
Add Primetime metadata in a PSSH box in the init segments. The use of this option implies the --primetime option. The <primetime-data> argument can be:
1. The character @ followed by the name of a file containing the Primetime Metadata to use
2. The character # followed by the Primetime Metadata encoded in Base64
Example
--primetime-metadata=@mymetadatafile.bin
--exec-dir=<exec_dir>
Directory where the Bento4 executables are located. This option may be needed when running this tool outside of its normal SDK distribution (running a custom build from source for example).