MP4Box(1) GPAC MP4Box(1)NAME
MP4Box - MPEG-4 Systems Toolbox
SYNOPSIS
MP4Box [options] file [options]
DESCRIPTION
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 IsoMe‐
dia/AVI/MPEG-PS/OGG containers, file hinting for RTP streaming for
QuickTime compatible streaming servers, file interleaving, file frag‐
mentation 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 con‐
vert 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.
GETTING HELP WITH MP4Box-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.
GENERAL OPTIONS-inter duration
interleaves media data in chunks of the maximum specified dura‐
tion (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 inter‐
leaving (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.source‐
forge.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 sec‐
onds). 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: crite‐
ria=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 out‐
put is specified THE INPUT FILE IS OVERWRITTEN.
HINTING OPTIONS-hint hint the file for RTPRTSP sessions. Payload type is automati‐
cally 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 offi‐
cial 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 synchro‐
nized. This is needed because most streaming servers don't sup‐
port desynchronized tracks in a single file. Be extremelly care‐
full when designing MPEG-4 interactive presentations for stream‐
ing 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 pack‐
ets.
-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.
IMPORT OPTIONS-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. Sup‐
ported 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).
ENCODING OPTIONS-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 millisec‐
onds. 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. WARN‐
ING: 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.
ISMACRYPT OPTIONS-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.
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.
EXTRACTING OPTIONS-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.
DUMP OPTIONS-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.
Meta OPTIONS
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 fol‐
lowed 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 applica‐
tion/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 refer‐
enced 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 wid‐
get package.
RTP STREAMER OPTIONS
MP4Box can stream ISO files to RTP. The streamer currently doesn't sup‐
port 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.
LIVE SCENE STREAMER OPTIONS
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.
ptions 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
SWF OPTIONS
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 dis‐
ables flattening.
SUPPORTED INPUT FORMATS
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
COMMON USAGE
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
BUGS and OTHER HELP
For bug reports, more information on BT or XMT-A formats or GPAC TTXT
files or ISMACryp, MPEG-4 Systems usage and more help on MP4Box please
visit the GPAC web site http://gpac.sourceforge.net
AUTHORS
Jean Le Feuvre <jeanlf@users.sourceforge.net> - GPAC (c) 2000-2005 -
(c) Telecom ParisTech 2005-2011
SEE ALSOGPAC(1), MP4Client(1)MP4Box June 2005 MP4Box(1)
