Skip to content

mp4box import opts

jeanlf edited this page Nov 14, 2019 · 22 revisions

HOME » MP4Box » Media Import

Importing Options

File importing

Syntax is -add / -cat filename[#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, the following syntax is used:

  • -add inputFile#video: adds the first video track in inputFile.
  • -add inputFile#audio: adds the first audio track in inputFile.
  • -add inputFile#trackID=ID or -add inputFile#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.

By default all imports are performed sequentially, and final interleaving is done at the end; this however requires a temporary file holding input 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 muxer input scheduling (each execution might lead to a slightly different result).

  • Some muxing options (marked with * below) will be activated for all inputs (i.e. in this mode, it is not possible to import one AVC track with xps_inband and another without).
  • Some muxing options (marked as ! below) cannot be used in this mode as they require temporary storage for file edition.
  • Usage of -cat is possible in this mode, but concatenated sources will not be interleaved in the output . If you wish to perforom more complex cat/add operations without temp file, use the gpac application.

MP4Box can import a desired amount of the input file rather than the whole file. To do this, use the syntax -add inputFile:dur=N, where N is the number of seconds you wish to import from input. MP4Box cannot start importing from a random point in the input, it always import from the begining.
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 likelly not be useful (default SRT/SUB importing uses default serif font, fontSize 18 and display size 400x60). Check TTXT doc for more details.

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 par stream, set per-file options using the syntax -add stream[:opt1:...:optN].

Allowed per-file options:

  • #video, #audio: base import for most AV files
  • #trackID=ID: track import for IsoMedia and other files
  • #pid=ID: stream import from MPEG-2 TS
  • :dur=D: * import only the first D seconds
  • :lang=LAN: set imported media language code
  • :delay=delay_ms: set imported media initial delay in ms
  • :par=PAR: set visual pixel aspect ratio (see -par )
  • :clap=CLAP: set visual clean aperture (see -clap )
  • :mx=MX: sets track matrix (see -mx )
  • :name=NAME: set track handler name
  • :ext=EXT: override file extension when importing
  • :hdlr=code: set track handler type to the given code point (4CC)
  • :disable: imported track(s) will be disabled
  • :group=G: add the track as part of the G alternate group. If G is 0, the first available GroupID will be picked.
  • :fps=VAL: same as -fps
  • :rap: ! import only RAP samples
  • :refs: ! import only reference pictures
  • :trailing: keep trailing 0-bytes in AVC/HEVC samples
  • :agg=VAL: * same as -agg
  • :dref: * same as -dref
  • :keep_refs: keeps track reference when importing a single track
  • :nodrop: same as -nodrop
  • :packed: * same as -packed
  • :sbr: same as -sbr
  • :sbrx: same as -sbrx
  • :ovsbr: same as -ovsbr
  • :ps: same as -ps
  • :psx: same as -psx
  • :asemode=MODE: * set the mode to create the AudioSampleEntry
    • 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)
  • :audio_roll=N: add a roll sample group with roll_distance N
  • :mpeg4: * 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=MODE: ! set SVC/LHVC import mode
    • 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: ! set HEVC/LHVC temporal sublayer import mode
    • 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: add default HEIF ccst box to visual sample entry
  • :forcesync: force non IDR samples with I slices to be marked as sync points (AVC GDR)

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

  • :xps_inband: * set xPS inband for AVC/H264 and HEVC (for reverse operation, re-import from raw media)
  • :xps_inbandx: * same as xps_inband and also keep first xPS in sample desciption
  • :au_delim: keep AU delimiter NAL units in the imported file
  • :max_lid=N: set HEVC max layer ID to be imported to N (by default imports all layers)
  • :max_tid=N: set HEVC max temporal ID to be imported to N (by default imports all temporal sublayers)
  • :tiles: add HEVC tiles signaling and NALU maps without splitting the tiles into different tile tracks
  • :split_tiles: ! split HEVC tiles into different tile tracks, one tile (or all tiles of one slice) per track.
  • :negctts: use negative CTS-DTS offsets (ISO4 brand)
  • :chap: specify the track is a chapter track
  • :chapter=NAME: add a single chapter (old nero format) with given name lasting the entire file
  • :chapfile=file: adds a chapter file (old nero format)
  • :layout=WxHxXxY: specify the track layout
    • 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
  • :rescale=TS: force media timescale to TS !! changes the media duration
  • :timescale=TS: set imported media timescale to TS.
  • :moovts=TS: set movie timescale to TS. A negative value picks the media timescale of the first track imported.
  • :noedit: * do not set edit list when importing B-frames video tracks
  • :rvc=FILENAME: set RVC configuration for the media
  • :fmt=FORMAT: override format detection with given format (cf BT/XMTA doc)
  • :profile=INT: override AVC profile
  • :level=INT: override AVC level
  • :novpsext: remove VPS extensions from HEVC VPS
  • :keepav1t: keep AV1 temporal delimiter OBU in samples, might help if source file had losses
  • :font=name: specify font name for text import (default Serif)
  • :size=s: specify font size for text import (default 18)
  • :text_layout=WxHxXxY: specify the track text layout
    • 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=ang: complementary angle below which 2 lines are merged, 0 means no flattening
  • :kind=schemeURI=value: set kind for the track
  • :txtflags=flags: set display flags (hexa number) of text track
  • :txtflags+=flags: add display flags (hexa number) to text track
  • :txtflags-=flags: remove display flags (hexa number) from text track
  • :rate=VAL: force average rate and max rate to VAL (in bps) in btrt box. If 0, removes btrt box
  • :stz2: use compact size table (for low-bitrates)
  • :bitdepth=VAL: set bit depth to VAL for imported video content (default is 24)
  • :colr=OPT: set color profile for imported video content (see ISO/IEC 23001-8). OPT is formatted as:
    • nclc,p,t,m: with p colour primary, t transfer characteristics and m matrix coef
    • nclx,p,t,m,r: same as nclx with r full range flag
    • 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
  • :tc=VAL: inject a single QT timecode. VAL is formated as:
    • [d]FPS[/FPS_den],h,m,s,f[,framespertick]: optionnal drop flag, framerate (integer or fractionnal), 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
  • :fstat: print filter session stats after import
  • :fgraph: print filter session graph after import
  • :sopt:[OPTS]: set OPTS as additionnal arguments to source filter. OPTS can be any usual filter argument, see filter doc gpac -h doc
  • :dopt:[OPTS]: * set OPTS as additionnal 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 muxer. Each filter in the chain is formatted as a regular filter, see filter doc gpac -h doc. If several filters are set, they will be chained in the given order. The last filter shall not have any Filter 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 +(eg -add url1+url2)
-cat (string): concatenate given file samples to file, creating tracks if needed. Multiple inputs can be specified using +(eg -cat url1+url2).
Note: 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 (string): do not attempt to align timestamps of samples inbetween tracks
-force-cat (string): skip media configuration check when concatenating file.


-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 developping 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 (eg 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: 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, default: 25): force frame rate for video and SUB subtitles import to the given value, expressed as a number or as timescale-increment.
Note: For raw H263 import, default FPS is 15, otherwise 25

Warning: This is ignored for ISOBMFF import, use :rescale option for that

-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).
Note: Maximum value is 15

Clone this wiki locally
You can’t perform that action at this time.