MP4Box - MPEG-4 Systems Toolbox
MP4Box [options] file [options]
MP4Box is a multi-purpose command line tool to create and edit
MPEG-4 Systems presentations and manipulate ISO-media files (MP4, 3GP,
MOV).
MP4Box supports file conversion from various raw formats and
IsoMedia/AVI/MPEG-PS/OGG containers, file hinting for RTP streaming for
QuickTime compatible streaming servers, file interleaving, file
fragmentation and track extraction.
MP4Box also provides dump tools used to inspect file layout, RTP
hint tracks, SDP information, scene composition. It may also be used to
convert to and from BT/XMT-A/VRML/X3D.
MP4Box also features MPEG-4 Systems encoders and decoders for BIFS
and OD tools.
MP4Box doesn't expect any particular order in options at
prompt.
- -h [type]
- prints help screen. "type" can be one of "general",
"hint", "import", "encode",
"extract", "dump", "swf", "meta",
"crypt", "format", "rtp", "live"
for specific help.
- -version
- prints version of MP4Box.
- -noprog
- disable progress reports.
- -quiet
- quiet mode (no log info).
- -v
- verbose mode (more log info).
- -strict-error
- exits after the first error is reported.
- -nodes
- lists supported MPEG-4 Systems nodes in MP4Box current build.
- -node NodeName
- prints the node syntax. Each field is listed as
eventType fieldType fieldName defaultValue
and field quantization information and quantization bounds if any.
- -xnodes
- lists supported X3D nodes in MP4Box current build.
- -xnode
NodeName
- prints the X3D node syntax. Each field is listed as
- -snodes
- lists supported SVG/LASeR nodes in MP4Box current build.
- -inter
duration
- interleaves media data in chunks of the maximum specified duration
(expressed in milliseconds) and prepare file for HTTP/FTP streaming. By
default MP4Box always stores with 0.5 second interleaving. An interleaving
value of '0' stores without interleaving (meta-data then track after
track).
-old-inter duration same as -inter but without drift adjustment
NOTE: Track Edit Lists are ignored when performing interleaving.
- -flat
- stores file with all media data first, non interleaved. If used when
creating a new file, no temporary file is created (faster storage).
- -frag duration
- fragments file using ISO-Media movie fragments. Tracks will be fragmented
so that no track run exceeds the specified duration (expressed in
milliseconds). Disables interleaving.
- -out <filename>
- specifies output file name.
- -tmp <dirname>
- specifies driectory for temporary storage. If not set, temporary storage
is OS-dependent.
- -ffspace
size
- inserts free space before moof in fragmented files.
- -nosys
- removes all MPEG-4 Systems information from the file but keeps an empty
IOD for MPEG-4 Profile@Level indications. alias: -no-sys
- -no-iod
- removes InitialObjectDescriptor from file.
- -isma
- rewrites the file as an ISMA 1.0 Audio/Video file (all systems info
rewritten) with proper clock references.
- -ismax
- rewrites the file as an ISMA 1.0 Audio/Video file (all systems info
rewritten) with ISMA clock references (streams not explicetly
synchronized).
NOTE: Seeking may be broken with some players (in ISMA, audio and video
streams do not depend on main scene clock).
- -3gp
- rewrites the file as a 3GP file (no more MPEG-4 Systems specific info).
This option is turned on by default when input file extension is .3gp or
.3g2.
- -ipod
- rewrites the file for iPod.
- -brand
ABCD[:v]
- sets major brand of file, with optional version.
- -ab ABCD
- adds given brand to file's alternate brand list.
- -rb ABCD
- removes given brand to file's alternate brand list.
- -cprt string
- adds string copyright notice to file.
- -chap
chap_file
- adds chapter information contained in chap_file to movie. For more details
on chapter file syntax, cf
http://gpac.sourceforge.net/auth_mp4box.php.
- -rem trackID
- removes given track from file - can be specified multiple times.
- -enable
trackID
- enables given track.
- -disable
trackID
- disables given track.
- -new
- forces creation of a new destination file.
- -lang
[tkID=]LAN
- sets the language of all tracks or the given track. LAN is the ISO 639-2 3
character code.
- -delay
[tkID=]delay_ms
- sets the delay in milliseconds of all tracks or the given track. LAN is
the ISO 639-2 3 character code.
- -par tkID=PAR
- sets visual track pixel aspect ratio (PAR=Num:Den or
"none").
- -name
tkID=name
- sets track handler name.
- -itags
tag1[:tag2]
- sets iTunes tags to file - more info: MP4Box -tag-list.
- -split
time_in_seconds
- splits in files of desired maximum duration. This will remove all MPEG-4
Systems media.
- -split-size
size_in_kilobytes
- splits in files of desired maximum size. This will remove all MPEG-4
Systems media. Alias: -splits
- -split-chunk
start:end
- extracts a new file from specified start to end times (in seconds). This
will remove all MPEG-4 Systems media. Alias: -splitx
- -splitz
start:end
- same as -split-chunk option, but adjust end time to be juste before the
last rap found in the chunk.
- -split-rap
start:end
- splits in files begining at each RAP. This will remove all MPEG-4 Systems
media. Alias: -splitr
- -group-add
fmt
- creates a new grouping information in the file. Format is a
colon-separated list of following options:
refTrack=ID: ID of the track used as a group reference. If not set, the
track will belong to the same group as the previous trackID specified. If
0 or no previous track specified, a new alternate group will be created.
switchID=ID: ID of the switch group to create. If 0, a new ID will be
computed for you. If <0, disables SwitchGroup.
criteria=string: list of space-separated 4CCs.
trackID=ID: ID of the track to add to this group.
*WARNING* Options modify state as they are parsed:
trackID=1:criteria=lang:trackID=2 is different from:
criteria=lang:trackID=1:trackID=2. -group-rem-track ID removes
track from its group.
- -group-rem
ID
- removes the track's group.
- -group-clean
- removes all group information from all tracks.
- -ref
id:XXXX:refID
- adds a reference of type 4CC from track ID to track refID.
- -dash DUR
- enables DASH-ing of the file with a segment duration of DUR.
- -rap
- segments begin with random access points.
- -frags-per-sidx
N
- sets the number of segments to be written in each SIDX box.
- -segment-name
name
- sets the segment name for generated segments.
- -segment-ext
name
- sets the segment extension name. Default is m4s.
- -url-template
- uses UrlTemplate instead of explicit sources in segments.
- -daisy-chain
- Uses daisy-chain SIDX instead of hierarchical. Ignored if frags/sidx is
0.
- -dash-ctx
FILE
- Stores/restore DASH timing from FILE.
- -dash-ts-prog
N
- Program_number to be considered in case of an MPTS input file.
When input file is an ISO-Media file (QT, MP4, 3GP), if no
output is specified THE INPUT FILE IS OVERWRITTEN.
- -hint
- hint the file for RTPRTSP sessions. Payload type is automatically detected
and configured unless forced through one of MPEG-4 Generic RTP
payload.
- -mtu size
- specifies Maximum Transmission Unit size in bytes (eg maximum RTP packet
size). Default size is 1500 bytes (Ethernet MTU). This must be choosen
carefully: specifying too large packets will result in undesired packet
fragmentation at UDP layer while specifying too small packets will result
in RTP header overhead.
- -copy
- forces hinted data to be copied to the hint track instead of simply
referenced. This speeds up RTP packet construction at the server side but
results in much bigger files.
- -tight
- performs sample-based interleaving of media tracks and hint tracks. This
should reduce disk seeks at server side (depending on server
implementation) but results in a bigger file.
- -multi
[maxptime]
- enables Access Units concatenation in RTP packets if possible. maxptime is
optional and specifies the maximum packet duration in milliseconds
(default 100).
- -rate ck_rate
- specifies the rtp rate in Hz when no default rate for payload. Default
value is 90000 (MPEG rtp rates).
- -mpeg4
- forces usage of the MPEG-4 generic payload whenever possible. Media tracks
without a mapping to MPEG-4 Systems cannot use this.
- -latm
- forces usage of the LATM payload for AAC audio.
- -static
- enables usage of static RTP payload IDs for streams with official payload
IDs. By default MP4Box always uses dynamic payload IDs for maximum
interoperability, some players having troubles with static ones.
MPEG-4 Generic Payload Options (Experts only)
- -ocr forces all media tracks in the file to be served synchronized.
This is needed because most streaming servers don't support desynchronized
tracks in a single file. Be extremelly carefull when designing MPEG-4
interactive presentations for streaming since you will have to take care
of the streaming server capabilities... MP4Box generates warnings when the
file timeline can be ambiguously interpreted by the server.
- -rap signals Access Units random access flag in RTP packets. This
is usually only needed for streaming of MPEG-4 Systems streams.
- -ts signals Access Units Time Stamps (CTS and DTS) in RTP
packets.
- -size signals Access Units size in RTP packets.
- -idx signals Access Units indexes (sequence numbers) in RTP
packets.
- -multi enables Access Units concatenation in RTP packets (-ts,
-size and -idx are selected if needed).
- -iod prevents system tracks embedding in IOD (ISMA-like IOD) when
generating in SDP. MP4Box automatically detects ambiguous (ISMA/non-ISMA)
files but nobody's perfect. This shouldn't be used with -isma option.
- -add-sdp
string
- adds string to movie SDP or track SDP (tkID:string, where tkID is the OD
of the hint track or its media track). This takes care of SDP line
reordering, but not of SDP content validity.
- -unhint
- removes all hint tracks and other hinting info from the file.
- -add
<src_file>
- adds all src_file tracks to input file, creating it if not exisiting. Up
to 20 cumulated -add operations can be used. Supported syntaxes are:
file#video: imports first video track from src_file.
file#audio: imports first audio track from src_file.
file#trackID=ID or file#ID: imports given trackfrom src_file. To get a
listing of tracks in input file, use -info [ID]
[;lang=LAN]: specifies language of imported media.
[;delay=delay_ms]: specifies initial delay in milliseconds of imported
media.
- -cat
<src_file>
- concatenates all src_file tracks to input file, creating it if not
exisiting. Media samples are added at the end of existing compatible
tracks. If no compatible track is found for a media it is created. Up to
20 cumulated -cat operations can be used. Syntax is the same as -add.
- -force-cat
- skips media configuration check when concatenating file.
- -keepsys
- by default all MPEG-4 systems media are removed with -add and -cat. This
option will avoid removing them from final file.
- -keep-all
- keeps all existing tracks when add file.
- -dref
- keeps media data in original file an only imports meta-data (frame timing,
size and random access).
- NOTE
- Data referencing may fail with some AVI because it requires the framed
data (eg an MP4 sample) to be continuous in the original file, which is
not always the case depending on the original interleaving.
- -no-drop
- forces constant FPS when importing AVI video. By default non coded frames
(n-vop) are removed at import time, resulting in a variable frame-rate
media.
- -packed
- for CMP/M4V (raw MPEG-4 Visual), forces packed-bitstream mode (removes all
n-vops and import at constant frame rate).
- -sbr
- imports AAC as AAC-SBR, with backward compatible signaling (non AAC-SBR
decoders should be able to play it).
- -sbrx
- imports AAC as AAC-SBR, with non-backward compatible signaling (non
AAC-SBR decoders will not be able to play it).
- -ovsbr
- imports AAC as AAC-SBR with oversample SBR.
- -ps
- imports AAC as AAC-PS, with backward compatible signaling of AAC-PS.
- -psx
- imports AAC as AAC-PS, with non-backward compatible signaling (non AAC-PS
decoders will not be able to play it).
- -fps FrameRate
- overrides the input video frame rate or specifies it for SUB
subtitles.
- -mpeg4
- forces using MPEG-4 sample descriptions rather than 3GP ones (3GP2
QCELP/EVRC/SMV audio only).
- -agg N
- aggregates N audio frames in 1 sample (3GP media only). Maximum possible
value is 15, and default value is 1 (no aggregation).
- -mp4
- specifies input file is for encoding. Supported inputs are
BT/XMT-A/WRL/SWF files. Output file name is by default the input file name
without extensions plus ".mp4" extension.
- -def
- encodes DEF'ed nodes and routes with their textual names.
- -log
- generates BIFS encoder log file.
- -ms file
- specifies file for track importing - by default FILE.mp4 is used when
encoding FILE.bt (in-place rewrite). This option is only needed if you
don't provide a proper muxInfo per stream in the BT/XMT file.
- -sync time
- forces BIFS random access point generation every time milliseconds. Cannot
be used with -shadow. WARNING: this may result in weird behavior of your
presentation since a BIFS random access point restarts all media currently
running in the scene (EXPERTS ONLY - DANGEROUS). Cannot be used with
-shadow.
- -shadow
time
- forces BIFS shadow random access points generation every time
milliseconds. Shadow samples are random access points that can be used
instead of non random access points when seeking. WARNING: this may be not
supported by some players (EXPERTS ONLY - DANGEROUS). Cannot be used with
-sync.
- -ctx-in
file
- specifies initial context (MP4/BT/XMTA) for chunk processing. Input file
must then be a command-only file: no IOD, and no implicit commands
(commands without 'AT').
- -ctx-out
file
- specifies output file of updated context (MP4/BT/XMTA) in chunk processing
mode. This is optional, chunk processing doesn't need to store the final
context.
- -resolution
res
- LASeR resolution factor (-8 to 7, default 0). All coords are multiplied by
2^res before truncation.
- -coord-bits
bits
- bits used for encoding truncated coordinates in LASeR. (0 to 31, default
12)
- -scale-bits
bits
- bits used for encoding truncated scales in LASeR. (0 to 4, default 0)
- -auto-quant
res
- Use automatic LASeR quantification. resolution is given as if using
-resolution but coord-bits and scale-bits are infered.
- -crypt
drm_file
- crypts a specific track using ISMA AES CTR 128.
- -decrypt
[drm_file]
- decrypts a specific track using ISMA AES CTR 128. drm_file can be omitted
if keys are in file.
- -set-kms
[tkID=]kms_uri
- changes KMS location for all tracks or a given one if tkID is
specified.
- DRM file syntax for GPAC
ISMACryp
- File is XML and shall start with xml header. File root is an
"ISMACryp" element. File is a list of "ISMACrypTrack"
elements.
ISMACrypTrack attributes:
TrackID: ID of track to en/decrypt.
key: AES-128 key formatted (hex string 0x +32 chars.
salt: CTR IV salt key (64 bits) (hex string 0x +16 chars.
Encryption only attributes
Scheme_URI: URI of scheme used.
KMS_URI: URI of key management system - ´self´ writes key and
salt in the file.
selectiveType selective encryption type - understood values are
"None": all samples encrypted (default), "RAP": only
encrypts random access units, "Non-RAP": only encrypts
non-random access units, "Rand": random selection is
performed", "X": Encrypts every first sample out of X,
"RandX": Encrypts one random sample out of X.
ipmpType: IPMP Signaling Type: None, IPMP, IPMPX.
ipmpDescriptorID: IPMP_Descriptor ID to use if IPMP(X) is used. If not set
MP4Box will generate one for you.
- -raw TrackID
- extracts given track in native format when supported.
- -raws TrackID
- extract each track sample to a file. Note: 'TrackID:N' extracts Nth sample
of the track.
- -nhnt TrackID
- extracts given track in NHNT format. All track types except
ObjectDescriptors tracks can be exported.
- -nhml TrackID
- extracts track in nhml format (XML nhnt). All track types except
ObjectDescriptors tracks can be exported.
- -single
TrackID
- extracts given track to a new mp4 file with a single track.
- -avi TrackID
- extracts visual track to an avi file.
- -qcp TrackID
- same as '-raw' but defaults to QCP file format for AVRC and SMV audio
codecs.
- -aviraw TK
- extracts AVI track to its raw format. TK can be one of "video",
"audio" or "audioN" for multi-track avi files (cf
'-info').
- -saf
- remux file to SAF multiplex.
- -dvbhdemux
- demux DVB-H file into IP Datagrams.
- -diod
- extracts file IOD in raw format when supported.
- -info
[TrackID]
- prints movie and tracks information. If TrackID specified, dumps only
extended track info. If input file is not an IsoMedia file, lists known
tracks for import.
- -bt
- dumps complete scene in a BT file. This will remove unknown MPEG4
nodes.
- -xmt
- dumps complete scene in an XMT-A file. This will remove unknown MPEG4
nodes.
- -wrl
- dumps complete scene in an VRML97 WRL file. This will remove unknown
VRML97 nodes.
- -x3d
- dumps complete scene in an X3D XML file. This will remove unknown X3D
nodes.
- -x3dv
- dumps complete scene in an X3D Text (VRML) file. This will remove unknown
X3D nodes.
- -lsr
- dumps complete scene in a LASeR+XML file.
- -diso
- creates XML image of the file atoms.
- -drtp
- creates XML image of all hint tracks samples of a hinted mp4 file.
- -dts
- prints sample timing to text output.
- -dcr
- creates XML image of all ISMACryp tracks samples of an mp4 file.
- -sdp
- creates SDP file associated with a hinted mp4 file.
- -dump-cover
- Extracts cover art if any.
- -dump-chap
- Extracts chapter list to file if any.
- -ttxt
- converts input subtitle to GPAC TTXT format.
- -ttxt trackID
- exports given text track to GPAC TTXT format.
- -srt
- converts input subtitle to SRT format.
- -srt trackID
- exports given text track to SRT subtitle format.
- -std
- dumps to stdout rather than file.
- -stat
- generates statitistic report on node/field usage for the whole
presentation.
- -stats
- generates statistic report on node/field usage per BIFS Access Unit.
- -statx
- generates statistic report on node/field usage in the scene graph after
each BIFS Access Unit.
- -hash
- generates SHA-1 Hash of the input file.
MP4Box supports the Meta addition to IsoMedia file format, used to
make the file a generic data container (timed or untimed).
- -set-meta
args
- sets meta object type. Syntax is "ABCD[;tk=N] where:
ABCD is the four character code of the type, or O/NULL to remove the meta
object
tk indicates whether the meta is at the root level (no "tk"), at
the moov level (tk=0) or at the track level (tk=trackID).
- -add-item
args
- adds resource to the given meta. args is the item file path followed by
';' separated options:
tk=N: same as above
name=item_name: specifies the item name, otherwise file name is used
mime=mimeType: specifies the item mime type, otherwise
application/octet-stream is used
encoding=enctype: specifies the content encoding type Note that file path
set to "this" or "self" will identify the item added
as the whole IsoMedia file
- -rem-item
args
- removes item from given meta. Syntax is itemID[;tk=ID].
- -set-primary
args
- sets given item as the primary one of the given meta. Syntax is
itemID[;tk=ID].
- -set-xml
args
- sets XML to the given meta. Syntax is xml_file_path[;tk=ID][;binary].
- -rem-xml
[tk=ID]
- removes XML data from the given meta.
- -dump-xml
xml_out_file_name[;tk=ID]
- dumps the XML data of the given meta to a file.
- -dump-item
itemID[;tk=ID][;path=fileName]
- dumps the given item of the the given meta to a file. By default the item
name is used as the output file name.
- -package
- packages input XML file into an ISO container. all media referenced except
hyperlinks are added to file.
- -mgt
- packages input XML file into an MPEG-U widget in ISO container. All files
contained in the current folder are added to the widget package.
MP4Box can stream ISO files to RTP. The streamer currently doesn't
support data carrouselling and will therefore not handle BIFS and OD streams
properly.
- -rtp
- enables rtp file streamer.
- -noloop
- disables looping when streaming.
- -mpeg4
- forces MPEG-4 ES Generic for all RTP streams.
- -dst=IP
- IP destination (uni/multi-cast). Default: 127.0.0.1.
- -port=PORT
- output port of the first stream. Default: 7000.
- -mtu=MTU
- path MTU for RTP packets. Default is 1450 bytes.
- -ifce=IP
- IP address of the physical interface to use. Default: NULL (ANY).
- -ttl=N
- time to live for multicast packets. Default: 1.
- -sdp=FILE
- file name of the generated SDP. Default is session.sdp.
MP4Box can stream BIFS or DIMS content to RTP with carousel
generation and updates. The streamer currently doesn't support
audio/video/image streaming at the same time. All options supported by the
file streamer are supported.
- -live
- enables rtp live streamer.
- -dims
- turns on DIMS mode for SVG input - default: off.
- -src=FILE
- source of updates - default: null.
- -rap=TIME
- duration in ms of base carousel - default: 0 (off). you can specify the
RAP period of a single ESID (not in DIMS) with -rap=ESID=X:time.
- Runtime
Options
- The following options can be used at prompt:
q: quits
u: inputs some commands to be sent
U: same as u but signals the updates as critical
e: inputs some commands to be sent without being aggregated
E: same as e but signals the updates as critical
f: forces RAP sending
F: forces RAP regeneration and sending
p: dumps current scene
MP4Box can import very simple Macromedia Flash files
(".SWF"). You can specify a SWF input file with -bt, xmt and -mp4
switches.
- -global
- all SWF defines are placed in first scene replace. By default SWF defines
are sent when needed.
- -no-ctrl
- uses a dedicated stream for movie control. This will disable
ActionScript.
- -no-text
- removes all SWF text.
- -no-font
- removes all embedded SWF Fonts, forcing usage of MPEG-4 Text and terminal
fonts.
- -no-line
- removes all lines from SWF shapes.
- -no-grad
- removes all gradients from swf shapes.
- -quad
- uses quadratic bezier curves instead of cubic ones.
- -xlp
- support for lines transparency and scalability.
- -flatten
Value
- replaces 2 consecutive lines by a single one when angle between lines is
less than Value (expressed in radians). Value 0 disables flattening.
- RAW Formats and
extensions
- NHNT (.media .nhnt .info)
MPEG Audio (.mp3)
ADTS-AAC (.aac)
MPEG-4 Visual (.cmp .m4v)
H263 Video (.263 .h263)
AVC/H264 Video (.h264 .h26L .264 .26L)
JPEG Images (.jpg .jpeg)
PNG Images (.png)
AMR(WB) Audio (.amr .awb)
EVRC Audio (.evc)
SMV Audio (.smv)
- Container Formats
and extensions
- AVI (.avi)
MPEG-PS (.mpg .mpeg .vob .vcd .svcd)
QCP (.qcp)
OGG (.ogg)
ISO-Media files (no extension checking)
- Text Formats and
extensions
-
SRT Subtitles (.srt)
SUB Subtitles (.sub)
GPAC Timed Text (.ttxt)
QuickTime TeXML Text (.xml) (cf QT documentation)
- Scene Formats and
extensions
- MPEG-4 XMT-A (.xmt .xmta .xmt.gz .xmta.gz)
MPEG-4 BT (.bt .bt.gz)
VRML (.wrl .wrl.gz)
X3D-XML (.x3d .x3d.gz)
X3D-VRML (.x3dv .x3dv.gz)
MacroMedia Flash (.swf) - very limitted import support only
- Importing a
file
- Import an AVI: MP4Box -add myfile.avi mymp4.mp4
Import audio from an AVI: MP4Box -add myfile.avi#audio mymp4.mp4
Import video from an AVI: MP4Box -add myfile.avi#video mymp4.mp4
Import an MP3 and leave data outside: MP4Box -dref -add myfile.mp3 mymp4.mp4
Import a JPEG or PNG: MP4Box -add myfile.jpg mymp4.mp4
Create a movie with subtitle: MP4Box -add video.avi -add audio.mp3 -add
Subtitle.srt mymp4.mp4
- Base File
operations
- Convert file for HTTP/FTP streaming: MP4Box -inter 1000 myfile.mp4
Convert unknown file to ISMA for HTTP/FTP streaming: MP4Box -isma -inter
1000 myfile.mp4
Convert unknown file to ISMA and respect ISMA broken sync: MP4Box -ismax
myfile.mp4
Convert unknown file to 3GP : MP4Box -3gp myfile.mp4
- Hinting a
File
- Prepare any mp4 for ISMA streaming: MP4Box -isma -hint myfile.mp4
Prepare any 3GP for streaming: MP4Box -hint myfile.3gp
Prepare any 3GP for streaming with RTP aggregation : MP4Box -hint -multi
myfile.3gp
Prepare a simple audio/video mp4 optimized for server: MP4Box -hint -copy
-tight myfile.mp4
Prepare a complex mp4 with BIFS for streaming: MP4Box -ocr -iod -hint
myfile.mp4
- Encoding/Decoding
a file
- Encode a BT file and keep node names for later inspection: MP4Box -mp4
-def pres.bt
Encode a XMT-A file: MP4Box -mp4 pres.xmt
Translate BT to XMT-A file: MP4Box -xmt pres.bt
Translate XMT-A to BT file: MP4Box -bt pres.xmt
Decode MP4 to BT: MP4Box -bt pres.mp4
Jean Le Feuvre <jeanlf@users.sourceforge.net> - GPAC (c)
2000-2005 - (c) Telecom ParisTech 2005-2011