gaspard7/wiki_gpac huggingface dataset:
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  
  
The special URL scheme `ipid://` can be used to locate an input pid by link directives.  
Example
```
in=ipid://#foo=bar
```
  
This will use pids having property `foo` with value `bar`, regardless of source filter ID.  
  
Example
```
in=ipid://TEST#foo=bar
```
  
This will use pids having property `foo` with value `bar` coming from filter with ID `TEST`.  
  
When using the `ipid://` scheme, filter chains cannot be specified (in accepts a single argument) and `port` is ignored.  
The syntax for link directive is the same as in gpac. However, if a listed property is not found on the input pid, the matching will fail.  
  
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.__
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.  
  
Example
```
{ "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](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 `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 `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
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)
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