gaspard7/wiki_gpac huggingface dataset:
Aspect Ratio and Sample Aspect Ratio

When output sample aspect ratio is set, the output dimensions are divided by the output sample aspect ratio.  
Example
```
evgs:osize=288x240:osar=3/2
```
  
The output dimensions will be 192x240.  
  
When aspect ratio is not kept ([keepar=off](#keepar=off)):  

- source is resampled to desired dimensions  
- if output aspect ratio is not set, output will use source sample aspect ratio  

  
When aspect ratio is partially kept ([keepar=nosrc](#keepar=nosrc)):  

- resampling is done on the input data without taking input sample aspect ratio into account  
- if output sample aspect ratio is not set ([osar=0/N](#osar=0/N)), source aspect ratio is forwarded to output.  

  
When aspect ratio is fully kept ([keepar=full](#keepar=full)), output aspect ratio is force to 1/1 if not set.  
  
When sample aspect ratio is kept, the filter will:  

- center the rescaled input frame on the output frame  
- fill extra pixels with [padclr](#padclr)
Options  {.no-collapse}

<div markdown class="option">  
<a id="osize" data-level="basic">__osize__</a> (v2di): osize of output video  
</div>  
<div markdown class="option">  
<a id="ofmt" data-level="basic">__ofmt__</a> (pfmt, default: _none_): pixel format for output video. When not set, input format is used  
</div>  
<div markdown class="option">  
<a id="ofr">__ofr__</a> (bool, default: _false_): force output full range  
</div>  
<div markdown class="option">  
<a id="keepar">__keepar__</a> (enum, default: _off_): keep aspect ratio  

- off: ignore aspect ratio  
- full: respect aspect ratio, applying input sample aspect ratio info  
- nosrc: respect aspect ratio but ignore input sample aspect ratio  
</div>  
  
<div markdown class="option">  
<a id="padclr">__padclr__</a> (str, default: _black_): clear color when aspect ration preservation is used  
</div>  
<div markdown class="option">  
<a id="osar">__osar__</a> (frac, default: _0/1_): force output pixel aspect ratio  
</div>  
<div markdown class="option">  
<a id="nbth">__nbth__</a> (sint, default: _-1_): number of threads to use, -1 means all cores  
</div>  
<div markdown class="option">  
<a id="hq">__hq__</a> (bool, default: _false_): use bilinear interpolation instead of closest pixel  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="wnd" data-level="basic">__wnd__</a> (str): size of output to crop, indicated as TxLxWxH. If % is indicated after a number, the value is in percent of the source width (for L and W) or height (for T and H). An absolute offset (+x, -x) can be added after percent  
</div>  
<div markdown class="option">  
<a id="copy">__copy__</a> (bool, default: _false_): copy the source pixels. By default the filter will try to forward crop frames by adjusting offsets and strides of the source if possible (window contained in frame)  
</div>  
<div markdown class="option">  
<a id="round">__round__</a> (enum, default: _up_): adjust dimension to be a multiple of 2  

- up: up rounding  
- down: down rounding  
- allup: up rounding on formats that do not require it (RGB, YUV444)  
- alldown: down rounding on formats that do not require it (RGB, YUV444)  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="size" data-level="basic">__size__</a> (v2di, default: _0x0_): source video resolution  
</div>  
<div markdown class="option">  
<a id="spfmt" data-level="basic">__spfmt__</a> (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|rgb4|rgb5|rgb6|rgba|argb|bgra|abgr|rgb|bgr|xrgb|rgbx|xbgr|bgrx|rgbd|rgbds|uncv): source pixel format. When not set, derived from file extension  
</div>  
  
<div markdown class="option">  
<a id="fps" data-level="basic">__fps__</a> (frac, default: _25/1_): number of frames per second  
</div>  
<div markdown class="option">  
<a id="copy" data-level="basic">__copy__</a> (bool, default: _false_): copy source bytes into output frame. If not set, source bytes are referenced only  
</div>
Simple Playback

In most cases your content consists of one audio stream and one video stream and composing them together is not needed.
You can play such content using:
```gpac -play source```

The `-play` alias resolves to `-i @{1} aout vout`, so the above is equivalent to:
```gpac -i source aout vout```

If you only want to play the audio, use
```gpac -i source aout```

If you only want to play the video, use
```gpac -i source vout```

If you only want to play the video as fast as possible without dropping, use
```gpac -i source vout:vsync=0```


See [this howto](filters-playback) for more details.
GUI Media player

The media player mode runs the compositor filter with an interactive GUI. It can be used to play interactive BIFS, VRML or SVG files, 360 videos, select streams in a session, view statistics, etc.

The player is invoked using [gpac](gpac_general) application:

```
#launching the GUI
gpac -gui

#launching the GUI with a target URL
gpac -gui source_url

```

The GUI accepts command-line options described in 
```
#help on GUI options
gpac -h gui
```

Using this command, the player will use 2 extra threads (i.e. `-threads=2` set by default).
Simple Media player

The simple media player mode runs the compositor filter without any GUI. It can be used to play interactive BIFS, VRML or SVG files, 360 videos, etc.

The simple player mode is invoked using [gpac](gpac_general) application:

```gpac -mp4c source_url```

Using this command, the player will use 2 extra threads (i.e. `-threads=2` set by default). 

The available options for this mode can be checked using:

```
#help on GUI options
gpac -h mp4c
```

_NOTE This mode is mostly used to debug scenes or when GUI is not needed._
Overview

This page describes the status of the implementation in the GPAC project of the Scalable Vector Graphics (SVG) language. It describes the features that are implemented and the roadmap for missing or new features.

The GPAC project includes support for the playback and rendering of SVG 1.2 content. The goal is not to provide yet another mixed HTML/SVG browser but to focus on the integration of multimedia description languages with audio/video data. The GPAC player will therefore remain in between a document browser and a traditional audio/video player with support for languages like BIFS, SVG, X3D ...

The implementation of the SVG support in GPAC is divided into 3 parts as follows:

- SVG Parsing

The GPAC framework reads SVG files (or streams) and builds the memory tree. It uses a (simple, limited, but functional) SAX parser. The parser can load, progressively or not, an SVG document into memory. If you are interested, the source code for this part is [here](https://github.com/gpac/gpac/blob/master/src/scene_manager/loader_svg.c).

- SVG Tree Management

This part of the SVG support is common in the GPAC implementation with the MPEG-4 BIFS tree management, and is called in general Scene Graph Management. The Scene Graph part is responsible for the creation of elements, the handling of attributes (parsing, dump, cloning ...). It also handles the animations and scripting features of SVG.
If you check out the source code, look for svg_nodes.h, scenegraph_svg.h, [src/scenegraph](https://github.com/gpac/gpac/tree/master/src/scenegraph)/svg_*.*.

- SVG Compositing and Rendering

The compositing and rendering operations consists in applying animations, triggering user interactions, rasterizing the vector graphics and producing the final image. If you check out the source code, look for [src/compositor](https://github.com/gpac/gpac/tree/master/src/compositor)/svg*.c.
Status

GPAC currently supports SVG Tiny 1.2. Some elements, supported at parsing, are not yet implemented in the rendering. Scripting support using MicroDOM is provided by QuickJS engine. Detailed support for each element, attribute, property and script interfaces is available [here](http://gpac.sourceforge.net/gpac_svg_support.xml).

Results of the GPAC behavior on the SVG 1.2 Tiny Test Suite can be found [here](http://gpac.sourceforge.net/gpac_svg_testsuite_status.xml).
Foreword {: data-level="all"}

A true multimedia player is a complex system involving networking, media and user interactions management, rasterizing, etc. The following section is a more or less exhaustive list of supported features in the GPAC player.
Since the GPAC player is mostly a frontend to the filter engine in GPAC, most features from [Filters](Filters) are supported.

With the deprecation of NPAPI and browser plugins in general, GPAC player can no longer be embedded in web browsers.
VRML-Based Scene Graphs

- Complete scene graphs for MPEG-4/VRML and X3D, configurable through included scene graph generators.
- All common interactivity types (events and routes, interpolators, conditionals, MPEG-4 valuators and X3D event filters).
- ECMAScript 2020 support through [QuickJS](https://bellard.org/quickjs/) engine.
- Full-feature PROTO and EXTERNPROTO support.
- MPEG-4 InputSensor (KeySensor, Mouse and StringSensor), X3D KeySensor and StringSensor support.
- Loading from binary (TS or MP4), text (bt) and XML (XMT-A)
- SAX Progressive loading of XMT and X3D files (text and gziped).

The status of VRML/BIFS implementation in GPAC can be checked [here](BIFS-Implementation-Status).

The status of X3D implementation in GPAC can be checked [here](X3D-Implementation-Status).
Hardcoded EXTERNPROTO nodes

GPAC extends VRML/BIFS node set through its hardcoded proto mechanism. These are protos with predefined URLs and interfaces, allowing BIFS compression without modifying the language syntax. These nodes are identified by a proto URN starting with `urn:inet:gpac:builtin:`.

The following hardcoded protos are available:

- PlanarExtrusion: extrude a 2D shape (except text) along a 2D path
- PathExtrusion: extrude a 2D shape, including text,  along a 2D path
- PlaneClipper: set a 3D plane clipper
- VRGeometry: portion of a sphere, used for 360 video tiling
- VRHud: build a simple head-up display in 360 videos showing various views of the sphere
- OffscreenGroup: draw all children (2D only) into offscreen memory 
- DepthGroup: assign depth to 2D children
- DepthViewPoint: configure depth position and scaling for 2D depth
- IndexedCurve2D: Curve2D reusing sub-paths through indexes 
- Untransform: reset current transformation to identity
- StyleGroup: force all children node to use the appearance given in the StyleGroup
SVG-based Scene Graph

- SVG 1.2 Tiny scene graph - see [SVG implementation details](SVG-Implementation-Status)
- Complete LASeR scene graph (subset of SVG Tiny 1.2)
- Some SVG 1.1 Full extensions
- XML events and SMIL animation for SVG content
- uDOM (MicroDOM) ECMAScript support through  [QuickJS](https://bellard.org/quickjs/) engine
- SAX Progressive loading of SVG files (text and gzipped)
3D Rendering

- Graphics backend: OpenGL and OpenGL-ES
- Alpha-blending (z-sorting), fast texturing when available (support for rectangular textures and non-power-of-2 textures), gradients, X3D RGBA colored meshes
- Frustum culling, ray-based node picking, decent collision detection through AABB tree, gravity
- Navigation in main screen and in 3D layers, viewpoint selection
- Text drawing in vectorial mode or textured mode (supports NICE text under OpenGL!)
Media Decoders

Decoders included in default builds:

- PNG, JPEG (libJPEG) and JPEG-2000
- MPEG-4 AAC, MPEG-1/2 audio, Dolby AC-3
- MPEG-1/2/4, H264|AVC, SVC, HEVC, L-HEVC
- AMR speech codec using 3GPP fixed-point reference code
- All codecs supported by FFmpeg
- Xiph Media codecs: Vorbis, Theora (FLAC and Opus supported through FFmpeg)
- SRT / 3GPP timed text / MPEG-4 Streaming Text decoder /WebVTT (rendering done through GPAC)
Networking

Any possible input from GPAC filter architecture is supported by the player. This includes:

- File access from local drive, HTTP download, pipes and sockets.
- MP4, 3GP, MP3/Shoutcast, JPEG, PNG, OGG/Icecast, AMR/EVRC/SMV, SAF, raw YUV and PCM
- AAC files and radio streams (icecast AAC-ADTS)
- Subtitles (SRT/SUB/TeXML/TTXT/WebVTT formats)
- MPEG-2 TS files and IP streams (and  experimental support for DVB for linux)
- MPEG-DASH, HLS and Smooth. This includes:
    - playback from an HTTP(s) server or from local storage for test purposes.
    - media segments based on TS and ISOBMF, with 3GPP timed text support
    - static (on demand) and dynamic (live) sessions
    - multiple period support
    - group selection support
    - independent component download (one adaptation set for audio, one for video)
    - most MPD syntax is supported
    - bitstream switching mode (single init segment) and non-bitstream switching mode
    - manual quality switching by using ctrl+h and ctrl+l
    - basic automatic quality switching when playing HTTP urls
    - tiling, gaze and decoding speed adaptation
 
- SDP input - RTP/RTSP streaming including RTP/UDP streaming, RTP over RTSP and HTTP tunneling of RTP traffic (QuickTime/Darwin Streaming Server). RTP Payload formats supported are:
    - RFC 3016 for MPEG-4 Simple Profile video and simple LATM AAC
    - RFC 3640 for any form of MPEG-4 streams (audio, video, systems)
    - RFC 3267 for AMR audio (narrow-band, octet-align format only)
    - RFC 2250 for MPEG-1/2 audio and video and MPEG-2 TS
    - RFC 2429 for H263 video used by 3GPP (no VRC, no extra Picture Header)
    - RFC 3984 for H264/AVC video (only STAP-A, FU-A and regular NAL units)
    - RFC 7798 for H265|HEVC video (AP, FU and regular NAL units)

 - Generic input using FFmpeg libavformat, supports most AV containers known (MPEG, VOB, AVI, MOV ...) and many protocols
 - Generic frame grabber FFmpeg libavdevice, supports many capture devices
MPEG-4 Scene Description Version 1

Node  |  Rendering  |  Notes
--- | --- | ---
Anchor | Supported |
AnimationStream | Supported |
Appearance | Supported |
AudioBuffer | Supported | for natural audio, not MPEG-4 SA
AudioClip | Supported |
AudioDelay | Not Supported |
AudioFX | Not Supported |
AudioMix | Not Supported |
AudioSource | Supported | for natural audio, not MPEG-4 SA
AudioSwitch | Not Supported |
Background | Supported |
Background2D | Supported |
Billboard | Supported |
Bitmap | Supported |
Box | Supported |
Circle | Supported |
Collision | Supported |
Color | Supported |
ColorInterpolator | Supported |
CompositeTexture2D | Supported |
CompositeTexture3D | Supported |
Conditional | Supported |
Cone | Supported |
Coordinate | Supported |
Coordinate2D | Supported |
CoordinateInterpolator | Supported |
CoordinateInterpolator2D | Supported |
Curve2D | Supported |
Cylinder | Supported |
CylinderSensor | Supported |
DirectionalLight | Supported |
DiscSensor | Supported |
ElevationGrid | Supported |
Expression | Supported |
Extrusion | Supported |
Face | Supported |
FaceDefMesh | Supported |
FaceDefTables | Supported |
FaceDefTransform | Supported |
FAP | Supported |
FDP | Supported |
FIT | Supported |
Fog | Supported |
FontStyle | Supported |
Form | Supported |
Group | Supported |
ImageTexture | Supported |
IndexedFaceSet | Supported |
IndexedFaceSet2D | Supported |
IndexedLineSet | Supported |
IndexedLineSet2D | Supported |
Inline | Supported |
LOD | Supported |
Layer2D | Supported |
Layer3D | Supported |
Layout | Supported |
LineProperties | Supported |
ListeningPoint | Not Supported |
Material | Supported |
Material2D | Supported |
NavigationInfo | Supported |
Normal | Supported |
NormalInterpolator | Supported |
OrderedGroup | Supported |
OrientationInterpolator | Supported |
PixelTexture | Supported |
PlaneSensor | Supported |
PlaneSensor2D | Supported |
PointLight | Supported |
PointSet | Supported |
PointSet2D | Supported |
PositionInterpolator | Supported |
PositionInterpolator2D | Supported |
ProximitySensor2D | Supported |
ProximitySensor | Supported |
QuantizationParameter | Supported |
Rectangle | Supported |
ScalarInterpolator | Supported |
Script | Supported |
Shape | Supported |
Sound | Supported | Stereo spatializer only
Sound2D | Supported |
Sphere | Supported |
SphereSensor | Supported |
SpotLight | Supported |
Switch | Supported |
TermCap | Supported | Partial support of caps
Text | Supported |
TextureCoordinate | Supported |
TextureTransform | Supported |
TimeSensor | Supported |
TouchSensor | Supported |
Transform | Supported |
Transform2D | Supported |
Valuator | Supported |
Viewpoint | Supported |
VisibilitySensor | Supported |
Viseme | Supported |
WorldInfo | Supported |

Note: VRML 97 nodes not included in MPEG-4 are not supported and will ** NEVER ** be. Their X3D equivalents are not supported but will be some day...
MPEG-4 Scene Description Version 2

Node  |  Rendering  |  Notes
--- | --- | ---
AcousticMaterial | Not Supported |
AcousticScene | Not Supported |
ApplicationWindow | Not Supported |
BAP | Not Supported |
BDP | Not Supported |
Body | Not Supported |
BodyDefTable | Not Supported |
BodySegmentConnectionHint | Not Supported |
DirectiveSound | Not Supported |
Hierarchical3DMesh | Not Supported |
MaterialKey | Supported |
PerceptualParameters | Not Supported |
MPEG-4 Scene Description Version 5

Node  |  Rendering  |  Notes
--- | --- | ---
BitWrapper | Supported | depends on the attached AFX decoder
CoordinateInterpolator4D | Supported |
DepthImage | Not Supported |
FFD | Not Supported |
MeshGrid | Not Supported |
NonLinearDeformer | Supported |
NurbsCurve | Not Supported |
NurbsCurve2D | Not Supported |
NurbsSurface | Not Supported |
OctreeImage | Not Supported |
PointTexture | Not Supported |
PositionAnimator | Supported |
PositionAnimator2D | Supported |
PositionInterpolator4D | Supported |
ProceduralTexture | Not Supported |
SBBone | Not Supported |
SBMuscle | Not Supported |
SBSegment | Not Supported |
SBSite | Not Supported |
SBSkinnedModel | Not Supported |
SBVCAnimation | Not Supported |
ScalarAnimator | Supported |
SimpleTexture | Not Supported |
SubdivisionSurface | Not Supported |
SubdivSurfaceSector | Not Supported |
WaveletSubdivisionSurface | Not Supported ||
MPEG-4 Scene Description Version 6

Node  |  Rendering  |  Notes
--- | --- | ---
Clipper2D | Not Supported |
ColorTransform | Supported |
Ellipse | Supported |
LinearGradient | Supported |
PathLayout | Supported |
RadialGradient | Supported |
SynthesizedTexture | Not Supported |
TransformMatrix2D | Supported |
Viewport | Supported |
XCurve2D | Supported |
XFontStyle | Not Supported |
XLineProperties | Supported |
Overview {: data-level="all"}

GPAC provides a highly configurable multimedia player through the [compositor](compositor) filter.

This player is much more than a traditional audiovisual player because, in addition to its capabilities to play most video or audio formats and its support for most of the existing delivery protocols, it focuses on graphics, animations and interactivity technologies.

The player can playback audiovisual content mixed with 2D or 3D content in the following formats: MPEG-4 BIFS and LASeR, W3C SVG, W3D VRML and X3D. The player also supports 360 video (EQR projection only for now), and QTVR images (Cube Maps).
GUI Media player

The GUI media player mode runs the compositor filter with an interactive GUI.
It can be used to play interactive BIFS, VRML or SVG files, 360 videos, select streams in a session, view statistics, etc.

The player is invoked using [gpac](gpac_general) application:

```
#launching the GUI
gpac -gui

#launching the GUI with a target URL
gpac -gui source_url

```

The GUI accepts command-line options described in 
```
#help on GUI options
gpac -h gui
```

Using this command, the player will use 2 extra threads (i.e. `-threads=2` set by default).
Checking playback capabilities

For the purpose of evaluating if the compilation and installation steps went well, the GPAC framework provides a test content in the form of an MPEG-4 file containing an MPEG-4 BIFS stream testing JavaScript, text rendering, 2D vector graphics and OpenGL playback, image display (PNG stream), video playback( MPEG-4 video Part 2 stream) and audio playback (AAC stream).

This file is called [gpac_cfg_test.mp4](https://github.com/gpac/gpac/raw/filters/share/doc/gpac_cfg_test.mp4)  and is located in the share install directory of GPAC (/usr/share/gpac/, \Program Files\GPAC\share\) and 

If the installation step went well, you should see this result and hear the audio:

[[/images/test_compositor_ok.png]]

Otherwise you should see at least one of the following lines:

[[/images/test_compositor_ko.png]]
Simple AV scene: No compositor :)

Let's start with something simple before pulling out the hammer.  
Assume you have a source (MP4, RTP, DASH, ...) and you want to output the raw decoded data of this source to something such as [pipes](pipes) , [sockets](sockets) , or [raw data](raw-formats).

The simplest way to do this in GPAC is to use the [reframer](reframer) filter, enforcing it to use RAW data.
 
```
gpac -i $SOURCE reframer:raw -o dump.yuv
gpac -i $SOURCE reframer:raw -o dump.pcm
gpac -i $SOURCE reframer:raw -o dump.pcm -o dump.yuv
```

If you need to perform say resampling and resizing:

Prior to GPAC 2.0
```gpac -i $SOURCE reframer:raw:FID=1 resample:sr=48k:ch=1:SID=1 @ -o dump.pcm ffsws:osize=256x256:SID=1 @ -o dump.yuv```

With GPAC 2.0, syntax can be simplified (old syntax is still working)
```gpac -i $SOURCE resample:sr=48k:ch=1 ffsws:osize=256x256 -o dump.pcm -o dump.yuv```


 You can obviously replace the output filters with any filters you like.
```gpac -i $SOURCE reframer:raw @ -o pipe://videopipe:ext=yuv @1 -o udp://127.0.0.1:1234/:ext=pcm```

With GPAC 2.0:
```gpac -i $SOURCE reframer:raw -o pipe://videopipe:ext=yuv -o udp://127.0.0.1:1234/:ext=pcm```
Complex AV scene

The [compositor](compositor) filter is a in charge of 2D+3D rasterization of natural and synthetic content and audio mixing, in a timed fashion. It is the core of [interactive rendering](Player) of gpac, but it can also be used in non-interactive mode to compose scenes in a filter chain. The compositor currently uses BIFS/BT/XMT, SVG/LASeR or VRML/X3D to describe multimedia scenes, scriptable through JavaScript.
Overlaying

Assume you want to insert some text and logo over a video. To do this with GPAC, you can:

- use a BIFS/BT/XMT scene
- use a [JavaScript drawing](evg) filter
- use the [AVMix](avmix) filter (see [howto](avmix_tuto) )

In this HowTo, we will only talk about using the compositor filter.

Design your scene, play it (`gpac -mp4c $BTSCENE`) to see the result. You can get a lot of inspiration from the gpac [BIFS tests](https://github.com/gpac/gpac/tree/master/tests/media/bifs).
In order to perform overlays, you need to use a Background2D node with a url `gpid://` cf [this example](http://download.tsi.telecom-paristech.fr/gpac/gpac_test_suite/resources/media/raw/overlay.bt). This will instruct the video to take the first visual PID connecting to the compositor and use it as source for this background node.

You can then compose the scene as follows:

```gpac -i $SOURCE -i $BTSCENE compositor -o dump.pcm -o dump.rgb```

In this mode, the compositor will generate a new visual frame for each incoming video frame (keeping its timing info), update the scene time based on that frame time and then render animations and mix audio according to this clock.  
This is a work in progress in GPAC, we might want to use the overlay facility with SVG or VRML/X3D as well (but these scene graphs don't have the convenient notion of 2D video background).

__Discussion__
The compositor is quite flexible and provides many options. It can be instructed to enforce a given output pixel format or audio format. When using 3D scenes, the compositor will output OpenGL textures as data packets. When using 2D scenes, it will output (unless enforced otherwise) regular data packets, by default in the source video pixel format. If the filter chains allows it, the video processing is done in place on the video input frame; this requires no other filter use these frames obviously. If the output format is enforced, video data will be copied. Audio is send as PCM data using the compositor audio options.