MP4Box(1)

📦

version 26.02.0 · 5 versions

26.02.0 · fedora 44 (latest)
26.07.0-unstable-2026-08 · nixos 26.05, nixpkgs unstable
2.0.0 · ubuntu jammy
2.4.0 · epel 10, epel 9, fedora 43
2.2.1 · ubuntu noble

💖 MP4Box(1) 💖

okay bestie, buckle UP — this is the manual page for MP4Box, straight out of the GPAC fam. It's MP4Box(1), which means section 1 of the manual, and yes it's the command-line one, the one you actually run in your terminal like the main character you are. 🎀

✨ NAME ✨

MP4Box — the GPAC command-line media packager 🦋

Like… it packs media. From the command line. That's the whole vibe. GPAC's little terminal bestie. 💅

✨ SYNOPSIS ✨

MP4Box [options] [file] [options]

Read it again, carefully, because the order is doing a thing:

MP4Box — the program itself, iconic, no notes 👑
[options] — options go first, because sure
[file] — then a file, if you feel like it
[options] — and then MORE OPTIONS after the file, because why would it be simple bestie 😭

The square brackets mean optional, so technically MP4Box alone is valid syntax, which is very "I showed up to class with no supplies" energy. But fr fr, the options-after-the-file thing is real and you will absolutely use it, so don't come for me. 💀

✨ General Options ✨

okay bestie, so MP4Box is literally a multimedia packager with a vast number of functionalities: conversion, splitting, hinting, dumping, DASH-ing, encryption, transcoding and others. It's giving Swiss Army knife but for media. 🎀 MP4Box provides a large set of options, classified by categories (see -h). These options do not follow any particular ordering. No cap.

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 metadata (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 📅

✨ Extracting Options ✨

Okay so MP4Box can absolutely be used to extract media tracks from MP4 files 💅 bestie that's its whole thing. BUT — and this is the important part — if you need to convert those tracks after you pull them out, you gotta go check the filters doc instead. Different vibe, different doc. 🦋

Options, bb:

-raw (string) — extract the given track in raw format when that's supported. Wanna name your own output file? Use tkID:output=FileName and it's yours. 🎀
-raws (string) — extract each sample of the given track to its own file. Use tkID:N to grab just the Nth sample. one sample, one file, no cap. ✨
-nhnt (int) — extract the given track into NHNT format.
-nhml (string) — extract the given track into NHML format. Add tkID:full if you want the full NHML dump with literally every packet property in it. 💖
-webvtt-raw (string) — extract the given track as raw media in WebVTT as metadata. Use tkID:embedded to shove the media data right into the WebVTT file. 🌸
-single (int) — extract the given track into a brand new mp4 file. glow up ✨
-six (int) — extract the given track as raw media in experimental XML streaming instructions. yes it says experimental. we move anyway. 🙈
-mux (string) — multiplex the input file to the destination you give it. 🎬
-qcp (int) — same as -raw but it defaults to a QCP file for EVRC/SMV.
-saf — multiplex the input file to SAF multiplex.
-dvbhdemux — demultiplex a DVB-H file into IP Datagrams that get sent on the network. it's giving networking era 🌈
-raw-layer (int) — same as -raw but it skips the SVC/MVC/LHVC extractors while extracting.
-diod — extract the file IOD in raw format. iconic.
-mpd (string) — convert the given HLS or smooth manifest (local or remote http, both fine) to MPD — options -url-template and -segment-timelinecan be used in this mode.

Note: this only provides basic conversion. For more advanced conversions, go see gpac -h dasher. 👑

Warning: this is not compatible with other DASH options and it does not convert associated segments. fr fr, heads up. 💀

🌈 DASH Options 🌈

Also see, bestie:

the dasher gpac -h dasher filter documentation 📚
[[DASH wiki|DASH-intro]] ✨

📥 Specifying input files 📥

Input media files to dash can use the following modifiers — think of them as little accessories you can clip onto your filename 💅:

#trackID=N: only use the track ID N from the source file
#N: only use the track ID N from the source file (this one's mapped to -tkid)
#video: only use the first video track from the source file
#audio: only use the first audio track from the source file
#Prop=Value: add PID filtering using the same syntax as SID fragments (cf gpac -h doc)
:id=NAME: set the representation ID to NAME. The reserved value NULL disables the representation ID for multiplexed inputs. If you don't set it, a default value gets computed and all selected tracks from the source end up in the same output multiplex.
:dur=VALUE: process VALUE seconds (fraction) from the media. If VALUE is longer than the media duration, the last sample duration gets extended.
:period=NAME: set the representation's period to NAME. You can use multiple periods. Periods show up in the MPD in the exact same order you specified them with this option.
:BaseURL=NAME: set the BaseURL. Set it multiple times for multiple BaseURLs.

Warning: this does not modify the generated files location (see segment template). 🙈

:bandwidth=VALUE: set the representation's bandwidth to the value you give it
:pdur=VALUE: sets the duration of the associated period to VALUE seconds (fraction) (it's an alias for period_duration:VALUE). This only gets used when no input media is specified (remote period insertion), e.g. :period=X:xlink=Z:pdur=Y
:ddur=VALUE: override the target DASH segment duration to VALUE seconds (fraction) for this input (alias for duration:VALUE)
:xlink=VALUE: set the xlink value for the period containing this element. Only the xlink declared on the first rep of a period will be used.
:asID=VALUE: set the AdaptationSet ID to VALUE (unsigned int)
:role=VALUE: set the role of this representation (cf DASH spec). Media with different roles belong to different adaptation sets.
:desc_p=VALUE: add a descriptor at the Period level.
:desc_as=VALUE: add a descriptor at the AdaptationSet level. Two input files with different values will land in different AdaptationSet elements.
:desc_as_c=VALUE: add a descriptor at the AdaptationSet level. The value is ignored while creating AdaptationSet elements.
:desc_rep=VALUE: add a descriptor at the Representation level. The value is ignored while creating AdaptationSet elements.
:sscale: force the movie timescale to match the media timescale of the first track in the segment.
:trackID=N: same as setting the fragment #trackID=
@f1[:args][@fN:args][@@fK:args]: set a filter chain to insert between the source and the dasher. Each filter in the chain is formatted as a regular filter, see the filter doc gpac -h doc. If you set several filters:
- they'll be chained in the order you gave them if they're separated by a single @
- a new filter chain gets created if they're separated by a double @@. In this case, no representation ID is assigned to the source.

Example:

source.mp4:@c=avc:b=1M@@c=avc:b=500k

This will load a filter chain with two encoders connected to the source and to the dasher. 🎀

Example:

source.mp4:@c=avc:b=1M@c=avc:b=500k

This will load a filter chain with the second encoder connected to the output of the first (!!). yes that's a real exclamation, we're all fine 💀

Note: @f must be placed after all other options. like, after. all of them. 🫶

Note: Descriptors value must be a properly formatted XML element(s), and the value is not checked. The syntax can use file@FILENAME to load content from a file. 🌸

✨ Options ✨

bestie this is the DASH options motherlode 💅 grab a boba, we're going through every single one, no skips, no cap.

-dash number — creates a DASH out of your input files, where number is the segment duration in ms (for the onDemand profile it's the subsegment duration instead) 🎬
-dash-live number — generates a live DASH session using number as the segment duration in ms. bonus mode: doing -dash-live=F also writes the live context out to F. MP4Box just stays in the live session until you press q or something fatal happens 💀
-ddbg-live number — literally the same as -dash-live but with no time regulation, purely for debug purposes 🐛
-frag number — sets the fragment duration in ms. if you don't set it, it defaults to the DASH duration (so one fragment per segment, cute) ✨
-out string — names your output MPD file, periodt 📝
-profile, -dash-profile string — picks the target DASH profile and auto-sets default options so you actually conform to it. default is full in static mode, live in dynamic mode (and yes, the old syntax using :live instead of .live as the separator is still possible, legacy icon 👑). the defined values are onDemand, live, main, simple, full, hbbtv1.5.live, dashavc264.live, dashavc264.onDemand, dashif.ll
-profile-ext string — sets a list of profile extensions, the way DASH-IF and DVB use them. the string gets colon-concatenated with whatever profile you're using 🔗
-rap — makes sure segments begin with random access points. heads up tho: segment durations might vary depending on the source encoding, it's giving chaotic but valid 🌈
-frag-rap — same vibe but for all the fragments: every fragment begins with a random access point (durations might vary depending on the source encoding) 🎯
-segment-name string — sets the segment name for the segments you generate. if you don't set it (default), segments get concatenated in the output file — except in the live profile where it's dash_%%s. the supported replacement strings are:
- $Number[%%0Nd]$ gets replaced by the segment number, possibly prefixed with 0
- $RepresentationID$ gets replaced by representation name
- $Time$ gets replaced by segment start time
- $Bandwidth$ gets replaced by representation bandwidth
- $Init=NAME$ gets replaced by NAME for init segment, ignored otherwise
- $Index=NAME$ gets replaced by NAME for index segments, ignored otherwise
- $Path=PATH$ gets replaced by PATH when creating segments, ignored otherwise
- $SubNumber[%%0Nd]$ gets replaced by the segment subnumber in segment sequences, possibly prefixed with 0
- $Segment=NAME$ gets replaced by NAME for media segments, ignored for init segments
-segment-ext string, default: m4s — sets the segment extension. null means no extension at all 🚫
-init-segment-ext string, default: mp4 — sets the segment extension for init, index and bitstream switching segments. null means no extension 🙅
-segment-timeline — uses SegmentTimeline when generating segments 📊
-segment-marker string — adds a box of the given type (a 4CC) at the end of each DASH segment 🏷️
-insert-utc — inserts a UTC clock at the beginning of each ISOBMF segment ⏰
-base-url string — sets the Base url at MPD level. can be used several times.

Warning: this does not modify generated files location, so don't let it fool you bestie 🫠

-mpd-title string — sets the MPD title 📛
-mpd-source string — sets the MPD source 📚
-mpd-info-url string — sets the MPD info url 🔗
-cprt string — adds a copyright string to the MPD ©️
-dash-ctx string — store/restore DASH timing from the file you point at 💾
-dynamic — uses the dynamic MPD type instead of static 🌀
-last-dynamic — same as -dynamic but it closes the period (inserts the lmsg brand if needed and updates the duration) 🔒
-mpd-duration number — sets the duration in seconds of a live session (if it's 0, you gotta use -mpd-refresh) ⏳
-mpd-refresh number — sets the MPD update time in seconds 🔄
-time-shift int — sets the MPD time shift buffer depth in seconds. -1 keeps all the files. default is 0 🕰️
-subdur number — sets the max duration in ms of the input file to be dashed in LIVE or context mode. this does not change the segment duration, it just stops dashing once the segments produced exceed that duration. if there aren't enough samples to finish a segment, data is looped — unless -no-loop is used, which triggers a period end 🔁
-run-for int — runs the dash-live session for the given ms, then dips out 🏃‍♀️
-min-buffer int — sets the MPD min buffer time in ms 🧺
-ast-offset int — sets the MPD AvailabilityStartTime offset in ms if positive, or the availabilityTimeOffset of each representation if negative ⚖️
-dash-scale int — says the timing for -dash, -dash-live, -subdur and -frag is expressed in the given timescale (units per seconds) rather than ms 📏
-mem-frags — fragmentation happens in memory rather than on disk before flushing to disk 🧠
-pssh int — sets the pssh store mode:
- v: initial movie
- f: movie fragments
- m: MPD
- mv, vm: in initial movie and MPD
- mf, fm: in movie fragments and MPD
- n: remove PSSH from MPD, initial movie and movie fragments
-sample-groups-traf — stores sample group descriptions in traf (duplicated for each traf). if not set, sample group descriptions go in the initial movie 📦
-mvex-after-traks — stores the mvex box after the trak boxes within the moov box. if not set, mvex goes before 🗂️
-sdtp-traf int — uses the sdtp box in traf (Smooth-like):
- no: do not use sdtp
- sdtp: use the sdtp box to indicate sample dependencies and do not write info in trun sample flags
- both: use the sdtp box to indicate sample dependencies and also write info in trun sample flags
-no-cache — disables the file cache for dash inputs 🚫
-no-loop — disables looping content in live mode and uses period switch instead 🔄
-hlsc — inserts UTC in variant playlists for live HLS ⏱️
-bound — segmentation will always try to split before or at, but never after, the segment boundary ✂️
-closest — segmentation will use the closest frame to the segment boundary (before or after) 🎯
-subsegs-per-sidx, -frags-per-sidx int — sets the number of subsegments to be written in each SIDX box:
- 0: a single SIDX box is used per segment
- -1: no SIDX box is used
-ssix — enables SubsegmentIndexBox describing 2 ranges, first one from moof to end of first I-frame, second one unmapped. this does not work with daisy chaining mode enabled ⚠️
-url-template — uses SegmentTemplate instead of explicit sources in segments. ignored if segments are stored in the output file 🔗
-url-template-sim — uses SegmentTemplate simulation while converting HLS to MPD 🧪
-daisy-chain — uses daisy-chain SIDX instead of hierarchical. ignored if frags/sidx is 0 ⛓️
-single-segment — uses a single segment for the whole file (OnDemand profile) 1️⃣
-single-file — uses a single file for the whole file (default) 📄
-bs-switching string, default: inband, values: inband|merge|multi|no|single — sets the bitstream switching mode:
- inband: use inband param set and a single init segment
- merge: try to merge param sets in a single sample description, fallback to no
- multi: use several sample description, one per quality
- no: use one init segment per quality
- pps: use out of band VPS,SPS,DCI, inband for PPS,APS and a single init segment
- single: to test with single input
-moof-sn int — sets the sequence number of the first moof to the given value 🔢
-tfdt int — sets the TFDT of the first traf to the given value in SCALE units (cf -dash-scale) ⏲️
-no-frags-default — disables default fragments flags in trex (required by some dash-if profiles and CMAF/smooth streaming compatibility) 🚧
-single-traf — uses a single track fragment per moof (smooth streaming and derived specs may require this) 1️⃣
-tfdt-traf — uses a tfdt per track fragment (when -single-traf is used) ⏲️
-dash-ts-prog int — program_number to be considered in case of an MPTS input file 📺
-frag-rt — when using fragments in live mode, flush fragments according to their timing ⏱️
-cp-location string — sets the ContentProtection element location:
- as: sets ContentProtection in the AdaptationSet element
- rep: sets ContentProtection in the Representation element
- both: sets ContentProtection in both elements
-start-date string — for live mode, sets the start date (as xs:date, e.g. YYYY-MM-DDTHH:MM:SSZ). default is current UTC.

Warning: do not use with multiple periods, nor when DASH duration is not a multiple of GOP size 😭

-cues string — ignores dash duration and segments according to cue times in the given XML file (see tests/media/dash_cues for examples) 🎯
-strict-cues — throws an error if something is wrong while parsing cues or applying cue-based segmentation 💥
-merge-last-seg — merges the last segment if it's shorter than half the target duration 🤝

🌈 File splitting ✂️

okay bestie, this is the glow-up section — MP4Box can split your input files by size, by duration, or straight-up extract a given part of the file into new IsoMedia file(s). 💅

The catch? This needs at most one track in the input file to have non random-access points (so like, typically one video track at most). Fr fr.

Splitting will ignore all MPEG-4 Systems tracks and hint tracks, but it will try to split private media tracks. She's inclusive like that. 🫶

Your input file also needs enough random access points to actually be splittable. If not… 😭 you will have to re-encode the content. No cap.

Oh and you can add media to a file and split it in the same pass! Iconic. But heads up: in this case, the destination file (the one which would be obtained without splitting) will not be stored. It's giving "trust the process".

Time ranges are specified as follows:

S-E — S start and E end times, formatted as HH:MM:SS.ms, MM:SS.ms or time in seconds (int, double, fraction)
S:E — S start time and E end times in seconds (int, double, fraction). If E is prefixed with D, this sets E = S + time
S:end or S:end-N — S start time in seconds (int, double), N number of seconds (int, double) before the end

MP4Box splitting runs a filter session using the reframer filter as follows:

splitrange option of the reframer is always set
source is demultiplexed with alltk option set
start and end ranges are passed to xs and xe options of the reframer
for -splitz, options xadjust and xround=after are enforced
for -splitg, options xadjust and xround=before are enforced
for -splitf, option xround=seek is enforced and propbe_refset if not specified at prompt
for -splitx, option xround=closest and propbe_ref are enforced if not specified at prompt

The default output storage mode is to full interleave and will require a temp file for each output. 🗂️ This behavior can be modified using -flat, -newfs, -inter and -frag.

The output file name(s) can be specified using -out and templates (e.g. -out split$num%04d$.mp4 produces split0001.mp4, split0002.mp4, ...). ✨

Multiple time ranges can be specified as a comma-separated list for -splitx, -splitz and -splitg. Slay.

-split (string) — split in files of given max duration (float number) in seconds. A trailing unit can be specified:
- M, m: duration is in minutes
- H, h: size is in hours
-split-rap, -splitr — split in files at each new RAP 🎯
-split-size, -splits (string) — split in files of given max size (integer number) in kilobytes. A trailing unit can be specified:
- M, m: size is in megabytes
- G, g: size is in gigabytes
-split-chunk, -splitx (string) — extract the specified time range as follows:
- the start time is moved to the RAP sample closest to the specified start time
- the end time is kept as requested
-splitz (string) — extract the specified time range so that ranges A:B and B:C share exactly the same boundary B:
- the start time is moved to the RAP sample at or after the specified start time
- the end time is moved to the frame preceding the RAP sample at or following the specified end time
-splitg (string) — extract the specified time range as follows:
- the start time is moved to the RAP sample at or before the specified start time
- the end time is moved to the frame preceding the RAP sample at or following the specified end time
-splitf (string) — extract the specified time range and insert edits such that the extracted output is exactly the specified range 🎀

🌸 File Dumping 🌸

MP4Box has many dump functionalities, from simple track listing to more complete reporting of special tracks. She contains multitudes, bestie. 💖

Options:

-std — dump/write to stdout and assume stdout is opened in binary mode
-stdb — dump/write to stdout and try to reopen stdout in binary mode
-tracks — print the number of tracks on stdout
-info (string) — print movie info (no parameter) or track extended info with specified ID
-infon (string) — print track info for given track number, 1 being the first track in the file
-infox — print movie and track extended info (same as -info N for each track)
-diso, -dmp4 — dump IsoMedia file boxes in XML output
-dxml — dump IsoMedia file boxes and known track samples in XML output
-disox — dump IsoMedia file boxes except sample tables in XML output
-keep-comp — do not decompress boxes when dumping
-keep-ods — do not translate ISOM ODs and ESDs tags (debug purpose only)
-bt — dump scene to BT format
-xmt — dump scene to XMT format
-wrl — dump scene to VRML format
-x3d — dump scene to X3D XML format
-x3dv — dump scene to X3D VRML format
-lsr — dump scene to LASeR XML (XSR) format
-svg — dump scene to SVG
-drtp — dump rtp hint samples structure to XML output
-dts — print sample timing, size and position in file to text output
-dtsx — same as -dts but does not print offset
-dtsc — same as -dts but analyses each sample for duplicated dts/cts (slow !) 🐌
-dtsxc — same as -dtsc but does not print offset (slow !) 🐌
-dnal (int) — print NAL sample info of given track
-dnalc (int) — print NAL sample info of given track, adding CRC for each nal
-dnald (int) — print NAL sample info of given track without DTS and CTS info
-dnalx (int) — print NAL sample info of given track without DTS and CTS info and adding CRC for each nal
-sdp — dump SDP description of hinted file
-dsap (int) — dump DASH SAP cues (see -cues) for a given track
-dsaps (int) — same as -dsap but only print sample number
-dsapc (int) — same as -dsap but only print CTS
-dsapd (int) — same as -dsap but only print DTS
-dsapp (int) — same as -dsap but only print presentation time
-dcr — dump ISMACryp samples structure to XML output
-dchunk — dump chunk info
-dump-cover — extract cover art 🎨
-dump-chap — extract chapter file as TTXT format
-dump-chap-ogg — extract chapter file as OGG format
-dump-chap-zoom — extract chapter file as zoom format
-dump-udta [tkID:]4cc — extract user data for the given 4CC. If tkID is given, dumps from UDTA of the given track ID, otherwise moov is used
-mergevtt — merge vtt cues while dumping
-ttxt (int) — convert input subtitle to GPAC TTXT format if no parameter. Otherwise, dump given text track to GPAC TTXT format
-srt (int) — convert input subtitle to SRT format if no parameter. Otherwise, dump given text track to SRT format
-nstat — generate node/field statistics for scene
-nstats — generate node/field statistics per Access Unit
-nstatx — generate node/field statistics for scene after each AU
-hash — generate SHA-1 Hash of the input file 🔐
-comp (string) — replace with compressed version all top level box types given as parameter, formatted as orig_4cc_1=comp_4cc_1[,orig_4cc_2=comp_4cc_2]
-topcount (string) — print to stdout the number of top-level boxes matching box types given as parameter, formatted as 4cc_1,4cc_2N
-topsize (string) — print to stdout the number of bytes of top-level boxes matching types given as parameter, formatted as 4cc_1,4cc_2N or all for all boxes
-bin — convert input XML file using NHML bitstream syntax to binary
-mpd-rip — fetch MPD and segment to disk
-udp-write (string, default: IP[:port]) — write input name to UDP (default port 2345)
-raw-cat (string) — raw concatenation of given file with input file
-wget (string) — fetch resource from http(s) URL
-dm2ts — dump timing of an input MPEG-2 TS stream sample timing
-check-xml — check XML output format for -dnal*, -diso* and -dxml options
-fuzz-chk — open file without probing and exit (for fuzz tests)

💜 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. iykyk. 👑

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 bestie 🎀 When you're importing SRT or SUB files, MP4Box is gonna pick default layout options so the subtitles show up at the bottom of the video. And like… you SHOULD NOT import those files before any video track is already in the destination file, otherwise the results are probably gonna be straight-up useless (default SRT/SUB importing uses the default serif font, fontSize 18 and display size 400x60). Want the full tea? Go check the TTXT doc. ✨

When you import several tracks/sources in one pass, all the options get applied if they're relevant to each source. These options are set for all the imported streams. If you need them per stream instead, set per-file options with the syntax -add stream[:opt1:...:optN]. 💅

The import file name can be set to empty or self, which means the import options should be applied to the destination file track(s). For example:

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

This applies moovts and noedit to all tracks in src.mp4. Another one:

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

This applies moovts and noedit to the track with ID=2 in src.mp4. Only per-file options marked with a S work in this mode, just so you know. 🙈

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

When importing as an external track, only options marked as E can be used.

✨ Allowed per-file options ✨

dur (int) — XCE — import only the specified duration from the media. The value can be:
- a positive float: that's the duration in seconds
- a fraction: that's the duration as a NUM/DEN fraction
- a negative integer: that's the duration in number of coded frames
start (number) — C — target start time in the source media. Heads up, it may not be supported depending on the source 😭
lang (string) — SE — set the imported media language code
delay (int) — SE — set the imported media initial delay (>0) or initial skip (<0), in ms or as fractional seconds (N/D)
par (string) — S — set the visual pixel aspect ratio (peep -par)
clap (string) — S — set the visual clean aperture (peep -clap)
mx (string) — SE — set the track matrix (peep -mx)
name (string) — S — set the track handler name
ext (string) — override the file extension when importing
hdlr (string) — S — set the track handler type to the given code point (4CC)
stype (string) — S — force the sample description type to the given code point (4CC). Ngl this may likely break the file 💀
tkhd (int) — SE — set the track header flags, either as a hex integer or as a comma-separated list of enable, movie, preview, size_ar keywords (use tkhd+=FLAGS to add and tkhd-=FLAGS to remove)
disable — SE — disable the imported track(s); use disable=no to force-enable a disabled track
group (int) — SE — add the track as part of the G alternate group. If G is 0, the first available GroupID gets 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 -no-drop
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 used to create the AudioSampleEntry. The value can be:
- v0-bs: use MPEG AudioSampleEntry v0 and the channel count from the bitstream (even if it's greater than 2) — this is the default
- v0-2: use MPEG AudioSampleEntry v0 and force the channel count 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 it's greater than 2). This also triggers 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 the -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 the SVC/LHVC import mode. The 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 base goes 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 the HEVC/LHVC temporal sublayer import mode. The value can be:
- split: each sublayer is in its own track
- splitbase: all sublayers are merged in a track, and the HEVC base goes 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 a default HEIF ccst box to the visual sample entry
forcesync — SE — force non IDR samples with I slices (OpenGOP or GDR) to be marked as sync points

Warning: THE RESULTING FILE IS NOT COMPLIANT WITH THE SPEC — but it will fix seeking in most players, so… trade-offs, bestie 😭

xps_inband — XC — set xPS inband for AVC/H264 and HEVC (for the reverse operation, re-import from raw media)
xps_inbandx — XC — same as xps_inband and it also keeps the first xPS in the sample description
au_delim — keep AU delimiter NAL units in the imported file
max_lid (int) — set the HEVC max layer ID to be imported to N (by default it imports all layers)
max_tid (int) — set the HEVC max temporal ID to be imported to N (by default it 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 a positive offset on an existing track
chap — SE — specify that the track is a chapter track
chapter (string) — SE — add a single chapter (old nero format) with the given name lasting the entire file
chapfile (string) — SE — add a chapter file (old nero format)
layout (string) — SE — 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 is 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 the imported media timescale to TS
moovts (int) — SE — set the movie timescale to TS. A negative value picks the media timescale of the first track imported
noedit — XS — do not set an edit list when importing B-frames video tracks
rvc (string) — S — set the RVC configuration for the media
fmt (string) — override format detection with the given format — this disables data probing and forces the ext option on the source
profile (int) — S — override AVC profile. It's an integer value, or one of high444, high, extended, main, baseline
level (int) — S — override AVC level; if the value is < 6, it's interpreted as a decimal expression
compat (int) — S — force the profile compatibility flags for the H.264 content
novpsext — remove VPS extensions from the HEVC VPS
keepav1t — keep the AV1 temporal delimiter OBU in samples, might help if the source file had losses
dlba (string) — S — force DolbyAtmos mode for EAC3. The value can be:
- no: disable Atmos signaling
- auto: use Atmos signaling from the first sample
- N: force Atmos signaling using compatibility type index N
font (string) — specify the font name for text import (default Serif)
size (int) — specify the 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 is used
- if Y=-1: the layout gets moved to the bottom of the track area
- X and Y can be omitted: :layout=WxH
swf-global — all SWF defines are placed in the first scene replace rather than when needed
swf-no-ctrl — use a single stream for movie control and dictionary (this disables ActionScript)
swf-no-text — remove all SWF text
swf-no-font — remove all embedded SWF Fonts (local playback host fonts are used instead)
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) — SE — set the kind for the track as schemeURI=value
txtflags (int) — set the display flags (hexa number) of the 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 the btrt box. If it's 0, the btrt box gets removed
stz2 — S — use a compact size table (for low-bitrates)
bitdepth (int) — set bit depth to VAL for imported video content (default is 24)
colr (string) — S: set the color profile for your imported video content, bestie. The value has to be formatted like one of these:
- nclc,p,t,m: where p is colour primary (int or string), t is transfer characteristics (int or string) and m is 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: where path is the file containing the ICC color profile
- rICC,path: where path is the file containing the restricted ICC color profile
- 'none': removes color info
hdr (string) — S: set HDR info on a track (see .I -hdr), and 'none' removes HDR info ✨
dvp, -dv-profile (string) — S: set the Dolby Vision profile on your imported track. The deets:
- Profile is an integer, or none to remove DV signaling
- Profile can be suffixed with a compatibility ID, e.g. 5.hdr10
- Allowed compatibility ID are none, hdr10, bt709, hlg709, hlg2100, bt2020, brd, or an 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) — SE: 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) — SE: override edit list, same syntax as .I -edits
lastsampdur (string) — S: set the 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) — SE: 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) — SE: assign a track group to a 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) — SE: set track position in track list, 1 being first track in file
extk — CE: add track as external track
times (string) — SE: modify timestamps using the timestamp file specified in value. Timestamp file is formatted as:
- a line starting with # is a comment, in which timescale=V can be used to set timescale (1000 by default)
- empty lines are ignored
- one line per sample in decode order, formated as cts or dts cts
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 the source filter. OPTS can be any usual filter argument, see filter doc gpac -h doc
dopt:[OPTS] — X: set OPTS as additional arguments to the 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, bestie: sopt, dopt and @f must be placed after all other options. No sneaking them in the middle 💅

🌈 Global import options 🌈

-add (string) — add the given file's tracks to the file. Multiple inputs can be specified using +, e.g. -add url1+url2
-cat (string) — concatenate the given file's samples to the file, creating tracks if needed. Multiple inputs can be specified using +, e.g. -cat url1+url2.

Note: This aligns the initial timestamp of the file to be concatenated

-catx (string) — same as .I cat but new tracks can be imported before concatenation by specifying +ADD_COMMAND where ADD_COMMAND is a regular .I 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 the media configuration check when concatenating a file.

Warning: THIS MAY BREAK THE CONCATENATED TRACK(S) 😭 do not say I didn't warn you

-keep-sys — keep all MPEG-4 Systems info when using .I add and .I cat (only used when adding IsoMedia files)
-dref — keep media data in the 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)

👑 Hinting Options 👑

So like, IsoMedia hinting consists in creating special tracks in the file that contain transport protocol specific information and optionally multiplexing information. These tracks are then used by the server to create the actual packets being sent over the network — in other words they provide the server with hints on how to build packets, hence their names hint tracks 🎀

MP4Box supports creation of hint tracks for RTSP servers supporting these such as QuickTime Streaming Server, DarwinStreaming Server or 3GPP-compliant RTSP servers. Iconic behaviour, honestly.

Note: GPAC streaming tools rtp output and rtsp server do not use hint tracks, they use on-the-fly packetization from any media sources, not just MP4

✨ Options: ✨

-hint — hint the file for RTP/RTSP
-mtu (int, default: 1450) — specify RTP MTU (max size) in bytes (this includes 12 bytes RTP header)
-copy — copy media data to hint track rather than reference (speeds up server but takes much more space)
-multi [maxptime] — enable frame concatenation in RTP packets if possible (with max duration 100 ms or maxptime ms if given)
-rate (int, default: 90000) — specify rtp rate in Hz when no default for payload
-mpeg4 — force MPEG-4 generic payload whenever possible
-latm — force MPG4-LATM transport for AAC streams
-static — enable static RTP payload IDs whenever possible (by default, dynamic payloads are always used)
-add-sdp (string) — add the given SDP string to movie (string) or track (tkID:string), tkID being the track ID or the hint track ID
-no-offset — signal no random offset for sequence number and timestamp (support will depend on server)
-unhint — remove all hinting information from file
-group-single — put all tracks in a single hint group
-ocr — force all MPEG-4 streams to be synchronized (MPEG-4 Systems only)
-rap — signal random access points in RTP packets (MPEG-4 Systems)
-ts — signal AU Time Stamps in RTP packets (MPEG-4 Systems)
-size — signal AU size in RTP packets (MPEG-4 Systems)
-idx — signal AU sequence numbers in RTP packets (MPEG-4 Systems)
-iod — prevent systems tracks embedding in IOD (MPEG-4 Systems), not compatible with .I -isma

🎬 MPEG-4 Scene Encoding Options

✨ General considerations ✨

okay so here's the tea, bestie: MP4Box does encoding and decoding of BT, XMT, VRML and (partially) X3D formats into MPEG-4 BIFS, plus encoding and decoding of XSR and SVG into MPEG-4 LASeR. it's giving versatile 💅

Any media track you specify through a MuxInfo element gets imported into the resulting MP4 file. automatic. no cap.

want the full lore? go read https://wiki.gpac.io/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format and the related pages 🦋

🎠 Scene Random Access 🎠

MP4Box can encode BIFS or LASeR streams and insert random access points at a given frequency. this is SO useful when you're packaging content for broadcast, because users will not turn in the scene at the same time (rude of them, honestly). in MPEG-4 terminology this is called the scene carousel. iconic behavior.

🧩 BIFS Chunk Processing 🧩

The BIFS chunk encoding mode allows encoding single BIFS access units from an initial context and a set of commands. very demure, very mindful.

The generated AUs are raw BIFS (not SL-packetized), in files called FILE-ESID-AUIDX.bifs, with FILE the basename of the input file.

Commands with a timing of 0 in the input will modify the carousel version only (i.e. output context). Commands with a timing different from 0 in the input will generate new AUs. periodt.

Options:

-mp4 — specify input file is for BIFS/LASeR encoding
-def — encode DEF names in BIFS
-sync (int) — force BIFS sync sample generation every given time in ms (cannot be used with shadow or carousel)
-shadow (int) — force BIFS sync shadow sample generation every given time in ms (cannot be used with sync or carousel)
-carousel (int) — use BIFS carousel (cannot be used with sync or shadow)
-sclog — generate scene codec log file if available
-ms (string) — import tracks from the given file
-ctx-in (string) — specify initial context (MP4/BT/XMT) file for chunk processing. Input file must be a commands-only file
-ctx-out (string) — specify storage of updated context (MP4/BT/XMT) file for chunk processing, optional
-resolution (int) — resolution factor (-8 to 7, default 0) for LASeR encoding, and all coordinates are multiplied by 2^res before truncation (LASeR encoding)
-coord-bits (int) — number of bits used for encoding truncated coordinates (0 to 31, default 12) (LASeR encoding)
-scale-bits (int) — extra bits used for encoding truncated scales (0 to 4, default 0) (LASeR encoding)
-auto-quant (int) — resolution is given as if using resolution but coord-bits and scale-bits are inferred (LASeR encoding)
-global-quant (int) — resolution is given as if using resolution but the res is inferred (BIFS encoding)

🔐 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

🖼️ Meta and HEIF Options 🖼️

IsoMedia files can be used as generic meta-data containers — for example, storing XML information and sample images for a movie. The resulting file may not always contain a movie, as is the case with some HEIF files or MPEG-21 files. ngl that's a whole vibe shift and it's valid.

These information can be stored at the file root level (as is the case for HEIF/IFF and MPEG-21 file formats), or at the movie or track level for a regular movie.

-set-meta ABCD[:tk=tkID] — set meta box type, with ABCD the four char meta type (NULL or 0 to remove meta)
- tk not set: use root (file) meta
- tkID == 0: use moov meta
- tkID != 0: use meta of given track
-add-item (string) — add resource to meta, with parameter syntax file_path[:opt1:optN]
- file_path this or self: item is the file itself
- tk=tkID: meta location (file, moov, track)
- name=str: item name, none if not set
- type=itype: item 4cc type (not needed if mime is provided)
- mime=mtype: item mime type, none if not set
- encoding=enctype: item content-encoding type, none if not set
- id=ID: item ID (strictly positive integer)
- ref=4cc,id: reference of type 4cc (such as 'dimg', 'auxl', 'cdsc') to an other item (can be set multiple times)
- group=4cc,id: indicate the type 4cc (such as 'altr') and id of an entity group this item belongs to
- replace: replace existing item by new item
-add-image (string) — add the given file as HEIF image item, with parameter syntax file_path[:opt1:optN]. If filepath is omitted, source is the input MP4 file
- name, id, ref, group: see add-item
- primary: indicate that this item should be the primary item
- time=t[-e][/i]: use the next sync sample after time t (float, in sec, default 0). A negative time imports ALL intra frames as items
  - If e is set (float, in sec), import all sync samples between t and e
  - If i is set (float, in sec), sets time increment between samples to import
- split_tiles: for an HEVC tiled image, each tile is stored as a separate item
- image-size=wxh: force setting the image size and ignoring the bitstream info, used for grid, overlay and identity derived images also
- rotation=a: set the rotation angle for this image to 90*a degrees anti-clockwise
- mirror-axis=axis: set the mirror axis: vertical, horizontal
- clap=Wn,Wd,Hn,Hd,HOn,HOd,VOn,VOd: see track clap
- image-pasp=axb: force the aspect ratio of the image
- image-pixi=(a|a,b,c): force the bit depth (1 or 3 channels)
- hidden: indicate that this image item should be hidden
- icc_path: path to icc data to add as color info
- alpha: indicate that the image is an alpha image (should use ref=auxl also)
- depth: indicate that the image is a depth image (should use ref=auxl also)
- it=ID: indicate the item ID of the source item to import
- itp=ID: same as it= but copy over all properties of the source item
- tk=tkID: indicate the track ID of the source sample. If 0, uses the first video track in the file
- samp=N: indicate the sample number of the source sample
- ref: do not copy the data but refer to the final sample/item location, ignored if filepath is set
- agrid[=AR]: creates an automatic grid from the image items present in the file, in their declaration order. The grid will try to have AR aspect ratio if specified (float), or the aspect ratio of the source otherwise. The grid will be the primary item and all other images will be hidden
- av1_op_index: select the AV1 operating point to use via a1op box
- replace: replace existing image by new image, keeping props listed in keep_props
- keep_props=4CCs: coma-separated list of properties types to keep when replacing the image, e.g. keep_props=auxC
- auxt=URN: mark image as auxiliary using given URN
- auxd=FILE: use data from FILE as auxiliary extensions (cf auxC box)
- any other options will be passed as options to the media importer, see -add
-add-derived-image (string) — create an image grid, overlay or identity item, with parameter syntax :type=(grid|iovl|iden)[:opt1:optN]
- image-grid-size=rxc: set the number of rows and columns of the grid
- image-overlay-offsets=h,v[,h,v]*: set the horizontal and vertical offsets of the images in the overlay
- image-overlay-color=r,g,b,a: set the canvas color of the overlay [0-65535]
- any other options from add-image can be used
-rem-item,-rem-image item_ID[:tk=tkID] — remove resource from meta
-set-primary item_ID[:tk=tkID] — set item as primary for meta
-set-xml xml_file_path[:tk=tkID][:binary] — set meta XML data
-rem-xml [tk=tkID] — remove meta XML data
-dump-xml file_path[:tk=tkID] — dump meta XML to file
-dump-item item_ID[:tk=tkID][:path=fileName] — dump item to file
-package (string) — package input XML file into an ISO container, all media referenced except hyperlinks are added to file
-mgt (string) — package input XML file into an MPEG-U widget with ISO container, all files contained in the current folder are added to the widget package

🧚 SWF Importer Options 🧚

MP4Box can import simple Macromedia Flash files (".SWF") 🫶 throwback era fr fr.

You can specify a SWF input file with '-bt', '-xmt' and '-mp4' options

Options:

-global — all SWF defines are placed in first scene replace rather than when needed
-no-ctrl — use a single stream for movie control and dictionary (this will disable ActionScript)
-no-text — remove all SWF text
-no-font — remove all embedded SWF Fonts (local playback host fonts used)
-no-line — remove all lines from SWF shapes
-no-grad — remove all gradients from swf shapes
-quad — use quadratic bezier curves instead of cubic ones
-xlp — support for lines transparency and scalability
-ic2d — use indexed curve 2D hardcoded proto
-same-app — appearance nodes are reused
-flatten (number) — complementary angle below which 2 lines are merged, value 0 means no flattening

🏷️ Tagging support 🏷️

Tags get written as a colon-separated list, bestie, like this:

tag_name=tag_value[:tag2=val2]

Setting a tag with no value, or a value of NULL, removes the tag.
The special tag value clear (or reset) removes all the tags. poof 💨
The special tag value cust means it's a custom domain tag — and in that case the tag value must start with DOMAIN,MEAN,.

Example

-itags cust='com.apple.iTunes,iTunEXTC,My Tag Value'

The DOMAIN and/or NAME strings can be empty, no stress. Unsupported tags? You can add them using their four character code as the tag name, and the value will be assumed to be a string. And if your tag name is only 3 characters long, the prefix 0xA9 gets used to build the four character code. cute 🎀

You can also load tags from a text file with -itags filename. That file has to be in UTF8 and follow this vibe:

lines starting with tag_name=value kick off a new tag
every other line is the continuation of the last declared tag

If the tag name starts with WM/, the tag goes into the Xtra box (that's a WMA tag, string only).

🔑 QT metadata key 🔑

The tag gets added as a QT metadata key if:

tag_name starts with QT/
or tag_name isn't recognized and is longer than 4 characters

Your tag_name can optionally be prefixed with HDLR@, which sets the tag namespace 4CC — and the default namespace is mdta.

And the tag_value can be prefixed with:

S: force string encoding (this one has to go first) instead of parsing the tag value
b: use 8-bit encoding for signed or unsigned int
s: use 16-bit encoding for signed or unsigned int
l: use 32-bit encoding for signed or unsigned int
L: use 64-bit encoding for signed or unsigned int
f: force float encoding for numbers

Numbers get converted by default and stored in variable-size mode. And if you wanna force a positive integer into signed storage, just slap a + in front of the number. periodt 💅

Example

-tags io.gpac.some_tag=s+32

This forces storing the value 32 in signed 16 bit format. slay.

The tag_value can also be formatted as:

XxY@WxH: a rectangle type
XxY: a point type
W@H: a size type
A,B,C,D,E,F,G,H,I: a 3x3 matrix
FNAME: data is loaded from FNAME, type set to jpeg or png if needed

✨ Supported tag names (name, value, type, aliases) ✨

album_artist (aART) — string (alias albumArtist)
genre (gnre) — string (ID3 genre tag)
tracknum (trkn) — fraction (syntax: A/B or A, B will be 0)
disk (disk) — fraction (syntax: A/B or A, B will be 0)
tempo (tmpo) — integer
compilation (cpil) — bool (yes or no)
show (tvsh) — string (alias tvShow)
episode_id (tven) — string (alias tvEpisodeID)
season (tvsn) — integer (alias tvSeason)
episode (tves) — integer (alias tvEPisode)
network (tvnn) — string (alias tvNetwork)
sdesc (desc) — string (alias description)
ldesc (ldes) — string (alias longDescription)
sort_name (sonm) — string (alias sortName)
sort_artist (soar) — string (alias sortArtist)
sort_album_artist (soaa) — string (alias sortAlbumArtist)
sort_album (soal) — string (alias sortAlbum)
sort_composer (soco) — string (alias sortComposer)
sort_show (sosn) — string (alias sortShow)
cover (covr) — file path (alias artwork)
copyright (cprt) — string
pdate (purd) — string (alias purchaseDate)
podcast (pcst) — bool (yes or no)
url (purl) — string (alias podcastURL)
keywords (kyyw) — string
category (catg) — string
hdvideo (hdvd) — integer
media (stik) — integer (alias mediaType)
rating (rtng) — integer (alias contentRating)
gapless (pgap) — bool (yes or no)

🎬 Live Scene Encoder Options 🎬

These options get specified as opt_name=opt_val. Here's the menu, bestie:

-live — enable live BIFS/LASeR encoder
-dst (string) — destination IP
-port (int, default: 7000) — destination port
-mtu (int, default: 1450) — path MTU for RTP packets
-ifce (string) — IP address of the physical interface to use
-ttl (int, default: 1) — time to live for multicast packets
-sdp (string, default: session.sdp) — output SDP file
-dims — turn on DIMS mode for SVG input
-no-rap — disable RAP sending and carousel generation
-src (string) — source of scene updates
-rap (int) — duration in ms of base carousel; you can specify the RAP period of a single ESID (not in DIMS) using ESID=X:time

Runtime options, aka the lil keyboard shortcuts 🫶:

q: quits
u: inputs some commands to be sent
U: same as u but signals the updates as critical
e: inputs some commands to be sent without being aggregated
E: same as e but signals the updates as critical
f: forces RAP sending
F: forces RAP regeneration and sending
p: dumps current scene

🌸 EXAMPLES 🌸

Basic and advanced examples are available at https://wiki.gpac.io/MP4Box/MP4Box — go look, it's giving tutorial energy 💖

💜 MORE 💜

Authors: GPAC developers, see git repo history (-log)

For bug reports, feature requests, more information and source code, visit https://github.com/gpac/gpac

build: 26.02

👀 SEE ALSO 👀

gpac(1)

okay bestie that's literally the whole page, you ate it up 💅✨ This was the MP4Box(1) manpage — source/version MP4Box, dated 2019. no cap, go tag some files 🎀🦋

📦 where this page comes from

fedora 44: gpac 26.02.0-1.fc44 · LGPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms