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

Importing Options

File importing

Syntax is -add / -cat URL[#FRAGMENT][:opt1...:optN=val]
This process will create the destination file if not existing, and add the track(s) to it. If you wish to always create a new destination file, add -new.
The supported input media types depend on your installation, check filters documentation for more info.

To select a desired media track from a source, a fragment identifier '#' can be specified, before any other options. The following syntax is used:

• #video: adds the first video track found in source
• #audio: adds the first audio track found in source
• #auxv: adds the first auxiliary video track found in source
• #pict: adds the first picture track found in source
• #trackID=ID or #ID: adds the specified track. For IsoMedia files, ID is the track ID. For other media files, ID is the value indicated by MP4Box -info inputFile
• #pid=ID: number of desired PID for MPEG-2 TS sources
• #prog_id=ID: number of desired program for MPEG-2 TS sources
• #program=NAME: name of desired program for MPEG-2 TS sources

By default all imports are performed sequentially, and final interleaving is done at the end; this however requires a temporary file holding original ISOBMF file (if any) and added files before creating the final output. Since this can become quite large, it is possible to add media to a new file without temporary storage, using -flat option, but this disables media interleaving.

If you wish to create an interleaved new file with no temporary storage, use the -newfs option. The interleaving might not be as precise as when using -new since it is dependent on multiplexer input scheduling (each execution might lead to a slightly different result). Additionally in this mode:

• Some multiplexing options (marked with X below) will be activated for all inputs (e.g. it is not possible to import one AVC track with xps_inband and another without).
• Some multiplexing options (marked as D below) cannot be used as they require temporary storage for file edition.
• Usage of -cat is possible, but concatenated sources will not be interleaved in the output. If you wish to perform more complex cat/add operations without temp file, use a playlist.

Source URL can be any URL supported by GPAC, not limited to local files.

Note: When importing SRT or SUB files, MP4Box will choose default layout options to make the subtitle appear at the bottom of the video. You SHOULD NOT import such files before any video track is added to the destination file, otherwise the results will likely not be useful (default SRT/SUB importing uses default serif font, fontSize 18 and display size 400x60). For more details, check TTXT doc.

When importing several tracks/sources in one pass, all options will be applied if relevant to each source. These options are set for all imported streams. If you need to specify these options per stream, set per-file options using the syntax -add stream[:opt1:...:optN].

The import file name may be set to empty or self, indicating that the import options should be applied to the destination file track(s).
Example

-add self:moovts=-1:noedit src.mp4

This will apply moovts and noedit option to all tracks in src.mp4
Example

-add self#2:moovts=-1:noedit src.mp4

This will apply moovts and noedit option to track with ID=2 in src.mp4
Only per-file options marked with a S are possible in this mode.

When importing an ISOBMFF/QT file, only options marked as C or S can be used.

Allowed per-file options:

dur (int): XC import only the specified duration from the media. Value can be:

• positive float: specifies duration in seconds
• fraction: specifies duration as NUM/DEN fraction
• negative integer: specifies duration in number of coded frames

start (number): C target start time in source media, may not be supported depending on the source
lang (string): S set imported media language code
delay (int): S set imported media initial delay (>0) or initial skip (<0) in ms or as fractional seconds (N/D)
par (string): S set visual pixel aspect ratio (see -par )
clap (string): S set visual clean aperture (see -clap )
mx (string): S set track matrix (see -mx )
name (string): S set track handler name
ext (string): override file extension when importing
hdlr (string): S set track handler type to the given code point (4CC)
stype (string): S force sample description type to given code point (4CC), may likely break the file
tkhd (int): S set track header flags has hex integer or as comma-separated list of enable, movie, preview, size_ar keywords (use tkhd+=FLAGS to add and tkhd-=FLAGS to remove)
disable: S disable imported track(s), use disable=no to force enabling a disabled track
group (int): S add the track as part of the G alternate group. If G is 0, the first available GroupID will be picked
fps (string): S same as -fps
rap: DS import only RAP samples
refs: DS import only reference pictures
trailing: keep trailing 0-bytes in AVC/HEVC samples
agg (int): X same as -agg
dref: XC same as -dref
keep_refs: C keep track reference when importing a single track
nodrop: same as -nodrop
packed: X same as -packed
sbr: same as -sbr
sbrx: same as -sbrx
ovsbr: same as -ovsbr
ps: same as -ps
psx: same as -psx
asemode (string): XS set the mode to create the AudioSampleEntry. Value can be:

• v0-bs: use MPEG AudioSampleEntry v0 and the channel count from the bitstream (even if greater than 2) - default
• v0-2: use MPEG AudioSampleEntry v0 and the channel count is forced to 2
• v1: use MPEG AudioSampleEntry v1 and the channel count from the bitstream
• v1-qt: use QuickTime Sound Sample Description Version 1 and the channel count from the bitstream (even if greater than 2). This will also trigger using alis data references instead of url, even for non-audio tracks

audio_roll (int): S add a roll sample group with roll_distance N for audio tracks
roll (int): S add a roll sample group with roll_distance N
proll (int): S add a preroll sample group with roll_distance N
mpeg4: X same as -mpeg4 option
nosei: discard all SEI messages during import
svc: import SVC/LHVC with explicit signaling (no AVC base compatibility)
nosvc: discard SVC/LHVC data when importing
svcmode (string): DS set SVC/LHVC import mode. Value can be:

• split: each layer is in its own track
• merge: all layers are merged in a single track
• splitbase: all layers are merged in a track, and the AVC base in another
• splitnox: each layer is in its own track, and no extractors are written
• splitnoxib: each layer is in its own track, no extractors are written, using inband param set signaling

temporal (string): DS set HEVC/LHVC temporal sublayer import mode. Value can be:

• split: each sublayer is in its own track
• splitbase: all sublayers are merged in a track, and the HEVC base in another
• splitnox: each layer is in its own track, and no extractors are written

subsamples: add SubSample information for AVC+SVC
deps: import sample dependency information for AVC and HEVC
ccst: S add default HEIF ccst box to visual sample entry
forcesync: force non IDR samples with I slices (OpenGOP or GDR) to be marked as sync points

Warning: RESULTING FILE IS NOT COMPLIANT WITH THE SPEC but will fix seeking in most players

xps_inband: XC set xPS inband for AVC/H264 and HEVC (for reverse operation, re-import from raw media)
xps_inbandx: XC same as xps_inband and also keep first xPS in sample description
au_delim: keep AU delimiter NAL units in the imported file
max_lid (int): set HEVC max layer ID to be imported to N (by default imports all layers)
max_tid (int): set HEVC max temporal ID to be imported to N (by default imports all temporal sublayers)
tiles: S add HEVC tiles signaling and NALU maps without splitting the tiles into different tile tracks
split_tiles: DS split HEVC tiles into different tile tracks, one tile (or all tiles of one slice) per track
negctts: S use negative CTS-DTS offsets (ISO4 brand). Use negctts=no to force using positive offset on existing track
chap: S specify the track is a chapter track
chapter (string): S add a single chapter (old nero format) with given name lasting the entire file
chapfile (string): S add a chapter file (old nero format)
layout (string): S specify the track layout as WxH[xXxY][xLAYER]. If W (resp H) is 0, the max width (resp height) of the tracks in the file are used
rescale (int): S force media timescale to TS (int or fraction) and change the media duration
sampdur (int): S force all samples duration (D) or sample durations and media timescale (D/TS), used to patch CFR files with broken timings
timescale (int): S set imported media timescale to TS
moovts (int): S set movie timescale to TS. A negative value picks the media timescale of the first track imported
noedit: XS do not set edit list when importing B-frames video tracks
rvc (string): S set RVC configuration for the media
fmt (string): override format detection with given format - disable data probing and force ext option on source

profile (int): S override AVC profile. Integer value, or high444, high, extended, main, baseline
level (int): S override AVC level, if value < 6, interpreted as decimal expression
compat (int): S force the profile compatibility flags for the H.264 content
novpsext: remove VPS extensions from HEVC VPS
keepav1t: keep AV1 temporal delimiter OBU in samples, might help if source file had losses
dlba (string): S force DolbyAtmos mode for EAC3. Value can be

• no: disable Atmos signaling
• auto: use Atmos signaling from first sample
• N: force Atmos signaling using compatibility type index N

font (string): specify font name for text import (default Serif)
size (int): specify font size for text import (default 18)
text_layout (string): specify the track text layout as WxHxXxY

• if W (resp H) = 0: the max width (resp height) of the tracks in the file are used
• if Y=-1: the layout is moved to the bottom of the track area
• X and Y can be omitted: :layout=WxH

swf-global: all SWF defines are placed in first scene replace rather than when needed
swf-no-ctrl: use a single stream for movie control and dictionary (this will disable ActionScript)
swf-no-text: remove all SWF text
swf-no-font: remove all embedded SWF Fonts (local playback host fonts used)
swf-no-line: remove all lines from SWF shapes
swf-no-grad: remove all gradients from SWF shapes
swf-quad: use quadratic bezier curves instead of cubic ones
swf-xlp: support for lines transparency and scalability
swf-ic2d: use indexed curve 2D hardcoded proto
swf-same-app: appearance nodes are reused
swf-flatten (number): complementary angle below which 2 lines are merged, 0 means no flattening
kind (string): S set kind for the track as schemeURI=value
txtflags (int): set display flags (hexa number) of text track. Use txtflags+=FLAGS to add flags and txtflags-=FLAGS to remove flags
rate (int): force average rate and max rate to VAL (in bps) in btrt box. If 0, removes btrt box
stz2: S use compact size table (for low-bitrates)
bitdepth (int): set bit depth to VAL for imported video content (default is 24)
colr (string): S set color profile for imported video content. Value is formatted as:

• nclc,p,t,m: with p colour primary (int or string), t transfer characteristics (int or string) and m matrix coef (int or string), cf -h cicp
• nclx,p,t,m,r: same as nclx with r full range flag (yes, on or no, off)
• prof,path: with path indicating the file containing the ICC color profile
• rICC,path: with path indicating the file containing the restricted ICC color profile
• 'none': removes color info

hdr (string): S set HDR info on track (see -hdr ), 'none' removes HDR info
dvp,-dv-profile (string): S set the Dolby Vision profile on imported track

• Profile is an integer, or none to remove DV signaling
• Profile can be suffixed with compatibility ID, e.g. 5.hdr10
• Allowed compatibility ID are none, hdr10, bt709, hlg709, hlg2100, bt2020, brd, or integer value as per DV spec
• Profile can be prefixed with 'f' to force DV codec type signaling, e.g. f8.2

fullrange (string): S force the video fullrange type in VUI for the AVC|H264 content (value yes, on or no, off)
videofmt (string): S force the video format in VUI for AVC|H264 and HEVC content, value can be component, pal, ntsc, secam, mac, undef
colorprim (string): S force the colour primaries in VUI for AVC|H264 and HEVC (int or string, cf -h cicp)
colortfc (string): S force transfer characteristics in VUI for AVC|H264 and HEVC (int or string, cf -h cicp)
colormx (string): S force the matrix coefficients in VUI for the AVC|H264 and HEVC content (int or string, cf -h cicp)
tc (string): S inject a single QT timecode. Value is formatted as:

• [d]FPS[/FPS_den],h,m,s,f[,framespertick]: optional drop flag, framerate (integer or fractional), hours, minutes, seconds and frame number
• : d is an optional flag used to indicate that the counter is in drop-frame format
• : the framespertick is optional and defaults to round(framerate); it indicates the number of frames per counter tick

edits (string): S override edit list, same syntax as -edits
lastsampdur (string): S set duration of the last sample. Value is formatted as:

• no value: use the previous sample duration
• integer: indicate the duration in milliseconds
• N/D: indicate the duration as fractional second

ID (int): S set target ID

• a value of 0 (default) will try to keep source track ID
• a value of -1 will ignore source track ID
• other value will try to set track ID to this value if no other track with same ID is present

tkgp (string): S assign track group to track. Value is formatted as TYPE,N with TYPE the track group type (4CC) and N the track group ID. A negative ID removes from track group ID -N
tkidx (string): S set track position in track list, 1 being first track in file
stats,-fstat: C print filter session stats after import
graph,-fgraph: C print filter session graph after import
sopt:[OPTS]: set OPTS as additional arguments to source filter. OPTS can be any usual filter argument, see filter doc gpac -h doc
dopt:[OPTS]: X set OPTS as additional arguments to destination filter. OPTS can be any usual filter argument, see filter doc gpac -h doc
@f1[:args][@fN:args]: set a filter chain to insert before the multiplexer. Each filter in the chain is formatted as a regular filter, see filter doc gpac -h doc. A @@ separator starts a new chain (see DASH help). The last filter in each chain shall not have any ID specified

Note: sopt, dopt and @f must be placed after all other options.

Global import options

-add (string): add given file tracks to file. Multiple inputs can be specified using +, e.g. -add url1+url2
-cat (string): concatenate given file samples to file, creating tracks if needed. Multiple inputs can be specified using +, e.g/ -cat url1+url2.
Note: This aligns initial timestamp of the file to be concatenated
-catx (string): same as -cat but new tracks can be imported before concatenation by specifying +ADD_COMMAND where ADD_COMMAND is a regular -add syntax
-catpl (string): concatenate files listed in the given playlist file (one file per line, lines starting with # are comments).
Note: Each listed file is concatenated as if called with -cat
-unalign-cat: do not attempt to align timestamps of samples in-between tracks
-force-cat: skip media configuration check when concatenating file.

Warning: THIS MAY BREAK THE CONCATENATED TRACK(S)

-keep-sys: keep all MPEG-4 Systems info when using -add and -cat (only used when adding IsoMedia files)
-dref: keep media data in original file using data referencing. The resulting file only contains the meta-data of the presentation (frame sizes, timing, etc...) and references media data in the original file. This is extremely useful when developing content, since importing and storage of the MP4 file is much faster and the resulting file much smaller.
Note: Data referencing may fail on some files because it requires the framed data (e.g. an IsoMedia sample) to be continuous in the original file, which is not always the case depending on the original interleaving or bitstream format (AVC or HEVC cannot use this option)
-no-drop,-nodrop: force constant FPS when importing AVI video
-packed: force packed bitstream when importing raw MPEG-4 part 2 Advanced Simple Profile
-sbr: backward compatible signaling of AAC-SBR
-sbrx: non-backward compatible signaling of AAC-SBR
-ps: backward compatible signaling of AAC-PS
-psx: non-backward compatible signaling of AAC-PS
-ovsbr: oversample SBR import (SBR AAC, PS AAC and oversampled SBR cannot be detected at import time)
-fps (string): force frame rate for video and SUB subtitles import to the given value, expressed as a number, as TS-inc or TS/inc.
Note: For raw H263 import, default FPS is 15, otherwise 25. This is accepted for ISOBMFF import but :rescale option should be preferred
-mpeg4: force MPEG-4 sample descriptions when possible. For AAC, forces MPEG-4 AAC signaling even if MPEG-2
-agg (int): aggregate N audio frames in 1 sample (3GP media only, maximum value is 15)