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

GETTING HELP WITH MP4Box

-h [type]

prints help screen. "type" can be one of "general", "hint", "import", "encode", "extract", "dump", "swf", "meta", "crypt", "format" for specific help.

-version

prints version of MP4Box.

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

GENERAL OPTIONS

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

-nosys removes all MPEG-4 Systems information from the file but keeps

an empty IOD for MPEG-4 Profile@Level indications.

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

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

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

-split time_in_seconds

splits in files of desired maximum duration. This will remove all MPEG-4 Systems media.

-splits size_in_kilobytes

splits in files of desired maximum size. This will remove all MPEG-4 Systems media.

-splitx start:end

extracts a new file from specified start to end times (in seconds). This will remove all MPEG-4 Systems media. When input file is an ISO-Media file (QT, MP4, 3GP), if no output 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 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.

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

-keepsys

by default all MPEG-4 systems media are removed with -add and -cat. This option will avoid removing them from final 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.

-nodrop

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 signal

ing (non AAC-SBR decoders should be able to play it).

-sbrx imports AAC as AAC-SBR, with non-backward compatible sig

naling (non AAC-SBR 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
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.

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

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

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.

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

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.

-diso creates XML image of the file atoms.

-drtp creates XML image of all hint tracks samples of a hinted

mp4 file.

-dcr creates XML image of all ISMACryp tracks samples of an

mp4 file.

-sdp creates SDP file associated with a hinted mp4 file.

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

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

SWF OPTIONS

MP4Box can import very simple Macromedia Flash files (".SWF").
You can specify a SWF input file with -bt, xmt and -mp4
switches.

-static

all SWF defines are placed in first scene replace. By
default SWF defines are sent when needed.

-ctrl uses a dedicated stream for movie control (forces -static

option).

-notext

removes all SWF text.

-nofont

removes all embedded SWF Fonts, forcing usage of MPEG-4
Text and terminal fonts.

-noline

removes all lines from SWF shapes.

-nograd

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.

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

SEE ALSO

GPAC(1), MP4Client(1)

MP4Box June 2005 MP4Box(1)