mp4box gen opts

Warning

GPAC's wiki has moved to wiki.gpac.io.

This github wiki will no longer be updated.

You can contribute to GPAC's documentation here.

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