gpac(1) GPAC gpac(1) NAME gpac - GPAC command-line filter session manager SYNOPSIS gpac [options]FILTER[LINK]FILTER[...] DESCRIPTION This page describes all filters usually present in GPAC To check for help on a filter not listed here, use gpac -h myfilter inspect Description: Packet inspector 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 is forced to frame 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 dumping 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 * tmcd: timecode as provided in SEI, N/A if not available (requires reframer) * 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, consuming packets after 10s of media are ready and rebuffering if less than 1s of media. Options (expert): log (str, default: stdout, Enum: _any|stderr|stdout|GLOG|TL|null): set probe log filename * _any: target file path and name * stderr: dump to stderr * stdout: dump to stdout * GLOG: use GPAC logs app@info * TL: use GPAC log tool TL at level info * null: silent mode 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), similar to -bsdbg option of reframer filters * 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 stats (bool, default: false): compute statistics for PIDs timeout (uint, default: 5000): timeout in ms when doing simple inspection in case no packets are received on some PIDs 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: Source prober 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, Enum: _any|stderr|stdout|GLOG|null): set probe log filename to print number of streams * _any: target file path and name * stderr: dump to stderr * stdout: dump to stdout * GLOG: use GPAC logs app@info * null: silent mode 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: 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: 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, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|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 * true: video texture is not resized but emulated with padding. This usually speeds up video mapping on shapes but disables texture transformations * false: 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, Enum: 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|rgb8|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 edits (enum, default: auto): do not use edit lists * auto: track delay and no edit list when possible * no: ignore edit list * strict: use edit list even if only signaling a delay 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, fails if source is not fragmented 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: 10000000): 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=splitx (dasher mode), rem otherwise nodata (enum, default: no): control sample data loading * no: regular load * yes: skip data loading * fake: allocate sample but no data copy lightp (bool, default: false): load minimal set of properties initseg (str): local init segment name when input is a single ISOBMFF segment extk (bool, default: true): allow external track loading ctso (sint): value to add to CTS offset for tracks using negative ctts - set to -1 to use the cslg box info or the minimum cts offset present in the track - set to -2 to use the minimum cts offset present in the track (cslg ignored) norw (bool, default: false): skip reformatting of samples - should only be used when rewriting fragments keepc (bool, default: true): keep corrupted samples (for multicast sources only) sigfo (bool, default: false): signal segment boundaries on output packets for DASH or HLS sources (same as sigfrag but independent from dasher options) drefu (str): override dref URL in source file with given value 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. Packet Injecting The filter can be used to inject a single packet instead of a file using .I pck option. No specific properties are attached, except a timescale if .I ptime is set. Example gpac fin:pck=str@"My Sample Text":ptime=2500/100:#CodecID=stxt:#StreamType=text This will declare the PID as WebVTT and send a single packet with payload My Sample Text and a timestamp value of 25 second. 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 ptime (frac, default: 0/0): timing for data packet, ignored if den is 0 btplay Description: BT/XMT/X3D decoder 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 is set to N, 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: none): 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 idelay (uint, default: 0): delay first request by the given number of ms svgplay Description: SVG decoder This filter parses SVG files directly into the scene graph of the compositor. When .I sax_dur is set to N, 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 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 rfac4 Description: AC4 reframer This filter parses AC4 files/data and outputs corresponding audio PID and frames. No options ufac4 Description: AC4 writer This filter converts MPEG-H Audio streams into AC4 encapsulated data. Options (expert): rcfg (bool, default: true): force repeating decoder config at each I-frame 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 upes (enum, default: no): keep unknown PES streams * no: ignored the streams * info: declare the stream as fake (no data forward), turns on dvbtxt * full: declare the stream and sends data mappcr (bool, default: true): remap PCR and timestamps into continuous timeline sigfo (bool, default: false): signal segment boundaries on output packets for DASH or HLS sources (same as sigfrag but independent from dasher options) 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] When the socket is listening in keep-alive .I ka mode: - a single connection is allowed and a single output PID will be produced - each connection close event will triger a pipeline flush 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 Time Regulation The filter uses the time between the last two received packets to estimates how often it should check for inputs. The maximum and minimum times to wait between two calls is given by the .I mwait option. The maximum time may need to be reduced for very high bitrates sources. 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 mwait (v2di, default: 1x30): set min and max wait times in ms to avoid too frequent polling 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 This filter reads raw MPEG-2 TS from DVB-T/T2 and DVB-S/S2 cards on linux. The URL scheme used is dvb:// with the following syntaxes: * `dvb://CHAN`: tunes to channel CHAN in the channel configuration file. * `dvb://+CHAN`: tunes to multiplex contaning channel CHAN and expose all programs. * `dvb://=N`: tunes to the N-th channel in the channel configuration file. * `dvb://@FREQ`: tunes to frequency FREQ and exposes all channels in multiplex. * `dvb://@=N`: tunes to N-th frequency and exposes all channels in multiplex. * `dvb://@chlist`: populates the .I chans option with available channels in the configuration file and do nothing else. When tuning by channel name CHAN, the first entry in the channel configuration file starting with CHAN will be used. The channel configuration file is set through .I chcfg. The expected format is VDR as produced by w_scan, with a syntax extended for comment lines, starting with #. Within a comment line, the following keywords can be used to override defaults: * `dev=N`: set the adapter index (N integer) or full path (N string). * `idx=K`: set the frontend index K. * `csidx=S`: set the committed switch index for DiSEqC. To view the default channels, use gpac -hx dvbin. Options (expert): src (cstr): URL of source content block_size (uint, default: 65536): block size used to read device chcfg (cstr, default: $GCFG/channels.conf): path to channels configuration file dev (str, default: 0): path to DVB adapter - if first character is a number, this is the device index idx (uint, default: 0): frontend index timeout (uint, default: 5000): timeout in ms before tune failure csleep (uint, default: 15): config sleep in ms between DiSEqC commands csidx (uint, default: 0): committed switch index for DiSEqC chans (strl): list of all channels, only pupulated for dvb://@chlist URL 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: DASH & 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 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: 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, Enum: 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 mcast_shift (sint, default: 0): shift requests time by given ms for multicast sources 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) xas (enum, default: codec): enable cross adaptation set switching (disabled if .I split_as is set) * no: disabled * codec: switching across sets only allowed for same codec * all: switching across sets allowed across any representation types 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 bsmerge (bool, default: true): allow merging of video bitstreams (only HEVC for now) keep_burl (enum, default: strip): control BaseURL in manifest * strip: strip BaseURL (default) * keep: keep BaseURL * inject: inject local relative URL before BaseURL value specified by relative_url option relative_url (str, default: ./): relative string to inject before BaseURL when keep_base_url is set to inject 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/xmlformats/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 * pad0: decrypt nothing and replace all crypted bits with 0 * pad1: decrypt nothing and replace all crypted bits with 1 * padsc: decrypt nothing and replace all crypted bytes with start codes 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/xmlformats/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 bk_stats (bool): print number of encrypted blocks to stdout upon exit bk_skip (bool): skip encryption but performs all other tasks (test mode) 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: gpac -i source.jpg:#ItemID=1 -o file.mp4 Storage The .I store option allows controlling if the file is fragmented (frag) or not, and when not fragmented, how interleaving (inter) is done. For cases where disk requirements are tight and fragmentation cannot be used, it is recommended to use either flat or fstart (fast-start) modes. sfrag mode is similar frag mode but aligns fragments on SAP samples. It is implied when using sfrag_tolerance. sfrag_tolerance is expressed as a percentage of the fragment duration (cdur). It allows to modulate the fragment durations while keeping the same number of fragments per segment. This is useful to align fragments on randomly placed SAP samples (typically scene-cuts or events). 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 itags 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 Property names formatted as cust_NAME@MEAN are added as a custom tag with name NAME and mean MEAN. Both NAME and MEAN can be empty. 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 * `tkgp_T4CC`: set/remove membership to track group with type T4CC and ID given by property value. A negative value N removes from track group with ID -N 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 this property 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 The default media type used for a PID can be overridden using property StreamSubtype. Example -i src.srt:#StreamSubtype=sbtl [-i ...] -o test.mp4 This will force the text stream to use sbtl handler type instead of default text one. Subtitle streams may be used as chapters by setting the property IsChap on the desired PID. Example -i src.srt:#IsChap [-i ...] -o test.mp4 This will force the text stream to be used as a QT chapter track. 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: auto): set composition offset mode for video tracks * auto: if fragmenting an ISOBMFF source, use source settings otherwise resolve to edit * 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 * 0: single sidx * >0: hierarchical or daisy-chained sidx * <0: 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 (DASH mode) or of a fragment (non-DASH mode) 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 fragment flags in initial moov 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) prft (enum, default: sender): set prft box mode, disabled if not fragmented mode * off: disable prft box * sender: put ntp time before encoder * both: put sender time (if available) and ntp time when writing the moof 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 force_seig (bool, default: false): force writing seig sample group for encrypted samples, even when all samples use the default single-key CENC configuration 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] lmsg (bool, default: false): set lmsg brand for the last segment or fragment 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 with channel count from stream (except for (e)AC3/4), recommended for backward compatibility * v0s: use v0 signaling and force channel count to 2 (stereo) if more than 2 channels * v0bs: use v0 signaling from bitstream only * v1: use v1 signaling, ISOBMFF style (will mux raw PCM as ISOBMFF style) * v1qt: use v1 signaling, QTFF style * v2qt: use v2 signaling, QTFF style (lpcm entry type) 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 (uses cmov for QT) * 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 dvsingle (bool, default: false): ignore DolbyVision profile 8 in xps inband mode if profile 5 is already set tsalign (bool, default: true): enable timeline realignment to 0 for first sample - if false, this will keep original timing with empty edit (possibly long) at begin chapm (enum, default: both): chapter storage mode * off: disable chapters * tk: use chapter track (QT-style) * udta: use user-data box chapters * both: use both chapter tracks and udta patch_dts (bool, default: false): patch previous samples duration when dts do not increase monotonically uncv (enum, default: prof): use uncv (ISO 23001-17) for raw video * off: disabled (always the case when muxing to QT) * gen: enabled, do not write profile * prof: enabled and write profile if known * tiny: enabled and write reduced version if profile known and compatible trunv1 (bool, default: false): force using version 1 of trun regardless of media type or CMAF brand rsot (bool, default: false): inject redundant sample timing information when present sfrag_tolerance (uint, default: 0): start fragment on SAP if previous fragment is not shorter than the indicated percentage of cdur scte35 (enum, default: auto): SCTE-35 signalling * auto: 'xmlbin' or 'evte' depending on the input * xmlbin: out-of-band (MPD) EventStream with xml+bin (recommended) * inband: in-band emsg boxes * all: signal everywhere detected * none: no EventStream nor emsg boxes auto_reorder (bool, default: false): reorder tracks in moov (first video, then audio, then text then other) 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/xmlformats/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/xmlformats/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 force_sync (bool, default: false): force sync points on non-IDR samples with I slices (not compliant) 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 refs (bool, default: false): import sample reference picture list (currently only for HEVC and VVC) seirw (bool, default: true): rewrite AVC sei messages for ISOBMFF constraints audelim (bool, default: false): keep Access Unit delimiter in payload keepfiller (bool, default: false): keep filler NAL units in output 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 media@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/xmlformats/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 * stxt and sbtt: ISO/IEC 14496-30 text stream and text 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 or : - for , ,