General Usage
Syntax¶
MP4Box [option] input [option] [other_dash_inputs]
General Options¶
MP4Box is a multimedia packager, with a vast number of functionalities: conversion, splitting, hinting, dumping, DASH-ing, encryption, transcoding and others.
MP4Box provides a large set of options, classified by categories (see -h). These options do not follow any particular ordering.
By default, MP4Box rewrites the input file. You can change this behavior by using the -out option.
MP4Box stores by default the file with 0.5 second interleaving and meta-data (moov
...) at the beginning, making it suitable for HTTP download-and-play. This may however takes longer to store the file, use -flat to change this behavior.
MP4Box usually generates a temporary file when creating a new IsoMedia file. The location of this temporary file is OS-dependent, and it may happen that the drive/partition the temporary file is created on has not enough space or no write access. In such a case, you can specify a temporary file location with -tmp.
Track identifier for track-based operations (usually referred to as tkID
in the help) use the following syntax:
- INT: target is track with ID
INT
- n
INT
: target is track numberINT
audio
,video
,text
: target is firstaudio
,video
ortext
trackaudioN
,videoN
,textN
: target is theN
thaudio
,video
ortext
track, withN=1
being the first track of desired type
Option values:
Unless specified otherwise, a track operation option of type integer
expects a track identifier value following it.
An option of type boolean
expects no following value.
-mem-track: enable memory tracker
-mem-track-stack: enable memory tracker with stack dumping
-p (string): use indicated profile for the global GPAC config. If not found, config file is created. If a file path is indicated, this will load profile from that file. Otherwise, this will create a directory of the specified name and store new config there. Reserved name 0
means a new profile, not stored to disk. Works using -p=NAME or -p NAME
-inter (number, default: 0.5): interleave file, producing track chunks with given duration in ms. A value of 0 disables interleaving
-old-inter (number): same as -inter but without drift correction
-tight: tight interleaving (sample based) of the file. This reduces disk seek operations but increases file size
-flat: store file with all media data first, non-interleaved. This speeds up writing time when creating new files
-frag (number): fragment file, producing track fragments of given duration in ms. This disables interleaving
-out (string): specify ISOBMFF output file name. By default input file is overwritten
-co64: force usage of 64-bit chunk offsets for ISOBMF files
-new: force creation of a new destination file
-newfs: force creation of a new destination file without temp file but interleaving support
-no-sys,-nosys: remove all MPEG-4 Systems info except IOD, kept for profiles. This is the default when creating regular AV content
-no-iod: remove MPEG-4 InitialObjectDescriptor from file
-mfra: insert movie fragment random offset when fragmenting file (ignored in dash mode)
-isma: rewrite the file as an ISMA 1.0 file
-ismax: same as -isma and remove all clock references
-3gp: rewrite as 3GPP(2) file (no more MPEG-4 Systems Info), always enabled if destination file extension is .3gp
, .3g2
or .3gpp
. Some tracks may be removed in the process
-ipod: rewrite the file for iPod/old iTunes
-psp: rewrite the file for PSP devices
-brand (string): set major brand of file (ABCD
) or brand with optional version (ABCD:v
)
-ab (string): add given brand to file's alternate brand list
-rb (string): remove given brand to file's alternate brand list
-cprt (string): add copyright string to file
-chap (string): set chapter information from given file. The following formats are supported (but cannot be mixed) in the chapter text file:
- ZoomPlayer: `AddChapter(nb_frames,chapter name)`, `AddChapterBySeconds(nb_sec,chapter name)` and `AddChapterByTime(h,m,s,chapter name)` with 1 chapter per line
- Time codes: `h:m:s chapter_name`, `h:m:s:ms chapter_name` and `h:m:s.ms chapter_name` with 1 chapter per line
- SMPTE codes: `h:m:s;nb_f/fps chapter_name` and `h:m:s;nb_f chapter_name` with `nb_f` the number of frames and `fps` the framerate with 1 chapter per line
- Common syntax: `CHAPTERX=h:m:s[:ms or .ms]` on first line and `CHAPTERXNAME=name` on next line (reverse order accepted)
-chapqt (string): set chapter information from given file, using QT signaling for text tracks
-set-track-id tkID:id2
: change id of track to id2
-swap-track-id tkID1:tkID1
: swap the id between tracks with id1 to id2
-rem (int): remove given track from file
-rap (int): remove all non-RAP samples from given track
-refonly (int): remove all non-reference pictures from given track
-enable (int): enable given track
-disable (int): disable given track
-timescale (int, default: 600): set movie timescale to given value (ticks per second)
-lang [tkID=]LAN
: set language. LAN is the BCP-47 code (eng, en-UK, ...). If no track ID is given, sets language to all tracks
-delay tkID=TIME
: set track start delay (>0) or initial skip (<0) in ms or in fractional seconds (N/D
)
-par tkID=PAR
: set visual track pixel aspect ratio. PAR is:
- N:D: set PAR to N:D in track, do not modify the bitstream
- wN:D: set PAR to N:D in track and try to modify the bitstream
- none: remove PAR info from track, do not modify the bitstream
- auto: retrieve PAR info from bitstream and set it in track
- force: force 1:1 PAR in track, do not modify the bitstream
-clap tkID=CLAP
: set visual track clean aperture. CLAP is Wn,Wd,Hn,Hd,HOn,HOd,VOn,VOd
or none
- n, d: numerator, denominator
- W, H, HO, VO: clap width, clap height, clap horizontal offset, clap vertical offset
-mx tkID=MX
: set track matrix, with MX is M1:M2:M3:M4:M5:M6:M7:M8:M9 in 16.16 fixed point integers or hexa
-kind tkID=schemeURI=value
: set kind for the track or for all tracks using all=schemeURI=value
-kind-rem tkID=schemeURI=value
: remove kind if given schemeID for the track or for all tracks with all=schemeURI=value
-name tkID=NAME
: set track handler name to NAME (UTF-8 string)
-tags,-itags (string): set iTunes tags to file, see -h tags
-group-add (string): create a new grouping information in the file. Format is a colon-separated list of following options:
- refTrack=ID: 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: 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 (int): remove given track from its group
-group-rem (int): remove the track's group
-group-clean: remove all group information from all tracks
-ref tkID:R4CC:refID
: add a reference of type R4CC from track ID to track refID (remove track reference if refID is 0)
-keep-utc: keep UTC timing in the file after edit
-udta tkID:[OPTS]
: set udta for given track or movie if tkID is 0. OPTS is a colon separated list of:
- type=CODE: 4CC code of the UDTA (not needed for
box=
option) - box=FILE: location of the udta data, formatted as serialized boxes
- box=base64,DATA: base64 encoded udta data, formatted as serialized boxes
- src=FILE: location of the udta data (will be stored in a single box of type CODE)
- src=base64,DATA: base64 encoded udta data (will be stored in a single box of type CODE)
- str=STRING: use the given string as payload for the udta box
Note: If no source is set, UDTA of type CODE will be removed
-patch [tkID=]FILE
: apply box patch described in FILE, for given trackID if set
-bo: freeze the order of boxes in input file
-init-seg (string): use the given file as an init segment for dumping or for encryption
-zmov: compress movie box according to ISOBMFF box compression or QT if mov extension
-xmov: same as zmov and wraps ftyp in otyp
-edits tkID=EDITS
: set edit list. The following syntax is used (no separators between entries):
- `r`: removes all edits
- `eSTART`: add empty edit with given start time. START can be
VAL
: start time in seconds (int, double, fraction), media duration used as edit duration-
VAL-DUR
: start time and duration in seconds (int, double, fraction)eSTART,MEDIA[,RATE]
: add regular edit with given start, media start time in seconds (int, double, fraction) and rate (fraction or INT)- Examples:
-
re0-5e5-3,4
: remove edits, add empty edit at 0s for 5s, then add regular edit at 5s for 3s starting at 4s in media track re0-4,0,0.5
: remove edits, add single edit at 0s for 4s starting at 0s in media track and playing at speed 0.5
-moovpad (int): specify amount of padding to keep after moov box for later inplace editing - if 0, moov padding is disabled
-no-inplace: disable inplace rewrite
-hdr (string): update HDR information based on given XML, 'none' removes HDR info
-time [tkID=]DAY/MONTH/YEAR-H:M:S
: set movie or track creation time
-mtime tkID=DAY/MONTH/YEAR-H:M:S
: set media creation time
Encryption/Decryption Options¶
MP4Box supports encryption and decryption of ISMA, OMA and CENC content, see encryption filter gpac -h cecrypt
.
It requires a specific XML file called CryptFile
, whose syntax is available at https://wiki.gpac.io/xmlformats/Common-Encryption
Image files (HEIF) can also be crypted / decrypted, using CENC only.
Options:
-crypt (string): encrypt the input file using the given CryptFile
-decrypt (string): decrypt the input file, potentially using the given CryptFile
. If CryptFile
is not given, will fail if the key management system is not supported
-set-kms tkID=kms_uri
: change ISMA/OMA KMS location for a given track or for all tracks if all=
is used
Help Options¶
-h (string): print help
- general: general options help
- hint: hinting options help
- dash: DASH segmenter help
- split: split options help
- import: import options help
- encode: scene description encoding options help
- meta: meta (HEIF, MPEG-21) handling options help
- extract: extraction options help
- dump: dump options help
- swf: Flash (SWF) options help
- crypt: ISMA E&A options help
- format: supported formats help
- live: BIFS streamer help
- core: libgpac core options
- all: print all the above help screens
- opts: print all options
- tags: print supported iTunes tags
- cicp: print various CICP code points
- VAL: search for option named
VAL
(without-
or--
) in MP4Box, libgpac core and all filters
-hx (string): look for given string in name and descriptions of all MP4Box and filters options
-nodes: list supported MPEG4 nodes
-nodex: list supported MPEG4 nodes and print nodes
-node (string): get given MPEG4 node syntax and QP infolist
-xnodes: list supported X3D nodes
-xnodex: list supported X3D nodes and print nodes
-xnode (string): get given X3D node syntax
-snodes: list supported SVG nodes
-languages: list supported ISO 639 languages
-boxes: list all supported ISOBMF boxes and their syntax
-stats,-fstat: print filter session statistics (import/export/encrypt/decrypt/dashing)
-graph,-fgraph: print filter session graph (import/export/encrypt/decrypt/dashing)
-v: verbose mode
-version: get build version
-- INPUT
: escape option if INPUT starts with -
character