gaspard7/wiki_gpac huggingface dataset:
Build and install the gpac library

Refer to the gpac [build documentation](/Build/Build-Introduction) provides detailed instructions for compiling GPAC on all supported platforms.

For linux systems, following the general build, you can use
 `$ make install-lib` to install the necessary libraries and header files. It will also install a gpac.pc file for pkg-config. With it you can easily build projects that use the gpac library with something like:
 `$ gcc -o example $(pkg-config --cflags gpac) example.c $(pkg-config --libs gpac)`

**_NOTE:_**: pkg-config needs to be installed on your machine.
Creating a filter session

The GPAC filter session object allows building media pipelines using multiple sources and destinations and arbitrary filter chains.

The simplest way to create a session object is to use the gf_fs_new_defaults() function.

```C 
GF_FilterSession *session = gf_fs_new_defaults(0u);  
if (session == NULL) {  
    fprintf(stderr, "Failed to create GPAC session\n");  
}
```

This function will create a new filter session, loading parameters from [gpac config](/Filters/core_config). This will also load all available filter registers not blacklisted.

More information on this function and alternatives can be found on the doxygen [libgpac documentation page](https://doxygen.gpac.io/group__fs__grp.html#gaa7570001b4d4c07ef8883b17d7ed12ca).
Loading filters

### Loading a source filter

Filters can be processing block ex: (de-)multiplexers, de/encoders, media segmenters (for HTTP Adaptive Streaming), RTSP server. But also they can be file access objects either as a source filter or a destination filter, (eventually pipe and sockets too):

```C
GF_Err gf_err = GF_OK;
GF_Filter *src_filter = gf_fs_load_source(session, "logo.png", NULL, NULL, &gf_err);  
if (gf_err != GF_OK)  
{  
  fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
}
```

Alternatively to [gf_fs_load_source](https://doxygen.gpac.io/group__fs__grp.html#gafce8e6e28696bc68e863bd4153282f80) function we can use the more generic [gf_fs_load_filter](https://doxygen.gpac.io/group__fs__grp.html#ga962fa3063a69ef02e43f06abe14cfe65) and use the [Fin](/Filters/fin) filter (followed by its options with the syntax :opt=val) as follows:

```C
GF_Filter *src_filter = gf_fs_load_filter(session, "fin:src=logo.png", &gf_err);
```

### Loading a filter

Filters are described through a [__gf_filter_register](https://doxygen.gpac.io/struct____gf__filter__register.html) structure. A set of built-in filters are available, and user-defined filters can be added or removed at runtime.

  

The filter session keeps an internal graph representation of all available filters and their possible input connections, which is used when resolving connections between filters.

  

The following code snippet provides an example to load the [reframer](/Filters/reframer) filter.

  
```C
GF_Filter *reframer_filter = gf_fs_load_filter(session, "reframer", &gf_err);  
if (gf_err != GF_OK)  
{  
    fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
}
```

options can be specified the same way as in the CLI of gpac, as stated with ‘fin’ above. Here is another example:

```C
GF_Filter *reframer_filter = gf_fs_load_filter(session, "reframer:rt=on", &gf_err);
```

### Loading a destination filter

Loading a destination filter, exactly like loading a source filter mentioned above can be done in two different ways:

  

by using [gf_fs_load_destination()](https://doxygen.gpac.io/group__fs__grp.html#ga2fd8f1f59622bc781cc81aafee99ee7d) function :

  
```C
GF_Err gf_err = GF_OK;  
GF Filter *src_filter = gf_fs_load_destination(session, "logo_result.png", NULL, NULL, &gf_err);  
if (gf_err != GF_OK)  
{  
    fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
}
```

Or by using the gf_fs_load_filter and use the Fout filter (or any alternative output destinations pipes, sockets.. ) as follows:
  
```C
//load destination filter  
GF_Filter *dst_filter = gf_fs_load_filter(session, "fout:dst=logo_result.png", &gf_err);  
if (gf_err != GF_OK)
{  
    fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
}
```
Connecting filters and creating a filter chain

The function [gf_filter_set_source()](https://doxygen.gpac.io/group__fs__filter.html#ga9d8a5da25284b1325d0210cc04a6a302) serves the purpose of explicitly assigning a source ID to a designated filter. Therefore it serves as an indicator for the graph resolver to link two filters. (it does not do the actual linking).  

It is crucial to invoke this function before establishing a connection from the specified source filter. If the linked filter lacks an assigned ID, the function automatically generates a dynamic one in the format %08X, utilizing the memory address of the filter.

It is important to note that in multithreaded sessions, proper session locking is essential before the filter creation step and must be unlocked after calling this function. Failure to do so may result in graph resolution occurring before the gf_filter_set_source() is invoked.

The function accepts three parameters, including the target filter, the filter to link from (source filter), and any link extensions allowed in link syntax, providing flexibility in defining link properties. ( Pid name, properties, types of properties…)

  
```C
gf_filter_set_source(destination_filter, source_filter, NULL);
```
Disabling the graph resolver and connecting filters manually

The helper function [gf_fs_set_max_resolution_chain_length()](https://doxygen.gpac.io/group__fs__grp.html#gaef500f3cb6589e05c161d8a50ab20f12) sets the maximum length of a filter chain dynamically loaded to solve connection between two filters. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually. ( using the above gf_filterset_source() function).

Note: this will not guarantee the linking, matching of capabilities between the two filters will still be evaluated. This can be very helpful in a testing/development scenario where one may need to disable the dynamic linking to solve compatibility issues between two filters.

```C
gf_fs_set_max_resolution_chain_length(session, 0);
```
Running the session and displaying stats

By default, the gpac filters session operates in a semi-blocking state. meaning whenever output PID buffers on a filter are all full, the filter is marked as blocked and not scheduled for processing. And whenever one output PID buffer is not full, the filter unblocks.

The function [gf_fs_run](https://doxygen.gpac.io/group__fs__grp.html#gafdef85e209aef33193e02f83ff5fcbab)() allows for executing the filter session. When the session is non-blocking, it processes tasks of the oldest scheduled filter, manages pending PID connections, and then returns. In the case of a blocking session, gf_fs_run() continues to run until the session concludes or is aborted. The function returns an error if any issues arise during execution, and the last errors can be retrieved using [gf_fs_get_last_connect_error](https://doxygen.gpac.io/group__fs__grp.html#ga026f96a009dd073700b7339fb3ade492) and [gf_fs_get_last_process_error](https://doxygen.gpac.io/group__fs__grp.html#ga2a217d0b7f3f44050f9f78cab10e577d).

  
```C
gf_err = gf_fs_run(session);  

if (gf_err>=GF_OK) {  
    gf_err = gf_fs_get_last_connect_error(session);  
if (gf_err>=GF_OK)  
    gf_err = gf_fs_get_last_process_error(session);  
}  
      
//print connections  
gf_fs_print_connections(session);  
gf_fs_print_stats(session);  
      
gf_fs_del(session);  
session = NULL;  
```
Sample code

In the following example we reproduce a [testsuite example](https://github.com/gpac/testsuite/blob/master/scripts/reframers.sh) that takes a png image as input and calls the reframer filter on the png and writes a new image using writegen and fout filters.

[ (image file png) fin -> ] -> reframe -> writegen -> [ -> fout (image result file) ]

**_NOTE:_**: the reframer filter has no functionnnal use in this particular example. the example is just an illustartion of a filters chain.     

```C
int  main(int argc, char *argv[])  
{
    GF_Err gf_err = GF_OK;  
        
    // session scheme for testing reframer with fin filter  
    GF_FilterSession *session = gf_fs_new_defaults(0u);  
    if (session == NULL) {
        fprintf(stderr, "Failed to create GPAC session\n");
        return EXIT_FAILURE;
    }  
      
    // load source filter
    GF_Filter * src_filter = gf_fs_load_filter(session, "fin:src=logo.png", &gf_err);  
    if (gf_err != GF_OK)  
    {  
        fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
    }
    //load reframer filter  
    GF_Filter *reframer_filter = gf_fs_load_filter(session, "reframer", &gf_err);  
    if (gf_err != GF_OK)  
    {  
        fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
    }
    //load writergen filter    
    GF_Filter *writegen_filter = gf_fs_load_filter(session, "writegen", &gf_err);  
    if (gf_err != GF_OK)  
    {  
        fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
    }
      
    //load destination filter
    GF_Filter *dst_filter = gf_fs_load_filter(session, "fout:dst=logo_result.png", &gf_err);  
    if (gf_err != GF_OK)  
    {  
        fprintf(stderr, "Failed to load filter: %s", gf_error_to_string(gf_err));  
    }  
      
    gf_filter_set_source(reframer_filter, src_filter, NULL);  
    gf_filter_set_source(writegen_filter,reframer_filter,NULL);  
    gf_filter_set_source(dst_filter ,writegen_filter,NULL);  
      
    gf_err = gf_fs_run(session);  
      
    if (gf_err>=GF_OK)
    {  
        gf_err = gf_fs_get_last_connect_error(session);   
        if (gf_err>=GF_OK)
            gf_err = gf_fs_get_last_process_error(session);
    }

    //print connections  
    gf_fs_print_connections(session);  
    gf_fs_print_stats(session);  
      
    gf_fs_del(session);  
    session = NULL;  
    return EXIT_SUCCESS;  
}  
```
Options  {.no-collapse}

<div markdown class="option">  
<a id="tiledrop" data-level="basic">__tiledrop__</a> (uintl, updatable): specify indexes of tiles to drop  
</div>  
<div markdown class="option">  
<a id="ttimeout" data-level="basic">__ttimeout__</a> (uint, default: _10000_, updatable): number of milliseconds to wait until considering a tile packet lost, 0 waits forever  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="reframe">__reframe__</a> (bool, default: _false_): force re-parsing of referenced content  
</div>  
<div markdown class="option">  
<a id="index" data-level="basic">__index__</a> (dbl, default: _1.0_): indexing window length  
</div>
FFmpeg decoder

Register name used to load filter: __ffdec__  
This filter may be automatically loaded during graph resolution.  
  
This filter decodes audio and video streams using FFmpeg.  
See FFmpeg documentation (https://ffmpeg.org/documentation.html) for more details.  
To list all supported decoders for your GPAC build, use `gpac -h ffdec:*`.  
  
Options can be passed from prompt using `--OPT=VAL`  
The default threading mode is to let libavcodec decide how many threads to use. To enforce single thread, use `--threads=1`
Codec Map

The [ffcmap](#ffcmap) option allows specifying FFmpeg codecs for codecs not supported by GPAC.  
Each entry in the list is formatted as `GID@name` or `GID@+name`, with:  

- GID: 4CC or 32 bit identifier of codec ID, as indicated by `gpac -i source inspect:full`  
- name: FFmpeg codec name  
- `+': is set and extra data is set and formatted as an ISOBMFF box, removes box header  

  
Example
```
gpac -i source.mp4 --ffcmap=BKV1@binkvideo vout
```
  
This will map an ISOBMFF track declared with coding type `BKV1` to binkvideo.
Options  {.no-collapse}

<div markdown class="option">  
<a id="ffcmap" data-level="basic">__ffcmap__</a> (strl): codec map  
</div>  
<div markdown class="option">  
<a id="c">__c__</a> (str):     codec name (GPAC or ffmpeg), only used to query possible arguments - updated to ffmpeg codec name after initialization  
</div>  
<div markdown class="option">  
<a id="*" data-level="basic">__*__</a> (str): any possible options defined for AVCodecContext and sub-classes. See `gpac -hx ffdec` and `gpac -hx ffdec:*`  
</div>
FFmpeg multiplexer

Register name used to load filter: __ffmx__  
This filter may be automatically loaded during graph resolution.  
  
Multiplexes files and open output protocols using FFmpeg.  
See FFmpeg documentation (https://ffmpeg.org/documentation.html) for more details.  
To list all supported multiplexers for your GPAC build, use `gpac -h ffmx:*`.This will list both supported output formats and protocols.  
Output protocols are listed with `Description: Output protocol`, and the subclass name identifies the protocol scheme.  
For example, if `ffmx:rtmp` is listed as output protocol, this means `rtmp://` destination URLs are supported.  
  
Some URL formats may not be sufficient to derive the multiplexing format, you must then use [ffmt](#ffmt) to specify the desired format.  
  
Unlike other multiplexing filters in GPAC, this filter is a sink filter and does not produce any PID to be redirected in the graph.  
The filter can however use template names for its output, using the first input PID to resolve the final name.  
The filter watches the property `FileNumber` on incoming packets to create new files.  
  
All PID properties prefixed with `meta:` will be added as metadata.
Options  {.no-collapse}

<div markdown class="option">  
<a id="dst" data-level="basic">__dst__</a> (cstr): location of destination file or remote URL  
</div>  
<div markdown class="option">  
<a id="start" data-level="basic">__start__</a> (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration  
</div>  
<div markdown class="option">  
<a id="speed" data-level="basic">__speed__</a> (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1  
</div>  
<div markdown class="option">  
<a id="ileave">__ileave__</a> (frac, default: _1_): interleave window duration in second, a value of 0 disable interleaving  
</div>  
<div markdown class="option">  
<a id="nodisc">__nodisc__</a> (bool, default: _false_): ignore stream configuration changes while multiplexing, may result in broken streams  
</div>  
<div markdown class="option">  
<a id="mime">__mime__</a> (cstr): set mime type for graph resolution  
</div>  
<div markdown class="option">  
<a id="ffiles">__ffiles__</a> (bool, default: _false_): force complete files to be created for each segment in DASH modes  
</div>  
<div markdown class="option">  
<a id="ffmt">__ffmt__</a> (str): force ffmpeg output format for the given URL  
</div>  
<div markdown class="option">  
<a id="block_size">__block_size__</a> (uint, default: _4096_): block size used to read file when using avio context  
</div>  
<div markdown class="option">  
<a id="keepts">__keepts__</a> (bool, default: _true_): do not shift input timeline back to 0  
</div>  
<div markdown class="option">  
<a id="*" data-level="basic">__*__</a> (str): any possible options defined for AVFormatContext and sub-classes (see `gpac -hx ffmx` and `gpac -hx ffmx:*`)  
</div>
PID selection

The MPEG-2 TS multiplexer assigns M2TS PID for media streams using the PID of the PMT plus the stream index.  
For example, the default config creates the first program with a PMT PID 100, the first stream will have a PID of 101.  
Streams are grouped in programs based on input PID property ServiceID if present. If absent, stream will go in the program with service ID as indicated by [sid](#sid) option.  

- [name](#name) option is overridden by input PID property `ServiceName`.  
- [provider](#provider) option is overridden by input PID property `ServiceProvider`.  
- [pcr_offset](#pcr_offset) option is overridden by input PID property `"tsmux:pcr_offset"`  
- [first_pts](#first_pts) option is overridden by input PID property `"tsmux:force_pts"`  
- [temi](#temi) option is overridden by input PID property `"tsmux:temi"`
Time and External Media Information (TEMI)

The [temi](#temi) option allows specifying a list of URLs or timeline IDs to insert in streams of a program.  
One or more TEMI timeline can be specified per PID.  
The syntax is a comma-separated list of one or more TEMI description.  
Each TEMI description is formatted as ID_OR_URL or #OPT1[#OPT2]#ID_OR_URL. Options are:  

- S`N`: indicate the target service with ID `N`  
- T`N`: set timescale to use (default: PID timescale)  
- D`N`: set delay in ms between two TEMI url descriptors (default 1000)  
- O`N`: set offset (max 64 bits) to add to TEMI timecodes (default 0). If timescale is not specified, offset value is in ms, otherwise in timescale units.  
- I`N`: set initial value (max 64 bits) of TEMI timecodes. If not set, initial value will match first packet CTS. If timescale is not specified, value is in PID timescale units, otherwise in specified timescale units.  
- P`N`: indicate target PID in program. Possible values are  

    - `V`: only insert for video streams.  
    - `A`: only insert for audio streams.  
    - `T`: only insert for text streams.  
    - N: only insert for stream with index `N` (0-based) in the program.  

- L`C`: set 64bit timecode signaling. Possible values for `C` are:  

    - `A`: automatic switch between 32 and 64 bit depending on timecode value (default if not specified).  
    - `Y`: use 64 bit signaling only.  
    - `N`: use 32 bit signaling only and wrap around timecode value.  

- N: insert NTP timestamp in TEMI timeline descriptor  
- ID_OR_URL: If number, indicate the TEMI ID to use for external timeline. Otherwise, give the URL to insert  

    
Example
```
temi="url"
```
  
Inserts a TEMI URL+timecode in the each stream of each program.  
Example
```
temi="#P0#url,#P1#4"
```
  
Inserts a TEMI URL+timecode in the first stream of all programs and an external TEMI with ID 4 in the second stream of all programs.  
Example
```
temi="#P0#2,#P0#url,#P1#4"
```
  
Inserts a TEMI with ID 2 and a TEMI URL+timecode in the first stream of all programs, and an external TEMI with ID 4 in the second stream of all programs.  
Example
```
temi="#S20#4,#S10#URL"
```
  
Inserts an external TEMI with ID 4 in the each stream of program with ServiceID 20 and a TEMI URL in each stream of program with ServiceID 10.  
Example
```
temi="#N#D500#PV#T30000#4"
```
  
Inserts an external TEMI with ID 4 and timescale 30000, NTP injection and carousel of 500 ms in the video stream of all programs.  
  
__Warning: multipliers (k,m,g) are not supported in TEMI options.__
Adaptive Streaming

In DASH and HLS mode:  

- the PCR is always initialized at 0, and [flush_rap](#flush_rap) is automatically set.  
- unless `nb_pack` is specified, 200 TS packets will be used as pack output in DASH mode.  
- `pes_pack=none` is forced since some demultiplexers have issues with non-aligned ADTS PES.  

  
The filter watches the property `FileNumber` on incoming packets to create new files, or new segments in DASH mode.  
The filter will look for property `M2TSRA` set on the input stream.  
The value can either be a 4CC or a string, indicating the MP2G-2 TS Registration tag for unknown media types.
CryptFile output

Register name used to load filter: __cryptout__  
This filter is not checked during graph resolution and needs explicit loading.  
  
This filter dispatch raw blocks from clear input files to encrypted files with AES 128 CBC in PKCS7  
  
The filter is automatically loaded by the DASH/HLS multiplexer and should not be explicitly loaded by your application.  
  
The filter accepts URL with scheme `gcryp://URL`, where `URL` is the URL to encrypt.
Options  {.no-collapse}

<div markdown class="option">  
<a id="exporter">__exporter__</a> (bool, default: _false_): compatibility with old exporter, displays export results  
</div>  
<div markdown class="option">  
<a id="merge_cues">__merge_cues__</a> (bool, default: _true_): merge VTT cues (undo ISOBMFF cue split)  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="bus">__bus__</a> (sint, default: _-1_): PCI bus number. If not set, device discovery is used  
</div>  
<div markdown class="option">  
<a id="slot">__slot__</a> (sint, default: _-1_): PCI bus number. If not set, device discovery is used  
</div>  
<div markdown class="option">  
<a id="fps">__fps__</a> (frac, default: _30/1_): default FPS to use if input stream fps cannot be detected  
</div>  
<div markdown class="option">  
<a id="clip">__clip__</a> (bool, default: _false_): clip YUV data to valid SDI range, slower  
</div>  
<div markdown class="option">  
<a id="port">__port__</a> (uint, default: _1_): set sdi output port of card  
</div>  
<div markdown class="option">  
<a id="start" data-level="basic">__start__</a> (dbl, default: _0.0_): set playback start offset, [-1, 0] means percent of media dur, e.g. -1 == dur  
</div>
M1V/M2V/M4V reframer

Register name used to load filter: __rfmpgvid__  
This filter may be automatically loaded during graph resolution.  
  
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  {.no-collapse}

<div markdown class="option">  
<a id="fps" data-level="basic">__fps__</a> (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz)  
</div>  
<div markdown class="option">  
<a id="index" data-level="basic">__index__</a> (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  
</div>  
<div markdown class="option">  
<a id="vfr">__vfr__</a> (bool, default: _false_): set variable frame rate import  
</div>  
<div markdown class="option">  
<a id="importer">__importer__</a> (bool, default: _false_): compatibility with old importer, displays import results  
</div>  
<div markdown class="option">  
<a id="notime">__notime__</a> (bool, default: _false_): ignore input timestamps, rebuild from 0  
</div>
Options  {.no-collapse}

<div markdown class="option">  
<a id="fps" data-level="basic">__fps__</a> (frac, default: _15000/1000_): import frame rate  
</div>  
<div markdown class="option">  
<a id="index" data-level="basic">__index__</a> (dbl, default: _1.0_): indexing window length  
</div>  
<div markdown class="option">  
<a id="notime">__notime__</a> (bool, default: _false_): ignore input timestamps, rebuild from 0  
</div>
BT/XMT/X3D loader

Register name used to load filter: __btplay__  
This filter may be automatically loaded during graph resolution.  
  
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 [sax_dur=N](#sax_dur=N) is set, the filter will do a progressive load of the source and cancel current loading when processing time is higher than `N`.
Built-in property types

Name | Description    
--- | ---    
sint | signed 32 bit integer    
uint | unsigned 32 bit integer    
lsint | signed 64 bit integer    
luint | unsigned 32 bit integer    
bool | boolean    
frac | 32/32 bit fraction    
lfrac | 64/64 bit fraction    
flt | 32 bit float number    
dbl | 64 bit float number    
v2di | 2D 32-bit integer vector    
v2d | 2D 64-bit float vector    
v3di | 3D 32-bit integer vector    
v4di | 4D 32-bit integer vector    
str | UTF-8 string    
mem | data buffer    
cstr | const UTF-8 string    
cmem | const data buffer    
ptr | 32 or 64 bit pointer    
strl | UTF-8 string list    
uintl | unsigned 32 bit integer list    
sintl | signed 32 bit integer list    
v2il | 2D 32-bit integer vector list    
4cc | Four character code    
4ccl | four-character codes list    
pfmt | raw pixel format    
afmt | raw audio format    
cprm | color primaries, string or int value from ISO/IEC 23091-2    
ctfc | color transfer characteristics, string or int value from ISO/IEC 23091-2    
cmxc | color matrix coefficients, string or int value from ISO/IEC 23091-2    
alay | channel layout configuration, string or int value from ISO/IEC 23091-3