gpac(1) GPAC gpac(1)
NAME
gpac - GPAC command-line filter session manager
SYNOPSIS
gpac [options]FILTER[LINK]FILTER[...]
DESCRIPTION
This page describes all filters usually present in GPAC
To check for help on a filter not listed here, use gpac -h myfilter
inspect
Description: Inspect packets
The inspect filter can be used to dump PID and packets. It may also be
used to check parts of payload of the packets.
The default options inspect only PID changes.
If .I full is not set, .I mode=frame is forced and PID properties are
formatted in human-readable form, one PID per line.
Otherwise, all properties are dumped.
Note: specifying .I xml, .I analyze, .I fmt or using -for-test will
force .I full to true.
Custom property duming
The packet inspector can be configured to dump specific properties of
packets using .I fmt.
When the option is not present, all properties are dumped. Otherwise,
only properties identified by $TOKEN$ are printed. You may use '$', '@'
or '%' for TOKEN separator. TOKEN can be:
* pn: packet (frame in framed mode) number
* dts: decoding time stamp in stream timescale, N/A if not available
* ddts: difference between current and previous packets decoding time
stamp in stream timescale, N/A if not available
* cts: composition time stamp in stream timescale, N/A if not available
* dcts: difference between current and previous packets composition
time stamp in stream timescale, N/A if not available
* ctso: difference between composition time stamp and decoding time
stamp in stream timescale, N/A if not available
* dur: duration in stream timescale
* frame: framing status
* interface: complete AU, interface object (no size info). Typically
a GL texture
* frame_full: complete AU
* frame_start: beginning of frame
* frame_end: end of frame
* frame_cont: frame continuation (not beginning, not end)
* sap or rap: SAP type of the frame
* ilace: interlacing flag (0: progressive, 1: top field, 2: bottom
field)
* corr: corrupted packet flag
* seek: seek flag
* bo: byte offset in source, N/A if not available
* roll: roll info
* crypt: crypt flag
* vers: carousel version number
* size: size of packet
* csize: total size of packets received so far
* crc: 32 bit CRC of packet
* lf or n: insert new line
* t: insert tab
* data: hex dump of packet (big output!) or as string if legal UTF-8
* lp: leading picture flag
* depo: depends on other packet flag
* depf: is depended on other packet flag
* red: redundant coding flag
* start: packet composition time as HH:MM:SS.ms
* startc: packet composition time as HH:MM:SS,ms
* end: packet end time as HH:MM:SS.ms
* endc: packet end time as HH:MM:SS,ms
* ck: clock type used for PCR discontinuities
* pcr: MPEG-2 TS last PCR, n/a if not available
* pcrd: difference between last PCR and decoding time, n/a if no PCR
available
* pcrc: difference between last PCR and composition time, n/a if no PCR
available
* P4CC: 4CC of packet property
* PropName: Name of packet property
* pid.P4CC: 4CC of PID property
* pid.PropName: Name of PID property
* fn: Filter name
Example
fmt="PID $pid.ID$ packet $pn$ DTS $dts$ CTS $cts$ $lf$"
This dumps packet number, cts and dts as follows: PID 1 packet 10 DTS
100 CTS 108
An unrecognized keyword or missing property will resolve to an empty
string.
Note: when dumping in interleaved mode, there is no guarantee that the
packets will be dumped in their original sequence order since the
inspector fetches one packet at a time on each PID.
Note on playback
Buffering can be enabled to check the input filter chain behaviour,
e.g. check HAS adaptation logic.
The various buffering options control when packets are consumed.
Buffering events are logged using media@info for state changes and
media@debug for media filling events.
The .I speed option is only used to configure the filter chain but is
ignored by the filter when consuming packets.
If real-time consumption is required, a reframer filter must be setup
before the inspect filter.
Example
gpac -i SRC reframer:rt=on
inspect:buffer=10000:rbuffer=1000:mbuffer=30000:speed=2
This will play the session at 2x speed, using 30s of maximum buffering,
consumming packets after 10s of media are ready and rebuffering if less
than 1s of media.
Options (expert):
log (str, default: stdout, minmax: fileName, stderr, stdout, GLOG or
null): set probe log filename to print number of streams, GLOG uses
GPAC logs app@info(default for android)
mode (enum, default: pck): dump mode
* pck: dump full packet
* blk: dump packets before reconstruction
* frame: force reframer
* raw: dump source packets without demultiplexing
interleave (bool, default: true): dump packets as they are received on
each PID. If false, logs are reported for each PID at end of session
deep (bool, default: false, updatable): dump packets along with PID
state change, implied when .I fmt is set
props (bool, default: true, updatable): dump packet properties, ignored
when .I fmt is set
dump_data (bool, default: false, updatable): enable full data dump
(very large output), ignored when .I fmt is set
fmt (str, updatable): set packet dump format
hdr (bool, default: true): print a header corresponding to fmt
string without '$' or "pid"
allp (bool, default: false): analyse for the entire duration, rather
than stopping when all PIDs are found
info (bool, default: false, updatable): monitor PID info changes
full (bool, default: false, updatable): full dump of PID properties
(always on if XML)
pcr (bool, default: false, updatable): dump M2TS PCR info
speed (dbl, default: 1.0): set playback command speed. If negative
and start is 0, start is set to -1
start (dbl, default: 0.0): set playback start offset. A negative
value means percent of media duration with -1 equal to duration
dur (frac, default: 0/0): set inspect duration
analyze (enum, default: off, updatable): analyze sample content (NALU,
OBU)
* off: no analyzing
* on: simple analyzing
* bs: log bitstream syntax (all elements read from bitstream)
* full: log bitstream syntax and bit sizes signaled as (N) after field
value, except 1-bit fields (omitted)
xml (bool, default: false, updatable): use xml formatting (implied if
(-analyze]() is set) and disable .I fmt
crc (bool, default: false, updatable): dump crc of samples of
subsamples (NALU or OBU) when analyzing
fftmcd (bool, default: false, updatable): consider timecodes use
ffmpeg-compatible signaling rather than QT compliant one
dtype (bool, default: false, updatable): dump property type
buffer (uint, default: 0): set playback buffer in ms
mbuffer (uint, default: 0): set max buffer occupancy in ms. If less
than buffer, use buffer
rbuffer (uint, default: 0, updatable): rebuffer trigger in ms. If 0 or
more than buffer, disable rebuffering
test (enum, default: no, updatable): skip predefined set of properties,
used for test mode
* no: no properties skipped
* noprop: all properties/info changes on PID are skipped, only packets
are dumped
* network: URL/path dump, cache state, file size properties skipped
(used for hashing network results)
* netx: same as network but skip track duration and templates (used for
hashing progressive load of fmp4)
* encode: same as network plus skip decoder config (used for hashing
encoding results)
* encx: same as encode and skip bitrates, media data size and co
* nocrc: disable packet CRC dump
* nobr: skip bitrate
probe
Description: Probe source
The Probe filter is used by applications (typically MP4Box) to query
demultiplexed PIDs (audio, video, ...) available in a source chain.
The filter outputs the number of input PIDs in the file specified by .I
log.
It is up to the app developer to query input PIDs of the prober and
take appropriated decisions.
Options (expert):
log (str, default: stdout, minmax: fileName, stderr, stdout GLOG or
null): set probe log filename to print number of streams, GLOG uses
GPAC logs app@info(default for android)
compositor
Description: Compositor
The GPAC compositor allows mixing audio, video, text and graphics in a
timed fashion.
The compositor operates either in media-client or filter-only mode.
Media-client mode
In this mode, the compositor acts as a pseudo-sink for the video side
and creates its own output window.
The video frames are dispatched to the output video PID in the form of
frame pointers requiring later GPU read if used.
The audio part acts as a regular filter, potentially mixing and
resampling the audio inputs to generate its output.
User events are directly processed by the filter in this mode.
Filter mode
In this mode, the compositor acts as a regular filter generating frames
based on the loaded scene.
It will generate its outputs based on the input video frames, and will
process user event sent by consuming filter(s).
If no input video frames (e.g. pure BIFS / SVG / VRML), the filter will
generate frames based on the .I fps, at constant or variable frame
rate.
It will stop generating frames as soon as all input streams are done,
unless extended/reduced by .I dur.
If audio streams are loaded, an audio output PID is created.
The default output pixel format in filter mode is:
- rgb when the filter is explicitly loaded by the application
- rgba when the filter is loaded during a link resolution
This can be changed by assigning the .I opfmt option.
If either .I opfmt specifies alpha channel or .I bc is not 0 but has
alpha=0, background creation in default scene will be skipped.
In filter-only mode, the special URL gpid:// is used to locate PIDs in
the scene description, in order to design scenes independently from
source media.
When such a PID is associated to a Background2D node in BIFS (no SVG
mapping yet), the compositor operates in pass-through mode.
In this mode, only new input frames on the pass-through PID will
generate new frames, and the scene clock matches the input packet time.
The output size and pixel format will be set to the input size and
pixel format, unless specified otherwise in the filter options.
If only 2D graphics are used and display driver is not forced, 2D
rasterizer will happen in the output pixel format (including YUV pixel
formats).
In this case, in-place processing (rasterizing over the input frame
data) will be used whenever allowed by input data.
If 3D graphics are used or display driver is forced, OpenGL will be
used on offscreen surface and the output packet will be an OpenGL
texture.
Specific URL syntaxes
The compositor accepts any URL type supported by GPAC. It also accepts
the following schemes for URLs:
* views:// : creates an auto-stereo scene of N views from
views://v1::.::vN
* mosaic:// : creates a mosaic of N views from mosaic://v1::.::vN
For both syntaxes, vN can be any type of URL supported by GPAC.
For views:// syntax, the number of rendered views is set by .I nbviews:
- If the URL gives less views than rendered, the views will be repeated
- If the URL gives more views than rendered, the extra views will be
ignored
The compositor can act as a source filter when the .I src option is
explicitly set, independently from the operating mode:
Example
gpac compositor:src=source.mp4 vout
The compositor can act as a source filter when the source url uses one
of the compositor built-in protocol schemes:
Example
gpac -i mosaic://URL1:URL2 vout
Options (expert):
aa (enum, default: all, updatable): set anti-aliasing mode for raster
graphics; whether the setting is applied or not depends on the graphics
module or graphic card
* none: no anti-aliasing
* text: anti-aliasing for text only
* all: complete anti-aliasing
hlfill (uint, default: 0x0, updatable): set highlight fill color (ARGB)
hlline (uint, default: 0xFF000000, updatable): set highlight stroke
color (ARGB)
hllinew (flt, default: 1.0, updatable): set highlight stroke width
sz (bool, default: true, updatable): enable scalable zoom. When
scalable zoom is enabled, resizing the output window will also
recompute all vectorial objects. Otherwise only the final buffer is
stretched
bc (uint, default: 0, updatable): default background color to use when
displaying transparent images or video with no scene composition
instructions
yuvhw (bool, default: true, updatable): enable YUV hardware for 2D blit
blitp (bool, default: true, updatable): partial hardware blit. If not
set, will force more redraw
softblt (bool, default: true): enable software blit/stretch in 2D. If
disabled, vector graphics rasterizer will always be used
stress (bool, default: false, updatable): enable stress mode of
compositor (rebuild all vector graphics and texture states at each
frame)
fast (bool, default: false, updatable): enable speed optimization -
whether the setting is applied or not depends on the graphics module /
graphic card
bvol (enum, default: no, updatable): draw bounding volume of objects
* no: disable bounding box
* box: draws a rectangle (2D) or box (3D)
* aabb: draws axis-aligned bounding-box tree (3D) or rectangle (2D)
textxt (enum, default: default, updatable): specify whether text shall
be drawn to a texture and then rendered or directly rendered. Using
textured text can improve text rendering in 3D and also improve text-
on-video like content
* default: use texturing for OpenGL rendering, no texture for 2D
rasterizer
* never: never uses text textures
* always: always render text to texture before drawing
out8b (bool, default: false, updatable): convert 10-bit video to 8 bit
texture before GPU upload
drop (bool, default: false, updatable): drop late frame when drawing.
If not set, frames are not dropped until a desynchronization of 1
second or more is observed
sclock (bool, default: false, updatable): force synchronizing all
streams on a single clock
sgaze (bool, default: false, updatable): simulate gaze events through
mouse
ckey (uint, default: 0, updatable): color key to use in windowless mode
(0xFFRRGGBB). GPAC currently does not support true alpha blitting to
desktop due to limitations in most windowing toolkit, it therefore uses
color keying mechanism. The alpha part of the key is used for global
transparency of the output, if supported
timeout (uint, default: 10000, updatable): timeout in ms after which a
source is considered dead (0 disable timeout)
fps (frac, default: 30/1, updatable): simulation frame rate when
animation-only sources are played (ignored when video is present)
timescale (uint, default: 0, updatable): timescale used for output
packets when no input video PID. A value of 0 means fps numerator
autofps (bool, default: true): use video input fps for output, ignored
in player mode. If no video or not set, uses .I fps
vfr (bool, default: false): only emit frames when changes are
detected. (always true in player mode and when filter is dynamically
loaded)
dur (dbl, default: 0, updatable): duration of generation. Mostly used
when no video input is present. Negative values mean number of frames,
positive values duration in second, 0 stops as soon as all streams are
done
fsize (bool, default: false, updatable): force the scene to resize to
the biggest bitmap available if no size info is given in the BIFS
configuration
mode2d (enum, default: defer, updatable): specify whether immediate
drawing should be used or not
* immediate: the screen is completely redrawn at each frame (always on
if pass-through mode is detected)
* defer: object positioning is tracked from frame to frame and dirty
rectangles info is collected in order to redraw the minimal amount of
the screen buffer
* debug: only renders changed areas, resetting other areas
Whether the setting is applied or not depends on the graphics module
and player mode
amc (bool, default: true): audio multichannel support; if disabled
always down-mix to stereo. Useful if the multichannel output does not
work properly
asr (uint, default: 0): force output sample rate (0 for auto)
ach (uint, default: 0): force output channels (0 for auto)
alayout (uint, default: 0): force output channel layout (0 for auto)
afmt (afmt, default: s16, minmax:
none,u8,s16,s16b,s24,s32,flt,dbl,u8p,s16p,s24p,s32p,fltp,dblp): force
output channel format (0 for auto)
asize (uint, default: 1024): audio output packet size in samples
abuf (uint, default: 100): audio output buffer duration in ms - the
audio renderer fills the output PID up to this value. A too low value
will lower latency but can have real-time playback issues
avol (uint, default: 100, updatable): audio volume in percent
apan (uint, default: 50, updatable): audio pan in percent, 50 is no pan
async (bool, default: true, updatable): audio resynchronization; if
disabled, audio data is never dropped but may get out of sync
max_aspeed (dbl, default: 2.0, updatable): silence audio if playback
speed is greater than specified value
max_vspeed (dbl, default: 4.0, updatable): move to i-frame only
decoding if playback speed is greater than specified value
buffer (uint, default: 3000, updatable): playout buffer in ms
(overridden by BufferLength property of input PID)
rbuffer (uint, default: 1000, updatable): rebuffer trigger in ms
(overridden by RebufferLength property of input PID)
mbuffer (uint, default: 3000, updatable): max buffer in ms, must be
greater than playout buffer (overridden by BufferMaxOccupancy property
of input PID)
ntpsync (uint, default: 0, updatable): ntp resync threshold in ms
(drops frame if their NTP is more than the given threshold above local
ntp), 0 disables ntp drop
nojs (bool, default: false): disable javascript
noback (bool, default: false): ignore background nodes and viewport
fill (useful when dumping to PNG)
ogl (enum, default: auto, updatable): specify 2D rendering mode
* auto: automatically decides between on, off and hybrid based on
content
* off: disables OpenGL; 3D will not be rendered
* on: uses OpenGL for all graphics; this will involve polygon
tesselation and 2D graphics will not look as nice as 2D mode
* hybrid: the compositor performs software drawing of 2D graphics with
no textures (better quality) and uses OpenGL for all 2D objects with
textures and 3D objects
pbo (bool, default: false, updatable): enable PixelBufferObjects to
push YUV textures to GPU in OpenGL Mode. This may slightly increase the
performances of the playback
nav (enum, default: none, updatable): override the default navigation
mode of MPEG-4/VRML (Walk) and X3D (Examine)
* none: disables navigation
* walk: 3D world walk
* fly: 3D world fly (no ground detection)
* pan: 2D/3D world zoom/pan
* game: 3D world game (mouse gives walk direction)
* slide: 2D/3D world slide
* exam: 2D/3D object examine
* orbit: 3D object orbit
* vr: 3D world VR (yaw/pitch/roll)
linegl (bool, default: false, updatable): indicate that outlining shall
be done through OpenGL pen width rather than vectorial outlining
epow2 (bool, default: true, updatable): emulate power-of-2 textures for
OpenGL (old hardware). Ignored if OpenGL rectangular texture extension
is enabled
* yes: video texture is not resized but emulated with padding. This
usually speeds up video mapping on shapes but disables texture
transformations
* no: video is resized to a power of 2 texture when mapping to a shape
paa (bool, default: false, updatable): indicate whether polygon
antialiasing should be used in full antialiasing mode. If not set, only
lines and points antialiasing are used
bcull (enum, default: on, updatable): indicate whether backface culling
shall be disable or not
* on: enables backface culling
* off: disables backface culling
* alpha: only enables backface culling for transparent meshes
wire (enum, default: none, updatable): wireframe mode
* none: objects are drawn as solid
* only: objects are drawn as wireframe only
* solid: objects are drawn as solid and wireframe is then drawn
norms (enum, default: none, updatable): normal vector drawing for debug
* none: no normals drawn
* face: one normal per face drawn
* vertex: one normal per vertex drawn
rext (bool, default: true, updatable): use non power of two
(rectangular) texture GL extension
cull (bool, default: true, updatable): use aabb culling: large objects
are rendered in multiple calls when not fully in viewport
depth_gl_scale (flt, default: 100, updatable): set depth scaler
depth_gl_type (enum, default: none, updatable): set geometry type used
to draw depth video
* none: no geometric conversion
* point: compute point cloud from pixel+depth
* strip: same as point but thins point set
nbviews (uint, default: 0, updatable): number of views to use in stereo
mode
stereo (enum, default: none, updatable): stereo output type. If your
graphic card does not support OpenGL shaders, only top and side modes
will be available
* none: no stereo
* side: images are displayed side by side from left to right
* top: images are displayed from top (laft view) to bottom (right view)
* hmd: same as side except that view aspect ratio is not changed
* ana: standard color anaglyph (red for left view, green and blue for
right view) is used (forces views=2)
* cols: images are interleaved by columns, left view on even columns
and left view on odd columns (forces views=2)
* rows: images are interleaved by columns, left view on even rows and
left view on odd rows (forces views=2)
* spv5: images are interleaved by for SpatialView 5 views display,
fullscreen mode (forces views=5)
* alio8: images are interleaved by for Alioscopy 8 views displays,
fullscreen mode (forces views=8)
* custom: images are interleaved according to the shader file indicated
in .I mvshader. The shader is exposed each view as uniform sampler2D
gfViewX, where X is the view number starting from the left
mvshader (str, updatable): file path to the custom multiview
interleaving shader
fpack (enum, default: none, updatable): default frame packing of input
video
* none: no frame packing
* top: top bottom frame packing
* side: side by side packing
camlay (enum, default: offaxis, updatable): camera layout in multiview
modes
* straight: camera is moved along a straight line, no rotation
* offaxis: off-axis projection is used
* linear: camera is moved along a straight line with rotation
* circular: camera is moved along a circle with rotation
iod (flt, default: 6.4, updatable): inter-ocular distance (eye
separation) in cm (distance between the cameras).
rview (bool, default: false, updatable): reverse view order
dbgpack (bool, default: false, updatable): view packed stereo video as
single image (show all)
tvtn (uint, default: 30, updatable): number of point sampling for tile
visibility algorithm
tvtt (uint, default: 8, updatable): number of points above which the
tile is considered visible
tvtd (enum, default: off, updatable): debug tiles and full coverage SRD
* off: regular draw
* partial: only displaying partial tiles, not the full sphere video
* full: only display the full sphere video
tvtf (bool, default: false, updatable): force all tiles to be
considered visible, regardless of viewpoint
fov (flt, default: 1.570796326794897, updatable): default field of view
for VR
vertshader (str): path to vertex shader file
fragshader (str): path to fragment shader file
autocal (bool, default: false, updatable): auto calibration of
znear/zfar in depth rendering mode
dispdepth (sint, default: -1, updatable): display depth, negative value
uses default screen height
dispdist (flt, default: 50, updatable): distance in cm between the
camera and the zero-disparity plane. There is currently no automatic
calibration of depth in GPAC
focdist (flt, default: 0, updatable): distance of focus point
osize (v2di, default: 0x0, updatable): force output size. If not set,
size is derived from inputs
dpi (v2di, default: 96x96, updatable): default dpi if not indicated by
video output
dbgpvr (flt, default: 0, updatable): debug scene used by PVR addon
player (enum, default: no): set compositor in player mode
* no: regular mode
* base: player mode
* gui: player mode with GUI auto-start
noaudio (bool, default: false): disable audio output
opfmt (pfmt, default: none, minmax:
none,yuv420,yvu420,yuv420_10,yuv422,yuv422_10,yuv444,yuv444_10,uyvy,vyuy,yuyv,yvyu,uyvl,vyul,yuyl,yvyl,nv12,nv21,nv1l,nv2l,yuva,yuvd,yuv444a,yuv444p,v308,yuv444ap,v408,v410,v210,grey,algr,gral,rgb4,rgb5,rgb6,rgba,argb,bgra,abgr,rgb,bgr,xrgb,rgbx,xbgr,bgrx,rgbd,rgbds,uncv):
pixel format to use for output. Ignored in .I player mode
drv (enum, default: auto): indicate if graphics driver should be
used
* no: never loads a graphics driver, software blit is used, no 3D
possible (in player mode, disables OpenGL)
* yes: always loads a graphics driver, output pixel format will be RGB
(in player mode, same as auto)
* auto: decides based on the loaded content
src (cstr): URL of source content
gaze_x (sint, default: 0, updatable): horizontal gaze coordinate
(0=left, width=right)
gaze_y (sint, default: 0, updatable): vertical gaze coordinate (0=top,
height=bottom)
gazer_enabled (bool, default: false, updatable): enable gaze event
dispatch
subtx (sint, default: 0, updatable): horizontal translation in pixels
towards right for subtitles renderers
subty (sint, default: 0, updatable): vertical translation in pixels
towards top for subtitles renderers
subfs (uint, default: 0, updatable): font size for subtitles renderers
(0 means automatic)
subd (sint, default: 0, updatable): subtitle delay in milliseconds for
subtitles renderers
audd (sint, default: 0, updatable): audio delay in milliseconds
clipframe (bool, default: false): visual output is clipped to bounding
rectangle
mp4dmx
Description: ISOBMFF/QT demultiplexer
This filter demultiplexes ISOBMF and QT files.
Input ISOBMFF/QT can be regular or fragmented, and available as files
or as raw bytestream.
Track Selection
The filter can use fragment identifiers of source to select a single
track for playback. The allowed fragments are:
* #audio: only use the first audio track
* #video: only use the first video track
* #auxv: only use the first auxiliary video track
* #pict: only use the first picture track
* #text: only use the first text track
* #trackID=VAL: only use the track with given ID
* #itemID=VAL: only use the item with given ID
* #ID=VAL: only use the track/item with given ID
* #VAL: only use the track/item with given ID
Scalable Tracks
When scalable tracks are present in a file, the reader can operate in 3
modes using .I smode option:
* smode=single: resolves all extractors to extract a single bitstream
from a scalable set. The highest level is used
In this mode, there is no enhancement decoder config, only a base one
resulting from the merge of the layers configurations
* smode=split: all extractors are removed and every track of the
scalable set is declared. In this mode, each enhancement track has no
base decoder config
and an enhancement decoder config.
* smode=splitx: extractors are kept in the bitstream, and every track
of the scalable set is declared. In this mode, each enhancement track
has a base decoder config
(copied from base) and an enhancement decoder config. This is mostly
used for DASHing content.
Warning: smode=splitx will result in extractor NAL units still present
in the output bitstream, which shall only be true if the output is
ISOBMFF based
Options (expert):
src (cstr): local file name of source content (only
used when explicitly loading the filter)
allt (bool, default: false): load all tracks even if unknown media
type
noedit (bool, default: false): do not use edit lists
itt (bool, default: false): convert all items of root meta into a
single PID
itemid (bool, default: true): keep item IDs in PID properties
smode (enum, default: split): load mode for scalable/tile tracks
* split: each track is declared, extractors are removed
* splitx: each track is declared, extractors are kept
* single: a single track is declared (highest level for scalable, tile
base for tiling)
alltk (bool, default: false): declare disabled tracks
frame_size (uint, default: 1024): frame size for raw audio samples
(dispatches frame_size samples per packet)
expart (bool, default: false): expose cover art as a dedicated video
PID
sigfrag (bool, default: false): signal fragment and segment boundaries
of source on output packets
tkid (str): declare only track based on given param
* integer value: declares track with the given ID
* audio: declares first audio track
* video: declares first video track
* 4CC: declares first track with matching 4CC for handler type
stsd (uint, default: 0): only extract sample mapped to the given
sample description index (0 means extract all)
nocrypt (bool): signal encrypted tracks as non encrypted
(mostly used for export)
mstore_size (uint, default: 1000000): target buffer size in bytes when
reading from memory stream (pipe etc...)
mstore_purge (uint, default: 50000): minimum size in bytes between
memory purges when reading from memory stream, 0 means purge as soon as
possible
mstore_samples (uint, default: 50): minimum number of samples to be
present before purging sample tables when reading from memory stream
(pipe etc...), 0 means purge as soon as possible
strtxt (bool, default: false): load text tracks (apple/tx3g) as MPEG-4
streaming text tracks
xps_check (enum, default: auto): parameter sets extraction mode from
AVC/HEVC/VVC samples
* keep: do not inspect sample (assumes input file is compliant when
generating DASH/HLS/CMAF)
* rem: removes all inband xPS and notify configuration changes
accordingly
* auto: resolves to keep for smode=splix (dasher mode), rem otherwise
nodata (bool, default: false): do not load sample data
initseg (str): local init segment name when input is a
single ISOBMFF segment
bifsdec
Description: MPEG-4 BIFS decoder
This filter decodes MPEG-4 BIFS binary frames directly into the scene
graph of the compositor.
Note: This filter cannot be used to dump BIFS content to text or xml,
use MP4Box for that.
No options
odfdec
Description: MPEG-4 OD decoder
This filter decodes MPEG-4 OD binary frames directly into the scene
manager of the compositor.
Note: This filter cannot be used to dump OD content to text or xml, use
MP4Box for that.
No options
fin
Description: File input
This filter dispatch raw blocks from input file into a filter chain.
Block size can be adjusted using .I block_size.
Content format can be forced through .I mime and file extension can be
changed through .I ext.
Note: Unless disabled at session level (see .I -no-probe ), file
extensions are usually ignored and format probing is done on the first
data block.
The special file name null is used for creating a file with no data,
needed by some filters such as dasher.
The special file name rand is used to generate random data.
The special file name randsc is used to generate random data with
0x000001 start-code prefix.
The filter handles both files and GF_FileIO objects as input URL.
Options (expert):
src (cstr): location of source file
block_size (uint, default: 0): block size used to read file. 0 means
5000 if file less than 500m, 1M otherwise
range (lfrac, default: 0-0): byte range
ext (cstr): override file extension
mime (cstr): set file mime type
pck (mem): data to use instead of file
btplay
Description: BT/XMT/X3D loader
This filter parses MPEG-4 BIFS (BT and XMT), VRML97 and X3D (wrl and
XML) files directly into the scene graph of the compositor.
When .I sax_dur=N is set, the filter will do a progressive load of the
source and cancel current loading when processing time is higher than
N.
Options (expert):
sax_dur (uint, default: 0): duration for SAX parsing (XMT), 0
disables SAX parsing
httpin
Description: HTTP input
This filter dispatch raw blocks from a remote HTTP resource into a
filter chain.
Block size can be adjusted using .I block_size, and disk caching
policies can be adjusted.
Content format can be forced through .I mime and file extension can be
changed through .I ext.
The filter supports both http and https schemes, and will attempt
reconnecting as TLS if TCP connection fails.
Note: Unless disabled at session level (see .I -no-probe ), file
extensions are usually ignored and format probing is done on the first
data block.
Options (expert):
src (cstr): URL of source content
block_size (uint, default: 100000): block size used to read file
cache (enum, default: disk): set cache mode
* auto: cache to disk if content length is known, no cache otherwise
* disk: cache to disk, discard once session is no longer used
* keep: cache to disk and keep
* mem: stores to memory, discard once session is no longer used
* mem_keep: stores to memory, keep after session is reassigned but move
to mem after first download
* none: no cache
* none_keep: stores to memory, keep after session is reassigned but
move to none after first download
range (lfrac, default: 0-0): set byte range, as fraction
ext (cstr): override file extension
mime (cstr): set file mime type
blockio (bool, default: false): use blocking IO
svgplay
Description: SVG loader
This filter parses SVG files directly into the scene graph of the
compositor.
When .I sax_dur=N is set, the filter will do a progressive load of the
source and cancel current loading when processing time is higher than
N.
Options (expert):
sax_dur (uint, default: 0): loading duration for SAX parsing, 0
disables SAX parsing
rfimg
Description: JPG/J2K/PNG/BMP reframer
This filter parses JPG/J2K/PNG/BMP files/data and outputs corresponding
visual PID and frames.
The following extensions for PNG change the pixel format for RGBA
images:
* pngd: use RGB+depth map pixel format
* pngds: use RGB+depth(7bits)+shape(MSB of alpha channel) pixel format
No options
imgdec
Description: PNG/JPG decoder
This filter decodes JPEG and PNG images.
No options
rfadts
Description: ADTS reframer
This filter parses AAC files/data and outputs corresponding audio PID
and frames.
Options (expert):
frame_size (uint, default: 1024): size of AAC frame in audio samples
index (dbl, default: 1.0): indexing window length
ovsbr (bool, default: false): force oversampling SBR (does not
multiply timescales by 2)
sbr (enum, default: no): set SBR signaling
* no: no SBR signaling at all
* imp: backward-compatible SBR signaling (audio signaled as AAC-LC)
* exp: explicit SBR signaling (audio signaled as AAC-SBR)
ps (enum, default: no): set PS signaling
* no: no PS signaling at all
* imp: backward-compatible PS signaling (audio signaled as AAC-LC)
* exp: explicit PS signaling (audio signaled as AAC-PS)
expart (bool, default: false): expose pictures as a dedicated video PID
aacchcfg (sint, default: 0): set AAC channel configuration to this
value if missing from ADTS header, use negative value to always
override
rflatm
Description: LATM reframer
This filter parses AAC in LATM files/data and outputs corresponding
audio PID and frames.
Options (expert):
frame_size (uint, default: 1024): size of AAC frame in audio samples
index (dbl, default: 1.0): indexing window length
rfmp3
Description: MP3 reframer
This filter parses MPEG-1/2 audio files/data and outputs corresponding
audio PID and frames.
Options (expert):
index (dbl, default: 1.0): indexing window length
expart (bool, default: false): expose pictures as a dedicated video PID
forcemp3 (bool, default: true): force mp3 signaling for MPEG-2 Audio
layer 3
faad
Description: FAAD decoder
This filter decodes AAC streams through faad library.
No options
maddec
Description: MAD decoder
This filter decodes MPEG 1/2 audio streams through libmad library.
No options
xviddec
Description: XVid decoder
This filter decodes MPEG-4 part 2 (and DivX) through libxvidcore
library.
Options (expert):
deblock_y (bool, default: false): enable Y deblocking
deblock_uv (bool, default: false): enable UV deblocking
film_effect (bool, default: false): enable film effect
dering_y (bool, default: false): enable Y deblocking
dering_uv (bool, default: false): enable UV deblocking
j2kdec
Description: OpenJPEG2000 decoder
Version: 2.x
This filter decodes JPEG2000 streams through OpenJPEG2000 library.
No options
rfac3
Description: AC3 reframer
This filter parses AC3 and E-AC3 files/data and outputs corresponding
audio PID and frames.
Options (expert):
index (dbl, default: 1.0): indexing window length
a52dec
Description: A52 decoder
This filter decodes AC3 streams through a52dec library.
No options
rfamr
Description: AMR/EVRC reframer
This filter parses AMR, AMR Wideband, EVRC and SMV files/data and
outputs corresponding audio PID and frames.
Options (expert):
index (dbl, default: 1.0): indexing window length
oggdmx
Description: OGG demultiplexer
This filter demultiplexes OGG files/data into a set of media PIDs and
frames.
Options (expert):
index (dbl, default: 1.0): indexing window length (not
implemented), use 0 to disable stream probing for duration),
expart (bool, default: false): expose pictures as a dedicated video PID
vorbisdec
Description: Vorbis decoder
This filter decodes Vorbis streams through libvorbis library.
No options
theoradec
Description: Theora decoder
This filter decodes Theora streams through libtheora library.
No options
m2tsdmx
Description: MPEG-2 TS demultiplexer
This filter demultiplexes MPEG-2 Transport Stream files/data into a set
of media PIDs and frames.
Options (expert):
temi_url (cstr): force TEMI URL
dsmcc (bool, default: no): enable DSMCC receiver
seeksrc (bool, default: true): seek local source file back to origin
once all programs are setup
sigfrag (bool, default: false): signal segment boundaries on output
packets for DASH or HLS sources
dvbtxt (bool, default: false): export DVB teletext streams
sockin
Description: UDP/TCP input
This filter handles generic TCP and UDP input sockets. It can also
probe for MPEG-2 TS over RTP input. Probing of MPEG-2 TS over UDP/RTP
is enabled by default but can be turned off.
Data format can be specified by setting either .I ext or .I mime
options. If not set, the format will be guessed by probing the first
data packet
- UDP sockets are used for source URLs formatted as udp://NAME
- TCP sockets are used for source URLs formatted as tcp://NAME
- UDP unix domain sockets are used for source URLs formatted as
udpu://NAME
- TCP unix domain sockets are used for source URLs formatted as
tcpu://NAME
When ports are specified in the URL and the default option separators
are used (see gpac -h doc), the URL must either:
- have a trailing '/', e.g. udp://localhost:1234/[:opts]
- use gpac separator, e.g. udp://localhost:1234[:gpac:opts]
On OSX with VM packet replay you will need to force multicast routing,
e.g. route add -net 239.255.1.4/32 -interface vboxnet0
Options (expert):
src (cstr): address of source content
block_size (uint, default: 0x60000): block size used to read socket
port (uint, default: 1234): default port if not specified
ifce (cstr): default multicast interface
listen (bool, default: false): indicate the input socket works in
server mode
ka (bool, default: false): keep socket alive if no more connections
maxc (uint, default: +I): max number of concurrent connections
tsprobe (bool, default: true): probe for MPEG-2 TS data, either RTP or
raw UDP. Disabled if mime or ext are given and do not match MPEG-2 TS
mimes/extensions
ext (str): indicate file extension of udp data
mime (str): indicate mime type of udp data
block (bool, default: false): set blocking mode for socket(s)
timeout (uint, default: 10000): set timeout in ms for UDP socket(s), 0
to disable timeout
reorder_pck (uint, default: 100): number of packets delay for RTP
reordering (M2TS over RTP)
reorder_delay (uint, default: 10): number of ms delay for RTP
reordering (M2TS over RTP)
ssm (strl): list of IP to include for source-
specific multicast
ssmx (strl): list of IP to exclude for source-
specific multicast
dvbin
Description: DVB for Linux
Experimental DVB support for linux, requires a channel config file
through .I chcfg
The URL syntax is dvb://CHANNAME[@FRONTEND], with:
* CHANNAME: the channel name as listed in the channel config file
* frontend: the index of the DVB adapter to use (optional, default is
0)
Options (expert):
src (cstr): URL of source content
block_size (uint, default: 65536): block size used to read file
chcfg (cstr): path to channels.conf file
osvcdec
Description: OpenSVC decoder
This filter decodes scalable AVC|H264 streams through OpenSVC library.
No options
vtbdec
Description: VideoToolBox decoder
This filter decodes video streams through OSX/iOS VideoToolBox (MPEG-2,
H263, AVC|H264, HEVC, ProRes). It allows GPU frame dispatch or direct
frame copy.
Options (expert):
reorder (uint, default: 6): number of frames to wait for temporal
re-ordering
no_copy (bool, default: true): dispatch decoded frames as OpenGL
textures (true) or as copied packets (false)
ofmt (pfmt, default: nv12): set default pixel format for decoded
video. If not found, fall back to nv12
disable_hw (bool, default: false): disable hardware decoding
wait_sync (bool, default: false, updatable): wait for sync frame before
decoding
mcdec
Description: MediaCodec decoder
This filter decodes video streams using hardware decoder on android
devices
Options (expert):
disable_gl (bool, default: false): disable OpenGL texture transfer
lsrdec
Description: MPEG-4 LASeR decoder
This filter decodes MPEG-4 LASeR binary frames directly into the scene
graph of the compositor.
Note: This filter cannot be used to dump LASeR content to text or xml,
use MP4Box for that.
No options
safdmx
Description: SAF demultiplexer
This filter demultiplexes SAF (MPEG-4 Simple Aggregation Format for
LASeR) files/data into a set of media PIDs and frames.
No options
dashin
Description: MPEG-DASH and HLS client
This filter reads MPEG-DASH, HLS and MS Smooth manifests.
Regular mode
This is the default mode, in which the filter produces media PIDs and
frames from sources indicated in the manifest.
The default behavior is to perform adaptation according to .I algo, but
the filter can:
- run with no adaptation, to grab maximum quality.
Example
gpac -i MANIFEST_URL:algo=none:start_with=max_bw -o dest.mp4
- run with no adaptation, fetching all qualities.
Example
gpac -i MANIFEST_URL:split_as -o dst=$File$.mp4:clone
File mode
When .I forward is set to file, the client forwards media files without
demultiplexing them.
This is mostly used to expose the DASH session to a file server such as
ROUTE or HTTP.
In this mode, the manifest is forwarded as an output PID.
Warning: This mode cannot be set through inheritance as it changes the
link capabilities of the filter. The filter MUST be explicitly
declared.
To expose a live DASH session to route:
Example
gpac -i MANIFEST_URL dashin:forward=file -o route://225.0.0.1:8000/
If the source has dependent media streams (scalability) and all
qualities and initialization segments need to be forwarded, add .I
split_as.
Segment bound modes
When .I forward is set to segb or mani, the client forwards media
frames (after demultiplexing) together with segment and fragment
boundaries of source files.
This mode can be used to process media data and regenerate the same
manifest/segmentation.
Example
gpac -i MANIFEST_URL:forward=mani cecrypt:cfile=DRM.xml -o
encrypted/live.mpd:pssh=mv
This will encrypt an existing DASH session, inject PSSH in manifest and
segments.
Example
gpac -i MANIFEST_URL:forward=segb cecrypt:cfile=DRM.xml -o
encrypted/live.m3u8
This will encrypt an existing DASH session and republish it as HLS,
using same segment names and boundaries.
This mode will force .I noseek=true to ensure the first segment fetched
is complete, and .I split_as=true to fetch all qualities.
Each first packet of a segment will have the following properties
attached:
* `CueStart`: indicate this is a segment start
* `FileNumber`: current segment number
* `FileName`: current segment file name without manifest (MPD or master
HLS) base url
* `DFPStart`: set with value 0 if this is the first packet in the
period, absent otherwise
If .I forward is set to mani, the first packet of a segment dispatched
after a manifest update will also carry the manifest payload as a
property:
* `DFManifest`: contains main manifest (MPD, M3U8 master)
* `DFVariant`: contains list of HLS child playlists as strings for the
given quality
* `DFVariantName`: contains list of associated HLS child playlists
name, in same order as manifests in DFVariant
Each output PID will have the following properties assigned:
* `DFMode`: set to 1 for segb or 2 for mani
* `DCue`: set to inband
* `DFPStart`: set to current period start value
* `FileName`: set to associated init segment if any
* `Representation`: set to the associated representation ID in the
manifest
* `DashDur`: set to the average segment duration as indicated in the
manifest
* `source_template`: set to true to indicate the source template is
known
* `stl_timescale`: timescale used by SegmentTimeline, or 0 if no
SegmentTimeline
* `init_url`: unresolved intialization URL (as it appears in the MPD or
in the variant playlist)
* `manifest_url`: manifest URL
* `hls_variant_name`: HLS variant playlist name (as it appears in the
HLS master playlist)
When the dasher is used together with this mode, this will force all
generated segments to have the same name, duration and fragmentation
properties as the input ones. It is therefore not recommended for
sessions stored/generated on local storage to generate the output in
the same directory.
Options (expert):
auto_switch (sint, default: 0): switch quality every N segments
* positive: go to higher quality or loop to lowest
* negative: go to lower quality or loop to highest
* 0: disabled
segstore (enum, default: mem): enable file caching
* mem: all files are stored in memory, no disk IO
* disk: files are stored to disk but discarded once played
* cache: all files are stored to disk and kept
algo (str, default: gbuf, minmax:
none|grate|gbuf|bba0|bolaf|bolab|bolau|bolao|JS): adaptation algorithm
to use
* none: no adaptation logic
* grate: GPAC legacy algo based on available rate
* gbuf: GPAC legacy algo based on buffer occupancy
* bba0: BBA-0
* bolaf: BOLA Finite
* bolab: BOLA Basic
* bolau: BOLA-U
* bolao: BOLA-O
* JS: use file JS (either with specified path or in $GSHARE/scripts/)
for algo (.js extension may be omitted)
start_with (enum, default: max_bw): initial selection criteria
* min_q: start with lowest quality
* max_q: start with highest quality
* min_bw: start with lowest bitrate
* max_bw: start with highest bitrate; if tiles are used, all low
priority tiles will have the lower (below max) bandwidth selected
* max_bw_tiles: start with highest bitrate; if tiles are used, all low
priority tiles will have their lowest bandwidth selected
max_res (bool, default: true): use max media resolution to configure
display
abort (bool, default: false): allow abort during a segment download
use_bmin (enum, default: auto): playout buffer handling
* no: use default player settings
* auto: notify player of segment duration if not low latency
* mpd: use the indicated min buffer time of the MPD
shift_utc (sint, default: 0): shift DASH UTC clock in ms
spd (sint, default: -I): suggested presentation delay in ms
route_shift (sint, default: 0): shift ROUTE requests time by given ms
server_utc (bool, default: yes): use ServerUTC or Date HTTP headers
instead of local UTC
screen_res (bool, default: yes): use screen resolution in selection
phase
init_timeshift (sint, default: 0): set initial timeshift in ms (if >0)
or in per-cent of timeshift buffer (if <0)
tile_mode (enum, default: none): tile adaptation mode
* none: bitrate is shared equally across all tiles
* rows: bitrate decreases for each row of tiles starting from the top,
same rate for each tile on the row
* rrows: bitrate decreases for each row of tiles starting from the
bottom, same rate for each tile on the row
* mrows: bitrate decreased for top and bottom rows only, same rate for
each tile on the row
* cols: bitrate decreases for each columns of tiles starting from the
left, same rate for each tile on the columns
* rcols: bitrate decreases for each columns of tiles starting from the
right, same rate for each tile on the columns
* mcols: bitrate decreased for left and right columns only, same rate
for each tile on the columns
* center: bitrate decreased for all tiles on the edge of the picture
* edges: bitrate decreased for all tiles on the center of the picture
tiles_rate (uint, default: 100): indicate the amount of bandwidth to
use at each quality level. The rate is recursively applied at each
level, e.g. if 50%, Level1 gets 50%, level2 gets 25%, ... If 100,
automatic rate allocation will be done by maximizing the quality in
order of priority. If 0, bitstream will not be smoothed across
tiles/qualities, and concurrency may happen between different media
delay40X (uint, default: 500): delay in milliseconds to wait between
two 40X on the same segment
exp_threshold (uint, default: 100): delay in milliseconds to wait after
the segment AvailabilityEndDate before considering the segment lost
switch_count (uint, default: 1): indicate how many segments the client
shall wait before switching up bandwidth. If 0, switch will happen as
soon as the bandwidth is enough, but this is more prone to network
variations
aggressive (bool, default: no): if enabled, switching algo targets the
closest bandwidth fitting the available download rate. If no, switching
algo targets the lowest bitrate representation that is above the
currently played (e.g. does not try to switch to max bandwidth)
debug_as (uintl): play only the adaptation sets indicated
by their indices (0-based) in the MPD
speedadapt (bool, default: no): enable adaptation based on playback
speed
noxlink (bool, default: no): disable xlink if period has both xlink
and adaptation sets
query (str): set query string (without initial '?')
to append to xlink of periods
split_as (bool, default: no): separate all qualities into different
adaptation sets and stream all qualities. Dependent representations
(scalable) are treated as independent
noseek (bool, default: no): disable seeking of initial segment(s) in
dynamic mode (useful when UTC clocks do not match)
bwcheck (uint, default: 5): minimum time in milliseconds between two
bandwidth checks when allowing segment download abort
lowlat (enum, default: early): segment scheduling policy in low latency
mode
* no: disable low latency
* strict: strict respect of AST offset in low latency
* early: allow fetching segments earlier than their AST in low latency
when input PID is empty
forward (enum, default: none): segment forwarding mode
* none: regular DASH read
* file: do not demultiplex files and forward them as file PIDs (imply
segstore=mem)
* segb: turn on .I split_as, segment and fragment bounds signaling
(sigfrag) in sources and DASH cue insertion
* mani: same as segb and also forward manifests
fmodefwd (bool, default: yes): forward packet rather than copy them in
file forward mode. Packet copy might improve performances in low
latency mode
skip_lqt (bool, default: no): disable decoding of tiles with highest
degradation hints (not visible, not gazed at) for debug purposes
llhls_merge (bool, default: yes): merge LL-HLS byte range parts into a
single open byte range request
groupsel (bool, default: no): select groups based on language (by
default all playable groups are exposed)
chain_mode (enum, default: on): MPD chaining mode
* off: do not use MPD chaining
* on: use MPD chaining once over, fallback if MPD load failure
* error: use MPD chaining once over or if error (MPD or segment
download)
asloop (bool, default: false): when auto switch is enabled, iterates
back and forth from highest to lowest qualities
cdcrypt
Description: CENC decryptor
The CENC decryptor supports decrypting CENC, ISMA, HLS Sample-AES
(MPEG2 ts) and Adobe streams.
For HLS, key is retrieved according to the key URI in the manifest.
Otherwise, the filter uses a configuration file.
The syntax is available at https://wiki.gpac.io/Common-Encryption
The DRM config file can be set per PID using the property DecryptInfo
(highest priority), CryptInfo (lower priority) or set at the filter
level using .I cfile (lowest priority).
When the file is set per PID, the first CryptInfo with the same ID is
used, otherwise the first CryptInfo is used.When the file is set
globally (not per PID), the first CrypTrack in the DRM config file with
the same ID is used, otherwise the first CrypTrack with ID 0 or not set
is used.
Options (expert):
cfile (str): crypt file location
decrypt (enum, default: full): decrypt mode (CENC only)
* full: decrypt everything, throwing error if keys are not found
* nokey: decrypt everything for which a key is found, skip decryption
otherwise
* skip: decrypt nothing
drop_keys (uintl): consider keys with given 1-based indexes
as not available (multi-key debug)
kids (strl): define KIDs. If keys is empty, consider
keys with given KID (as hex string) as not available (debug)
keys (strl): define key values for each of the
specified KID
hls_cenc_patch_iv (bool, default: false): ignore IV updates in some
broken HLS+CENC streams
cecrypt
Description: CENC encryptor
The CENC encryptor supports CENC, ISMA and Adobe encryption. It uses a
DRM config file for declaring keys.
The syntax is available at https://wiki.gpac.io/Common-Encryption
The DRM config file can be set per PID using the property CryptInfo, or
set at the filter level using .I cfile.
When the DRM config file is set per PID, the first CrypTrack in the DRM
config file with the same ID is used, otherwise the first CrypTrack is
used (regardless of the CrypTrack ID).
When the DRM config file is set globally (not per PID), the first
CrypTrack in the DRM config file with the same ID is used, otherwise
the first CrypTrack with ID 0 or not set is used.
If no DRM config file is defined for a given PID, this PID will not be
encrypted, or an error will be thrown if .I allc is specified.
Options (expert):
cfile (str): crypt file location
allc (bool): throw error if no DRM config file is
found for a PID
mp4mx
Description: ISOBMFF/QT multiplexer
This filter multiplexes streams to ISOBMFF (14496-12 and derived
specifications) or QuickTime
Tracks and Items
By default all input PIDs with ItemID property set are multiplexed as
items, otherwise they are multiplexed as tracks.
To prevent source items to be multiplexed as items, use .I -itemid
option from ISOBMFF demultiplexer.
Example
gpac -i source.mp4:itemid=false -o file.mp4
To force non-item streams to be multiplexed as items, use #ItemID
option on that PID:
Example
gpac -i source.jpg:#ItemID=1 -o file.mp4
Storage
The .I store option allows controlling if the file is fragmented or
not, and when not fragmented, how interleaving is done. For cases where
disk requirements are tight and fragmentation cannot be used, it is
recommended to use either flat or fstart modes.
The .I vodcache option allows controlling how DASH onDemand segments
are generated:
- If set to on, file data is stored to a temporary file on disk and
flushed upon completion, no padding is present.
- If set to insert, SIDX/SSIX will be injected upon completion of the
file by shifting bytes in file. In this case, no padding is required
but this might not be compatible with all output sinks and will take
longer to write the file.
- If set to replace, SIDX/SSIX size will be estimated based on duration
and DASH segment length, and padding will be used in the file before
the final SIDX. If input PIDs have the properties DSegs set, this will
used be as the number of segments.
The on and insert modes will produce exactly the same file, while the
mode replace may inject a free box before the sidx.
Custom boxes
Custom boxes can be specified as box patches:
For movie-level patch, the .I boxpatch option of the filter should be
used.
Per PID box patch can be specified through the PID property boxpatch.
Example
gpac -i source:#boxpatch=myfile.xml -o mux.mp4
Per Item box patch can be specified through the PID property boxpatch.
Example
gpac -i source:1ItemID=1:#boxpatch=myfile.xml -o mux.mp4
The box patch is applied before writing the initial moov box in
fragmented mode, or when writing the complete file otherwise.
The box patch can either be a filename or the full XML string.
Tagging
When tagging is enabled, the filter will watch the property CoverArt
and all custom properties on incoming PID.
The built-in tag names are indicated by MP4Box -h tags.
QT tags can be specified using qtt_NAME property names, and will be
added using formatting specified in MP4Box -h tags.
Other tag class may be specified using tag_NAME property names, and
will be added if .I tags is set to all using:
- NAME as a box 4CC if NAME is four characters long
- NAME as a box 4CC if NAME is 3 characters long, and will be prefixed
by 0xA9
- the CRC32 of the NAME as a box 4CC if NAME is not four characters
long
User data
The filter will look for the following PID properties to create user
data entries:
* `udtab`: set the track user-data box to the property value which must
be a serialized box array blob
* `mudtab`: set the movie user-data box to the property value which
must be a serialized box array blob
* `udta_U4CC`: set track user-data box entry of type U4CC to property
value
* `mudta_U4CC`: set movie user-data box entry of type U4CC to property
value
Example
gpac -i src.mp4:#udta_tagc='My Awesome Tag' -o tag.mp4
gpac -i src.mp4:#mudtab=data@box.bin -o tag.mp4
Custom sample group descriptions and sample auxiliary info
The filter watches the following custom data properties on incoming
packets:
* `grp_A4CC`: maps packet to sample group description of type A4CC and
entry set to property payload
* `grp_A4CC_param`: same as above and sets sample to group
grouping_type_parameter to param
* `sai_A4CC`: adds property payload as sample auxiliary information of
type A4CC
* `sai_A4CC_param`: same as above and sets aux_info_type_parameterto
param
The property grp_EMSG consists in one or more EventMessageBox as
defined in MPEG-DASH.
- in fragmented mode, presence of these boxes in a packet will start a
new fragment, with the boxes written before the moof
- in regular mode, an internal sample group of type EMSG is currently
used for emsg box storage
Notes
The filter watches the property FileNumber on incoming packets to
create new files (regular mode) or new segments (DASH mode).
The filter watches the property DSIWrap (4CC as int or string) on
incoming PID to wrap decoder configuration in a box of given type
(unknown wrapping)
Example
-i unkn.mkv:#ISOMSubtype=VIUK:#DSIWrap=cfgv -o t.mp4
This will wrap the unknown stream using VIUK code point in stsd and
wrap any decoder configuration data in a cfgv box.
If .I pad_sparse is set, the filter watches the property Sparse on
incoming PID to decide whether empty packets should be injected to keep
packet duration info.
Such packets are only injected when a whole in the timeline is
detected.
- if Sparse is absent, empty packet is inserted for unknown text and
metadata streams
- if Sparse is true, empty packet is inserted for all stream types
- if Sparse is false, empty packet is never injected
Options (expert):
m4sys (bool, default: false): force MPEG-4 Systems signaling of tracks
dref (bool, default: false): only reference data from source file -
not compatible with all media sources
ctmode (enum, default: edit): set composition offset mode for video
tracks
* edit: uses edit lists to shift first frame to presentation time 0
* noedit: ignore edit lists and does not shift timeline
* negctts: uses ctts v1 with possibly negative offsets and no edit
lists
dur (frac, default: 0): only import the specified duration. If
negative, specify the number of coded frames to import
pack3gp (uint, default: 1): pack a given number of 3GPP audio frames
in one sample
importer (bool, default: false): compatibility with old importer,
displays import progress
pack_nal (bool, default: false): repack NALU size length to minimum
possible size for NALU-based video (AVC/HEVC/...)
xps_inband (enum, default: no): use inband (in sample data) parameter
set for NALU-based video (AVC/HEVC/...)
* no: parameter sets are not inband, several sample descriptions might
be created
* pps: picture parameter sets are inband, all other parameter sets are
in sample description
* all: parameter sets are inband, no parameter sets in sample
description
* both: parameter sets are inband, signaled as inband, and also first
set is kept in sample description
* mix: creates non-standard files using single sample entry with first
PSs found, and moves other PS inband
* auto: keep source config, or defaults to no if source is not ISOBMFF
store (enum, default: inter): file storage mode
* inter: perform precise interleave of the file using .I cdur (requires
temporary storage of all media)
* flat: write samples as they arrive and moov at end (fastest mode)
* fstart: write samples as they arrive and moov before mdat
* tight: uses per-sample interleaving of all tracks (requires temporary
storage of all media)
* frag: fragments the file using cdur duration
* sfrag: fragments the file using cdur duration but adjusting to start
with SAP1/3
cdur (frac, default: -1/1): chunk duration for flat and interleaving
modes or fragment duration for fragmentation modes
* 0: no specific interleaving but moov first
* negative: defaults to 1.0 unless overridden by storage profile
moovts (sint, default: 600): timescale to use for movie. A negative
value picks the media timescale of the first track added
moof_first (bool, default: true): generate fragments starting with moof
then mdat
abs_offset (bool, default: false): use absolute file offset in
fragments rather than offsets from moof
fsap (bool, default: true): split truns in video fragments at SAPs
to reduce file size
subs_sidx (sint, default: -1): number of subsegments per sidx. negative
value disables sidx, -2 removes sidx if present in source PID
m4cc (str): 4 character code of empty box to append
at the end of a segment
chain_sidx (bool, default: false): use daisy-chaining of SIDX
msn (uint, default: 1): sequence number of first moof to N
msninc (uint, default: 1): sequence number increase between moof
boxes
tfdt (lfrac, default: 0): set initial decode time (tfdt) of first
traf
tfdt_traf (bool, default: false): force tfdt box in each traf
nofragdef (bool, default: false): disable default flags in fragments
straf (bool, default: false): use a single traf per moof (smooth
streaming and co)
strun (bool, default: false): use a single trun per traf (smooth
streaming and co)
psshs (enum, default: moov): set pssh boxes store mode
* moof: in first moof of each segments
* moov: in movie box
* both: in movie box and in first moof of each segment
* none: pssh is discarded
sgpd_traf (bool, default: false): store sample group descriptions in
traf (duplicated for each traf). If not used, sample group descriptions
are stored in the movie box
vodcache (enum, default: replace): enable temp storage for VoD dash
modes
* on: use temp storage of complete file for sidx and ssix injection
* insert: insert sidx and ssix by shifting bytes in output file
* replace: precompute pace requirements for sidx and ssix and rewrite
file range at end
noinit (bool, default: false): do not produce initial moov, used for
DASH bitstream switching mode
tktpl (enum, default: yes): use track box from input if any as a
template to create new track
* no: disables template
* yes: clones the track (except edits and decoder config)
* udta: only loads udta
mudta (enum, default: yes): use udta and other moov extension boxes
from input if any
* no: disables import
* yes: clones all extension boxes
* udta: only loads udta
mvex (bool, default: false): set mvex boxes after trak boxes
sdtp_traf (enum, default: no): use sdtp box in traf box rather than
using flags in trun sample entries
* no: do not use sdtp
* sdtp: use sdtp box to indicate sample dependencies and do not write
info in trun sample flags
* both: use sdtp box to indicate sample dependencies and also write
info in trun sample flags
trackid (uint, default: 0): track ID of created track for single
track. Default 0 uses next available trackID
fragdur (bool, default: false): fragment based on fragment duration
rather than CTS. Mostly used for MP4Box -frag option
btrt (bool, default: true): set btrt box in sample description
styp (str): set segment styp major brand (and
optionally version) to the given 4CC[.version]
mediats (sint, default: 0): set media timescale. A value of 0 means
inherit from PID, a value of -1 means derive from samplerate or frame
rate
ase (enum, default: v0): set audio sample entry mode for more
than stereo layouts
* v0: use v0 signaling but channel count from stream, recommended for
backward compatibility
* v0s: use v0 signaling and force channel count to 2 (stereo) if more
than 2 channels
* v1: use v1 signaling, ISOBMFF style (will mux raw PCM as ISOBMFF
style)
* v1qt: use v1 signaling, QTFF style
ssix (bool, default: false): create ssix box when sidx box is
present, level 1 mapping I-frames byte ranges, level 0xFF mapping the
rest
ccst (bool, default: false): insert coding constraint box for video
tracks
maxchunk (uint, default: 0): set max chunk size in bytes for runs
(only used in non-fragmented mode). 0 means no constraints
noroll (bool, default: false): disable roll sample grouping
norap (bool, default: false): disable rap sample grouping
saio32 (bool, default: false): use 32 bit offset for side data location
instead of 64 bit offset
tfdt64 (bool, default: false): use 64 bit tfdt and sidx even for 32
bits timestamps
compress (enum, default: no): set top-level box compression mode
* no: disable box compression
* moov: compress only moov box
* moof: compress only moof boxes
* sidx: compress moof and sidx boxes
* ssix: compress moof, sidx and ssix boxes
* all: compress moov, moof, sidx and ssix boxes
fcomp (bool, default: false): force using compress box even when
compressed size is larger than uncompressed
otyp (bool, default: false): inject original file type when using
compressed boxes
trun_inter (bool, default: false): interleave samples in trun based on
the temporal level, the lowest level are stored first (this will create
as many trun boxes as required)
truns_first (bool, default: false): store track runs before sample
group description and sample encryption information
block_size (uint, default: 10000): target output block size, 0 for
default internal value (10k)
boxpatch (str): apply box patch before writing
deps (bool, default: true): add samples dependencies information
mfra (bool, default: false): enable movie fragment random access when
fragmenting (ignored when dashing)
forcesync (bool, default: false): force all SAP types to be considered
sync samples (might produce non-compliant files)
refrag (bool, default: false): use track fragment defaults from initial
file if any rather than computing them from PID properties (used when
processing standalone segments/fragments)
itags (enum, default: strict): tag injection mode
* none: do not inject tags
* strict: only inject recognized itunes tags
* all: inject all possible tags
keep_utc (bool, default: false): force all new files and tracks to keep
the source UTC creation and modification times
pps_inband (bool, default: no): when .I xps_inband is set, inject PPS
in each non SAP 1/2/3 sample
moovpad (uint, default: 0): insert free box of given size after moov
for future in-place editing
cmaf (enum, default: no): use CMAF guidelines (turns on mvex,
truns_first, strun, straf, tfdt_traf, chain_sidx and restricts
subs_sidx to -1 or 0)
* no: CMAF not enforced
* cmfc: use CMAF cmfc guidelines
* cmf2: use CMAF cmf2 guidelines (turns on nofragdef)
pad_sparse (bool, default: true): inject sample with no data (size 0)
to keep durations in unknown sparse text and metadata tracks
force_dv (bool, default: false): force DV sample entry types even when
AVC/HEVC compatibility is signaled
tsalign (bool, default: true): enable timeline realignment to 0 for
first sample in fragmented mode
rfqcp
Description: QCP reframer
This filter parses QCP files/data and outputs corresponding audio PID
and frames.
Options (expert):
index (dbl, default: 1.0): indexing window length
rfh263
Description: H263 reframer
This filter parses H263 files/data and outputs corresponding visual PID
and frames.
Options (expert):
fps (frac, default: 15000/1000): import frame rate
index (dbl, default: 1.0): indexing window length
notime (bool, default: false): ignore input timestamps, rebuild from 0
rfmpgvid
Description: M1V/M2V/M4V reframer
This filter parses MPEG-1/2 and MPEG-4 part 2 video files/data and
outputs corresponding video PID and frames.
Note: The filter uses negative CTS offsets: CTS is correct, but some
frames may have DTS greater than CTS.
Options (expert):
fps (frac, default: 0/1000): import frame rate (0 default to FPS from
bitstream or 25 Hz)
index (dbl, default: -1.0): indexing window length. If 0, bitstream
is not probed for duration. A negative value skips the indexing if the
source file is larger than 20M (slows down importers) unless a play
with start range > 0 is issued
vfr (bool, default: false): set variable frame rate import
importer (bool, default: false): compatibility with old importer,
displays import results
notime (bool, default: false): ignore input timestamps, rebuild from 0
nhntr
Description: NHNT reader
This filter reads NHNT files/data to produce a media PID and frames.
NHNT documentation is available at https://wiki.gpac.io/NHNT-Format
Options (expert):
reframe (bool, default: false): force re-parsing of referenced content
index (dbl, default: 1.0): indexing window length
nhmlr
Description: NHML reader
This filter reads NHML files/data to produce a media PID and frames.
NHML documentation is available at https://wiki.gpac.io/NHML-Format
Options (expert):
reframe (bool, default: false): force re-parsing of referenced content
index (dbl, default: 1.0): indexing window length
rfnalu
Description: AVC/HEVC reframer
This filter parses AVC|H264 and HEVC files/data and outputs
corresponding video PID and frames.
This filter produces ISOBMFF-compatible output: start codes are
removed, NALU length field added and avcC/hvcC config created.
Note: The filter uses negative CTS offsets: CTS is correct, but some
frames may have DTS greater than CTS.
Options (expert):
fps (frac, default: 0/1000): import frame rate (0 default to FPS from
bitstream or 25 Hz)
index (dbl, default: -1.0): indexing window length. If 0, bitstream
is not probed for duration. A negative value skips the indexing if the
source file is larger than 20M (slows down importers) unless a play
with start range > 0 is issued
explicit (bool, default: false): use explicit layered (SVC/LHVC) import
strict_poc (enum, default: off): delay frame output of an entire GOP to
ensure CTS info is correct when POC suddenly changes
* off: disable GOP buffering
* on: enable GOP buffering, assuming no error in POC
* error: enable GOP buffering and try to detect lost frames
nosei (bool, default: false): remove all sei messages
nosvc (bool, default: false): remove all SVC/MVC/LHVC data
novpsext (bool, default: false): remove all VPS extensions
importer (bool, default: false): compatibility with old importer,
displays import results
nal_length (uint, default: 4): set number of bytes used to code length
field: 1, 2 or 4
subsamples (bool, default: false): import subsamples information
deps (bool, default: false): import sample dependency information
seirw (bool, default: true): rewrite AVC sei messages for ISOBMFF
constraints
audelim (bool, default: false): keep Access Unit delimiter in payload
notime (bool, default: false): ignore input timestamps, rebuild from 0
dv_mode (enum, default: auto): signaling for DolbyVision
* none: never signal DV profile
* auto: signal DV profile if RPU or EL are found
* clean: do not signal and remove RPU and EL NAL units
* single: signal DV profile if RPU are found and remove EL NAL units
dv_profile (uint, default: 0): profile for DolbyVision (currently
defined profiles are 4, 5, 7, 8, 9), 0 for auto-detect
dv_compatid (enum, default: auto): cross-compatibility ID for
DolbyVision
* auto: auto-detect
* none: no cross-compatibility
* hdr10: CTA HDR10, as specified by EBU TR 03
* bt709: SDR BT.709
* hlg709: HLG BT.709 gamut in ITU-R BT.2020
* hlg2100: HLG BT.2100 gamut in ITU-R BT.2020
* bt2020: SDR BT.2020
* brd: Ultra HD Blu-ray Disc HDR
bsdbg (enum, default: off): debug NAL parsing in parser@debug logs
* off: not enabled
* on: enabled
* full: enable with number of bits dumped
m2psdmx
Description: MPEG PS demultiplexer
This filter demultiplexes MPEG-2 program streams to produce media PIDs
and frames.
No options
avidmx
Description: AVI demultiplexer
This filter demultiplexes AVI files to produce media PIDs and frames.
Options (expert):
fps (frac, default: 1/0): import frame rate, default is AVI one
importer (bool, default: false): compatibility with old importer,
displays import results
noreframe (bool, default: false): skip media reframer
txtin
Description: Subtitle loader
This filter reads subtitle data from input PID to produce subtitle
frames on a single PID.
The filter supports the following formats:
* SRT: https://en.wikipedia.org/wiki/SubRip
* WebVTT: https://www.w3.org/TR/webvtt1/
* TTXT: https://wiki.gpac.io/TTXT-Format-Documentation
* QT 3GPP Text XML (TexML): Apple QT6, likely deprecated
* TTML: https://www.w3.org/TR/ttml2/
* SUB: one subtitle per line formatted as {start_frame}{end_frame}text
* SSA (Substation Alpha): basic parsing support for common files
Input files must be in UTF-8 or UTF-16 format, with or without BOM. The
internal frame format is:
* WebVTT (and srt if desired): ISO/IEC 14496-30 VTT cues
* TTML: ISO/IEC 14496-30 XML subtitles
* Others: 3GPP/QT Timed Text
TTML Support
If .I ttml_split option is set, the TTML document is split in
independent time segments by inspecting all overlapping subtitles in
the body.
Empty periods in TTML will result in empty TTML documents or will be
skipped if .I no_empty option is set.
The first sample has a CTS assigned as indicated by .I ttml_cts:
- a numerator of -2 indicates the first CTS is 0
- a numerator of -1 indicates the first CTS is the first active time in
document
- a numerator >= 0 indicates the CTS to use for first sample
When TTML splitting is disabled, the duration of the TTML sample is
given by .I ttml_dur if not 0, or set to the document duration
By default, media resources are kept as declared in TTML2 documents.
ttml_embed can be used to embed inside the TTML sample the resources in