gaspard7/wiki_gpac huggingface dataset:
Filtering input streams {: data-level="beginner" }

Assume you have an input file with several tracks/media streams, such as two videos in AVC and HEVC, and audios in english and french, and you only want to import AVC and english audio from that source file.

With regular MP4Box usage, you would need to know the track IDs of the desired tracks. If you have a collection of such files with varying track IDs, you would need complex dumping and analyzing of the file tracks to extract their track IDs and import them.
```
#get number of tracks
nbt=`MP4Box -tracks source.mp4`
#for each track
MP4Box -infon i source.mp4
#grep AVC / eng / ... and decide if you want this track
```

Thanks to the filter design and [link syntax](filters_general#complex-links), you have a much simpler way to do this:
 
```
MP4Box -add source.mp4:dopt:SID=#CodecID=avc,#Language=eng -new dest.mp4
```

This will assign option `SID=....` to the destination filter (the file multiplexer). The SID syntax in this example will instruct the filter session to only connect PIDs with property `CodecID=avc` or with property `Language=eng` to the destination multiplexer. 

You can use any [property](filters_properties) defined in GPAC, and even check for multiple properties:

```
MP4Box -add source.mp4:dopt:SID=#CodecID=avc,#Language=eng#CodecID=aac -new dest.mp4
```
Inserting a filter chain

__WARNING__
MP4Box 1.0 used the syntax `@@` to identify filter chains. The syntax is still supported in later versions, but does not allow for complex paths in the filter chain. It is recommended to use the new syntax, as illustrated in this howto.


It is possible to provide a filter chain to a source being imported in MP4Box.
```
MP4Box -add source.264:@reframer:saps=1 -new file.mp4
```

The above command will invoke the [reframer](reframer) filter with the [saps](reframer#saps) option. The filter will be inserted between the source and the destination. 

You can also play with [encoding](encoding):
 
```
MP4Box -add source.264:@enc:c=avc:fintra=2 -new file.mp4
```

The above command will invoke an encoding filter chain in AVC|H264 format with a forced intra period of 2 seconds. The filter will be inserted between the source and the destination. 
 
If your source is YUV (or PCM), you will have to insert source parameters using the `sopt`option:
```
MP4Box -add source.yuv:sopt:size=320x240:fps=30000/1001:@enc:c=avc:fintra=2 -new file.mp4
```

The above command will load the source file as a YUV 420 8 bits 320x240 @ 29.97 Hz.


 
You may also specify several paths for the filter chain:
```
MP4Box -add source.mp4:@ffsws:osize=160x120@enc:c=avc:fintra=2:b=100k@@ffsws:osize=320x240@enc:c=avc:fintra=2:b=200k -new file.mp4
```

The above command will the source and:

- rescale it to 160x120 and encode it at 100 kbps
- rescale it to 320x240 and encode it at 200 kbps


__Discussion__   
You may ask yourself whether using MP4Box or gpac is more efficient for such an operation:

-  When you add a single track using MP4Box to a new file, gpac and MP4Box are strictly equivalent. 
- If you add several tracks in one shot in a new file, gpac will be more efficient as a single filter session will be used to import all tracks, whereas MP4Box uses one filter session per `-add` operation (unless [-newfs](mp4box-gen-opts#newfs) is set).
- The filter architecture does not support (for the moment) reading and writing in the same file, so if you need to add a track to an existing file, you must use MP4Box for that.
DASHing {: data-level="beginner" }

It is possible to provide a filter chain to each source being DASHed with MP4Box.
```
MP4Box -dash 1000 -profile live -out session.mpd source.mp4:@reframer:saps=1 source.mp4
```

The above command will invoke a reframer filter forwarding only IDR and discarding other frames, allowing to create a trick mode representation and a regular representation.

 
```
MP4Box -dash 2000 -profile live -out session.mpd source.mp4:@enc:c=avc:fintra=2
```

The above command will invoke an encoding filter chain in AVC|H264 format with a forced intra period of 2 seconds.

```
MP4Box -dash 2000 -profile live -out session.mpd source.mp4:@enc:c=avc:fintra=2:@cecrypt:cfile=drm.xml
```

The above command will invoke an encoding filter chain in AVC|H264 format with a forced intra period of 2 seconds, followed by an encryption driven by the file `drm.xml`.


```
MP4Box -dash 2000 -profile live -out session.mpd source.mp4:@enc:c=avc:fintra=2:b=1M:#Representation=1@@enc:c=avc:fintra=2:b=2M:#Representation=2
```

The above command will invoke two encoding filter chains in AVC|H264 format with a forced intra period of 2 seconds, and bitrates of 1 mbps and 2 mbps. Note that we need to assign the representation IDs in this case, as MP4Box dashing consider by default all streams from a given source as part of the same representation.


__Discussion__   
The filter chain will be run at each invocation of MP4Box. Therefore it is not recommended to use complex chains (e.g. encoding or encrypting) and [-dash-ctx](mp4box-dash-opts#dash-ctx) or [-dash-live](mp4box-dash-opts#dash-live) together, as the content would be processed (encoded, encrypted) multiple times, at least up to the current DASH time. 

You may ask yourself whether using MP4Box or gpac is more efficient for such an operation. If  you don't use `-add` options, MP4Box and gpac are strictly equivalent, a single filter session is used by both to dash the content.

Note: sources to MP4Box for dashing are no longer restricted to MP4 files. The dasher filter will enforce MP4 output but processes any source:

```
MP4Box -dash 2000 -profile live -out session.mpd source.264 source.aac
```

The above command will invoke create a DASH session from non packaged AVC|H264 and AAC sources, using ISOBMFF as output format.

```
MP4Box -dash 2000 -profile live -out session.mpd:m2ts source.264 source.aac
```

The above command will invoke create a DASH session from non packaged AVC|H264 and AAC sources, using MPEG-2 TS as output format.
Overview {:data-level="all"}

The GPAC log system is based on two orthogonal concepts:

*   **tools**: the category of the log you want to listen to. For instance when playing a MPEG-TS file, you may want to hear about the container log; when player remote content, you may want to hear about the network log; when trying to find a deadlock (but there are obviously none in GPAC ;), you may want to hear about the mutex log. The complete list is provided [here](core_logs).

*   **levels**: the deepness of the log. You have to choose whether you want to know about errors only, or about any thing the developer thought right to signal for fellow developers.

> **/!\\ In GPAC, you can choose which tools you want to hear, and for each tool you can set a level.**

The general syntax is:

```
-logs log_args: sets log tools and levels, formatted as a ':'-separated list of toolX[:toolZ]@levelX
```

Concrete examples are given further in this article.
Example of available Tools

- GF_LOG_CORE      (core)     : log message from the core library (init, threads, network calls, etc)
- GF_LOG_FILTERS    (filters) : log message from the filter session
- GF_LOG_CONTAINER (container): log message from a bitstream parser (IsoMedia, MPEG-2 TS, OGG, ...)
- GF_LOG_NETWORK   (network)  : log message from the network/service stack (messages & co)
- GF_LOG_RTP       (rtp)      : log message from the RTP/RTCP stack (TS info) and packet structure & hinting (debug)
- GF_LOG_AUTHOR    (author)   : log message from authoring subsystem (file manipulation, import/export)
- GF_LOG_CODEC     (codec)    : log message from a codec
- GF_LOG_PARSER    (parser)   : log message from any XML parser (context loading, etc)
- GF_LOG_COMPOSE   (compose)  : log message from compositor related to object drawing
- GF_LOG_MEDIA     (media)    : log message from the compositor related to media object playback
- GF_LOG_AUDIO     (audio)    : log message related to audio playback compositor
- GF_LOG_SCENE     (scene)    : log message from the scene graph/scene_manager (nodes and attribute modification, events)
- GF_LOG_MMIO      (mmio)     : log message from multimedia I/O devices (audio/video input/output, ...)
- GF_LOG_SCRIPT    (script)   : log message from the scripting engine bindings execution (not from scripts)
- GF_LOG_CONSOLE   (console)  : log for all messages coming from script alert() and print()
- GF_LOG_APP       (app)      : log message for apps (MP4Box, gpac)
- GF_LOG_ALL       (all)      : all available logs
Available Levels

- GF_LOG_QUIET   (quiet)  : disable all Log message
- GF_LOG_ERROR   (error)  : log message describes an error
- GF_LOG_WARNING (warning): log message describes a warning
- GF_LOG_INFO    (info)   : log message is informational (state, etc..)
- GF_LOG_DEBUG   (debug)  : log message is a debug info


**/!\\ Note** that these levels apply to GPAC, not to the content being processed. For instance `GF_LOG_ERROR` is intended to signal GPAC has encountered a serious error. On the contrary, if you read an MPEG-TS files containing some errors that are correctly handled by GPAC, you should use the `GF_LOG_WARNING` channel.
Setting tools and levels in GPAC

Here is a screenshot of gpac playback executed with default logs:

![](https://gpac.io/files/2011/08/capture_log1.png)

In this example GPAC says a PID from the MPEG2-TS stream is not supported (and therefore won't be decoded).

GPAC apps features several options related to logging:

```
-logs=log_args: sets log tools and levels, formatted as a ':'-separated list of toolX[:toolZ]@levelX
```

Here is an example, which sets all messages to the `warning` level (default level for all tools) except `core`, `audio` and `mem` that are set to the `debug` level, and `container` and `sync` that are set to the `error` level:

```
-logs=core:audio:mem@debug:container:sync@error
```

Other log options are:

* `-strict-error`:  exit when the player reports its first error
* `-log-file=file`: sets output log file. Also works with -lf
Choosing an output for logs

By default GPAC outputs its logs to stdout. However as you can see in the latest example from the previous section, GPAC applications feature a `-log-file` option:


* `-log-file=file`: sets output log file. Also works with `-lf`

This behavior is implemented by default in all applications in GPAC (MP4Box, gpac) and by any application forwarding their arguments to libgpac.
Calling the log

When you need to print a log message, call the `GF_LOG` macro as follows:

```c
GF_LOG(GF_LOG_LEVEL, GF_LOG_TOOL, (MESSAGE));
```

Where:

*   `GF_LOG_LEVEL` belongs to the level list above (`GF_LOG_QUIET`, ..., `GF_LOG_DEBUG`)
*   `GF_LOG_TOOL` belongs to the tool list above (`GF_LOG_CORE`, ..., `GF_LOG_CONSOLE`)
*   `(MESSAGE)`: a message contained between parentheses and with the same formatting as `printf`.

For example:

```c
GF_LOG(GF_LOG_INFO, GF_LOG_CONSOLE, ("%s %s\n", servName, evt->message.message));
```
Extracting raw video from a file

```gpac -i source.mp4 -o test.yuv```

The above command will dump the video content from `source.mp4` into a YUV420 8-bits `test.yuv`.   
If the source contains other tracks such as audio or text, they will be ignored as [described here](filters_general#general).  

__Discussion__  
In GPAC, file extension are used to infer the type of data being produced. Note that unless data probing is disabled, this is not the case for input files. 
For most supported media types, this association is given by the [writegen](writegen) filter, in charge of forwarding media streams of type `audio`, `video`, ... into data streams of type `file`. For more information on codec <-> file extension associations, check the writegen filter capabilities using `gpac -hh writegen`.

For raw formats, the writegen filter performs a PID capability negotiation to enforce a pixel format (or an audio format) to match the type indicated by the file extension. 
- The association between pixel format and file extension is [given here](filters_properties#pixel-formats).    
- The association between audio format and file extension is [given here](filters_properties#audio-formats).    


You can enforce the format even when using a different extension. 

```gpac -i source.mp4 -o test.foo:ext=yuv```


You are obviously not limited to physical file output, this works as well with pipes and sockets:

```
gpac -i source.mp4 -o pipe://mypipe:ext=yuv
gpac -i source.mp4 -o tcp://127.0.0.1:1234/:ext=yuv
gpac -i source.mp4 -o udp://127.0.0.1:1234/:ext=yuv
```

Note that in case of pipes or socket, the `ext` option shall be set to the desired format to solve the chain. See [pipes](pipes) and [sockets](sockets).
Extracting and resizing raw video from a file

```gpac -i source.mp4 ffsws:osize=128x128 -o test.yuv```

The above command will dump the video content from `source.mp4` into a YUV420 8-bits resized to 128x128 pixels `test.yuv`.   

__Discussion__  
Prior to GPAC 2.0, the following command had to be used:

```gpac -i source.mp4 ffsws:osize=128x128 @ -o test.yuv```

The link directive `@` is used to prevent the decoded YUV/RGB data PID to link against the `test.yuv` destination, by enforcing the destination to only accept PIDs coming from `ffsws`, as described in the [general documentation](filters_general#filter-linking-link). GPAC 2.0 and above simplified command line processing to avoid link directives in most cases.


The simplest way to resize a video in GPAC at the current time is to use the FFmpeg-based [rescaler](ffsws).

The [writegen](writegen) filter used in the extraction process can be used to specify an extraction range using its [start](writegen#start) and [dur](writegen#dur) options:

```gpac -i source.mp4 ffsws:osize=128x128 -o test.yuv:start=10:dur=5```

This will resize and extract the video from start time 10s until end range 15s.
Extracting Frames from a file

```gpac -i source.mp4 -o dump_$num$.yuv```

The above command will dump each video frame  from `source.mp4` into a YUV420 8-bits  `test_N.yuv`, with `N` the frame number.

You can also simply extract to compressed formats by changing destination type (here dump to PNG):
```gpac -i source.mp4 -o dump_$num$.png```

Resizing images while extracting is similar as previously:

```gpac -i source.mp4 ffsws:osize=128x128 -o dump_$num$.png```

The [writegen](writegen) filter used in the extraction process can be used to specify an extraction range using its [start](writegen#start) and [dur](writegen#dur) options:

```gpac -i source.mp4 ffsws:osize=128x128 -o dump_$num$.png:start=10:dur=5```

This will resize and extract the video frames from start time 10s until end range 15s.
Extraction with processing of raw data

```
gpac -i source.mp4 resample:sr=44100:ch=2 ffsws:osize=128x128 -o test.pcm -o test.yuv
#or with link directives
gpac -i source.mp4 resample:sr=44100:ch=2 ffsws:osize=128x128 -o test.pcm -o test.yuv
```

The above command lines will do a one pass raw extraction of audio and video content from `source.mp4`, performing audio resampling to 44100 Hz stereo and video resizing to 128x128 pixels.
Overview {: data-level="all" }

We discuss here how to use the [flist](flist) filter to deal with playlists in GPAC.  

The filter is designed to concatenate media streams coming from a sequence of sources into a continuous timeline.
It can operate in file list mode or as a processor for playlists files with extension `txt` or `m3u`.

In both modes, when switching sources, the filter will match streams (PIDs) based on their stream type values. If no PID exists, a new output PID is created. If the new source has less PIDs than the previous source, the extra PIDs are kept but marked as being in end of stream state.

The filter will move to the next item once all PIDs are done playing. It will then adjust the timeline of the following source by repositioning the new source smallest initial timestamp to the greatest time (timestamp+duration) of the last source.
File list mode {: data-level="beginner" }

```
gpac flist:srcs=file.mp4:floop=-1 vout
```

The above command will play  `file.mp4`, looping it forever. The source may have any number of streams

```
gpac flist:srcs=f1.mp4,f2.mp4 vout
```

The above command will play  `f1.mp4` then `f2.mp4`. 

```
gpac flist:srcs=images/*.png:fdur=1/25 vout
```

The above command will play all files with extension `png` in directory `images`, each image lasting for 40 milliseconds.

```
gpac flist:srcs=images/*.png:fdur=1:fsort=date -o slide.mp4
```

The above command will gather all files with extension `png` in directory `images` ordered by their file creation date, each image lasting for 1 second, and output as a PNG track in MP4 format.
General usage

The playlist mode allows you to build complex source sequences. Think of it as piping the output of several sequential `gpac` executions into a consuming `gpac` instance.

 
```
##begin pl.m3u
s1.mp4
s2.mp4
s3.mp4
s4.mp4
##end playlist

gpac -i pl.m3u -o dash/live.mpd
```

The above command will play sources in sequence and feed them to the [dasher](dasher) for DASH/HLS generation.

Each source specified is a regular GPAC source, and can be a local file, a remote http(s) resource, a broadcast session, a DASH session, a source generator filter, another `flist` instance, etc ...

If the sources are ISOBMFF fragments, concatenation will be done automatically at the input side (in terms of internal filters logic, we issue a source switch event rather than loading a new source).

The syntax is the same as the one used by `gpac`.
```
##begin mixed.m3u
http://somehost/vod.mpd
localfile.mp4
##end playlist
```

Playlist can specify options applying to the source(s) listed in the next line.
- Options are listed on a single line starting with `#`.
- A line starting with `##` is ignored.
- Each line in the playlist not starting with `#` is a source entry for the playlist. 

```
##begin mixed.m3u
#repeat=1
file.aac
file.mp3
##end playlist
```

This will play twice `file.aac` then once `file.mp3`.
Multi-sources entries

A source entry may contain more than one source, for example if you want to open in parallel audio, video and subtitles:

```
##begin mixed.m3u
vid.mp4 && audio.mp4 && audio_fr.mp4 && subs.mp4
vid2.mp4 && audio2.mp4 && audio2_fr.mp4 && subs2.mp4
##end playlist
```

In this case, the filter will move to the next item in the playlist only once all PIDs from all sources are done playing.

A source entry may also contain filter directives, just like `gpac` command line. These can be used to apply processing only for the current sources, such as transcoding if you know the source is not in the right format:

```
##begin mixed.m3u
file.aac
file.mp3 @ enc:c=aac:b=64k
file2.aac
##end playlist
```

This will only activate the AAC encoder for the `file.mp3` source. When `file2.aac` is queued for processing, the transcoding chain used for `file.mp3` will be unloaded. 

The following describes a sequence of sources to be used as input to a DASH multi-period session:  
```

##begin mixed.m3u
vid1.mp4:#Period=1

#props=#Period=2
vid2.mp4 && audio2.mp4:#Language=en && audio2_fr.mp4:#Language=fr

vid3.mp4:#Period=1
##end playlist
```

This will result in a DASH MPD with three periods, the first (resp. third) period containing media from `vid1.mp4` (resp. `vid3.mp4`) and the second period containing media from `vid2.mp4`, `audio2.mp4` and `audio2_fr.mp4`.
 
Note that in this example:

- audio sources override their language definitions
- we use the `props` option for the second source entry to signal the DASH period ID of each source globally, rather than copying it for each source. 

__Warning The set of separators is the default one of gpac (cf [-seps](gpac_general#seps) ), and cannot be modified__


The playlist mode can also be used to generate DASH/HLS segmentation cues, instructing the dasher to generate segments matching the boundaries of the source files. This can be useful when your encoder performs some optimized scene cut and generates segments with variable duration.
 
```

##begin playlist.m3u
v1.264 && a1.aac
v2.264 && a2.aac
v3.264 && a3.aac
##end playlist

gpac -i playlist.m3u:sigcues -o dash.mpd
```

The DASH session will in that case only have 3 segments containing v1/a1,  v2/a2 and v3/a3 (obviously, make sure vX and aX have the same duration ...).
Live playlists

The playlist can be reloaded at run time, waiting for new sources to be pushed. You need to specify the [ka](flist#ka) option to keep the playlist alive, or specify `ka` directive in the playlist. Until an `end` directive is seen, the filter session will be kept alive even when no new source is available.

  
`gpac -i pl.m3u:ka -o dash/live.mpd:dmode=dynamic`

Then after some time generate a new playlist:
```
##begin pl.m3u
s3.mp4
s4.mp4
s5.mp4
s6.mp4
##end playlist
```

The filter will look for its last active source in the new playlist and load the following sources at the end of the current source. If the last active source is not found, the filter will restart from the beginning of the playlist.

Finally use a terminating playlist:
```
##begin pl.m3u
s6.mp4
s7.mp4
s8.mp4
#end
##end playlist
```

You can use a playlist with only a single line containing the next file to play, but you must however ensure that you produce this playlist only once the incoming file is written to disk.

You can also instruct the filter to delete each source once processed, either for the entire playlist using [fdel](flist#fdel), or per source using `del` option:

```
##begin pl.m3u
#del
s1.mp4
#del
s2.mp4
s3.mp4
s4.mp4
##end playlist
```

In this example, only `s1.mp4` and `s2.mp4` will be deleted.
Splicing playlists

The filter can be used to splice content, i.e. replace part of the content with some other content for a given time. This is typically used for ad insertion cases, but other use cases are possible as well.

**WARNING**
Splicing is a tricky topic, as the source and replacement content will likely have different characteristics such as coding format,  initial synchronization or misaligned duration. See discussion below
 
The filter does **NOT** operate on the media content payload and cannot perform operations such as cross-fade or other. If you wish to do this with GPAC, you will need to write your own filter (see [2D](evg) and [3D](webgl) examples).
Static playlists

In this example, we will replace the content from `main` source in the range [4, 10] with the content from `ad1` . We need to indicate:

- an `out` cue: the point in the `main` timeline when the content replacement must begin
- an `in` cue: the point in the `main` timeline when the content replacement must end and the main content must resume.


```
##begin pl.m3u
#out=4 in=10
main
ad1
##end playlist
```


The filter is designed to split content at SAP (random access) boundaries, automatically resuming the main content on the next SAP at or after the `in` point. The replacement content is then removed, and the main content timeline restored without any re-alignment.

The replacement content can use playlist directives as usual. A typical usage is when the final splice duration is not known precisely and you want a fallback (here `filler`) for the rest of the splicing period:

```
##begin pl.m3u
#out=4 in=10
main
ad1
#repeat=-1
filler
##end playlist
```

In this example, if `ad1` is 6s, `filler` is 1s but the actual splice period is [4, 12.5], the `filler` will be played in loop for 2.5s. 

Once the splicing source (`main`) is over, the playlists continues after the last loaded URL.