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: mp4dash [options] <media-file> [<media-file> ...]

Each <media-file> 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 1.6.0 r607

Options:
  -h, --help            show this help message and exit
  -v, --verbose         Be verbose
  -d, --debug           Print out debugging information
  -o <output-dir>, --output-dir=<output-dir>
                        Output directory
  -f, --force           Allow output to an existing directory
  --mpd-name=<filename>
                        MPD file name
  --profiles=<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=<prefix>
                        Use this prefix for prefixed media file names (instead
                        of the default prefix "media")
  --init-segment=<filename>
                        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=<duration>
                        Minimum buffer time (in seconds)
  --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
  --subtitles           Enable Subtitles
  --group=<group-definition>
                        Specify the attributes of a group. This option may be
                        used multiple times, once per group
  --smooth              Produce an output compatible with Smooth Streaming
  --smooth-client-manifest-name=<filename>
                        Smooth Streaming Client Manifest file name
  --smooth-server-manifest-name=<filename>
                        Smooth Streaming Server Manifest file name
  --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
                        (AES-128), where <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;
                        or (2) @<key-locator> where <key-locator> is an
                        expression of one of the supported key locator schemes
                        (see online docs for details)
  --encryption-args=<cmdline-arguments>
                        Pass additional command line arguments to mp4encrypt
                        (separated by spaces)
  --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,  or (2) the
                        character '#' followed by a PlayReady Header Object
                        encoded in Base64, or (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)
  --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=<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 either: (1) the character '#' followed
                        by a Widevine header encoded in Base64, or (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], 'policy' [string])
  --primetime           Add Primetime 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 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
  --exec-dir=<exec_dir>
                        Directory where the Bento4 executables are located

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).