Skip to content

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
  • nINT: target is track number INT
  • audio, video, text: target is first audio, video or text track
  • audioN, videoN, textN: target is the Nth audio, video or text track, with N=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

Was this page helpful?