Provided by: gpac_2.2.1+dfsg1-3.1build2_amd64 
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 <head> or <body>:
- for <source>, <image>, <audio>, <font>, local URIs indicated in src will be loaded and src rewritten.
- for <data> with base64 coding, the data will be decoded, <data> element removed and parent <source>
rewritten with src attribute inserted.
The embedded data is added as a subsample to the TTML frame, and the referring elements will use
src=urn:mpeg:14496-30:N with N the index of the subsample.
A subtitle zero may be specified using .I ttml_zero. This will remove all subtitles before the given time
T0, and rewrite each subtitle begin/end T to T-T0 using millisecond accuracy.
Warning: Original time formatting (tick, frames/subframe ...) will be lost when this option is used,
converted to HH:MM:SS.ms.
The subtitle zero time must be prefixed with T when the option is not set as a global argument:
Example
gpac -i test.ttml:ttml_zero=T10:00:00 [...]
MP4Box -add test.ttml:sopt:ttml_zero=T10:00:00 [...]
gpac -i test.ttml --ttml_zero=10:00:00 [...]
gpac -i test.ttml --ttml_zero=T10:00:00 [...]
MP4Box -add test.ttml --ttml_zero=10:00:00 [...]
Simple Text Support
The text loader can convert input files in simple text streams of a single packet, by forcing the codec
type on the input:EX gpac -i test.txt:#CodecID=stxt [...]
Example
gpac fin:pck="Text Data":#CodecID=stxt [...]
The content of the source file will be the payload of the text sample. The .I stxtmod option allows
specifying WebVTT, TX3G or simple text mode for output format.
In this mode, the .I stxtdur option is used to control the duration of the generated subtitle:
- a positive value always forces the duration
- a negative value forces the duration if input packet duration is not known
Options (expert):
webvtt (bool, default: false): force WebVTT import of SRT files
nodefbox (bool, default: false): skip default text box
noflush (bool, default: false): skip final sample flush for srt
fontname (str): default font
fontsize (uint, default: 18): default font size
lang (str): default language
width (uint, default: 0): default width of text area
height (uint, default: 0): default height of text area
txtx (uint, default: 0): default horizontal offset of text area: -1 (left), 0 (center) or 1 (right)
txty (uint, default: 0): default vertical offset of text area: -1 (bottom), 0 (center) or 1 (top)
zorder (sint, default: 0): default z-order of the PID
timescale (uint, default: 1000): default timescale of the PID
ttml_split (bool, default: true): split ttml doc in non-overlapping samples
ttml_cts (lfrac, default: -1/1): first sample cts - see filter help
ttml_dur (frac, default: 0/1): sample duration when not spliting split - see filter help
ttml_embed (bool, default: false): force embedding TTML resources
ttml_zero (str): set subtitle zero time for TTML
no_empty (bool, default: false): do not send empty samples
stxtdur (frac, default: 1): duration for simple text
stxtmod (enum, default: none): simple text stream mode- none: declares output PID as simple text stream
* tx3g: declares output PID as TX3G/Apple stream
* vtt: declares output PID as WebVTT stream
ttxtdec
Description: TTXT/TX3G decoder
This filter decodes TTXT/TX3G streams into a BIFS scene graph of the compositor filter.
The TTXT documentation is available at https://wiki.gpac.io/TTXT-Format-Documentation
In stand-alone rendering (no associated video), the filter will use:
- Width and Height properties of input pid if any
- otherwise, osize option of compositor if set
- otherwise, .I txtw and .I txth
Options (expert):
texture (bool, default: false): use texturing for output text
outline (bool, default: false): draw text outline
txtw (uint, default: 400): default width in standalone rendering
txth (uint, default: 200): default height in standalone rendering
vttdec
Description: WebVTT decoder
This filter decodes WebVTT streams into a SVG scene graph of the compositor filter.
The scene graph creation is done through JavaScript.
The filter options are used to override the JS global variables of the WebVTT renderer.
In stand-alone rendering (no associated video), the filter will use:
- Width and Height properties of input pid if any
- otherwise, osize option of compositor if set
- otherwise, .I txtw and .I txth
Options (expert):
script (str, default: $GSHARE/scripts/webvtt-renderer.js): location of WebVTT SVG JS renderer
font (str, default: SANS, updatable): font
fontSize (flt, default: 20, updatable): font size
color (str, default: white, updatable): text color
lineSpacing (flt, default: 1.0, updatable): line spacing as scaling factor to font size
txtw (uint, default: 400): default width in standalone rendering
txth (uint, default: 200): default height in standalone rendering
ttmldec
Description: TTML decoder
This filter decodes TTML streams into a SVG scene graph of the compositor filter.
The scene graph creation is done through JavaScript.
The filter options are used to override the JS global variables of the TTML renderer.
In stand-alone rendering (no associated video), the filter will use:
- Width and Height properties of input pid if any
- otherwise, osize option of compositor if set
- otherwise, .I txtw and .I txth
Options (expert):
script (str, default: $GSHARE/scripts/ttml-renderer.js): location of TTML SVG JS renderer
font (str, default: SANS, updatable): font
fontSize (flt, default: 20, updatable): font size
color (str, default: white, updatable): text color
valign (enum, default: bottom, updatable): vertical alignment
* bottom: align text at bottom of text area
* center: align text at center of text area
* top: align text at top of text area
lineSpacing (flt, default: 1.0, updatable): line spacing as scaling factor to font size
txtw (uint, default: 400): default width in standalone rendering
txth (uint, default: 200): default height in standalone rendering
rtpin
Description: RTP/RTSP/SDP input
This filter handles SDP/RTSP/RTP input reading. It supports:
- SDP file reading
- RTP direct url through rtp:// protocol scheme
- RTSP session processing through rtsp:// and satip:// protocol schemes
The filter produces either PIDs with media frames, or file PIDs with multiplexed data (e.g. MPEG-2 TS).
The filter will use:
- RTSP over HTTP tunnel if server port is 80 or 8080 or if protocol scheme is rtsph://.
- RTSP over TLS if server port is 322 or if protocol scheme is rtsps://.
- RTSP over HTTPS tunnel if server port is 443 and if protocol scheme is rtsph://.
The filter will attempt reconnecting in TLS mode after two consecutive initial connection failures.
Options (expert):
src (cstr): location of source content (SDP, RTP or RTSP URL)
firstport (uint, default: 0): default first port number to use (0 lets the filter decide)
ifce (str): default interface IP to use for multicast. If NULL, the default system
interface will be used
ttl (uint, default: 127, minmax: 0-127): multicast TTL
reorder_len (uint, default: 1000): reorder length in packets
reorder_delay (uint, default: 50): max delay in RTP re-orderer, packets will be dispatched after that
block_size (uint, default: 0x100000): buffer size for RTP/UDP or RTSP when interleaved
disable_rtcp (bool, default: false): disable RTCP reporting
nat_keepalive (uint, default: 0): delay in ms of NAT keepalive, disabled by default (except for SatIP,
set to 30s by default)
force_mcast (str): force multicast on indicated IP in RTSP setup
use_client_ports (bool, default: false): force using client ports (hack for some RTSP servers overriding
client ports)
bandwidth (uint, default: 0): set bandwidth param for RTSP requests
default_port (uint, default: 554, minmax: 0-65535): set default RTSP port
satip_port (uint, default: 1400, minmax: 0-65535): set default port for SATIP
transport (enum, default: auto): set RTP over RTSP
* auto: set interleave on if HTTP tunnel is used, off otherwise and retry in interleaved mode if UDP
timeout
* tcp: enable RTP over RTSP
* udp: disable RTP over RTSP
udp_timeout (uint, default: 10000): default timeout before considering UDP is down
rtcp_timeout (uint, default: 5000): default timeout for RTCP traffic in ms. After this timeout, playback
will start out of sync. If 0 always wait for RTCP
first_packet_drop (uint, default: 0, updatable): set number of first RTP packet to drop (0 if no drop)
frequency_drop (uint, default: 0, updatable): drop 1 out of N packet (0 disable dropping)
loss_rate (sint, default: -1, updatable): loss rate to signal in RTCP, -1 means real loss rate, otherwise
a per-thousand of packet lost
user_agent (str, default: $GUA): user agent string, by default solved from GPAC preferences
languages (str, default: $GLANG): user languages, by default solved from GPAC preferences
stats (uint, default: 500): update statistics to the user every given MS (0 disables reporting)
max_sleep (sint, default: 1000): set max sleep in milliseconds:
- a negative value -N means to always sleep for N ms
- a positive value N means to sleep at most N ms but will sleep less if frame duration is shorter
rtcpsync (bool, default: true): use RTCP to adjust synchronization
forceagg (bool, default: false): force RTSP control aggregation (patch for buggy servers)
ssm (strl): list of IP to include for source-specific multicast
ssmx (strl): list of IP to exclude for source-specific multicast
fout
Description: File output
This filter is used to write data to disk, and does not produce any output PID.
In regular mode, the filter only accept PID of type file. It will dump to file incoming packets (stream
type file), starting a new file for each packet having a frame_start flag set, unless operating in .I cat
mode.
If the output file name is std or stdout, writes to stdout.
The output file name can use gpac templating mechanism, see gpac -h doc.The filter watches the property
FileNumber on incoming packets to create new files.
Discard sink mode
When the destination is null, the filter is a sink dropping all input packets.
In this case it accepts ANY type of input PID, not just file ones.
HTTP streaming recording
When recording a DASH or HLS session, the number of segments to keep per quality can be set using .I
max_cache_segs.
- value 0 keeps everything (default behaviour)
- a negative value N will keep -N files regardless of the time-shift buffer value
- a positive value N will keep MAX(N, time-shift buffer) files
Example
gpac -i LIVE_MPD dashin:forward=file -o rec/$File$:max_cache_segs=3
This will force keeping a maximum of 3 media segments while recording the DASH session.
Options (expert):
dst (cstr): location of destination file
append (bool, default: false): open in append mode
dynext (bool, default: false): indicate the file extension is set by filter chain, not dst
start (dbl, default: 0.0): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
speed (dbl, default: 1.0): set playback speed when vsync is on. If negative and start is 0, start is
set to -1
ext (cstr): set extension for graph resolution, regardless of file extension
mime (cstr): set mime type for graph resolution
cat (enum, default: none): cat each file of input PID rather than creating one file per filename
* none: never cat files
* auto: only cat if files have same names
* all: always cat regardless of file names
ow (bool, default: true): overwrite output if existing
mvbk (uint, default: 8192): block size used when moving parts of the file around in patch mode
redund (bool, default: false): keep redundant packet in output file
max_cache_segs (sint, default: 0): maximum number of segments cached per HAS quality when recording live
sessions (0 means no limit)
uflatm
Description: Raw AAC to LATM writer
This filter converts AAC streams into LATM encapsulated data.
Options (expert):
fdsi (frac, default: 0): set delay between two LATM Audio Config
ufadts
Description: ADTS writer
This filter converts AAC streams into ADTS encapsulated data.
Options (expert):
mpeg2 (enum, default: auto): signal as MPEG2 AAC
* auto: selects based on AAC profile
* no: always signals as MPEG-4 AAC
* yes: always signals as MPEG-2 AAC
ufmhas
Description: MHAS writer
This filter converts MPEG-H Audio streams into MHAS encapsulated data.
Options (expert):
syncp (bool, default: yes): if set, insert sync packet at each frame, otherwise only at SAP
reframer
Description: Media Reframer
This filter provides various tools on inputs:
- ensure reframing (1 packet = 1 Access Unit)
- optionally force decoding
- real-time regulation
- packet filtering based on SAP types or frame numbers
- time-range extraction and splitting
This filter forces input PIDs to be properly framed (1 packet = 1 Access Unit).
It is typically needed to force remultiplexing in file to file operations when source and destination
files use the same format.
SAP filtering
The filter can remove packets based on their SAP types using .I saps option.
For example, this can be used to extract only the key frame (SAP 1,2,3) of a video to create a trick mode
version.
Frame filtering
This filter can keep only specific Access Units of the source using .I frames option.
For example, this can be used to extract only specific key pictures of a video to create a HEIF
collection.
Frame decoding
This filter can force input media streams to be decoded using the .I raw option.
Example
gpac -i m.mp4 reframer:raw=av [dst]
Real-time Regulation
The filter can perform real-time regulation of input packets, based on their timescale and timestamps.
For example to simulate a live DASH:
Example
gpac -i m.mp4 reframer:rt=on -o live.mpd:dynamic
Range extraction
The filter can perform time range extraction of the source using .I xs and .I xe options.
The formats allowed for times specifiers are:
* 'T'H:M:S, 'T'M:S: specify time in hours, minutes, seconds
* 'T'H:M:S.MS, 'T'M:S.MS, 'T'S.MS: specify time in hours, minutes, seconds and milliseconds
* INT, FLOAT, NUM/DEN: specify time in seconds (number or fraction)
* 'D'INT, 'D'FLOAT, 'D'NUM/DEN: specify end time as offset to start time in seconds (number or fraction)
- only valid for .I xe
* 'F'NUM: specify time as frame number
* XML DateTime: specify absolute UTC time
In this mode, the timestamps are rewritten to form a continuous timeline, unless .I xots is set.
When multiple ranges are given, the filter will try to seek if needed and supported by source.
Example
gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10,T00:02:00:xe=T00:00:20,T00:01:20 [dst]
This will extract the time ranges [10s,20s], [1m10s,1m20s] and all media starting from 2m
If no end range is found for a given start range:
- if a following start range is set, the end range is set to this next start
- otherwise, the end range is open
Example
gpac -i m.mp4 reframer:xs=0,10,25:xe=5,20 [dst]
This will extract the time ranges [0s,5s], [10s,20s] and all media starting from 25s
Example
gpac -i m.mp4 reframer:xs=0,10,25 [dst]
This will extract the time ranges [0s,10s], [10s,25s] and all media starting from 25s
It is possible to signal range boundaries in output packets using .I splitrange.
This will expose on the first packet of each range in each PID the following properties:
* `FileNumber`: starting at 1 for the first range, to be used as replacement for $num$ in templates
* `FileSuffix`: corresponding to StartRange_EndRange or StartRange for open ranges, to be used as
replacement for $FS$ in templates
Example
gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10:xe=T00:00:20:splitrange -o dump_$FS$.264 [dst]
This will create two output files dump_T00.00.10_T00.02.00.264 and dump_T00.01.10.264.
Note: The : and / characters are replaced by . in FileSuffix property.
It is possible to modify PID properties per range using .I props. Each set of property must be specified
using the active separator set.
Warning: The option must be escaped using double separators in order to be parsed properly.
Example
gpac -i m.mp4 reframer:xs=0,30::props=#Period=P1,#Period=P2:#foo=bar [dst]
This will assign to output PIDs
* during the range [0,30]: property Period to P1
* during the range [30, end]: properties Period to P2 and property foo to bar
For uncompressed audio PIDs, input frame will be split to closest audio sample number.
When .I xround is set to seek, the following applies:
- a single range shall be specified
- the first I-frame preceding or matching the range start is used as split point
- all packets before range start are marked as seek points
- packets overlapping range start are forwarded with a SkipBegin property set to the amount of media to
skip
- packets overlapping range end are forwarded with an adjusted duration to match the range end
This mode is typically used to extract a range in a frame/sample accurate way, rather than a GOP-aligned
way.
When .I xround is not set to seek, compressed audio streams will still use seek mode.
Consequently, these streams will have modified edit lists in ISOBMFF which might not be properly handled
by players.
This can be avoided using .I no_audio_seek, but this will introduce audio delay.
UTC-based range extraction
The filter can perform range extraction based on UTC time rather than media time. In this mode, the end
time must be:
* a UTC date: range extraction will stop after this date
* a time in second: range extraction will stop after the specified duration
The UTC reference is specified using .I utc_ref.
If UTC signal from media source is used, the filter will probe for .I utc_probe before considering the
source has no UTC signal.
The properties SenderNTP and, if absent, UTC of source packets are checked for establishing the UTC
reference.
Other split actions
The filter can perform splitting of the source using .I xs option.
The additional formats allowed for .I xs option are:
* `SAP`: split source at each SAP/RAP
* `D`VAL: split source by chunks of VAL seconds
* `D`NUM/DEN: split source by chunks of NUM/DEN seconds
* `S`VAL: split source by chunks of estimated size VAL bytes (can use property multipliers, e.g. m)
Note: In these modes, .I splitrange and .I xadjust are implicitly set.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
rt (enum, default: off): real-time regulation mode of input
* off: disables real-time regulation
* on: enables real-time regulation, one clock per PID
* sync: enables real-time regulation one clock for all PIDs
saps (uintl, minmax: 0|1|2|3|4): list of SAP types (0,1,2,3,4) to forward, other packets are dropped
(forwarding only sap 0 will break the decoding)
refs (bool, default: false): forward only frames used as reference frames, if indicated in the input
stream
speed (dbl, default: 0.0): speed for real-time regulation mode, a value of 0 uses speed from play
commands
raw (enum, default: no): force input AV streams to be in raw format
* no: do not force decoding of inputs
* av: force decoding of audio and video inputs
* a: force decoding of audio inputs
* v: force decoding of video inputs
frames (sintl): drop all except listed frames (first being 1). A negative value -V keeps
only first frame every V frames
xs (strl): extraction start time(s)
xe (strl): extraction end time(s). If less values than start times, the last time
interval extracted is an open range
xround (enum, default: before): adjust start time of extraction range to I-frame
* before: use first I-frame preceding or matching range start
* seek: see filter help
* after: use first I-frame (if any) following or matching range start
* closest: use I-frame closest to range start
xadjust (bool, default: false): adjust end time of extraction range to be before next I-frame
xots (bool, default: false): keep original timestamps after extraction
nosap (bool, default: false): do not cut at SAP when extracting range (may result in broken streams)
splitrange (bool, default: false): signal file boundary at each extraction first packet for template-base
file generation
seeksafe (dbl, default: 10.0): rewind play requests by given seconds (to make sure the I-frame preceding
start is catched)
tcmdrw (bool, default: true): rewrite TCMD samples when splitting
props (strl): extra output PID properties per extraction range
no_audio_seek (bool, default: false): disable seek mode on audio streams (no change of priming duration)
probe_ref (bool, default: false): allow extracted range to be longer in case of B-frames with reference
frames presented outside of range
utc_ref (enum, default: any): set reference mode for UTC range extraction
* local: use UTC of local host
* any: use UTC of media, or UTC of local host if not found in media after probing time
* media: use UTC of media (abort if none found)
utc_probe (uint, default: 5000): timeout in milliseconds to try to acquire UTC reference from media
writegen
Description: Stream to file
Generic single stream to file converter, used when extracting/converting PIDs.
The writegen filter should usually not be explicitly loaded without a source ID specified, since the
filter would likely match any PID connection.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
pfmt (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 for raw extract. If not set, derived from extension
afmt (afmt, default: none, minmax: none,u8,s16,s16b,s24,s32,flt,dbl,u8p,s16p,s24p,s32p,fltp,dblp): audio
format for raw extract. If not set, derived from extension
decinfo (enum, default: auto): decoder config insert mode
* no: never inserted
* first: inserted on first packet
* sap: inserted at each SAP
* auto: selects between no and first based on media type
split (bool, default: false): force one file per decoded frame
frame (bool, default: false): force single frame dump with no rewrite. In this mode, all codec types are
supported
sstart (uint, default: 0): start number of frame to forward. If 0, all samples are forwarded
send (uint, default: 0): end number of frame to forward. If less than start frame, all samples
after start are forwarded
dur (frac, default: 0): duration of media to forward after first sample. If 0, all samples are
forwarded
merge_region (bool, default: false): merge TTML regions with same ID while reassembling TTML doc
ufnalu
Description: AVC/HEVC to AnnexB writer
This filter converts AVC|H264 and HEVC streams into AnnexB format, with inband parameter sets and start
codes.
Options (expert):
rcfg (bool, default: true): force repeating decoder config at each I-frame
extract (enum, default: all): layer extraction mode
* all: extracts all layers
* base: extract base layer only
* layer: extract non-base layer(s) only
delim (bool, default: true): insert AU Delimiter NAL
pps_inband (bool, default: false): inject PPS at each non SAP frame, ignored if rcfg is not set
writeqcp
Description: QCP writer
This filter converts a single QCELP, EVRC or MSV stream to a QCP output file.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
ufvtt
Description: WebVTT unframer
This filter converts a single ISOBMFF WebVTT stream to its unframed format.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
merge_cues (bool, default: true): merge VTT cues (undo ISOBMFF cue split)
nhntw
Description: NHNT writer
This filter converts a single stream to an NHNT output file.
NHNT documentation is available at https://wiki.gpac.io/NHNT-Format
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
large (bool, default: false): use large file mode
nhmlw
Description: NHML writer
This filter converts a single stream to an NHML output file.
NHML documentation is available at https://wiki.gpac.io/NHML-Format
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
dims (bool, default: false): use DIMS mode
name (str): set output name of media and info files produced
nhmlonly (bool, default: false): only dump NHML info, not media
pckp (bool, default: false): full NHML dump
chksum (enum, default: none): insert frame checksum
* none: no checksum
* crc: CRC32 checksum
* sha1: SHA1 checksum
vobsubdmx
Description: VobSub parser
This filter parses VobSub files/data to produce media PIDs and frames.
Options (expert):
blankframe (bool, default: true): force inserting a blank frame if first subpic is not at 0
avimx
Description: AVI multiplexer
This filter multiplexes raw or compressed audio and video to produce an AVI output.
Unlike other multiplexing filters in GPAC, this filter is a sink filter and does not produce any PID to
be redirected in the graph.
The filter can however use template names for its output, using the first input PID to resolve the final
name.
The filter watches the property FileNumber on incoming packets to create new files.
The filter will look for property AVIType set on the input stream.
The value can either be a 4CC or a string, indicating the mux format for the PID.
If the string is prefixed with + and the decoder configuration is present and formatted as an ISOBMFF
box, the box header will be removed.
Options (expert):
dst (cstr): location of destination file
fps (frac, default: 25/1): default framerate if none indicated in stream
noraw (bool, default: false): disable raw output in AVI, only compressed ones allowed
opendml_size (luint, default: 0): force opendml format when chunks are larger than this amount (0 means
1.9Gb max size in each riff chunk)
aout
Description: Audio output
This filter writes a single uncompressed audio input PID to a sound card or other audio output device.
The longer the audio buffering .I bdur is, the longer the audio latency will be (pause/resume). The
quality of fast forward audio playback will also be degraded when using large audio buffers.
If .I clock is set, the filter will report system time (in us) and corresponding packet CTS for other
filters to use for AV sync.
Options (expert):
drv (cstr): audio driver name
bnum (uint, default: 2): number of audio buffers (0 for auto)
bdur (uint, default: 100): total duration of all buffers in ms (0 for auto)
threaded (bool, default: true): force dedicated thread creation if sound card driver is not threaded
dur (frac, default: 0): only play the specified duration
clock (bool, default: true): hint audio clock for this stream
speed (dbl, default: 1.0, updatable): set playback speed. If speed is negative and start is 0, start is
set to -1
start (dbl, default: 0.0, updatable): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
vol (uint, default: 100, minmax: 0-100, updatable): set default audio volume, as a percentage between 0
and 100
pan (uint, default: 50, minmax: 0-100, updatable): set stereo pan, as a percentage between 0 and 100, 50
being centered
buffer (uint, default: 200): set playout 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
adelay (frac, default: 0, updatable): set audio delay in sec
buffer_done (bool): buffer done indication (readonly, for user app)
rebuffer (luint): system time in us at which last rebuffer started, 0 if not rebuffering
(readonly, for user app)
media_offset (dbl, default: 0): media offset (substract this value to CTS to get media time - readonly)
ufm4v
Description: M4V writer
This filter converts MPEG-4 part 2 visual streams into writable format (reinsert decoder config).
Options (expert):
rcfg (bool, default: true): force repeating decoder config at each I-frame
ufvc1
Description: VC1 writer
This filter converts VC1 visual streams into writable format (reinsert decoder config and start codes if
needed).
Options (expert):
rcfg (bool, default: true): force repeating decoder config at each I-frame
resample
Description: Audio resampler
This filter resamples raw audio to a target sample rate, number of channels or audio format.
Options (expert):
och (uint, default: 0): desired number of output audio channels (0 for auto)
osr (uint, default: 0): desired sample rate of output audio (0 for auto)
osfmt (afmt, default: none): desired sample format of output audio (none for auto)
olayout (str, minmax:
mono,stereo,3/0.0,3/1.0,3/2.0,3/2.1,5/2.1,1+1,2/1.0,2/2.0,3/3.1,3/4.1,11/11.2,5/2.1,5/5.2,5/4.1,6/5.1,6/7.1,5/6.1,7/6.1):
desired CICP layout of output audio (null for auto)
vout
Description: Video output
This filter displays a single visual input PID in a window.
The window is created unless a window handle (HWND, xWindow, etc) is indicated in the config file (
[Temp]OSWnd=ptr).
The output uses GPAC video output module indicated in .I drv option or in the config file (see GPAC core
help).
The video output module can be further configured (see GPAC core help).
The filter can use OpenGL or 2D blit of the graphics card, depending on the OS support.
The filter can be used do dump frames as written by the graphics card (GPU read-back) using .I
dumpframes.
In this case, the window is not visible and only the listed frames are drawn to the GPU.
The pixel format of the dumped frame is always RGB in OpenGL and matches the video backbuffer format in
2D mode.
Options (expert):
drv (cstr): video driver name
vsync (bool, default: true): enable video screen sync
drop (bool, default: false, updatable): enable dropping late frames
disp (enum, default: gl): display mode
* gl: OpenGL
* pbo: OpenGL with PBO
* blit: 2D hardware blit
* soft: software blit
start (dbl, default: 0.0, updatable): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
dur (lfrac, default: 0): only play the specified duration
speed (dbl, default: 1.0, updatable): set playback speed when vsync is on. If speed is negative and start
is 0, start is set to -1
hold (dbl, default: 1.0): number of seconds to hold display for single-frame streams (a negative
value force a hold on last frame for single or multi-frames streams)
linear (bool, default: false): use linear filtering instead of nearest pixel for GL mode
back (uint, default: 0x808080): back color for transparent images
wsize (v2di, default: -1x-1): default init window size
- 0x0 holds the window size of the first frame
- negative values indicate video media size
wpos (v2di, default: -1x-1): default position (0,0 top-left)
vdelay (frac, default: 0, updatable): set delay in sec, positive value displays after audio clock
hide (bool, default: false): hide output window
fullscreen (bool, default: false, updatable): use fullscreen
buffer (uint, default: 100): set playout 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
dumpframes (uintl): ordered list of frames to dump, 1 being first frame. Special value 0 means
dump all frames
out (str, default: dump): radical of dump frame filenames. If no extension provided, frames are
exported as $OUT_%d.PFMT
async (bool, default: true): sync video to audio output if any
owsize (v2di): output window size (readonly)
buffer_done (bool): buffer done indication (readonly)
rebuffer (luint): system time in us at which last rebuffer started, 0 if not rebuffering
(readonly)
vjs (bool, default: true): use default JS script for vout control
media_offset (dbl, default: 0): media offset (substract this value to CTS to get media time - readonly)
wid (uint, default: 0): window id (readonly)
vflip (enum, default: no, updatable): flip video (GL only)
* no: no flipping
* v: vertical flip
* h: horizontal flip
* vh: horizontal and vertical
* hv: same as vh
vrot (enum, default: 0, updatable): rotate video by given angle
* 0: no rotation
* 90: rotate 90 degree counter clockwise
* 180: rotate 180 degree
* 270: rotate 90 degree clockwise
vcrop
Description: Video crop
This filter is used to crop raw video data.
Options (expert):
wnd (str): size of output to crop, indicated as TxLxWxH. If % is indicated after a
number, the value is in percent of the source width (for L and W) or height (for T and H). An absolute
offset (+x, -x) can be added after percent
copy (bool, default: false): copy the source pixels. By default the filter will try to forward crop
frames by adjusting offsets and strides of the source if possible (window contained in frame)
round (enum, default: up): adjust dimension to be a multiple of 2
* up: up rounding
* down: down rounding
* allup: up rounding on formats that do not require it (RGB, YUV444)
* alldown: down rounding on formats that do not require it (RGB, YUV444)
vflip
Description: Video flip
This filter flips uncompressed video frames vertically, horizontally, in both directions or no flip
Options (expert):
mode (enum, default: vert, updatable): flip mode
* off: no flipping (passthrough)
* vert: vertical flip
* horiz: horizontal flip
* both: horizontal and vertical flip
rfrawvid
Description: RAW video reframer
This filter parses raw YUV and RGB files/data and outputs corresponding raw video PID and frames.
The filter also parses YUV4MPEG format.
Options (expert):
size (v2di, default: 0x0): source video resolution
spfmt (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):
source pixel format. When not set, derived from file extension
fps (frac, default: 25/1): number of frames per second
copy (bool, default: false): copy source bytes into output frame. If not set, source bytes are
referenced only
rfpcm
Description: PCM reframer
This filter parses raw PCM file/data or WAVE files and outputs corresponding raw audio PID and frames.
Options (expert):
sr (uint, default: 44100): sample rate
safmt (afmt, default: none, minmax: none,u8,s16,s16b,s24,s32,flt,dbl,u8p,s16p,s24p,s32p,fltp,dblp): audio
format
ch (uint, default: 2): number of channels
framelen (uint, default: 1024): number of samples to put in one audio frame. For planar formats, indicate
plane size in samples
jpgenc
Description: JPG encoder
This filter encodes a single uncompressed video PID to JPEG using libjpeg.
Options (expert):
dctmode (enum, default: fast): type of DCT used
* slow: precise but slow integer DCT
* fast: less precise but faster integer DCT
* float: float DCT
quality (uint, default: 100, minmax: 0-100, updatable): compression quality
pngenc
Description: PNG encoder
This filter encodes a single uncompressed video PID to PNG using libpng.
No options
rewind
Description: Audio/Video rewinder
This filter reverses audio and video frames in negative playback speed.
The filter is in passthrough if speed is positive. Otherwise, it reverts decoded GOPs for video, or
revert samples in decoded frame for audio (not really nice for most codecs).
Options (expert):
rbuffer (uint, default: 100): size of video rewind buffer in frames. If more frames than this, flush is
performed
flist
Description: Sources concatenator
This filter can be used to play playlist files or a list of sources.
The filter loads any source supported by GPAC: remote or local files or streaming sessions (TS, RTP, DASH
or other).
The filter demultiplexes inputs and recomputes input timestamps into a continuous timeline.
At each new source, the filter tries to remap input PIDs to already declared output PIDs of the same
type, if any, or declares new output PIDs otherwise. If no input PID matches the type of an output, no
packets are send for that PID.
Source list mode
The source list mode is activated by using flist:srcs=f1[,f2], where f1 can be a file or a directory to
enumerate.
The syntax for directory enumeration is:
* dir, dir/ or dir/*: enumerates everything in directory dir
* foo/*.png: enumerates all files with extension png in directory foo
* foo/*.png;*.jpg: enumerates all files with extension png or jpg in directory foo
The resulting file list can be sorted using .I fsort.
If the sort mode is datex and source files are images or single frame files, the following applies:
- options .I floop, .I revert and .I fdur are ignored
- the files are sorted by modification time
- the first frame is assigned a timestamp of 0
- each frame (coming from each file) is assigned a duration equal to the difference of modification time
between the file and the next file
- the last frame is assigned the same duration as the previous one
When sorting by names:
- shorter filenames are inserted before longer filenames
- alphabetical sorting is used if same filename length
Playlist mode
The playlist mode is activated when opening a playlist file (m3u format, utf-8 encoding, no BOM, default
extensions m3u, txt or pl).
In this mode, directives can be given in a comment line, i.e. a line starting with # before the line with
the file name.
Lines stating with ## are ignored.
The playlist file is refreshed whenever the next source has to be reloaded in order to allow for dynamic
pushing of sources in the playlist.
If the last URL played cannot be found in the playlist, the first URL in the playlist file will be
loaded.
When .I ka is used to keep refreshing the playlist on regular basis, the playlist must end with a new
line.
Playlist refreshing will abort:
- if the input playlist has a line not ending with a LF (0 character, in order to avoid asynchronous
issues when reading the playlist.
- if the input playlist has not been modified for the .I timeout option value (infinite by default).
Playlist directives
A playlist directive line can contain zero or more directives, separated with space. The following
directives are supported:
* repeat=N: repeats N times the content (hence played N+1).
* start=T: tries to play the file from start time T seconds (double format only). This may not work with
some files/formats not supporting seeking.
* stop=T: stops source playback after T seconds (double format only). This works on any source
(implemented independently from seek support).
* cat: specifies that the following entry should be concatenated to the previous source rather than
opening a new source. This can optionally specify a byte range if desired, otherwise the full file is
concatenated.
Note: When sources are ISOBMFF files or segments on local storage or GF_FileIO objects, the concatenation
will be automatically detected.
* srange=T: when cat is set, indicates the start T (64 bit decimal, default 0) of the byte range from the
next entry to concatenate.
* send=T: when cat is set, indicates the end T (64 bit decimal, default 0) of the byte range from the
next entry to concatenate.
* props=STR: assigns properties described in STR to all PIDs coming from the listed sources on next line.
STR is formatted according to gpac -h doc using the default parameter set.
* del: specifies that the source file(s) must be deleted once processed, true by default if .I fdel is
set.
* out=V: specifies splicing start time (cf below).
* in=V: specifies splicing end time (cf below).
* nosync: prevents timestamp adjustments when joining sources (implied if cat is set).
* keep: keeps spliced period in output (cf below).
* mark: only inject marker for the splice period and do not load any replacement content (cf below).
* sprops=STR: assigns properties described in STR to all PIDs of the main content during a splice (cf
below). STR is formatted according to gpac -h doc using the default parameter set.
* chap=NAME: assigns chapter name at the start of next URL (filter always removes source chapter names).
The following global options (applying to the filter, not the sources) may also be set in the playlist:
* ka=N: force .I ka option to N millisecond refresh.
* floop=N: set .I floop option from within playlist.
* raw: set .I raw option from within playlist.
The default behavior when joining sources is to realign the timeline origin of the new source to the
maximum time in all PIDs of the previous sources.
This may create gaps in the timeline in case previous source PIDs are not of equal duration (quite common
with most audio codecs).
Using nosync directive will disable this realignment and provide a continuous timeline but may introduce
synchronization errors depending in the source encoding (use with caution).
Source syntax
The source lines follow the usual source syntax, see gpac -h.
Additional PID properties can be added per source (see gpac -h doc), but are valid only for the current
source, and reset at next source.
The loaded sources do not inherit arguments from the parent playlist filter.
The URL given can either be a single URL, or a list of URLs separated by " && " to load several sources
for the active entry.
Warning: There shall not be any other space/tab characters between sources.
Example
audio.mp4 && video.mp4
Source with filter chains
Each URL can be followed by a chain of one or more filters, using the @ link directive as used in gpac
(see gpac -h doc).
A negative link index (e.g. @-1) can be used to setup a new filter chain starting from the last specified
source in the line.
Warning: There shall be a single character, with value space (' '), before and after each link directive.
Example
src.mp4 @ reframer:rt=on
This will inject a reframer with real-time regulation between source and flist filter.
Example
src.mp4 @ reframer:saps=1 @1 reframer:saps=0,2,3
src.mp4 @ reframer:saps=1 @-1 reframer:saps=0,2,3
This will inject a reframer filtering only SAP1 frames and a reframer filtering only non-SAP1 frames
between source and flist filter
Link options can be specified (see gpac -h doc).
Example
src.mp4 @#video reframer:rt=on
This will inject a reframer with real-time regulation between video PID of source and flist filter.
When using filter chains, the flist filter will only accept PIDs from the last declared filter in the
chain.
In order to accept other PIDs from the source, you must specify a final link directive with no following
filter.
Example
src.mp4 @#video reframer:rt=on @-1#audio
This will inject a reframer with real-time regulation between video PID of source and flist filter, and
will also allow audio PIDs from source to connect to flist filter.
The empty link directive can also be used on the last declared filter
Example
src.mp4 @ reframer:rt=on @#audio
This will inject a reframer with real-time regulation between source and flist filter and only connect
audio PIDs to flist filter.
Splicing
The playlist can be used to splice content with other content following a media in the playlist.
A source item is declared as main media in a splice operation if and only if it has an out directive set
(possibly empty).
Directive can be used for the main media except concatenation directives.
The splicing operations do not alter media frames and do not perform uncompressed domain operations such
as cross-fade or mixing.
The out (resp. in) directive specifies the media splice start (resp. end) time. The value can be
formatted as follows:
* empty: the time is not yet assigned
* `now`: the time is resolved to the next SAP point in the media
* integer, float or fraction: set time in seconds
* `+VAL`: used for in only, specify the end point as delta in seconds from the start point (VAL can be
integer, float or fraction)
* DATE: set splice time according to wall clock DATE, formatted as an XSD dateTime
The splice times (except wall clock) are expressed in the source (main media) timing, not the
reconstructed output timeline.
When a splice begins (out time reached), the source items following the main media are played until the
end of the splice or the end of the main media.
Sources used during the splice period can use directives such as start, dur or repeat.
Once a splice is done (in time reached), the main media out splice time is reset to undefined.
When the main media has undefined out or in splice times, the playlist is reloaded at each new main media
packet to check for resolved values.
- out can only be modified when no splice is active, otherwise it is ignored. If modified, it resets the
next source to play to be the one following the modified main media.
- in can only be modified when a splice is active with an undefined end time, otherwise it is ignored.
When the main media is over:
- if repeat directive is set, the main media is repeated, in and out set to their initial values and the
next splicing content is the one following the main content,
- otherwise, the next source queued is the one following the last source played during the last splice
period.
It is allowed to defined several main media in the playlist, but a main media is not allowed as media for
a splice period.
The filter will look for the property Period on the output PIDs of the main media for multi-period DASH.
If found, _N is appended to the period ID, with N starting from 1 and increased at each main media
resume.
If no Period property is set on main or spliced media, period switch can still be forced using .I
-pswitch DASH option.
If mark directive is set for a main media, no content replacement is done and the splice boundaries will
be signaled in the main media.
If keep directive is set for a main media, the main media is forwarded along with the replacement
content.
When mark or keep directives are set, it is possible to alter the PID properties of the main media using
sprops directive.
Example
#out=2 in=4 mark sprops=#xlink=http://foo.bar/
src:#Period=main
This will inject property xlink on the output PIDs in the splice zone (corresponding to period main_2)
but not in the rest of the main media.
Directives mark, keep and sprops are reset at the end of the splice period.
Options (expert):
floop (sint, default: 0): loop playlist/list of files, 0 for one time, n for n+1 times, -1 for
indefinitely
srcs (strl): list of files to play
fdur (frac, default: 1/25): frame duration for source files with a single frame (0/NaN fraction means
reuse source timing which is usually not set!)
revert (bool, default: false): revert list of files (.I srcs, not playlist)
timescale (uint, default: 0): force output timescale on all PIDs (0 uses the timescale of the first PID
found)
ka (uint, default: 0): keep playlist alive (disable loop), waiting for a new input to be added or
#end directive to end playlist. The value specifies the refresh rate in ms
timeout (luint, default: -1): timeout in ms after which the playlist is considered dead (-1 means
indefinitely)
fsort (enum, default: no): sort list of files
* no: no sorting, use default directory enumeration of OS
* name: sort by alphabetical name
* size: sort by increasing size
* date: sort by increasing modification time
* datex: sort by increasing modification time
sigcues (bool, default: false): inject CueStart property at each source begin (new or repeated) for
DASHing
fdel (bool, default: false): delete source files after processing in playlist mode (does not delete the
playlist)
raw (enum, default: no): force input AV streams to be in raw format
* no: do not force decoding of inputs
* av: force decoding of audio and video inputs
* a: force decoding of audio inputs
* v: force decoding of video inputs
m2tsmx
Description: MPEG-2 TS multiplexer
This filter multiplexes one or more input PIDs into a MPEG-2 Transport Stream multiplex.
PID selection
The MPEG-2 TS multiplexer assigns M2TS PID for media streams using the PID of the PMT plus the stream
index.
For example, the default config creates the first program with a PMT PID 100, the first stream will have
a PID of 101.
Streams are grouped in programs based on input PID property ServiceID if present. If absent, stream will
go in the program with service ID as indicated by .I sid option.
- .I name option is overridden by input PID property ServiceName.
- .I provider option is overridden by input PID property ServiceProvider.
- .I pcr_offset option is overridden by input PID property "tsmux:pcr_offset"
- .I first_pts option is overridden by input PID property "tsmux:force_pts"
- .I temi option is overridden by input PID property "tsmux:temi"
Time and External Media Information (TEMI)
The .I temi option allows specifying a list of URLs or timeline IDs to insert in streams of a program.
One or more TEMI timeline can be specified per PID.
The syntax is a comma-separated list of one or more TEMI description.
Each TEMI description is formatted as ID_OR_URL or #OPT1[#OPT2]#ID_OR_URL. Options are:
* S`N`: indicate the target service with ID N
* T`N`: set timescale to use (default: PID timescale)
* D`N`: set delay in ms between two TEMI url descriptors (default 1000)
* O`N`: set offset (max 64 bits) to add to TEMI timecodes (default 0). If timescale is not specified,
offset value is in ms, otherwise in timescale units.
* I`N`: set initial value (max 64 bits) of TEMI timecodes. If not set, initial value will match first
packet CTS. If timescale is not specified, value is in PID timescale units, otherwise in specified
timescale units.
* P`N`: indicate target PID in program. Possible values are
* `V`: only insert for video streams.
* `A`: only insert for audio streams.
* `T`: only insert for text streams.
* N: only insert for stream with index N (0-based) in the program.
* L`C`: set 64bit timecode signaling. Possible values for C are:
* `A`: automatic switch between 32 and 64 bit depending on timecode value (default if not specified).
* `Y`: use 64 bit signaling only.
* `N`: use 32 bit signaling only and wrap around timecode value.
* N: insert NTP timestamp in TEMI timeline descriptor
* ID_OR_URL: If number, indicate the TEMI ID to use for external timeline. Otherwise, give the URL to
insert
Example
temi="url"
Inserts a TEMI URL+timecode in the each stream of each program.
Example
temi="#P0#url,#P1#4"
Inserts a TEMI URL+timecode in the first stream of all programs and an external TEMI with ID 4 in the
second stream of all programs.
Example
temi="#P0#2,#P0#url,#P1#4"
Inserts a TEMI with ID 2 and a TEMI URL+timecode in the first stream of all programs, and an external
TEMI with ID 4 in the second stream of all programs.
Example
temi="#S20#4,#S10#URL"
Inserts an external TEMI with ID 4 in the each stream of program with ServiceID 20 and a TEMI URL in each
stream of program with ServiceID 10.
Example
temi="#N#D500#PV#T30000#4"
Inserts an external TEMI with ID 4 and timescale 30000, NTP injection and carousel of 500 ms in the video
stream of all programs.
Warning: multipliers (k,m,g) are not supported in TEMI options.
Adaptive Streaming
In DASH and HLS mode:
- the PCR is always initialized at 0, and .I flush_rap is automatically set.
- unless nb_pack is specified, 200 TS packets will be used as pack output in DASH mode.
- pes_pack=none is forced since some demultiplexers have issues with non-aligned ADTS PES.
The filter watches the property FileNumber on incoming packets to create new files, or new segments in
DASH mode.
The filter will look for property M2TSRA set on the input stream.
The value can either be a 4CC or a string, indicating the MP2G-2 TS Registration tag for unknown media
types.
Options (expert):
breq (uint, default: 100): buffer requirements in ms for input PIDs
pmt_id (uint, default: 100): define the ID of the first PMT to use in the mux
rate (uint, default: 0): target rate in bps of the multiplex. If not set, variable rate is used
pmt_rate (uint, default: 200): interval between PMT in ms
pat_rate (uint, default: 200): interval between PAT in ms
first_pts (luint, default: 0): force PTS value of first packet, in 90kHz
pcr_offset (luint, default: -1): offset all timestamps from PCR by V, in 90kHz (default value is computed
based on input media)
mpeg4 (enum, default: none): force usage of MPEG-4 signaling (IOD and SL Config)
* none: disables 4on2
* full: sends AUs as SL packets over section for OD, section/pes for scene (cf bifs_pes)
* scene: sends only scene streams as 4on2 but uses regular PES without SL for audio and video
pmt_version (uint, default: 200): set version number of the PMT
disc (bool, default: false): set the discontinuity marker for the first packet of each stream
repeat_rate (uint, default: 0): interval in ms between two carousel send for MPEG-4 systems (overridden
by CarouselRate PID property if defined)
repeat_img (uint, default: 0): interval in ms between re-sending (as PES) of single-image streams (if 0,
image data is sent once only)
max_pcr (uint, default: 100): set max interval in ms between 2 PCR
nb_pack (uint, default: 4): pack N TS packets in output packets
pes_pack (enum, default: audio): set AU to PES packing mode
* audio: will pack only multiple audio AUs in a PES
* none: make exactly one AU per PES
* all: will pack multiple AUs per PES for all streams
realtime (bool, default: false): use real-time output
bifs_pes (enum, default: off): select BIFS streams packetization (PES vs sections)
* on: uses BIFS PES
* off: uses BIFS sections
* copy: uses BIFS PES but removes timestamps in BIFS SL and only carries PES timestamps
flush_rap (bool, default: false): force flushing mux program when RAP is found on video, and injects PAT
and PMT before the next video PES begin
pcr_only (bool, default: false): enable PCR-only TS packets
pcr_init (lsint, default: -1): set initial PCR value for the programs. A negative value means random
value is picked
sid (uint, default: 0): set service ID for the program
name (str): set service name for the program
provider (str): set service provider name for the program
sdt_rate (uint, default: 0): interval in ms between two DVB SDT tables (if 0, SDT is disabled)
temi (str): insert TEMI time codes in adaptation field
log_freq (uint, default: 500): delay between logs for realtime mux
latm (bool, default: false): use LATM AAC encapsulation instead of regular ADTS
subs_sidx (sint, default: -1): number of subsegments per sidx (negative value disables sidx)
dasher
Description: DASH and HLS segmenter
This filter provides segmentation and manifest generation for MPEG-DASH and HLS formats.
The segmenter currently supports:
- MPD and m3u8 generation (potentially in parallel)
- ISOBMFF, MPEG-2 TS, MKV and raw bitstream segment formats
- override of profiles and levels in manifest for codecs
- most MPEG-DASH profiles
- static and dynamic (live) manifest offering
- context store and reload for batch processing of live/dynamic sessions
The filter does perform per-segment real-time regulation using .I sreg.
If you need per-frame real-time regulation on non-real-time inputs, insert a reframer before to perform
real-time regulation.
Example
gpac -i file.mp4 reframer:rt=on -o live.mpd:dmode=dynamic
Template strings
The segmenter uses templates to derive output file names, regardless of the DASH mode (even when
templates are not used). The default one is $File$_dash for ondemand and single file modes, and
$File$_$Number$ for separate segment files
Example
template=Great_$File$_$Width$_$Number$
If input is foo.mp4 with 640x360 video resolution, this will resolve in Great_foo_640_$Number$ for the
DASH template.
Example
template=Great_$File$_$Width$
If input is foo.mp4 with 640x360 video resolution, this will resolve in Great_foo_640.mp4 for onDemand
case.
Standard DASH replacement strings:
* $Number[%%0Nd]$: replaced by the segment number, possibly prefixed with 0
* $RepresentationID$: replaced by representation name
* $Time$: replaced by segment start time
* $Bandwidth$: replaced by representation bandwidth.
Note: these strings are not replaced in the manifest templates elements.
Additional replacement strings (not DASH, not generic GPAC replacements but may occur multiple times in
template):
* $Init=NAME$: replaced by NAME for init segment, ignored otherwise
* $XInit=NAME$: complete replace by NAME for init segment, ignored otherwise
* $Index=NAME$: replaced by NAME for index segments, ignored otherwise
* $Path=PATH$: replaced by PATH when creating segments, ignored otherwise
* $Segment=NAME$: replaced by NAME for media segments, ignored for init segments
* $FS$ (FileSuffix): replaced by _trackN in case the input is an AV multiplex, or kept empty otherwise
Note: these strings are replaced in the manifest templates elements.
PID assignment and configuration
To assign PIDs into periods and adaptation sets and configure the session, the segmenter looks for the
following properties on each input PID:
* `Representation`: assigns representation ID to input PID. If not set, the default behavior is to have
each media component in different adaptation sets. Setting the Representation allows explicit
multiplexing of the source(s)
* `Period`: assigns period ID to input PID. If not set, the default behavior is to have all media in the
same period with the same start time
* `PStart`: assigns period start. If not set, 0 is assumed, and periods appear in the Period ID
declaration order. If negative, this gives the period order (-1 first, then -2 ...). If positive, this
gives the true start time and will abort DASHing at period end
Note: When both positive and negative values are found, the by-order periods (negative) will be inserted
AFTER the timed period (positive)
* `ASID`: assigns parent adaptation set ID. If not 0, only sources with same AS ID will be in the same
adaptation set
Note: If multiple streams in source, only the first stream will have an AS ID assigned
* `xlink`: for remote periods, only checked for null PID
* `Role`, `PDesc`, `ASDesc`, `ASCDesc`, `RDesc`: various descriptors to set for period, AS or
representation
* `BUrl`: overrides segmenter [-base] with a set of BaseURLs to use for the PID (per representation)
* `Template`: overrides segmenter .I template for this PID
* `DashDur`: overrides segmenter segment duration for this PID
* `StartNumber`: sets the start number for the first segment in the PID, default is 1
* `IntraOnly`: indicates input PID follows HLS EXT-X-I-FRAMES-ONLY guidelines
* `CropOrigin`: indicates x and y coordinates of video for SRD (size is video size)
* `SRD`: indicates SRD position and size of video for SRD, ignored if CropOrigin is set
* `SRDRef`: indicates global width and height of SRD, ignored if CropOrigin is set
* `HLSMExt`: list of extensions to add to master playlist entries, ['foo','bar=val'] added as
,foo,bar=val
* `HLSVExt`: list of extensions to add to variant playlist, ['#foo','#bar=val'] added as #foo #bar=val
* Non-dash properties: Bitrate, SAR, Language, Width, Height, SampleRate, NumChannels, Language, ID,
DependencyID, FPS, Interlaced, Codec. These properties are used to setup each representation and can be
overridden on input PIDs using the general PID property settings (cf global help).
Example
gpac -i test.mp4:#Bitrate=1M -o test.mpd
This will force declaring a bitrate of 1M for the representation, regardless of actual input bitrate.
Example
gpac -i muxav.mp4 -o test.mpd
This will create un-multiplexed DASH segments.
Example
gpac -i muxav.mp4:#Representation=1 -o test.mpd
This will create multiplexed DASH segments.
Example
gpac -i m1.mp4 -i m2.mp4:#Period=Yep -o test.mpd
This will put src m1.mp4 in first period, m2.mp4 in second period.
Example
gpac -i m1.mp4:#BUrl=http://foo/bar -o test.mpd
This will assign a baseURL to src m1.mp4.
Example
gpac -i m1.mp4:#ASCDesc=<ElemName val="attval">text</ElemName> -o test.mpd
This will assign the specified XML descriptor to the adaptation set.
Note: this can be used to inject most DASH descriptors not natively handled by the segmenter.
The segmenter handles the XML descriptor as a string and does not attempt to validate it. Descriptors, as
well as some segmenter filter arguments, are string lists (comma-separated by default), so that multiple
descriptors can be added:
Example
gpac -i m1.mp4:#RDesc=<Elem attribute="1"/>,<Elem2>text</Elem2> -o test.mpd
This will insert two descriptors in the representation(s) of m1.mp4.
Example
gpac -i video.mp4:#Template=foo$Number$ -i audio.mp4:#Template=bar$Number$ -o test.mpd
This will assign different templates to the audio and video sources.
Example
gpac -i null:#xlink=http://foo/bar.xml:#PDur=4 -i m.mp4:#PStart=-1 -o test.mpd
This will insert an create an MPD with first a remote period then a regular one.
Example
gpac -i null:#xlink=http://foo/bar.xml:#PStart=6 -i m.mp4 -o test.mpd
This will create an MPD with first a regular period, dashing only 6s of content, then a remote one.
Example
gpac -i v1:#SRD=0x0x1280x360:#SRDRef=1280x720 -i v2:#SRD=0x360x1280x360 -o test.mpd
This will layout the v2 below v1 using a global SRD size of 1280x720.
The segmenter will create multiplexing filter chains for each representation and will reassign PID IDs so
that each media component (video, audio, ...) in an adaptation set has the same ID.
For HLS, the output PID will deliver the master playlist and the variant playlists.
The default variant playlist are $NAME_$N.m3u8, where $NAME is the radical of the output file name and $N
is the 1-based index of the variant.
Segmentation
The default behavior of the segmenter is to estimate the theoretical start time of each segment based on
target segment duration, and start a new segment when a packet with SAP type 1,2,3 or 4 with time greater
than the theoretical time is found.
This behavior can be changed to find the best SAP packet around a segment theoretical boundary using .I
sbound:
* `closest` mode: the segment will start at the closest SAP of the theoretical boundary
* `in` mode: the segment will start at or before the theoretical boundary
Warning: These modes will introduce delay in the segmenter (typically buffering of one GOP) and should
not be used for low-latency modes.
The segmenter can also be configured to:
- completely ignore SAP when segmenting using .I sap.
- ignore SAP on non-video streams when segmenting using .I strict_sap.
The segmenter will by default announce a new segment in the manifest(s) as soon as its size/offset is
known or its name is known, but the segment (or part in LL-HLS) may still not be completely written/sent.
This may result in temporary mismatches between segment/part size currently received versus size as
advertized in manifest.
If the target destination cannot support this, use .I seg_sync to update manifest(s) only once
segments/parts are completely flushed; this will however slightly increase the latency of manifest
updates.
Dynamic (real-time live) Mode
The dasher does not perform real-time regulation by default.
For regular segmentation, you should enable segment regulation .I sreg if your sources are not real-time.
Example
gpac -i source.mp4 -o live.mpd:segdur=2:profile=live:dmode=dynamic:sreg
For low latency segmentation with fMP4, you will need to specify the following options:
* cdur: set the fMP4 fragment duration
* asto: set the availability time offset for DASH. This value should be equal or slightly greater than
segment duration minus cdur
* llhls: enable low latency for HLS
Note: .I llhls will force CMAF to cmfc if .I cmaf is not set.
If your sources are not real-time, insert a reframer filter with real-time regulation
Example
gpac -i source.mp4 reframer:rt=on -o live.mpd:segdur=2:cdur=0.2:asto=1.8:profile=live:dmode=dynamic
This will create DASH segments of 2 seconds made of fragments of 200 ms and indicate to the client that
requests can be made 1.8 seconds earlier than segment complete availability on server.
Example
gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=br:dmode=dynamic
This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts
using byte ranges in the final segment.
Example
gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=sf:dmode=dynamic
This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts
using dedicated files.
You can combine LL-HLS and DASH-LL generation:
Example
gpac -i source.mp4 reframer:rt=on -o
live.mpd:dual:segdur=2:cdur=0.2:asto=1.8:llhls=br:profile=live:dmode=dynamic
For DASH, the filter will use the local clock for UTC anchor points in DASH.
The filter can fetch and signal clock in other ways using .I utcs.
Example
[opts]:utcs=inband
This will use the local clock and insert in the MPD a UTCTiming descriptor containing the local clock.
Example
[opts]::utcs=http://time.akamai.com[::opts]
This will fetch time from http://time.akamai.com, use it as the UTC reference for segment generation and
insert in the MPD a UTCTiming descriptor containing the time server URL.
Note: if not set as a global option using --utcs=, you must escape the url using double :: or use other
separators.
Cue-driven segmentation
The segmenter can take a list of instructions, or Cues, to use for the segmentation process, in which
case only these are used to derive segment boundaries. Cues can be set through XML files or injected in
input packets.
Cue files can be specified for the entire segmenter, or per PID using DashCue property.
Cues are given in an XML file with a root element called <DASHCues>, with currently no attribute
specified. The children are one or more <Stream> elements, with attributes:
* id: integer for stream/track/PID ID
* timescale: integer giving the units of following timestamps
* mode: if present and value is edit, the timestamp are in presentation time (edit list applied)
otherwise they are in media time
* ts_offset: integer giving a value (in timescale) to subtract to the DTS/CTS values listed
The children of <Stream> are one or more <Cue> elements, with attributes:
* sample: integer giving the sample/frame number of a sample at which splitting shall happen
* dts: long integer giving the decoding time stamp of a sample at which splitting shall happen
* cts: long integer giving the composition / presentation time stamp of a sample at which splitting shall
happen
Warning: Cues shall be listed in decoding order.
If the DashCue property of a PID equals inband, the PID will be segmented according to the CueStart
property of input packets.
This feature is typically combined with a list of files as input:
Example
gpac -i list.m3u:sigcues -o res/live.mpd
This will load the flist filter in cue mode, generating continuous timelines from the sources and
injecting a CueStart property at each new file.
If the .I cues option equals none, the DashCue property of input PIDs will be ignored.
Manifest Generation only mode
The segmenter can be used to generate manifests from already fragmented ISOBMFF inputs using .I sigfrag.
In this case, segment boundaries are attached to each packet starting a segment and used to drive the
segmentation.
This can be used with single-track ISOBMFF sources, either single file or multi file.
For single file source:
- if onDemand .I profile is requested, sources have to be formatted as a DASH self-initializing media
segment with the proper sidx.
- templates are disabled.
- .I sseg is forced for all profiles except onDemand ones.
For multi files source:
- input shall be a playlist containing the initial file followed by the ordered list of segments.
- if no .I template is provided, the full or main .I profile will be used
* if [-template]() is provided, it shall be correct: the filter will not try to guess one from the input
file names and will not validate it either.
The manifest generation-only mode supports both MPD and HLS generation.
Example
gpac -i ondemand_src.mp4 -o dash.mpd:sigfrag:profile=onDemand
This will generate a DASH manifest for onDemand Profile based on the input file.
Example
gpac -i ondemand_src.mp4 -o dash.m3u8:sigfrag
This will generate a HLS manifest based on the input file.
Example
gpac -i seglist.txt -o dash.mpd:sigfrag
This will generate a DASH manifest in Main Profile based on the input files.
Example
gpac -i seglist.txt:Template=$XInit=init$$q1/$Number$ -o dash.mpd:sigfrag:profile=live
This will generate a DASH manifest in live Profile based on the input files. The input file will contain
init.mp4, q1/1.m4s, q1/2.m4s...
Cue Generation only mode
The segmenter can be used to only generate segment boundaries from a set of inputs using .I gencues,
without generating manifests or output files.
In this mode, output PIDs are declared directly rather than redirected to media segment files.
The segmentation logic is not changed, and packets are forwarded with the same information and timing as
in regular mode.
Output PIDs are forwarded with DashCue=inband property, so that any subsequent dasher follows the same
segmentation process (see above).
The first packet in a segment has:
- property FileNumber (and, if multiple files, FileName) set as usual
- property CueStart set
- property DFPStart=0 set if this is the first packet in a period
This mode can be used to pre-segment the streams for later processing that must take place before final
dashing.
Example
gpac -i source.mp4 dasher:gencues cecrypt:cfile=roll_seg.xml -o live.mpd
This will allow the encrypter to locate dash boundaries and roll keys at segment boundaries.
Example
gpac -i s1.mp4 -i s2.mp4:#CryptInfo=clear:#Period=3 -i s3.mp4:#Period=3 dasher:gencues
cecrypt:cfile=roll_period.xml -o live.mpd
If the DRM file uses keyRoll=period, this will generate:
- first period crypted with one key
- second period clear
- third period crypted with another key
Multiplexer development considerations
Output multiplexers allowing segmented output must obey the following:
- inspect packet properties
* FileNumber: if set, indicate the start of a new DASH segment
* FileName: if set, indicate the file name. If not present, output shall be a single file. This is only
set for packet carrying the FileNumber property, and only on one PID (usually the first) for multiplexed
outputs
* IDXName: gives the optional index name. If not present, index shall be in the same file as dash
segment. Only used for MPEG-2 TS for now
* EODS: property is set on packets with no payload and no timestamp to signal the end of a DASH segment.
This is only used when stopping/resuming the segmentation process, in order to flush segments without
dispatching an EOS (see .I subdur )
- for each segment done, send a downstream event on the first connected PID signaling the size of the
segment and the size of its index if any
- for multiplexers with init data, send a downstream event signaling the size of the init and the size of
the global index if any
- the following filter options are passed to multiplexers, which should declare them as arguments:
* noinit: disables output of init segment for the multiplexer (used to handle bitstream switching with
single init in DASH)
* frag: indicates multiplexer shall use fragmented format (used for ISOBMFF mostly)
* subs_sidx=0: indicates an SIDX shall be generated - only added if not already specified by user
* xps_inband=all|no|both: indicates AVC/HEVC/... parameter sets shall be sent inband, out of band, or
both
* nofragdef: indicates fragment defaults should be set in each segment rather than in init segment
The segmenter adds the following properties to the output PIDs:
* DashMode: identifies VoD (single file with global index) or regular DASH mode used by segmenter
* DashDur: identifies target DASH segment duration - this can be used to estimate the SIDX size for
example
* LLHLS: identifies LLHLS is used; the multiplexer must send fragment size events back to the dasher, and
set LLHLSFragNum on the first packet of each fragment
* SegSync: indicates that fragments/segments must be completely flushed before sending back size events
Options (expert):
segdur (frac, default: 0/0): target segment duration in seconds. A value less than or equal to 0
defaults to 1.0 second
tpl (bool, default: true): use template mode (multiple segment, template URLs)
stl (bool, default: false): use segment timeline (ignored in on_demand mode)
dmode (enum, default: static, updatable): dash content mode
* static: static content
* dynamic: live generation
* dynlast: last call for live, will turn the MPD into static
sseg (bool, default: false): single segment is used
sfile (bool, default: false): use a single file for all segments (default in on_demand)
align (bool, default: true): enable segment time alignment between representations
sap (bool, default: true): enable splitting segments at SAP boundaries
mix_codecs (bool, default: false): enable mixing different codecs in an adaptation set
ntp (enum, default: rem): insert/override NTP clock at the beginning of each segment
* rem: removes NTP from all input packets
* yes: inserts NTP at each segment start
* keep: leaves input packet NTP untouched
no_sar (bool, default: false): do not check for identical sample aspect ratio for adaptation sets
bs_switch (enum, default: def): bitstream switching mode (single init segment)
* def: resolves to off for onDemand and inband for live
* off: disables BS switching
* on: enables it if same decoder configuration is possible
* inband: moves decoder config inband if possible
* both: inband and outband parameter sets
* pps: moves PPS and APS inband, keep VPS,SPS and DCI out of band (used for VVC RPR)
* force: enables it even if only one representation
* multi: uses multiple stsd entries in ISOBMFF
template (str): template string to use to generate segment name
segext (str): file extension to use for segments
initext (str): file extension to use for the init segment
muxtype (enum, default: auto): muxtype to use for the segments
* mp4: uses ISOBMFF format
* ts: uses MPEG-2 TS format
* mkv: uses Matroska format
* webm: uses WebM format
* ogg: uses OGG format
* raw: uses raw media format (disables multiplexed representations)
* auto: guess format based on extension, default to mp4 if no extension
rawsub (bool, default: no): use raw subtitle format instead of encapsulating in container
asto (dbl, default: 0): availabilityStartTimeOffset to use in seconds. A negative value simply
increases the AST, a positive value sets the ASToffset to representations
profile (enum, default: auto): target DASH profile. This will set default option values to ensure
conformance to the desired profile. For MPEG-2 TS, only main and live are used, others default to main
* auto: turns profile to live for dynamic and full for non-dynamic
* live: DASH live profile, using segment template
* onDemand: MPEG-DASH live profile
* main: MPEG-DASH main profile, using segment list
* full: MPEG-DASH full profile
* hbbtv1.5.live: HBBTV 1.5 DASH profile
* dashavc264.live: DASH-IF live profile
* dashavc264.onDemand: DASH-IF onDemand profile
* dashif.ll: DASH IF low-latency profile (set UTC server to time.akamai.com if none set)
profX (str): list of profile extensions, as used by DASH-IF and DVB. The string will be
colon-concatenated with the profile used
cp (enum, default: set): content protection element location
* set: in adaptation set element
* rep: in representation element
* both: in both adaptation set and representation elements
pssh (enum, default: v): storage mode for PSSH box
* f: stores in movie fragment only
* v: stores in movie only, or movie and fragments if key roll is detected
* m: stores in mpd only
* mf: stores in mpd and movie fragment
* mv: stores in mpd and movie
* n: discard pssh from mpd and segments
buf (sint, default: -100): min buffer duration in ms. negative value means percent of segment
duration (e.g. -150 = 1.5*seg_dur)
spd (sint, default: 0): suggested presentation delay in ms
timescale (sint, default: 0): set timescale for timeline and segment list/template. A value of 0 picks
up the first timescale of the first stream in an adaptation set. A negative value forces using stream
timescales for each timed element (multiplication of segment list/template/timelines). A positive value
enforces the MPD timescale
check_dur (bool, default: true): check duration of sources in period, trying to have roughly equal
duration. Enforced whenever period start times are used
skip_seg (bool, default: false): increment segment number whenever an empty segment would be produced -
NOT DASH COMPLIANT
title (str): MPD title
source (str): MPD Source
info (str): MPD info url
cprt (str): MPD copyright string
lang (str): language of MPD Info
location (strl): set MPD locations to given URL
base (strl): set base URLs of MPD
refresh (dbl, default: 0): refresh rate for dynamic manifests, in seconds (a negative value sets the
MPD duration, value 0 uses dash duration)
tsb (dbl, default: 30): time-shift buffer depth in seconds (a negative value means infinity)
subdur (dbl, default: 0): maximum duration of the input file to be segmented. This does not change
the segment duration, segmentation stops once segments produced exceeded the duration
ast (str): set start date (as xs:date, e.g. YYYY-MM-DDTHH:MM:SSZ) for live mode.
Default is now. !! Do not use with multiple periods, nor when DASH duration is not a multiple of GOP size
!!
state (str): path to file used to store/reload state info when simulating live. This is
stored as a valid MPD with GPAC XML extensions
loop (bool, default: false): loop sources when dashing with subdur and state. If not set, a new period
is created once the sources are over
split (bool, default: true): enable cloning samples for text/metadata/scene description streams,
marking further clones as redundant
hlsc (bool, default: false): insert clock reference in variant playlist in live HLS
cues (str): set cue file
strict_cues (bool, default: false): strict mode for cues, complains if splitting is not on SAP type 1/2/3
or if unused cue is found
strict_sap (enum, default: off): strict mode for sap
* off: ignore SAP types for PID other than video, enforcing _startsWithSAP=1_
* sig: same as .I off but keep _startsWithSAP_ to the true SAP value
* on: warn if any PID uses SAP 3 or 4 and switch to FULL profile
* intra: ignore SAP types greater than 3 on all media types
subs_sidx (sint, default: -1): number of subsegments per sidx. negative value disables sidx. Only used to
inherit sidx option of destination
cmpd (bool, default: false): skip line feed and spaces in MPD XML for compactness
styp (str): indicate the 4CC to use for styp boxes when using ISOBMFF output
dual (bool): indicate to produce both MPD and M3U files
sigfrag (bool): use manifest generation only mode
sbound (enum, default: out): indicate how the theoretical segment start TSS (= segment_number *
duration) should be handled
* out: segment split as soon as TSS is exceeded (TSS <= segment_start)
* closest: segment split at closest SAP to theoretical bound
* in: TSS is always in segment (TSS >= segment_start)
reschedule (bool, default: false): reschedule sources with no period ID assigned once done (dynamic mode
only)
sreg (bool, default: false): regulate the session
- when using subdur and context, only generate segments from the past up to live edge
- otherwise in dynamic mode without context, do not generate segments ahead of time
scope_deps (bool, default: true): scope PID dependencies to be within source. If disabled, PID
dependencies will be checked across all input PIDs regardless of their sources
utcs (str): URL to use as time server / UTCTiming source. Special value inband enables
inband UTC (same as publishTime), special prefix xsd@ uses xsDateTime schemeURI rather than ISO
force_flush (bool, default: false): force generating a single segment for each input. This can be useful
in batch mode when average source duration is known and used as segment duration but actual duration may
sometimes be greater
last_seg_merge (bool, default: false): force merging last segment if less than half the target duration
mha_compat (enum, default: no): adaptation set generation mode for compatible MPEG-H Audio profile
* no: only generate the adaptation set for the main profile
* comp: only generate the adaptation sets for all compatible profiles
* all: generate the adaptation set for the main profile and all compatible profiles
mname (str): output manifest name for ATSC3 multiplexing
llhls (enum, default: off): HLS low latency type
* off: do not use LL-HLS
* br: use LL-HLS with byte-range for segment parts, pointing to full segment (DASH-LL compatible)
* sf: use separate files for segment parts (post-fixed .1, .2 etc.)
* brsf: generate two sets of manifest, one for byte-range and one for files (_IF added before extension
of manifest)
hlsdrm (str): cryp file info for HLS full segment encryption
hlsx (strl): list of string to append to master HLS header before variants with
['#foo','#bar=val'] added as #foo #bar=val
ll_preload_hint (bool, default: true): inject preload hint for LL-HLS
ll_rend_rep (bool, default: true): inject rendition reports for LL-HLS
ll_part_hb (dbl, default: -1): user-defined part hold-back for LLHLS, negative value means 3 times max
part duration in session
ckurl (str): set the ClearKey URL common to all encrypted streams (overriden by CKUrl
pid property)
hls_absu (enum, default: no): use absolute url in HLS generation using first URL in base
* no: do not use absolute URL
* var: use absolute URL only in variant playlists
* mas: use absolute URL only in master playlist
* both: use absolute URL everywhere
seg_sync (bool, default: false): force waiting for last packet of fragment/segment to be written before
announcing segment in DASH/HLS playlist
cmaf (enum, default: no): use cmaf guidelines
* no: CMAF not enforced
* cmfc: use CMAF cmfc guidelines
* cmf2: use CMAF cmf2 guidelines
chain (str): URL of next MPD for regular chaining
chain_fbk (str): URL of fallback MPD
gencues (bool, default: false): only insert segment boundaries and do not generate manifests
force_init (bool, default: false): force init segment creation in bitstream switching mode
keep_src (bool, default: false): keep source URLs in manifest generation mode
gxns (bool, default: false): insert some gpac extensions in manifest (for now, only tfdt of first
segment)
dkid (enum, default: auto): control injection of default KID in MPD
* off: default KID not injected
* on: default KID always injected
* auto: default KID only injected if no key roll is detected (as per DASH-IF guidelines)
tileagg
Description: HEVC tile aggregator
This filter aggregates a set of split tiled HEVC streams (hvt1 or hvt2 in ISOBMFF) into a single HEVC
stream.
Options (expert):
tiledrop (uintl, updatable): specify indexes of tiles to drop
ttimeout (uint, default: 10000, updatable): number of milliseconds to wait until considering a tile
packet lost, 0 waits forever
tilesplit
Description: HEVC tile bitstream splitter
This filter splits an HEVC tiled stream into tiled HEVC streams (hvt1 or hvt2 in ISOBMFF).
The filter will move to passthrough mode if the bitstream is not tiled.
If the Bitrate property is set on the input PID, the output tile PIDs will have a bitrate set to (Bitrate
- 10k)/nb_opids, 10 kbps being reserved for the base.
Each tile PID will be assigned the following properties:
* `ID`: equal to the base PID ID (same as input) plus the 1-based index of the tile in raster scan order.
* `TileID`: equal to the 1-based index of the tile in raster scan order.
Warning: The filter does not check if tiles are independently-coded (MCTS) !
Warning: Support for dynamic changes of tiling grid has not been tested !
Options (expert):
tiledrop (uintl, updatable): specify indexes of tiles to drop (0-based, in tile raster scan order)
pin
Description: pipe input
This filter handles generic input pipes (mono-directional) in blocking or non blocking mode.
Warning: Input pipes cannot seek.
Data format of the pipe may be specified using extension (either in file name or through .I ext) or MIME
type through .I mime.
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.
stdin pipe
The filter can handle reading from stdin, by using - or stdin as input file name.
Example
gpac -i - vout
gpac -i stdin vout
Named pipes
The filter can handle reading from named pipes. The associated protocol scheme is pipe:// when loaded as
a generic input (e.g. -i pipe://URL where URL is a relative or absolute pipe name).
On Windows hosts, the default pipe prefix is \.ipeac if
no prefix is set.
dst=mypipe resolves in \.ipeacpipe
dst=\.ipeapppipe
resolves in \.ipeapppipe
Any destination name starting with \ is used as is, with translated in /.
Input pipes are created by default in non-blocking mode.
The filter can create the pipe if not found using .I mkp. On windows hosts, this will create a pipe
server.
On non windows hosts, the created pipe will delete the pipe file upon filter destruction.
Input pipes can be setup to run forever using .I ka. In this case:
- any potential pipe close on the writing side will be ignored
- end of stream will be triggered upon pipe close if .I sigeos is set
- final end of stream will be triggered upon session close.
This can be useful to pipe raw streams from different process into gpac:
* Receiver side: gpac -i pipe://mypipe:ext=.264:mkp:ka
* Sender side: cat raw1.264 > mypipe && gpac -i raw2.264 -o pipe://mypipe:ext=.264
The pipe input can be created in blocking mode or non-blocking mode.
Options (expert):
src (cstr): name of source pipe
block_size (uint, default: 5000): buffer size used to read pipe
ext (str): indicate file extension of pipe data
mime (str): indicate mime type of pipe data
blk (bool, default: false): open pipe in block mode
ka (bool, default: false): keep-alive pipe when end of input is detected
mkp (bool, default: false): create pipe if not found
sigeos (bool, default: false): signal end of stream whenever a pipe breaks in keep-alive mode
pout
Description: pipe output
This filter handles generic output pipes (mono-directional) in blocking mode only.
Warning: Output pipes do not currently support non blocking mode.
The associated protocol scheme is pipe:// when loaded as a generic output (e.g. -o pipe://URL where URL
is a relative or absolute pipe name).
Data format of the pipe shall be specified using extension (either in filename or through .I ext option)
or MIME type through .I mime
The pipe name indicated in .I dst can use template mechanisms from gpac, e.g. dst=pipe_$ServiceID$
On Windows hosts, the default pipe prefix is \.ipeac if
no prefix is set
dst=mypipe resolves in \.ipeacpipe
dst=\.ipeapppipe
resolves in \.ipeapppipe
Any destination name starting with \ is used as is, with translated in /
The pipe input can create the pipe if not found using .I mkp. On windows hosts, this will create a pipe
server.
On non windows hosts, the created pipe will delete the pipe file upon filter destruction.
The pipe can be kept alive after a broken pipe is detected using .I ka. This is typically used when
clients crash/exits and resumes.
When a keep-alive pipe is broken, input data is discarded and the filter will keep trashing data as fast
as possible.
It is therefore recommended to use this mode with real-time inputs (use a reframer if needed).
Options (expert):
dst (cstr): name of destination pipe
ext (str): indicate file extension of pipe data
mime (str): indicate mime type of pipe data
dynext (bool, default: false): indicate the file extension is set by filter chain, not dst
start (dbl, default: 0.0): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
speed (dbl, default: 1.0): set playback speed. If negative and start is 0, start is set to -1
mkp (bool, default: false): create pipe if not found
block_size (uint, default: 5000): buffer size used to write to pipe, windows only
ka (bool, default: false): keep pipe alive when broken pipe is detected
gsfmx
Description: GSF Multiplexer
This filter provides GSF (GPAC Serialized Format) multiplexing.
It serializes the stream states (config/reconfig/info update/remove/eos) and packets of input PIDs. This
allows either saving to file a session, or forwarding the state/data of streams to another instance of
GPAC using either pipes or sockets. Upstream events are not serialized.
The default behavior does not insert sequence numbers. When running over general protocols not ensuring
packet order, this should be inserted.
The serializer sends tune-in packets (global and per PID) at the requested carousel rate - if 0, no
carousel. These packets are marked as redundant so that they can be discarded by output filters if
needed.
Encryption
The stream format can be encrypted in AES 128 CBC mode. For all packets, the packet header (header, size,
frame size/block offset and optional seq num) are in the clear and the following bytes until the last
byte of the last multiple of block size (16) fitting in the payload are encrypted.
For data packets, each fragment is encrypted individually to avoid error propagation in case of losses.
For other packets, the entire packet is encrypted before fragmentation (fragments cannot be processed
individually).
For header/tunein packets, the first 25 bytes after the header are in the clear (signature,version,IV and
pattern).
The .I IV is constant to avoid packet overhead, randomly generated if not set and sent in the initial
stream header. Pattern mode can be used (cf CENC cbcs) to encrypt K block and leave N blocks in the
clear.
Filtering properties
The header/tunein packet may get quite big when all PID properties are kept. In order to help reduce its
size, the .I minp option can be used: this will remove all built-in properties marked as droppable (cf
property help) as well as all non built-in properties.
The .I skp option may also be used to specify which property to drop:
Example
skp="4CC1,Name2
This will remove properties of type 4CC1 and properties (built-in or not) of name Name2.
File mode
By default the filter only accepts framed media streams as input PID, not files. This can be changed by
explicitly loading the filter with .I ext or .I dst set.
Example
gpac -i source.mp4 gsfmx:dst=manifest.mpd -o dump.gsf
This will DASH the source and store every files produced as PIDs in the GSF mux.
In order to demultiplex such a file, the gsfdmxfilter will likely need to be explicitly loaded:
Example
gpac -i mux.gsf gsfdmx -o dump/$File$:dynext:clone
This will extract all files from the GSF mux.
By default when working in file mode, the filter only accepts PIDs of type file as input.
To allow a mix of files and streams, use .I mixed:
Example
gpac -i source.mp4 gsfmx:dst=manifest.mpd:mixed -o dump.gsf
This will DASH the source, store the manifest file and the media streams with their packet properties in
the GSF mux.
Options (expert):
sigsn (bool, default: false): signal packet sequence number after header field and before size field.
Sequence number is per PID, encoded on 16 bits. Header packet does not have a SN
sigdur (bool, default: true): signal duration
sigbo (bool, default: false): signal byte offset
sigdts (bool, default: true): signal decoding timestamp
dbg (enum, default: no): set debug mode
* no: disable debug
* nodata: force packet size to 0
* nopck: skip packet
key (mem): encrypt packets using given key
IV (mem): set IV for encryption - a constant IV is used to keep packet overhead
small (cbcs-like)
pattern (frac, default: 1/0): set nb_crypt / nb_skip block pattern. default is all encrypted
mpck (uint, default: 0): set max packet size. 0 means no fragmentation (each AU is sent in one
packet)
magic (str): magic string to append in setup packet
skp (str): comma separated list of PID property names to skip
minp (bool, default: false): include only the minimum set of properties required for stream processing
crate (dbl, default: 0): carousel period for tune-in info in seconds
ext (str): file extension for file mode
dst (str): target URL in file mode
mixed (bool, default: false): allow GSF to contain both files and media streams
gsfdmx
Description: GSF demultiplexer
This filter provides GSF (GPAC Serialized Format) demultiplexing.
It de-serializes the stream states (config/reconfig/info update/remove/eos) and packets in the GSF
bytestream.
This allows either reading a session saved to file, or receiving the state/data of streams from another
instance of GPAC using either pipes or sockets
The stream format can be encrypted in AES 128 CBC mode, in which case the demultiplexing filter must be
given a 128 bit key.
Options (expert):
key (mem): key for decrypting packets
magic (str): magic string to check in setup packet
mq (uint, default: 4): set max packet queue length for loss detection. 0 will flush incomplete
packet when a new one starts
pad (uint, default: 0, minmax: 0-255): byte value used to pad lost packets
sockout
Description: UDP/TCP output
This filter handles generic output sockets (mono-directional) in blocking mode only.
The filter can work in server mode, waiting for source connections, or in client mode, directly
connecting to a server.
In server mode, the filter can be instructed to keep running at the end of the stream.
In server mode, the default behavior is to keep input packets when no more clients are connected; this
can be adjusted though the .I kp option, however there is no realtime regulation of how fast packets are
dropped.
If your sources are not real time, consider adding a real-time scheduler in the chain (cf reframer
filter), or set the send .I rate option.
- UDP sockets are used for destinations URLs formatted as udp://NAME
- TCP sockets are used for destinations URLs formatted as tcp://NAME
- UDP unix domain sockets are used for destinations URLs formatted as udpu://NAME
- TCP unix domain sockets are used for destinations 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 escape, e.g. udp://localhost:1234[:gpac:opts]
The socket output can be configured to drop or revert packet order for test purposes.
A window size in packets is specified as the drop/revert fraction denominator, and the index of the
packet to drop/revert is given as the numerator/
If the numerator is 0, a packet is randomly chosen in that window.
Example
:pckd=4/10
This drops every 4th packet of each 10 packet window.
Example
:pckr=0/100
This reverts the send order of one random packet in each 100 packet window.
Options (expert):
dst (cstr): URL of destination
sockbuf (uint, default: 65536): block size used to read file
port (uint, default: 1234): default port if not specified
ifce (cstr): default multicast interface
ext (str): file extension of pipe data
mime (str): mime type of pipe data
listen (bool, default: false): indicate the output socket works in server mode
maxc (uint, default: +I): max number of concurrent connections
ka (bool, default: false): keep socket alive if no more connections
kp (bool, default: true): keep packets in queue if no more clients
start (dbl, default: 0.0): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
speed (dbl, default: 1.0): set playback speed. If negative and start is 0, start is set to -1
rate (uint, default: 0): set send rate in bps, disabled by default (as fast as possible)
pckr (frac, default: 0/0): reverse packet every N
pckd (frac, default: 0/0): drop packet every N
ttl (uint, default: 0, minmax: 0-127): multicast TTL
rfav1
Description: AV1/IVF/VP9 reframer
This filter parses AV1 OBU, AV1 AnnexB or IVF with AV1 or VP9 files/data and outputs corresponding visual
PID and frames.
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
importer (bool, default: false): compatibility with old importer
deps (bool, default: false): import sample dependency information
notime (bool, default: false): ignore input timestamps, rebuild from 0
temporal_delim (bool, default: false): keep temporal delimiters in reconstructed frames
bsdbg (enum, default: off): debug OBU parsing in media@debug logs
* off: not enabled
* on: enabled
* full: enable with number of bits dumped
ufobu
Description: IVF/OBU/annexB writer
This filter rewrites VPx or AV1 bitstreams into a IVF, annexB or OBU sequence.
The temporal delimiter OBU is re-inserted in annexB (.av1 and .av1bfiles, with obu_size set) and OBU
sequences (.obufiles, without obu_size)
Note: VP8/9 codecs will only use IVF output (equivalent to file extension .ivf or :ext=ivf set on
output).
Options (expert):
rcfg (bool, default: true): force repeating decoder config at each I-frame
nvdec
Description: NVidia decoder
This filter decodes MPEG-2, MPEG-4 Part 2, AVC|H264 and HEVC streams through NVidia decoder. It allows
GPU frame dispatch or direct frame copy.
If the SDK is not available, the configuration key nvdec@disabled will be written in configuration file
to avoid future load attempts.
Options (expert):
num_surfaces (uint, default: 20): number of hardware surfaces to allocate
unload (enum, default: no): decoder unload mode
* no: keep inactive decoder alive
* destroy: destroy inactive decoder
* reuse: detach decoder from inactive PIDs and reattach to active ones
vmode (enum, default: cuvid): video decoder backend
* cuvid: use dedicated video engines directly
* cuda: use a CUDA-based decoder if faster than dedicated engines
* dxva: go through DXVA internally if possible (requires D3D9)
fmode (enum, default: gl): frame output mode
* copy: each frame is copied and dispatched
* single: frame data is only retrieved when used, single memory space for all frames (not safe if
multiple consumers)
* gl: frame data is mapped to an OpenGL texture
routein
Description: ROUTE input
This filter is a receiver for ROUTE sessions (ATSC 3.0 and generic ROUTE).
- ATSC 3.0 mode is identified by the URL atsc://.
- Generic ROUTE mode is identified by the URL route://IP:PORT.
The filter can work in cached mode, source mode or standalone mode.
Cached mode
The cached mode is the default filter behavior. It populates GPAC HTTP Cache with the received files,
using http://groute/serviceN/ as service root, N being the ROUTE service ID.
In cached mode, repeated files are always pushed to cache.
The maximum number of media segment objects in cache per service is defined by .I nbcached; this is a
safety used to force object removal in case DASH client timing is wrong and some files are never
requested at cache level.
The cached MPD is assigned the following headers:
* `x-route`: integer value, indicates the ROUTE service ID.
* `x-route-first-seg`: string value, indicates the name of the first segment (completely or currently
being) retrieved from the broadcast.
* `x-route-ll`: boolean value, if yes indicates that the indicated first segment is currently being
received (low latency signaling).
* `x-route-loop`: boolean value, if yes indicates a loop in the service has been detected (usually pcap
replay loop).
The cached files are assigned the following headers:
* `x-route`: boolean value, if yes indicates the file comes from an ROUTE session.
If .I max_segs is set, file deletion event will be triggered in the filter chain.
Source mode
In source mode, the filter outputs files on a single output PID of type file. The files are dispatched
once fully received, the output PID carries a sequence of complete files. Repeated files are not sent
unless requested.
If needed, one PID per TSI can be used rather than a single PID. This avoids mixing files of different
mime types on the same PID (e.g. HAS manifest and ISOBMFF).
Example
gpac -i atsc://gcache=false -o $ServiceID$/$File$:dynext
This will grab the files and forward them as output PIDs, consumed by the fout filter.
If .I max_segs is set, file deletion event will be triggered in the filter chain.
Standalone mode
In standalone mode, the filter does not produce any output PID and writes received files to the .I odir
directory.
Example
gpac -i atsc://:odir=output
This will grab the files and write them to output directory.
If .I max_segs is set, old files will be deleted.
File Repair
In case of losses or incomplete segment reception (during tune-in), the files are patched as follows:
* MPEG-2 TS: all lost ranges are adjusted to 188-bytes boundaries, and transformed into NULL TS packets.
* ISOBMFF: all top-level boxes are scanned, and incomplete boxes are transformed in free boxes, except
mdat kept as is if .I repair is set to simple.
If .I kc option is set, corrupted files will be kept. If .I fullseg is not set and files are only
partially received, they will be kept.
Interface setup
On some systems (OSX), when using VM packet replay, you may need to force multicast routing on your local
interface.
For ATSC, you will have to do this for the base signaling multicast (224.0.23.60):
Example
route add -net 224.0.23.60/32 -interface vboxnet0
Then for each ROUTE service in the multicast:
Example
route add -net 239.255.1.4/32 -interface vboxnet0
Options (expert):
src (cstr): URL of source content
ifce (str): default interface to use for multicast. If NULL, the default system
interface will be used
gcache (bool, default: true): indicate the files should populate GPAC HTTP cache
tunein (sint, default: -2): service ID to bootstrap on for ATSC 3.0 mode (0 means tune to no service,
-1 tune all services -2 means tune on first service found)
buffer (uint, default: 0x80000): receive buffer size to use in bytes
timeout (uint, default: 5000): timeout in ms after which tunein fails
nbcached (uint, default: 8): number of segments to keep in cache per service
kc (bool, default: false): keep corrupted file
skipr (bool, default: true): skip repeated files (ignored in cache mode)
stsi (bool, default: false): define one output PID per tsi/serviceID (ignored in cache mode)
stats (uint, default: 1000): log statistics at the given rate in ms (0 disables stats)
tsidbg (uint, default: 0): gather only objects with given TSI (debug)
max_segs (uint, default: 0): maximum number of segments to keep on disk
odir (str): output directory for standalone mode
reorder (bool, default: false): ignore order flag in ROUTE/LCT packets, avoiding considering object done
when TOI changes
rtimeout (uint, default: 5000): default timeout in ms to wait when gathering out-of-order packets
fullseg (bool, default: false): only dispatch full segments in cache mode (always true for other modes)
repair (enum, default: simple): repair mode for corrupted files
* no: no repair is performed
* simple: simple repair is performed (incomplete mdat boxes will be kept)
* strict: incomplete mdat boxes will be lost as well as preceding moof boxes
* full: HTTP-based repair, not yet implemented
rtpout
Description: RTP Streamer
The RTP streamer handles SDP/RTP output streaming.
SDP mode
When the destination URL is an SDP, the filter outputs an SDP on a file PID and streams RTP packets over
UDP, starting from the indicated .I port.
Direct RTP mode
When the destination URL uses the protocol scheme rtp://IP:PORT, the filter does not output any SDP and
streams a single input over RTP, using PORT indicated in the destination URL, or the first .I port
configured.
In this mode, it is usually needed to specify the desired format using .I ext or .I mime.
Example
gpac -i src -o rtp://localhost:1234/:ext=ts
This will indicate that the RTP streamer expects a MPEG-2 TS mux as an input.
RTP Packets
The RTP packets produced have a maximum payload set by the .I mtu option (IP packet will be MTU + 40
bytes of IP+UDP+RTP headers).
The real-time scheduling algorithm works as follows:
- first initialize the clock by:
- computing the smallest timestamp for all input PIDs
- mapping this media time to the system clock
- determine the earliest packet to send next on each input PID, adding .I delay if any
- finally compare the packet mapped timestamp TS to the system clock SC. When TS - SC is less than .I tt,
the RTP packets for the source packet are sent
The filter does not check for RTCP timeout and will run until all input PIDs reach end of stream.
Options (expert):
ip (str): destination IP address (NULL is 127.0.0.1)
port (uint, default: 7000): port for first stream in session
loop (bool, default: true): loop all streams in session (not always possible depending on source type)
mpeg4 (bool, default: false): send all streams using MPEG-4 generic payload format if possible
mtu (uint, default: 1460): size of RTP MTU in bytes
ttl (uint, default: 2): time-to-live for multicast packets
ifce (str): default network interface to use
payt (uint, default: 96, minmax: 96-127): payload type to use for dynamic decoder configurations
delay (sint, default: 0): send delay for packet (negative means send earlier)
tt (uint, default: 1000): time tolerance in microseconds. Whenever schedule time minus realtime is
below this value, the packet is sent right away
runfor (sint, default: -1): run for the given time in ms. Negative value means run for ever (if loop)
or source duration, 0 only outputs the sdp
tso (sint, default: -1): set timestamp offset in microseconds. Negative value means random initial
timestamp
xps (bool, default: false): force parameter set injection at each SAP. If not set, only inject if
different from SDP ones
latm (bool, default: false): use latm for AAC payload format
dst (cstr): URL for direct RTP mode
ext (str): file extension for direct RTP mode
mime (cstr): set mime type for direct RTP mode
rtspout
Description: RTSP Server
The RTSP server partially implements RTSP 1.0, with support for OPTIONS, DESCRIBE, SETUP, PLAY, PAUSE and
TEARDOWN.
Multiple PLAY ranges are not supported, PLAY range end is not supported, PAUSE range is not supported.
Only aggregated control is supported for PLAY and PAUSE, PAUSE/PLAY on single stream is not supported.
The server only runs on TCP, and handles request in sequence: it will not probe for commands until
previous response is sent.
The server supports both RTP over UDP delivery and RTP interleaved over RTSP delivery.
The scheduling algorithm and RTP options are the same as the RTP output filter, see gpac -h rtpout
The server will disconnect UDP streaming sessions if no RTCP traffic has been received for .I timeout
seconds.
The server can run over TLS by specifying .I cert and .I pkey, in which case the default .I port is 322.
Sink mode
The filter can work as a simple output filter by specifying the .I dst option:
Example
gpac -i source -o rtsp://myip/sessionname
gpac -i source -o rtsp://myip/sessionname
In this mode, only one session is possible. It is possible to .I loop the input source(s).
Server mode
The filter can work as a regular RTSP server by specifying the .I mounts option to indicate paths of
media file to be served:
Example
gpac rtspout:mounts=mydir1,mydir2
In this case, content RES from any of the specified directory is exposed as rtsp://SERVER/RES
The .I mounts option can also specify access rule file(s), see gpac -h creds. When rules are used:
- if a directory has a name rule, it will be used in the URL
- otherwise, the directory is directly available under server root /
- only read access and multicast rights are checked
Example
[foodir]
name=bar
Content RES of this directory is exposed as rtsp://SERVER/bar/RES.
In this mode, it is possible to load any source supported by gpac by setting the option .I dynurl.
The expected syntax of the dynamic RTSP URLs is rtsp://servername/?URL1[&URLN] or
rtsp://servername/@URL1[@URLN]
Each URL can be absolute or local, in which case it is resolved against the mount point(s).
Example
gpac -i rtsp://localhost/?pipe://mynamepipe&myfile.mp4 [dst filters]
The server will resolve this URL in a new session containing streams from myfile.mp4 and streams from
pipe mynamepipe.
When setting .I runfor in server mode, the server will exit at the end of the last session being closed.
The parameter name=VAL is reserved to assign a session name in case multicast mirroring is used.
Example
gpac -i rtsp://localhost/?name=live?pipe://mynamepipe&myfile.mp4 [dst filters]
Usage of dynamic URLs can also be configured using the specific directory $dynurl in an access rule file.
EX[$dynurl]
ru=foo
This will allow dynamic URLs only for foo user.
Note: If the .I dynurl is set, it is enabled for all users, without authentication.
Multicasting
In both modes, clients can setup multicast if the .I mcast option is on or mirror.
When .I mcast is set to mirror mode, any DESCRIBE command on a resource already delivered through a
multicast session will use that multicast.
Consequently, only DESCRIBE methods are processed for such sessions, other methods will return
Unauthorized.
In server mode, multicast can be enabled per read directory using the mcast access rule of the directory
configuration - see gpac -h creds.
HTTP Tunnel
The server mode supports handling RTSP over HTTP tunnel by default. This can be disabled using .I htun.
The tunnel conforms to QT specification, and only HTTP 1.0 and 1.1 tunnels are supported.
Options (expert):
dst (cstr): location of destination resource
port (uint, default: 554): server port
firstport (uint, default: 6000): port for first stream in session
mtu (uint, default: 1460): size of RTP MTU in bytes
ttl (uint, default: 0): time-to-live for multicast packets (a value of 0 uses client requested
TTL, or 1)
ifce (str): default network interface to use
payt (uint, default: 96, minmax: 96-127): payload type to use for dynamic decoder configurations
mpeg4 (bool, default: false): send all streams using MPEG-4 generic payload format if possible
delay (sint, default: 0): send delay for packet (negative means send earlier)
tt (uint, default: 1000): time tolerance in microsecond (whenever schedule time minus realtime is
below this value, the packet is sent right away)
runfor (sint, default: -1): run the session for the given time in ms. A negative value means run for
ever if loop or source duration, value 0 only outputs the sdp
tso (sint, default: -1): set timestamp offset in microseconds (negative value means random initial
timestamp)
xps (bool, default: false): force parameter set injection at each SAP. If not set, only inject if
different from SDP ones
latm (bool, default: false): use latm for AAC payload format
mounts (strl): list of directories to expose in server mode
block_size (uint, default: 10000): block size used to read TCP socket
maxc (uint, default: 100): maximum number of connections
timeout (uint, default: 20): timeout in seconds for inactive sessions (0 disable timeout)
user_agent (str, default: $GUA): user agent string, by default solved from GPAC preferences
close (bool, default: false): close RTSP connection after each request, except when RTP over RTSP is
used
loop (bool, default: true): loop all streams in session (not always possible depending on source type)
dynurl (bool, default: false): allow dynamic service assembly
mcast (enum, default: off): control multicast setup of a session
* off: clients are never allowed to create a multicast
* on: clients can create multicast sessions
* mirror: clients can create a multicast session. Any later request to the same URL will use that
multicast session
quit (bool, default: false): exit server once first session is over (for test purposes)
htun (bool, default: true): enable RTSP over HTTP tunnel
trp (enum, default: both): transport mode
* both: allow TCP or UDP traffic
* udp: only allow UDP traffic
* tcp: only allow TCP traffic
cert (str): certificate file in PEM format to use for TLS mode
pkey (str): private key file in PEM format to use for TLS mode
httpout
Description: HTTP Server
The HTTP output filter can act as:
- a simple HTTP server
- an HTTP server sink
- an HTTP server file sink
- an HTTP client sink
- an HTTP server source
The server currently handles GET, HEAD, PUT, POST, DELETE methods, and basic OPTIONS support.
Single or multiple byte ranges are supported for both GET and PUT/POST methods, in all server modes.
- for GET, the resulting body is a single-part body formed by the concatenated byte ranges as requested
(no overlap checking).
- for PUT/POST, the received data is pushed to the target file according to the byte ranges specified in
the client request.
Warning: the partial PUT request is RFC2616 compliant but not compliant with RFC7230. PATCH method is not
yet implemented in GPAC.
When a single read directory is specified, the server root / is the content of this directory.
When multiple read directories are specified, the server root / contains the list of the mount points
with their directory names.
When a write directory is specified, the upload resource name identifies a file in this directory (the
write directory name is not present in the URL).
A directory rule file (cf gpac -h creds) can be specified in .I rdirs but NOT in .I wdir. When rules are
used:
- if a directory has a name rule, it will be used in the URL
- otherwise, the directory is directly available under server root /
- read and write access rights are checked
Example
[foodir]
name=bar
Content RES of this directory is exposed as http://SERVER/bar/RES.
Listing can be enabled on server using .I dlist.
When disabled, a GET on a directory will fail.
When enabled, a GET on a directory will return a simple HTML listing of the content inspired from Apache.
Simple HTTP server
In this mode, the filter does not need any input connection and exposes all files in the directories
given by .I rdirs.
PUT and POST methods are only supported if a write directory is specified by .I wdir option.
Example
gpac httpout:rdirs=outcoming
This sets up a read-only server.
Example
gpac httpout:wdir=incoming
This sets up a write-only server.
Example
gpac httpout:rdirs=outcoming:wdir=incoming:port=8080
This sets up a read-write server running on .I port 8080.
HTTP server sink
In this mode, the filter will forward input PIDs to connected clients, trashing the data if no client is
connected unless .I hold is specified.
The filter does not use any read directory in this mode.
This mode is mostly useful to setup live HTTP streaming of media sessions such as MP3, MPEG-2 TS or other
multiplexed representations:
Example
gpac -i MP3_SOURCE -o http://localhost/live.mp3 --hold
In this example, the server waits for client requests on /live.mp3 and will then push each input packet
to all connected clients.
If the source is not real-time, you can inject a reframer filter performing realtime regulation.
Example
gpac -i MP3_SOURCE reframer:rt=on -o http://localhost/live.mp3
In this example, the server will push each input packet to all connected clients, or trash the packet if
no connected clients.
In this mode, ICECast meta-data can be inserted using .I ice. The default inserted values are ice-audio-
info, icy-br, icy-pub (set to 1) and icy-name if input ServiceName property is set.
The server will also look for any property called ice-* on the input PID and inject them.
Example
gpac -i source.mp3:#ice-Genre=CoolRock -o http://IP/live.mp3 --ice
This will inject the header ice-Genre: CoolRock in the response.
Once one complete input file is sent, it is no longer available for download unless .I reopen is set and
input PID is not over.
This mode should not be used with multiple files muxers such as DASH or HLS.
HTTP server file sink
In this mode, the filter will write input PIDs to files in the first read directory specified, acting as
a file output sink.
The filter uses a read directory in this mode, which must be writable.
Upon client GET request, the server will check if the requested URL matches the name of a file currently
being written by the server.
- If so, the server will:
- send the content using HTTP chunk transfer mode, starting with what is already written on disk
- push remaining data to the client as soon as received while writing it to disk, until source file is
done
- If not so, the server will simply send the file from the disk as a regular HTTP session, without chunk
transfer.
This mode is typically used for origin server in HAS sessions where clients may request files while they
are being produced (low latency DASH).
Example
gpac -i SOURCE reframer:rt=on -o http://localhost:8080/live.mpd --rdirs=temp --dmode=dynamic --cdur=0.1
In this example, a real-time dynamic DASH session with chunks of 100ms is created, writing files to temp.
A client connecting to the live edge will receive segments as they are produced using HTTP chunk
transfer.
The server can store incoming files to memory mode by setting the read directory to gmem.
In this mode, .I max_cache_segs is always at least 1.
If .I max_cache_segs value N is not 0, each incoming PID will store at most:
- MIN(N, time-shift depth) files if stored in memory
- -N files if stored locally and N is negative
- MAX(N, time-shift depth) files if stored locally and N is positive
- unlimited otherwise (files stored locally, N is positive and no time-shift info)
HTTP client sink
In this mode, the filter will upload input PIDs data to remote server using PUT (or POST if .I post is
set).
This mode must be explicitly activated using .I hmode.
The filter uses no read or write directories in this mode.
Example
gpac -i SOURCE -o http://targethost:8080/live.mpd:gpac:hmode=push
In this example, the filter will send PUT methods to the server running on .I port 8080 at targethost
location (IP address or name).
HTTP server source
In this mode, the server acts as a source rather than a sink. It declares incoming PUT or POST methods as
output PIDs
This mode must be explicitly activated using .I hmode.
The filter uses no read or write directories in this mode, and uploaded data is NOT stored by the server.
Example
gpac httpout:hmode=source vout aout
In this example, the filter will try to play uploaded files through video and audio output.
HTTPS server
The server can run over TLS (https) for all the server modes. TLS is enabled by specifying .I cert and .I
pkey options.
Both certificate and key must be in PEM format.
The server currently only operates in either HTTPS or HTTP mode and cannot run both modes at the same
time. You will need to use two httpout filters for this, one operating in HTTPS and one operating in
HTTP.
Multiple destinations on single server
When running in server mode, multiple HTTP outputs with same URL/port may be used:
- the first loaded HTTP output filter with same URL/port will be reused
- all httpout options of subsequent httpout filters, except .I dst will be ignored, other options will be
inherited as usual
Example
gpac -i dash.mpd dashin:forward=file:SID=D1 dashin:forward=segb:SID=D2 -o
http://localhost:80/live.mpd:SID=D1:rdirs=dash -o http://localhost:80/live_rw.mpd:SID=D2:sigfrag
This will:
- load the HTTP server and forward (through D1) the dash session to this server using live.mpd as
manifest name
- reuse the HTTP server and regenerate the manifest (through D2 and sigfrag option), using live_rw.mpd as
manifest name
Options (expert):
dst (cstr): location of destination resource
port (uint, default: 0): server port
ifce (str): default network interface to use
rdirs (strl): list of directories to expose for read
wdir (str): directory to expose for write
cert (str): certificate file in PEM format to use for TLS mode
pkey (str): private key file in PEM format to use for TLS mode
block_size (uint, default: 10000): block size used to read and write TCP socket
user_agent (str, default: $GUA): user agent string, by default solved from GPAC preferences
close (bool, default: false): close HTTP connection after each request
maxc (uint, default: 100): maximum number of connections, 0 is unlimited
maxp (uint, default: 6): maximum number of connections for one peer (0 is unlimited)
cache_control (str): specify the Cache-Control string to add (none disable cache control and
ETag)
hold (bool, default: false): hold packets until one client connects
hmode (enum, default: default): filter operation mode, ignored if .I wdir is set
* default: run in server mode
* push: run in client mode using PUT or POST
* source: use server as source filter on incoming PUT/POST
timeout (uint, default: 5): timeout in seconds for persistent connections (0 disable timeout)
ext (cstr): set extension for graph resolution, regardless of file extension
mime (cstr): set mime type for graph resolution
quit (bool, default: false): exit server once all input PIDs are done and client disconnects (for test
purposes)
post (bool, default: false): use POST instead of PUT for uploading files
dlist (bool, default: false): enable HTML listing for GET requests on directories
sutc (bool, default: false): insert server UTC in response headers as Server-UTC: VAL_IN_MS
cors (enum, default: auto): insert CORS header allowing all domains
* off: disable CORS
* on: enable CORS
* auto: enable CORS when Origin is found in request
reqlog (str): provide short log of the requests indicated in this option (comma
separated list, * for all) regardless of HTTP log settings. Value REC logs file writing start/end
ice (bool, default: false): insert ICE meta-data in response headers in sink mode
max_client_errors (uint, default: 20): force disconnection after specified number of consecutive errors
from HTTTP 1.1 client (ignored in H/2 or when close is set)
max_cache_segs (sint, default: 5): maximum number of segments cached per HAS quality (see filter help)
reopen (bool, default: false): in server mode with no read dir, accept requests on files already over but
with input pid not in end of stream
max_async_buf (uint, default: 100000): maximum async buffer size in bytes when sharing output over
multiple connection without file IO
blockio (bool, default: false): use blocking IO in push or source mode or in server mode with no read dir
hevcsplit
Description: HEVC tile splitter
This filter splits a motion-constrained tiled HEVC PID into N independent HEVC PIDs.
Use hevcmerge filter to merge initially motion-constrained tiled HEVC PID in a single output.
No options
hevcmerge
Description: HEVC Tile merger
This filter merges a set of HEVC PIDs into a single motion-constrained tiled HEVC PID.
The filter creates a tiling grid with a single row and as many columns as needed.
If .I mrows is set and tiles properly align on the final grid, multiple rows will be declared in the PPS.
Positioning of tiles can be automatic (implicit) or explicit.
The filter will check the SPS and PPS configurations of input PID and warn if they are not aligned but
will still process them unless .I strict is set.
The filter assumes that all input PIDs are synchronized (frames share the same timestamp) and will
reassemble frames with the same decode time. If PIDs are of unequal duration, the filter will drop frames
as soon as one PID is over.
Implicit Positioning
In implicit positioning, results may vary based on the order of input PIDs declaration.
In this mode the filter will automatically allocate new columns for tiles with height not a multiple of
max CU height.
Explicit Positioning
In explicit positioning, the CropOrigin property on input PIDs is used to setup the tile grid. In this
case, tiles shall not overlap in the final output.
If CropOrigin is used, it shall be set on all input sources.
If positive coordinates are used, they specify absolute positioning in pixels of the tiles. The
coordinates are automatically adjusted to the next multiple of max CU width and height.
If negative coordinates are used, they specify relative positioning (e.g. 0x-1 indicates to place the
tile below the tile 0x0).
In this mode, it is the caller responsibility to set coordinates so that all tiles in a column have the
same width and only the last row/column uses non-multiple of max CU width/height values. The filter will
complain and abort if this is not respected.
- If an horizontal blank is detected in the layout, an empty column in the tiling grid will be inserted.
- If a vertical blank is detected in the layout, it is ignored.
Spatial Relationship Description (SRD)
The filter will create an SRDMap property in the output PID if SRDRef and SRD or CropOrigin are set on
all input PIDs.
The SRDMap allows forwarding the logical sources SRD in the merged PID.
The output PID SRDRef is set to the output video size.
The input SRDRef and SRD are usually specified in DASH MPD, but can be manually assigned to inputs.
- SRDRef gives the size of the referential used for the input SRD (usually matches the original video
size, but not always)
- SRD gives the size and position of the input in the original video, expressed in SRDRef referential of
the input.
The inputs do not need to have matching SRDRef
This indicates that src1 contains a video located at 0,0, with a size of 640x480 pixels in a virtual source of 1280x720 pixels.
Example
src2:SRD=640x0x640x480:SRDRef=1280x720
This indicates that src1 contains a video located at 640,0, with a size of 640x480 pixels in a virtual source of 1280x720 pixels.
Each merged input is described by 8 integers in the output SRDMap:
- the source SRD is rescaled in the output SRDRef to form the first part (4 integers) of the SRDMap (i.e. where was the input ?)
- the source location in the reconstructed video forms the second part (4 integers) of the SRDMap (i.e. where are the input pixels in the output ?)
Assuming the two sources are encoded at 320x240 and merged as src2 above src1, the output will be a 320x480 video with a SRDMap of {0,160,160,240,0,0,320,240,0,0,160,240,0,240,320,240}
Note: merged inputs are always listed in SRDMap in their tile order in the output bitstream.
Alternatively to using SRD and SRDRef, it is possible to specify CropOrigin property on the inputs, in which case:
- the CropOrigin gives the location in the source
- the input size gives the size in the source, and no rescaling of referential is done
Example
src1:CropOrigin=0x0 src1:CropOrigin=640x0
Assuming the two sources are encoded at 320x240 and merged as src1 above src2, the output will be a 320x480 video with a SRDMap of {0,0,320,240,0,0,320,240,640,0,320,240,0,240,320,240}
Options (expert):
strict (bool, default: false): strict comparison of SPS and PPS of input PIDs
mrows (bool, default: false): signal multiple rows in tile grid when possible
rfflac
Description: FLAC reframer
This filter parses FLAC files/data and outputs corresponding audio PID and frames.
By default the reframer will only check CRC footer of frames if a change in sample rate or channel
mapping is detected.
This should accomodate for most configurations, but CRC check can be enforced using .I docrc.
Options (expert):
index (dbl, default: 1.0): indexing window length
docrc (bool, default: false): perform CRC check after each frame
rfmhas
Description: MPEH-H Audio Stream reframer
This filter parses MHAS files/data and outputs corresponding audio PID and frames.
By default, the filter expects a MHAS stream with SYNC packets set, otherwise tune-in will fail. Using .I
nosync=false can help parsing bitstreams with no SYNC packets.
The default behavior is to dispatch a framed MHAS bitstream. To demultiplex into a raw MPEG-H Audio, use
.I mpha.
Options (expert):
index (dbl, default: 1.0): indexing window length
mpha (bool, default: false): demultiplex MHAS and only forward audio frames
pcksync (uint, default: 4): number of unknown packets to tolerate before considering sync is lost
nosync (bool, default: true): initial sync state
rfprores
Description: ProRes reframer
This filter parses ProRes raw files/data and outputs corresponding visual PID and frames.
Options (expert):
fps (frac, default: 0/1000): import frame rate (0 default to FPS from bitstream or 25 Hz)
findex (bool, default: true): index frames. If true, filter will be able to work in rewind mode
cid (str): set QT 4CC for the imported media. If not set, default is 'ap4h' for
YUV444 and 'apch' for YUV422
notime (bool, default: false): ignore input timestamps, rebuild from 0
tssplit
Description: MPEG Transport Stream splitter
This filter splits an MPEG-2 transport stream into several single program transport streams.
Only the PAT table is rewritten, other tables (PAT, PMT) and streams (PES) are forwarded as is.
If .I dvb is set, global DVB tables of the input multiplex are forwarded to each output mux; otherwise
these tables are discarded.
Options (expert):
dvb (bool, default: true): forward all packets from global DVB PIDs
mux_id (sint, default: -1): set initial ID of output mux; the first program will use mux_id, the
second mux_id+1, etc. If not set, this value will be set to sourceMuxId*255
avonly (bool, default: true): do not forward programs with no AV component
nb_pack (uint, default: 10): pack N packets before sending
bsrw
Description: Compressed bitstream rewriter
This filter rewrites some metadata of various bitstream formats.
The filter can currently modify the following properties in video bitstreams:
- MPEG-4 Visual:
- sample aspect ratio
- profile and level
- AVC|H264, HEVC and VVC:
- sample aspect ratio
- profile, level, profile compatibility
- video format, video fullrange
- color primaries, transfer characteristics and matrix coefficients (or remove all info)
- ProRes:
- sample aspect ratio
- color primaries, transfer characteristics and matrix coefficients
Values are by default initialized to -1, implying to keep the related info (present or not) in the
bitstream.
A .I sar value of 0/0 will remove sample aspect ratio info from bitstream if possible.
The filter can currently modify the following properties in the stream configuration but not in the
bitstream:
* HEVC: profile IDC, profile space, general compatibility flags
* VVC: profile IDC, general profile and level indication
The filter will work in passthrough mode for all other codecs and media types.
Options (expert):
cprim (cprm, default: -1, minmax:
reserved0,BT709,undef,reserved3,BT470M,BT470G,SMPTE170,SMPTE240,FILM,BT2020,SMPTE428,SMPTE431,SMPTE432,EBU3213,
updatable): color primaries according to ISO/IEC 23001-8 / 23091-2
ctfc (ctfc, default: -1, minmax:
reserved0,BT709,undef,reserved3,BT470M,BT470BG,SMPTE170,SMPTE249,Linear,Log100,Log316,IEC61966,BT1361,sRGB,BT2020_10,BT2020_12,SMPTE2084,SMPTE428,STDB67,
updatable): color transfer characteristics according to ISO/IEC 23001-8 / 23091-2
cmx (cmxc, default: -1, minmax: GBR,BT709,undef,FCC,BT601,SMPTE170,SMPTE240,YCgCo,BT2020,BT2020cl,YDzDx,
updatable): color matrix coeficients according to ISO/IEC 23001-8 / 23091-2
sar (frac, default: -1/-1, updatable): aspect ratio to rewrite
m4vpl (sint, default: -1, updatable): set ProfileLevel for MPEG-4 video part two
fullrange (bool, default: false, updatable): video full range flag
novsi (bool, default: false, updatable): remove video_signal_type from VUI in AVC|H264 and HEVC
novuitiming (bool, default: false, updatable): remove timing_info from VUI in AVC|H264 and HEVC
prof (sint, default: -1, updatable): profile indication for AVC|H264
lev (sint, default: -1, updatable): level indication for AVC|H264, level_idc for VVC
pcomp (sint, default: -1, updatable): profile compatibility for AVC|H264
pidc (sint, default: -1, updatable): profile IDC for HEVC and VVC
pspace (sint, default: -1, updatable): profile space for HEVC
gpcflags (sint, default: -1, updatable): general compatibility flags for HEVC
rmsei (bool, default: false, updatable): remove SEI messages from bitstream for AVC|H264, HEVC and VVC
vidfmt (enum, default: -1, updatable): video format for AVC|H264, HEVC and VVC
(component|pal|ntsc|secam|mac|undef)
bssplit
Description: Compressed layered bitstream splitter
This filter splits input stream by layers and sublayers
The filter supports AVC|H264, HEVC and VVC stream splitting and is pass-through for other codec types.
Splitting is based on temporalID value (start from 1) and layerID value (start from 0).
For AVC|H264, layerID is the dependency value, or quality value if svcqid is set.
Each input stream is filtered according to the ltid option as follows:
* no value set: input stream is split by layerID, i.e. each layer creates an output
* `all`: input stream is split by layerID and temporalID, i.e. each {layerID,temporalID} creates an
output
* `lID`: input stream is split according to layer lID value, and temporalID is ignored
* `.tID`: input stream is split according to temporal sub-layer tID value and layerID is ignored
* `lID.tID`: input stream is split according to layer lID and sub-layer tID values
Note: A tID value of 0 in ltid is equivalent to value 1.
Multiple values can be given in ltid, in which case each value gives the maximum {layerID,temporalID}
values for the current layer.
A few examples on an input with 2 layers each with 2 temporal sublayers:
* `ltid=0.2`: this will split the stream in:
- one stream with {lID=0,tID=1} and {lID=0,tID=2} NAL units
- one stream with all other layers/substreams
* `ltid=0.1,1.1`: this will split the stream in:
- one stream with {lID=0,tID=1} NAL units
- one stream with {lID=0,tID=2}, {lID=1,tID=1} NAL units
- one stream with the rest {lID=0,tID=2}, {lID=1,tID=2} NAL units
* `ltid=0.1,0.2`: this will split the stream in:
- one stream with {lID=0,tID=1} NAL units
- one stream with {lID=0,tID=2} NAL units
- one stream with the rest {lID=1,tID=1}, {lID=1,tID=2} NAL units
The filter can also be used on AVC and HEVC DolbyVision streams to split base stream and DV RPU/EL.
The filter does not create aggregator or extractor NAL units.
Options (expert):
ltid (strl): temporal and layer ID of output streams
svcqid (bool, default: false): use qualityID instead of dependencyID for SVC splitting
sig_ltid (bool, default: false): signal maximum temporal (max_temporal_id) and layer ID (max_layer_id) of
output streams (mostly used for debug)
bsagg
Description: Compressed layered bitstream aggregator
This filter aggregates layers and sublayers into a single output PID.
The filter supports AVC|H264, HEVC and VVC stream reconstruction, and is passthrough for other codec
types.
Aggregation is based on temporalID value (start from 1) and layerID value (start from 0).
For AVC|H264, layerID is the dependency value, or quality value if svcqid is set.
The filter can also be used on AVC and HEVC DolbyVision dual-streams to aggregate base stream and DV
RPU/EL.
The filter does not forward aggregator or extractor NAL units.
Options (expert):
svcqid (bool, default: false): use qualityID instead of dependencyID for SVC splitting
ufttxt
Description: TX3G unframer
This filter converts a single ISOBMFF TX3G stream to TTXT (xml format) unframed stream.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
tx3g2srt
Description: TX3G to SRT
This filter converts a single ISOBMFF TX3G stream to an SRT unframed stream.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
tx3g2vtt
Description: TX3G to WebVTT
This filter converts a single ISOBMFF TX3G stream to a WebVTT unframed stream.
Options (expert):
exporter (bool, default: false): compatibility with old exporter, displays export results
tx3g2ttml
Description: TX3G to TTML
This filter converts ISOBMFF TX3G stream to a TTML stream.
Each output TTML frame is a complete TTML document.
No options
vtt2tx3g
Description: WebVTT to TX3G
This filter rewrites unframed WebVTT to TX3G / QT Timed Text (binary format)
Unframed WebVTT packets consist in single cues:
- cue payload as packet payload
- prefix as packet string property vtt_pre
- cue ID as packet string property vtt_cueid
- cue settings as packet string property vtt_settings
- packet timing contains the cue timing (start and duration)
Options (expert):
fontname (str): default font
fontsize (uint, default: 18): default font size
rfsrt
Description: SRT reframer
This filter rewrites unframed SRT to TX3G / QT Timed Text (binary format)
An unframed SRT packet consists in a single SRT cue as packet payload and packet timing contains the cue
timing (start and duration).
Options (expert):
fontname (str): default font
fontsize (uint, default: 18): default font size
ttml2vtt
Description: TTML to WebVTT
This filter converts TTML frames to unframed WebVTT
Conversion is quite limited: only the first div is analyzed and only basic styling is implemented.
No options
ttml2srt
Description: TTML to SRT
This filter converts TTML frames to unframed SRT
Conversion is quite limited: only the first div is analyzed and only basic styling is implemented.
No options
ffdmx
Description: FFMPEG demultiplexer
Version: Lavf59.34.102
This filter demultiplexes an input file or open a source protocol using FFMPEG.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details.
To list all supported demultiplexers for your GPAC build, use gpac -h ffdmx:*.
This will list both supported input formats and protocols.
Input protocols are listed with Description: Input protocol, and the subclass name identifies the
protocol scheme.
For example, if ffdmx:rtmp is listed as input protocol, this means rtmp:// source URLs are supported.
Options (expert):
src (cstr): URL of source content
* (str): any possible options defined for AVFormatContext and sub-classes. See gpac
-hx ffdmx and gpac -hx ffdmx:*
ffdec
Description: FFMPEG decoder
Version: Lavc59.55.100
This filter decodes audio and video streams using FFMPEG.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details.
To list all supported decoders for your GPAC build, use gpac -h ffdec:*.
Options can be passed from prompt using --OPT=VAL
The default threading mode is to let libavcodec decide how many threads to use. To enforce single thread,
use --threads=1
Codec Map
The .I ffcmap option allows specifying FFMPEG codecs for codecs not supported by GPAC.
Each entry in the list is formatted as GID@name or GID@+name, with:
* GID: 4CC or 32 bit identifier of codec ID, as indicated by gpac -i source inspect:full
* name: FFMPEG codec name
* `+': is set and extra data is set and formatted as an ISOBMFF box, removes box header
Example
gpac -i source.mp4 --ffcmap=BKV1@binkvideo vout
This will map an ISOBMFF track declared with coding type BKV1 to binkvideo.
Options (expert):
ffcmap (strl): codec map
c (str): codec name (GPAC or ffmpeg), only used to query possible arguments -
updated to ffmpeg codec name after initialization
* (str): any possible options defined for AVCodecContext and sub-classes. See gpac
-hx ffdec and gpac -hx ffdec:*
ffavin
Description: FFMPEG AV Capture
Version: Lavd59.8.101
Reads from audio/video capture devices using FFMPEG.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details.
To list all supported grabbers for your GPAC build, use gpac -h ffavin:*.
Device identification
Typical classes are dshow on windows, avfoundation on OSX, video4linux2 or x11grab on linux
Typical device name can be the webcam name:
- FaceTime HD Camera on OSX, device name on windows, /dev/video0 on linux
- screen-capture-recorder, see http://screencapturer.sf.net/ on windows
- Capture screen 0 on OSX (0=first screen), or screenN for short
- X display name (e.g. :0.0) on linux
The general mapping from ffmpeg command line is:
- ffmpeg -f maps to .I fmt option
- ffmpeg -i maps to .I dev option
Example
ffmpeg -f libndi_newtek -i MY_NDI_TEST ...
gpac -i av://:fmt=libndi_newtek:dev=MY_NDI_TEST ...
You may need to escape the .I dev option if the format uses ':' as separator, as is the case for
AVFoundation:
Example
gpac -i av://::dev=0:1 ...
Options (expert):
src (str): url of device, video://, audio:// or av://
fmt (str): name of device class. If not set, defaults to first device class
dev (str, default: 0): name of device or index of device
copy (enum, default: A): set copy mode of raw frames
* N: frames are only forwarded (shared memory, no copy)
* A: audio frames are copied, video frames are forwarded
* V: video frames are copied, audio frames are forwarded
* AV: all frames are copied
sclock (bool, default: false): use system clock (us) instead of device timestamp (for buggy devices)
probes (uint, default: 10, minmax: 0-100): probe a given number of video frames before emitting (this
usually helps with bad timing of the first frames)
block_size (uint, default: 4096): block size used to read file when using avio context
* (str): any possible options defined for AVInputFormat and AVFormatContext (see
gpac -hx ffavin and gpac -hx ffavin:*)
ffsws
Description: FFMPEG video rescaler
Version: SwS6.8.112
This filter rescales raw video data using FFMPEG to the specified size and pixel format.
Output size assignment
If .I osize is {0,0}, the output dimensions will be set to the input size, and input aspect ratio will be
ignored.
If .I osize is {0,H} (resp. {W,0}), the output width (resp. height) will be set to respect input aspect
ratio. If .I keepar=nosrc, input sample aspect ratio is ignored.
Aspect Ratio and Sample Aspect Ratio
When output sample aspect ratio is set, the output dimensions are divided by the output sample aspect
ratio.
Example
ffsws:osize=288x240:osar=3/2
The output dimensions will be 192x240.
When aspect ratio is not kept (.I keepar=off):
- source is resampled to desired dimensions
- if output aspect ratio is not set, output will use source sample aspect ratio
When aspect ratio is partially kept (.I keepar=nosrc):
- resampling is done on the input data without taking input sample aspect ratio into account
- if output sample aspect ratio is not set (.I osar=0/N), source aspect ratio is forwarded to output.
When aspect ratio is fully kept (.I keepar=full), output aspect ratio is force to 1/1 if not set.
When sample aspect ratio is kept, the filter will:
- center the rescaled input frame on the output frame
- fill extra pixels with .I padclr
Algorithms options
- for bicubic, to tune the shape of the basis function, .I p1 tunes f(1) and .I p2 f´(1)
- for gauss .I p1 tunes the exponent and thus cutoff frequency
- for lanczos .I p1 tunes the width of the window function
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details
Options (expert):
osize (v2di): osize of output video
ofmt (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 for output video. When not set, input format is used
scale (enum, default: bicubic): scaling mode (see filter help)
(fastbilinear|bilinear|bicubic|X|point|area|bicublin|gauss|sinc|lanzcos|spline)
p1 (dbl, default: +I): scaling algo param1
p2 (dbl, default: +I): scaling algo param2
ofr (bool, default: false): force output full range
brightness (bool, default: 0): 16.16 fixed point brightness correction, 0 means use default
contrast (uint, default: 0): 16.16 fixed point brightness correction, 0 means use default
saturation (uint, default: 0): 16.16 fixed point brightness correction, 0 means use default
otable (sintl): the yuv2rgb coefficients describing the output yuv space, normally
ff_yuv2rgb_coeffs[x], use default if not set
itable (sintl): the yuv2rgb coefficients describing the input yuv space, normally
ff_yuv2rgb_coeffs[x], use default if not set
keepar (enum, default: off): keep aspect ratio
* off: ignore aspect ratio
* full: respect aspect ratio, applying input sample aspect ratio info
* nosrc: respect aspect ratio but ignore input sample aspect ratio
padclr (str, default: black): clear color when aspect ration preservation is used
osar (frac, default: 0/1): force output pixel aspect ratio
ffenc
Description: FFMPEG encoder
Version: Lavc59.55.100
This filter encodes audio and video streams using FFMPEG.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details.
To list all supported encoders for your GPAC build, use gpac -h ffenc:*.
The filter will try to resolve the codec name in .I c against a libavcodec codec name (e.g. libx264) and
use it if found.
If not found, it will consider the name to be a GPAC codec name and find a codec for it. In that case, if
no pixel format is given, codecs will be enumerated to find a matching pixel format.
Options can be passed from prompt using --OPT=VAL (global options) or appending ::OPT=VAL to the desired
encoder filter.
The filter will look for property TargetRate on input PID to set the desired bitrate per PID.
The filter will force a closed gop boundary:
- at each packet with a FileNumber property set or a CueStart property set to true.
- if .I fintra and .I rc is set.
When forcing a closed GOP boundary, the filter will flush, destroy and recreate the encoder to make sure
a clean context is used, as currently many encoders in libavcodec do not support clean reset when forcing
picture types.
If .I fintra is not set and the output of the encoder is a DASH session in live profile without segment
timeline, .I fintra will be set to the target segment duration and .I rc will be set.
The filter will look for property logpass on input PID to set 2-pass log filename, otherwise defaults to
ffenc2pass-PID.log.
Arguments may be updated at runtime. If .I rld is set, the encoder will be flushed then reloaded with new
options.
If codec is video and .I fintra is set, reload will happen at next forced intra; otherwise, reload
happens at next encode.
The .I rld option is usually needed for dynamic updates of rate control parameters, since most encoders
in ffmpeg do not support it.
Options (expert):
c (str): codec identifier. Can be any supported GPAC codec name or ffmpeg codec
name - updated to ffmpeg codec name after initialization
pfmt (pfmt, default: none): pixel format for input video. When not set, input format is used
fintra (frac, default: -1/1): force intra / IDR frames at the given period in sec, e.g. fintra=2 will
force an intra every 2 seconds and fintra=1001/1000 will force an intra every 30 frames on
30000/1001=29.97 fps video; ignored for audio
all_intra (bool, default: false, updatable): only produce intra frames
ls (bool, default: false): log stats
rc (bool, default: false): reset encoder when forcing intra frame (some encoders might not support
intra frame forcing)
rld (bool, default: false, updatable): force reloading of encoder when arguments are updated
* (str): any possible options defined for AVCodecContext and sub-classes. see gpac
-hx ffenc and gpac -hx ffenc:*
ffmx
Description: FFMPEG multiplexer
Version: Lavf59.34.102
Multiplexes files and open output protocols using FFMPEG.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details.
To list all supported multiplexers for your GPAC build, use gpac -h ffmx:*.This will list both supported
output formats and protocols.
Output protocols are listed with Description: Output protocol, and the subclass name identifies the
protocol scheme.
For example, if ffmx:rtmp is listed as output protocol, this means rtmp:// destination URLs are
supported.
Some URL formats may not be sufficient to derive the multiplexing format, you must then use .I ffmt to
specify the desired format.
Unlike other multiplexing filters in GPAC, this filter is a sink filter and does not produce any PID to
be redirected in the graph.
The filter can however use template names for its output, using the first input PID to resolve the final
name.
The filter watches the property FileNumber on incoming packets to create new files.
Options (expert):
dst (cstr): location of destination file or remote URL
start (dbl, default: 0.0): set playback start offset. A negative value means percent of media
duration with -1 equal to duration
speed (dbl, default: 1.0): set playback speed. If negative and start is 0, start is set to -1
ileave (frac, default: 1): interleave window duration in second, a value of 0 disable interleaving
nodisc (bool, default: false): ignore stream configuration changes while multiplexing, may result in
broken streams
mime (cstr): set mime type for graph resolution
ffiles (bool, default: false): force complete files to be created for each segment in DASH modes
ffmt (str): force ffmpeg output format for the given URL
block_size (uint, default: 4096): block size used to read file when using avio context
keepts (bool, default: true): do not shift input timeline back to 0
* (str): any possible options defined for AVFormatContext and sub-classes (see gpac
-hx ffmx and gpac -hx ffmx:*)
ffavf
Description: FFMPEG AVFilter
Version: Lavf59.34.102
This filter provides libavfilter raw audio and video tools.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details
To list all supported avfilters for your GPAC build, use gpac -h ffavf:*.
Declaring a filter
The filter loads a filter or a filter chain description from the .I f option.
Example
ffavf:f=showspectrum
Unlike other FFMPEG bindings in GPAC, this filter does not parse other libavfilter options, you must
specify them directly in the filter chain, and the .I f option will have to be escaped.
Example
ffavf::f=showspectrum=size=320x320 or ffavf::f=showspectrum=size=320x320::pfmt=rgb
ffavf::f=anullsrc=channel_layout=5.1:sample_rate=48000
For complex filter graphs, it is possible to store options in a file (e.g. opts.txt):
Example
:f=anullsrc=channel_layout=5.1:sample_rate=48000
And load arguments from file:
Example
ffavf:opts.txt aout
The filter will automatically create buffer and buffersink AV filters for data exchange between GPAC and
libavfilter.
The builtin options ( .I pfmt, .I afmt ...) can be used to configure the buffersink filter to set the
output format of the filter.
Naming of PIDs
For simple filter graphs with only one input and one output, the input PID is assigned the avfilter name
in and the output PID is assigned the avfilter name out
When a graph has several inputs, input PID names shall be assigned by the user using the ffid property,
and mapping must be done in the filter.
Example
gpac -i video:#ffid=a -i logo:#ffid=b ffavf::f=[a][b]overlay=main_w-overlay_w-10:main_h-overlay_h-10 vout
In this example:
- the video source is identified as a
- the logo source is identified as b
- the filter declaration maps a to its first input (in this case, main video) and b to its second input
(in this case the overlay)
When a graph has several outputs, output PIDs will be identified using the ffid property set to the
output avfilter name.
Example
gpac -i source ffavf::f=split inspect:SID=#ffid=out0 vout#SID=out1
In this example:
- the splitter produces 2 video streams out0 and out1
- the inspector only process stream with ffid out0
- the video output only displays stream with ffid out1
The name(s) of the final output of the avfilter graph cannot be configured in GPAC. You can however name
intermediate output(s) in a complex filter chain as usual.
Filter graph commands
The filter handles option updates as commands passed to the AV filter graph. The syntax expected in the
option name is:
* com_name=value: sends command com_name with value value to all filters
* name#com_name=value: sends command com_name with value value to filter named name
Options (expert):
f (str): filter or filter chain description
pfmt (pfmt, default: none): pixel format of output. If not set, let AVFilter decide
afmt (afmt, default: none): audio format of output. If not set, let AVFilter decide
sr (uint, default: 0): sample rate of output. If not set, let AVFilter decide
ch (uint, default: 0): number of channels of output. If not set, let AVFilter decide
dump (bool, default: false, updatable): dump graph as log media@info or stderr if not set
* (str): any possible options defined for AVFilter and sub-classes (see gpac -hx
ffavf and gpac -hx ffavf:*)
ffbsf
Description: FFMPEG BitStream filter
Version: Lavc59.55.100
This filter provides bitstream filters (BSF) for compressed audio and video formats.
See FFMPEG documentation (https://ffmpeg.org/documentation.html) for more details
To list all supported bitstream filters for your GPAC build, use gpac -h ffbsf:*.
Several BSF may be specified in .I f for different coding types. BSF not matching the coding type are
silently ignored.
When no BSF matches the input coding type, or when .I f is empty, the filter acts as a passthrough
filter.
Options are specified after the desired filters:
- ffbsf:f=h264_metadata:video_full_range_flag=0
- ffbsf:f=h264_metadata,av1_metadata:video_full_range_flag=0:color_range=tv
Note: Using BSFs on some media types (e.g. avc, hevc) may trigger creation of a reframer filter (e.g.
rfnalu)
Options (expert):
f (strl): bitstream filters name - see filter help
* (str): any possible options defined for AVBitstreamFilter and sub-classes. See
gpac -hx ffbsf and gpac -hx ffbsf:*
jsf
Description: JavaScript filter
This filter runs a javascript file specified in .I js defining a new JavaScript filter.
For more information on how to use JS filters, please check https://wiki.gpac.io/jsfilter
Options (expert):
js (cstr): location of script source
* (str): any possible options defined for the script (see gpac -hx
jsf:js=$YOURSCRIPT or gpac -hx $YOURSCRIPT)
routeout
Description: ROUTE output
The ROUTE output filter is used to distribute a live file-based session using ROUTE.
The filter supports DASH and HLS inputs, ATSC3.0 signaling and generic ROUTE signaling.
The filter is identified using the following URL schemes:
* `atsc://`: session is a full ATSC 3.0 session
* `route://IP:port`: session is a ROUTE session running on given multicast IP and port
The filter only accepts input PIDs of type FILE.
- HAS Manifests files are detected by file extension and/or MIME types, and sent as part of the signaling
bundle or as LCT object files for HLS child playlists.
- HAS Media segments are detected using the OrigStreamType property, and send as LCT object files using
the DASH template string.
- A PID without OrigStreamType property set is delivered as a regular LCT object file (called raw
hereafter).
For raw file PIDs, the filter will look for the following properties:
* `ROUTEName`: set resource name. If not found, uses basename of URL
* `ROUTECarousel`: set repeat period. If not found, uses .I carousel. If 0, the file is only sent once
* `ROUTEUpload`: set resource upload time. If not found, uses .I carousel. If 0, the file will be sent as
fast as possible.
When DASHing for ROUTE or single service ATSC, a file extension, either in .I dst or in .I ext, may be
used to identify the HAS session type (DASH or HLS).
Example
"route://IP:PORT/manifest.mpd", "route://IP:PORT/:ext=mpd"
When DASHing for multi-service ATSC, forcing an extension will force all service to use the same formats.
Example
"atsc://:ext=mpd", "route://IP:PORT/manifest.mpd"
If multiple services with different formats are needed, you will need to explicit your filters:
Example
gpac -i DASH_URL:#ServiceID=1 dashin:forward=file:FID=1 -i HLS_URL:#ServiceID=2 dashin:forward=file:FID=2
-o atsc://:SID=1,2
gpac -i MOVIE1:#ServiceID=1 dasher:FID=1:mname=manifest.mpd -i MOVIE2:#ServiceID=2
dasher:FID=2:mname=manifest.m3u8 -o atsc://:SID=1,2
Warning: When forwarding an existing DASH/HLS session, do NOT set any extension or manifest name.
By default, all streams in a service are assigned to a single route session, and differentiated by ROUTE
TSI (see .I splitlct).
TSI are assigned as follows:
- signaling TSI is always 0
- raw files are assigned TSI 1 and increasing number of TOI
- otherwise, the first PID found is assigned TSI 10, the second TSI 20 etc ...
Init segments and HLS child playlists are sent before each new segment, independently of .I carousel.
ATSC 3.0 mode
In this mode, the filter allows multiple service multiplexing, identified through the ServiceID property.
By default, a single multicast IP is used for route sessions, each service will be assigned a different
port.
The filter will look for ROUTEIP and ROUTEPort properties on the incoming PID. If not found, the default
.I ip and .I port will be used.
The ATSC short service name can be set using PID property ShortServiceName. If not found, ServiceName is
checked, otherwise default to GPAC.
ROUTE mode
In this mode, only a single service can be distributed by the ROUTE session.
Note: .I ip is ignored, and .I first_port is used if no port is specified in .I dst.
The ROUTE session will include a multi-part MIME unsigned package containing manifest and S-TSID, sent on
TSI=0.
Low latency mode
When using low-latency mode, the input media segments are not re-assembled in a single packet but are
instead sent as they are received.
In order for the real-time scheduling of data chunks to work, each fragment of the segment should have a
CTS and timestamp describing its timing.
If this is not the case (typically when used with an existing DASH session in file mode), the scheduler
will estimate CTS and duration based on the stream bitrate and segment duration. The indicated bitrate is
increased by .I brinc percent for safety.
If this fails, the filter will trigger warnings and send as fast as possible.
Note: The LCT objects are sent with no length (TOL header) assigned until the final segment size is
known, potentially leading to a final 0-size LCT fragment signaling only the final size.
Examples
Since the ROUTE filter only consumes files, it is required to insert:
- the dash demultiplexer in file forwarding mode when loading a DASH session
- the dash multiplexer when creating a DASH session
Multiplexing an existing DASH session in route:
Example
gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/
Multiplexing an existing DASH session in atsc:
Example
gpac -i source.mpd dashin:forward=file -o atsc://
Dashing and multiplexing in route:
Example
gpac -i source.mp4 dasher:profile=live -o route://225.1.1.0:6000/manifest.mpd
Dashing and multiplexing in route Low Latency:
Example
gpac -i source.mp4 dasher -o route://225.1.1.0:6000/manifest.mpd:profile=live:cdur=0.2:llmode
Sending a single file in ROUTE using half a second upload time, 2 seconds carousel:
Example
gpac -i URL:#ROUTEUpload=0.5:#ROUTECarousel=2 -o route://225.1.1.0:6000/
Common mistakes:
Example
gpac -i source.mpd -o route://225.1.1.0:6000/
This will only send the manifest file as a regular object and will not load the dash session.
Example
gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/manifest.mpd
This will force the ROUTE multiplexer to only accept .mpd files, and will drop all segment files (same if
.I ext is used).
Example
gpac -i source.mpd dasher -o route://225.1.1.0:6000/
gpac -i source.mpd dasher -o route://225.1.1.0:6000/manifest.mpd
These will demultiplex the input, re-dash it and send the output of the dasher to ROUTE
Options (expert):
dst (cstr): destination URL
ext (cstr): set extension for graph resolution, regardless of file extension
mime (cstr): set mime type for graph resolution
ifce (str): default interface to use for multicast. If NULL, the default system
interface will be used
carousel (uint, default: 1000): carousel period in ms for repeating signaling and raw file data
first_port (uint, default: 6000): port number of first ROUTE session in ATSC mode
ip (str, default: 225.1.1.0): multicast IP address for ROUTE session in ATSC mode
ttl (uint, default: 0): time-to-live for multicast packets
bsid (uint, default: 800): ID for ATSC broadcast stream
mtu (uint, default: 1472): size of LCT MTU in bytes
splitlct (enum, default: off): split mode for LCT channels
* off: all streams are in the same LCT channel
* type: each new stream type results in a new LCT channel
* all: all streams are in dedicated LCT channel, the first stream being used for STSID signaling
korean (bool, default: false): use Korean version of ATSC 3.0 spec instead of US
llmode (bool, default: false): use low-latency mode
brinc (uint, default: 10): bitrate increase in percent when estimating timing in low latency mode
noreg (bool, default: false): disable rate regulation for media segments, pushing them as fast as
received
runfor (uint, default: 0): run for the given time in ms
rftruehd
Description: TrueHD reframer
This filter parses Dolby TrueHD files/data and outputs corresponding audio PID and frames.
Options (expert):
index (dbl, default: 1.0): indexing window length
auxac3 (bool, default: false): expose auxiliary AC-3 stream if present
cryptin
Description: CryptFile input
This filter dispatch raw blocks from encrypted files with AES 128 CBC in PKCS7 to clear input files
The filter is automatically loaded by the DASH/HLS demultiplexer and should not be explicitly loaded by
your application.
The filter accepts URL with scheme gcryp://URL, where URL is the URL to decrypt.
The filter can process http(s) and local file key URLs (setup through HLS manifest), and expects a full
key (16 bytes) as result of resource fetching.
Options (expert):
src (cstr): location of source file
fullfile (bool, default: false): reassemble full file before decryption
cryptout
Description: CryptFile output
This filter dispatch raw blocks from clear input files to encrypted files with AES 128 CBC in PKCS7
The filter is automatically loaded by the DASH/HLS multiplexer and should not be explicitly loaded by
your application.
The filter accepts URL with scheme gcryp://URL, where URL is the URL to encrypt.
Options (expert):
dst (cstr): location of source file
fullfile (bool, default: false): reassemble full file before decryption
restamp
Description: Packet timestamp rewriter
This filter rewrites timing (offsets and rate) of packets.
The delays (global or per stream class) can be either positive (stream presented later) or negative
(stream presented sooner).
The specified .I fps can be either 0, positive or negative.
- if 0 or if the stream is audio, stream rate is not modified.
- otherwise if negative, stream rate is multiplied by -fps.num/fps.den.
- otherwise if positive and the stream is not video, stream rate is not modified.
- otherwise (video PID), constant frame rate is assumed and:
- if .I rawv=no, video frame rate is changed to the specified rate (speed-up or slow-down).
- if .I rawv=force, input video stream is decoded and video frames are dropped/copied to match the new
rate.
- if .I rawv=dyn, input video stream is decoded if not all-intra and video frames are dropped/copied to
match the new rate.
Note: frames are simply copied or dropped with no motion compensation.
Options (expert):
fps (frac, default: 0/1): target fps
delay (frac, default: 0/1, updatable): delay to add to all streams
delay_v (frac, default: 0/1, updatable): delay to add to video streams
delay_a (frac, default: 0/1, updatable): delay to add to audio streams
delay_t (frac, default: 0/1, updatable): delay to add to text streams
delay_o (frac, default: 0/1, updatable): delay to add to other streams
rawv (enum, default: no): copy video frames
* no: no raw frame copy/drop
* force: force decoding all video streams
* dyn: decoding video streams if not all intra
tsinit (lfrac, default: -1/1): initial timestamp to resync to, negative values disables resync
oggmx
Description: OGG multiplexer
This filter multiplexes audio and video to produce an OGG stream.
The .I cdur option allows specifiying the interleaving duration (max time difference between consecutive
packets of different streams).
Options (expert):
cdur (frac, default: 1/10): stream interleaving duration in seconds
rcfg (frac, default: 0/1): stream config re-injection frequency in seconds
unframer
Description: Stream unframer
This filter is used to force reframing of input sources using the same internal framing as GPAC (e.g.
ISOBMFF) but with broken framing or signaling.
Example
gpac -i src.mp4 unframer -o dst.mp4
This will:
- force input PIDs of unframer to be in serialized form (AnnexB, ADTS, ...)
- trigger reframers to be instanciated after the unframer filter.
Using the unframer filter avoids doing a dump to disk then reimport or other complex data piping.
No options
writeuf
Description: Stream to unframed format
Generic single stream to unframed format converter, used when converting PIDs. This filter should not be
explicitly loaded.
No options
dtout
Description: DekTec SDIOut
This filter provides SDI output to be used with DTA 2174 or DTA 2154 cards.
Options (expert):
bus (sint, default: -1): PCI bus number. If not set, device discovery is used
slot (sint, default: -1): PCI bus number. If not set, device discovery is used
fps (frac, default: 30/1): default FPS to use if input stream fps cannot be detected
clip (bool, default: false): clip YUV data to valid SDI range, slower
port (uint, default: 1): set sdi output port of card
start (dbl, default: 0.0): set playback start offset, [-1, 0] means percent of media dur, e.g. -1 ==
dur
ohevcdec
Description: OpenHEVC decoder
This filter decodes HEVC and LHVC (HEVC scalable extensions) from one or more PIDs through the OpenHEVC
library
Options (expert):
threading (enum, default: frame): set threading mode
* frameslice: parallel decoding of both frames and slices
* frame: parallel decoding of frames
* slice: parallel decoding of slices
nb_threads (uint, default: 0): set number of threads (if 0, uses number of cores minus one)
no_copy (bool, default: false): directly dispatch internal decoded frame without copy
pack_hfr (bool, default: false): pack 4 consecutive frames in a single output
seek_reset (bool, default: false): reset decoder when seeking
force_stereo (bool, default: true): use stereo output for multiview (top-bottom only)
reset_switch (bool, default: false): reset decoder at config change
glpush
Description: GPU texture uploader
Version: 1.0
Author: GPAC team
This filter pushes input video streams to GPU as OpenGL textures. It can be used to simulate hardware
decoders dispatching OpenGL textures
No options
thumbs
Description: Thumbnail collection generator
Version: 1.0
Author: GPAC team
This filter generates screenshots from a video stream.
The input video is downsampled by the .I scale factor. The output size is configured based on the number
of images per line and per column in the .I grid.
Once configured, the output size is no longer modified.
The .I snap option indicates to use one video frame every given seconds. If value is 0, all input frames
are used.
If the number of rows is 0, it will be computed based on the source duration and desired .I snap time,
and will default to 10 if it cannot be resolved.
To output one image per input frame, use :grid=1x1.
If a single image per output frame is used, the default value for .I snap is 0 and for .I scale is 1.
Otherwise, the default value for .I snap is 1 second and for .I scale is 10.
A single line of text can be inserted over each frame. Predefined keywords can be used in input text,
identified as $KEYWORD$:
* ts: replaced by packet timestamp
* timescale: replaced by PID timescale
* time: replaced by packet time as HH:MM:SS.ms
* cpu: replaced by current CPU usage of process
* mem: replaced by current memory usage of process
* version: replaced by GPAC version
* fversion: replaced by GPAC full version
* mae: replaced by Mean Absolute Error with previous frame
* mse: replaced by Mean Square Error with previous frame
* P4CC, PropName: replaced by corresponding PID property
Example
gpac -i src reframer:saps=1 thumbs:snap=30:grid=6x30 -o dump/$num$.png
This will generate images from key-frames only, inserting one image every 30 seconds. Using key-frame
filtering is much faster but may give unexpected results if there are not enough key-frames in the
source.
Example
gpac -i src thumbs:snap=0:grid=5x5 -o dump/$num$.png
This will generate one image containing 25 frames every second at 25 fps.
If a single image per output frame is used and the scaling factor is 1, the input packet is reused as
input with text and graphics overlaid.
Example
gpac -i src thumbs:grid=1x1:txt='Frame $time$' -o dump/$num$.png
This will inject text over each frame and keep timing and other packet properties.
A json output can be specified in input .I list to let applications retrieve frame position in output
image from its timing.
Scene change detection
The filter can compute the absolute and/or square error metrics between consecutive images and drop image
if the computed metric is less than the given threshold.
If both .I mae and .I mse thresholds are 0, scene detection is not performed (default).
If both .I mae and .I mse thresholds are not 0, the frame is added if it passes both thresholds.
For both metrics, a value of 0 means all pixels are the same, a value of 100 means all pixels have 100%
intensity difference (e.g. black versus white).
The scene detection is performed after the .I snap filtering and uses:
- the previous frame in the stream, whether it was added or not, if .I scref is not set,
- the last added frame otherwise.
Typical thresholds for scene cut detection are 14 to 20 for .I mae and 5 to 7 for .I mse.
Since this is a costly process, it is recommended to use it combined with key-frames selection:
Example
gpac -i src reframer:saps=1 thumbs:mae=15 -o dump/$num$.png
The .I maxsnap option can be used to force insertion after the given time if no scene cut is found.
Options (expert):
grid (v2di, default: 6x0): number of images per lines and columns
scale (dbl, default: -1): scale factor for input size
mae (uint, default: 0, minmax: 0,100): scene diff threshold using Mean Absolute Error
mse (uint, default: 0, minmax: 0,100): scene diff threshold using Mean Square Error
lw (dbl, default: 0.0): line width between images in pixels
lc (str, default: white): line color
clear (str, default: white): clear color
snap (dbl, default: -1): duration between images, 0 for all images
maxsnap (dbl, default: -1): maximum duration between two thumbnails when scene change detection is
enabled
pfmt (pfmt, default: rgb): output pixel format
txt (str, default: ): text to insert per thumbnail
tc (str, default: white): text color
tb (str, default: black): text shadow
font (str, default: SANS): font to use
fs (dbl, default: 10): font size to use in percent of scaled height
tv (dbl, default: 0): text vertical position in percent of scaled height
thread (sint, default: -1): number of threads for software rasterizer, -1 for all available cores
blt (bool, default: true): use blit instead of software rasterizer
scref (bool, default: false): use last inserted image as reference for scene change detection
dropfirst (bool, default: false): drop first image
list (str, default: null): export json list of frame times and positions to given file
lxy (bool, default: false): add explict x and y in json export
avmix
Description: Audio Video Mixer
Author: GPAC team
AVMix is an audio video mixer controlled by an updatable JSON playlist format. The filter can be used to:
- schedule video sequence(s) over time
- mix videos together
- layout of multiple videos
- overlay images, text and graphics over source videos
All input streams are decoded prior to entering the mixer.
- audio streams are mixed in software
- video streams are composed according to the gpu option
- other stream types are not yet supported
OpenGL hardware acceleration can be used, but the supported feature set is currently not the same with or
without GPU.
In software mode, the mixer will detect whether any of the currently active video sources can be used as
a base canvas for the output to save processing time.
The default behavior is to do this detection only at the first generated frame, use dynpfmt to modify
this.
The filter can be extended through JavaScript modules. Currently only scenes and transition effects use
this feature.
Live vs offline
When operating offline, the mixer will wait for video frames to be ready for 10 times lwait. After this
timeout, the filter will abort if no input is available.
This implies that there shall always be a media to compose, i.e. no "holes" in the timeline.
Note: The playlist is still refreshed in offline mode.
When operating live, the mixer will initially wait for video frames to be ready for lwait seconds. After
this initial timeout, the output frames will indicate:
- 'No signal' if no input is available (no source frames) or no scene is defined
- 'Signal lost' if no new input data has been received for lwait on a source
Playlist Format
Overview
The main components in a playlist are:
* Media sources and sequences: each source is described by one or more URL to the media data, and each
sequence is a set of sources to be played continuously
* Transitions: sources in a sequence can be combined using transitions
* Scenes: a scene describes one graphical object to put on screen and if and how input video are mapped
on objects
* Groups: a group is a hierarchy of scenes and groups with positioning properties, and can also be used
to create offscreen images reused by other elements
* Timers: a timer can be used to animate scene parameters in various fashions
The playlist content shall be either a single JSON object or an array of JSON objects, hereafter called
root objects.
Root objects types can be indicated through a type property:
* seq: a sequence object
* url: a source object (if used as root, a default sequence object will be created)
* scene: a scene object
* group: a group object
* timer: a timer object
* script: a script object
* config: a config object
* watch: a watcher object
* style: a style object
Except for style, the type property of root objects is usually not needed as the parser guesses the
object types from its properties.
A root object with a property skip set to anything but 0 or false is ignored.
Within a group hierarchy, any scene or group object with a property skip set to anything but 0 or false
is ignored.
Any unrecognized property not starting with _ will be reported as warning.
Colors
Colors are handled as strings, formatted as:
- the DOM color name (see gpac -h colors)
- HTML codes $RRGGBB or #RRGGBB
- RGB hex vales 0xRRGGBB
- RGBA hex values 0xAARRGGBB
- the color none is 0x00000000, its signification depends on the object using it.
If JS code needs to manipulate colors, use sys.color_lerp and sys.color_component functions.
JS Hooks
Some object types allow for custom JS code to be executed.
The script code can either be the value of the property, or located in a file indicated in the property.
The code is turned into a function (i.e. new Function(args, js_code)) upon initial playlist parsing or
reload, hereafter called JSFun.
The JSFun arguments and return value are dependent on the parent object type.
The parent object is exposed as this in JSFun and can be used to store context information for the JS
code.
The code can use the global functions and modules defined, especially:
* sys: GPAC system module
* evg: GPAC EVG module
* os: QuickJS OS module
* video_playing: video playing state
* audio_playing: audio playing state
* video_time: output video time
* video_timescale: output video timescale
* video_width: output video width
* video_height: output video height
* audio_time: output audio time
* audio_timescale: output audio timescale
* samplerate: output audio samplerate
* channels: output audio channels
* current_utc_clock: current UTC clock in ms
* get_media_time: gets media time of output (no argument) or of source with id matching the first
argument. Return
* -4: not found
* -3: not playing
* -2: in prefetch
* -1: timing not yet known
* value: media time in seconds (float)
* resolve_url: resolves URL given in first argument against media playlist URL and returns the resolved
url (string)
* get_scene(id): gets scene with given ID
* get_group(id): gets group with given ID
* mouse_over(evt): returns scene under mouse described by a GPAC event, or null if no scene (picking for
scenes with perspective projection is not supported)
* mouse_over(x, y): returns scene under coordinates {x, y} in pixels, {0,0} representing the center of
the frame, x axis oriented towards the right and y axis oriented towards the top
Scene and group options must be accessed through getters and setters:
* scene.get(prop_name): gets the scene option
* scene.set(prop_name, value): sets the scene option
* group.get(prop_name): gets the group option
* group.set(prop_name, value): sets the group option
Warning: Results are undefined if JS code modifies the scene/group objects in any other way.
Other playlist objects (as well as scene and group objects) can be queried using query_element(ID,
propName) or modified using update_element(ID, propName, value) (see playlist update below).
Warning: There is no protection of global variables and state, write your script carefully!
Additionally, scripts executed within scene modules can modify the internal playlist using:
* remove_element(ID): removes a scene, group, sequence, timer, script or watcher with given ID from
playlist
* parse_element(JSON): parses a root playlist element and add it to the current playlist
* parse_scene(JSON, parent): parses a scene and add it to parent group if not null or root otherwise
* parse_group(JSON, parent): parses a group and add it to parent group if not null or root otherwise
* reload_playlist(JSON): parses a new playlist (an empty JSON array will reset the playlist). If the
calling scene is no longer in the resulting scene tree, it will be added to the root of the scene tree.
All these playlist-related functions must be called within the update() callback of the scene module.
Sequences
Properties for sequence objects:
* id (null): sequence identifier
* loop (0): number of loops for the sequence (0 means no loop, -1 will loop forever)
* start (0): sequence start time (see notes). If negative, the sequence is not active
* stop (0): sequence stop time (see notes). If less than start, the sequence will stop only when over
* transition (null): a transition object to apply between sources of the sequence
* seq ([]): array of one or more source objects
Notes
Media source timing does not depend on the media being used by a scene or not, it is only governed by the
sequence parameters.
This means that a sequence not used by any active scene will not be rendered (video nor audio).
The syntax for start and stop fields is:
* `now`: resolves to current UTC clock in live mode, and to 0 for non-live mode
* date: converted to UTC date in live mode, and to 0 for non-live mode
* N: converted to current utc clock (or 0 for non-live mode) plus N seconds UTC
* "N": converted to current utc clock (or 0 for non-live mode) plus N seconds UTC
In 'live' mode, if start is set using a UTC date, the sequence will have a start range equal to
MAX(current_UTC - start_in_UTC, 0). Some sources may be skipped to fulfill this condition.
This allows different instances of the filter using the same playlist to initialize media time in the
same fashion.
When reloading the playlist:
- if the sequence is active, start value is ignored
- if the sequence was not started, start value is updated
- if the sequence was over, start value is updated only of greater than previous resolved UTC start time.
Sources
Properties for source objects
* id (null): source identifier, used when reloading the playlist
* src ([]): list of sourceURL describing the URLs to play. Multiple sources will be played in parallel
* start (0.0): media start time in source
* stop (0.0): media stop time in source, ignored if less than or equal to start
* mix (true): if true, apply sequence transition or mix effect ratio as audio volume. Otherwise volume is
not modified by transitions.
* fade ('inout'): indicate how audio should be faded at stream start/end:
* in: audio fade-in when playing first frame
* out: audio fade-out when playing last frame
* inout: both fade-in and fade-out are enabled
* other: no audio fade
* keep_alive (false): if using a dedicated gpac process for one or more input, relaunch process(es) at
source end if exit code is greater than 2 or if not responding after rtimeout
* seek (false): if true and keep_alive is active, adjust start according to the time elapsed since source
start when relaunching process(es)
* prefetch (500): prefetch duration in ms (play before start time of source), 0 for no prefetch
* hold (false): if media duration is known and media stop time is greater than media duration, activate
no signal mode until desired stop time is reached (disable transition), otherwise move to next source at
end of stream
Source Locations
Properties for sourceURL objects
* id (null): source URL identifier, used when reloading the playlist
* in (null): input URL or filter chain to load as string. Words starting with - are ignored. The first
entry must specify a source URL, and additional filters and links can be specified using @N[#LINKOPT] and
@@N[#LINKOPT] syntax, as in gpac
* port (null): input port for source. Possible values are:
* pipe: launch a gpac process to play the source using GSF format over pipe
* tcp, tcpu: launch a gpac process to play the source using GSF format over TCP socket (tcp) or unix
domain TCP socket (tcpu)
* not specified or empty string: loads source using the current process
* other: use value as input filter declaration and launch in as a dedicated process (e.g. in="ffmpeg
..." port="pipe://...")
* opts (null): options for the gpac process instance when using a dedicated gpac process, ignored
otherwise
* media ('all'): filter input media by type, a for audio, v for video, t for text (several characters
allowed, e.g. av or va), all accept all input media
* raw (true): indicate if input port is decoded AV (true) or compressed AV (false) when using a dedicated
gpac process, ignored otherwise
Notes
When launching a child process, the input filter is created first and the child process launched
afterwards.
Warning: When launching a child process directly (e.g. in="ffmpeg ..."), any relative URL used in in must
be relative to the current working directory.
2D and 3D transformation
Common properties for group and scene objects
* active (true): indicate if the object is active or not. An inactive object will not be refreshed nor
rendered
* x (0): horizontal translation
* y (0): vertical translation
* cx (0): horizontal coordinate of rotation center
* cy (0): vertical coordinate of rotation center
* units ('rel'): unit type for x, y, cx, cy, width and height. Possible values are:
* rel: units are expressed in percent of current reference (see below)
* pix: units are expressed in pixels
* rotation (0): rotation angle of the scene in degrees
* hscale (1): horizontal scaling factor to apply to the group
* vscale (1): vertical skewing factor to apply to the scene
* hskew (0): horizontal skewing factor to apply to the scene
* vskew (0): vertical skewing factor to apply to the scene
* zorder (0): display order of the scene or of the offscreen group (ignored for regular groups)
* untransform (false): if true, reset parent tree matrix to identity before computing matrix
* mxjs (null): JS code for matrix evaluation
* z (0): depth translation
* cz (0): depth coordinate of rotation center
* zscale (1): depth scaling factor to apply to the group
* orientation ([0, 0, 1, 0]): scale along the given orientation axis [x, y, z, angle] - see VRML
scaleOrientation
* axis ([0, 0, 1]): rotation axis
* position ([0, 0, auto]): camera location
* target ([0, 0, 0]): point where the camera is looking
* up ([0, 1, 0]): camera up vector
* viewport ([0, 0, 100, 100]): viewport for camera
* fov (45): field of view in degrees
* ar (0): camera aspect ratio, 0 means default
* znear (0): near Z plane distance, 0 means default
* zfar (0): far Z plane distance, 0 means default
Coordinate System
Each group or scene is specified in a local coordinate system for which:
- {0,0} represents the center
- X values increase to the right
- Y values increase to the top
- Z values increase towards the eye of a viewer (Z=X^Y)
The 2D local transformation matrix is computed as rotate(cx, cy, rotation) * hskew * vskew *
scale(hscale, vscale) * translate(x, y).
The 3D local transformation matrix is computed as translate(x, y, z) * rotate(cx, cy, cz, rotation) *
scale(hscale, vscale, zscale). Skewing is not supported for 3D.
The default unit system (rel) is relative to the current established reference space:
- by default, the reference space is {output_width, output_height}, the origin {0,0} being the center of
the output frame
- any group with reference=true, width>0 and height>0 establishes a new reference space {group.width,
group.height}
Inside a reference space R, relative coordinates are interpreted as follows:
- For horizontal coordinates, 0 means center, -50 means left edge (-R.width/2), 50 means right edge
(+R.width/2).
- For vertical coordinates, 0 means center, -50 means bottom edge (-R.height/2), 50 means top edge
(+R.height/2).
- For width, 100 means R.width.
- For height, 100 means R.height.
- For depth (z and cz) coordinates, the value is a percent of the reference height (+R.height).
If width=height, the width is set to the computed height of the object.
If height=width, the height is set to the computed width of the object.
For x property, the following special values are defined:
- y will set the value to the computed y of the object.
- -y will set the value to the computed -y of the object.
For y property, the following special values are defined:
- x will set the value to the computed x of the object.
- -x will set the value to the computed -x of the object.
Changing reference is typically needed when creating offscreen groups, so that children relative
coordinates are resolved against the offscreen canvas size.
The selection between 2D and 3D is done automatically based on z, cz, axis and orientation values.
The default projection is:
- viewport is the entire output frame
- field of view is PI/4 and aspect ratio is output width/height
- zNear is 0.1 and zFar is 10 times maximum(output width, output height)
- camera up direction is Y axis and camera distance is so that a rectangle facing the camera with z=0 and
size equal to output size covers exactly the output frame.
- depth buffer is disabled
The default projection can be changed by setting camera properties at group or scene level. When set on a
group, all children of the group will use the given camera properties (camera parameters on children are
ignored).
The viewport parameter is specified as an array [x, y, w, h], where:
* x: horizontal coordinate of the viewport center, in group or scene units, or 'y' to use y value, or
'-y' to use -y value.
* y: vertical coordinate of the viewport center, in group or scene units, or 'x' to use x value, or '-x'
to use -x value.
* w: width of the viewport, in group or scene units, or 'height' to use h value.
* h: height of the viewport, in group or scene units, or 'width' to use w value.
z-ordering
zorder specifies the display order of the element in the offscreen canvas of the enclosing offscreen
group, or on the output frame if no offscreen group in parent tree.
This order is independent of the parent group z-ordering. This allows moving objects of a group up and
down the display stack without modifying the groups.
Coordinate modifications through JS
The JSFun specified in mxjs has a single parameter tr.
The tr parameter is an object containing the following variables that the code can modify:
* x, y, z, cx, cy, cz, hscale, vscale, zscale, hskew, vskew, rotation, untransform, axis, orientation:
these values are initialized to the current group values in local coordinate system units
* update: if set to true, the object matrix will be recomputed at each frame even if no change in the
group or scene parameters (always enforced to true if use is set)
* depth: for groups with use, indicates the recursion level of the used element. A value of 0 indicates
this is a direct render of the element, otherwise it is a render through use
The JSFun may return false to indicate that the scene should be considered as inactive. Any other return
value (undefined or not false) will mark the scene as active.
EX: "mxjs": "tr.rotation = (get_media_time() % 8) * 360 / 8; tr.update=true;"
Grouping
Properties for group objects
* id (null): group identifier
* scenes ([]): zero or more group or scene objects, cannot be animated or updated
* opacity (1): group opacity
* offscreen ('none'): set group in offscreen mode, cannot be animated or updated. An offscreen mode is
not directly visible but can be used in some texture operations. Possible values are:
* none: regular group
* mask: offscreen surface is alpha+grey
* color: offscreen surface is alpha+colors or colors if back_color is set
* dual: same as color but allows group to be displayed
* scaler (1): when opacity or offscreen rendering is used, offscreen canvas size is divided by this
factor (>=1)
* back_color ('none'): when opacity or offscreen rendering is used, fill offscreen canvas with the given
color.
* width (-1): when opacity or offscreen rendering is used, limit offscreen width to given value (see
below)
* height (-1): when opacity or offscreen rendering is used, limit offscreen height to given value (see
below)
* use (null): id of group or scene to re-use
* use_depth (-1): number of recursion allowed for the used element, negative means global max branch
depth as indicated by maxdepth
* reverse (false): reverse scenes order before draw
* reference (false): group is a reference space for relative coordinate of children nodes
Notes
The maximum depth of a branch in the scene graph is maxdepth (traversing aborts after this limit).
In offscreen mode, the bounds of the enclosed objects are computed to allocate the offscreen surface,
unless width and height are both greater or equal to 0.
Enforcing offscreen size is useful when generating textures for later effects.
Offscreen rendering is always done in software.
When enforcing scaler>1 on a group with opacity==1, offscreen rendering will be used and the scaler
applied.
When enforcing width and height on a group with opacity<1, the display may be truncated if children
objects are out of the offscreen canvas bounds.
Scenes
Properties for scene objects
* id (null): scene identifier
* js ('shape'): scene type, either builtin (see below) or path to a JS module, cannot be animated or
updated
* sources ([]): list of identifiers of sequences or offscreen groups used by this scene
* width (-1): width of the scene, -1 means reference space width
* height (-1): height of the scene, -1 means reference space height
* mix (null): a transition object to apply if more than one source is set, ignored otherwise
* mix_ratio (-1): mix ratio for transition effect, <=0 means first source only, >=1 means second source
only
* volume (1.0): audio volume (0: silence, 1: input volume), this value is not clamped by the mixer.
* fade ('inout'): indicate how audio should be faded at scene activate/deactivate:
* in: audio fade-in when playing first frame after scene activation
* out: audio fade-out when playing last frame at scene activation
* inout: both fade-in and fade-out are enabled
* other: no audio fade
* autoshow (true): automatically deactivate scene when sequences set in sources are not active
* nosig ('lost'): enable no-signal message for scenes using sequences:
* no: disable message
* lost: display message when signal is lost
* before: display message if source is not yet active
* all: always display message if source is inactive
* styles ([]): list of style IDs to use
- any other property exposed by the underlying scene JS module.
Notes
Inputs to a scene, whether sequence or offscreen group, must be declared prior to the scene itself.
A default scene will be injected if none is found when initially loading the playlist. If you need to
start with an empty output, use a scene with no sequence associated.
If a scene uses one or more sequences and autoshow is not set, the scene will be drawn with no sequence
attached if all sequences are inactive (not yet started or over).
Transitions and Mixing effects
JSON syntax
Properties for transition objects:
* id (null): transition identifier
* type: transition type, either builtin (see below) or path to a JS module
* dur: transition duration (transitions always end at source stop time). Ignored if transition is
specified for a scene mix.
* fun (null): JS code modifying the ratio effect
- any other property exposed by the underlying transition module.
Notes
A sequence of two media with playback duration (as indicated in source) of D1 and D2 using a transition
of duration DT will result in a sequence lasting D1 + D2 - DT.
The JSFun specified by fun takes one argument ratio and must return the recomputed ratio.
Example
"fun": "return ratio*ratio;"
Timers and animations
Properties for timer objects
* id (null): id of the timer
* dur (0): duration of the timer in seconds
* loop (false): loops timer when stop is not set
* pause (false): pause timer
* start (-1): start time (see notes), negative value means inactive
* stop (-1): stop time (see notes), ignored if less than start
* keys ([]): list of keys used for interpolation, ordered list between 0.0 and 1.0
* anims ([]): list of animation objects
Properties for animation objects
* values ([]): list of values to interpolate, there must be as many values as there are keys
* color (false): indicate the values are color (as strings)
* angle (false): indicate the interpolation factor is an angle in degree, to convert to radians
(interpolation ratio multiplied by PI and divided by 180) before interpolation
* mode ('linear') : interpolation mode:
* linear: linear interpolation between the values
* discrete: do not interpolate
* other: JS code modifying the interpolation ratio
* postfun (null): JS code modifying the interpolation result
* end ('freeze'): behavior at end of animation:
* freeze: keep last animated values
* restore: restore targets to their initial values
* targets ([]): list of strings indicating targets properties to modify. Syntax is:
* ID@option: modifies property option of object with given ID
* ID@option[IDX]: modifies value at index IDX of array property option of object with given ID
Notes
Currently, only scene, group, transition and script objects can be modified through timers (see playlist
updates).
The syntax for start and stop fields is:
* `now`: resolves to current UTC clock in live mode, and to 0 for non-live mode
* date: converted to UTC date in live mode, and to 0 for non-live mode
* N: converted to UTC clock at init plus N seconds for timer objects (absolute offset from timeline init)
* "N": converted to current UTC clock plus N seconds (relative offset from current time) with N a
positive or negative number
The JSFun specified by mode has one input parameter interp equal to the interpolation factor and must
return the new interpolation factor.
Example
"mode":"return interp*interp;"
The JSFun specified by postfun has two input parameters res (the current interplation result) and interp
(the interpolation factor), and must return the new interpolated value.
Example
"postfun": "if (interp<0.5) return res*res; return res;"
Scripts
Properties for script objects
* id (null): id of the script
* script (null): JavaScript code or path to JavaScript file to execute, cannot be animated or updated
* active (true): indicate if script is active or not
Notes
Script objects allow read and write access to the playlist from script. They currently can only be used
to modify scenes and groups and to activate/deactivate other scripts.
The JSFun function specified by fun has no input parameter. The return value (default 0) is the number of
seconds (float) to wait until next evaluation of the script.
EX: { "script": "let s=get_scene('s1'); let rot = s.get('rotation'); rot += 10; s.set('rotation', rot);
return 2;" }
This will change scene s1 rotation every 2 seconds
Watchers
Properties for watcher objects
* id (null): ID of the watcher
* active (true): indicate if watcher is active or not
* watch (""): element watched, formatted as ID@prop, with ID the element ID and prop the property name to
watch
* target (""): action for watcher. Allowed syntaxes are:
* `ID@prop`, `ID@prop[idx]`: copy value to property prop of the element ID (potentially at index idx if
specified for arrays)
* `ID.fun_name`: call function fun_name exported from scene module ID, using three arguments ['value',
'watchID', 'watchPropName'], no return value check
* otherwise: action must be JS code, and the resulting JSFun has one argument value containing the
watched value, and no return value check
* with (undefined): for targets in the form ID@prop, use this value instead of the watched value
Notes
A watcher can be used to monitor changes in an object in the playlist.
Any object property that can be animated or updated can be monitored by a watcher.
In addition, the following virtual properties (cannot be read or write) can be watched:
* sequence.active: value is set to true when sequence is activated, and false when deactivated
* source.active: value is set to true when source playback starts, and false when source playback stops
* timer.active: value is set to true when timer starts, and false when timer stops
Only the active property can be animated or updated in a watcher.
Example
{'watch': 's1@rotation', 'target': 's2@rotation'}
This will copy s1.rotation to s2.rotation.
Example
{'watch': 's1@rotation', 'target': 'get_scene('s2').set('rotation', -value); }
This will copy the -1*s1.rotation to s2.rotation.
Watching UI events
Watchers can also be used to monitor GPAC user events by setting watch to:
- an event name to monitor, one of keydown, keyup, mousemove, mouseup, mousedown, wheel, textInput
- events to monitor all events (including internal events).
For keyup and keydown events, the key code to watch may additionally be given in parenthesis, e.g.
'watch': 'keyup(T)'.
Note: User events are only sent if the output of the filter is consumed by the vout filter.
When event monitoring is used, the target must be a javascript callback (i.e. it cannot be ID@prop).
The javascript function will be called with a single argument evt containing the GPAC event.
Example
{'watch': 'mousemove', 'target': 'let s = mouse_over(evt); get_scene('s2').set('fill', (s && (s.id=='s1')
? 'white' : 'black' );'}
This will set s1 fill color to white of mouse is over s2 and to black otherwise.
Styles
Properties for style objects
* id (null): ID of the style
* forced (false): always apply style even when no modifications
* other: any property to share between scene
Notes
A style object allows scenes to share the same values for a given set of properties.
If a scene property has the same name as a style property, the scene property is replaced by the style
property.
Styles only apply to scene properties as follows:
- volume, fade, mix_ratio can use style
- all options defined by the scene module can use style
- transformation or other scene properties cannot use style
Properties of a style object can be animated or updated, but a style object cannot be watched.
Styles are applied to each associated scene in order of declaration, e.g. ['st1', 'st2'] and ['st2',
'st1'] will likely give different results.
If force is not set for a style, the style is only applied after being modified (load, animation,
update); if a scene uses ['st1', 'st2'] and only st1 is
modified (animation, update), st2 will only be applied once.
Filter configuration
The playlist may specify configuration options of the filter, using a root object of type 'config':
- property names are the same as the filter options
- property values are given in the native type, or as strings for fractions (format N/D), vectors (format
WxH) or enums
- each declared property overrides the filter option of the same name (whether default or set at filter
creation)
A configuration object in the playlist is only parsed when initially loading the playlist, and ignored
when reloading it.
The following additional properties are defined for testing:
* reload_tests([]): list of playlists to reload
* reload_timeout(1.0): timeout in seconds before playlist reload
* reload_loop (0): number of times to repeat the reload tests (not including original playlist which is
not reloaded)
Playlist modification
The playlist file can be modified at any time.
Objects are identified across playlist reloads through their id property.
Objects that are not present after reloading a playlist are removed from the mixer. This implies that
reloading a playlist will recreate most objects with no ID associated.
A sequence object modified between two reloads is refreshed, except for its start field if sequence
active.
A source object shall have the same parent sequence between two reloads. Any modification on the object
will only be taken into consideration when (re)loading the source.
A sourceURL object is not tracked for modification, only evaluated when activating the parent source
object.
A scene or group object modified between two reloads is notified of each changed value.
A timer object modified between two reloads is shut down and restarted. Consequently, animation objects
are not tracked between reloads.
A transition object may change between two reloads, but any modification on the object will only be taken
into consideration when restarting the effect.
A script object modified between two reloads has its code re-evaluated
A watcher object modified between two reloads has its watch source and code re-evaluated
A style object is not tracked (all styles are reloaded when reloading a playlist).
Playlist example
The following is an example playlist using a sequence of two videos with a mix transition and an animated
video area:
Example
[
{"id": "seq1", "loop": -1, "start": 0, "seq":
[
{ "id": "V1", "src": [{"in": "s1.mp4"}], "start": 60, "stop": 80},
{ "id": "V2", "src": [{"in": "s2.mp4"}], "stop": 100}
],
"transition": { "dur": 1, "type": "mix"}
},
{"id": "scene1", "sources": ["seq1"]},
{"start": 0, "dur": 10, "keys": [0, 1], "anims":
[
{"values": [50, 0], "targets": ["scene1@x", "scene1@y"]},
{"values": [0, 100], "targets": ["scene1@width", "scene1@height"]}
]
}
]
Updates Format
Updates can be sent to modify the playlist, rather than reloading the entire playlist.
Updates are read from a separate file specified in updates, inactive by default.
Warning: The updates file is only read when modified AFTER the initialization of the filter.
The updates file content shall be either a single JSON object or an array of JSON objects.
The properties of these objects are:
* skip: if true or 1, ignores the update, otherwise apply it
* replace: string identifying the target replacement. Syntax is:
* ID@name: indicate property name of element with given ID to replace
* ID@name[idx]: indicate the index in the property name of element with given ID to replace
* with: replacement value, must be of the same type as the target value.
An id property cannot be updated.
The following playlist elements of a playlist can be updated:
* scene: all properties except js and read-only module properties
* group: all properties except scenes and offscreen
* sequence: start, stop, loop and transition properties
* timer: start, stop, loop, pause and dur properties
* transition: all properties
* for sequence transitions: most of these properties will only be updated at next reload
* for active scene transitions: whether these changes are applied right away depend on the transition
module
Example
[
{"replace": "scene1@x", "with": 20},
{"replace": "seq1@start", "with": "now"}
]
Scene modules
Scene mask
This scene sets the canvas alpha mask mode.
The canvas alpha mask is always full screen.
In software mode, combining mask effect in record mode and reverse group drawing allows drawing front to
back while writing pixels only once.
Options:
* mode ('off'): if set, reset clipper otherwise set it to scene position and size
* off: mask is disabled
* on: mask is enabled and cleared, further draw operations will take place on mask
* onkeep: mask is enabled but not cleared, further draw operations will take place on mask
* use: mask is enabled, further draw operations will be filtered by mask
* use_inv: mask is enabled, further draw operations will be filtered by 1-mask
* rec: mask is in record mode, further draw operations will be drawn on output and will set mask value
to 0
Scene clear
This scene clears the canvas area covered by the scene with a given color.
The default clear color of the mixer is black.
The clear area is always axis-aligned in output frame, so when skew/rotation are present, the axis-
aligned bounding box of the transformed scene area will be cleared.
Options:
* color ('none'): clear color
Scene clip
This scene resets the canvas clipper or sets the canvas clipper to the scene area.
The clipper is always axis-aligned in output frame, so when skew/rotation are present, the axis-aligned
bounding box of the transformed clipper will be used.
Clippers are handled through a stack, resetting the clipper pops the stack and restores previous clipper.
If a clipper is already defined when setting the clipper, the clipper set is the intersection of the two
clippers.
Options:
* reset (false): if set, reset clipper otherwise set it to scene position and size
* stack (true): if false, clipper is set/reset independently of the clipper stack (no intersection, no
push/pop of the stack)
Scene shape
This scene can be used to setup a shape, its outline and specify the fill and strike modes.
Supported shapes include:
- a variety of rectangles, ellipse and other polygons
- custom paths specified from JS
- text
The color modes for shapes and outlines include:
- texturing using data from input media streams (shape fill only)
- texturing using local JPEG and PNG files (shape fill only)
- solid color
- linear and radial gradients
The default scene is optimized to fallback to fast blit when no transformations are used on a straight
rectangle shape.
All options can be updated at run time.
The module accepts 0, 1 or 2 sequences as input.
Color replacement operations can be specified for base scenes using source videos by specifying the
replace option. The replacement source is:
- the image data if img is set, potentially altered using *_rep options
- otherwise a linear gradient if fill=linear or a radial gradient if fill=radial (NOT supported in GPU
mode, use an offscreen group for this).
Warning: Color replacement operations cannot be used with transition or mix effects.
Text options
Text can be loaded from file if text[0] is an existing local file.
By default all lines are loaded. The number of loaded lines can be specified using text[1] as follows:
* 0 or not present: all lines are loaded
* N > 0: only keep the last N lines
* N < 0: only keep the first N lines
Text loaded from file will be refreshed whenever the file is modified.
Predefined keywords can be used in input text, identified as $KEYWORD$. The following keywords (case
insensitive) are defined:
* time: replaced by UTC date
* ltime: replaced by locale date
* date: replaced by date (Y/M/D)
* ldate: replaced by locale date (Y/M/D)
* mtime: replaced by output media time
* mtime_SRC: replaced by media time of input source SRC
* cpu: replaced by current CPU usage of process
* mem: replaced by current memory usage of process
* version: replaced by GPAC version
* fversion: replaced by GPAC full version
* P4CC, PropName: replaced by corresponding PID property
Custom paths
Custom paths (shapes) can be created through JS code indicated in 'shape', either inline or through a
file.
The following GPAC JS modules are imported:
- Sys as sys
- All EVG as evg
- os form QuickJS
See https://doxygen.gpac.io for more information on EVG and Sys JS APIs.
The code is exposed the scene as this. The variable this.path is created, representing an empty path.
Example
"shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0,
this.width, this.height/3); this.path.add_path(el);"
The default behaviour is to use the shape width and height as reference size for texture mapping.
If your custom path is textured, with bounding rectangle size different from the indicated shape size,
set the variable this.tx_adjust to true.
In the previous example, the texture mapping will not be impacted by the custom path size.
Example
"shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0,
this.width, this.height/3); this.path.add_path(el); this.tx_adjust = true;"
In this example, the texture mapping will be adjusted to the desired size.
The global variables and functions are available (c.f. gpac -h avmix:global):
* get_media_time(): return media time in seconds (float) of output
* get_media_time(SRC): get time of source with id SRC, return -4 if not found, -3 if not playing, -2 if
in prefetch, -1 if timing not yet known, media time in seconds (float) otherwise
* current_utc_clock: current UTC time in ms
* video_time: output video time
* video_timescale: output video timescale
* video_width: output video width
* video_height: output video height
If your path needs to be reevaluated on regular basis, set the value this.reload to the timeout to next
reload, in milliseconds.
Options:
* rx (0): horizontal radius for rounded rect in percent of object width if positive, in absolute value if
negative, value y means use ry
* ry (0): vertical radius for rounded rect in percent of object height if positive, in absolute value if
negative, value x means use rx
* tl (1): top-left corner scaler (positive, 0 disables corner)
* bl (1): bottom-left corner scaler (positive, 0 disables corner)
* tr (1): top-right corner scaler (positive, 0 disables corner)
* br (1): bottom-right corner scaler (positive, 0 disables corner)
* rs (false): repeat texture horizontally
* rt (false): repeat texture vertically
* keep_ar (true): keep aspect ratio
* pad_color ('0x00FFFFFF'): color to use for texture padding if rs or rt are false. Use none to use
texture edge, 0x00FFFFFF for transparent (always enforced if source is transparent)
* txmx ([]): texture matrix - all 6 coefficients must be set, i.e. [xx xy tx yx yy ty]
* cmx ([]): color transform - all 20 coefficients must be set in order, i.e. [Mrr, Mrg, Mrb, Mra, Tr,
Mgr, Mgg ...]
* line_width (0): line width in percent of width if positive, or absolute value if negative
* line_color ('white'): line color, linear for linear gradient and radial for radial gradient
* line_pos ('center'): line/shape positioning. Possible values are:
* center: line is centered around shape
* outside: line is outside the shape
* inside: line is inside the shape
* line_dash ('plain'): line dashing mode. Possible values are:
* plain: no dash
* dash: predefined dash pattern is used
* dot: predefined dot pattern is used
* dashdot: predefined dash-dot pattern is used
* dashdashdot: predefined dash-dash-dot pattern is used
* dashdotdot: predefined dash-dot-dot pattern is used
* dashes ([]): dash/dot pattern lengths for custom dashes (these will be multiplied by line size)
* cap ('flat'): line end style. Possible values are:
* flat: flat end
* round: round end
* square: square end (extends limit compared to flat)
* triangle: triangle end
* join ('miter'): line joint style. Possible values are:
* miter: miter join (straight lines)
* round: round join
* bevel: bevel join
* bevelmiter: bevel+miter join
* miter_limit (2): miter limit for joint styles
* dash_length (-1): length of path to outline, negative values mean full path
* dash_offset (0): offset in path at which the outline starts
* blit (true): use blit if possible, otherwise EVG texturing. If disabled, always use texturing
* fill ('none'): fill color if used without sources, linear for linear gradient and radial for radial
gradient
* img (''): image for scene without sources or when replace is set. Accepts either a path to a local
image (JPG or PNG), the ID of an offscreen group or the ID of a sequence
* alpha (1): global texture transparency
* replace (''): if img or fill is set and shape is using source, set multi texture option. Possible modes
are:
* a, r, g or b: replace alpha source component by indicated component from img . If prefix - is set,
replace by one minus the indicated component
* m: mix using mix_ratio the color components of source and img and set alpha to full opacity
* M: mix using mix_ratio all components of source and img, including alpha
* xC: mix source 1 and source 2 using img component C (a, r, g or b) and force alpha to full opacity
* XC: mix source 1 and source 2 using img component C (a, r, g or b), including alpha
* shape ('rect'): shape type. Possible values are:
* rect: rounded rectangle
* square: square using smaller width/height value
* ellipse: ellipse
* circle: circle using smaller width/height value
* rhombus: axis-aligned rhombus
* text: force text mode even if text field is empty
* rects: same as rounded rectangle but use straight lines for corners
* other value: JS code for custom path creation, either string or local file name (dynamic reload
possible)
* grad_p ([]): gradient positions between 0 and 1
* grad_c ([]): gradient colors for each position, as strings
* grad_start ([]): start point for linear gradient or center point for radial gradient
* grad_end ([]): end point for linear gradient or radius value for radial gradient
* grad_focal ([]): focal point for radial gradient
* grad_mode ('pad'): gradient mode. Possible values are:
* pad: color padding outside of gradient bounds
* spread: mirror gradient outside of bounds
* repeat: repeat gradient outside of bounds
* text ([]): text lines (UTF-8 only). If not empty, force shape=text
* font ([]): font name(s)
* size (20): font size in percent of height (horizontal text) or width (vertical text), or absolute value
if negative
* baseline ('alphabetic'): baseline position. Possible values are:
* alphabetic: alphabetic position of baseline
* top: baseline at top of EM Box
* hanging: reserved, not implemented
* middle: baseline at middle of EM Box
* ideograph: reserved, not implemented
* bottom: baseline at bottom of EM Box
* align ('center'): horizontal text alignment. Possible values are:
* center: center of shape
* start: start of shape (left or right depending on text direction)
* end: end of shape (right or left depending on text direction)
* left: left of shape
* right: right of shape
* spacing (0): line spacing in percent of height (horizontal text) or width (vertical text), or absolute
value if negative
* bold (false): use bold version of font
* italic (false): use italic version of font
* underline (false): underline text
* vertical (false): draw text vertically
* flip (false): flip text vertically
* extend (0): maximum text width in percent of width (for horizontal) or height (for vertical), or
absolute value if negative
* keep_ar_rep (true): same as keep_ar for local image in replace mode
* txmx_rep ([]): same as txmx for local image in replace mode
* cmx_rep ([]): same as cmx for local image in replace mode
* pad_color_rep ('none'): same as pad_color for local image in replace mode
* rs_rep (false): same as rs for local image in replace mode
* rt_rep (false): same as rt for local image in replace mode
Transition modules
Transition gltrans - GPU only
This transition module wraps gl-transitions, see https://gl-transitions.com/ and gpac -h avmix:gltrans
for builtin transitions
Options:
* fx (''): effect name for built-in effects, or path to gl-transition GLSL file
Transition swipe - software/GPU
This transition performs simple 2D affine transformations for source videos transitions, with
configurable effect origin
Options:
* from ('left'): direction of video 2 entry. Possible values are:
* left: from left to right edges
* right: from right to left edges
* top: from top to bottom edges
* bottom: from bottom to top edges
* topleft: from top-left to bottom-right corners
* topright: from top-right to bottom-left corners
* bottomleft: from bottom-left to top-right corners
* bottomright: from bottom-right to top-left corners
* mode ('slide'): how video 2 entry impacts video 1. Possible values are:
* slide: video 1 position is not modified
* push: video 2 pushes video 1 away
* squeeze: video 2 squeezes video 1 along opposite edge
* grow: video 2 size increases, video 1 not modified
* swap: video 2 size increases, video 1 size decreases
Transition mix - software/GPU
This transition performs cross-fade of source videos
Transition fade - software/GPU
This transition performs fade to/from color of source videos
Options:
* color ('black'): fade color
Options (expert):
pl (str, default: avmix.json): local playlist file to load
live (bool, default: true): live mode
gpu (enum, default: off): enable GPU usage
* off: no GPU
* mix: only render textured path to GPU, use software rasterizer for the outlines, solid fills and
gradients
* all: try to use GPU for everything
thread (sint, default: -1): use threads for software rasterizer (-1 for all available cores)
lwait (uint, default: 1000): timeout in ms before considering no signal is present
ltimeout (uint, default: 4000): timeout in ms before restarting child processes
maxdur (dbl, default: 0): run for given seconds and exit, will not abort if 0 (used for live mode
tests)
updates (str): local JSON files for playlist updates
maxdepth (uint, default: 100): maximum depth of a branch in the scene graph
vsize (v2d, default: 1920x1080): output video size, 0 disable video output
fps (frac, default: 25): output video frame rate
pfmt (pfmt, default: yuv): output pixel format. Use rgba in GPU mode to force alpha channel
dynpfmt (enum, default: init): allow dynamic change of output pixel format in software mode
* off: pixel format is forced to desired value
* init: pixel format is forced to format of fullscreen input in first generated frame
* all: pixel format changes each time a full-screen input PID at same resolution is used
sr (uint, default: 44100): output audio sample rate, 0 disable audio output
ch (uint, default: 2): number of output audio channels, 0 disable audio output
afmt (afmt, default: s16): output audio format (only s16, s32, flt and dbl are supported)
alen (uint, default: 1024): default number of samples per frame
avgen
Description: AV Counter Generator
Version: 1.0
Author: GPAC Team
This filter generates AV streams representing a counter. Streams can be enabled or disabled using .I
type.
The filter is software-based and does not use GPU.
When .I adjust is set, the first video frame is adjusted such that a full circle happens at each exact
second according to the system UTC clock.
By default, video UTC and date are computed at each frame generation from current clock and not from
frame number.
This will result in broken timing when playing at speeds other than 1.0.
This can be changed using .I lock.
Audio beep is generated every second, with octave (2xfreq) of even beep used every 10 seconds.
When video is generated, beep is synchronized to video at each exact second.
If NTP injection is used, each video packet (but not audio ones) has a SenderNTP property set; if video
is not used, each audio packet has a SenderNTP property set.
Multiple output stream generation
More than one output size can be specified. This will result in multiple sources being generated, one per
size.
A size can be specified more than once, resulting in packet references when .I copy is not set, or full
copies otherwise.
Target encoding bitrates can be assigned to each output using .I rates. This can be useful when
generating dash:
Example
gpac avgen:sizes=1280x720,1920x1080:rates=2M,5M c=aac:FID=1 c=264:FID=2:clone -o live.mpd:SID=1,2
Multiview generation
In multiview mode, only the animated counter will move in depth backward and forward, as indicated by the
.I disparity value.
When .I pack is set, a packed stereo couple is generated for each video packet.
Otherwise, when .I views is greater than 2, each view is generated on a dedicated output PID with the
property ViewIdx set in [1, views].
Multi-view output forces usage of .I copy mode.
PID Naming
The audio PID is assigned the name audio and ID 1.
If a single video PID is produced, it is assigned the name video and ID 2.
If multiple video PIDs are produced, they are assigned the names videoN and ID N+1, N in [1, sizes].
If multiple .I views are generated, they are assigned the names videoN_vK and ID N*views+K-1, N in [1,
sizes], K in [1, views].
Options (expert):
type (enum, default: av): output selection
* a: audio only
* v: video only
* av: audio and video
freq (uint, default: 440): frequency of beep
freq2 (uint, default: 659): frequency of odd beep
sr (uint, default: 44100): output samplerate
flen (uint, default: 1024): output frame length in samples
ch (uint, default: 1): number of channels
alter (bool, default: false): beep alternatively on each channel
blen (uint, default: 50): length of beep in milliseconds
fps (frac, default: 25): video frame rate
sizes (v2il, default: 1280x720): video size in pixels
pfmt (pfmt, default: yuv): output pixel format
lock (bool, default: false): lock timing to video generation
dyn (bool, default: true): move bottom banner
ntp (bool, default: true): send NTP along with packets
copy (bool, default: false): copy the framebuffer into each video packet instead of using packet
references
dur (frac, default: 0/0): run for the given time in second
adjust (bool, default: true): adjust start time to synchronize counter and UTC
pack (enum, default: no): packing mode for stereo views
* no: no packing
* ss: side by side packing, forces .I views to 2
* tb: top-bottom packing, forces .I views to 2
disparity (uint, default: 20): disparity in pixels between left-most and right-most views
views (uint, default: 1): number of views
rates (strl): number of target bitrates to assign, one per size
logt (bool): log frame time to console
EXAMPLES
Basic and advanced examples are available at https://wiki.gpac.io/Filters
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: 2.2-rev655-g65430e305-master
Copyright: (c) 2000-2022 Telecom Paris distributed under LGPL v2.1+ - http://gpac.io
SEE ALSO
gpac(1), MP4Box(1)
gpac 2019 gpac(1)