diff --git a/.gitignore b/.gitignore index 8f997d18..ecb5b0f8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,8 @@ .ignore/ site/ .venv/ +venv/ __pycache__/ site.* .DS_Store +node_modules/ diff --git a/content-tagging-system.md b/content-tagging-system.md new file mode 100644 index 00000000..b0f02eb0 --- /dev/null +++ b/content-tagging-system.md @@ -0,0 +1,137 @@ + + +# GPAC Wiki Content Tagging and Level Switch System + +## Overview + +The GPAC wiki implements a content tagging and level switch system to provide a customized reading experience for users with different levels of expertise. This system allows users to toggle between "Beginner" and "Expert" modes, affecting the visibility of content sections and keywords displayed. + +## Purpose + +The main goals of this system are: +1. To help users new to GPAC access simpler, more approachable content. +2. To provide more in-depth, technical content for experienced users. +3. To create a dynamic reading experience that adapts to the user's knowledge level. + +## Implementation + +### Content Tagging + + +Content tagging is implemented in Markdown files using the `attr_list` extension. Tags are applied to H1 headers (single `#` in Markdown) using the following syntax: + +```markdown +# Section Title {: data-level="beginner" } +``` + +Available levels: +- `beginner`: Content suitable for newcomers to GPAC. +- If not specified: More advanced content (considered as expert level). + +### Level Switch + +The level switch is a toggle located in the "Settings" menu in the header of the user interface. It allows users to switch between "Beginner" and "Expert" modes. + +Default setting: The default level is set to "Expert", displaying all documentation. + +User preference storage: The selected level is stored in the browser's local storage, persisting between sessions. + + +## Functionality + +### Content Visibility + +When switching between levels: + +. Expert mode: + - All sections are visible (in Howtos). + - The full Table of Contents (TOC) is displayed, including all sections and subsections. + - For filter options: all options are dispalyed. + +2. Beginner mode: + - Only sections tagged as "beginner" are visible (in Howtos). + - Sections not explicitly tagged as "beginner" disappear(in Howtos). + - For filter options: options with the attribute `id="vsize" data-level="basic"` will be visible in beginner mode. + + +Example: + +![Beginner](docs/images/ex_beginner.png) + +Beginner mode: Only sections tagged as "beginner" are visible. + +![Expert](docs/images/ex_expert.png) + +Expert mode: All sections are visible. + +### Keywords Cloud + +The keywords cloud is dynamic and changes based on the selected level: + +- In Expert mode: All keywords are displayed. +- In Beginner mode: Only keywords tagged as "beginner" or "all" are shown. + +Keywords are defined in the `data/keywords.json` file with the following structure: + +```json +{ + "KEYWORD": { + "description": "Keyword description", + "level": "beginner" + } +} +``` + +When a user clicks on a keyword, a modal appears with the keyword's definition. + +## Implementation Details + +### Key Files + +- `javascripts/levels.js`: Main logic for level switching and content filtering. +- `javascripts/domManipulation.js`: Handles DOM manipulation for showing/hiding content. + +### Howtos Section + +The level switching functionality is currently implemented only in the "Howtos" section of the documentation. + + +## Developer Guidelines + +1. Tagging new content: + - Always tag H1 headers in Markdown files. + - Use the format: `# Title {: data-level="level" }` where `level` is "beginner". + + - Untagged sections are considered "expert" by default. + +2. Adding new keywords: + - Add new keywords to the `data/keywords.json` file. + - Include a description and appropriate level tag. + +3. Testing: + - Test new content in both Beginner and Expert modes to ensure proper visibility. + - Verify that the TOC updates correctly when switching levels. + - Check that the keywords cloud updates appropriately. + +## Best Practices for Content Formatting + +When adding or editing content in the GPAC wiki, it's crucial to follow certain formatting practices to ensure readability and proper rendering of the documentation. One key aspect to pay attention to is the spacing between code blocks and other elements. + +### Spacing Between Code Blocks + +Always add a blank line between code blocks and surrounding text. This practice prevents rendering issues and improves readability. + +#### Good Practice: + +Example: + +![Code block formatting issue](docs/images/good_format.png) + +#### Bad Practice: + +Avoid this: +Example: + +![Code block formatting issue](docs/images/bad_format.png) + + diff --git a/docs/Build/Basic-Player-Application-using-GPAC.md b/docs/Build/Basic-Player-Application-using-GPAC.md index bc1a5bb0..fdbfe199 100644 --- a/docs/Build/Basic-Player-Application-using-GPAC.md +++ b/docs/Build/Basic-Player-Application-using-GPAC.md @@ -1,3 +1,21 @@ +--- +tags: +- scene +- source +- input +- media +- data +- stream +- raw +- output +- frame +- compositor +- sink +- dump +--- + + + ## Objective This example shows a basic GPAC player application. It takes an URL as input and outputs it in a terminal. diff --git a/docs/Build/Build-Introduction.md b/docs/Build/Build-Introduction.md index 2bcd1cc5..8ad5448b 100644 --- a/docs/Build/Build-Introduction.md +++ b/docs/Build/Build-Introduction.md @@ -1,3 +1,10 @@ +--- +tags: +- option +--- + + + This section describes how to build GPAC from scratch and how to develop with it. You can get pre-compiled binaries on [the GPAC website](https://gpac.io/downloads/gpac-nightly-builds/). diff --git a/docs/Build/GPAC-build-MP4Box-only-all-platforms.md b/docs/Build/GPAC-build-MP4Box-only-all-platforms.md index 0a5f6603..7a75f4e4 100644 --- a/docs/Build/GPAC-build-MP4Box-only-all-platforms.md +++ b/docs/Build/GPAC-build-MP4Box-only-all-platforms.md @@ -1,5 +1,13 @@ +--- +tags: +- option +- data +--- -## Build MP4Box with Visual Studio + + + +# Build MP4Box with Visual Studio {: data-level="all"} We published a minimal solution to build MP4Box.exe only, with zero dependency. No DLL to distribute. @@ -7,7 +15,7 @@ You need Visual Studio 2010 or more recent (a pop-up will ask you to upgrade you That's all! -## Build MP4Box with Make +# Build MP4Box with Make On your system, you need the following tools installed on your system: @@ -103,7 +111,7 @@ make -j4 You can find more examples in [our TravisCI script](https://github.com/gpac/gpac/blob/master/.travis.yml). -## Next Step +# Next Step We have started [a multimedia component-level build system called Zenbuild](https://github.com/gpac/zenbuild). Zenbuild builds FFmpeg/libav, VLC or GPAC with most of their features enabled (librtmp, jack, openHEVC, etc.). You can start using Zenbuild, it is fully operational! diff --git a/docs/Build/MP4-dmx-examples.md b/docs/Build/MP4-dmx-examples.md index 9447fde8..5a13712b 100644 --- a/docs/Build/MP4-dmx-examples.md +++ b/docs/Build/MP4-dmx-examples.md @@ -1,3 +1,26 @@ +--- +tags: +- mp4 +- source +- sample +- block +- input +- media +- isomedia +- segment +- isobmff +- data +- stream +- frame +- buffer +- box +- rebuffer +- dash +- chunk +--- + + + We have added to GPAC some sample applications demonstrating how to use GPAC to demux MP4 files. They are not full applications, just examples taking some MP4 files as input and displaying some information about the media samples contained in the file. diff --git a/docs/Build/Upgrading.md b/docs/Build/Upgrading.md index 9916708c..b4d0c5c1 100644 --- a/docs/Build/Upgrading.md +++ b/docs/Build/Upgrading.md @@ -1,4 +1,13 @@ -# In source tree building +--- +tags: +- input +- data +- source +--- + + + +# In source tree building {: data-level="all" } If you build GPAC directly in the source tree (i.e., running `./configure && make` in the same directory as the configure script), the following steps must be done when upgrading your code base to a new version of GPAC, or when switching branches: - uninstall any previous version of GPAC (optional, the build system as of 1.0 is independent from the presence of any other version of libgpac headers on the system) diff --git a/docs/Build/build/GPAC-Build-Guide-for-Android.md b/docs/Build/build/GPAC-Build-Guide-for-Android.md index 0da9dd95..861d4c5b 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-Android.md +++ b/docs/Build/build/GPAC-Build-Guide-for-Android.md @@ -1,12 +1,24 @@ -The Android build is a bit complicated. The method described here is the one used for the official Android builds. It is fairly rigid, with some hard-coded paths and versions. It should not be too hard to adapt it to one's own set up, but there is no guarantee that it will work as is on (for example) more recent versions of the ndk/sdk. +--- +tags: +- input +- data +- source +- link +--- -It was tested on Ubuntu 14 to 18. -The process has three main steps: set up the build environment, cross-compile the dependencies, build the GPAC apk. -In the following, we'll call the main working directory ``. +!!! note + The Android build is a bit complicated. The method described here is the one used for the official Android builds. It is fairly rigid, with some hard-coded paths and versions. It should not be too hard to adapt it to one's own setup, but there is no guarantee that it will work as is on (for example) more recent versions of the ndk/sdk. -# Set up the build toolchain + It was tested on Ubuntu 14 to 18. + + The process has three main steps: set up the build environment, cross-compile the dependencies, build the GPAC apk. + + In the following, we'll call the main working directory ``. + + +# Set up the build toolchain {: data-level="all"} ## JVM and tools diff --git a/docs/Build/build/GPAC-Build-Guide-for-Linux.md b/docs/Build/build/GPAC-Build-Guide-for-Linux.md index a1f03c91..356af222 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-Linux.md +++ b/docs/Build/build/GPAC-Build-Guide-for-Linux.md @@ -1,4 +1,15 @@ -_Preliminary notes: the following instructions will be based on Ubuntu and Debian. It should be easily applicable to other distributions, the only changes should be name of the packages to be installed, and the package manager used._ +--- +tags: +- option +- data +- binary +--- + + + +!!! note + Preliminary notes: the following instructions will be based on Ubuntu and Debian. It should be easily applicable to other distributions, the only changes should be the name of the packages to be installed, and the package manager used. + GPAC is a modular piece of software which depends on third-party libraries. During the build process it will try to detect and leverage the installed third-party libraries on your system. Here are the instructions to: @@ -6,7 +17,7 @@ GPAC is a modular piece of software which depends on third-party libraries. Duri * build a minimal 'MP4Box' and 'gpac' (only contains GPAC core features like muxing and streaming), * build a complete GPAC by rebuilding all the dependencies manually. -# General case for all builds +# General case for all builds {: data-level="all" } ## Development tools @@ -185,6 +196,7 @@ If you already have a gpac version installed, or if you have already built gpac /gpac_public$ make uninstall /gpac_public$ make distclean ``` + **before** running `./configure`. ### Install for developers diff --git a/docs/Build/build/GPAC-Build-Guide-for-MSYS-MinGW.md b/docs/Build/build/GPAC-Build-Guide-for-MSYS-MinGW.md index 33a88ee6..1321da1f 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-MSYS-MinGW.md +++ b/docs/Build/build/GPAC-Build-Guide-for-MSYS-MinGW.md @@ -1,6 +1,15 @@ -The following is the guide to build GPAC on Windows using MSYS2 and the MinGW gcc toolchain. It is a bit clunky and will probably only work on x64 and without cross-compilation. +--- +tags: +- input +- data +- source +--- -# Setting up + + +_The following is the guide to build GPAC on Windows using MSYS2 and the MinGW gcc toolchain. It is a bit clunky and will probably only work on x64 and without cross-compilation._ + +# Setting up {: data-level="all"} ## MSYS diff --git a/docs/Build/build/GPAC-Build-Guide-for-OSX.md b/docs/Build/build/GPAC-Build-Guide-for-OSX.md index 557e2822..a58aa8f2 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-OSX.md +++ b/docs/Build/build/GPAC-Build-Guide-for-OSX.md @@ -1,7 +1,16 @@ -Since the OSX build is essentially the same as the Linux build, this doc will be succinct. Please refer to the [Linux build guide](GPAC-Build-Guide-for-Linux) for further details. +--- +tags: +- data +- encode +- encoder +--- -# MP4Box only + +_Since the OSX build is essentially the same as the Linux build, this doc will be succinct. Please refer to the [Linux build guide](GPAC-Build-Guide-for-Linux) for further details._ + + +# MP4Box only {: data-level="all"} Same as Linux: diff --git a/docs/Build/build/GPAC-Build-Guide-for-WASM.md b/docs/Build/build/GPAC-Build-Guide-for-WASM.md index 00975559..58ce3754 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-WASM.md +++ b/docs/Build/build/GPAC-Build-Guide-for-WASM.md @@ -1,10 +1,23 @@ +--- +tags: +- option +- source +- heif +- data +- frame +--- + + + [**HOME**](Home) » [**Build**](Build-Introduction) » WASM -This page describes how to build GPAC for WASM/Emscripten. +_This page describes how to build GPAC for WASM/Emscripten._ + +!!! note + You can check a live demo at [https://wasm.gpac.io](https://wasm.gpac.io). -A live demo can be seen at [https://wasm.gpac.io](https://wasm.gpac.io) -# (Recommended) Use Docker +# (Recommended) Use Docker {: data-level="all"} The easiest way to build GPAC for WASM is to use the provided Dockerfile at `build/docker/wasm.Dockerfile` in the GPAC repository. diff --git a/docs/Build/build/GPAC-Build-Guide-for-Windows.md b/docs/Build/build/GPAC-Build-Guide-for-Windows.md index 27a88ac6..b1d19c18 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-Windows.md +++ b/docs/Build/build/GPAC-Build-Guide-for-Windows.md @@ -1,13 +1,27 @@ -To build on Windows, you'll need: - * [Git](https://git-scm.com/download/win) - * [Visual Studio](https://visualstudio.microsoft.com/vs/community/) (at least VS2015 is recommended) +--- +tags: +- source +- input +- binary +- data +- property +--- - For a full build, other tools might be required, they will be mentioned at the time. -# NOTE FOR Windows XP Users + +!!! note + To build on Windows, you'll need: + * [Git](https://git-scm.com/download/win) + * [Visual Studio](https://visualstudio.microsoft.com/vs/community/) (at least VS2015 is recommended) + + For a full build, other tools might be required, they will be mentioned at the time. + + +# NOTE FOR Windows XP Users {: data-level="all" } + Windows XP is no longer supported (by GPAC nor Microsoft) in our regular build system. See [this discussion](https://github.com/gpac/gpac/issues/1490#issuecomment-649519836) for further details. - # Build MP4Box only +# Build MP4Box only To build only the MP4Box command line utility, you will need to: @@ -31,7 +45,8 @@ It might be called something else depending on your version of Visual Studio. Th You can adjust the parameters: - `/p:Platform=x64`: Change to `/p:Platform=Win32` to get a 32 bits build - - `/p:PlatformToolset=v140` and `/p:WindowsTargetPlatformVersion=8.1`: Change this depending on your Visual Studio version and the Windows SDK version you have installed. (e.g.: `/p:PlatformToolset=v143 /p:WindowsTargetPlatformVersion=10.0` for VS 2022 on Windows 10) + - `/p:PlatformToolset=v140` and `/p:WindowsTargetPlatformVersion=8.1`: Change this depending on your Visual Studio version and the Windows SDK version you have installed. + - (e.g.: `/p:PlatformToolset=v143 /p:WindowsTargetPlatformVersion=10.0` for VS 2022 on Windows 10) You can find out what versions you have by opening the gpac.sln solution in Visual Studio, opening the property page of one the project, and checking the "Platform Toolset" and "Windows SDK Version" fields. @@ -42,7 +57,7 @@ You can adjust the parameters: You can add this directory to your `PATH` environment variable. Or move the binary to a destination in your `PATH`. Or just use it locally. - # Full GPAC build +# Full GPAC build To get a full build of the whole GPAC project, you will first need to build some dependencies, copy them over to the main gpac repository, and build it. @@ -101,6 +116,7 @@ The binaries will be in ```batch \gpac_public\bin\\ ``` + (e.g. `\gpac_public\bin\x64\Release`) You can add this to your `PATH` to run it from anywhere. diff --git a/docs/Build/build/GPAC-Build-Guide-for-iOS.md b/docs/Build/build/GPAC-Build-Guide-for-iOS.md index 689135ab..ad4e56c3 100644 --- a/docs/Build/build/GPAC-Build-Guide-for-iOS.md +++ b/docs/Build/build/GPAC-Build-Guide-for-iOS.md @@ -1,9 +1,16 @@ -To build GPAC for iOS, we'll first need to cross-compile some dependencies, before building the project itself. +--- +tags: +- data +--- -For the following, we'll call the working directory ``. -# Building dependencies +_To build GPAC for iOS, we'll first need to cross-compile some dependencies, before building the project itself._ + +_For the following, we'll call the working directory ``._ + + +# Building dependencies {: data-level="all"} ## Get the code diff --git a/docs/Build/build/GPAC-Build-with-Docker.md b/docs/Build/build/GPAC-Build-with-Docker.md index a8c0c650..ee782766 100644 --- a/docs/Build/build/GPAC-Build-with-Docker.md +++ b/docs/Build/build/GPAC-Build-with-Docker.md @@ -1,13 +1,35 @@ +--- +tags: +- profile +- mp4 +- mpd +- pid +- heif +- media +- isomedia +- data +- isobmff +- frame +- xml +- output +- codec +- mpeg +- libgpac +- dash +--- + + + [**HOME**](Home) » [**Build**](Build-Introduction) » Docker -This page contains instructions on how to build and use gpac with Docker. +_This page contains instructions on how to build and use gpac with Docker._ -For now, only linux containers are available. +_For now, only linux containers are available._ -Pre-requisite: a working [Docker](https://www.docker.com/) installation. +_Pre-requisite: a working [Docker](https://www.docker.com/) installation._ -# Linux +# Linux {: data-level="all"} We provide two types of resources depending on your use case. @@ -16,8 +38,10 @@ We provide two types of resources depending on your use case. ## Build your own image (optional) -```bash +``` bash + # clone gpac repo + git clone https://github.com/gpac/gpac.git cd gpac diff --git a/docs/Build/old/Command-line-GPAC-compiling-on-Windows-x86-using-free-Microsoft-Visual-C++.md b/docs/Build/old/Command-line-GPAC-compiling-on-Windows-x86-using-free-Microsoft-Visual-C++.md index fa7dbf85..7a1973f3 100644 --- a/docs/Build/old/Command-line-GPAC-compiling-on-Windows-x86-using-free-Microsoft-Visual-C++.md +++ b/docs/Build/old/Command-line-GPAC-compiling-on-Windows-x86-using-free-Microsoft-Visual-C++.md @@ -1,4 +1,16 @@ -## Overview +--- +tags: +- source +- chain +- data +- output +- sink +- dump +--- + + + +# Overview {: data-level="all"} Windows users often ask about how to compile GPAC and generate an installer. The main problem on platforms, like Windows, that don't rely on a modern package system is to get your dependencies with the correct version. Fortunately, we release a package containing most of the extra-libs we use. @@ -6,7 +18,7 @@ The first reaction of unix users when compiling GPAC is to use an existing gnu/g **This article was made using a clean install within a virtualized Windows XP. It focuses on command-lines but converting and compiling projects from the GUI works.** -## Getting the tools +# Getting the tools * [Download Visual C++ Express](http://www.microsoft.com/express/Downloads/) on the web (2010 has been used for this article). * Ensure you have access to msbuild.exe which is provided with [the .NET framework 3.5](http://www.microsoft.com/downloads/en/details.aspx?FamilyId=333325fd-ae52-4e35-b531-508d977d32a6&displaylang=en) (it should be installed on any up-to-date Windows): `%WINDIR%\Microsoft.NET\Framework\v3.5\MSBuild.exe` @@ -21,7 +33,7 @@ Rem: some users told us June 2010 DirectX SDK got rid of some needed components. Note: if you don't have the MFC/AFX headers, GPAC still provides you with SDL as an audio/video output. -## Getting the source code (or organizing it) +# Getting the source code (or organizing it) Make sure you have git and [subversion installed on your system](http://subversion.apache.org/), and **add the subversion binaries to your path**. @@ -35,7 +47,7 @@ Download the file at __drv__ (cstr): audio driver name -__bnum__ (uint, default: _2_): number of audio buffers (0 for auto) -__bdur__ (uint, default: _100_): total duration of all buffers in ms (0 for auto) +
+__drv__ (cstr): audio driver name +
+
+__bnum__ (uint, default: _2_): number of audio buffers (0 for auto) +
+
+__bdur__ (uint, default: _100_): total duration of all buffers in ms (0 for auto) +
+
__threaded__ (bool, default: _true_): force dedicated thread creation if sound card driver is not threaded +
+
__dur__ (frac, default: _0_): only play the specified duration +
+
__clock__ (bool, default: _true_): hint audio clock for this stream -__speed__ (dbl, default: _1.0_, updatable): set playback speed. If speed is negative and start is 0, start is set to -1 -__start__ (dbl, default: _0.0_, updatable): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__vol__ (uint, default: _100_, minmax: 0-100, updatable): set default audio volume, as a percentage between 0 and 100 -__pan__ (uint, default: _50_, minmax: 0-100, updatable): set stereo pan, as a percentage between 0 and 100, 50 being centered -__buffer__ (uint, default: _200_): set playout buffer in ms -__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer -__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
+__speed__ (dbl, default: _1.0_, updatable): set playback speed. If speed is negative and start is 0, start is set to -1 +
+
+__start__ (dbl, default: _0.0_, updatable): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__vol__ (uint, default: _100_, minmax: 0-100, updatable): set default audio volume, as a percentage between 0 and 100 +
+
+__pan__ (uint, default: _50_, minmax: 0-100, updatable): set stereo pan, as a percentage between 0 and 100, 50 being centered +
+
+__buffer__ (uint, default: _200_): set playout buffer in ms +
+
+__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer +
+
+__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
__adelay__ (frac, default: _0_, updatable): set audio delay in sec +
+
__buffer_done__ (bool): buffer done indication (readonly, for user app) +
+
__rebuffer__ (luint): system time in us at which last rebuffer started, 0 if not rebuffering (readonly, for user app) +
+
__media_offset__ (dbl, default: _0_): media offset (substract this value to CTS to get media time - readonly) +
diff --git a/docs/Filters/avgen.md b/docs/Filters/avgen.md index 583479a4..7f0fab8c 100644 --- a/docs/Filters/avgen.md +++ b/docs/Filters/avgen.md @@ -27,7 +27,8 @@ Target encoding bitrates can be assigned to each output using [rates](#rates). T Example ``` gpac avgen:sizes=1280x720,1920x1080:rates=2M,5M c=aac:FID=1 c=264:FID=2:clone -o live.mpd:SID=1,2 -``` +``` + # Multiview generation @@ -44,38 +45,82 @@ If multiple video PIDs are produced, they are assigned the names `videoN` and ID If multiple [views](#views) are generated, they are assigned the names `videoN_vK` and ID `N*views+K-1`, N in [1, sizes], K in [1, views]. -# Options +# Options {.no-collapse} -__type__ (enum, default: _av_): output selection +
+__type__ (enum, default: _av_): output selection - a: audio only - v: video only - av: audio and video - -__freq__ (uint, default: _440_): frequency of beep -__freq2__ (uint, default: _659_): frequency of odd beep -__sr__ (uint, default: _44100_): output samplerate -__flen__ (uint, default: _1024_): output frame length in samples -__ch__ (uint, default: _1_): number of channels -__alter__ (bool, default: _false_): beep alternatively on each channel -__blen__ (uint, default: _50_): length of beep in milliseconds -__fps__ (frac, default: _25_): video frame rate -__sizes__ (v2il, default: _1280x720_): video size in pixels -__pfmt__ (pfmt, default: _yuv_): output pixel format -__lock__ (bool, default: _false_): lock timing to video generation -__dyn__ (bool, default: _true_): move bottom banner -__ntp__ (bool, default: _true_): send NTP along with packets -__copy__ (bool, default: _false_): copy the framebuffer into each video packet instead of using packet references -__dur__ (frac, default: _0/0_): run for the given time in second -__adjust__ (bool, default: _true_): adjust start time to synchronize counter and UTC -__pack__ (enum, default: _no_): packing mode for stereo views +
+ +
+__freq__ (uint, default: _440_): frequency of beep +
+
+__freq2__ (uint, default: _659_): frequency of odd beep +
+
+__sr__ (uint, default: _44100_): output samplerate +
+
+__flen__ (uint, default: _1024_): output frame length in samples +
+
+__ch__ (uint, default: _1_): number of channels +
+
+__alter__ (bool, default: _false_): beep alternatively on each channel +
+
+__blen__ (uint, default: _50_): length of beep in milliseconds +
+
+__fps__ (frac, default: _25_): video frame rate +
+
+__sizes__ (v2il, default: _1280x720_): video size in pixels +
+
+__pfmt__ (pfmt, default: _yuv_): output pixel format +
+
+__lock__ (bool, default: _false_): lock timing to video generation +
+
+__dyn__ (bool, default: _true_): move bottom banner +
+
+__ntp__ (bool, default: _true_): send NTP along with packets +
+
+__copy__ (bool, default: _false_): copy the framebuffer into each video packet instead of using packet references +
+
+__dur__ (frac, default: _0/0_): run for the given time in second +
+
+__adjust__ (bool, default: _true_): adjust start time to synchronize counter and UTC +
+
+__pack__ (enum, default: _no_): packing mode for stereo views - no: no packing - ss: side by side packing, forces [views](#views) to 2 - tb: top-bottom packing, forces [views](#views) to 2 - -__disparity__ (uint, default: _20_): disparity in pixels between left-most and right-most views -__views__ (uint, default: _1_): number of views -__rates__ (strl): number of target bitrates to assign, one per size -__logt__ (bool): log frame time to console +
+ +
+__disparity__ (uint, default: _20_): disparity in pixels between left-most and right-most views +
+
+__views__ (uint, default: _1_): number of views +
+
+__rates__ (strl): number of target bitrates to assign, one per size +
+
+__logt__ (bool): log frame time to console +
diff --git a/docs/Filters/avidmx.md b/docs/Filters/avidmx.md index e88564a3..ceda393c 100644 --- a/docs/Filters/avidmx.md +++ b/docs/Filters/avidmx.md @@ -8,9 +8,15 @@ This filter may be automatically loaded during graph resolution. This filter demultiplexes AVI files to produce media PIDs and frames. -# Options +# Options {.no-collapse} -__fps__ (frac, default: _1/0_): import frame rate, default is AVI one +
+__fps__ (frac, default: _1/0_): import frame rate, default is AVI one +
+
__importer__ (bool, default: _false_): compatibility with old importer, displays import results +
+
__noreframe__ (bool, default: _false_): skip media reframer +
diff --git a/docs/Filters/avimx.md b/docs/Filters/avimx.md index bd5f2fd3..9ad6c1f5 100644 --- a/docs/Filters/avimx.md +++ b/docs/Filters/avimx.md @@ -16,10 +16,18 @@ The value can either be a 4CC or a string, indicating the mux format for the PID If the string is prefixed with `+` and the decoder configuration is present and formatted as an ISOBMFF box, the box header will be removed. -# Options +# Options {.no-collapse} -__dst__ (cstr): location of destination file -__fps__ (frac, default: _25/1_): default framerate if none indicated in stream +
+__dst__ (cstr): location of destination file +
+
+__fps__ (frac, default: _25/1_): default framerate if none indicated in stream +
+
__noraw__ (bool, default: _false_): disable raw output in AVI, only compressed ones allowed +
+
__opendml_size__ (luint, default: _0_): force opendml format when chunks are larger than this amount (0 means 1.9Gb max size in each riff chunk) +
diff --git a/docs/Filters/avmix.md b/docs/Filters/avmix.md index 3c331ec6..0e49963c 100644 --- a/docs/Filters/avmix.md +++ b/docs/Filters/avmix.md @@ -230,13 +230,15 @@ The special URL scheme `ipid://` can be used to locate an input pid by link dire 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. @@ -366,7 +368,8 @@ The `JSFun` may return false to indicate that the scene should be considered as Example ``` "mxjs": "tr.rotation = (get_media_time() % 8) * 360 / 8; tr.update=true;" -``` +``` + ## Grouping ### Properties for `group` objects @@ -465,7 +468,8 @@ The `JSFun` specified by `fun` takes one argument `ratio` and must return the re Example ``` "fun": "return ratio*ratio;" -``` +``` + ## Timers and animations ### Properties for `timer` objects @@ -521,13 +525,15 @@ The `JSFun` specified by `mode` has one input parameter `interp` equal to the in 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 @@ -547,7 +553,8 @@ The `JSFun` function specified by `fun` has no input parameter. The return value 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 @@ -583,13 +590,15 @@ 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 @@ -610,7 +619,8 @@ The javascript function will be called with a single argument `evt` containing t 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 @@ -703,7 +713,8 @@ Example ] } ] -``` +``` + # Updates Format @@ -744,7 +755,8 @@ Example {"replace": "scene1@x", "with": 20}, {"replace": "seq1@start", "with": "now"} ] -``` +``` + # Scene modules @@ -768,32 +780,6 @@ Options: -## Scene `clear` -This scene clears the canvas area covered by the scene with a given color. - -The default clear color of the mixer is `black`. - -The clear area is always axis-aligned in output frame, so when skew/rotation are present, the axis-aligned bounding box of the transformed scene area will be cleared. - -Options: - -- color ('none'): clear color - - -## 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) - - ## Scene `shape` This scene can be used to setup a shape, its outline and specify the fill and strike modes. Supported shapes include: @@ -868,7 +854,8 @@ The code is exposed the scene as `this`. The variable `this.path` is created, re Example ``` "shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0, this.width, this.height/3); this.path.add_path(el);" -``` +``` + The default behaviour is to use the shape width and height as reference size for texture mapping. If your custom path is textured, with bounding rectangle size different from the indicated shape size, set the variable `this.tx_adjust` to true. @@ -878,7 +865,8 @@ In the previous example, the texture mapping will not be impacted by the custom Example ``` "shape": "this.path.add_rectangle(0, 0, this.width, this.height); let el = new evg.Path().ellipse(0, 0, this.width, this.height/3); this.path.add_path(el); this.tx_adjust = true;" -``` +``` + In this example, the texture mapping will be adjusted to the desired size. The global variables and functions are available (c.f. `gpac -h avmix:global`): @@ -1014,8 +1002,41 @@ Options: - rt_rep (false): same as `rt` for local image in replace mode +## 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) + + +## Scene `clear` +This scene clears the canvas area covered by the scene with a given color. + +The default clear color of the mixer is `black`. + +The clear area is always axis-aligned in output frame, so when skew/rotation are present, the axis-aligned bounding box of the transformed scene area will be cleared. + +Options: + +- color ('none'): clear color + + # Transition modules +## Transition `fade` - software/GPU +This transition performs fade to/from color of source videos +Options: + +- color ('black'): fade color + + ## Transition `gltrans` - GPU only This transition module wraps gl-transitions, see https://gl-transitions.com/ and `gpac -h avmix:gltrans` for builtin transitions Options: @@ -1051,42 +1072,69 @@ Options: ## Transition `mix` - software/GPU This transition performs cross-fade of source videos - -## Transition `fade` - software/GPU -This transition performs fade to/from color of source videos -Options: - -- color ('black'): fade color - -# Options +# Options {.no-collapse} -__pl__ (str, default: _avmix.json_): local playlist file to load -__live__ (bool, default: _true_): live mode +
+__pl__ (str, default: _avmix.json_): local playlist file to load +
+
+__live__ (bool, default: _true_): live mode +
+
__gpu__ (enum, default: _off_): enable GPU usage - off: no GPU - mix: only render textured path to GPU, use software rasterizer for the outlines, solid fills and gradients - all: try to use GPU for everything +
+
__thread__ (sint, default: _-1_): use threads for software rasterizer (-1 for all available cores) +
+
__lwait__ (uint, default: _1000_): timeout in ms before considering no signal is present +
+
__ltimeout__ (uint, default: _4000_): timeout in ms before restarting child processes +
+
__maxdur__ (dbl, default: _0_): run for given seconds and exit, will not abort if 0 (used for live mode tests) +
+
__updates__ (str): local JSON files for playlist updates +
+
__maxdepth__ (uint, default: _100_): maximum depth of a branch in the scene graph -__vsize__ (v2d, default: _1920x1080_): output video size, 0 disable video output -__fps__ (frac, default: _25_): output video frame rate -__pfmt__ (pfmt, default: _yuv_): output pixel format. Use `rgba` in GPU mode to force alpha channel +
+
+__vsize__ (v2d, default: _1920x1080_): output video size, 0 disable video output +
+
+__fps__ (frac, default: _25_): output video frame rate +
+
+__pfmt__ (pfmt, default: _yuv_): output pixel format. Use `rgba` in GPU mode to force alpha channel +
+
__dynpfmt__ (enum, default: _init_): allow dynamic change of output pixel format in software mode - off: pixel format is forced to desired value - init: pixel format is forced to format of fullscreen input in first generated frame - all: pixel format changes each time a full-screen input PID at same resolution is used - -__sr__ (uint, default: _44100_): output audio sample rate, 0 disable audio output -__ch__ (uint, default: _2_): number of output audio channels, 0 disable audio output -__afmt__ (afmt, default: _s16_): output audio format (only s16, s32, flt and dbl are supported) +
+ +
+__sr__ (uint, default: _44100_): output audio sample rate, 0 disable audio output +
+
+__ch__ (uint, default: _2_): number of output audio channels, 0 disable audio output +
+
+__afmt__ (afmt, default: _s16_): output audio format (only s16, s32, flt and dbl are supported) +
+
__alen__ (uint, default: _1024_): default number of samples per frame +
diff --git a/docs/Filters/bsagg.md b/docs/Filters/bsagg.md index 4d041e2d..383b5da9 100644 --- a/docs/Filters/bsagg.md +++ b/docs/Filters/bsagg.md @@ -18,7 +18,9 @@ The filter can also be used on AVC and HEVC DolbyVision dual-streams to aggregat The filter does not forward aggregator or extractor NAL units. -# Options +# Options {.no-collapse} -__svcqid__ (bool, default: _false_): use qualityID instead of dependencyID for SVC splitting +
+__svcqid__ (bool, default: _false_): use qualityID instead of dependencyID for SVC splitting +
diff --git a/docs/Filters/bsrw.md b/docs/Filters/bsrw.md index d4123115..500d789f 100644 --- a/docs/Filters/bsrw.md +++ b/docs/Filters/bsrw.md @@ -39,26 +39,58 @@ The filter can currently modify the following properties in the stream configura The filter will work in passthrough mode for all other codecs and media types. -# Options +# Options {.no-collapse} -__cprim__ (cprm, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470G|SMPTE170|SMPTE240|FILM|BT2020|SMPTE428|SMPTE431|SMPTE432|EBU3213, updatable): color primaries according to ISO/IEC 23001-8 / 23091-2 +
+__cprim__ (cprm, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470G|SMPTE170|SMPTE240|FILM|BT2020|SMPTE428|SMPTE431|SMPTE432|EBU3213, updatable): color primaries according to ISO/IEC 23001-8 / 23091-2 +
-__ctfc__ (ctfc, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470BG|SMPTE170|SMPTE249|Linear|Log100|Log316|IEC61966|BT1361|sRGB|BT2020_10|BT2020_12|SMPTE2084|SMPTE428|STDB67, updatable): color transfer characteristics according to ISO/IEC 23001-8 / 23091-2 +
+__ctfc__ (ctfc, default: _-1_, Enum: reserved0|BT709|undef|reserved3|BT470M|BT470BG|SMPTE170|SMPTE249|Linear|Log100|Log316|IEC61966|BT1361|sRGB|BT2020_10|BT2020_12|SMPTE2084|SMPTE428|STDB67, updatable): color transfer characteristics according to ISO/IEC 23001-8 / 23091-2 +
-__cmx__ (cmxc, default: _-1_, Enum: GBR|BT709|undef|FCC|BT601|SMPTE170|SMPTE240|YCgCo|BT2020|BT2020cl|YDzDx, updatable): color matrix coeficients according to ISO/IEC 23001-8 / 23091-2 +
+__cmx__ (cmxc, default: _-1_, Enum: GBR|BT709|undef|FCC|BT601|SMPTE170|SMPTE240|YCgCo|BT2020|BT2020cl|YDzDx, updatable): color matrix coeficients according to ISO/IEC 23001-8 / 23091-2 +
-__sar__ (frac, default: _-1/-1_, updatable): aspect ratio to rewrite -__m4vpl__ (sint, default: _-1_, updatable): set ProfileLevel for MPEG-4 video part two -__fullrange__ (bool, default: _false_, updatable): video full range flag -__novsi__ (bool, default: _false_, updatable): remove video_signal_type from VUI in AVC|H264 and HEVC -__novuitiming__ (bool, default: _false_, updatable): remove timing_info from VUI in AVC|H264 and HEVC -__prof__ (sint, default: _-1_, updatable): profile indication for AVC|H264 -__lev__ (sint, default: _-1_, updatable): level indication for AVC|H264, level_idc for VVC -__pcomp__ (sint, default: _-1_, updatable): profile compatibility for AVC|H264 -__pidc__ (sint, default: _-1_, updatable): profile IDC for HEVC and VVC -__pspace__ (sint, default: _-1_, updatable): profile space for HEVC -__gpcflags__ (sint, default: _-1_, updatable): general compatibility flags for HEVC -__rmsei__ (bool, default: _false_, updatable): remove SEI messages from bitstream for AVC|H264, HEVC and VVC -__vidfmt__ (enum, default: _-1_, updatable): video format for AVC|H264, HEVC and VVC (component|pal|ntsc|secam|mac|undef) +
+__sar__ (frac, default: _-1/-1_, updatable): aspect ratio to rewrite +
+
+__m4vpl__ (sint, default: _-1_, updatable): set ProfileLevel for MPEG-4 video part two +
+
+__fullrange__ (bool, default: _false_, updatable): video full range flag +
+
+__novsi__ (bool, default: _false_, updatable): remove video_signal_type from VUI in AVC|H264 and HEVC +
+
+__novuitiming__ (bool, default: _false_, updatable): remove timing_info from VUI in AVC|H264 and HEVC +
+
+__prof__ (sint, default: _-1_, updatable): profile indication for AVC|H264 +
+
+__lev__ (sint, default: _-1_, updatable): level indication for AVC|H264, level_idc for VVC +
+
+__pcomp__ (sint, default: _-1_, updatable): profile compatibility for AVC|H264 +
+
+__pidc__ (sint, default: _-1_, updatable): profile IDC for HEVC and VVC +
+
+__pspace__ (sint, default: _-1_, updatable): profile space for HEVC +
+
+__gpcflags__ (sint, default: _-1_, updatable): general compatibility flags for HEVC +
+
+__rmsei__ (bool, default: _false_, updatable): remove SEI messages from bitstream for AVC|H264, HEVC and VVC +
+
+__vidfmt__ (enum, default: _-1_, updatable): video format for AVC|H264, HEVC and VVC (component|pal|ntsc|secam|mac|undef) +
diff --git a/docs/Filters/bssplit.md b/docs/Filters/bssplit.md index 0735456d..ff273e17 100644 --- a/docs/Filters/bssplit.md +++ b/docs/Filters/bssplit.md @@ -50,9 +50,15 @@ The filter can also be used on AVC and HEVC DolbyVision streams to split base st The filter does not create aggregator or extractor NAL units. -# Options +# Options {.no-collapse} -__ltid__ (strl): temporal and layer ID of output streams -__svcqid__ (bool, default: _false_): use qualityID instead of dependencyID for SVC splitting -__sig_ltid__ (bool, default: _false_): signal maximum temporal (`max_temporal_id`) and layer ID (`max_layer_id`) of output streams (mostly used for debug) +
+__ltid__ (strl): temporal and layer ID of output streams +
+
+__svcqid__ (bool, default: _false_): use qualityID instead of dependencyID for SVC splitting +
+
+__sig_ltid__ (bool, default: _false_): signal maximum temporal (`max_temporal_id`) and layer ID (`max_layer_id`) of output streams (mostly used for debug) +
diff --git a/docs/Filters/btplay.md b/docs/Filters/btplay.md index 8f53fc97..880b6f69 100644 --- a/docs/Filters/btplay.md +++ b/docs/Filters/btplay.md @@ -10,7 +10,9 @@ This filter parses MPEG-4 BIFS (BT and XMT), VRML97 and X3D (wrl and XML) files 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`. -# Options +# Options {.no-collapse} +
__sax_dur__ (uint, default: _0_): duration for SAX parsing (XMT), 0 disables SAX parsing +
diff --git a/docs/Filters/ccdec.md b/docs/Filters/ccdec.md index 61af34e2..f3d1fa0a 100644 --- a/docs/Filters/ccdec.md +++ b/docs/Filters/ccdec.md @@ -1,6 +1,6 @@ -# Closed-Caption decoder +# Closed-Caption decoder {:data-level="all"} Register name used to load filter: __ccdec__ This filter is not checked during graph resolution and needs explicit loading. diff --git a/docs/Filters/cdcrypt.md b/docs/Filters/cdcrypt.md index 61e81b97..35bbd33f 100644 --- a/docs/Filters/cdcrypt.md +++ b/docs/Filters/cdcrypt.md @@ -14,9 +14,12 @@ The DRM config file can be set per PID using the property `DecryptInfo` (highest When the file is set per PID, the first `CryptInfo` with the same ID is used, otherwise the first `CryptInfo` is used.When the file is set globally (not per PID), the first `CrypTrack` in the DRM config file with the same ID is used, otherwise the first `CrypTrack` with ID 0 or not set is used. -# Options +# Options {.no-collapse} -__cfile__ (str): crypt file location +
+__cfile__ (str): crypt file location +
+
__decrypt__ (enum, default: _full_): decrypt mode (CENC only) - full: decrypt everything, throwing error if keys are not found @@ -25,9 +28,18 @@ When the file is set per PID, the first `CryptInfo` with the same ID is used, ot - pad0: decrypt nothing and replace all crypted bits with 0 - pad1: decrypt nothing and replace all crypted bits with 1 - padsc: decrypt nothing and replace all crypted bytes with start codes +
+
__drop_keys__ (uintl): consider keys with given 1-based indexes as not available (multi-key debug) +
+
__kids__ (strl): define KIDs. If `keys` is empty, consider keys with given KID (as hex string) as not available (debug) +
+
__keys__ (strl): define key values for each of the specified KID +
+
__hls_cenc_patch_iv__ (bool, default: _false_): ignore IV updates in some broken HLS+CENC streams +
diff --git a/docs/Filters/cecrypt.md b/docs/Filters/cecrypt.md index a78fe72b..bb57ad52 100644 --- a/docs/Filters/cecrypt.md +++ b/docs/Filters/cecrypt.md @@ -13,9 +13,15 @@ When the DRM config file is set globally (not per PID), the first `CrypTrack` in If no DRM config file is defined for a given PID, this PID will not be encrypted, or an error will be thrown if [allc](#allc) is specified. -# Options +# Options {.no-collapse} -__cfile__ (str): crypt file location -__allc__ (bool): throw error if no DRM config file is found for a PID -__bk_stats__ (bool): print number of encrypted blocks to stdout upon exit +
+__cfile__ (str): crypt file location +
+
+__allc__ (bool): throw error if no DRM config file is found for a PID +
+
+__bk_stats__ (bool): print number of encrypted blocks to stdout upon exit +
diff --git a/docs/Filters/compositor.md b/docs/Filters/compositor.md index b45c69c9..405245b8 100644 --- a/docs/Filters/compositor.md +++ b/docs/Filters/compositor.md @@ -60,57 +60,110 @@ The compositor can act as a source filter when the [src](#src) option is explici Example ``` gpac compositor:src=source.mp4 vout -``` +``` + The compositor can act as a source filter when the source url uses one of the compositor built-in protocol schemes: Example ``` gpac -i mosaic://URL1:URL2 vout -``` +``` + -# Options +# Options {.no-collapse} +
__aa__ (enum, default: _all_, updatable): set anti-aliasing mode for raster graphics; whether the setting is applied or not depends on the graphics module or graphic card - none: no anti-aliasing - text: anti-aliasing for text only - all: complete anti-aliasing +
+
__hlfill__ (uint, default: _0x0_, updatable): set highlight fill color (ARGB) +
+
__hlline__ (uint, default: _0xFF000000_, updatable): set highlight stroke color (ARGB) +
+
__hllinew__ (flt, default: _1.0_, updatable): set highlight stroke width +
+
__sz__ (bool, default: _true_, updatable): enable scalable zoom. When scalable zoom is enabled, resizing the output window will also recompute all vectorial objects. Otherwise only the final buffer is stretched -__bc__ (uint, default: _0_, updatable): default background color to use when displaying transparent images or video with no scene composition instructions +
+
+__bc__ (uint, default: _0_, updatable): default background color to use when displaying transparent images or video with no scene composition instructions +
+
__yuvhw__ (bool, default: _true_, updatable): enable YUV hardware for 2D blit +
+
__blitp__ (bool, default: _true_, updatable): partial hardware blit. If not set, will force more redraw +
+
__softblt__ (bool, default: _true_): enable software blit/stretch in 2D. If disabled, vector graphics rasterizer will always be used +
+
__stress__ (bool, default: _false_, updatable): enable stress mode of compositor (rebuild all vector graphics and texture states at each frame) -__fast__ (bool, default: _false_, updatable): enable speed optimization - whether the setting is applied or not depends on the graphics module / graphic card +
+
+__fast__ (bool, default: _false_, updatable): enable speed optimization - whether the setting is applied or not depends on the graphics module / graphic card +
+
__bvol__ (enum, default: _no_, updatable): draw bounding volume of objects - no: disable bounding box - box: draws a rectangle (2D) or box (3D) - aabb: draws axis-aligned bounding-box tree (3D) or rectangle (2D) +
+
__textxt__ (enum, default: _default_, updatable): specify whether text shall be drawn to a texture and then rendered or directly rendered. Using textured text can improve text rendering in 3D and also improve text-on-video like content - default: use texturing for OpenGL rendering, no texture for 2D rasterizer - never: never uses text textures - always: always render text to texture before drawing +
+
__out8b__ (bool, default: _false_, updatable): convert 10-bit video to 8 bit texture before GPU upload -__drop__ (bool, default: _false_, updatable): drop late frame when drawing. If not set, frames are not dropped until a desynchronization of 1 second or more is observed +
+
+__drop__ (bool, default: _false_, updatable): drop late frame when drawing. If not set, frames are not dropped until a desynchronization of 1 second or more is observed +
+
__sclock__ (bool, default: _false_, updatable): force synchronizing all streams on a single clock +
+
__sgaze__ (bool, default: _false_, updatable): simulate gaze events through mouse +
+
__ckey__ (uint, default: _0_, updatable): color key to use in windowless mode (0xFFRRGGBB). GPAC currently does not support true alpha blitting to desktop due to limitations in most windowing toolkit, it therefore uses color keying mechanism. The alpha part of the key is used for global transparency of the output, if supported -__timeout__ (uint, default: _10000_, updatable): timeout in ms after which a source is considered dead (0 disable timeout) -__fps__ (frac, default: _30/1_, updatable): simulation frame rate when animation-only sources are played (ignored when video is present) -__timescale__ (uint, default: _0_, updatable): timescale used for output packets when no input video PID. A value of 0 means fps numerator +
+
+__timeout__ (uint, default: _10000_, updatable): timeout in ms after which a source is considered dead (0 disable timeout) +
+
+__fps__ (frac, default: _30/1_, updatable): simulation frame rate when animation-only sources are played (ignored when video is present) +
+
+__timescale__ (uint, default: _0_, updatable): timescale used for output packets when no input video PID. A value of 0 means fps numerator +
+
__autofps__ (bool, default: _true_): use video input fps for output, ignored in player mode. If no video or not set, uses [fps](#fps) +
+
__vfr__ (bool, default: _false_): only emit frames when changes are detected. (always true in player mode and when filter is dynamically loaded) -__dur__ (dbl, default: _0_, updatable): duration of generation. Mostly used when no video input is present. Negative values mean number of frames, positive values duration in second, 0 stops as soon as all streams are done +
+
+__dur__ (dbl, default: _0_, updatable): duration of generation. Mostly used when no video input is present. Negative values mean number of frames, positive values duration in second, 0 stops as soon as all streams are done +
+
__fsize__ (bool, default: _false_, updatable): force the scene to resize to the biggest bitmap available if no size info is given in the BIFS configuration +
+
__mode2d__ (enum, default: _defer_, updatable): specify whether immediate drawing should be used or not - immediate: the screen is completely redrawn at each frame (always on if pass-through mode is detected) @@ -118,34 +171,76 @@ gpac -i mosaic://URL1:URL2 vout - debug: only renders changed areas, resetting other areas Whether the setting is applied or not depends on the graphics module and player mode +
-__amc__ (bool, default: _true_): audio multichannel support; if disabled always down-mix to stereo. Useful if the multichannel output does not work properly +
+__amc__ (bool, default: _true_): audio multichannel support; if disabled always down-mix to stereo. Useful if the multichannel output does not work properly +
+
__asr__ (uint, default: _0_): force output sample rate (0 for auto) +
+
__ach__ (uint, default: _0_): force output channels (0 for auto) +
+
__alayout__ (uint, default: _0_): force output channel layout (0 for auto) +
+
__afmt__ (afmt, default: _s16_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): force output channel format (0 for auto) +
+
__asize__ (uint, default: _1024_): audio output packet size in samples +
+
__abuf__ (uint, default: _100_): audio output buffer duration in ms - the audio renderer fills the output PID up to this value. A too low value will lower latency but can have real-time playback issues -__avol__ (uint, default: _100_, updatable): audio volume in percent -__apan__ (uint, default: _50_, updatable): audio pan in percent, 50 is no pan +
+
+__avol__ (uint, default: _100_, updatable): audio volume in percent +
+
+__apan__ (uint, default: _50_, updatable): audio pan in percent, 50 is no pan +
+
__async__ (bool, default: _true_, updatable): audio resynchronization; if disabled, audio data is never dropped but may get out of sync +
+
__max_aspeed__ (dbl, default: _2.0_, updatable): silence audio if playback speed is greater than specified value +
+
__max_vspeed__ (dbl, default: _4.0_, updatable): move to i-frame only decoding if playback speed is greater than specified value -__buffer__ (uint, default: _3000_, updatable): playout buffer in ms (overridden by `BufferLength` property of input PID) -__rbuffer__ (uint, default: _1000_, updatable): rebuffer trigger in ms (overridden by `RebufferLength` property of input PID) -__mbuffer__ (uint, default: _3000_, updatable): max buffer in ms, must be greater than playout buffer (overridden by `BufferMaxOccupancy` property of input PID) -__ntpsync__ (uint, default: _0_, updatable): ntp resync threshold in ms (drops frame if their NTP is more than the given threshold above local ntp), 0 disables ntp drop +
+
+__buffer__ (uint, default: _3000_, updatable): playout buffer in ms (overridden by `BufferLength` property of input PID) +
+
+__rbuffer__ (uint, default: _1000_, updatable): rebuffer trigger in ms (overridden by `RebufferLength` property of input PID) +
+
+__mbuffer__ (uint, default: _3000_, updatable): max buffer in ms, must be greater than playout buffer (overridden by `BufferMaxOccupancy` property of input PID) +
+
+__ntpsync__ (uint, default: _0_, updatable): ntp resync threshold in ms (drops frame if their NTP is more than the given threshold above local ntp), 0 disables ntp drop +
+
__nojs__ (bool, default: _false_): disable javascript +
+
__noback__ (bool, default: _false_): ignore background nodes and viewport fill (useful when dumping to PNG) +
+
__ogl__ (enum, default: _auto_, updatable): specify 2D rendering mode - auto: automatically decides between on, off and hybrid based on content - off: disables OpenGL; 3D will not be rendered - on: uses OpenGL for all graphics; this will involve polygon tesselation and 2D graphics will not look as nice as 2D mode - hybrid: the compositor performs software drawing of 2D graphics with no textures (better quality) and uses OpenGL for all 2D objects with textures and 3D objects +
+
__pbo__ (bool, default: _false_, updatable): enable PixelBufferObjects to push YUV textures to GPU in OpenGL Mode. This may slightly increase the performances of the playback +
+
__nav__ (enum, default: _none_, updatable): override the default navigation mode of MPEG-4/VRML (Walk) and X3D (Examine) - none: disables navigation @@ -157,42 +252,66 @@ Whether the setting is applied or not depends on the graphics module and player - exam: 2D/3D object examine - orbit: 3D object orbit - vr: 3D world VR (yaw/pitch/roll) +
+
__linegl__ (bool, default: _false_, updatable): indicate that outlining shall be done through OpenGL pen width rather than vectorial outlining +
+
__epow2__ (bool, default: _true_, updatable): emulate power-of-2 textures for OpenGL (old hardware). Ignored if OpenGL rectangular texture extension is enabled - yes: video texture is not resized but emulated with padding. This usually speeds up video mapping on shapes but disables texture transformations - no: video is resized to a power of 2 texture when mapping to a shape +
+
__paa__ (bool, default: _false_, updatable): indicate whether polygon antialiasing should be used in full antialiasing mode. If not set, only lines and points antialiasing are used +
+
__bcull__ (enum, default: _on_, updatable): indicate whether backface culling shall be disable or not - on: enables backface culling - off: disables backface culling - alpha: only enables backface culling for transparent meshes +
+
__wire__ (enum, default: _none_, updatable): wireframe mode - none: objects are drawn as solid - only: objects are drawn as wireframe only - solid: objects are drawn as solid and wireframe is then drawn +
+
__norms__ (enum, default: _none_, updatable): normal vector drawing for debug - none: no normals drawn - face: one normal per face drawn - vertex: one normal per vertex drawn +
+
__rext__ (bool, default: _true_, updatable): use non power of two (rectangular) texture GL extension +
+
__cull__ (bool, default: _true_, updatable): use aabb culling: large objects are rendered in multiple calls when not fully in viewport +
+
__depth_gl_scale__ (flt, default: _100_, updatable): set depth scaler +
+
__depth_gl_type__ (enum, default: _none_, updatable): set geometry type used to draw depth video - none: no geometric conversion - point: compute point cloud from pixel+depth - strip: same as point but thins point set +
-__nbviews__ (uint, default: _0_, updatable): number of views to use in stereo mode +
+__nbviews__ (uint, default: _0_, updatable): number of views to use in stereo mode +
+
__stereo__ (enum, default: _none_, updatable): stereo output type. If your graphic card does not support OpenGL shaders, only `top` and `side` modes will be available - none: no stereo @@ -205,66 +324,135 @@ Whether the setting is applied or not depends on the graphics module and player - spv5: images are interleaved by for SpatialView 5 views display, fullscreen mode (forces views=5) - alio8: images are interleaved by for Alioscopy 8 views displays, fullscreen mode (forces views=8) - custom: images are interleaved according to the shader file indicated in [mvshader](#mvshader). The shader is exposed each view as uniform sampler2D gfViewX, where X is the view number starting from the left +
+
__mvshader__ (str, updatable): file path to the custom multiview interleaving shader +
+
__fpack__ (enum, default: _none_, updatable): default frame packing of input video - none: no frame packing - top: top bottom frame packing - side: side by side packing +
+
__camlay__ (enum, default: _offaxis_, updatable): camera layout in multiview modes - straight: camera is moved along a straight line, no rotation - offaxis: off-axis projection is used - linear: camera is moved along a straight line with rotation - circular: camera is moved along a circle with rotation +
-__iod__ (flt, default: _6.4_, updatable): inter-ocular distance (eye separation) in cm (distance between the cameras). +
+__iod__ (flt, default: _6.4_, updatable): inter-ocular distance (eye separation) in cm (distance between the cameras). +
+
__rview__ (bool, default: _false_, updatable): reverse view order +
+
__dbgpack__ (bool, default: _false_, updatable): view packed stereo video as single image (show all) +
+
__tvtn__ (uint, default: _30_, updatable): number of point sampling for tile visibility algorithm +
+
__tvtt__ (uint, default: _8_, updatable): number of points above which the tile is considered visible +
+
__tvtd__ (enum, default: _off_, updatable): debug tiles and full coverage SRD - off: regular draw - partial: only displaying partial tiles, not the full sphere video - full: only display the full sphere video +
+
__tvtf__ (bool, default: _false_, updatable): force all tiles to be considered visible, regardless of viewpoint -__fov__ (flt, default: _1.570796326794897_, updatable): default field of view for VR +
+
+__fov__ (flt, default: _1.570796326794897_, updatable): default field of view for VR +
+
__vertshader__ (str): path to vertex shader file +
+
__fragshader__ (str): path to fragment shader file +
+
__autocal__ (bool, default: _false_, updatable): auto calibration of znear/zfar in depth rendering mode +
+
__dispdepth__ (sint, default: _-1_, updatable): display depth, negative value uses default screen height +
+
__dispdist__ (flt, default: _50_, updatable): distance in cm between the camera and the zero-disparity plane. There is currently no automatic calibration of depth in GPAC +
+
__focdist__ (flt, default: _0_, updatable): distance of focus point +
+
__osize__ (v2di, default: _0x0_, updatable): force output size. If not set, size is derived from inputs +
+
__dpi__ (v2di, default: _96x96_, updatable): default dpi if not indicated by video output +
+
__dbgpvr__ (flt, default: _0_, updatable): debug scene used by PVR addon +
+
__player__ (enum, default: _no_): set compositor in player mode - no: regular mode - base: player mode - gui: player mode with GUI auto-start +
+
__noaudio__ (bool, default: _false_): disable audio output +
+
__opfmt__ (pfmt, default: _none_, Enum: none|yuv420|yvu420|yuv420_10|yuv422|yuv422_10|yuv444|yuv444_10|uyvy|vyuy|yuyv|yvyu|uyvl|vyul|yuyl|yvyl|nv12|nv21|nv1l|nv2l|yuva|yuvd|yuv444a|yuv444p|v308|yuv444ap|v408|v410|v210|grey|algr|gral|rgb4|rgb5|rgb6|rgba|argb|bgra|abgr|rgb|bgr|xrgb|rgbx|xbgr|bgrx|rgbd|rgbds|uncv): pixel format to use for output. Ignored in [player](#player) mode +
+
__drv__ (enum, default: _auto_): indicate if graphics driver should be used - no: never loads a graphics driver, software blit is used, no 3D possible (in player mode, disables OpenGL) - yes: always loads a graphics driver, output pixel format will be RGB (in player mode, same as `auto`) - auto: decides based on the loaded content +
+
__src__ (cstr): URL of source content +
+
__gaze_x__ (sint, default: _0_, updatable): horizontal gaze coordinate (0=left, width=right) +
+
__gaze_y__ (sint, default: _0_, updatable): vertical gaze coordinate (0=top, height=bottom) +
+
__gazer_enabled__ (bool, default: _false_, updatable): enable gaze event dispatch +
+
__subtx__ (sint, default: _0_, updatable): horizontal translation in pixels towards right for subtitles renderers +
+
__subty__ (sint, default: _0_, updatable): vertical translation in pixels towards top for subtitles renderers +
+
__subfs__ (uint, default: _0_, updatable): font size for subtitles renderers (0 means automatic) +
+
__subd__ (sint, default: _0_, updatable): subtitle delay in milliseconds for subtitles renderers +
+
__audd__ (sint, default: _0_, updatable): audio delay in milliseconds +
+
__clipframe__ (bool, default: _false_): visual output is clipped to bounding rectangle +
diff --git a/docs/Filters/core_config.md b/docs/Filters/core_config.md index 342ee6be..195eaf52 100644 --- a/docs/Filters/core_config.md +++ b/docs/Filters/core_config.md @@ -32,7 +32,8 @@ Example ``` [core] threads=2 -``` +``` + Setting this in the config file is equivalent to using `-threads=2`. The options specified at prompt overrides the value of the config file. @@ -43,7 +44,8 @@ Example ``` [filter@rtpin] interleave=yes -``` +``` + This will force the rtp input filter to always request RTP over RTSP by default. To generate a configuration file with all filters options serialized, use [-wf](gpac_general/#wf). @@ -54,12 +56,14 @@ This will set option `OPTNAME`, when present, to `VAL` in any loaded filter. Example ``` --buffer=100 -i file vout aout -``` +``` + This is equivalent to specifying `vout:buffer=100 aout:buffer=100`. Example ``` --buffer=100 -i file vout aout:buffer=10 -``` +``` + This is equivalent to specifying `vout:buffer=100 aout:buffer=10`. __Warning: This syntax only applies to regular filter options. It cannot be used with builtin shortcuts (gfreg, enc, ...).__ @@ -68,7 +72,8 @@ Meta-filter options can be set in the same way using the syntax `--OPT_NAME=VAL` Example ``` --profile=Baseline -i file.cmp -o dump.264 -``` +``` + This is equivalent to specifying `-o dump.264:profile=Baseline`. For both syntaxes, it is possible to specify the filter registry name of the option, using `--FNAME:OPTNAME=VAL` or `--FNAME@OPTNAME=VAL`. @@ -76,5 +81,6 @@ In this case the option will only be set for filters which are instances of regi Example ``` --flist@timescale=100 -i plist1 -i plist2 -o live.mpd -``` +``` + This will set the timescale option on the playlists filters but not on the dasher filter. diff --git a/docs/Filters/core_logs.md b/docs/Filters/core_logs.md index 3d5e9ed0..99471997 100644 --- a/docs/Filters/core_logs.md +++ b/docs/Filters/core_logs.md @@ -3,12 +3,23 @@ # libgpac logs options: +
__-noprog__: disable progress messages +
+
__-quiet__: disable all messages, including errors -__-log-file__,__-lf__ (string): set output log file -__-log-clock__,__-lc__: log time in micro sec since start time of GPAC before each log line except for `app` tool -__-log-utc__,__-lu__: log UTC time in ms before each log line except for `app` tool -__-logs__ (string): set log tools and levels. +
+
+__-log-file__,__-lf__ (string): set output log file +
+
+__-log-clock__,__-lc__: log time in micro sec since start time of GPAC before each log line except for `app` tool +
+
+__-log-utc__,__-lu__: log UTC time in ms before each log line except for `app` tool +
+
+__-logs__ (string): set log tools and levels. You can independently log different tools involved in a session. log_args is formatted as a colon (':') separated list of `toolX[:toolZ]@levelX` @@ -57,8 +68,14 @@ The special keyword `strict` can be set to exit at first error. Example ``` -logs=all@info:dash@debug:ncl -``` +``` + This moves all log to info level, dash to debug level and disable color logs +
+
__-proglf__: use new line at each progress messages -__-log-dual__,__-ld__: output to both file and stderr +
+
+__-log-dual__,__-ld__: output to both file and stderr +
diff --git a/docs/Filters/core_options.md b/docs/Filters/core_options.md index ebfa074c..9ad909f6 100644 --- a/docs/Filters/core_options.md +++ b/docs/Filters/core_options.md @@ -3,16 +3,37 @@ # libgpac core options: +
__-noprog__: disable progress messages +
+
__-quiet__: disable all messages, including errors +
+
__-proglf__: use new line at each progress messages +
+
__-strict-error__,__-se__: exit after the first error is reported +
+
__-store-dir__ (string): set storage directory +
+
__-mod-dirs__ (string list): set additional module directories as a semi-colon `;` separated list +
+
__-js-dirs__ (string list): set javascript directories +
+
__-no-js-mods__ (string list): disable javascript module loading -__-ifce__ (string): set default multicast interface (default is ANY), either an IP address or a device name as listed by `gpac -h net`. Prefix '+' will force using IPv6 for dual interface -__-lang__ (string): set preferred language +
+
+__-ifce__ (string): set default multicast interface (default is ANY), either an IP address or a device name as listed by `gpac -h net`. Prefix '+' will force using IPv6 for dual interface +
+
+__-lang__ (string): set preferred language +
+
__-cfg__,__-opt__ (string): get or set configuration file value. The string parameter can be formatted as: - `section:key=val`: set the key to a new value @@ -21,24 +42,58 @@ - no argument: print the entire configuration file - `section`: print the given section - `section:key`: print the given `key` in `section` (section can be set to `*`)- `*:key`: print the given `key` in all sections +
+
__-no-save__: discard any changes made to the config file upon exit +
+
__-mod-reload__: unload / reload module shared libs when no longer used +
+
__-for-test__: disable all creation/modification dates and GPAC versions in files +
+
__-old-arch__: enable compatibility with pre-filters versions of GPAC +
+
__-ntp-shift__ (int): shift NTP clock by given amount in seconds +
+
__-bs-cache-size__ (int, default: __512__): cache size for bitstream read and write from file (0 disable cache, slower IOs) +
+
__-no-check__: disable compliance tests for inputs (ISOBMFF for now). This will likely result in random crashes +
+
__-unhandled-rejection__: dump unhandled promise rejections +
+
__-startup-file__ (string): startup file of compositor in GUI mode +
+
__-docs-dir__ (string): default documents directory (for GUI on iOS and Android) +
+
__-last-dir__ (string): last working directory (for GUI) +
+
__-no-poll__: disable poll and use select for socket groups +
+
__-no-tls-rcfg__: disable automatic TCP to TLS reconfiguration +
+
__-no-fd__: use buffered IO instead of file descriptor for read/write - this can speed up operations on small files +
+
__-no-mx__: disable all mutexes, threads and semaphores (do not use if unsure about threading used) +
+
__-xml-max-csize__ (int, default: __100k__): maximum XML content or attribute size +
+
__-netcap__ (string): set packet capture and filtering rules formatted as [CFG][RULES]. Each `-netcap` argument will define a configuration [CFG] is an optional comma-separated list of: @@ -65,55 +120,118 @@ Example ``` -netcap=dst=dump.gpc -``` +``` + This will record packets to dump.gpc Example ``` -netcap=src=dump.gpc,id=NC1 -i session1.sdp:NCID=NC1 -i session2.sdp -``` +``` + This will read packets from dump.gpc only for session1.sdp and let session2.sdp use regular sockets Example ``` -netcap=[p=1234,s=100,n=20][r=200,s=500,o=10,v=FE] -``` +``` + This will use regular network interface and drop packets 100 to 119 on port 1234 and patch one random packet every 200 starting from packet 500, setting byte 10 to FE +
+
__-cache__ (string): cache directory location +
+
__-proxy__ (string): set HTTP proxy server address and port +
+
__-maxrate__ (int): set max HTTP download rate in bits per sec. 0 means unlimited +
+
__-no-cache__: disable HTTP caching +
+
__-offline-cache__: enable offline HTTP caching (no re-validation of existing resource in cache) -__-clean-cache__: indicate if HTTP cache should be clean upon launch/exit +
+
+__-clean-cache__: indicate if HTTP cache should be clean upon launch/exit +
+
__-cache-size__ (int, default: __100M__): specify cache size in bytes +
+
__-tcp-timeout__ (int, default: __5000__): time in milliseconds to wait for HTTP/RTSP connect before error +
+
__-req-timeout__ (int, default: __10000__): time in milliseconds to wait on HTTP/RTSP request before error (0 disables timeout) +
+
__-no-timeout__: ignore HTTP 1.1 timeout in keep-alive +
+
__-broken-cert__: enable accepting broken SSL certificates +
+
__-user-agent__,__-ua__ (string): set user agent name for HTTP/RTSP +
+
__-user-profileid__ (string): set user profile ID (through __X-UserProfileID__ entity header) in HTTP requests +
+
__-user-profile__ (string): set user profile filename. Content of file is appended as body to HTTP HEAD/GET requests, associated Mime is __text/xml__ +
+
__-query-string__ (string): insert query string (without `?`) to URL on requests +
+
__-dm-threads__: force using threads for async download requests rather than session scheduler +
+
__-cte-rate-wnd__ (int, default: __20__): set window analysis length in milliseconds for chunk-transfer encoding rate estimation +
+
__-cred__ (string): path to 128 bits key for credential storage +
+
__-no-h2__: disable HTTP2 +
+
__-no-h2c__: disable HTTP2 upgrade (i.e. over non-TLS) +
+
__-h2-copy__: enable intermediate copy of data in nghttp2 (default is disabled but may report as broken frames in wireshark) +
+
__-curl__: use CURL instead of GPAC HTTP stack +
+
__-no-h3__: disable HTTP3 (CURL only) +
+
__-dbg-edges__: log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx) +
+
__-full-link__: throw error if any PID in the filter graph cannot be linked +
+
__-no-dynf__: disable dynamically loaded filters +
+
__-no-block__ (Enum, default: __no__): disable blocking mode of filters - no: enable blocking mode - fanout: disable blocking on fan-out, unblocking the PID as soon as one of its destinations requires a packet - all: disable blocking +
+
__-no-reg__: disable regulation (no sleep) in session +
+
__-no-reassign__: disable source filter reassignment in PID graph resolution +
+
__-sched__ (Enum, default: __free__): set scheduler mode - free: lock-free queues except for task list (default) @@ -121,48 +239,125 @@ This will use regular network interface and drop packets 100 to 119 on port 1234 - freex: lock-free queues including for task lists (experimental) - flock: mutexes for queues even when no thread (debug mode) - direct: no threads and direct dispatch of tasks whenever possible (debug mode) +
+
__-max-chain__ (int, default: __6__): set maximum chain length when resolving filter links. Default value covers for _[ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]_. Filter chains loaded for adaptation (e.g. pixel format change) are loaded after the link resolution. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually +
+
__-max-sleep__ (int, default: __50__): set maximum sleep time slot in milliseconds when regulation is enabled +
+
__-step-link__: load filters one by one when solvink a link instead of loading all filters for the solved path +
+
__-threads__ (int): set N extra thread for the session. -1 means use all available cores +
+
__-no-probe__: disable data probing on sources and relies on extension (faster load but more error-prone) +
+
__-no-argchk__: disable tracking of argument usage (all arguments will be considered as used) +
+
__-blacklist__ (string): blacklist the filters listed in the given string (comma-separated list). If first character is '-', this is a whitelist, i.e. only filters listed in the given string will be allowed +
+
__-no-graph-cache__: disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (lower memory usage but slower) +
+
__-no-reservoir__: disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more +
+
__-buffer-gen__ (int, default: __1000__): default buffer size in microseconds for generic pids +
+
__-buffer-dec__ (int, default: __1000000__): default buffer size in microseconds for decoder input pids +
+
__-buffer-units__ (int, default: __1__): default buffer size in frames when timing is not available +
+
__-gl-bits-comp__ (int, default: __8__): number of bits per color component in OpenGL +
+
__-gl-bits-depth__ (int, default: __16__): number of bits for depth buffer in OpenGL +
+
__-gl-doublebuf__: enable OpenGL double buffering +
+
__-glfbo-txid__ (int): set output texture ID when using `glfbo` output. The OpenGL context shall be initialized and gf_term_process shall be called with the OpenGL context active +
+
__-video-output__ (string): indicate the name of the video output module to use (see `gpac -h modules`). The reserved name `glfbo` is used in player mode to draw in the OpenGL texture identified by [glfbo-txid](#glfbo-txid). In this mode, the application is responsible for sending event to the compositor +
+
__-audio-output__ (string): indicate the name of the audio output module to use +
+
__-font-reader__ (string): indicate name of font reader module +
+
__-font-dirs__ (string): indicate comma-separated list of directories to scan for fonts +
+
__-rescan-fonts__: indicate the font directory must be rescanned +
+
__-wait-fonts__: wait for SVG fonts to be loaded before displaying frames +
+
__-webvtt-hours__: force writing hour when serializing WebVTT +
+
__-charset__ (string): set charset when not recognized from input. Possible values are: - utf8: force UTF-8 - utf16: force UTF-16 little endian - utf16be: force UTF-16 big endian - other: attempt to parse anyway +
+
__-rmt__: enable profiling through [Remotery](https://github.com/Celtoys/Remotery). A copy of Remotery visualizer is in gpac/share/vis, usually installed in _/usr/share/gpac/vis_ or _Program Files/GPAC/vis_ +
+
__-rmt-port__ (int, default: __17815__): set remotery port +
+
__-rmt-reuse__: allow remotery to reuse port +
+
__-rmt-localhost__: make remotery only accepts localhost connection +
+
__-rmt-sleep__ (int, default: __10__): set remotery sleep (ms) between server updates +
+
__-rmt-nmsg__ (int, default: __10__): set remotery number of messages per update +
+
__-rmt-qsize__ (int, default: __131072__): set remotery message queue size in bytes +
+
__-rmt-log__: redirect logs to remotery (experimental, usually not well handled by browser) +
+
__-rmt-ogl__: make remotery sample opengl calls +
+
__-m2ts-vvc-old__: hack for old TS streams using 0x32 for VVC instead of 0x33 +
+
__-piff-force-subsamples__: hack for PIFF PSEC files generated by 0.9.0 and 1.0 MP4Box with wrong subsample_count inserted for audio +
+
__-vvdec-annexb__: hack for old vvdec+libavcodec supporting only annexB format +
+
__-heif-hevc-urn__: use HEVC URN for alpha and depth in HEIF instead of MPEG-B URN (HEIF first edition) +
+
__-boxdir__ (string): use box definitions in the given directory for XML dump +
diff --git a/docs/Filters/cryptin.md b/docs/Filters/cryptin.md index df8ef72b..76121366 100644 --- a/docs/Filters/cryptin.md +++ b/docs/Filters/cryptin.md @@ -14,8 +14,12 @@ The filter accepts URL with scheme `gcryp://URL`, where `URL` is the URL to decr The filter can process http(s) and local file key URLs (setup through HLS manifest), and expects a full key (16 bytes) as result of resource fetching. -# Options +# Options {.no-collapse} -__src__ (cstr): location of source file +
+__src__ (cstr): location of source file +
+
__fullfile__ (bool, default: _false_): reassemble full file before decryption +
diff --git a/docs/Filters/cryptout.md b/docs/Filters/cryptout.md index 01a22fd2..95f161c4 100644 --- a/docs/Filters/cryptout.md +++ b/docs/Filters/cryptout.md @@ -12,8 +12,12 @@ The filter is automatically loaded by the DASH/HLS multiplexer and should not be The filter accepts URL with scheme `gcryp://URL`, where `URL` is the URL to encrypt. -# Options +# Options {.no-collapse} -__dst__ (cstr): location of source file +
+__dst__ (cstr): location of source file +
+
__fullfile__ (bool, default: _false_): reassemble full file before decryption +
diff --git a/docs/Filters/dasher.md b/docs/Filters/dasher.md index aa60983a..50f1e371 100644 --- a/docs/Filters/dasher.md +++ b/docs/Filters/dasher.md @@ -22,19 +22,22 @@ If you need per-frame real-time regulation on non-real-time inputs, insert a [re Example ``` gpac -i file.mp4 reframer:rt=on -o live.mpd:dmode=dynamic -``` +``` + ## Template strings The segmenter uses templates to derive output file names, regardless of the DASH mode (even when templates are not used). The default one is `$File$_dash` for ondemand and single file modes, and `$File$_$Number$` for separate segment files Example ``` template=Great_$File$_$Width$_$Number$ -``` +``` + If input is `foo.mp4` with `640x360` video resolution, this will resolve in `Great_foo_640_$Number$` for the DASH template. Example ``` template=Great_$File$_$Width$ -``` +``` + If input is `foo.mp4` with `640x360` video resolution, this will resolve in `Great_foo_640.mp4` for onDemand case. Standard DASH replacement strings: @@ -91,59 +94,70 @@ _Note: If multiple streams in source, only the first stream will have an AS ID a Example ``` gpac -i test.mp4:#Bitrate=1M -o test.mpd -``` +``` + This will force declaring a bitrate of 1M for the representation, regardless of actual input bitrate. Example ``` gpac -i muxav.mp4 -o test.mpd -``` +``` + This will create un-multiplexed DASH segments. Example ``` gpac -i muxav.mp4:#Representation=1 -o test.mpd -``` +``` + This will create multiplexed DASH segments. Example ``` gpac -i m1.mp4 -i m2.mp4:#Period=Yep -o test.mpd -``` +``` + This will put src `m1.mp4` in first period, `m2.mp4` in second period. Example ``` gpac -i m1.mp4:#BUrl=http://foo/bar -o test.mpd -``` +``` + This will assign a baseURL to src `m1.mp4`. Example ``` gpac -i m1.mp4:#ASCDesc=<ElemName val="attval">text</ElemName> -o test.mpd -``` +``` + This will assign the specified XML descriptor to the adaptation set. _Note: this can be used to inject most DASH descriptors not natively handled by the segmenter._ The segmenter handles the XML descriptor as a string and does not attempt to validate it. Descriptors, as well as some segmenter filter arguments, are string lists (comma-separated by default), so that multiple descriptors can be added: Example ``` gpac -i m1.mp4:#RDesc=<Elem attribute="1"/>,<Elem2>text</Elem2> -o test.mpd -``` +``` + This will insert two descriptors in the representation(s) of `m1.mp4`. Example ``` gpac -i video.mp4:#Template=foo$Number$ -i audio.mp4:#Template=bar$Number$ -o test.mpd -``` +``` + This will assign different templates to the audio and video sources. Example ``` gpac -i null:#xlink=http://foo/bar.xml:#PDur=4 -i m.mp4:#PStart=-1 -o test.mpd -``` +``` + This will insert an create an MPD with first a remote period then a regular one. Example ``` gpac -i null:#xlink=http://foo/bar.xml:#PStart=6 -i m.mp4 -o test.mpd -``` +``` + This will create an MPD with first a regular period, dashing only 6s of content, then a remote one. Example ``` gpac -i v1:#SRD=0x0x1280x360:#SRDRef=1280x720 -i v2:#SRD=0x360x1280x360 -o test.mpd -``` +``` + This will layout the `v2` below `v1` using a global SRD size of 1280x720. The segmenter will create multiplexing filter chains for each representation and will reassign PID IDs so that each media component (video, audio, ...) in an adaptation set has the same ID. @@ -155,7 +169,8 @@ When HLS mode is enabled, the segment [template](#template) is relative to the v Example ``` gpac -i av.mp4:#HLSPL=$Type$/index.m3u8 -o dash/live.m3u8:dual:template='$Number$' -``` +``` + This will put video segments and playlist in `dash/video/` and audio segments and playlist in `dash/audio/` ## Segmentation @@ -186,7 +201,8 @@ For regular segmentation, you should enable segment regulation [sreg](#sreg) if Example ``` gpac -i source.mp4 -o live.mpd:segdur=2:profile=live:dmode=dynamic:sreg -``` +``` + For low latency segmentation with fMP4, you will need to specify the following options: @@ -201,36 +217,42 @@ If your sources are not real-time, insert a reframer filter with real-time regul Example ``` gpac -i source.mp4 reframer:rt=on -o live.mpd:segdur=2:cdur=0.2:asto=1.8:profile=live:dmode=dynamic -``` +``` + This will create DASH segments of 2 seconds made of fragments of 200 ms and indicate to the client that requests can be made 1.8 seconds earlier than segment complete availability on server. Example ``` gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=br:dmode=dynamic -``` +``` + This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts using byte ranges in the final segment. Example ``` gpac -i source.mp4 reframer:rt=on -o live.m3u8:segdur=2:cdur=0.2:llhls=sf:dmode=dynamic -``` +``` + This will create DASH segments of 2 seconds made of fragments of 200 ms and produce HLS low latency parts using dedicated files. You can combine LL-HLS and DASH-LL generation: Example ``` gpac -i source.mp4 reframer:rt=on -o live.mpd:dual:segdur=2:cdur=0.2:asto=1.8:llhls=br:profile=live:dmode=dynamic -``` +``` + For DASH, the filter will use the local clock for UTC anchor points in DASH. The filter can fetch and signal clock in other ways using [utcs](#utcs). Example ``` [opts]:utcs=inband -``` +``` + This will use the local clock and insert in the MPD a UTCTiming descriptor containing the local clock. Example ``` [opts]::utcs=http://time.akamai.com[::opts] -``` +``` + This will fetch time from `http://time.akamai.com`, use it as the UTC reference for segment generation and insert in the MPD a UTCTiming descriptor containing the time server URL. _Note: if not set as a global option using `--utcs=`, you must escape the url using double `::` or use other separators._ @@ -260,7 +282,8 @@ This feature is typically combined with a list of files as input: Example ``` gpac -i list.m3u:sigcues -o res/live.mpd -``` +``` + This will load the `flist` filter in cue mode, generating continuous timelines from the sources and injecting a `CueStart` property at each new file. If the [cues](#cues) option equals `none`, the `DashCue` property of input PIDs will be ignored. @@ -287,22 +310,26 @@ The manifest generation-only mode supports both MPD and HLS generation. Example ``` gpac -i ondemand_src.mp4 -o dash.mpd:sigfrag:profile=onDemand -``` +``` + This will generate a DASH manifest for onDemand Profile based on the input file. Example ``` gpac -i ondemand_src.mp4 -o dash.m3u8:sigfrag -``` +``` + This will generate a HLS manifest based on the input file. Example ``` gpac -i seglist.txt -o dash.mpd:sigfrag -``` +``` + This will generate a DASH manifest in Main Profile based on the input files. Example ``` gpac -i seglist.txt:Template=$XInit=init$$q1/$Number$ -o dash.mpd:sigfrag:profile=live -``` +``` + This will generate a DASH manifest in live Profile based on the input files. The input file will contain `init.mp4`, `q1/1.m4s`, `q1/2.m4s`... ## Cue Generation only mode @@ -323,12 +350,14 @@ This mode can be used to pre-segment the streams for later processing that must Example ``` gpac -i source.mp4 dasher:gencues cecrypt:cfile=roll_seg.xml -o live.mpd -``` +``` + This will allow the encrypter to locate dash boundaries and roll keys at segment boundaries. Example ``` gpac -i s1.mp4 -i s2.mp4:#CryptInfo=clear:#Period=3 -i s3.mp4:#Period=3 dasher:gencues cecrypt:cfile=roll_period.xml -o live.mpd -``` +``` + If the DRM file uses `keyRoll=period`, this will generate: - first period crypted with one key @@ -342,7 +371,8 @@ This is typically used to redirect segments to a given destination regardless of Example ``` gpac -i SRC -o null:ext=mpd:tpl_force --template=pipe://mypipe -``` +``` + This will trash the manifest and open `mypipe` as destination for the muxer result. __Warning: Options for segment destination cannot be set through the [template](#template), global options must be used.__ @@ -367,22 +397,26 @@ To avoid this behaviour, the [sflush](#sflush) option should be set to `end` or Example ``` gpac -i SRC -o dash.mpd:segdur=2:state=CTX && gpac -i SRC -o dash.mpd:segdur=2:state=CTX -``` +``` + This will generate all dash segments for `SRC` (last one possibly shorter) and create a new period at end of input. Example ``` gpac -i SRC -o dash.mpd:segdur=2:state=CTX:loop && gpac -i SRC -o dash.mpd:segdur=2:state=CTX:loop -``` +``` + This will generate all dash segments for `SRC` and restart `SRC` to fill-up last segment. Example ``` gpac -i SRC -o dash.mpd:segdur=2:state=CTX:sflush=end && gpac -i SRC -o dash.mpd:segdur=2:state=CTX:sflush=end -``` +``` + This will generate all dash segments for `SRC` without looping/closing the period at end of input. Timestamps in the second call will be rewritten to be contiguous with timestamp at end of first call. Example ``` gpac -i SRC1 -o dash.mpd:segdur=2:state=CTX:sflush=end:keep_ts && gpac -i SRC2 -o dash.mpd:segdur=2:state=CTX:sflush=end:keep_ts -``` +``` + This will generate all dash segments for `SRC1` without looping/closing the period at end of input, then for `SRC2`. Timestamps of the sources will not be rewritten. _Note: The default behaviour of MP4Box `-dash-ctx` option is to set the (-loop)[] to true._ @@ -392,7 +426,8 @@ When loaded implicitly during link resolution, the dasher will only link its out Example ``` gpac -i SRC -o URL1:OPTS1 -o URL2:OPTS1 -``` +``` + This will create one dasher (with options OPTS1) for the URL1 and one dasher (with options OPTS1) for URL2. This allows dashing to multiple outputs with different formats, dash durations, etc. @@ -401,7 +436,8 @@ In order to do this, the filter MUST be explicitly loaded and all options relate Example ``` gpac -i SRC dasher:cmfc:segdur=2 -o URL1 -o URL2 -``` +``` + This will create a single dasher whose outputs (manifests and segments) will be redirected to the given URLs. When explicitly loading the filter, the [dual](#dual) option will be disabled unless [mname](#mname) is set to the alternate output name. @@ -435,30 +471,53 @@ The segmenter adds the following properties to the output PIDs: -# Options +# Options {.no-collapse} -__segdur__ (frac, default: _0/0_): target segment duration in seconds. A value less than or equal to 0 defaults to 1.0 second -__tpl__ (bool, default: _true_): use template mode (multiple segment, template URLs) -__stl__ (bool, default: _false_): use segment timeline (ignored in on_demand mode) -__dmode__ (enum, default: _static_, updatable): dash content mode +
+__segdur__ (frac, default: _0/0_): target segment duration in seconds. A value less than or equal to 0 defaults to 1.0 second +
+
+__tpl__ (bool, default: _true_): use template mode (multiple segment, template URLs) +
+
+__stl__ (bool, default: _false_): use segment timeline (ignored in on_demand mode) +
+
+__dmode__ (enum, default: _static_, updatable): dash content mode - static: static content - dynamic: live generation - dynlast: last call for live, will turn the MPD into static - dynauto: live generation and move to static manifest upon end of stream +
+
__sseg__ (bool, default: _false_): single segment is used +
+
__sfile__ (bool, default: _false_): use a single file for all segments (default in on_demand) +
+
__align__ (bool, default: _true_): enable segment time alignment between representations -__sap__ (bool, default: _true_): enable splitting segments at SAP boundaries +
+
+__sap__ (bool, default: _true_): enable splitting segments at SAP boundaries +
+
__mix_codecs__ (bool, default: _false_): enable mixing different codecs in an adaptation set +
+
__ntp__ (enum, default: _rem_): insert/override NTP clock at the beginning of each segment - rem: removes NTP from all input packets - yes: inserts NTP at each segment start - keep: leaves input packet NTP untouched +
+
__no_sar__ (bool, default: _false_): do not check for identical sample aspect ratio for adaptation sets +
+
__bs_switch__ (enum, default: _def_): bitstream switching mode (single init segment) - def: resolves to off for onDemand and inband for live @@ -469,11 +528,19 @@ The segmenter adds the following properties to the output PIDs: - pps: moves PPS and APS inband, keep VPS,SPS and DCI out of band (used for VVC RPR) - force: enables it even if only one representation - multi: uses multiple stsd entries in ISOBMFF - -__template__ (str): template string to use to generate segment name -__segext__ (str): file extension to use for segments -__initext__ (str): file extension to use for the init segment -__muxtype__ (enum, default: _auto_): muxtype to use for the segments +
+ +
+__template__ (str): template string to use to generate segment name +
+
+__segext__ (str): file extension to use for segments +
+
+__initext__ (str): file extension to use for the init segment +
+
+__muxtype__ (enum, default: _auto_): muxtype to use for the segments - mp4: uses ISOBMFF format - ts: uses MPEG-2 TS format @@ -482,10 +549,16 @@ The segmenter adds the following properties to the output PIDs: - ogg: uses OGG format - raw: uses raw media format (disables multiplexed representations) - auto: guess format based on extension, default to mp4 if no extension +
+
__rawsub__ (bool, default: _no_): use raw subtitle format instead of encapsulating in container +
+
__asto__ (dbl, default: _0_): availabilityStartTimeOffset to use in seconds. A negative value simply increases the AST, a positive value sets the ASToffset to representations -__profile__ (enum, default: _auto_): target DASH profile. This will set default option values to ensure conformance to the desired profile. For MPEG-2 TS, only main and live are used, others default to main +
+
+__profile__ (enum, default: _auto_): target DASH profile. This will set default option values to ensure conformance to the desired profile. For MPEG-2 TS, only main and live are used, others default to main - auto: turns profile to live for dynamic and full for non-dynamic - live: DASH live profile, using segment template @@ -496,14 +569,20 @@ The segmenter adds the following properties to the output PIDs: - dashavc264.live: DASH-IF live profile - dashavc264.onDemand: DASH-IF onDemand profile - dashif.ll: DASH IF low-latency profile (set UTC server to time.akamai.com if none set) +
+
__profX__ (str): list of profile extensions, as used by DASH-IF and DVB. The string will be colon-concatenated with the profile used. If starting with `+`, the profile string by default is erased and `+` is skipped +
+
__cp__ (enum, default: _set_): content protection element location - set: in adaptation set element - rep: in representation element - both: in both adaptation set and representation elements +
+
__pssh__ (enum, default: _v_): storage mode for PSSH box - f: stores in movie fragment only @@ -512,123 +591,246 @@ The segmenter adds the following properties to the output PIDs: - mf: stores in mpd and movie fragment - mv: stores in mpd and movie - n: discard pssh from mpd and segments - -__buf__ (sint, default: _-100_): min buffer duration in ms. negative value means percent of segment duration (e.g. -150 = 1.5*seg_dur) -__spd__ (sint, default: _0_): suggested presentation delay in ms +
+ +
+__buf__ (sint, default: _-100_): min buffer duration in ms. negative value means percent of segment duration (e.g. -150 = 1.5*seg_dur) +
+
+__spd__ (sint, default: _0_): suggested presentation delay in ms +
+
__timescale__ (sint, default: _0_): set timescale for timeline and segment list/template. A value of 0 picks up the first timescale of the first stream in an adaptation set. A negative value forces using stream timescales for each timed element (multiplication of segment list/template/timelines). A positive value enforces the MPD timescale -__check_dur__ (bool, default: _true_): check duration of sources in period, trying to have roughly equal duration. Enforced whenever period start times are used +
+
+__check_dur__ (bool, default: _true_): check duration of sources in period, trying to have roughly equal duration. Enforced whenever period start times are used +
+
__skip_seg__ (bool, default: _false_): increment segment number whenever an empty segment would be produced - NOT DASH COMPLIANT -__title__ (str): MPD title -__source__ (str): MPD Source -__info__ (str): MPD info url -__cprt__ (str): MPD copyright string -__lang__ (str): language of MPD Info -__location__ (strl): set MPD locations to given URL +
+
+__title__ (str): MPD title +
+
+__source__ (str): MPD Source +
+
+__info__ (str): MPD info url +
+
+__cprt__ (str): MPD copyright string +
+
+__lang__ (str): language of MPD Info +
+
+__location__ (strl): set MPD locations to given URL +
+
__base__ (strl): set base URLs of MPD +
+
__refresh__ (dbl, default: _0_): refresh rate for dynamic manifests, in seconds (a negative value sets the MPD duration, value 0 uses dash duration) -__tsb__ (dbl, default: _30_): time-shift buffer depth in seconds (a negative value means infinity) -__keep_segs__ (bool, default: _false_): do not delete segments no longer in time-shift buffer +
+
+__tsb__ (dbl, default: _30_): time-shift buffer depth in seconds (a negative value means infinity) +
+
+__keep_segs__ (bool, default: _false_): do not delete segments no longer in time-shift buffer +
+
__ast__ (str): set start date (as xs:date, e.g. YYYY-MM-DDTHH:MM:SSZ) for live mode. Default is now. !! Do not use with multiple periods, nor when DASH duration is not a multiple of GOP size !! +
+
__state__ (str): path to file used to store/reload state info when simulating live. This is stored as a valid MPD with GPAC XML extensions +
+
__keep_ts__ (bool, default: _false_): do not shift timestamp when reloading a context +
+
__loop__ (bool, default: _false_): loop sources when dashing with subdur and state. If not set, a new period is created once the sources are over +
+
__subdur__ (dbl, default: _0_): maximum duration of the input file to be segmented. This does not change the segment duration, segmentation stops once segments produced exceeded the duration +
+
__split__ (bool, default: _true_): enable cloning samples for text/metadata/scene description streams, marking further clones as redundant +
+
__hlsc__ (bool, default: _false_): insert clock reference in variant playlist in live HLS +
+
__cues__ (str): set cue file +
+
__strict_cues__ (bool, default: _false_): strict mode for cues, complains if splitting is not on SAP type 1/2/3 or if unused cue is found +
+
__strict_sap__ (enum, default: _off_): strict mode for sap - off: ignore SAP types for PID other than video, enforcing `AdaptationSet@startsWithSAP=1` - sig: same as [off](#off) but keep `AdaptationSet@startsWithSAP` to the true SAP value - on: warn if any PID uses SAP 3 or 4 and switch to FULL profile - intra: ignore SAP types greater than 3 on all media types +
+
__subs_sidx__ (sint, default: _-1_): number of subsegments per sidx. Negative value disables sidx. Only used to inherit sidx option of destination +
+
__cmpd__ (bool, default: _false_): skip line feed and spaces in MPD XML for compactness +
+
__styp__ (str): indicate the 4CC to use for styp boxes when using ISOBMFF output +
+
__dual__ (bool): indicate to produce both MPD and M3U files +
+
__sigfrag__ (bool): use manifest generation only mode +
+
__sbound__ (enum, default: _out_): indicate how the theoretical segment start `TSS (= segment_number * duration)` should be handled - out: segment split as soon as `TSS` is exceeded (`TSS` <= segment_start) - closest: segment split at closest SAP to theoretical bound - in: `TSS` is always in segment (`TSS` >= segment_start) +
+
__reschedule__ (bool, default: _false_): reschedule sources with no period ID assigned once done (dynamic mode only) +
+
__sreg__ (bool, default: _false_): regulate the session - when using subdur and context, only generate segments from the past up to live edge - otherwise in dynamic mode without context, do not generate segments ahead of time +
+
__scope_deps__ (bool, default: _true_): scope PID dependencies to be within source. If disabled, PID dependencies will be checked across all input PIDs regardless of their sources +
+
__utcs__ (str): URL to use as time server / UTCTiming source. Special value `inband` enables inband UTC (same as publishTime), special prefix `xsd@` uses xsDateTime schemeURI rather than ISO +
+
__sflush__ (enum, default: _off_): segment flush mode - see filter help: - off: no specific actions - single: force generating a single segment for each input - end: skip loop detection and clamp duration adjustment at end of input, used for state mode +
+
__last_seg_merge__ (bool, default: _false_): force merging last segment if less than half the target duration +
+
__mha_compat__ (enum, default: _no_): adaptation set generation mode for compatible MPEG-H Audio profile - no: only generate the adaptation set for the main profile - comp: only generate the adaptation sets for all compatible profiles - all: generate the adaptation set for the main profile and all compatible profiles +
+
__mname__ (str): output manifest name for ATSC3 multiplexing (using 'm3u8' only toggles HLS generation) +
+
__llhls__ (enum, default: _off_): HLS low latency type - off: do not use LL-HLS - br: use LL-HLS with byte-range for segment parts, pointing to full segment (DASH-LL compatible) - sf: use separate files for segment parts (post-fixed .1, .2 etc.) - brsf: generate two sets of manifest, one for byte-range and one for files (`_IF` added before extension of manifest) +
+
__hlsdrm__ (str): cryp file info for HLS full segment encryption +
+
__hlsx__ (strl): list of string to append to master HLS header before variants with `['#foo','#bar=val']` added as `#foo \n #bar=val` +
+
__hlsiv__ (bool, default: _true_): inject IV in variant HLS playlist`` +
+
__ll_preload_hint__ (bool, default: _true_): inject preload hint for LL-HLS +
+
__ll_rend_rep__ (bool, default: _true_): inject rendition reports for LL-HLS +
+
__ll_part_hb__ (dbl, default: _-1_): user-defined part hold-back for LLHLS, negative value means 3 times max part duration in session +
+
__ckurl__ (str): set the ClearKey URL common to all encrypted streams (overriden by `CKUrl` pid property) +
+
__hls_absu__ (enum, default: _no_): use absolute url in HLS generation using first URL in [base]() - no: do not use absolute URL - var: use absolute URL only in variant playlists - mas: use absolute URL only in master playlist - both: use absolute URL everywhere +
+
__hls_ap__ (bool, default: _false_): use audio as primary media instead of video when generating playlists +
+
__seg_sync__ (enum, default: _auto_): control how waiting on last packet P of fragment/segment to be written impacts segment injection in manifest - no: do not wait for P - yes: wait for P - auto: wait for P if HLS is used +
+
__cmaf__ (enum, default: _no_): use cmaf guidelines - no: CMAF not enforced - cmfc: use CMAF `cmfc` guidelines - cmf2: use CMAF `cmf2` guidelines +
+
__pswitch__ (enum, default: _single_): period switch control mode - single: change period if PID configuration changes - force: force period switch at each PID reconfiguration instead of absorbing PID reconfiguration (for splicing or add insertion not using periodID) - stsd: change period if PID configuration changes unless new configuration was advertised in initial config +
+
__chain__ (str): URL of next MPD for regular chaining +
+
__chain_fbk__ (str): URL of fallback MPD +
+
__gencues__ (bool, default: _false_): only insert segment boundaries and do not generate manifests +
+
__force_init__ (bool, default: _false_): force init segment creation in bitstream switching mode +
+
__keep_src__ (bool, default: _false_): keep source URLs in manifest generation mode +
+
__gxns__ (bool, default: _false_): insert some gpac extensions in manifest (for now, only tfdt of first segment) +
+
__dkid__ (enum, default: _auto_): control injection of default KID in MPD - off: default KID not injected - on: default KID always injected - auto: default KID only injected if no key roll is detected (as per DASH-IF guidelines) +
+
__tpl_force__ (bool, default: _false_): use template string as is without trying to add extension or solve conflicts in names +
+
__ttml_agg__ (bool, default: _false_): force aggregation of TTML samples of a DASH segment into a single sample +
diff --git a/docs/Filters/dashin.md b/docs/Filters/dashin.md index 2d36fc1a..3920daf9 100644 --- a/docs/Filters/dashin.md +++ b/docs/Filters/dashin.md @@ -18,14 +18,16 @@ The default behavior is to perform adaptation according to [algo](#algo), but th Example ``` gpac -i MANIFEST_URL:algo=none:start_with=max_bw -o dest.mp4 -``` +``` + - run with no adaptation, fetching all qualities. Example ``` gpac -i MANIFEST_URL:split_as -o dst=$File$.mp4 -``` +``` + # File mode @@ -39,7 +41,8 @@ To expose a live DASH session to route: Example ``` gpac -i MANIFEST_URL dashin:forward=file -o route://225.0.0.1:8000/ -``` +``` + If the source has dependent media streams (scalability) and all qualities and initialization segments need to be forwarded, add [split_as](#split_as). @@ -52,13 +55,15 @@ This mode can be used to process media data and regenerate the same manifest/seg Example ``` gpac -i MANIFEST_URL:forward=mani cecrypt:cfile=DRM.xml -o encrypted/live.mpd:pssh=mv -``` +``` + This will encrypt an existing DASH session, inject PSSH in manifest and segments. Example ``` gpac -i MANIFEST_URL:forward=segb cecrypt:cfile=DRM.xml -o encrypted/live.m3u8 -``` +``` + This will encrypt an existing DASH session and republish it as HLS, using same segment names and boundaries. This mode will force [noseek](#noseek)=`true` to ensure the first segment fetched is complete, and [split_as](#split_as)=`true` to fetch all qualities. @@ -96,20 +101,25 @@ Each output PID will have the following properties assigned: When the [dasher](dasher) is used together with this mode, this will force all generated segments to have the same name, duration and fragmentation properties as the input ones. It is therefore not recommended for sessions stored/generated on local storage to generate the output in the same directory. -# Options +# Options {.no-collapse} +
__auto_switch__ (sint, default: _0_): switch quality every N segments - positive: go to higher quality or loop to lowest - negative: go to lower quality or loop to highest - 0: disabled +
+
__segstore__ (enum, default: _mem_): enable file caching - mem: all files are stored in memory, no disk IO - disk: files are stored to disk but discarded once played - cache: all files are stored to disk and kept +
+
__algo__ (str, default: _gbuf_, Enum: none|grate|gbuf|bba0|bolaf|bolab|bolau|bolao|JS): adaptation algorithm to use - none: no adaptation logic @@ -121,29 +131,51 @@ When the [dasher](dasher) is used together with this mode, this will force all g - bolau: BOLA-U - bolao: BOLA-O - JS: use file JS (either with specified path or in $GSHARE/scripts/) for algo (.js extension may be omitted) +
-__start_with__ (enum, default: _max_bw_): initial selection criteria +
+__start_with__ (enum, default: _max_bw_): initial selection criteria - min_q: start with lowest quality - max_q: start with highest quality - min_bw: start with lowest bitrate - max_bw: start with highest bitrate; if tiles are used, all low priority tiles will have the lower (below max) bandwidth selected - max_bw_tiles: start with highest bitrate; if tiles are used, all low priority tiles will have their lowest bandwidth selected +
-__max_res__ (bool, default: _true_): use max media resolution to configure display +
+__max_res__ (bool, default: _true_): use max media resolution to configure display +
+
__abort__ (bool, default: _false_): allow abort during a segment download -__use_bmin__ (enum, default: _auto_): playout buffer handling +
+
+__use_bmin__ (enum, default: _auto_): playout buffer handling - no: use default player settings - auto: notify player of segment duration if not low latency - mpd: use the indicated min buffer time of the MPD +
+
__shift_utc__ (sint, default: _0_): shift DASH UTC clock in ms +
+
__spd__ (sint, default: _-I_): suggested presentation delay in ms +
+
__mcast_shift__ (sint, default: _0_): shift requests time by given ms for multicast sources +
+
__server_utc__ (bool, default: _yes_): use `ServerUTC` or `Date` HTTP headers instead of local UTC +
+
__screen_res__ (bool, default: _yes_): use screen resolution in selection phase +
+
__init_timeshift__ (sint, default: _0_): set initial timeshift in ms (if >0) or in per-cent of timeshift buffer (if <0) +
+
__tile_mode__ (enum, default: _none_): tile adaptation mode - none: bitrate is shared equally across all tiles @@ -155,42 +187,85 @@ When the [dasher](dasher) is used together with this mode, this will force all g - mcols: bitrate decreased for left and right columns only, same rate for each tile on the columns - center: bitrate decreased for all tiles on the edge of the picture - edges: bitrate decreased for all tiles on the center of the picture +
+
__tiles_rate__ (uint, default: _100_): indicate the amount of bandwidth to use at each quality level. The rate is recursively applied at each level, e.g. if 50%, Level1 gets 50%, level2 gets 25%, ... If 100, automatic rate allocation will be done by maximizing the quality in order of priority. If 0, bitstream will not be smoothed across tiles/qualities, and concurrency may happen between different media +
+
__delay40X__ (uint, default: _500_): delay in milliseconds to wait between two 40X on the same segment +
+
__exp_threshold__ (uint, default: _100_): delay in milliseconds to wait after the segment AvailabilityEndDate before considering the segment lost +
+
__switch_count__ (uint, default: _1_): indicate how many segments the client shall wait before switching up bandwidth. If 0, switch will happen as soon as the bandwidth is enough, but this is more prone to network variations +
+
__aggressive__ (bool, default: _no_): if enabled, switching algo targets the closest bandwidth fitting the available download rate. If no, switching algo targets the lowest bitrate representation that is above the currently played (e.g. does not try to switch to max bandwidth) +
+
__debug_as__ (uintl): play only the adaptation sets indicated by their indices (0-based) in the MPD +
+
__speedadapt__ (bool, default: _no_): enable adaptation based on playback speed +
+
__noxlink__ (bool, default: _no_): disable xlink if period has both xlink and adaptation sets +
+
__query__ (str): set query string (without initial '?') to append to xlink of periods +
+
__split_as__ (bool, default: _no_): separate all qualities into different adaptation sets and stream all qualities. Dependent representations (scalable) are treated as independent +
+
__noseek__ (bool, default: _no_): disable seeking of initial segment(s) in dynamic mode (useful when UTC clocks do not match) +
+
__bwcheck__ (uint, default: _5_): minimum time in milliseconds between two bandwidth checks when allowing segment download abort +
+
__lowlat__ (enum, default: _early_): segment scheduling policy in low latency mode - no: disable low latency - strict: strict respect of AST offset in low latency - early: allow fetching segments earlier than their AST in low latency when input PID is empty +
+
__forward__ (enum, default: _none_): segment forwarding mode - none: regular DASH read - file: do not demultiplex files and forward them as file PIDs (imply `segstore=mem`) - segb: turn on [split_as](#split_as), segment and fragment bounds signaling (`sigfrag`) in sources and DASH cue insertion - mani: same as `segb` and also forward manifests +
+
__fmodefwd__ (bool, default: _yes_): forward packet rather than copy them in `file` forward mode. Packet copy might improve performances in low latency mode +
+
__skip_lqt__ (bool, default: _no_): disable decoding of tiles with highest degradation hints (not visible, not gazed at) for debug purposes +
+
__llhls_merge__ (bool, default: _yes_): merge LL-HLS byte range parts into a single open byte range request +
+
__groupsel__ (bool, default: _no_): select groups based on language (by default all playable groups are exposed) +
+
__chain_mode__ (enum, default: _on_): MPD chaining mode - off: do not use MPD chaining - on: use MPD chaining once over, fallback if MPD load failure - error: use MPD chaining once over or if error (MPD or segment download) +
+
__asloop__ (bool, default: _false_): when auto switch is enabled, iterates back and forth from highest to lowest qualities +
+
__bsmerge__ (bool, default: _true_): allow merging of video bitstreams (only HEVC for now) +
diff --git a/docs/Filters/dtout.md b/docs/Filters/dtout.md index 69a60051..7a48c7a7 100644 --- a/docs/Filters/dtout.md +++ b/docs/Filters/dtout.md @@ -8,12 +8,24 @@ This filter may be automatically loaded during graph resolution. This filter provides SDI output to be used with _DTA 2174_ or _DTA 2154_ cards. -# Options +# Options {.no-collapse} +
__bus__ (sint, default: _-1_): PCI bus number. If not set, device discovery is used +
+
__slot__ (sint, default: _-1_): PCI bus number. If not set, device discovery is used +
+
__fps__ (frac, default: _30/1_): default FPS to use if input stream fps cannot be detected +
+
__clip__ (bool, default: _false_): clip YUV data to valid SDI range, slower +
+
__port__ (uint, default: _1_): set sdi output port of card -__start__ (dbl, default: _0.0_): set playback start offset, [-1, 0] means percent of media dur, e.g. -1 == dur +
+
+__start__ (dbl, default: _0.0_): set playback start offset, [-1, 0] means percent of media dur, e.g. -1 == dur +
diff --git a/docs/Filters/dvbin.md b/docs/Filters/dvbin.md index 91493a96..a946cf82 100644 --- a/docs/Filters/dvbin.md +++ b/docs/Filters/dvbin.md @@ -14,9 +14,15 @@ The URL syntax is `dvb://CHANNAME[@FRONTEND]`, with: -# Options +# Options {.no-collapse} -__src__ (cstr): URL of source content +
+__src__ (cstr): URL of source content +
+
__block_size__ (uint, default: _65536_): block size used to read file -__chcfg__ (cstr): path to channels.conf file +
+
+__chcfg__ (cstr): path to channels.conf file +
diff --git a/docs/Filters/evgs.md b/docs/Filters/evgs.md index f0e92171..be947062 100644 --- a/docs/Filters/evgs.md +++ b/docs/Filters/evgs.md @@ -18,7 +18,8 @@ When output sample aspect ratio is set, the output dimensions are divided by the Example ``` evgs:osize=288x240:osar=3/2 -``` +``` + The output dimensions will be 192x240. When aspect ratio is not kept ([keepar=off](#keepar=off)): @@ -42,19 +43,35 @@ When sample aspect ratio is kept, the filter will: -# Options +# Options {.no-collapse} -__osize__ (v2di): osize of output video -__ofmt__ (pfmt, default: _none_): pixel format for output video. When not set, input format is used +
+__osize__ (v2di): osize of output video +
+
+__ofmt__ (pfmt, default: _none_): pixel format for output video. When not set, input format is used +
+
__ofr__ (bool, default: _false_): force output full range +
+
__keepar__ (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 +
+
__padclr__ (str, default: _black_): clear color when aspect ration preservation is used +
+
__osar__ (frac, default: _0/1_): force output pixel aspect ratio +
+
__nbth__ (sint, default: _-1_): number of threads to use, -1 means all cores +
+
__hq__ (bool, default: _false_): use bilinear interpolation instead of closest pixel +
diff --git a/docs/Filters/ffavf.md b/docs/Filters/ffavf.md index db1c3f95..4952a409 100644 --- a/docs/Filters/ffavf.md +++ b/docs/Filters/ffavf.md @@ -16,25 +16,29 @@ The filter loads a filter or a filter chain description from the [f](#f) option. Example ``` ffavf:f=showspectrum -``` +``` + Unlike other FFmpeg bindings in GPAC, this filter does not parse other libavfilter options, you must specify them directly in the filter chain, and the [f](#f) option will have to be escaped. Example ``` ffavf::f=showspectrum=size=320x320 or ffavf::f=showspectrum=size=320x320::pfmt=rgb ffavf::f=anullsrc=channel_layout=5.1:sample_rate=48000 -``` +``` + For complex filter graphs, it is possible to store options in a file (e.g. `opts.txt`): Example ``` :f=anullsrc=channel_layout=5.1:sample_rate=48000 -``` +``` + And load arguments from file: Example ``` ffavf:opts.txt aout -``` +``` + The filter will automatically create `buffer` and `buffersink` AV filters for data exchange between GPAC and libavfilter. The builtin options ( [pfmt](#pfmt), [afmt](#afmt) ...) can be used to configure the `buffersink` filter to set the output format of the filter. @@ -47,7 +51,8 @@ When a graph has several inputs, input PID names shall be assigned by the user u Example ``` gpac -i video:#ffid=a -i logo:#ffid=b ffavf::f=[a][b]overlay=main_w-overlay_w-10:main_h-overlay_h-10 vout -``` +``` + In this example: - the video source is identified as `a` @@ -59,7 +64,8 @@ When a graph has several outputs, output PIDs will be identified using the `ffid Example ``` gpac -i source ffavf::f=split inspect:SID=#ffid=out0 vout#SID=out1 -``` +``` + In this example: - the splitter produces 2 video streams `out0` and `out1` @@ -78,13 +84,27 @@ The filter handles option updates as commands passed to the AV filter graph. The -# Options - -__f__ (str): filter or filter chain description -__pfmt__ (pfmt, default: _none_): pixel format of output. If not set, let AVFilter decide -__afmt__ (afmt, default: _none_): audio format of output. If not set, let AVFilter decide -__sr__ (uint, default: _0_): sample rate of output. If not set, let AVFilter decide -__ch__ (uint, default: _0_): number of channels of output. If not set, let AVFilter decide -__dump__ (bool, default: _false_, updatable): dump graph as log media@info or stderr if not set -__*__ (str): any possible options defined for AVFilter and sub-classes (see `gpac -hx ffavf` and `gpac -hx ffavf:*`) +# Options {.no-collapse} + +
+__f__ (str): filter or filter chain description +
+
+__pfmt__ (pfmt, default: _none_): pixel format of output. If not set, let AVFilter decide +
+
+__afmt__ (afmt, default: _none_): audio format of output. If not set, let AVFilter decide +
+
+__sr__ (uint, default: _0_): sample rate of output. If not set, let AVFilter decide +
+
+__ch__ (uint, default: _0_): number of channels of output. If not set, let AVFilter decide +
+
+__dump__ (bool, default: _false_, updatable): dump graph as log media@info or stderr if not set +
+
+__*__ (str): any possible options defined for AVFilter and sub-classes (see `gpac -hx ffavf` and `gpac -hx ffavf:*`) +
diff --git a/docs/Filters/ffavin.md b/docs/Filters/ffavin.md index b142c45e..0ad01aa2 100644 --- a/docs/Filters/ffavin.md +++ b/docs/Filters/ffavin.md @@ -31,28 +31,44 @@ Example ``` ffmpeg -f libndi_newtek -i MY_NDI_TEST ... gpac -i av://:fmt=libndi_newtek:dev=MY_NDI_TEST ... -``` +``` + You may need to escape the [dev](#dev) option if the format uses ':' as separator, as is the case for AVFoundation: Example ``` gpac -i av://::dev=0:1 ... -``` +``` + -# Options +# Options {.no-collapse} -__src__ (str): url of device, `video://`, `audio://` or `av://` -__fmt__ (str): name of device class. If not set, defaults to first device class -__dev__ (str, default: _0_): name of device or index of device +
+__src__ (str): url of device, `video://`, `audio://` or `av://` +
+
+__fmt__ (str): name of device class. If not set, defaults to first device class +
+
+__dev__ (str, default: _0_): name of device or index of device +
+
__copy__ (enum, default: _A_): set copy mode of raw frames - N: frames are only forwarded (shared memory, no copy) - A: audio frames are copied, video frames are forwarded - V: video frames are copied, audio frames are forwarded - AV: all frames are copied +
+
__sclock__ (bool, default: _false_): use system clock (us) instead of device timestamp (for buggy devices) +
+
__probes__ (uint, default: _10_, minmax: 0-100): probe a given number of video frames before emitting (this usually helps with bad timing of the first frames) -__*__ (str): any possible options defined for AVInputFormat and AVFormatContext (see `gpac -hx ffavin` and `gpac -hx ffavin:*`) +
+
+__*__ (str): any possible options defined for AVInputFormat and AVFormatContext (see `gpac -hx ffavin` and `gpac -hx ffavin:*`) +
diff --git a/docs/Filters/ffbsf.md b/docs/Filters/ffbsf.md index b15808b1..30e8ac37 100644 --- a/docs/Filters/ffbsf.md +++ b/docs/Filters/ffbsf.md @@ -1,6 +1,6 @@ -# FFmpeg BitStream filter +# FFmpeg BitStream filter {:data-level="all"} Register name used to load filter: __ffbsf__ This filter is not checked during graph resolution and needs explicit loading. diff --git a/docs/Filters/ffdec.md b/docs/Filters/ffdec.md index eb9a0c1e..8e94a73e 100644 --- a/docs/Filters/ffdec.md +++ b/docs/Filters/ffdec.md @@ -25,13 +25,20 @@ Each entry in the list is formatted as `GID@name` or `GID@+name`, with: Example ``` gpac -i source.mp4 --ffcmap=BKV1@binkvideo vout -``` +``` + This will map an ISOBMFF track declared with coding type `BKV1` to binkvideo. -# Options +# Options {.no-collapse} -__ffcmap__ (strl): codec map +
+__ffcmap__ (strl): codec map +
+
__c__ (str): codec name (GPAC or ffmpeg), only used to query possible arguments - updated to ffmpeg codec name after initialization -__*__ (str): any possible options defined for AVCodecContext and sub-classes. See `gpac -hx ffdec` and `gpac -hx ffdec:*` +
+
+__*__ (str): any possible options defined for AVCodecContext and sub-classes. See `gpac -hx ffdec` and `gpac -hx ffdec:*` +
diff --git a/docs/Filters/ffdmx.md b/docs/Filters/ffdmx.md index fde5938a..9a7feea3 100644 --- a/docs/Filters/ffdmx.md +++ b/docs/Filters/ffdmx.md @@ -13,11 +13,21 @@ Input protocols are listed with `Description: Input protocol`, and the subclass For example, if `ffdmx:rtmp` is listed as input protocol, this means `rtmp://` source URLs are supported. -# Options +# Options {.no-collapse} -__src__ (cstr): URL of source content -__reparse__ (bool, default: _false_): force reparsing of stream content (AVC,HEVC,VVC,AV1 only for now) +
+__src__ (cstr): URL of source content +
+
+__reparse__ (bool, default: _false_): force reparsing of stream content (AVC,HEVC,VVC,AV1 only for now) +
+
__block_size__ (uint, default: _4096_): block size used to read file when using GFIO context +
+
__strbuf_min__ (uint, default: _1MB_): internal buffer size when demuxing from GPAC's input stream -__*__ (str): any possible options defined for AVFormatContext and sub-classes. See `gpac -hx ffdmx` and `gpac -hx ffdmx:*` +
+
+__*__ (str): any possible options defined for AVFormatContext and sub-classes. See `gpac -hx ffdmx` and `gpac -hx ffdmx:*` +
diff --git a/docs/Filters/ffenc.md b/docs/Filters/ffenc.md index f6d68d24..88cfb526 100644 --- a/docs/Filters/ffenc.md +++ b/docs/Filters/ffenc.md @@ -6,7 +6,7 @@ Register name used to load filter: __ffenc__ This filter may be automatically loaded during graph resolution. This filter encodes audio and video streams using FFmpeg. -See FFmpeg documentation (https://ffmpeg.org/documentation.html) for more details. +See FFmpeg documentation [FFmpeg Documentation](https://ffmpeg.org/documentation.html)for more details. To list all supported encoders for your GPAC build, use `gpac -h ffenc:*`. The filter will try to resolve the codec name in [c](#c) against a libavcodec codec name (e.g. `libx264`) and use it if found. @@ -32,14 +32,30 @@ If codec is video and [fintra](#fintra) is set, reload will happen at next force The [rld](#rld) option is usually needed for dynamic updates of rate control parameters, since most encoders in ffmpeg do not support it. -# Options - -__c__ (str): codec identifier. Can be any supported GPAC codec name or ffmpeg codec name - updated to ffmpeg codec name after initialization -__pfmt__ (pfmt, default: _none_): pixel format for input video. When not set, input format is used -__fintra__ (frac, default: _-1/1_): force intra / IDR frames at the given period in sec, e.g. `fintra=2` will force an intra every 2 seconds and `fintra=1001/1000` will force an intra every 30 frames on 30000/1001=29.97 fps video; ignored for audio +# Options {.no-collapse} + +
+__c__ (str): codec identifier. Can be any supported GPAC codec name or ffmpeg codec name - updated to ffmpeg codec name after initialization +
+
+__pfmt__ (pfmt, default: _none_): pixel format for input video. When not set, input format is used +
+
+__fintra__ (frac, default: _-1/1_): force intra / IDR frames at the given period in sec, e.g. `fintra=2` will force an intra every 2 seconds and `fintra=1001/1000` will force an intra every 30 frames on 30000/1001=29.97 fps video; ignored for audio +
+
__all_intra__ (bool, default: _false_, updatable): only produce intra frames +
+
__ls__ (bool, default: _false_): log stats +
+
__rc__ (bool, default: _false_): reset encoder when forcing intra frame (some encoders might not support intra frame forcing) +
+
__rld__ (bool, default: _false_, updatable): force reloading of encoder when arguments are updated -__*__ (str): any possible options defined for AVCodecContext and sub-classes. see `gpac -hx ffenc` and `gpac -hx ffenc:*` +
+
+__*__ (str): any possible options defined for AVCodecContext and sub-classes. see `gpac -hx ffenc` and `gpac -hx ffenc:*` +
diff --git a/docs/Filters/ffmx.md b/docs/Filters/ffmx.md index d5c78101..586b23fc 100644 --- a/docs/Filters/ffmx.md +++ b/docs/Filters/ffmx.md @@ -20,17 +20,39 @@ The filter watches the property `FileNumber` on incoming packets to create new f All PID properties prefixed with `meta:` will be added as metadata. -# Options - -__dst__ (cstr): location of destination file or remote URL -__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 +# Options {.no-collapse} + +
+__dst__ (cstr): location of destination file or remote URL +
+
+__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 +
+
__ileave__ (frac, default: _1_): interleave window duration in second, a value of 0 disable interleaving +
+
__nodisc__ (bool, default: _false_): ignore stream configuration changes while multiplexing, may result in broken streams +
+
__mime__ (cstr): set mime type for graph resolution +
+
__ffiles__ (bool, default: _false_): force complete files to be created for each segment in DASH modes +
+
__ffmt__ (str): force ffmpeg output format for the given URL +
+
__block_size__ (uint, default: _4096_): block size used to read file when using avio context +
+
__keepts__ (bool, default: _true_): do not shift input timeline back to 0 -__*__ (str): any possible options defined for AVFormatContext and sub-classes (see `gpac -hx ffmx` and `gpac -hx ffmx:*`) +
+
+__*__ (str): any possible options defined for AVFormatContext and sub-classes (see `gpac -hx ffmx` and `gpac -hx ffmx:*`) +
diff --git a/docs/Filters/ffsws.md b/docs/Filters/ffsws.md index fb23ec75..e346dac7 100644 --- a/docs/Filters/ffsws.md +++ b/docs/Filters/ffsws.md @@ -18,7 +18,8 @@ When output sample aspect ratio is set, the output dimensions are divided by the Example ``` ffsws:osize=288x240:osar=3/2 -``` +``` + The output dimensions will be 192x240. When aspect ratio is not kept ([keepar=off](#keepar=off)): @@ -51,27 +52,55 @@ When sample aspect ratio is kept, the filter will: See FFmpeg documentation (https://ffmpeg.org/documentation.html) for more details -# Options +# Options {.no-collapse} -__osize__ (v2di): osize of output video -__ofmt__ (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): pixel format for output video. When not set, input format is used +
+__osize__ (v2di): osize of output video +
+
+__ofmt__ (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): pixel format for output video. When not set, input format is used +
+
__scale__ (enum, default: _bicubic_): scaling mode (see filter help) (fastbilinear|bilinear|bicubic|X|point|area|bicublin|gauss|sinc|lanzcos|spline) +
+
__p1__ (dbl, default: _+I_): scaling algo param1 +
+
__p2__ (dbl, default: _+I_): scaling algo param2 +
+
__ofr__ (bool, default: _false_): force output full range +
+
__brightness__ (bool, default: _0_): 16.16 fixed point brightness correction, 0 means use default +
+
__contrast__ (uint, default: _0_): 16.16 fixed point brightness correction, 0 means use default +
+
__saturation__ (uint, default: _0_): 16.16 fixed point brightness correction, 0 means use default +
+
__otable__ (sintl): the yuv2rgb coefficients describing the output yuv space, normally ff_yuv2rgb_coeffs[x], use default if not set +
+
__itable__ (sintl): the yuv2rgb coefficients describing the input yuv space, normally ff_yuv2rgb_coeffs[x], use default if not set +
+
__keepar__ (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 +
+
__padclr__ (str, default: _black_): clear color when aspect ration preservation is used +
+
__osar__ (frac, default: _0/1_): force output pixel aspect ratio +
diff --git a/docs/Filters/filters_general.md b/docs/Filters/filters_general.md index c8c96b21..9e177cb5 100644 --- a/docs/Filters/filters_general.md +++ b/docs/Filters/filters_general.md @@ -59,24 +59,28 @@ When string parameters are used (e.g. URLs), it is recommended to escape the str Example ``` filter:ARG=http://foo/bar?yes:gpac:opt=VAL -``` +``` + This will properly extract the URL. Example ``` filter:ARG=http://foo/bar?yes:opt=VAL -``` +``` + This will fail to extract it and keep `:opt=VAL` as part of the URL. The escape mechanism is not needed for local source, for which file existence is probed during argument parsing. It is also not needed for builtin protocol handlers (`avin://`, `video://`, `audio://`, `pipe://`) For schemes not using a server path, e.g. `tcp://` and `udp://`, the escape is not needed if a trailing `/` is appended after the port number. Example ``` -i tcp://127.0.0.1:1234:OPT -``` +``` + This will fail to extract the URL and options. Example ``` -i tcp://127.0.0.1:1234/:OPT -``` +``` + This will extract the URL and options. _Note: one trick to avoid the escape sequence is to declare the URLs option at the end, e.g. `f1:opt1=foo:url=http://bar`, provided you have only one URL parameter to specify on the filter._ @@ -84,7 +88,8 @@ It is possible to locally disable option parsing (usefull for string options) by Example ``` filter::opt1=UDP://IP:PORT/:someopt=VAL::opt2=VAL2 -``` +``` + This will pass `UDP://IP:PORT/:someopt=VAL` to `opt1` without inspecting it, and `VAL2` to `opt2`. @@ -93,12 +98,14 @@ Source and sink filters do not need to be addressed by the filter name, specifyi Example ``` "src=file.mp4" or "-src file.mp4" or "-i file.mp4" -``` +``` + This will find a filter (for example `fin`) able to load `file.mp4`. The same result can be achieved by using `fin:src=file.mp4`. Example ``` "dst=dump.yuv" or "-dst dump.yuv" or "-o dump.yuv" -``` +``` + This will dump the video content in `dump.yuv`. The same result can be achieved by using `fout:dst=dump.yuv`. Specific source or sink filters may also be specified using `filterName:src=URL` or `filterName:dst=URL`. @@ -110,7 +117,8 @@ There is a special option called `gfreg` which allows specifying preferred filte Example ``` src=file.mp4:gfreg=ffdmx,ffdec -``` +``` + This will use _ffdmx_ to read `file.mp4` and _ffdec_ to decode it. This can be used to test a specific filter when alternate filter chains are possible. @@ -130,14 +138,16 @@ The shortcut syntax `c=TYPE` (e.g. `c=aac:opts`) is also supported. Example ``` gpac -i dump.yuv:size=320x240:fps=25 enc:c=avc:b=150000:g=50:cgop=true:fast=true -o raw.264 -``` +``` + This creates a 25 fps AVC at 175kbps with a gop duration of 2 seconds, using closed gop and fast encoding settings for ffmpeg. The inverse operation (forcing a decode to happen) is possible using the _reframer_ filter. Example ``` gpac -i file.mp4 reframer:raw=av -o null -``` +``` + This will force decoding media from `file.mp4` and trash (send to `null`) the result (doing a decoder benchmark for example). ## Escaping option separators @@ -145,17 +155,20 @@ When a filter uses an option defined as a string using the same separator charac Example ``` f:a=foo:b=bar -``` +``` + This will set option `a` to `foo` and option `b` to `bar` on the filter. Example ``` f::a=foo:b=bar -``` +``` + This will set option `a` to `foo:b=bar` on the filter. Example ``` f:a=foo::b=bar:c::d=fun -``` +``` + This will set option `a` to `foo`, `b` to `bar:c` and the option `d` to `fun` on the filter. # Filter linking [_LINK_] @@ -189,7 +202,8 @@ A filter with `RSID` set is not clonable. Example ``` gpac -i file.mp4 c=avc -o output -``` +``` + With this setup in _implicit mode_: - if the file has a video PID, it will connect to `enc` but not to `output`. The output PID of `enc` will connect to `output`. @@ -199,7 +213,8 @@ With this setup in _implicit mode_: Example ``` gpac -cl -i file.mp4 c=avc -o output -``` +``` + With this setup in _complete mode_: - if the file has a video PID, it will connect both to `enc` and to `output`, and the output PID of `enc` will connect to `output`. @@ -210,7 +225,8 @@ Furthermore in _implicit mode_, filter connections are restricted to filters def Example ``` gpac -i video1 reframer:saps=1 -i video2 ffsws:osize=128x72 -o output -``` +``` + This will connect: - `video1` to `reframer` then `reframer` to `output` but will prevent `reframer` to `ffsws` connection. @@ -220,7 +236,8 @@ This will connect: Example ``` gpac -i video1 -i video2 reframer:saps=1 ffsws:osize=128x72 -o output -``` +``` + This will connect `video1` AND `video2` to `reframer->ffsws->output` The _implicit mode_ allows specifying linear processing chains (no PID fan-out except for final output(s)) without link directives, simplifying command lines for common cases. @@ -230,7 +247,8 @@ __Warning: Argument order really matters in implicit mode!__ Example ``` gpac -i file.mp4 c=avc c=aac -o output -``` +``` + If the file has a video PID, it will connect to `c=avc` but not to `output`. The output PID of `c=avc` will connect to `output`. If the file has an audio PID, it will connect to `c=aac` but not to `output`. The output PID of `c=aac` will connect to `output`. If the file has other PIDs than audio or video, they will connect to `output`. @@ -238,7 +256,8 @@ If the file has other PIDs than audio or video, they will connect to `output`. Example ``` gpac -i file.mp4 ffswf=osize:128x72 c=avc resample=osr=48k c=aac -o output -``` +``` + This will force: - `SRC(video)->ffsws->enc(video)->output` and prevent `SRC(video)->output`, `SRC(video)->enc(video)` and `ffsws->output` connections which would happen in _complete mode_. @@ -254,17 +273,20 @@ Several link directives can be given for a filter. Example ``` fA fB @1 fC -``` +``` + This indicates that `fC` only accepts inputs from `fA`. Example ``` fA fB fC @1 @0 fD -``` +``` + This indicates that `fD` only accepts inputs from `fB` and `fC`. Example ``` fA fB fC ... @@1 fZ -``` +``` + This indicates that `fZ` only accepts inputs from `fB`. ## Complex links @@ -277,17 +299,20 @@ The `@` link directive is just a quick shortcut to set the following filter argu Example ``` fA fB @1 fC -``` +``` + This is equivalent to `fA:FID=1 fB fC:SID=1`. Example ``` fA:FID=1 fB fC:SID=1 -``` +``` + This indicates that `fC` only accepts input from `fA`, but `fB` might accept inputs from `fA`. Example ``` fA:FID=1 fB:FID=2 fC:SID=1 fD:SID=1,2 -``` +``` + This indicates that `fD` only accepts input from `fA` and `fB` and `fC` only from `fA` _Note: A filter with sourceID set cannot get input from filters with no IDs._ @@ -317,45 +342,53 @@ Example ``` fA fB:SID=*#ServiceID=2 fA fB:SID=#ServiceID=2 -``` +``` + This indicates to match connection between `fA` and `fB` only for PIDs with a `ServiceID` property of `2`. These extensions also work with the _LINK_ `@` shortcut. Example ``` fA fB @1#video fC -``` +``` + This indicates that `fC` only accepts inputs from `fA`, and of type video. Example ``` gpac -i img.heif @#ItemID=200 vout -``` +``` + This indicates to connect to `vout` only PIDs with `ItemID` property equal to `200`. Example ``` gpac -i vid.mp4 @#PID=1 vout -``` +``` + This indicates to connect to `vout` only PIDs with `ID` property equal to `1`. Example ``` gpac -i vid.mp4 @#Width=640 vout -``` +``` + This indicates to connect to `vout` only PIDs with `Width` property equal to `640`. Example ``` gpac -i vid.mp4 @#Width-640 vout -``` +``` + This indicates to connect to `vout` only PIDs with `Width` property less than `640` Example ``` gpac -i vid.mp4 @#ID=ItemID#ItemNumber=1 vout -``` +``` + This will connect to `vout` only PID with an ID property equal to ItemID property (keep items, discard tracks) and an Item number of 1 (first item). Multiple fragment can be specified to check for multiple PID properties. Example ``` gpac -i vid.mp4 @#Width=640#Height+380 vout -``` +``` + This indicates to connect to `vout` only PIDs with `Width` property equal to `640` and `Height` greater than `380`. __Warning: If a PID directly connects to one or more explicitly loaded filters, no further dynamic link resolution will be done to connect it to other filters with no sourceID set. Link directives should be carefully setup.__ @@ -363,7 +396,8 @@ __Warning: If a PID directly connects to one or more explicitly loaded filters, Example ``` fA @ reframer fB -``` +``` + If `fB` accepts inputs provided by `fA` but `reframer` does not, this will link `fA` PID to `fB` filter since `fB` has no sourceID. Since the PID is connected, the filter engine will not try to solve a link between `fA` and `reframer`. @@ -371,14 +405,16 @@ An exception is made for local files: by default, a local file destination will Example ``` gpac -i file.mp4 -o dump.mp4 -``` +``` + This will prevent direct connection of PID of type `file` to dst `file.mp4`, remultiplexing the file. The special option `nomux` is used to allow direct connections (ignored for non-sink filters). Example ``` gpac -i file.mp4 -o dump.mp4:nomux -``` +``` + This will result in a direct file copy. This only applies to local files destination. For pipes, sockets or other file outputs (HTTP, ROUTE): @@ -399,12 +435,14 @@ This is mostly used for _implicit mode_ in `gpac`: each first source filter spec Example ``` gpac -i in1.mp4 -i in2.mp4 -o out1.mp4 -o out2.mp4 -``` +``` + This will result in both inputs multiplexed in both outputs. Example ``` gpac -i in1.mp4 -o out1.mp4 -i in2.mp4 -o out2.mp4 -``` +``` + This will result in in1 mixed to out1 and in2 mixed to out2, these last two filters belonging to a different sub-session. # Arguments inheriting @@ -413,31 +451,36 @@ Unless explicitly disabled (see [-max-chain](core_options/#max-chain)), the filt Example ``` gpac -i file.mp4:OPT -o file.aac -o file.264 -``` +``` + This will pass the `:OPT` to all filters loaded between the source and the two destinations. Example ``` gpac -i file.mp4 -o file.aac:OPT -o file.264 -``` +``` + This will pass the `:OPT` to all filters loaded between the source and the file.aac destination. _Note: the destination arguments inherited are the arguments placed __AFTER__ the `dst=` option._ Example ``` gpac -i file.mp4 fout:OPTFOO:dst=file.aac:OPTBAR -``` +``` + This will pass the `:OPTBAR` to all filters loaded between `file.mp4` source and `file.aac` destination, but not `OPTFOO`. Arguments inheriting can be stopped by using the keyword `gfloc`: arguments after the keyword will not be inherited. Example ``` gpac -i file.mp4 -o file.aac:OPTFOO:gfloc:OPTBAR -o file.264 -``` +``` + This will pass `:OPTFOO` to all filters loaded between `file.mp4` source and `file.aac` destination, but not `OPTBAR` Arguments are by default tracked to check if they were used by the filter chain, and a warning is thrown if this is not the case. It may be useful to specify arguments which may not be consumed depending on the graph resolution; the specific keyword `gfopt` indicates that arguments after the keyword will not be tracked. Example ``` gpac -i file.mp4 -o file.aac:OPTFOO:gfopt:OPTBAR -o file.264 -``` +``` + This will warn if `OPTFOO` is not consumed, but will not track `OPTBAR`. A filter may be assigned a name (for inspection purposes, not inherited) using `:N=name` option. This name is not used in link resolution and may be changed at runtime by the filter instance. @@ -470,7 +513,8 @@ Templating can be useful when encoding several qualities in one pass. Example ``` gpac -i dump.yuv:size=640x360 vcrop:wnd=0x0x320x180 c=avc:b=1M @2 c=avc:b=750k -o dump_$CropOrigin$x$Width$x$Height$.264 -``` +``` + This will create a cropped version of the source, encoded in AVC at 1M, and a full version of the content in AVC at 750k. Outputs will be `dump_0x0x320x180.264` for the cropped version and `dump_0x0x640x360.264` for the non-cropped one. # Cloning filters @@ -479,31 +523,36 @@ When a filter accepts a single connection and has a connected input, it is no lo Example ``` gpac -i img.heif -o dump_$ItemID$.jpg -``` +``` + In this case, only one item (likely the first declared in the file) will connect to the destination. Other items will not be connected since the destination only accepts one input PID. Example ``` gpac -i img.heif -o dump_$ItemID$.jpg -``` +``` + In this case, the destination will be cloned for each item, and all will be exported to different JPEGs thanks to URL templating. Example ``` gpac -i vid.mpd c=avc:FID=1 -o transcode.mpd:SID=1 -``` +``` + In this case, the encoder will be cloned for each video PIDs in the source, and the destination will only use PIDs coming from the encoders. When implicit linking is enabled, all filters are by default clonable. This allows duplicating the processing for each PIDs of the same type. Example ``` gpac -i dual_audio resample:osr=48k c=aac -o dst -``` +``` + The `resampler` filter will be cloned for each audio PID, and the encoder will be cloned for each resampler output. You can explicitly deactivate the cloning instructions: Example ``` gpac -i dual_audio resample:osr=48k:clone=0 c=aac -o dst -``` +``` + The first audio will connect to the `resample` filter, the second to the `enc` filter and the `resample` output will connect to a clone of the `enc` filter. # Templating filter chains @@ -517,14 +566,16 @@ Example ``` gpac -i source.ts -o file_$ServiceID$.mp4:SID=*#ServiceID=* gpac -i source.ts -o file_$ServiceID$.mp4:SID=#ServiceID= -``` +``` + In this case, each new `ServiceID` value found when connecting PIDs to the destination will create a new destination file. Cloning in implicit linking mode applies to output as well: Example ``` gpac -i dual_audio -o dst_$PID$.aac -``` +``` + Each audio track will be dumped to aac (potentially reencoding if needed). # Assigning PID properties @@ -547,7 +598,8 @@ __Warning: Properties are not filtered and override the properties of the filter Example ``` gpac -i v1.mp4:#ServiceID=4 -i v2.mp4:#ServiceID=2 -o dump.ts -``` +``` + This will multiplex the streams in `dump.ts`, using `ServiceID` 4 for PIDs from `v1.mp4` and `ServiceID` 2 for PIDs from `v2.mp4`. PID properties may be conditionally assigned by checking other PID properties. The syntax uses parenthesis (not configurable) after the property assignment sign: @@ -564,17 +616,20 @@ _Note: When set, the default value (empty condition) always matches the PID, the Example ``` gpac -i source.mp4:#MyProp=(audio)"Super Audio",(video)"Super Video" -``` +``` + This will assign property `MyProp` to `Super Audio` for audio PIDs and to `Super Video` for video PIDs. Example ``` gpac -i source.mp4:#MyProp=(audio1)"Super Audio" -``` +``` + This will assign property `MyProp` to `Super Audio` for first audio PID declared. Example ``` gpac -i source.mp4:#MyProp=(Width+1280)HD -``` +``` + This will assign property `MyProp` to `HD` for PIDs with property `Width` greater than 1280. The property value can use templates with the following keywords: @@ -585,19 +640,22 @@ The property value can use templates with the following keywords: Example ``` gpac -i source.ts:#ASID=$PID$ -``` +``` + This will assign DASH AdaptationSet ID to the PID ID value. Example ``` gpac -i source.ts:#RepresentationID=$ServiceID$ -``` +``` + This will assign DASH Representation ID to the PID ServiceID value. A property can also be removed by not specifying any value. Conditional removal is possible using the above syntax. Example ``` gpac -i source.ts:#FOO= -``` +``` + This will remove the `FOO` property on the output PID. # Using option files @@ -616,7 +674,8 @@ An option file declaration (`filter:myopts.txt`) follows the same inheritance ru Example ``` gpac -i source.mp4:myopts.txt:foo=bar -o dst -``` +``` + Any filter loaded between `source.mp4` and `dst` will inherit both `myopts.txt` and `foo` options and will resolve options and PID properties given in `myopts.txt`. # Ignoring filters at run-time @@ -627,17 +686,20 @@ When the PID codec ID matches one of the specified codec, the filter is replaced Example ``` -i src c=avc:b=1m:ccp -o mux -``` +``` + This will replace the encoder filter with a reframer if the input PID is in AVC|H264 format, or uses the encoder for other visual PIDs. Example ``` -i src c=avc:b=1m:ccp=avc,hevc -o mux -``` +``` + This will replace the encoder filter with a reframer if the input PID is in AVC|H264 or HEVC format, or uses the encoder for other visual PIDs. Example ``` -i src cecrypt:cfile=drm.xml:ccp=aac -o mux -``` +``` + This will replace the encryptor filter with a reframer if the input PID is in AAC format, or uses the encryptor for other PIDs. # Specific filter options @@ -665,7 +727,8 @@ The `$GINC` construct can be used to dynamically assign numbers in filter chains Example ``` gpac -i source.ts tssplit @#ServiceID= -o dump_$GINC(10,2).ts -``` +``` + This will dump first service in dump_10.ts, second service in dump_12.ts, etc... As seen previously, the following options may be set on any filter, but are not visible in individual filter help: diff --git a/docs/Filters/filters_properties.md b/docs/Filters/filters_properties.md index 82137654..68add983 100644 --- a/docs/Filters/filters_properties.md +++ b/docs/Filters/filters_properties.md @@ -274,11 +274,11 @@ MaxBuffer | uint | D | Maximum buffer occupancy in ms | PBMX ReBuffer | uint | D | Rebuffer threshold in ms, 0 disable rebuffering | PBRE ViewIdx | uint | D | View index for multiview (1 being left) | VIDX FragURL | str | D | Fragment URL (without '#') of original URL (used by some filters to set the property on media PIDs) | OFRA -ROUTEIP | str | D | ROUTE session IP address | RSIP -ROUTEPort | uint | D | ROUTE session port number | RSPN -ROUTEName | str | D | Name (location) of raw file to advertise in ROUTE session | RSFN -ROUTECarousel | frac | D | Carousel period in seconds of raw file in ROUTE session | RSCR -ROUTEUpload | frac | D | Upload time in seconds of raw file in ROUTE session | RSST +MCASTIP | str | D | session Multicast IP address for ROUTE/MABR | MSIP +MCASTPort | uint | D | session port number for ROUTE/MABR | MSPN +MCASTName | str | D | Name (location) of raw file to advertise in ROUTE/MABR session | MSFN +MCASTCarousel | frac | D | Carousel period in seconds of raw file or low-latency manifest/init segments for ROUTE/MABR sessions | MSCR +MCASTUpload | frac | D | Upload time in seconds of raw files for ROUTE/MABR sessions | MSST Stereo | uint | D | Stereo type of video | PSTT Projection | uint | D | Projection type of video | PPJT InitalPose | v3di | D | Initial pose for 360 video, in degrees expressed as 16.16 bits (x is yaw, y is pitch, z is roll) | PPOS @@ -305,6 +305,8 @@ DownloadSession | ptr | D | Pointer to download session | GHTT HasTemi | bool | D | TEMI present flag | PTEM XPSMask | uint | DP | Parameter set mask | PXPM RangeEnd | bool | P | Signal packet is the last in the desired play range | PCER +RefID | sint | P | packet identifier for dependency (usually POC for video) | PKID +Refs | sintl | P | list of packet identifier this packet depends on | PRFS # Pixel formats @@ -852,10 +854,15 @@ gopher | httpin | n/a gophers | httpin | n/a imap | httpin | n/a imaps | httpin | n/a +ldap | httpin | n/a +ldaps | httpin | n/a mqtt | httpin | n/a pop3 | httpin | n/a pop3s | httpin | n/a +rtmp | httpin | n/a rtsp | httpin rtpin | rtspout +scp | httpin | n/a +sftp | httpin | n/a smb | httpin | n/a smbs | httpin | n/a smtp | httpin | n/a diff --git a/docs/Filters/fin.md b/docs/Filters/fin.md index 49590d9f..8616168a 100644 --- a/docs/Filters/fin.md +++ b/docs/Filters/fin.md @@ -21,17 +21,32 @@ No specific properties are attached, except a timescale if (-ptime)[] is set. Example ``` gpac fin:pck=str@"My Sample Text":ptime=2500/100:#CodecID=stxt:#StreamType=text -``` +``` + This will declare the PID as WebVTT and send a single packet with payload `My Sample Text` and a timestamp value of 25 second. -# Options +# Options {.no-collapse} -__src__ (cstr): location of source file +
+__src__ (cstr): location of source file +
+
__block_size__ (uint, default: _0_): block size used to read file. 0 means 5000 if file less than 500m, 1M otherwise -__range__ (lfrac, default: _0-0_): byte range -__ext__ (cstr): override file extension -__mime__ (cstr): set file mime type -__pck__ (mem): data to use instead of file -__ptime__ (frac, default: _0/0_): timing for data packet, ignored if den is 0 +
+
+__range__ (lfrac, default: _0-0_): byte range +
+
+__ext__ (cstr): override file extension +
+
+__mime__ (cstr): set file mime type +
+
+__pck__ (mem): data to use instead of file +
+
+__ptime__ (frac, default: _0/0_): timing for data packet, ignored if den is 0 +
diff --git a/docs/Filters/flist.md b/docs/Filters/flist.md index 057675b4..0f4cc51d 100644 --- a/docs/Filters/flist.md +++ b/docs/Filters/flist.md @@ -100,7 +100,8 @@ __Warning: There shall not be any other space/tab characters between sources.__ Example ``` audio.mp4 && video.mp4 -``` +``` + ## Source with filter chains Each URL can be followed by a chain of one or more filters, using the `@` link directive as used in gpac (see `gpac -h doc`). @@ -111,20 +112,23 @@ __Warning: There shall be a single character, with value space (' '), before and Example ``` src.mp4 @ reframer:rt=on -``` +``` + This will inject a reframer with real-time regulation between source and `flist` filter. Example ``` src.mp4 @ reframer:saps=1 @1 reframer:saps=0,2,3 src.mp4 @ reframer:saps=1 @-1 reframer:saps=0,2,3 -``` +``` + This will inject a reframer filtering only SAP1 frames and a reframer filtering only non-SAP1 frames between source and `flist` filter Link options can be specified (see `gpac -h doc`). Example ``` src.mp4 @#video reframer:rt=on -``` +``` + This will inject a reframer with real-time regulation between video PID of source and `flist` filter. When using filter chains, the `flist` filter will only accept PIDs from the last declared filter in the chain. @@ -132,14 +136,16 @@ In order to accept other PIDs from the source, you must specify a final link dir Example ``` src.mp4 @#video reframer:rt=on @-1#audio -``` +``` + This will inject a reframer with real-time regulation between video PID of source and `flist` filter, and will also allow audio PIDs from source to connect to `flist` filter. The empty link directive can also be used on the last declared filter Example ``` src.mp4 @ reframer:rt=on @#audio -``` +``` + This will inject a reframer with real-time regulation between source and `flist` filter and only connect audio PIDs to `flist` filter. ## Splicing @@ -190,38 +196,65 @@ Example ``` #out=2 in=4 mark sprops=#xlink=http://foo.bar/ src:#Period=main -``` +``` + This will inject property xlink on the output PIDs in the splice zone (corresponding to period `main_2`) but not in the rest of the main media. Directives `mark`, `keep` and `sprops` are reset at the end of the splice period. -# Options - -__floop__ (sint, default: _0_): loop playlist/list of files, `0` for one time, `n` for n+1 times, `-1` for indefinitely -__srcs__ (strl): list of files to play -__fdur__ (frac, default: _1/25_): frame duration for source files with a single frame (0/NaN fraction means reuse source timing which is usually not set!) +# Options {.no-collapse} + +
+__floop__ (sint, default: _0_): loop playlist/list of files, `0` for one time, `n` for n+1 times, `-1` for indefinitely +
+
+__srcs__ (strl): list of files to play +
+
+__fdur__ (frac, default: _1/25_): frame duration for source files with a single frame (0/NaN fraction means reuse source timing which is usually not set!) +
+
__revert__ (bool, default: _false_): revert list of files ([srcs](#srcs), not playlist) +
+
__timescale__ (uint, default: _0_): force output timescale on all PIDs (0 uses the timescale of the first PID found) +
+
__ka__ (uint, default: _0_): keep playlist alive (disable loop), waiting for a new input to be added or `#end` directive to end playlist. The value specifies the refresh rate in ms +
+
__timeout__ (luint, default: _-1_): timeout in ms after which the playlist is considered dead (`-1` means indefinitely) -__fsort__ (enum, default: _no_): sort list of files +
+
+__fsort__ (enum, default: _no_): sort list of files - no: no sorting, use default directory enumeration of OS - name: sort by alphabetical name - size: sort by increasing size - date: sort by increasing modification time - datex: sort by increasing modification time +
+
__sigcues__ (bool, default: _false_): inject `CueStart` property at each source begin (new or repeated) for DASHing +
+
__fdel__ (bool, default: _false_): delete source files after processing in playlist mode (does not delete the playlist) +
+
__keepts__ (bool, default: _false_): keep initial timestamps unmodified (no reset to 0) -__raw__ (enum, default: _no_): force input AV streams to be in raw format +
+
+__raw__ (enum, default: _no_): force input AV streams to be in raw format - no: do not force decoding of inputs - av: force decoding of audio and video inputs - a: force decoding of audio inputs - v: force decoding of video inputs +
-__flush__ (bool, default: _false_): send a flush signal once playlist is done before entering keepalive +
+__flush__ (bool, default: _false_): send a flush signal once playlist is done before entering keepalive +
diff --git a/docs/Filters/fout.md b/docs/Filters/fout.md index efe8f266..a689c3a4 100644 --- a/docs/Filters/fout.md +++ b/docs/Filters/fout.md @@ -27,33 +27,60 @@ When recording a DASH or HLS session, the number of segments to keep per quality Example ``` gpac -i LIVE_MPD dashin:forward=file -o rec/$File$:max_cache_segs=3 -``` +``` + This will force keeping a maximum of 3 media segments while recording the DASH session. -# Options +# Options {.no-collapse} -__dst__ (cstr): location of destination file +
+__dst__ (cstr): location of destination file +
+
__append__ (bool, default: _false_): open in append mode +
+
__dynext__ (bool, default: _false_): indicate the file extension is set by filter chain, not dst -__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__speed__ (dbl, default: _1.0_): set playback speed when vsync is on. If negative and start is 0, start is set to -1 +
+
+__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__speed__ (dbl, default: _1.0_): set playback speed when vsync is on. If negative and start is 0, start is set to -1 +
+
__ext__ (cstr): set extension for graph resolution, regardless of file extension +
+
__mime__ (cstr): set mime type for graph resolution +
+
__cat__ (enum, default: _none_): cat each file of input PID rather than creating one file per filename - none: never cat files - auto: only cat if files have same names - all: always cat regardless of file names +
-__ow__ (enum, default: _yes_): overwrite output mode when concatenation is not used +
+__ow__ (enum, default: _yes_): overwrite output mode when concatenation is not used - yes: override file if existing - no: throw error if file existing - ask: interactive prompt +
-__mvbk__ (uint, default: _8192_): block size used when moving parts of the file around in patch mode -__redund__ (bool, default: _false_): keep redundant packet in output file +
+__mvbk__ (uint, default: _8192_): block size used when moving parts of the file around in patch mode +
+
+__redund__ (bool, default: _false_): keep redundant packet in output file +
+
__max_cache_segs__ (sint, default: _0_): maximum number of segments cached per HAS quality when recording live sessions (0 means no limit) +
+
__force_null__ (bool, default: _false_): force no output regardless of file name +
diff --git a/docs/Filters/ghidmx.md b/docs/Filters/ghidmx.md index ab5f3e46..d723d4c2 100644 --- a/docs/Filters/ghidmx.md +++ b/docs/Filters/ghidmx.md @@ -15,12 +15,14 @@ Indexes are constructed using the dasher filter and a given segment duration. Example ``` gpac -i SRC [... -i SRCn] -o index.ghi:segdur=2 -``` +``` + This constructs a binary index for the DASH session. Example ``` gpac -i SRC -o index.ghix:segdur=2 -``` +``` + This constructs an XML index for the DASH session. __Warning: XML indexes should only be used for debug purposes as they can take a significant amount of time to be parsed.__ @@ -33,13 +35,15 @@ The index can be used to generate manifest, child variants for HLS, init segment Example ``` gpac -i index.ghi:gm=all -o dash/vod.mpd -``` +``` + This generates manifest(s) and init segment(s). Example ``` gpac -i index.ghi:rep=FOO:sn=10 -o dash/vod.mpd -``` +``` + This generates the 10th segment of representation with ID `FOO`. _Note: The manifest file(s) and init segment(s) are not written when generating a segment. The manifest target (mpd or m3u8) is only used to setup the filter chain and target output path._ @@ -47,19 +51,22 @@ _Note: The manifest file(s) and init segment(s) are not written when generating Example ``` gpac -i index.ghi:gm=main -o dash/vod.m3u8 -``` +``` + This generates main manifest only (MPD or master HLS playlist). Example ``` gpac -i index.ghi:gm=child:rep=FOO:out=BAR -o dash/vod.m3u8 -``` +``` + This generates child manifest for representation `FOO` in file `BAR`. Example ``` gpac -i index.ghi:gm=init:rep=FOO:out=BAR2 -o dash/vod.m3u8 -``` +``` + This generates init segment for representation `FOO` in file `BAR2`. The filter outputs are PIDs using framed packets marked with segment boundaries and can be chained to other filters before entering the dasher (e.g. for encryption, transcode...). @@ -68,7 +75,8 @@ If representation IDs are not assigned during index creation, they default to th Example ``` gpac -i src.ghi inspect:full -``` +``` + # Muxed Representations @@ -76,19 +84,22 @@ The filter can be used to generate muxed representations, either at manifest gen Example ``` gpac -i index.ghi:mux=A@V1@V2 -o dash/vod.mpd -``` +``` + This will generate a manifest muxing representations `A` with representations `V1` and `V2`. Example ``` gpac -i index.ghi:mux=A@V1@V2,T@V1@V2 -o dash/vod.mpd -``` +``` + This will generate a manifest muxing representations `A` and `T` with representations `V1` and `V2`. Example ``` gpac -i index.ghi:rep=V2:sn=5:mux=A@V2 -o dash/vod.mpd -``` +``` + This will generate the 5th segment containing representations `A` and `V2`. The filter does not store any state, it is the user responsibility to use consistent information across calls: @@ -108,8 +119,9 @@ Indexing supports fragmented and non-fragmented MP4, MPEG-2 TS and seekable inpu -# Options +# Options {.no-collapse} +
__gm__ (enum, default: _main_): manifest generation mode - none: no manifest generation (implied if sn is not 0) @@ -117,10 +129,21 @@ Indexing supports fragmented and non-fragmented MP4, MPEG-2 TS and seekable inpu - main: generate main manifest (MPD or master M3U8) - child: generate child playlist for HLS - init: generate init segment +
+
__force__ (bool, default: _false_): force loading sources in manifest generation for debug +
+
__rep__ (str): representation to generate +
+
__sn__ (uint): segment number to generate, 0 means init segment +
+
__mux__ (strl): representation to mux - cf filter help +
+
__out__ (str): output filename to generate +
diff --git a/docs/Filters/gpac_general.md b/docs/Filters/gpac_general.md index 964e0d6c..04e0f3ce 100644 --- a/docs/Filters/gpac_general.md +++ b/docs/Filters/gpac_general.md @@ -19,25 +19,48 @@ The session can be interrupted at any time using `ctrl+c`, which can also be use The possible options for gpac are: -__-mem-track__: enable memory tracker -__-mem-track-stack__: enable memory tracker with stack dumping +
__-ltf__: load test-unit filters (used for for unit tests only) +
+
__-sloop__ (int): loop execution of session, creating a session at each loop, mainly used for testing. If no value is given, loops forever +
+
__-runfor__ (int): run for the given amount of milliseconds, exit with full session flush +
+
__-runforf__ (int): run for the given amount of milliseconds, exit with fast session flush +
+
__-runforx__ (int): run for the given amount of milliseconds and exit with no cleanup +
+
__-runfors__ (int): run for the given amount of milliseconds and exit with segfault (tests) +
+
__-runforl__ (int): run for the given amount of milliseconds and wait forever at end (tests) -__-stats__: print stats after execution -__-graph__: print graph after execution +
+
+__-stats__: print stats after execution +
+
+__-graph__: print graph after execution +
+
__-qe__: enable quick exit (no mem cleanup) +
+
__-k__: enable keyboard interaction from command line -__-r__ (string): enable reporting +
+
+__-r__ (string): enable reporting - r: runtime reporting - r=FA[,FB]: runtime reporting but only print given filters, e.g. `r=mp4mx` for ISOBMFF multiplexer only - r=: only print final report +
+
__-seps__ (string, default: __:=#,!@__): set the default character sets used to separate various arguments - the first char is used to separate argument names @@ -46,20 +69,38 @@ The possible options for gpac are: - the fourth char, if present, is used for list separators (_sourceIDs_, _gfreg_, ...) - the fifth char, if present, is used for boolean negation - the sixth char, if present, is used for LINK directives (see [filters help (-h doc)](filters_general)) +
-__-i__,__-src__ (string): specify an input file - see [filters help (-h doc)](filters_general) +
+__-i__,__-src__ (string): specify an input file - see [filters help (-h doc)](filters_general) +
-__-o__,__-dst__ (string): specify an output file - see [filters help (-h doc)](filters_general) +
+__-o__,__-dst__ (string): specify an output file - see [filters help (-h doc)](filters_general) +
+
__-ib__ (string): specify an input file to wrap as GF_FileIO object (testing of GF_FileIO) +
+
__-ibx__ (string): specify an input file to wrap as GF_FileIO object without caching (testing of GF_FileIO) +
+
__-ob__ (string): specify an output file to wrap as GF_FileIO object (testing of GF_FileIO) +
+
__-cl__: force complete mode when no link directive are set - see [filters help (-h doc)](filters_general) +
+
__-sid__: force source IDs to be present when attempting to link - see [filters help (-h doc)](filters_general) +
+
__-step__: test step mode in non-blocking session -__-h__,__-help,-ha,-hx,-hh__ (string): print help. Use `-help` or `-h` for basic options, `-ha` for advanced options, `-hx` for expert options and `-hh` for all. +
+
+__-h__,__-help,-ha,-hx,-hh__ (string): print help. Use `-help` or `-h` for basic options, `-ha` for advanced options, `-hx` for expert options and `-hh` for all. _Note: The `@` character can be used in place of the `*` character. String parameter can be:_ - empty: print command line options help @@ -94,41 +135,79 @@ _Note: The `@` character can be used in place of the `*` character. String param - FNAME.OPT: print option `OPT` in filter `FNAME` - OPT: look in filter names and options for `OPT` and suggest possible matches if none found. Use `-hx` to look for keyword in all option descriptions +
+
__-p__ (string): use indicated profile for the global GPAC config. If not found, config file is created. If a file path is indicated, this will load profile from that file. Otherwise, this will create a directory of the specified name and store new config there. The following reserved names create a temporary profile (not stored on disk): - 0: full profile - n: null profile disabling shared modules/filters and system paths in config (may break GUI and other filters) Appending `:reload` to the profile name will force recreating a new configuration file +
+
__-alias__ (string): assign a new alias or remove an alias. Can be specified several times. See [alias usage (-h alias)](#using-aliases) +
+
__-aliasdoc__ (string): assign documentation for a given alias (optional). Can be specified several times +
+
__-uncache__: revert all items in GPAC cache directory to their original name and server path +
+
__-js__ (string): specify javascript file to use as controller of filter session +
+
__-wc__: write all core options in the config file unless already set +
+
__-we__: write all file extensions in the config file unless already set (useful to change some default file extensions) +
+
__-wf__: write all filter options in the config file unless already set +
+
__-wfx__: write all filter options and all meta filter arguments in the config file unless already set (_large config file !_) +
+
__-xopt__: unrecognized options and filters declaration following this option are ignored - used to pass arguments to GUI +
+
__-creds__ (string): setup credentials as used by servers +
+
__-rv__: return absolute value of GPAC internal error instead of 1 when error +
The following libgpac core options allow customizing the filter session: +
__-dbg-edges__: log edges status in filter graph before dijkstra resolution (for debug). Edges are logged as edge_source(status(disable_depth), weight, src_cap_idx -> dst_cap_idx) +
+
__-full-link__: throw error if any PID in the filter graph cannot be linked +
+
__-no-dynf__: disable dynamically loaded filters +
+
__-no-block__ (Enum, default: __no__): disable blocking mode of filters - no: enable blocking mode - fanout: disable blocking on fan-out, unblocking the PID as soon as one of its destinations requires a packet - all: disable blocking +
+
__-no-reg__: disable regulation (no sleep) in session +
+
__-no-reassign__: disable source filter reassignment in PID graph resolution +
+
__-sched__ (Enum, default: __free__): set scheduler mode - free: lock-free queues except for task list (default) @@ -136,19 +215,44 @@ The following libgpac core options allow customizing the filter session: - freex: lock-free queues including for task lists (experimental) - flock: mutexes for queues even when no thread (debug mode) - direct: no threads and direct dispatch of tasks whenever possible (debug mode) +
+
__-max-chain__ (int, default: __6__): set maximum chain length when resolving filter links. Default value covers for _[ in -> ] dmx -> reframe -> decode -> encode -> reframe -> mx [ -> out]_. Filter chains loaded for adaptation (e.g. pixel format change) are loaded after the link resolution. Setting the value to 0 disables dynamic link resolution. You will have to specify the entire chain manually +
+
__-max-sleep__ (int, default: __50__): set maximum sleep time slot in milliseconds when regulation is enabled +
+
__-step-link__: load filters one by one when solvink a link instead of loading all filters for the solved path +
+
__-threads__ (int): set N extra thread for the session. -1 means use all available cores +
+
__-no-probe__: disable data probing on sources and relies on extension (faster load but more error-prone) +
+
__-no-argchk__: disable tracking of argument usage (all arguments will be considered as used) +
+
__-blacklist__ (string): blacklist the filters listed in the given string (comma-separated list). If first character is '-', this is a whitelist, i.e. only filters listed in the given string will be allowed +
+
__-no-graph-cache__: disable internal caching of filter graph connections. If disabled, the graph will be recomputed at each link resolution (lower memory usage but slower) +
+
__-no-reservoir__: disable memory recycling for packets and properties. This uses much less memory but stresses the system memory allocator much more +
+
__-buffer-gen__ (int, default: __1000__): default buffer size in microseconds for generic pids +
+
__-buffer-dec__ (int, default: __1000000__): default buffer size in microseconds for decoder input pids +
+
__-buffer-units__ (int, default: __1__): default buffer size in frames when timing is not available +
# Using Aliases The gpac command line can become quite complex when many sources or filters are used. In order to simplify this, an alias system is provided. @@ -162,7 +266,8 @@ When parsing arguments, the alias will be replace by its value. Example ``` gpac -alias="output aout vout" -``` +``` + This allows later audio and video playback using `gpac -i src.mp4 output` Aliases can use arguments from the command line. The allowed syntaxes are: @@ -188,22 +293,26 @@ Arguments not used by any aliases are kept on the command line, other ones are r Example ``` -alias="foo src=@{N} dst=test.mp4" -``` +``` + The command `gpac foo f1 f2` expands to `gpac src=f2 dst=test.mp4 f1` Example ``` -alias="list: inspect src=@{+:N}" -``` +``` + The command `gpac list f1 f2 f3` expands to `gpac inspect src=f1 src=f2 src=f3` Example ``` -alias="list inspect src=@{+2:N}" -``` +``` + The command `gpac list f1 f2 f3` expands to `gpac inspect src=f2 src=f3 f1` Example ``` -alias="plist aout vout flist:srcs=@{-,N}" -``` +``` + The command `gpac plist f1 f2 f3` expands to `gpac aout vout flist:srcs="f1,f2,f3"` Alias documentation can be set using `gpac -aliasdoc="NAME VALUE"`, with `NAME` the alias name and `VALUE` the documentation. @@ -243,7 +352,8 @@ Example [somedir] ru=foo rg=bar -``` +``` + The following keys are defined per directory, but may be ignored by the server depending on its operation mode: @@ -262,7 +372,8 @@ Example rg=bar [d1/d2] ru=foo -``` +``` + With this configuration: - the directory `d1` will be readable by all members of group `bar` @@ -288,12 +399,14 @@ The last run can be omitted. Example ``` gpac -dl -np -i SRC reframer -g -rl -g inspect -g -rl -``` +``` + This will load SRC and reframer, print the graph (no connection), relink SRC, print the graph (connection to reframer), insert inspect, print the graph (no connection), relink reframer and run. No play event is sent here. Example ``` gpac -dl -np -i SRC reframer inspect:deep -g -rl=2 -g -rl -se -``` +``` + This will load SRC, reframer and inspect, print the graph (no connection), relink SRC, print the graph (connection to reframer), print the graph (no connection), relink reframer, send play and run. Linking can be done once filters are loaded, using the syntax `@F@SRC` or `@@F@SRC`: @@ -306,27 +419,52 @@ Sources MUST be set before relinking outputs using (-rl)[]. Example ``` gpac -dl -i SRC F1 F2 [...] @1@2 @0@2 -``` +``` + This will set SRC as source to F1 and SRC as source to F2 after loading all filters. The following options are used in defer mode: +
__-dl__: enable defer linking mode for step-by-step graph building tests +
+
__-np__: prevent play event from sinks +
+
__-rl[=F]__ (string): relink outputs of filter `F` (default 1) +
+
__-wl[=F]__ (string): same as `-rl` but does not flush session) +
+
__-pi=[+|-][F[:i]]__ (string): print PID properties (all or of index `i`) of filter `F` (default 0) - if prefixed with `-`: only list PIDs - if prefixed with `+`: also print PID info +
+
__-pl=[+][F[:i]]@NAME__ (string): probe filter chain from filter `F` (default 0) to the given filter `NAME`: - if prefixed with `+`: print all known chains and their priorities +
+
__-pd=[F[:i]]__ (string): print possible PID destinations (all or of index `i`) of filter `F` (default 0) +
+
__-f__: flush session until no more tasks +
+
__-g__: print graph +
+
__-s__: print stats +
+
__-se__: send PLAY event from sinks (only done once) +
+
__-m__ (string): print message +
diff --git a/docs/Filters/gsfdmx.md b/docs/Filters/gsfdmx.md index fa3a6616..801281f1 100644 --- a/docs/Filters/gsfdmx.md +++ b/docs/Filters/gsfdmx.md @@ -12,10 +12,18 @@ This allows either reading a session saved to file, or receiving the state/data The stream format can be encrypted in AES 128 CBC mode, in which case the demultiplexing filter must be given a 128 bit key. -# Options +# Options {.no-collapse} +
__key__ (mem): key for decrypting packets +
+
__magic__ (str): magic string to check in setup packet +
+
__mq__ (uint, default: _4_): set max packet queue length for loss detection. 0 will flush incomplete packet when a new one starts +
+
__pad__ (uint, default: _0_, minmax: 0-255): byte value used to pad lost packets +
diff --git a/docs/Filters/gsfmx.md b/docs/Filters/gsfmx.md index 038d4c5c..c7e54543 100644 --- a/docs/Filters/gsfmx.md +++ b/docs/Filters/gsfmx.md @@ -26,7 +26,8 @@ The [skp](#skp) option may also be used to specify which property to drop: Example ``` skp="4CC1,Name2 -``` +``` + This will remove properties of type `4CC1` and properties (built-in or not) of name `Name2`. # File mode @@ -35,13 +36,15 @@ By default the filter only accepts framed media streams as input PID, not files. Example ``` gpac -i source.mp4 gsfmx:dst=manifest.mpd -o dump.gsf -``` +``` + This will DASH the source and store every files produced as PIDs in the GSF mux. In order to demultiplex such a file, the `gsfdmx`filter will likely need to be explicitly loaded: Example ``` gpac -i mux.gsf gsfdmx -o dump/$File$:dynext -``` +``` + This will extract all files from the GSF mux. By default when working in file mode, the filter only accepts PIDs of type `file` as input. @@ -49,31 +52,64 @@ To allow a mix of files and streams, use [mixed](#mixed): Example ``` gpac -i source.mp4 gsfmx:dst=manifest.mpd:mixed -o dump.gsf -``` +``` + This will DASH the source, store the manifest file and the media streams with their packet properties in the GSF mux. -# Options +# Options {.no-collapse} -__sigsn__ (bool, default: _false_): signal packet sequence number after header field and before size field. Sequence number is per PID, encoded on 16 bits. Header packet does not have a SN +
+__sigsn__ (bool, default: _false_): signal packet sequence number after header field and before size field. Sequence number is per PID, encoded on 16 bits. Header packet does not have a SN +
+
__sigdur__ (bool, default: _true_): signal duration +
+
__sigbo__ (bool, default: _false_): signal byte offset +
+
__sigdts__ (bool, default: _true_): signal decoding timestamp +
+
__dbg__ (enum, default: _no_): set debug mode - no: disable debug - nodata: force packet size to 0 - nopck: skip packet +
-__key__ (mem): encrypt packets using given key -__IV__ (mem): set IV for encryption - a constant IV is used to keep packet overhead small (cbcs-like) +
+__key__ (mem): encrypt packets using given key +
+
+__IV__ (mem): set IV for encryption - a constant IV is used to keep packet overhead small (cbcs-like) +
+
__pattern__ (frac, default: _1/0_): set nb_crypt / nb_skip block pattern. default is all encrypted +
+
__mpck__ (uint, default: _0_): set max packet size. 0 means no fragmentation (each AU is sent in one packet) +
+
__magic__ (str): magic string to append in setup packet +
+
__skp__ (str): comma separated list of PID property names to skip +
+
__minp__ (bool, default: _false_): include only the minimum set of properties required for stream processing +
+
__crate__ (dbl, default: _0_): carousel period for tune-in info in seconds +
+
__ext__ (str): file extension for file mode +
+
__dst__ (str): target URL in file mode +
+
__mixed__ (bool, default: _false_): allow GSF to contain both files and media streams +
diff --git a/docs/Filters/hevcmerge.md b/docs/Filters/hevcmerge.md index ed886194..8cd99211 100644 --- a/docs/Filters/hevcmerge.md +++ b/docs/Filters/hevcmerge.md @@ -44,7 +44,8 @@ This indicates that `src1` contains a video located at 0,0, with a size of 640x4 Example ``` src2:SRD=640x0x640x480:SRDRef=1280x720 -``` +``` + This indicates that `src1` contains a video located at 640,0, with a size of 640x480 pixels in a virtual source of 1280x720 pixels. Each merged input is described by 8 integers in the output `SRDMap`: @@ -64,12 +65,17 @@ Alternatively to using `SRD` and `SRDRef`, it is possible to specify `CropOrigin Example ``` src1:CropOrigin=0x0 src1:CropOrigin=640x0 -``` +``` + Assuming the two sources are encoded at 320x240 and merged as src1 above src2, the output will be a 320x480 video with a `SRDMap` of `{0,0,320,240,0,0,320,240,640,0,320,240,0,240,320,240}` -# Options +# Options {.no-collapse} +
__strict__ (bool, default: _false_): strict comparison of SPS and PPS of input PIDs +
+
__mrows__ (bool, default: _false_): signal multiple rows in tile grid when possible +
diff --git a/docs/Filters/httpin.md b/docs/Filters/httpin.md index d28ae49a..9691461a 100644 --- a/docs/Filters/httpin.md +++ b/docs/Filters/httpin.md @@ -14,10 +14,15 @@ The filter supports both http and https schemes, and will attempt reconnecting a _Note: Unless disabled at session level (see [-no-probe](core_options/#no-probe) ), file extensions are usually ignored and format probing is done on the first data block._ -# Options +# Options {.no-collapse} -__src__ (cstr): URL of source content +
+__src__ (cstr): URL of source content +
+
__block_size__ (uint, default: _100000_): block size used to read file +
+
__cache__ (enum, default: _none_): set cache mode - auto: cache to disk if content length is known, no cache otherwise @@ -27,9 +32,18 @@ _Note: Unless disabled at session level (see [-no-probe](core_options/#no-probe) - mem_keep: stores to memory, keep after session is reassigned but move to `mem` after first download - none: no cache - none_keep: stores to memory, keep after session is reassigned but move to `none` after first download - -__range__ (lfrac, default: _0-0_): set byte range, as fraction -__ext__ (cstr): override file extension -__mime__ (cstr): set file mime type +
+ +
+__range__ (lfrac, default: _0-0_): set byte range, as fraction +
+
+__ext__ (cstr): override file extension +
+
+__mime__ (cstr): set file mime type +
+
__blockio__ (bool, default: _false_): use blocking IO +
diff --git a/docs/Filters/httpout.md b/docs/Filters/httpout.md index 878a9a61..336b2cb6 100644 --- a/docs/Filters/httpout.md +++ b/docs/Filters/httpout.md @@ -39,7 +39,8 @@ Example ``` [foodir] name=bar -``` +``` + Content `RES` of this directory is exposed as `http://SERVER/bar/RES`. Listing can be enabled on server using [dlist](#dlist). @@ -58,19 +59,22 @@ PUT and POST methods are only supported if a write directory is specified by [wd Example ``` gpac httpout:rdirs=outcoming -``` +``` + This sets up a read-only server. Example ``` gpac httpout:wdir=incoming -``` +``` + This sets up a write-only server. Example ``` gpac httpout:rdirs=outcoming:wdir=incoming:port=8080 -``` +``` + This sets up a read-write server running on [port](#port) 8080. @@ -82,13 +86,15 @@ This mode is mostly useful to setup live HTTP streaming of media sessions such a Example ``` gpac -i MP3_SOURCE -o http://localhost/live.mp3 --hold -``` +``` + In this example, the server waits for client requests on `/live.mp3` and will then push each input packet to all connected clients. If the source is not real-time, you can inject a reframer filter performing realtime regulation. Example ``` gpac -i MP3_SOURCE reframer:rt=on -o http://localhost/live.mp3 -``` +``` + In this example, the server will push each input packet to all connected clients, or trash the packet if no connected clients. In this mode, ICECast meta-data can be inserted using [ice](#ice). The default inserted values are `ice-audio-info`, `icy-br`, `icy-pub` (set to 1) and `icy-name` if input `ServiceName` property is set. @@ -96,7 +102,8 @@ The server will also look for any property called `ice-*` on the input PID and i Example ``` gpac -i source.mp3:#ice-Genre=CoolRock -o http://IP/live.mp3 --ice -``` +``` + This will inject the header `ice-Genre: CoolRock` in the response. Once one complete input file is sent, it is no longer available for download unless [reopen](#reopen) is set and input PID is not over. @@ -121,7 +128,8 @@ This mode is typically used for origin server in HAS sessions where clients may Example ``` gpac -i SOURCE reframer:rt=on -o http://localhost:8080/live.mpd --rdirs=temp --dmode=dynamic --cdur=0.1 -``` +``` + In this example, a real-time dynamic DASH session with chunks of 100ms is created, writing files to `temp`. A client connecting to the live edge will receive segments as they are produced using HTTP chunk transfer. The server can store incoming files to memory mode by setting the read directory to `gmem`. @@ -144,7 +152,8 @@ The filter uses no read or write directories in this mode. Example ``` gpac -i SOURCE -o http://targethost:8080/live.mpd:gpac:hmode=push -``` +``` + In this example, the filter will send PUT methods to the server running on [port](#port) 8080 at `targethost` location (IP address or name). @@ -156,7 +165,8 @@ The filter uses no read or write directories in this mode, and uploaded data is Example ``` gpac httpout:hmode=source vout aout -``` +``` + In this example, the filter will try to play uploaded files through video and audio output. @@ -178,7 +188,8 @@ When running in server mode, multiple HTTP outputs with same URL/port may be use Example ``` gpac -i dash.mpd dashin:forward=file:FID=D1 dashin:forward=segb:FID=D2 -o http://localhost:80/live.mpd:SID=D1:rdirs=dash -o http://localhost:80/live_rw.mpd:SID=D2:sigfrag -``` +``` + This will: - load the HTTP server and forward (through `D1`) the dash session to this server using `live.mpd` as manifest name @@ -186,50 +197,121 @@ This will: -# Options +# Options {.no-collapse} -__dst__ (cstr): location of destination resource -__port__ (uint, default: _0_): server port +
+__dst__ (cstr): location of destination resource +
+
+__port__ (uint, default: _0_): server port +
+
__ifce__ (str): default network interface to use -__rdirs__ (strl): list of directories to expose for read -__wdir__ (str): directory to expose for write -__cert__ (str): certificate file in PEM format to use for TLS mode -__pkey__ (str): private key file in PEM format to use for TLS mode +
+
+__rdirs__ (strl): list of directories to expose for read +
+
+__wdir__ (str): directory to expose for write +
+
+__cert__ (str): certificate file in PEM format to use for TLS mode +
+
+__pkey__ (str): private key file in PEM format to use for TLS mode +
+
__block_size__ (uint, default: _10000_): block size used to read and write TCP socket -__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences +
+
+__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences +
+
__close__ (bool, default: _false_): close HTTP connection after each request +
+
__maxc__ (uint, default: _100_): maximum number of connections, 0 is unlimited +
+
__maxp__ (uint, default: _6_): maximum number of connections for one peer (0 is unlimited) +
+
__cache_control__ (str): specify the `Cache-Control` string to add (`none` disable cache control and ETag) +
+
__hold__ (bool, default: _false_): hold packets until one client connects +
+
__hmode__ (enum, default: _default_): filter operation mode, ignored if [wdir](#wdir) is set - default: run in server mode - push: run in client mode using PUT or POST - source: use server as source filter on incoming PUT/POST +
+
__timeout__ (uint, default: _30_): timeout in seconds for persistent connections (0 disable timeout) +
+
__ext__ (cstr): set extension for graph resolution, regardless of file extension +
+
__mime__ (cstr): set mime type for graph resolution +
+
__quit__ (bool, default: _false_): exit server once all input PIDs are done and client disconnects (for test purposes) +
+
__post__ (bool, default: _false_): use POST instead of PUT for uploading files +
+
__dlist__ (bool, default: _false_): enable HTML listing for GET requests on directories +
+
__sutc__ (bool, default: _false_): insert server UTC in response headers as `Server-UTC: VAL_IN_MS` +
+
__cors__ (enum, default: _auto_): insert CORS header allowing all domains - off: disable CORS - on: enable CORS - auto: enable CORS when `Origin` is found in request +
+
__reqlog__ (str): provide short log of the requests indicated in this option (comma separated list, `*` for all) regardless of HTTP log settings. Value `REC` logs file writing start/end. If prefix `-` is set, do not log request end +
+
__ice__ (bool, default: _false_): insert ICE meta-data in response headers in sink mode +
+
__max_client_errors__ (uint, default: _20_): force disconnection after specified number of consecutive errors from HTTTP 1.1 client (ignored in H/2 or when `close` is set) +
+
__max_cache_segs__ (sint, default: _5_): maximum number of segments cached per HAS quality (see filter help) +
+
__reopen__ (bool, default: _false_): in server mode with no read dir, accept requests on files already over but with input pid not in end of stream +
+
__max_async_buf__ (uint, default: _100000_): maximum async buffer size in bytes when sharing output over multiple connection without file IO +
+
__blockio__ (bool, default: _false_): use blocking IO in push or source mode or in server mode with no read dir +
+
__ka__ (bool, default: _true_): keep input alive if failure in push mode +
+
__hdrs__ (strl): additional HTTP headers to inject, even values are names, odd values are values +
+
__js__ (str): javascript logic for server +
+
__zmax__ (uint, default: _50000_): maximum uncompressed size allowed for gzip or deflate compression for text files (only enabled if client indicates it), 0 will disable compression +
+
+__cte__ (bool, default: _true_): use chunked transfer-encoding mode when possible +
diff --git a/docs/Filters/inspect.md b/docs/Filters/inspect.md index 020e6f7a..24bef255 100644 --- a/docs/Filters/inspect.md +++ b/docs/Filters/inspect.md @@ -68,7 +68,8 @@ When the option is not present, all properties are dumped. Otherwise, only prope Example ``` fmt="PID $pid.ID$ packet $pn$ DTS $dts$ CTS $cts$ $lf$" -``` +``` + This dumps packet number, cts and dts as follows: `PID 1 packet 10 DTS 100 CTS 108 \n` An unrecognized keyword or missing property will resolve to an empty string. @@ -84,13 +85,15 @@ If real-time consumption is required, a reframer filter must be setup before the Example ``` gpac -i SRC reframer:rt=on inspect:buffer=10000:rbuffer=1000:mbuffer=30000:speed=2 -``` +``` + This will play the session at 2x speed, using 30s of maximum buffering, consuming packets after 10s of media are ready and rebuffering if less than 1s of media. -# Options +# Options {.no-collapse} -__log__ (str, default: _stdout_, Enum: _any|stderr|stdout|GLOG|TL|null): set probe log filename +
+__log__ (str, default: _stdout_, Enum: _any|stderr|stdout|GLOG|TL|null): set probe log filename - _any: target file path and name - stderr: dump to stderr @@ -98,42 +101,90 @@ This will play the session at 2x speed, using 30s of maximum buffering, consumin - GLOG: use GPAC logs `app@info` - TL: use GPAC log tool `TL` at level `info` - null: silent mode +
-__mode__ (enum, default: _pck_): dump mode +
+__mode__ (enum, default: _pck_): dump mode - pck: dump full packet - blk: dump packets before reconstruction - frame: force reframer - raw: dump source packets without demultiplexing +
+
__interleave__ (bool, default: _true_): dump packets as they are received on each PID. If false, logs are reported for each PID at end of session +
+
__deep__ (bool, default: _false_, updatable): dump packets along with PID state change, implied when [fmt](#fmt) is set +
+
__props__ (bool, default: _true_, updatable): dump packet properties, ignored when [fmt](#fmt) is set +
+
__dump_data__ (bool, default: _false_, updatable): enable full data dump (_very large output_), ignored when [fmt](#fmt) is set +
+
__fmt__ (str, updatable): set packet dump format +
+
__hdr__ (bool, default: _true_): print a header corresponding to fmt string without '$' or "pid" +
+
__allp__ (bool, default: _false_): analyse for the entire duration, rather than stopping when all PIDs are found +
+
__info__ (bool, default: _false_, updatable): monitor PID info changes +
+
__full__ (bool, default: _false_, updatable): full dump of PID properties (always on if XML) +
+
__pcr__ (bool, default: _false_, updatable): dump M2TS PCR info -__speed__ (dbl, default: _1.0_): set playback command speed. If negative and start is 0, start is set to -1 -__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__dur__ (frac, default: _0/0_): set inspect duration +
+
+__speed__ (dbl, default: _1.0_): set playback command speed. If negative and start is 0, start is set to -1 +
+
+__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__dur__ (frac, default: _0/0_): set inspect duration +
+
__analyze__ (enum, default: _off_, updatable): analyze sample content (NALU, OBU), similar to `-bsdbg` option of reframer filters - off: no analyzing - on: simple analyzing - bs: log bitstream syntax (all elements read from bitstream) - full: log bitstream syntax and bit sizes signaled as `(N)` after field value, except 1-bit fields (omitted) - -__xml__ (bool, default: _false_, updatable): use xml formatting (implied if (-analyze]() is set) and disable [fmt](#fmt) -__crc__ (bool, default: _false_, updatable): dump crc of samples of subsamples (NALU or OBU) when analyzing +
+ +
+__xml__ (bool, default: _false_, updatable): use xml formatting (implied if (-analyze]() is set) and disable [fmt](#fmt) +
+
+__crc__ (bool, default: _false_, updatable): dump crc of samples of subsamples (NALU or OBU) when analyzing +
+
__fftmcd__ (bool, default: _false_, updatable): consider timecodes use ffmpeg-compatible signaling rather than QT compliant one -__dtype__ (bool, default: _false_, updatable): dump property type +
+
+__dtype__ (bool, default: _false_, updatable): dump property type +
+
__buffer__ (uint, default: _0_): set playback buffer in ms -__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer -__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
+__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer +
+
+__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
__stats__ (bool, default: _false_): compute statistics for PIDs +
+
__test__ (enum, default: _no_, updatable): skip predefined set of properties, used for test mode - no: no properties skipped @@ -144,5 +195,6 @@ This will play the session at 2x speed, using 30s of maximum buffering, consumin - encx: same as encode and skip bitrates, media data size and co - nocrc: disable packet CRC dump - nobr: skip bitrate +
diff --git a/docs/Filters/jpgenc.md b/docs/Filters/jpgenc.md index 9e9c3c6d..f55fce01 100644 --- a/docs/Filters/jpgenc.md +++ b/docs/Filters/jpgenc.md @@ -8,13 +8,17 @@ This filter may be automatically loaded during graph resolution. This filter encodes a single uncompressed video PID to JPEG using libjpeg. -# Options +# Options {.no-collapse} +
__dctmode__ (enum, default: _fast_): type of DCT used - slow: precise but slow integer DCT - fast: less precise but faster integer DCT - float: float DCT +
-__quality__ (uint, default: _100_, minmax: 0-100, updatable): compression quality +
+__quality__ (uint, default: _100_, minmax: 0-100, updatable): compression quality +
diff --git a/docs/Filters/jsf.md b/docs/Filters/jsf.md index 3802832f..4df05664 100644 --- a/docs/Filters/jsf.md +++ b/docs/Filters/jsf.md @@ -10,8 +10,12 @@ This filter runs a javascript file specified in [js](#js) defining a new JavaScr For more information on how to use JS filters, please check https://wiki.gpac.io/Howtos/jsf/jsfilter -# Options +# Options {.no-collapse} -__js__ (cstr): location of script source -__*__ (str): any possible options defined for the script (see `gpac -hx jsf:js=$YOURSCRIPT` or `gpac -hx $YOURSCRIPT`) +
+__js__ (cstr): location of script source +
+
+__*__ (str): any possible options defined for the script (see `gpac -hx jsf:js=$YOURSCRIPT` or `gpac -hx $YOURSCRIPT`) +
diff --git a/docs/Filters/m2tsdmx.md b/docs/Filters/m2tsdmx.md index 21cffbf5..0eb3c0af 100644 --- a/docs/Filters/m2tsdmx.md +++ b/docs/Filters/m2tsdmx.md @@ -8,11 +8,21 @@ This filter may be automatically loaded during graph resolution. This filter demultiplexes MPEG-2 Transport Stream files/data into a set of media PIDs and frames. -# Options +# Options {.no-collapse} +
__temi_url__ (cstr): force TEMI URL +
+
__dsmcc__ (bool, default: _no_): enable DSMCC receiver +
+
__seeksrc__ (bool, default: _true_): seek local source file back to origin once all programs are setup +
+
__sigfrag__ (bool, default: _false_): signal segment boundaries on output packets for DASH or HLS sources +
+
__dvbtxt__ (bool, default: _false_): export DVB teletext streams +
diff --git a/docs/Filters/m2tsmx.md b/docs/Filters/m2tsmx.md index 1ac905f5..d423e395 100644 --- a/docs/Filters/m2tsmx.md +++ b/docs/Filters/m2tsmx.md @@ -52,27 +52,32 @@ Each TEMI description is formatted as ID_OR_URL or #OPT1[#OPT2]#ID_OR_URL. Optio 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.__ @@ -95,50 +100,108 @@ The value can either be a 4CC or a string, indicating the MP2G-2 TS Registration In LATM mux mode, the decoder configuration is inserted at the given [repeat_rate](#repeat_rate) or `CarouselRate` PID property if defined. -# Options +# Options {.no-collapse} +
__breq__ (uint, default: _100_): buffer requirements in ms for input PIDs -__pmt_id__ (uint, default: _100_): define the ID of the first PMT to use in the mux -__rate__ (uint, default: _0_): target rate in bps of the multiplex. If not set, variable rate is used -__pmt_rate__ (uint, default: _200_): interval between PMT in ms -__pat_rate__ (uint, default: _200_): interval between PAT in ms +
+
+__pmt_id__ (uint, default: _100_): define the ID of the first PMT to use in the mux +
+
+__rate__ (uint, default: _0_): target rate in bps of the multiplex. If not set, variable rate is used +
+
+__pmt_rate__ (uint, default: _200_): interval between PMT in ms +
+
+__pat_rate__ (uint, default: _200_): interval between PAT in ms +
+
__first_pts__ (luint, default: _0_): force PTS value of first packet, in 90kHz +
+
__pcr_offset__ (luint, default: _-1_): offset all timestamps from PCR by V, in 90kHz (default value is computed based on input media) +
+
__mpeg4__ (enum, default: _none_): force usage of MPEG-4 signaling (IOD and SL Config) - none: disables 4on2 - full: sends AUs as SL packets over section for OD, section/pes for scene (cf bifs_pes) - scene: sends only scene streams as 4on2 but uses regular PES without SL for audio and video +
+
__pmt_version__ (uint, default: _200_): set version number of the PMT +
+
__disc__ (bool, default: _false_): set the discontinuity marker for the first packet of each stream +
+
__repeat_rate__ (uint, default: _0_): interval in ms between two carousel send for MPEG-4 systems (overridden by `CarouselRate` PID property if defined) +
+
__repeat_img__ (uint, default: _0_): interval in ms between re-sending (as PES) of single-image streams (if 0, image data is sent once only) +
+
__max_pcr__ (uint, default: _100_): set max interval in ms between 2 PCR -__nb_pack__ (uint, default: _4_): pack N TS packets in output packets +
+
+__nb_pack__ (uint, default: _4_): pack N TS packets in output packets +
+
__pes_pack__ (enum, default: _audio_): set AU to PES packing mode - audio: will pack only multiple audio AUs in a PES - none: make exactly one AU per PES - all: will pack multiple AUs per PES for all streams +
-__realtime__ (bool, default: _false_): use real-time output +
+__realtime__ (bool, default: _false_): use real-time output +
+
__bifs_pes__ (enum, default: _off_): select BIFS streams packetization (PES vs sections) - on: uses BIFS PES - off: uses BIFS sections - copy: uses BIFS PES but removes timestamps in BIFS SL and only carries PES timestamps +
+
__flush_rap__ (bool, default: _false_): force flushing mux program when RAP is found on video, and injects PAT and PMT before the next video PES begin +
+
__pcr_only__ (bool, default: _false_): enable PCR-only TS packets -__pcr_init__ (lsint, default: _-1_): set initial PCR value for the programs. A negative value means random value is picked -__sid__ (uint, default: _0_): set service ID for the program -__name__ (str): set service name for the program -__provider__ (str): set service provider name for the program -__sdt_rate__ (uint, default: _0_): interval in ms between two DVB SDT tables (if 0, SDT is disabled) +
+
+__pcr_init__ (lsint, default: _-1_): set initial PCR value for the programs. A negative value means random value is picked +
+
+__sid__ (uint, default: _0_): set service ID for the program +
+
+__name__ (str): set service name for the program +
+
+__provider__ (str): set service provider name for the program +
+
+__sdt_rate__ (uint, default: _0_): interval in ms between two DVB SDT tables (if 0, SDT is disabled) +
+
__temi__ (str): insert TEMI time codes in adaptation field +
+
__log_freq__ (uint, default: _500_): delay between logs for realtime mux +
+
__latm__ (bool, default: _false_): use LATM AAC encapsulation instead of regular ADTS +
+
__subs_sidx__ (sint, default: _-1_): number of subsegments per sidx (negative value disables sidx) +
+
__keepts__ (bool, default: _false_): keep cts/dts untouched and adjust PCR accordingly, used to keep TS unmodified when dashing +
diff --git a/docs/Filters/mcdec.md b/docs/Filters/mcdec.md index bfd409e5..295d09cc 100644 --- a/docs/Filters/mcdec.md +++ b/docs/Filters/mcdec.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter decodes video streams using hardware decoder on android devices -# Options +# Options {.no-collapse} -__disable_gl__ (bool, default: _false_): disable OpenGL texture transfer +
+__disable_gl__ (bool, default: _false_): disable OpenGL texture transfer +
diff --git a/docs/Filters/mp4dmx.md b/docs/Filters/mp4dmx.md index 3ef146c2..7b13c8ce 100644 --- a/docs/Filters/mp4dmx.md +++ b/docs/Filters/mp4dmx.md @@ -42,60 +42,108 @@ and an enhancement decoder config. __Warning: smode=splitx will result in extractor NAL units still present in the output bitstream, which shall only be true if the output is ISOBMFF based__ -# Options +# Options {.no-collapse} +
__src__ (cstr): local file name of source content (only used when explicitly loading the filter) +
+
__allt__ (bool, default: _false_): load all tracks even if unknown media type +
+
__edits__ (enum, default: _auto_): do not use edit lists - auto: track delay and no edit list when possible - no: ignore edit list - strict: use edit list even if only signaling a delay +
+
__itt__ (bool, default: _false_): convert all items of root meta into a single PID +
+
__itemid__ (bool, default: _true_): keep item IDs in PID properties +
+
__smode__ (enum, default: _split_): load mode for scalable/tile tracks - split: each track is declared, extractors are removed - splitx: each track is declared, extractors are kept - single: a single track is declared (highest level for scalable, tile base for tiling) +
+
__alltk__ (bool, default: _false_): declare disabled tracks +
+
__frame_size__ (uint, default: _1024_): frame size for raw audio samples (dispatches frame_size samples per packet) +
+
__expart__ (bool, default: _false_): expose cover art as a dedicated video PID +
+
__sigfrag__ (bool, default: _false_): signal fragment and segment boundaries of source on output packets, fails if source is not fragmented +
+
__tkid__ (str): declare only track based on given param - integer value: declares track with the given ID - audio: declares first audio track - video: declares first video track - 4CC: declares first track with matching 4CC for handler type +
+
__stsd__ (uint, default: _0_): only extract sample mapped to the given sample description index (0 means extract all) +
+
__nocrypt__ (bool): signal encrypted tracks as non encrypted (mostly used for export) +
+
__mstore_size__ (uint, default: _1000000_): target buffer size in bytes when reading from memory stream (pipe etc...) +
+
__mstore_purge__ (uint, default: _50000_): minimum size in bytes between memory purges when reading from memory stream, 0 means purge as soon as possible +
+
__mstore_samples__ (uint, default: _50_): minimum number of samples to be present before purging sample tables when reading from memory stream (pipe etc...), 0 means purge as soon as possible +
+
__strtxt__ (bool, default: _false_): load text tracks (apple/tx3g) as MPEG-4 streaming text tracks +
+
__xps_check__ (enum, default: _auto_): parameter sets extraction mode from AVC/HEVC/VVC samples - keep: do not inspect sample (assumes input file is compliant when generating DASH/HLS/CMAF) - rem: removes all inband xPS and notify configuration changes accordingly - auto: resolves to `keep` for `smode=splitx` (dasher mode), `rem` otherwise +
+
__nodata__ (enum, default: _no_): control sample data loading - no: regular load - yes: skip data loading - fake: allocate sample but no data copy +
+
__lightp__ (bool, default: _false_): load minimal set of properties +
+
__initseg__ (str): local init segment name when input is a single ISOBMFF segment +
+
__ctso__ (sint): value to add to CTS offset for tracks using negative ctts - set to `-1` to use the `cslg` box info or the minimum cts offset present in the track - set to `-2` to use the minimum cts offset present in the track (`cslg` ignored) +
+
__norw__ (bool, default: _false_): skip reformating of samples - should only be used when rewriting fragments +
+
__keepc__ (bool, default: _false_): keep corrupted samples - should only be used in multicast modes +
diff --git a/docs/Filters/mp4mx.md b/docs/Filters/mp4mx.md index 6c4be772..36af75ab 100644 --- a/docs/Filters/mp4mx.md +++ b/docs/Filters/mp4mx.md @@ -15,13 +15,15 @@ To prevent source items to be multiplexed as items, use [-itemid](mp4dmx/#itemid Example ``` gpac -i source.mp4:itemid=false -o file.mp4 -``` +``` + To force non-item streams to be multiplexed as items, use _#ItemID_ option on that PID: Example ``` gpac -i source.jpg:#ItemID=1 -o file.mp4 -``` +``` + # Storage @@ -45,12 +47,14 @@ Per PID box patch can be specified through the PID property `boxpatch`. Example ``` gpac -i source:#boxpatch=myfile.xml -o mux.mp4 -``` +``` + Per Item box patch can be specified through the PID property `boxpatch`. Example ``` gpac -i source:1ItemID=1:#boxpatch=myfile.xml -o mux.mp4 -``` +``` + The box patch is applied before writing the initial `moov box in fragmented mode, or when writing the complete file otherwise.` The box patch can either be a filename or the full XML string. @@ -84,7 +88,8 @@ Example ``` gpac -i src.mp4:#udta_tagc='My Awesome Tag' -o tag.mp4 gpac -i src.mp4:#mudtab=data@box.bin -o tag.mp4 -``` +``` + # Custom sample group descriptions and sample auxiliary info @@ -112,7 +117,8 @@ The filter watches the property `DSIWrap` (4CC as int or string) on incoming PID Example ``` -i unkn.mkv:#ISOMSubtype=VIUK:#DSIWrap=cfgv -o t.mp4 -``` +``` + This will wrap the unknown stream using `VIUK` code point in `stsd` and wrap any decoder configuration data in a `cfgv` box. If [pad_sparse](#pad_sparse) is set, the filter watches the property `Sparse` on incoming PID to decide whether empty packets should be injected to keep packet duration info. @@ -127,32 +133,49 @@ The default media type used for a PID can be overriden using property `StreamSub Example ``` -i src.srt:#StreamSubtype=sbtl [-i ...] -o test.mp4 -``` +``` + This will force the text stream to use `sbtl` handler type instead of default `text` one. Subtitle streams may be used as chapters by setting the property `IsChap` on the desired PID. Example ``` -i src.srt:#IsChap [-i ...] -o test.mp4 -``` +``` + This will force the text stream to be used as a QT chapter track. -# Options +# Options {.no-collapse} +
__m4sys__ (bool, default: _false_): force MPEG-4 Systems signaling of tracks +
+
__dref__ (bool, default: _false_): only reference data from source file - not compatible with all media sources +
+
__ctmode__ (enum, default: _auto_): set composition offset mode for video tracks - auto: if fragmenting an ISOBMFF source, use source settings otherwise resolve to `edit` - edit: uses edit lists to shift first frame to presentation time 0 - noedit: ignore edit lists and does not shift timeline - negctts: uses ctts v1 with possibly negative offsets and no edit lists +
-__dur__ (frac, default: _0_): only import the specified duration. If negative, specify the number of coded frames to import +
+__dur__ (frac, default: _0_): only import the specified duration. If negative, specify the number of coded frames to import +
+
__pack3gp__ (uint, default: _1_): pack a given number of 3GPP audio frames in one sample +
+
__importer__ (bool, default: _false_): compatibility with old importer, displays import progress +
+
__pack_nal__ (bool, default: _false_): repack NALU size length to minimum possible size for NALU-based video (AVC/HEVC/...) -__xps_inband__ (enum, default: _no_): use inband (in sample data) parameter set for NALU-based video (AVC/HEVC/...) +
+
+__xps_inband__ (enum, default: _no_): use inband (in sample data) parameter set for NALU-based video (AVC/HEVC/...) - no: parameter sets are not inband, several sample descriptions might be created - pps: picture parameter sets are inband, all other parameter sets are in sample description @@ -160,8 +183,10 @@ This will force the text stream to be used as a QT chapter track. - both: parameter sets are inband, signaled as inband, and also first set is kept in sample description - mix: creates non-standard files using single sample entry with first PSs found, and moves other PS inband - auto: keep source config, or defaults to no if source is not ISOBMFF +
-__store__ (enum, default: _inter_): file storage mode +
+__store__ (enum, default: _inter_): file storage mode - inter: perform precise interleave of the file using [cdur](#cdur) (requires temporary storage of all media) - flat: write samples as they arrive and `moov` at end (fastest mode) @@ -169,87 +194,163 @@ This will force the text stream to be used as a QT chapter track. - tight: uses per-sample interleaving of all tracks (requires temporary storage of all media) - frag: fragments the file using cdur duration - sfrag: fragments the file using cdur duration but adjusting to start with SAP1/3 +
-__cdur__ (frac, default: _-1/1_): chunk duration for flat and interleaving modes or fragment duration for fragmentation modes +
+__cdur__ (frac, default: _-1/1_): chunk duration for flat and interleaving modes or fragment duration for fragmentation modes - 0: no specific interleaving but moov first - negative: defaults to 1.0 unless overridden by storage profile +
+
__moovts__ (sint, default: _600_): timescale to use for movie. A negative value picks the media timescale of the first track added +
+
__moof_first__ (bool, default: _true_): generate fragments starting with moof then mdat +
+
__abs_offset__ (bool, default: _false_): use absolute file offset in fragments rather than offsets from moof +
+
__fsap__ (bool, default: _true_): split truns in video fragments at SAPs to reduce file size +
+
__subs_sidx__ (sint, default: _-1_): number of subsegments per sidx - 0: single sidx - >0: hierarchical or daisy-chained sidx - <0: disables sidx - -2: removes sidx if present in source PID +
+
__m4cc__ (str): 4 character code of empty box to append at the end of a segment (DASH mode) or of a fragment (non-DASH mode) +
+
__chain_sidx__ (bool, default: _false_): use daisy-chaining of SIDX -__msn__ (uint, default: _1_): sequence number of first moof to N -__msninc__ (uint, default: _1_): sequence number increase between `moof` boxes -__tfdt__ (lfrac, default: _0_): set initial decode time (`tfdt`) of first traf -__tfdt_traf__ (bool, default: _false_): force `tfdt` box in each traf -__nofragdef__ (bool, default: _false_): disable default flags in fragments +
+
+__msn__ (uint, default: _1_): sequence number of first moof to N +
+
+__msninc__ (uint, default: _1_): sequence number increase between `moof` boxes +
+
+__tfdt__ (lfrac, default: _0_): set initial decode time (`tfdt`) of first traf +
+
+__tfdt_traf__ (bool, default: _false_): force `tfdt` box in each traf +
+
+__nofragdef__ (bool, default: _false_): disable default flags in fragments +
+
__straf__ (bool, default: _false_): use a single traf per moof (smooth streaming and co) +
+
__strun__ (bool, default: _false_): use a single trun per traf (smooth streaming and co) +
+
__prft__ (bool, default: _true_): set `prft` box at segment start, disabled if not fragmented mode +
+
__psshs__ (enum, default: _moov_): set `pssh` boxes store mode - moof: in first moof of each segments - moov: in movie box - both: in movie box and in first moof of each segment - none: pssh is discarded +
+
__sgpd_traf__ (bool, default: _false_): store sample group descriptions in traf (duplicated for each traf). If not used, sample group descriptions are stored in the movie box -__vodcache__ (enum, default: _replace_): enable temp storage for VoD dash modes +
+
+__vodcache__ (enum, default: _replace_): enable temp storage for VoD dash modes - on: use temp storage of complete file for sidx and ssix injection - insert: insert sidx and ssix by shifting bytes in output file - replace: precompute pace requirements for sidx and ssix and rewrite file range at end +
+
__noinit__ (bool, default: _false_): do not produce initial `moov, used for DASH bitstream switching mode` +
+
__tktpl__ (enum, default: _yes_): use track box from input if any as a template to create new track - no: disables template - yes: clones the track (except edits and decoder config) - udta: only loads udta +
+
__mudta__ (enum, default: _yes_): use `udta` and other `moov` extension boxes from input if any - no: disables import - yes: clones all extension boxes - udta: only loads udta +
+
__mvex__ (bool, default: _false_): set `mvex` boxes after `trak` boxes +
+
__sdtp_traf__ (enum, default: _no_): use `sdtp` box in `traf` box rather than using flags in trun sample entries - no: do not use `sdtp` - sdtp: use `sdtp` box to indicate sample dependencies and do not write info in `trun` sample flags - both: use `sdtp` box to indicate sample dependencies and also write info in `trun` sample flags +
+
__trackid__ (uint, default: _0_): track ID of created track for single track. Default 0 uses next available trackID +
+
__fragdur__ (bool, default: _false_): fragment based on fragment duration rather than CTS. Mostly used for `MP4Box -frag` option -__btrt__ (bool, default: _true_): set `btrt` box in sample description -__styp__ (str): set segment `styp` major brand (and optionally version) to the given 4CC[.version] -__mediats__ (sint, default: _0_): set media timescale. A value of 0 means inherit from PID, a value of -1 means derive from samplerate or frame rate -__ase__ (enum, default: _v0_): set audio sample entry mode for more than stereo layouts +
+
+__btrt__ (bool, default: _true_): set `btrt` box in sample description +
+
+__styp__ (str): set segment `styp` major brand (and optionally version) to the given 4CC[.version] +
+
+__mediats__ (sint, default: _0_): set media timescale. A value of 0 means inherit from PID, a value of -1 means derive from samplerate or frame rate +
+
+__ase__ (enum, default: _v0_): set audio sample entry mode for more than stereo layouts - v0: use v0 signaling but channel count from stream, recommended for backward compatibility - v0s: use v0 signaling and force channel count to 2 (stereo) if more than 2 channels - v1: use v1 signaling, ISOBMFF style (will mux raw PCM as ISOBMFF style) - v1qt: use v1 signaling, QTFF style - v2qt: use v2 signaling, QTFF style (lpcm entry type) +
+
__ssix__ (bool, default: _false_): create `ssix` box when `sidx` box is present, level 1 mapping I-frames byte ranges, level 0xFF mapping the rest +
+
__ccst__ (bool, default: _false_): insert coding constraint box for video tracks +
+
__maxchunk__ (uint, default: _0_): set max chunk size in bytes for runs (only used in non-fragmented mode). 0 means no constraints +
+
__noroll__ (bool, default: _false_): disable roll sample grouping +
+
__norap__ (bool, default: _false_): disable rap sample grouping +
+
__saio32__ (bool, default: _false_): use 32 bit offset for side data location instead of 64 bit offset +
+
__tfdt64__ (bool, default: _false_): use 64 bit tfdt and sidx even for 32 bits timestamps +
+
__compress__ (enum, default: _no_): set top-level box compression mode - no: disable box compression @@ -258,51 +359,100 @@ This will force the text stream to be used as a QT chapter track. - sidx: compress moof and sidx boxes - ssix: compress moof, sidx and ssix boxes - all: compress moov, moof, sidx and ssix boxes +
+
__fcomp__ (bool, default: _false_): force using compress box even when compressed size is larger than uncompressed +
+
__otyp__ (bool, default: _false_): inject original file type when using compressed boxes +
+
__trun_inter__ (bool, default: _false_): interleave samples in `trun` based on the temporal level, the lowest level are stored first (this will create as many `trun` boxes as required) +
+
__truns_first__ (bool, default: _false_): store track runs before sample group description and sample encryption information +
+
__block_size__ (uint, default: _10000_): target output block size, 0 for default internal value (10k) +
+
__boxpatch__ (str): apply box patch before writing +
+
__deps__ (bool, default: _true_): add samples dependencies information +
+
__mfra__ (bool, default: _false_): enable movie fragment random access when fragmenting (ignored when dashing) +
+
__forcesync__ (bool, default: _false_): force all SAP types to be considered sync samples (might produce non-compliant files) +
+
__refrag__ (bool, default: _false_): use track fragment defaults from initial file if any rather than computing them from PID properties (used when processing standalone segments/fragments) +
+
__itags__ (enum, default: _strict_): tag injection mode - none: do not inject tags - strict: only inject recognized itunes tags - all: inject all possible tags +
+
__keep_utc__ (bool, default: _false_): force all new files and tracks to keep the source UTC creation and modification times +
+
__pps_inband__ (bool, default: _no_): when [xps_inband](#xps_inband) is set, inject PPS in each non SAP 1/2/3 sample +
+
__moovpad__ (uint, default: _0_): insert `free` box of given size after `moov` for future in-place editing +
+
__cmaf__ (enum, default: _no_): use CMAF guidelines (turns on `mvex`, `truns_first`, `strun`, `straf`, `tfdt_traf`, `chain_sidx` and restricts `subs_sidx` to -1 or 0) - no: CMAF not enforced - cmfc: use CMAF `cmfc` guidelines - cmf2: use CMAF `cmf2` guidelines (turns on `nofragdef`) +
+
__pad_sparse__ (bool, default: _true_): inject sample with no data (size 0) to keep durations in unknown sparse text and metadata tracks +
+
__force_dv__ (bool, default: _false_): force DV sample entry types even when AVC/HEVC compatibility is signaled +
+
__dvsingle__ (bool, default: _false_): ignore DolbyVision profile 8 in xps inband mode if profile 5 is already set +
+
__tsalign__ (bool, default: _true_): enable timeline realignment to 0 for first sample - if false, this will keep original timing with empty edit (possibly long) at begin) +
+
__chapm__ (enum, default: _both_): chapter storage mode - off: disable chapters - tk: use chapter track (QT-style) - udta: use user-data box chapters - both: use both chapter tracks and udta +
+
__patch_dts__ (bool, default: _false_): patch previous samples duration when dts do not increase monotonically +
+
__uncv__ (enum, default: _prof_): use uncv (ISO 23001-17) for raw video - off: disabled (always the case when muxing to QT) - gen: enabled, do not write profile - prof: enabled and write profile if known - tiny: enabled and write reduced version if profile known and compatible +
+
__trunv1__ (bool, default: _false_): force using version 1 of trun regardless of media type or CMAF brand +
+
__rsot__ (bool, default: _false_): inject redundant sample timing information when present +
diff --git a/docs/Filters/mpeghdec.md b/docs/Filters/mpeghdec.md index a1b2f271..df6f580b 100644 --- a/docs/Filters/mpeghdec.md +++ b/docs/Filters/mpeghdec.md @@ -1,6 +1,6 @@ -# MPEG-H Audio decoder +# MPEG-H Audio decoder {:data-level="all"} Register name used to load filter: __mpeghdec__ This filter may be automatically loaded during graph resolution. diff --git a/docs/Filters/nhmlr.md b/docs/Filters/nhmlr.md index 35daf657..138f21b5 100644 --- a/docs/Filters/nhmlr.md +++ b/docs/Filters/nhmlr.md @@ -9,8 +9,12 @@ This filter reads NHML files/data to produce a media PID and frames. NHML documentation is available at https://wiki.gpac.io/xmlformats/NHML-Format -# Options +# Options {.no-collapse} +
__reframe__ (bool, default: _false_): force re-parsing of referenced content -__index__ (dbl, default: _1.0_): indexing window length +
+
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/nhmlw.md b/docs/Filters/nhmlw.md index a96ad15d..8ca0b061 100644 --- a/docs/Filters/nhmlw.md +++ b/docs/Filters/nhmlw.md @@ -9,17 +9,29 @@ This filter converts a single stream to an NHML output file. NHML documentation is available at https://wiki.gpac.io/xmlformats/NHML-Format -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
+
__dims__ (bool, default: _false_): use DIMS mode -__name__ (str): set output name of media and info files produced +
+
+__name__ (str): set output name of media and info files produced +
+
__nhmlonly__ (bool, default: _false_): only dump NHML info, not media +
+
__pckp__ (bool, default: _false_): full NHML dump +
+
__chksum__ (enum, default: _none_): insert frame checksum - none: no checksum - crc: CRC32 checksum - sha1: SHA1 checksum +
diff --git a/docs/Filters/nhntr.md b/docs/Filters/nhntr.md index 902258b5..c9920d55 100644 --- a/docs/Filters/nhntr.md +++ b/docs/Filters/nhntr.md @@ -9,8 +9,12 @@ This filter reads NHNT files/data to produce a media PID and frames. NHNT documentation is available at https://wiki.gpac.io/xmlformats/NHNT-Format -# Options +# Options {.no-collapse} +
__reframe__ (bool, default: _false_): force re-parsing of referenced content -__index__ (dbl, default: _1.0_): indexing window length +
+
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/nhntw.md b/docs/Filters/nhntw.md index dcc9c220..382ca58e 100644 --- a/docs/Filters/nhntw.md +++ b/docs/Filters/nhntw.md @@ -9,8 +9,12 @@ This filter converts a single stream to an NHNT output file. NHNT documentation is available at https://wiki.gpac.io/xmlformats/NHNT-Format -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results -__large__ (bool, default: _false_): use large file mode +
+
+__large__ (bool, default: _false_): use large file mode +
diff --git a/docs/Filters/nvdec.md b/docs/Filters/nvdec.md index 156d9eb1..61e87442 100644 --- a/docs/Filters/nvdec.md +++ b/docs/Filters/nvdec.md @@ -12,25 +12,33 @@ The absolute path to cuda lib can be set using the `cuda_lib` option in `core` o The absolute path to cuvid lib can be set using the `cuvid_lib` option in `core` or `temp` section of the config file, e.g. `-cfg=temp:cuvid_lib=PATH_TO_CUDA` -# Options +# Options {.no-collapse} +
__num_surfaces__ (uint, default: _20_): number of hardware surfaces to allocate +
+
__unload__ (enum, default: _no_): decoder unload mode - no: keep inactive decoder alive - destroy: destroy inactive decoder - reuse: detach decoder from inactive PIDs and reattach to active ones +
+
__vmode__ (enum, default: _cuvid_): video decoder backend - cuvid: use dedicated video engines directly - cuda: use a CUDA-based decoder if faster than dedicated engines - dxva: go through DXVA internally if possible (requires D3D9) +
-__fmode__ (enum, default: _gl_): frame output mode +
+__fmode__ (enum, default: _gl_): frame output mode - copy: each frame is copied and dispatched - single: frame data is only retrieved when used, single memory space for all frames (not safe if multiple consumers) - gl: frame data is mapped to an OpenGL texture +
diff --git a/docs/Filters/oggdmx.md b/docs/Filters/oggdmx.md index 092e2621..f4e6ce25 100644 --- a/docs/Filters/oggdmx.md +++ b/docs/Filters/oggdmx.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter demultiplexes OGG files/data into a set of media PIDs and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length (not implemented), use 0 to disable stream probing for duration), -__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
+__index__ (dbl, default: _1.0_): indexing window length (not implemented), use 0 to disable stream probing for duration), +
+
+__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
diff --git a/docs/Filters/oggmx.md b/docs/Filters/oggmx.md index b547ee5a..c18ad03c 100644 --- a/docs/Filters/oggmx.md +++ b/docs/Filters/oggmx.md @@ -10,8 +10,12 @@ This filter multiplexes audio and video to produce an OGG stream. The [cdur](#cdur) option allows specifying the interleaving duration (max time difference between consecutive packets of different streams). -# Options +# Options {.no-collapse} -__cdur__ (frac, default: _1/10_): stream interleaving duration in seconds -__rcfg__ (frac, default: _0/1_): stream config re-injection frequency in seconds +
+__cdur__ (frac, default: _1/10_): stream interleaving duration in seconds +
+
+__rcfg__ (frac, default: _0/1_): stream config re-injection frequency in seconds +
diff --git a/docs/Filters/ohevcdec.md b/docs/Filters/ohevcdec.md index e941a773..85da0a28 100644 --- a/docs/Filters/ohevcdec.md +++ b/docs/Filters/ohevcdec.md @@ -1,6 +1,6 @@ -# OpenHEVC decoder +# OpenHEVC decoder {:data-level="all"} Register name used to load filter: __ohevcdec__ This filter may be automatically loaded during graph resolution. diff --git a/docs/Filters/pin.md b/docs/Filters/pin.md index b108c9d8..fad231b0 100644 --- a/docs/Filters/pin.md +++ b/docs/Filters/pin.md @@ -19,7 +19,8 @@ Example ``` gpac -i - vout gpac -i stdin vout -``` +``` + # Named pipes @@ -52,17 +53,39 @@ This is typically needed for mux filters waiting for EOS to flush their data. If [marker](#marker) is set, the following strings (all 8-bytes with `` -# Options +# Options {.no-collapse} -__src__ (cstr): name of source pipe +
+__src__ (cstr): name of source pipe +
+
__block_size__ (uint, default: _5000_): buffer size used to read pipe -__ext__ (str): indicate file extension of pipe data -__mime__ (str): indicate mime type of pipe data +
+
+__ext__ (str): indicate file extension of pipe data +
+
+__mime__ (str): indicate mime type of pipe data +
+
__blk__ (bool, default: _false_): open pipe in block mode +
+
__ka__ (bool, default: _false_): keep-alive pipe when end of input is detected -__mkp__ (bool, default: _false_): create pipe if not found +
+
+__mkp__ (bool, default: _false_): create pipe if not found +
+
__sigflush__ (bool, default: _false_): signal end of stream upon pipe close - cf filter help +
+
__marker__ (bool, default: _false_): inspect payload for flush and reconfigure signals - cf filter help +
+
__bpcnt__ (uint, default: _0_): number of broken pipe allowed before exiting, 0 means forever +
+
__timeout__ (uint, default: _0_): timeout in ms before considering input is in end of stream (0: no timeout) +
diff --git a/docs/Filters/pout.md b/docs/Filters/pout.md index aace8f97..3aa05bfd 100644 --- a/docs/Filters/pout.md +++ b/docs/Filters/pout.md @@ -27,16 +27,36 @@ If [marker](#marker) is set, the string `GPACPIF` (8 bytes including 0-terminato Pipeline flushing is currently triggered by DASH segment end or ISOBMF fragment end. -# Options - -__dst__ (cstr): name of destination pipe -__ext__ (str): indicate file extension of pipe data -__mime__ (str): indicate mime type of pipe data +# Options {.no-collapse} + +
+__dst__ (cstr): name of destination pipe +
+
+__ext__ (str): indicate file extension of pipe data +
+
+__mime__ (str): indicate mime type of pipe data +
+
__dynext__ (bool, default: _false_): indicate the file extension is set by filter chain, not dst -__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 -__mkp__ (bool, default: _false_): create pipe if not found +
+
+__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 +
+
+__mkp__ (bool, default: _false_): create pipe if not found +
+
__block_size__ (uint, default: _5000_): buffer size used to write to pipe, Windows only +
+
__ka__ (bool, default: _false_): keep pipe alive when broken pipe is detected +
+
__marker__ (bool, default: _false_): inject marker upon pipeline flush events +
diff --git a/docs/Filters/probe.md b/docs/Filters/probe.md index 91e28a96..6f51b9e7 100644 --- a/docs/Filters/probe.md +++ b/docs/Filters/probe.md @@ -11,14 +11,16 @@ The filter outputs the number of input PIDs in the file specified by [log](#log) It is up to the app developer to query input PIDs of the prober and take appropriated decisions. -# Options +# Options {.no-collapse} -__log__ (str, default: _stdout_, Enum: _any|stderr|stdout|GLOG|null): set probe log filename to print number of streams +
+__log__ (str, default: _stdout_, Enum: _any|stderr|stdout|GLOG|null): set probe log filename to print number of streams - _any: target file path and name - stderr: dump to stderr - stdout: dump to stdout - GLOG: use GPAC logs `app@info` - null: silent mode +
diff --git a/docs/Filters/reframer.md b/docs/Filters/reframer.md index 82cc0a8d..c50f4102 100644 --- a/docs/Filters/reframer.md +++ b/docs/Filters/reframer.md @@ -37,7 +37,8 @@ This filter can force input media streams to be decoded using the [raw](#raw) op Example ``` gpac -i m.mp4 reframer:raw=av [dst] -``` +``` + # Real-time Regulation @@ -46,7 +47,8 @@ For example to simulate a live DASH: Example ``` gpac -i m.mp4 reframer:rt=on -o live.mpd:dynamic -``` +``` + # Range extraction @@ -68,7 +70,8 @@ When multiple ranges are given, the filter will try to seek if needed and suppor Example ``` gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10,T00:02:00:xe=T00:00:20,T00:01:20 [dst] -``` +``` + This will extract the time ranges [10s,20s], [1m10s,1m20s] and all media starting from 2m If no end range is found for a given start range: @@ -80,12 +83,14 @@ If no end range is found for a given start range: Example ``` gpac -i m.mp4 reframer:xs=0,10,25:xe=5,20 [dst] -``` +``` + This will extract the time ranges [0s,5s], [10s,20s] and all media starting from 25s Example ``` gpac -i m.mp4 reframer:xs=0,10,25 [dst] -``` +``` + This will extract the time ranges [0s,10s], [10s,25s] and all media starting from 25s It is possible to signal range boundaries in output packets using [splitrange](#splitrange). @@ -98,7 +103,8 @@ This will expose on the first packet of each range in each PID the following pro Example ``` gpac -i m.mp4 reframer:xs=T00:00:10,T00:01:10:xe=T00:00:20:splitrange -o dump_$FS$.264 [dst] -``` +``` + This will create two output files dump_T00.00.10_T00.02.00.264 and dump_T00.01.10.264. _Note: The `:` and `/` characters are replaced by `.` in `FileSuffix` property._ @@ -109,7 +115,8 @@ __Warning: The option must be escaped using double separators in order to be par Example ``` gpac -i m.mp4 reframer:xs=0,30::props=#Period=P1,#Period=P2:#foo=bar [dst] -``` +``` + This will assign to output PIDs - during the range [0,30]: property `Period` to `P1` @@ -159,58 +166,106 @@ The additional formats allowed for [xs](#xs) option are: _Note: In these modes, [splitrange](#splitrange) and [xadjust](#xadjust) are implicitly set._ -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results -__rt__ (enum, default: _off_, updatable): real-time regulation mode of input +
+
+__rt__ (enum, default: _off_, updatable): real-time regulation mode of input - off: disables real-time regulation - on: enables real-time regulation, one clock per PID - sync: enables real-time regulation one clock for all PIDs +
-__saps__ (uintl, Enum: 0|1|2|3|4, updatable): list of SAP types (0,1,2,3,4) to forward, other packets are dropped (forwarding only sap 0 will break the decoding) +
+__saps__ (uintl, Enum: 0|1|2|3|4, updatable): list of SAP types (0,1,2,3,4) to forward, other packets are dropped (forwarding only sap 0 will break the decoding) +
-__refs__ (bool, default: _false_, updatable): forward only frames used as reference frames, if indicated in the input stream +
+__refs__ (bool, default: _false_, updatable): forward only frames used as reference frames, if indicated in the input stream +
+
__speed__ (dbl, default: _0.0_, updatable): speed for real-time regulation mode, a value of 0 uses speed from play commands -__raw__ (enum, default: _no_): force input AV streams to be in raw format +
+
+__raw__ (enum, default: _no_): force input AV streams to be in raw format - no: do not force decoding of inputs - av: force decoding of audio and video inputs - a: force decoding of audio inputs - v: force decoding of video inputs +
+
__frames__ (sintl, updatable): drop all except listed frames (first being 1). A negative value `-V` keeps only first frame every `V` frames -__xs__ (strl): extraction start time(s) -__xe__ (strl): extraction end time(s). If less values than start times, the last time interval extracted is an open range +
+
+__xs__ (strl): extraction start time(s) +
+
+__xe__ (strl): extraction end time(s). If less values than start times, the last time interval extracted is an open range +
+
__xround__ (enum, default: _before_): adjust start time of extraction range to I-frame - before: use first I-frame preceding or matching range start - seek: see filter help - after: use first I-frame (if any) following or matching range start - closest: use I-frame closest to range start +
+
__xadjust__ (bool, default: _false_): adjust end time of extraction range to be before next I-frame +
+
__xots__ (bool, default: _false_): keep original timestamps after extraction +
+
__nosap__ (bool, default: _false_): do not cut at SAP when extracting range (may result in broken streams) +
+
__splitrange__ (bool, default: _false_): signal file boundary at each extraction first packet for template-base file generation +
+
__seeksafe__ (dbl, default: _10.0_): rewind play requests by given seconds (to make sure the I-frame preceding start is catched) +
+
__tcmdrw__ (bool, default: _true_): rewrite TCMD samples when splitting +
+
__props__ (strl): extra output PID properties per extraction range +
+
__no_audio_seek__ (bool, default: _false_): disable seek mode on audio streams (no change of priming duration) +
+
__probe_ref__ (bool, default: _false_): allow extracted range to be longer in case of B-frames with reference frames presented outside of range +
+
__utc_ref__ (enum, default: _any_): set reference mode for UTC range extraction - local: use UTC of local host - any: use UTC of media, or UTC of local host if not found in media after probing time - media: use UTC of media (abort if none found) +
+
__utc_probe__ (uint, default: _5000_): timeout in milliseconds to try to acquire UTC reference from media +
+
__copy__ (bool, default: _false_, updatable): try copying frame interface into packets +
+
__cues__ (enum, default: _no_, updatable): cue filtering mode - no: do no filter frames based on cue info - segs: only forward frames marked as segment start - frags: only forward frames marked as fragment start +
+
__rmseek__ (bool, default: _false_, updatable): remove seek flag of all sent packets +
diff --git a/docs/Filters/resample.md b/docs/Filters/resample.md index ca1d2dfe..a1560986 100644 --- a/docs/Filters/resample.md +++ b/docs/Filters/resample.md @@ -9,11 +9,19 @@ Filters of this class can connect to each-other. This filter resamples raw audio to a target sample rate, number of channels or audio format. -# Options +# Options {.no-collapse} -__och__ (uint, default: _0_): desired number of output audio channels (0 for auto) -__osr__ (uint, default: _0_): desired sample rate of output audio (0 for auto) -__osfmt__ (afmt, default: _none_): desired sample format of output audio (`none` for auto) -__olayout__ (alay, Enum: mono|stereo|3/0.0|3/1.0|3/2.0|3/2.1|5/2.1|1+1|2/1.0|2/2.0|3/3.1|3/4.1|11/11.2|5/2.1|5/5.2|5/4.1|6/5.1|6/7.1|5/6.1|7/6.1): desired CICP layout of output audio (null for auto) +
+__och__ (uint, default: _0_): desired number of output audio channels (0 for auto) +
+
+__osr__ (uint, default: _0_): desired sample rate of output audio (0 for auto) +
+
+__osfmt__ (afmt, default: _none_): desired sample format of output audio (`none` for auto) +
+
+__olayout__ (alay, Enum: mono|stereo|3/0.0|3/1.0|3/2.0|3/2.1|5/2.1|1+1|2/1.0|2/2.0|3/3.1|3/4.1|11/11.2|5/2.1|5/5.2|5/4.1|6/5.1|6/7.1|5/6.1|7/6.1): desired CICP layout of output audio (null for auto) +
diff --git a/docs/Filters/restamp.md b/docs/Filters/restamp.md index 4f93b193..75aee895 100644 --- a/docs/Filters/restamp.md +++ b/docs/Filters/restamp.md @@ -28,21 +28,41 @@ When [align](#align) is not 0, if the difference between two consecutive timesta is set to the last computed timestamp plus the minimum packet duration for the stream. -# Options - -__fps__ (frac, default: _0/1_): target fps -__delay__ (frac, default: _0/1_, updatable): delay to add to all streams -__delay_v__ (frac, default: _0/1_, updatable): delay to add to video streams -__delay_a__ (frac, default: _0/1_, updatable): delay to add to audio streams -__delay_t__ (frac, default: _0/1_, updatable): delay to add to text streams -__delay_o__ (frac, default: _0/1_, updatable): delay to add to other streams -__rawv__ (enum, default: _no_): copy video frames +# Options {.no-collapse} + +
+__fps__ (frac, default: _0/1_): target fps +
+
+__delay__ (frac, default: _0/1_, updatable): delay to add to all streams +
+
+__delay_v__ (frac, default: _0/1_, updatable): delay to add to video streams +
+
+__delay_a__ (frac, default: _0/1_, updatable): delay to add to audio streams +
+
+__delay_t__ (frac, default: _0/1_, updatable): delay to add to text streams +
+
+__delay_o__ (frac, default: _0/1_, updatable): delay to add to other streams +
+
+__rawv__ (enum, default: _no_): copy video frames - no: no raw frame copy/drop - force: force decoding all video streams - dyn: decoding video streams if not all intra +
-__tsinit__ (lfrac, default: _-1/1_): initial timestamp to resync to, negative values disables resync -__align__ (uint, default: _0_): timestamp alignment threshold (0 disables alignment) - see filter help -__reorder__ (bool, default: _false_): reorder input packets by CTS (resulting PID may fail decoding) +
+__tsinit__ (lfrac, default: _-1/1_): initial timestamp to resync to, negative values disables resync +
+
+__align__ (uint, default: _0_): timestamp alignment threshold (0 disables alignment) - see filter help +
+
+__reorder__ (bool, default: _false_): reorder input packets by CTS (resulting PID may fail decoding) +
diff --git a/docs/Filters/rewind.md b/docs/Filters/rewind.md index 7ec1b63a..3d705ba7 100644 --- a/docs/Filters/rewind.md +++ b/docs/Filters/rewind.md @@ -9,7 +9,9 @@ This filter reverses audio and video frames in negative playback speed. The filter is in passthrough if speed is positive. Otherwise, it reverts decoded GOPs for video, or revert samples in decoded frame for audio (not really nice for most codecs). -# Options +# Options {.no-collapse} +
__rbuffer__ (uint, default: _100_): size of video rewind buffer in frames. If more frames than this, flush is performed +
diff --git a/docs/Filters/rfac3.md b/docs/Filters/rfac3.md index 3ff4332a..52d80079 100644 --- a/docs/Filters/rfac3.md +++ b/docs/Filters/rfac3.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter parses AC3 and E-AC3 files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length +
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/rfadts.md b/docs/Filters/rfadts.md index b3a8ebbc..f19b3267 100644 --- a/docs/Filters/rfadts.md +++ b/docs/Filters/rfadts.md @@ -8,23 +8,37 @@ This filter may be automatically loaded during graph resolution. This filter parses AAC files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} +
__frame_size__ (uint, default: _1024_): size of AAC frame in audio samples -__index__ (dbl, default: _1.0_): indexing window length +
+
+__index__ (dbl, default: _1.0_): indexing window length +
+
__ovsbr__ (bool, default: _false_): force oversampling SBR (does not multiply timescales by 2) +
+
__sbr__ (enum, default: _no_): set SBR signaling - no: no SBR signaling at all - imp: backward-compatible SBR signaling (audio signaled as AAC-LC) - exp: explicit SBR signaling (audio signaled as AAC-SBR) +
+
__ps__ (enum, default: _no_): set PS signaling - no: no PS signaling at all - imp: backward-compatible PS signaling (audio signaled as AAC-LC) - exp: explicit PS signaling (audio signaled as AAC-PS) +
-__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
+__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
+
__aacchcfg__ (sint, default: _0_): set AAC channel configuration to this value if missing from ADTS header, use negative value to always override +
diff --git a/docs/Filters/rfamr.md b/docs/Filters/rfamr.md index 4bb6622e..b9c9920b 100644 --- a/docs/Filters/rfamr.md +++ b/docs/Filters/rfamr.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter parses AMR, AMR Wideband, EVRC and SMV files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length +
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/rfav1.md b/docs/Filters/rfav1.md index 06f35595..fb79cc96 100644 --- a/docs/Filters/rfav1.md +++ b/docs/Filters/rfav1.md @@ -8,18 +8,32 @@ This filter may be automatically loaded during graph resolution. This filter parses AV1 OBU, AV1 AnnexB or IVF with AV1 or VP9 files/data and outputs corresponding visual PID and frames. -# Options +# Options {.no-collapse} -__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) -__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) +
+
+__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+
__importer__ (bool, default: _false_): compatibility with old importer +
+
__deps__ (bool, default: _false_): import sample dependency information +
+
__notime__ (bool, default: _false_): ignore input timestamps, rebuild from 0 +
+
__temporal_delim__ (bool, default: _false_): keep temporal delimiters in reconstructed frames +
+
__bsdbg__ (enum, default: _off_): debug OBU parsing in `media@debug logs` - off: not enabled - on: enabled - full: enable with number of bits dumped +
diff --git a/docs/Filters/rfflac.md b/docs/Filters/rfflac.md index 93e2d465..0afac870 100644 --- a/docs/Filters/rfflac.md +++ b/docs/Filters/rfflac.md @@ -11,8 +11,12 @@ By default the reframer will only check CRC footer of frames if a change in samp This should accommodate for most configurations, but CRC check can be enforced using [docrc](#docrc). -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length -__docrc__ (bool, default: _false_): perform CRC check after each frame +
+__index__ (dbl, default: _1.0_): indexing window length +
+
+__docrc__ (bool, default: _false_): perform CRC check after each frame +
diff --git a/docs/Filters/rfh263.md b/docs/Filters/rfh263.md index 090bfad4..11d573d3 100644 --- a/docs/Filters/rfh263.md +++ b/docs/Filters/rfh263.md @@ -8,9 +8,15 @@ This filter may be automatically loaded during graph resolution. This filter parses H263 files/data and outputs corresponding visual PID and frames. -# Options +# Options {.no-collapse} -__fps__ (frac, default: _15000/1000_): import frame rate -__index__ (dbl, default: _1.0_): indexing window length +
+__fps__ (frac, default: _15000/1000_): import frame rate +
+
+__index__ (dbl, default: _1.0_): indexing window length +
+
__notime__ (bool, default: _false_): ignore input timestamps, rebuild from 0 +
diff --git a/docs/Filters/rflatm.md b/docs/Filters/rflatm.md index fa59a0a0..7f9da1b6 100644 --- a/docs/Filters/rflatm.md +++ b/docs/Filters/rflatm.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter parses AAC in LATM files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} +
__frame_size__ (uint, default: _1024_): size of AAC frame in audio samples -__index__ (dbl, default: _1.0_): indexing window length +
+
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/rfmhas.md b/docs/Filters/rfmhas.md index 3194593f..932ab8fe 100644 --- a/docs/Filters/rfmhas.md +++ b/docs/Filters/rfmhas.md @@ -10,10 +10,18 @@ By default, the filter expects a MHAS stream with SYNC packets set, otherwise tu The default behavior is to dispatch a framed MHAS bitstream. To demultiplex into a raw MPEG-H Audio, use [mpha](#mpha). -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length -__mpha__ (bool, default: _false_): demultiplex MHAS and only forward audio frames -__pcksync__ (uint, default: _4_): number of unknown packets to tolerate before considering sync is lost -__nosync__ (bool, default: _true_): initial sync state +
+__index__ (dbl, default: _1.0_): indexing window length +
+
+__mpha__ (bool, default: _false_): demultiplex MHAS and only forward audio frames +
+
+__pcksync__ (uint, default: _4_): number of unknown packets to tolerate before considering sync is lost +
+
+__nosync__ (bool, default: _true_): initial sync state +
diff --git a/docs/Filters/rfmp3.md b/docs/Filters/rfmp3.md index a8455510..d1ac2d54 100644 --- a/docs/Filters/rfmp3.md +++ b/docs/Filters/rfmp3.md @@ -8,9 +8,15 @@ This filter may be automatically loaded during graph resolution. This filter parses MPEG-1/2 audio files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length -__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
+__index__ (dbl, default: _1.0_): indexing window length +
+
+__expart__ (bool, default: _false_): expose pictures as a dedicated video PID +
+
__forcemp3__ (bool, default: _true_): force mp3 signaling for MPEG-2 Audio layer 3 +
diff --git a/docs/Filters/rfmpgvid.md b/docs/Filters/rfmpgvid.md index 72aff953..d2c467f4 100644 --- a/docs/Filters/rfmpgvid.md +++ b/docs/Filters/rfmpgvid.md @@ -9,11 +9,21 @@ This filter parses MPEG-1/2 and MPEG-4 part 2 video files/data and outputs corre _Note: The filter uses negative CTS offsets: CTS is correct, but some frames may have DTS greater than CTS._ -# Options +# Options {.no-collapse} -__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) -__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) +
+
+__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+
__vfr__ (bool, default: _false_): set variable frame rate import +
+
__importer__ (bool, default: _false_): compatibility with old importer, displays import results +
+
__notime__ (bool, default: _false_): ignore input timestamps, rebuild from 0 +
diff --git a/docs/Filters/rfnalu.md b/docs/Filters/rfnalu.md index db9d43c9..c0ef7920 100644 --- a/docs/Filters/rfnalu.md +++ b/docs/Filters/rfnalu.md @@ -10,35 +10,71 @@ This filter produces ISOBMFF-compatible output: start codes are removed, NALU le _Note: The filter uses negative CTS offsets: CTS is correct, but some frames may have DTS greater than CTS._ -# Options +# Options {.no-collapse} -__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) -__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) +
+
+__index__ (dbl, default: _-1.0_): indexing window length. If 0, bitstream is not probed for duration. A negative value skips the indexing if the source file is larger than 20M (slows down importers) unless a play with start range > 0 is issued +
+
__explicit__ (bool, default: _false_): use explicit layered (SVC/LHVC) import +
+
__strict_poc__ (enum, default: _off_): delay frame output of an entire GOP to ensure CTS info is correct when POC suddenly changes - off: disable GOP buffering - on: enable GOP buffering, assuming no error in POC - error: enable GOP buffering and try to detect lost frames +
+
__nosei__ (bool, default: _false_): remove all sei messages +
+
__nosvc__ (bool, default: _false_): remove all SVC/MVC/LHVC data +
+
__novpsext__ (bool, default: _false_): remove all VPS extensions +
+
__importer__ (bool, default: _false_): compatibility with old importer, displays import results +
+
__nal_length__ (uint, default: _4_): set number of bytes used to code length field: 1, 2 or 4 +
+
__subsamples__ (bool, default: _false_): import subsamples information +
+
__deps__ (bool, default: _false_): import sample dependency information +
+
+__refs__ (bool, default: _false_): import sample reference picture list (currently only for HEVC and VVC) +
+
__seirw__ (bool, default: _true_): rewrite AVC sei messages for ISOBMFF constraints +
+
__audelim__ (bool, default: _false_): keep Access Unit delimiter in payload +
+
__notime__ (bool, default: _false_): ignore input timestamps, rebuild from 0 +
+
__dv_mode__ (enum, default: _auto_): signaling for DolbyVision - none: never signal DV profile - auto: signal DV profile if RPU or EL are found - clean: do not signal and remove RPU and EL NAL units - single: signal DV profile if RPU are found and remove EL NAL units +
+
__dv_profile__ (uint, default: _0_): profile for DolbyVision (currently defined profiles are 4, 5, 7, 8, 9), 0 for auto-detect +
+
__dv_compatid__ (enum, default: _auto_): cross-compatibility ID for DolbyVision - auto: auto-detect @@ -49,11 +85,14 @@ _Note: The filter uses negative CTS offsets: CTS is correct, but some frames may - hlg2100: HLG BT.2100 gamut in ITU-R BT.2020 - bt2020: SDR BT.2020 - brd: Ultra HD Blu-ray Disc HDR +
+
__bsdbg__ (enum, default: _off_): debug NAL parsing in `media@debug` logs - off: not enabled - on: enabled - full: enable with number of bits dumped +
diff --git a/docs/Filters/rfpcm.md b/docs/Filters/rfpcm.md index 7d5d3b98..6e0d1277 100644 --- a/docs/Filters/rfpcm.md +++ b/docs/Filters/rfpcm.md @@ -8,11 +8,19 @@ This filter may be automatically loaded during graph resolution. This filter parses raw PCM file/data or WAVE files and outputs corresponding raw audio PID and frames. -# Options +# Options {.no-collapse} -__sr__ (uint, default: _44100_): sample rate -__safmt__ (afmt, default: _none_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): audio format +
+__sr__ (uint, default: _44100_): sample rate +
+
+__safmt__ (afmt, default: _none_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): audio format +
-__ch__ (uint, default: _2_): number of channels +
+__ch__ (uint, default: _2_): number of channels +
+
__framelen__ (uint, default: _1024_): number of samples to put in one audio frame. For planar formats, indicate plane size in samples +
diff --git a/docs/Filters/rfprores.md b/docs/Filters/rfprores.md index c0d985e2..976aa347 100644 --- a/docs/Filters/rfprores.md +++ b/docs/Filters/rfprores.md @@ -8,10 +8,18 @@ This filter may be automatically loaded during graph resolution. This filter parses ProRes raw files/data and outputs corresponding visual PID and frames. -# Options +# Options {.no-collapse} -__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) -__findex__ (bool, default: _true_): index frames. If true, filter will be able to work in rewind mode +
+__fps__ (frac, default: _0/1000_): import frame rate (0 default to FPS from bitstream or 25 Hz) +
+
+__findex__ (bool, default: _true_): index frames. If true, filter will be able to work in rewind mode +
+
__cid__ (str): set QT 4CC for the imported media. If not set, default is 'ap4h' for YUV444 and 'apch' for YUV422 +
+
__notime__ (bool, default: _false_): ignore input timestamps, rebuild from 0 +
diff --git a/docs/Filters/rfqcp.md b/docs/Filters/rfqcp.md index 5da4e3f1..9703bc5c 100644 --- a/docs/Filters/rfqcp.md +++ b/docs/Filters/rfqcp.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter parses QCP files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length +
+__index__ (dbl, default: _1.0_): indexing window length +
diff --git a/docs/Filters/rfrawvid.md b/docs/Filters/rfrawvid.md index b57c21d9..a1f66e5f 100644 --- a/docs/Filters/rfrawvid.md +++ b/docs/Filters/rfrawvid.md @@ -10,11 +10,19 @@ This filter parses raw YUV and RGB files/data and outputs corresponding raw vide The filter also parses YUV4MPEG format. -# Options +# Options {.no-collapse} -__size__ (v2di, default: _0x0_): source video resolution -__spfmt__ (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 +
+__size__ (v2di, default: _0x0_): source video resolution +
+
+__spfmt__ (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 +
-__fps__ (frac, default: _25/1_): number of frames per second -__copy__ (bool, default: _false_): copy source bytes into output frame. If not set, source bytes are referenced only +
+__fps__ (frac, default: _25/1_): number of frames per second +
+
+__copy__ (bool, default: _false_): copy source bytes into output frame. If not set, source bytes are referenced only +
diff --git a/docs/Filters/rfsrt.md b/docs/Filters/rfsrt.md index e486f993..8fb3842e 100644 --- a/docs/Filters/rfsrt.md +++ b/docs/Filters/rfsrt.md @@ -10,8 +10,12 @@ This filter rewrites unframed SRT to TX3G / QT Timed Text (binary format) An unframed SRT packet consists in a single SRT cue as packet payload and packet timing contains the cue timing (start and duration). -# Options +# Options {.no-collapse} -__fontname__ (str): default font -__fontsize__ (uint, default: _18_): default font size +
+__fontname__ (str): default font +
+
+__fontsize__ (uint, default: _18_): default font size +
diff --git a/docs/Filters/rftruehd.md b/docs/Filters/rftruehd.md index a25072ca..6b206644 100644 --- a/docs/Filters/rftruehd.md +++ b/docs/Filters/rftruehd.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter parses Dolby TrueHD files/data and outputs corresponding audio PID and frames. -# Options +# Options {.no-collapse} -__index__ (dbl, default: _1.0_): indexing window length -__auxac3__ (bool, default: _false_): expose auxiliary AC-3 stream if present +
+__index__ (dbl, default: _1.0_): indexing window length +
+
+__auxac3__ (bool, default: _false_): expose auxiliary AC-3 stream if present +
diff --git a/docs/Filters/routein.md b/docs/Filters/routein.md index 6d2b9c17..9369f2b8 100644 --- a/docs/Filters/routein.md +++ b/docs/Filters/routein.md @@ -42,7 +42,8 @@ If needed, one PID per TSI can be used rather than a single PID. This avoids mix Example ``` gpac -i atsc://gcache=false -o $ServiceID$/$File$:dynext -``` +``` + This will grab the files and forward them as output PIDs, consumed by the [fout](fout) filter. If [max_segs](#max_segs) is set, file deletion event will be triggered in the filter chain. @@ -53,7 +54,8 @@ In standalone mode, the filter does not produce any output PID and writes receiv Example ``` gpac -i atsc://:odir=output -``` +``` + This will grab the files and write them to `output` directory. If [max_segs](#max_segs) is set, old files will be deleted. @@ -75,43 +77,91 @@ For ATSC, you will have to do this for the base signaling multicast (224.0.23.60 Example ``` route add -net 224.0.23.60/32 -interface vboxnet0 -``` +``` + Then for each multicast service in the multicast: Example ``` route add -net 239.255.1.4/32 -interface vboxnet0 -``` +``` + -# Options +# Options {.no-collapse} -__src__ (cstr): URL of source content +
+__src__ (cstr): URL of source content +
+
__ifce__ (str): default interface to use for multicast. If NULL, the default system interface will be used +
+
__gcache__ (bool, default: _true_): indicate the files should populate GPAC HTTP cache -__tunein__ (sint, default: _-2_): service ID to bootstrap on for ATSC 3.0 mode (0 means tune to no service, -1 tune all services -2 means tune on first service found) +
+
+__tunein__ (sint, default: _-2_): service ID to bootstrap on for ATSC 3.0 mode (0 means tune to no service, -1 tune all services -2 means tune on first service found) +
+
__buffer__ (uint, default: _0x80000_): receive buffer size to use in bytes -__timeout__ (uint, default: _5000_): timeout in ms after which tunein fails +
+
+__timeout__ (uint, default: _5000_): timeout in ms after which tunein fails +
+
__nbcached__ (uint, default: _8_): number of segments to keep in cache per service +
+
__kc__ (bool, default: _false_): keep corrupted file +
+
__skipr__ (bool, default: _true_): skip repeated files (ignored in cache mode) +
+
__stsi__ (bool, default: _false_): define one output PID per tsi/serviceID (ignored in cache mode) +
+
__stats__ (uint, default: _1000_): log statistics at the given rate in ms (0 disables stats) +
+
__tsidbg__ (uint, default: _0_): gather only objects with given TSI (debug) +
+
__max_segs__ (uint, default: _0_): maximum number of segments to keep on disk +
+
__odir__ (str): output directory for standalone mode +
+
__reorder__ (bool, default: _true_): consider packets are not always in order - if false, this will evaluate an LCT object as done when TOI changes -__cloop__ (bool, default: _false_): check for loops based on TOI (used for capture replay) -__rtimeout__ (uint, default: _1000_): default timeout in us to wait when gathering out-of-order packets +
+
+__cloop__ (bool, default: _false_): check for loops based on TOI (used for capture replay) +
+
+__rtimeout__ (uint, default: _100000_): default timeout in us to wait when gathering out-of-order packets +
+
__fullseg__ (bool, default: _false_): only dispatch full segments in cache mode (always true for other modes) +
+
__repair__ (enum, default: _simple_): repair mode for corrupted files - no: no repair is performed - simple: simple repair is performed (incomplete `mdat` boxes will be kept) - strict: incomplete mdat boxes will be lost as well as preceding `moof` boxes - full: HTTP-based repair of all lost packets - -__repair_url__ (cstr): repair url -__max_sess__ (uint, default: _1_): max number of concurrent HTTP repair sessions -__llmode__ (bool, default: _true_): enable low-latency access -__dynsel__ (bool, default: _true_): dynamically enable and disable multicast groups based on their selection state +
+ +
+__repair_url__ (cstr): repair url +
+
+__max_sess__ (uint, default: _1_): max number of concurrent HTTP repair sessions +
+
+__llmode__ (bool, default: _true_): enable low-latency access +
+
+__dynsel__ (bool, default: _true_): dynamically enable and disable multicast groups based on their selection state +
diff --git a/docs/Filters/routeout.md b/docs/Filters/routeout.md index 57bb7871..bcc1d59e 100644 --- a/docs/Filters/routeout.md +++ b/docs/Filters/routeout.md @@ -24,31 +24,36 @@ The filter only accepts input PIDs of type `FILE`. For `raw` file PIDs, the filter will look for the following properties: -- `ROUTEName`: set resource name. If not found, uses basename of URL -- `ROUTECarousel`: set repeat period. If not found, uses [carousel](#carousel). If 0, the file is only sent once -- `ROUTEUpload`: set resource upload time. If not found, uses [carousel](#carousel). If 0, the file will be sent as fast as possible. +- `MCASTName`: set resource name. If not found, uses basename of URL +- `MCASTCarousel`: set repeat period. If not found, uses [carousel](#carousel). If 0, the file is only sent once +- `MCASTUpload`: set resource upload time. If not found, uses [carousel](#carousel). If 0, the file will be sent as fast as possible. When DASHing for ROUTE, DVB-MABR or single service ATSC, a file extension, either in [dst](#dst) or in [ext](#ext), may be used to identify the HAS session type (DASH or HLS). Example ``` "route://IP:PORT/manifest.mpd", "route://IP:PORT/:ext=mpd" -``` +``` + When DASHing for multi-service ATSC, forcing an extension will force all service to use the same formats. Example ``` "atsc://:ext=mpd", "route://IP:PORT/manifest.mpd" -``` +``` + If multiple services with different formats are needed, you will need to explicit your filters: Example ``` gpac -i DASH_URL:#ServiceID=1 dashin:forward=file:FID=1 -i HLS_URL:#ServiceID=2 dashin:forward=file:FID=2 -o atsc://:SID=1,2 gpac -i MOVIE1:#ServiceID=1 dasher:FID=1:mname=manifest.mpd -i MOVIE2:#ServiceID=2 dasher:FID=2:mname=manifest.m3u8 -o atsc://:SID=1,2 -``` +``` + __Warning: When forwarding an existing DASH/HLS session, do NOT set any extension or manifest name.__ +The filter will look for `MCASTIP` and `MCASTPort` properties on the incoming PID to setup multicast of each service. If not found, the default [ip](#ip) and port will be used, with port incremented by one for each new multicast stream. + By default, all streams in a service are assigned to a single multicast session, and differentiated by TSI (see [splitlct](#splitlct)). TSI are assigned as follows: @@ -57,13 +62,23 @@ TSI are assigned as follows: - otherwise, the first PID found is assigned TSI 10, the second TSI 20 etc ... +When [splitlct](#splitlct) is set to `mcast`, the IP multicast adress is computed as follows: + + - if `MCASTIP` is set on the PID and is different from the service multicast IP, it is used + - otherwise the service multicast IP plus one is used + +The multicast port used is set as follows: + +- if `MCASTPort` is set on the PID, it is used +- otherwise the same port as the service one is used. + Init segments and HLS child playlists are sent before each new segment, independently of [carousel](#carousel). # ATSC 3.0 mode In this mode, the filter allows multiple service multiplexing, identified through the `ServiceID` property. By default, a single multicast IP is used for route sessions, each service will be assigned a different port. -The filter will look for `ROUTEIP` and `ROUTEPort` properties on the incoming PID. If not found, the default [ip](#ip) and [port](#port) will be used. +The filter will look for `MCASTIP` and `MCASTPort` properties on the incoming PID. If not found, the default [ip](#ip) and [port](#port) will be used. ATSC 3.0 attributes set by using the following PID properties: @@ -88,7 +103,6 @@ In this mode, the filter allows multiple service multiplexing, identified throug _Note: [ip](#ip) and [first_port](#first_port) are used to send the multicast gateway configuration, init segments and manifests. [first_port](#first_port) is used only if no port is specified in [dst](#dst)._ The session will carry DVB-MABR gateway configuration, maifests and init segments on `TSI=1` -The filter will look for `ROUTEIP` and `ROUTEPort` properties on the incoming PID to setup multicast of each service. If not found, the default [ip](#ip) and port will be used, with port incremented by one for each new multicast stream. The FLUTE session always uses a symbol length of [mtu](#mtu) minus 44 bytes. @@ -100,8 +114,8 @@ If this is not the case (typically when used with an existing DASH session in fi If this fails, the filter will trigger warnings and send as fast as possible. _Note: The LCT objects are sent with no length (TOL header) assigned until the final segment size is known, potentially leading to a final 0-size LCT fragment signaling only the final size._ -In this mode, init segments and manifests are sent at the frequency given by property `ROUTECarousel` of the source PID if set or by (-carousel)[] option. -Indicating `ROUTECarousel=0` will disable mid-segment repeating of manifests and init segments. +In this mode, init segments and manifests are sent at the frequency given by property `MCASTCarousel` of the source PID if set or by (-carousel)[] option. +Indicating `MCASTCarousel=0` will disable mid-segment repeating of manifests and init segments. # Examples @@ -115,45 +129,53 @@ Multiplexing an existing DASH session in route: Example ``` gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/ -``` +``` + Multiplexing an existing DASH session in atsc: Example ``` gpac -i source.mpd dashin:forward=file -o atsc:// -``` +``` + Dashing and multiplexing in route: Example ``` gpac -i source.mp4 dasher:profile=live -o route://225.1.1.0:6000/manifest.mpd -``` +``` + Dashing and multiplexing in route Low Latency: Example ``` gpac -i source.mp4 dasher -o route://225.1.1.0:6000/manifest.mpd:profile=live:cdur=0.2:llmode -``` +``` + Sending a single file in ROUTE using half a second upload time, 2 seconds carousel: Example ``` -gpac -i URL:#ROUTEUpload=0.5:#ROUTECarousel=2 -o route://225.1.1.0:6000/ -``` +gpac -i URL:#MCASTUpload=0.5:#MCASTCarousel=2 -o route://225.1.1.0:6000/ +``` + Common mistakes: Example ``` gpac -i source.mpd -o route://225.1.1.0:6000/ -``` +``` + This will only send the manifest file as a regular object and will not load the dash session. Example ``` gpac -i source.mpd dashin:forward=file -o route://225.1.1.0:6000/manifest.mpd -``` +``` + This will force the ROUTE multiplexer to only accept .mpd files, and will drop all segment files (same if [ext](#ext) is used). Example ``` gpac -i source.mpd dasher -o route://225.1.1.0:6000/ gpac -i source.mpd dasher -o route://225.1.1.0:6000/manifest.mpd -``` +``` + These will demultiplex the input, re-dash it and send the output of the dasher to ROUTE # Error simulation @@ -162,42 +184,94 @@ It is possible to simulate errors with (-errsim)(). In this mode the LCT network Example ``` gpac -i source.mpd dasher -o route://225.1.1.0:6000/:errsim=1.0x98.0 -``` +``` + for a 1.0 percent chance to transition to error (not sending data over the network) and 98.0 to transition from error back to OK. -# Options +# Options {.no-collapse} -__dst__ (cstr): destination URL +
+__dst__ (cstr): destination URL +
+
__ext__ (cstr): set extension for graph resolution, regardless of file extension +
+
__mime__ (cstr): set mime type for graph resolution +
+
__ifce__ (str): default interface to use for multicast. If NULL, the default system interface will be used +
+
__carousel__ (uint, default: _1000_): carousel period in ms for repeating signaling and raw file data +
+
__first_port__ (uint, default: _6000_): port number of first ROUTE session in ATSC mode +
+
__ip__ (str, default: _225.1.1.0_): multicast IP address for ROUTE session in ATSC mode -__ttl__ (uint, default: _0_): time-to-live for multicast packets +
+
+__ttl__ (uint, default: _0_): time-to-live for multicast packets +
+
__bsid__ (uint, default: _800_): ID for ATSC broadcast stream -__mtu__ (uint, default: _1472_): size of LCT MTU in bytes -__splitlct__ (enum, default: _off_): split mode for LCT channels +
+
+__mtu__ (uint, default: _1472_): size of LCT MTU in bytes +
+
+__splitlct__ (enum, default: _off_): split mode for LCT channels - off: all streams are in the same LCT channel - type: each new stream type results in a new LCT channel - all: all streams are in dedicated LCT channel, the first stream being used for STSID signaling +- mcast: all streams are in dedicated multicast groups +
-__korean__ (bool, default: _false_): use Korean version of ATSC 3.0 spec instead of US +
+__korean__ (bool, default: _false_): use Korean version of ATSC 3.0 spec instead of US +
+
__llmode__ (bool, default: _false_): use low-latency mode +
+
__brinc__ (uint, default: _10_): bitrate increase in percent when estimating timing in low latency mode +
+
__noreg__ (bool, default: _false_): disable rate regulation for media segments, pushing them as fast as received -__runfor__ (uint, default: _0_): run for the given time in ms -__nozip__ (bool, default: _false_): do not zip signaling package (STSID+manifest) -__furl__ (bool, default: _false_): inject full URLs of source service in the signaling instead of stripped server path -__flute__ (bool, default: _true_): use flute for DVB-MABR object delivery -__csum__ (enum, default: _meta_): send MD5 checksum for DVB flute +
+
+__runfor__ (uint, default: _0_): run for the given time in ms +
+
+__nozip__ (bool, default: _false_): do not zip signaling package (STSID+manifest) +
+
+__furl__ (bool, default: _false_): inject full URLs of source service in the signaling instead of stripped server path +
+
+__flute__ (bool, default: _true_): use flute for DVB-MABR object delivery +
+
+__csum__ (enum, default: _meta_): send MD5 checksum for DVB flute - no: do not send checksum - meta: only send checksum for configuration files, manifests and init segments - all: send checksum for everything +
-__recv_obj_timeout__ (uint, default: _50_): timeout period in ms before resorting to unicast repair -__errsim__ (v2d, default: _0.0x100.0_): simulate errors using a 2-state Markov chain. Value are percentages +
+__recv_obj_timeout__ (uint, default: _50_): set timeout period in ms before client resorts to unicast repair +
+
+__errsim__ (v2d, default: _0.0x100.0_): simulate errors using a 2-state Markov chain. Value are percentages +
+
+__use_inband__ (bool, default: _false_): DVB mabr option: If true send the mani and init segment in content transport sessions instead of configuration transport session +
+
+__ssm__ (bool, default: _false_): indicate source-specific multicast for DVB-MABR, requires `ifce` to be set +
diff --git a/docs/Filters/rtpin.md b/docs/Filters/rtpin.md index 78ba81a4..b7f371cc 100644 --- a/docs/Filters/rtpin.md +++ b/docs/Filters/rtpin.md @@ -23,43 +23,99 @@ The filter will use: The filter will attempt reconnecting in TLS mode after two consecutive initial connection failures. -# Options +# Options {.no-collapse} -__src__ (cstr): location of source content (SDP, RTP or RTSP URL) +
+__src__ (cstr): location of source content (SDP, RTP or RTSP URL) +
+
__firstport__ (uint, default: _0_): default first port number to use (0 lets the filter decide) +
+
__ifce__ (str): default interface IP to use for multicast. If NULL, the default system interface will be used +
+
__ttl__ (uint, default: _127_, minmax: 0-127): multicast TTL +
+
__reorder_len__ (uint, default: _1000_): reorder length in packets +
+
__reorder_delay__ (uint, default: _50_): max delay in RTP re-orderer, packets will be dispatched after that +
+
__block_size__ (uint, default: _0x100000_): buffer size for RTP/UDP or RTSP when interleaved +
+
__disable_rtcp__ (bool, default: _false_): disable RTCP reporting +
+
__nat_keepalive__ (uint, default: _0_): delay in ms of NAT keepalive, disabled by default (except for SatIP, set to 30s by default) +
+
__force_mcast__ (str): force multicast on indicated IP in RTSP setup +
+
__use_client_ports__ (bool, default: _false_): force using client ports (hack for some RTSP servers overriding client ports) +
+
__bandwidth__ (uint, default: _0_): set bandwidth param for RTSP requests -__default_port__ (uint, default: _554_, minmax: 0-65535): set default RTSP port -__satip_port__ (uint, default: _1400_, minmax: 0-65535): set default port for SATIP +
+
+__default_port__ (uint, default: _554_, minmax: 0-65535): set default RTSP port +
+
+__satip_port__ (uint, default: _1400_, minmax: 0-65535): set default port for SATIP +
+
__transport__ (enum, default: _auto_): set RTP over RTSP - auto: set interleave on if HTTP tunnel is used, off otherwise and retry in interleaved mode if UDP timeout - tcp: enable RTP over RTSP - udp: disable RTP over RTSP +
-__udp_timeout__ (uint, default: _10000_): default timeout before considering UDP is down +
+__udp_timeout__ (uint, default: _10000_): default timeout before considering UDP is down +
+
__rtcp_timeout__ (uint, default: _5000_): default timeout for RTCP traffic in ms. After this timeout, playback will start out of sync. If 0 always wait for RTCP +
+
__first_packet_drop__ (uint, default: _0_, updatable): set number of first RTP packet to drop (0 if no drop) +
+
__frequency_drop__ (uint, default: _0_, updatable): drop 1 out of N packet (0 disable dropping) +
+
__loss_rate__ (sint, default: _-1_, updatable): loss rate to signal in RTCP, -1 means real loss rate, otherwise a per-thousand of packet lost -__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences -__languages__ (str, default: _$GLANG_): user languages, by default solved from GPAC preferences +
+
+__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences +
+
+__languages__ (str, default: _$GLANG_): user languages, by default solved from GPAC preferences +
+
__stats__ (uint, default: _500_): update statistics to the user every given MS (0 disables reporting) +
+
__max_sleep__ (sint, default: _1000_): set max sleep in milliseconds: - a negative value `-N` means to always sleep for `N` ms - a positive value `N` means to sleep at most `N` ms but will sleep less if frame duration is shorter +
+
__rtcpsync__ (bool, default: _true_): use RTCP to adjust synchronization +
+
__forceagg__ (bool, default: _false_): force RTSP control aggregation (patch for buggy servers) +
+
__ssm__ (strl): list of IP to include for source-specific multicast +
+
__ssmx__ (strl): list of IP to exclude for source-specific multicast +
diff --git a/docs/Filters/rtpout.md b/docs/Filters/rtpout.md index 53279f02..a7b910bb 100644 --- a/docs/Filters/rtpout.md +++ b/docs/Filters/rtpout.md @@ -18,7 +18,8 @@ In this mode, it is usually needed to specify the desired format using [ext](#ex Example ``` gpac -i src -o rtp://localhost:1234/:ext=ts -``` +``` + This will indicate that the RTP streamer expects a MPEG-2 TS mux as an input. # RTP Packets @@ -38,23 +39,57 @@ The real-time scheduling algorithm works as follows: The filter does not check for RTCP timeout and will run until all input PIDs reach end of stream. -# Options +# Options {.no-collapse} -__ip__ (str): destination IP address (NULL is 127.0.0.1) -__port__ (uint, default: _7000_): port for first stream in session -__loop__ (bool, default: _true_): loop all streams in session (not always possible depending on source type) +
+__ip__ (str): destination IP address (NULL is 127.0.0.1) +
+
+__port__ (uint, default: _7000_): port for first stream in session +
+
+__loop__ (bool, default: _true_): loop all streams in session (not always possible depending on source type) +
+
__mpeg4__ (bool, default: _false_): send all streams using MPEG-4 generic payload format if possible -__mtu__ (uint, default: _1460_): size of RTP MTU in bytes +
+
+__mtu__ (uint, default: _1460_): size of RTP MTU in bytes +
+
__ttl__ (uint, default: _2_): time-to-live for multicast packets +
+
__ifce__ (str): default network interface to use +
+
__payt__ (uint, default: _96_, minmax: 96-127): payload type to use for dynamic decoder configurations -__delay__ (sint, default: _0_): send delay for packet (negative means send earlier) +
+
+__delay__ (sint, default: _0_): send delay for packet (negative means send earlier) +
+
__tt__ (uint, default: _1000_): time tolerance in microseconds. Whenever schedule time minus realtime is below this value, the packet is sent right away -__runfor__ (sint, default: _-1_): run for the given time in ms. Negative value means run for ever (if loop) or source duration, 0 only outputs the sdp +
+
+__runfor__ (sint, default: _-1_): run for the given time in ms. Negative value means run for ever (if loop) or source duration, 0 only outputs the sdp +
+
__tso__ (sint, default: _-1_): set timestamp offset in microseconds. Negative value means random initial timestamp +
+
__xps__ (bool, default: _false_): force parameter set injection at each SAP. If not set, only inject if different from SDP ones +
+
__latm__ (bool, default: _false_): use latm for AAC payload format -__dst__ (cstr): URL for direct RTP mode +
+
+__dst__ (cstr): URL for direct RTP mode +
+
__ext__ (str): file extension for direct RTP mode +
+
__mime__ (cstr): set mime type for direct RTP mode +
diff --git a/docs/Filters/rtspout.md b/docs/Filters/rtspout.md index 84cc7fe3..b835d1ed 100644 --- a/docs/Filters/rtspout.md +++ b/docs/Filters/rtspout.md @@ -23,7 +23,8 @@ Example ``` gpac -i source -o rtsp://myip/sessionname gpac -i source -o rtsp://myip/sessionname -``` +``` + In this mode, only one session is possible. It is possible to [loop](#loop) the input source(s). # Server mode @@ -32,7 +33,8 @@ The filter can work as a regular RTSP server by specifying the [mounts](#mounts) Example ``` gpac rtspout:mounts=mydir1,mydir2 -``` +``` + In this case, content `RES` from any of the specified directory is exposed as `rtsp://SERVER/RES` The [mounts](#mounts) option can also specify access rule file(s), see `gpac -h creds`. When rules are used: @@ -45,7 +47,8 @@ Example ``` [foodir] name=bar -``` +``` + Content `RES` of this directory is exposed as `rtsp://SERVER/bar/RES`. @@ -55,7 +58,8 @@ Each URL can be absolute or local, in which case it is resolved against the moun Example ``` gpac -i rtsp://localhost/?pipe://mynamepipe&myfile.mp4 [dst filters] -``` +``` + The server will resolve this URL in a new session containing streams from `myfile.mp4` and streams from pipe `mynamepipe`. When setting [runfor](#runfor) in server mode, the server will exit at the end of the last session being closed. @@ -63,7 +67,8 @@ The parameter `name=VAL` is reserved to assign a session name in case multicast Example ``` gpac -i rtsp://localhost/?name=live?pipe://mynamepipe&myfile.mp4 [dst filters] -``` +``` + Usage of dynamic URLs can also be configured using the specific directory `$dynurl` in an access rule file. EX[$dynurl] @@ -86,44 +91,100 @@ The server mode supports handling RTSP over HTTP tunnel by default. This can be The tunnel conforms to QT specification, and only HTTP 1.0 and 1.1 tunnels are supported. -# Options - -__dst__ (cstr): location of destination resource -__port__ (uint, default: _554_): server port +# Options {.no-collapse} + +
+__dst__ (cstr): location of destination resource +
+
+__port__ (uint, default: _554_): server port +
+
__firstport__ (uint, default: _6000_): port for first stream in session -__mtu__ (uint, default: _1460_): size of RTP MTU in bytes +
+
+__mtu__ (uint, default: _1460_): size of RTP MTU in bytes +
+
__ttl__ (uint, default: _0_): time-to-live for multicast packets (a value of 0 uses client requested TTL, or 1) +
+
__ifce__ (str): default network interface to use +
+
__payt__ (uint, default: _96_, minmax: 96-127): payload type to use for dynamic decoder configurations -__mpeg4__ (bool, default: _false_): send all streams using MPEG-4 generic payload format if possible +
+
+__mpeg4__ (bool, default: _false_): send all streams using MPEG-4 generic payload format if possible +
+
__delay__ (sint, default: _0_): send delay for packet (negative means send earlier) +
+
__tt__ (uint, default: _1000_): time tolerance in microsecond (whenever schedule time minus realtime is below this value, the packet is sent right away) +
+
__runfor__ (sint, default: _-1_): run the session for the given time in ms. A negative value means run for ever if loop or source duration, value 0 only outputs the sdp +
+
__tso__ (sint, default: _-1_): set timestamp offset in microseconds (negative value means random initial timestamp) +
+
__xps__ (bool, default: _false_): force parameter set injection at each SAP. If not set, only inject if different from SDP ones -__latm__ (bool, default: _false_): use latm for AAC payload format -__mounts__ (strl): list of directories to expose in server mode +
+
+__latm__ (bool, default: _false_): use latm for AAC payload format +
+
+__mounts__ (strl): list of directories to expose in server mode +
+
__block_size__ (uint, default: _10000_): block size used to read TCP socket +
+
__maxc__ (uint, default: _100_): maximum number of connections +
+
__timeout__ (uint, default: _20_): timeout in seconds for inactive sessions (0 disable timeout) -__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences +
+
+__user_agent__ (str, default: _$GUA_): user agent string, by default solved from GPAC preferences +
+
__close__ (bool, default: _false_): close RTSP connection after each request, except when RTP over RTSP is used +
+
__loop__ (bool, default: _true_): loop all streams in session (not always possible depending on source type) +
+
__dynurl__ (bool, default: _false_): allow dynamic service assembly +
+
__mcast__ (enum, default: _off_): control multicast setup of a session - off: clients are never allowed to create a multicast - on: clients can create multicast sessions - mirror: clients can create a multicast session. Any later request to the same URL will use that multicast session +
+
__quit__ (bool, default: _false_): exit server once first session is over (for test purposes) +
+
__htun__ (bool, default: _true_): enable RTSP over HTTP tunnel +
+
__trp__ (enum, default: _both_): transport mode - both: allow TCP or UDP traffic - udp: only allow UDP traffic - tcp: only allow TCP traffic - -__cert__ (str): certificate file in PEM format to use for TLS mode -__pkey__ (str): private key file in PEM format to use for TLS mode +
+ +
+__cert__ (str): certificate file in PEM format to use for TLS mode +
+
+__pkey__ (str): private key file in PEM format to use for TLS mode +
diff --git a/docs/Filters/scte35dec.md b/docs/Filters/scte35dec.md index 7b9103c2..fb4f2587 100644 --- a/docs/Filters/scte35dec.md +++ b/docs/Filters/scte35dec.md @@ -10,12 +10,16 @@ packets as 23001-18 'emib' boxes. It also creates empty 'emeb' box in between following segmentation as hinted by the graph. -# Options +# Options {.no-collapse} -__mode__ (enum, default: _23001-18_): mode to operate in +
+__mode__ (enum, default: _23001-18_): mode to operate in - 23001-18: extract SCTE-35 markers as emib/emeb boxes for Event Tracks - passthrough: pass-through mode adding cue start property on splice points +
-__segdur__ (frac, default: _1/1_): segmentation duration in seconds. 0/0 flushes immediately for each input packet (beware of the bitrate overhead) +
+__segdur__ (frac, default: _1/1_): segmentation duration in seconds. 0/0 flushes immediately for each input packet (beware of the bitrate overhead) +
diff --git a/docs/Filters/sockin.md b/docs/Filters/sockin.md index 98b13f04..681266d4 100644 --- a/docs/Filters/sockin.md +++ b/docs/Filters/sockin.md @@ -28,25 +28,55 @@ When the socket is listening in keep-alive [ka](#ka) mode: - each connection close event will triger a pipeline flush -On OSX with VM packet replay you will need to force multicast routing, e.g. `route add -net 239.255.1.4/32 -interface vboxnet0` - -# Options +# Options {.no-collapse} -__src__ (cstr): address of source content +
+__src__ (cstr): address of source content +
+
__block_size__ (uint, default: _0x60000_): block size used to read socket -__port__ (uint, default: _1234_): default port if not specified +
+
+__port__ (uint, default: _1234_): default port if not specified +
+
__ifce__ (cstr): default multicast interface -__listen__ (bool, default: _false_): indicate the input socket works in server mode +
+
+__listen__ (bool, default: _false_): indicate the input socket works in server mode +
+
__ka__ (bool, default: _false_): keep socket alive if no more connections -__maxc__ (uint, default: _+I_): max number of concurrent connections +
+
+__maxc__ (uint, default: _+I_): max number of concurrent connections +
+
__tsprobe__ (bool, default: _true_): probe for MPEG-2 TS data, either RTP or raw UDP. Disabled if mime or ext are given and do not match MPEG-2 TS mimes/extensions -__ext__ (str): indicate file extension of udp data -__mime__ (str): indicate mime type of udp data +
+
+__ext__ (str): indicate file extension of udp data +
+
+__mime__ (str): indicate mime type of udp data +
+
__block__ (bool, default: _false_): set blocking mode for socket(s) +
+
__timeout__ (uint, default: _10000_): set timeout in ms for UDP socket(s), 0 to disable timeout +
+
__reorder_pck__ (uint, default: _100_): number of packets delay for RTP reordering (M2TS over RTP) +
+
__reorder_delay__ (uint, default: _10_): number of ms delay for RTP reordering (M2TS over RTP) +
+
__ssm__ (strl): list of IP to include for source-specific multicast +
+
__ssmx__ (strl): list of IP to exclude for source-specific multicast +
diff --git a/docs/Filters/sockout.md b/docs/Filters/sockout.md index 38e3af5b..23e4980c 100644 --- a/docs/Filters/sockout.md +++ b/docs/Filters/sockout.md @@ -30,31 +30,65 @@ If the numerator is 0, a packet is randomly chosen in that window. Example ``` :pckd=4/10 -``` +``` + This drops every 4th packet of each 10 packet window. Example ``` :pckr=0/100 -``` +``` + This reverts the send order of one random packet in each 100 packet window. -# Options +# Options {.no-collapse} -__dst__ (cstr): URL of destination +
+__dst__ (cstr): URL of destination +
+
__sockbuf__ (uint, default: _65536_): block size used to read file -__port__ (uint, default: _1234_): default port if not specified +
+
+__port__ (uint, default: _1234_): default port if not specified +
+
__ifce__ (cstr): default multicast interface -__ext__ (str): file extension of pipe data -__mime__ (str): mime type of pipe data +
+
+__ext__ (str): file extension of pipe data +
+
+__mime__ (str): mime type of pipe data +
+
__listen__ (bool, default: _false_): indicate the output socket works in server mode +
+
__maxc__ (uint, default: _+I_): max number of concurrent connections +
+
__ka__ (bool, default: _false_): keep socket alive if no more connections +
+
__kp__ (bool, default: _true_): keep packets in queue if no more clients -__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 +
+
+__start__ (dbl, default: _0.0_): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__speed__ (dbl, default: _1.0_): set playback speed. If negative and start is 0, start is set to -1 +
+
__rate__ (uint, default: _0_): set send rate in bps, disabled by default (as fast as possible) +
+
__pckr__ (frac, default: _0/0_): reverse packet every N +
+
__pckd__ (frac, default: _0/0_): drop packet every N +
+
__ttl__ (uint, default: _0_, minmax: 0-127): multicast TTL +
diff --git a/docs/Filters/svgplay.md b/docs/Filters/svgplay.md index 261b50aa..0ccb83d3 100644 --- a/docs/Filters/svgplay.md +++ b/docs/Filters/svgplay.md @@ -10,7 +10,9 @@ This filter parses SVG 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`. -# Options +# Options {.no-collapse} +
__sax_dur__ (uint, default: _0_): loading duration for SAX parsing, 0 disables SAX parsing +
diff --git a/docs/Filters/thumbs.md b/docs/Filters/thumbs.md index 10c2f0e1..16804c54 100644 --- a/docs/Filters/thumbs.md +++ b/docs/Filters/thumbs.md @@ -37,13 +37,15 @@ A single line of text can be inserted over each frame. Predefined keywords can b Example ``` gpac -i src reframer:saps=1 thumbs:snap=30:grid=6x30 -o dump/$num$.png -``` +``` + This will generate images from key-frames only, inserting one image every 30 seconds. Using key-frame filtering is much faster but may give unexpected results if there are not enough key-frames in the source. Example ``` gpac -i src thumbs:snap=0:grid=5x5 -o dump/$num$.png -``` +``` + This will generate one image containing 25 frames every second at 25 fps. If a single image per output frame is used and the scaling factor is 1, the input packet is reused as input with text and graphics overlaid. @@ -51,7 +53,8 @@ If a single image per output frame is used and the scaling factor is 1, the inpu Example ``` gpac -i src thumbs:grid=1x1:txt='Frame $time$' -o dump/$num$.png -``` +``` + This will inject text over each frame and keep timing and other packet properties. A json output can be specified in input [list](#list) to let applications retrieve frame position in output image from its timing. @@ -77,33 +80,78 @@ Since this is a costly process, it is recommended to use it combined with key-fr Example ``` gpac -i src reframer:saps=1 thumbs:mae=15 -o dump/$num$.png -``` +``` + The [maxsnap](#maxsnap) option can be used to force insertion after the given time if no scene cut is found. -# Options - -__grid__ (v2di, default: _6x0_): number of images per lines and columns -__scale__ (dbl, default: _-1_): scale factor for input size +# Options {.no-collapse} + +
+__grid__ (v2di, default: _6x0_): number of images per lines and columns +
+
+__scale__ (dbl, default: _-1_): scale factor for input size +
+
__mae__ (uint, default: _0_, minmax: 0,100): scene diff threshold using Mean Absolute Error +
+
__mse__ (uint, default: _0_, minmax: 0,100): scene diff threshold using Mean Square Error +
+
__lw__ (dbl, default: _0.0_): line width between images in pixels +
+
__lc__ (str, default: _white_): line color +
+
__clear__ (str, default: _white_): clear color -__snap__ (dbl, default: _-1_): duration between images, 0 for all images -__maxsnap__ (dbl, default: _-1_): maximum duration between two thumbnails when scene change detection is enabled +
+
+__snap__ (dbl, default: _-1_): duration between images, 0 for all images +
+
+__maxsnap__ (dbl, default: _-1_): maximum duration between two thumbnails when scene change detection is enabled +
+
__pfmt__ (pfmt, default: _rgb_): output pixel format +
+
__txt__ (str, default: __): text to insert per thumbnail +
+
__tc__ (str, default: _white_): text color +
+
__tb__ (str, default: _black_): text shadow +
+
__font__ (str, default: _SANS_): font to use +
+
__fs__ (dbl, default: _10_): font size to use in percent of scaled height +
+
__tv__ (dbl, default: _0_): text vertical position in percent of scaled height +
+
__thread__ (sint, default: _-1_): number of threads for software rasterizer, -1 for all available cores +
+
__blt__ (bool, default: _true_): use blit instead of software rasterizer +
+
__scref__ (bool, default: _false_): use last inserted image as reference for scene change detection +
+
__dropfirst__ (bool, default: _false_): drop first image +
+
__list__ (str, default: _null_): export json list of frame times and positions to given file +
+
__lxy__ (bool, default: _false_): add explicit x and y in json export +
diff --git a/docs/Filters/tileagg.md b/docs/Filters/tileagg.md index 9f2cb7dc..d576e82f 100644 --- a/docs/Filters/tileagg.md +++ b/docs/Filters/tileagg.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter aggregates a set of split tiled HEVC streams (`hvt1` or `hvt2` in ISOBMFF) into a single HEVC stream. -# Options +# Options {.no-collapse} -__tiledrop__ (uintl, updatable): specify indexes of tiles to drop -__ttimeout__ (uint, default: _10000_, updatable): number of milliseconds to wait until considering a tile packet lost, 0 waits forever +
+__tiledrop__ (uintl, updatable): specify indexes of tiles to drop +
+
+__ttimeout__ (uint, default: _10000_, updatable): number of milliseconds to wait until considering a tile packet lost, 0 waits forever +
diff --git a/docs/Filters/tilesplit.md b/docs/Filters/tilesplit.md index 96131460..c2043b21 100644 --- a/docs/Filters/tilesplit.md +++ b/docs/Filters/tilesplit.md @@ -20,7 +20,9 @@ __Warning: The filter does not check if tiles are independently-coded (MCTS) !__ __Warning: Support for dynamic changes of tiling grid has not been tested !__ -# Options +# Options {.no-collapse} -__tiledrop__ (uintl, updatable): specify indexes of tiles to drop (0-based, in tile raster scan order) +
+__tiledrop__ (uintl, updatable): specify indexes of tiles to drop (0-based, in tile raster scan order) +
diff --git a/docs/Filters/tssplit.md b/docs/Filters/tssplit.md index 21cd73d0..76dbbc9f 100644 --- a/docs/Filters/tssplit.md +++ b/docs/Filters/tssplit.md @@ -10,10 +10,18 @@ Only the PAT table is rewritten, other tables (PAT, PMT) and streams (PES) are f If [dvb](#dvb) is set, global DVB tables of the input multiplex are forwarded to each output mux; otherwise these tables are discarded. -# Options +# Options {.no-collapse} +
__dvb__ (bool, default: _true_): forward all packets from global DVB PIDs +
+
__mux_id__ (sint, default: _-1_): set initial ID of output mux; the first program will use mux_id, the second mux_id+1, etc. If not set, this value will be set to sourceMuxId*255 +
+
__avonly__ (bool, default: _true_): do not forward programs with no AV component +
+
__nb_pack__ (uint, default: _10_): pack N packets before sending +
diff --git a/docs/Filters/ttmldec.md b/docs/Filters/ttmldec.md index e79ad11b..383df55a 100644 --- a/docs/Filters/ttmldec.md +++ b/docs/Filters/ttmldec.md @@ -17,19 +17,35 @@ In stand-alone rendering (no associated video), the filter will use: -# Options +# Options {.no-collapse} +
__script__ (str, default: _$GSHARE/scripts/ttml-renderer.js_): location of TTML SVG JS renderer +
+
__font__ (str, default: _SANS_, updatable): font +
+
__fontSize__ (flt, default: _20_, updatable): font size +
+
__color__ (str, default: _white_, updatable): text color +
+
__valign__ (enum, default: _bottom_, updatable): vertical alignment - bottom: align text at bottom of text area - center: align text at center of text area - top: align text at top of text area +
+
__lineSpacing__ (flt, default: _1.0_, updatable): line spacing as scaling factor to font size +
+
__txtw__ (uint, default: _400_): default width in standalone rendering +
+
__txth__ (uint, default: _200_): default height in standalone rendering +
diff --git a/docs/Filters/ttxtdec.md b/docs/Filters/ttxtdec.md index 5b37f61d..88caa787 100644 --- a/docs/Filters/ttxtdec.md +++ b/docs/Filters/ttxtdec.md @@ -16,10 +16,18 @@ In stand-alone rendering (no associated video), the filter will use: -# Options +# Options {.no-collapse} +
__texture__ (bool, default: _false_): use texturing for output text +
+
__outline__ (bool, default: _false_): draw text outline +
+
__txtw__ (uint, default: _400_): default width in standalone rendering +
+
__txth__ (uint, default: _200_): default height in standalone rendering +
diff --git a/docs/Filters/tx3g2srt.md b/docs/Filters/tx3g2srt.md index a35e783b..f7b950e7 100644 --- a/docs/Filters/tx3g2srt.md +++ b/docs/Filters/tx3g2srt.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts a single ISOBMFF TX3G stream to an SRT unframed stream. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
diff --git a/docs/Filters/tx3g2vtt.md b/docs/Filters/tx3g2vtt.md index 68a491da..e1dfc888 100644 --- a/docs/Filters/tx3g2vtt.md +++ b/docs/Filters/tx3g2vtt.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts a single ISOBMFF TX3G stream to a WebVTT unframed stream. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
diff --git a/docs/Filters/txtin.md b/docs/Filters/txtin.md index 9bb51b75..8c01dd92 100644 --- a/docs/Filters/txtin.md +++ b/docs/Filters/txtin.md @@ -61,7 +61,8 @@ MP4Box -add test.ttml:sopt:ttml_zero=T10:00:00 [...] gpac -i test.ttml --ttml_zero=10:00:00 [...] gpac -i test.ttml --ttml_zero=T10:00:00 [...] MP4Box -add test.ttml --ttml_zero=10:00:00 [...] -``` +``` + # Simple Text Support @@ -70,7 +71,8 @@ Example ``` gpac -i test.txt:#CodecID=stxt [...] gpac fin:pck="Text Data":#CodecID=stxt [...] -``` +``` + The content of the source file will be the payload of the text sample. The [stxtmod](#stxtmod) option allows specifying WebVTT, TX3G or simple text mode for output format. In this mode, the [stxtdur](#stxtdur) option is used to control the duration of the generated subtitle: @@ -86,26 +88,63 @@ When reframing simple text streams from demuxers (e.g. subtitles from MKV), the When importing SRT, SUB or SSA files, the output format of the PID can be selected using [stxtmod](#stxtmod). -# Options +# Options {.no-collapse} +
__nodefbox__ (bool, default: _false_): skip default text box +
+
__noflush__ (bool, default: _false_): skip final sample flush for srt -__fontname__ (str): default font -__fontsize__ (uint, default: _18_): default font size -__lang__ (str): default language -__width__ (uint, default: _0_): default width of text area -__height__ (uint, default: _0_): default height of text area -__txtx__ (uint, default: _0_): default horizontal offset of text area: -1 (left), 0 (center) or 1 (right) -__txty__ (uint, default: _0_): default vertical offset of text area: -1 (bottom), 0 (center) or 1 (top) +
+
+__fontname__ (str): default font +
+
+__fontsize__ (uint, default: _18_): default font size +
+
+__lang__ (str): default language +
+
+__width__ (uint, default: _0_): default width of text area +
+
+__height__ (uint, default: _0_): default height of text area +
+
+__txtx__ (uint, default: _0_): default horizontal offset of text area: -1 (left), 0 (center) or 1 (right) +
+
+__txty__ (uint, default: _0_): default vertical offset of text area: -1 (bottom), 0 (center) or 1 (top) +
+
__zorder__ (sint, default: _0_): default z-order of the PID +
+
__timescale__ (uint, default: _1000_): default timescale of the PID +
+
__ttml_split__ (bool, default: _true_): split ttml doc in non-overlapping samples +
+
__ttml_cts__ (lfrac, default: _-1/1_): first sample cts - see filter help +
+
__ttml_dur__ (frac, default: _0/1_): sample duration when not spliting split - see filter help +
+
__ttml_embed__ (bool, default: _false_): force embedding TTML resources +
+
__ttml_zero__ (str): set subtitle zero time for TTML +
+
__no_empty__ (bool, default: _false_): do not send empty samples +
+
__stxtdur__ (frac, default: _1_): duration for simple text +
+
__stxtmod__ (enum, default: _tx3g_): text stream mode for simple text streams and SRT inputs - stxt: output PID formatted as simple text stream @@ -113,5 +152,6 @@ When importing SRT, SUB or SSA files, the output format of the PID can be select - tx3g: output PID formatted as TX3G/Apple stream - vtt: output PID formatted as WebVTT stream - webvtt: same as vtt (for backward compatiblity +
diff --git a/docs/Filters/ufadts.md b/docs/Filters/ufadts.md index e732744c..7bfde37f 100644 --- a/docs/Filters/ufadts.md +++ b/docs/Filters/ufadts.md @@ -8,12 +8,14 @@ This filter may be automatically loaded during graph resolution. This filter converts AAC streams into ADTS encapsulated data. -# Options +# Options {.no-collapse} +
__mpeg2__ (enum, default: _auto_): signal as MPEG2 AAC - auto: selects based on AAC profile - no: always signals as MPEG-4 AAC - yes: always signals as MPEG-2 AAC +
diff --git a/docs/Filters/uflatm.md b/docs/Filters/uflatm.md index 6be7b12a..1230c2a0 100644 --- a/docs/Filters/uflatm.md +++ b/docs/Filters/uflatm.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts AAC streams into LATM encapsulated data. -# Options +# Options {.no-collapse} +
__fdsi__ (frac, default: _0_): set delay between two LATM Audio Config +
diff --git a/docs/Filters/ufm4v.md b/docs/Filters/ufm4v.md index df33dac6..7502d39f 100644 --- a/docs/Filters/ufm4v.md +++ b/docs/Filters/ufm4v.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts MPEG-4 part 2 visual streams into writable format (reinsert decoder config). -# Options +# Options {.no-collapse} -__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
+__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
diff --git a/docs/Filters/ufmhas.md b/docs/Filters/ufmhas.md index 43e51d81..7ba23df8 100644 --- a/docs/Filters/ufmhas.md +++ b/docs/Filters/ufmhas.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts MPEG-H Audio streams into MHAS encapsulated data. -# Options +# Options {.no-collapse} +
__syncp__ (bool, default: _false_): if set, insert sync packet at each frame, otherwise only at SAP +
diff --git a/docs/Filters/ufnalu.md b/docs/Filters/ufnalu.md index 5943b372..87a38bf0 100644 --- a/docs/Filters/ufnalu.md +++ b/docs/Filters/ufnalu.md @@ -8,15 +8,23 @@ This filter may be automatically loaded during graph resolution. This filter converts AVC|H264 and HEVC streams into AnnexB format, with inband parameter sets and start codes. -# Options +# Options {.no-collapse} -__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
+__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
+
__extract__ (enum, default: _all_): layer extraction mode - all: extracts all layers - base: extract base layer only - layer: extract non-base layer(s) only +
+
__delim__ (bool, default: _true_): insert AU Delimiter NAL -__pps_inband__ (bool, default: _false_): inject PPS at each non SAP frame, ignored if rcfg is not set +
+
+__pps_inband__ (bool, default: _false_): inject PPS at each non SAP frame, ignored if rcfg is not set +
diff --git a/docs/Filters/ufobu.md b/docs/Filters/ufobu.md index 1eae0026..ca707a7d 100644 --- a/docs/Filters/ufobu.md +++ b/docs/Filters/ufobu.md @@ -10,7 +10,9 @@ The temporal delimiter OBU is re-inserted in annexB (`.av1` and `.av1b`files, wi _Note: VP8/9 codecs will only use IVF output (equivalent to file extension `.ivf` or `:ext=ivf` set on output)._ -# Options +# Options {.no-collapse} -__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
+__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
diff --git a/docs/Filters/ufttxt.md b/docs/Filters/ufttxt.md index 6d2b582c..385d5f89 100644 --- a/docs/Filters/ufttxt.md +++ b/docs/Filters/ufttxt.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts a single ISOBMFF TX3G stream to TTXT (xml format) unframed stream. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
diff --git a/docs/Filters/ufvc1.md b/docs/Filters/ufvc1.md index c997362c..72a0807b 100644 --- a/docs/Filters/ufvc1.md +++ b/docs/Filters/ufvc1.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts VC1 visual streams into writable format (reinsert decoder config and start codes if needed). -# Options +# Options {.no-collapse} -__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
+__rcfg__ (bool, default: _true_): force repeating decoder config at each I-frame +
diff --git a/docs/Filters/ufvtt.md b/docs/Filters/ufvtt.md index 8b2bd664..8548b0af 100644 --- a/docs/Filters/ufvtt.md +++ b/docs/Filters/ufvtt.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter converts a single ISOBMFF WebVTT stream to its unframed format. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
+
__merge_cues__ (bool, default: _true_): merge VTT cues (undo ISOBMFF cue split) +
diff --git a/docs/Filters/uncvdec.md b/docs/Filters/uncvdec.md index 06e98b3a..d30e7972 100644 --- a/docs/Filters/uncvdec.md +++ b/docs/Filters/uncvdec.md @@ -8,8 +8,12 @@ This filter may be automatically loaded during graph resolution. This filter translates UNCV pixel format to a usable pixel format. -# Options +# Options {.no-collapse} -__force_pf__ (bool, default: _false_): ignore possible mapping to GPAC pixel formats -__no_tile__ (bool, default: _false_): ignore tiling info (debug) +
+__force_pf__ (bool, default: _false_): ignore possible mapping to GPAC pixel formats +
+
+__no_tile__ (bool, default: _false_): ignore tiling info (debug) +
diff --git a/docs/Filters/uncvg.md b/docs/Filters/uncvg.md index 949c06a3..be33bb5c 100644 --- a/docs/Filters/uncvg.md +++ b/docs/Filters/uncvg.md @@ -35,12 +35,19 @@ Components are described as N[bpc][+k] with -# Options +# Options {.no-collapse} -__vsize__ (v2d, default: _128x128_): width and height of output image -__c__ (strl, default: _R8,G8,B8_): image components -__tiles__ (v2d, default: _1x1_): number of horizontal and vertical tiles -__interleave__ (enum, default: _pix_): interleave type +
+__vsize__ (v2d, default: _128x128_): width and height of output image +
+
+__c__ (strl, default: _R8,G8,B8_): image components +
+
+__tiles__ (v2d, default: _1x1_): number of horizontal and vertical tiles +
+
+__interleave__ (enum, default: _pix_): interleave type - comp: component-based interleaving (planar modes) - pix: pixel-based interleaving (packed modes) @@ -48,32 +55,75 @@ Components are described as N[bpc][+k] with - row: row-based interleaving - tile: tile-component interleaving - multi: pixel-based interleaving (packed modes) for sub-sampled modes +
-__sampling__ (enum, default: _none_): sampling types +
+__sampling__ (enum, default: _none_): sampling types - none: no sub-sampling - 422: YUV 4:2:2 sub-sampling - 420: YUV 4:2:0 sub-sampling - 411: YUV 4:1:1 sub-sampling +
-__block_size__ (uint, default: _0_): block size in bytes -__pad_lsb__ (bool, default: _false_): padded bits are at LSB in the block -__ble__ (bool, default: _false_): block is little endian -__br__ (bool, default: _false_): block has reversed components -__pixel_size__ (uint, default: _0_): size of pixel in bytes -__row_align__ (uint, default: _0_): row alignment in bytes -__tile_align__ (uint, default: _0_): tile alignment in bytes -__cle__ (bool, default: _false_): byte-aligned components are little endian -__img__ (str, default: __): use specified image as input instead of RGB generation -__asize__ (bool, default: _false_): use input image size -__pal__ (strl, default: _red,green,blue,white,black,yellow,cyan,grey,orange,violet_): default palette for color generation -__fa__ (strl, default: _B,G,G,R_): bayer-like filter - only 2x2 on R,G,B components is supported -__bpm__ (strl, default: __): set sensor bad pixel map as a list of cN (broken column), rM (broken row) or NxM (single pixel) -__fps__ (frac, default: _25/1_): frame rate to generate - using 0 will trigger item muxing -__dur__ (frac, default: _1/1_): duration to generate - using 0 will trigger item muxing -__cloc__ (uint, default: _-1_, minmax: -1,6): set chroma location type -__stereo__ (bool, default: _false_): dump a stereo image -__sq__ (flt, default: _0_): generate square patterns instead of columns -__shade__ (bool, default: _false_): shade pixels from black at bottom to full intensity at top -__scpt__ (bool, default: _false_): use single color per tile, first tile using the first color in palette +
+__block_size__ (uint, default: _0_): block size in bytes +
+
+__pad_lsb__ (bool, default: _false_): padded bits are at LSB in the block +
+
+__ble__ (bool, default: _false_): block is little endian +
+
+__br__ (bool, default: _false_): block has reversed components +
+
+__pixel_size__ (uint, default: _0_): size of pixel in bytes +
+
+__row_align__ (uint, default: _0_): row alignment in bytes +
+
+__tile_align__ (uint, default: _0_): tile alignment in bytes +
+
+__cle__ (bool, default: _false_): byte-aligned components are little endian +
+
+__img__ (str, default: __): use specified image as input instead of RGB generation +
+
+__asize__ (bool, default: _false_): use input image size +
+
+__pal__ (strl, default: _red,green,blue,white,black,yellow,cyan,grey,orange,violet_): default palette for color generation +
+
+__fa__ (strl, default: _B,G,G,R_): bayer-like filter - only 2x2 on R,G,B components is supported +
+
+__bpm__ (strl, default: __): set sensor bad pixel map as a list of cN (broken column), rM (broken row) or NxM (single pixel) +
+
+__fps__ (frac, default: _25/1_): frame rate to generate - using 0 will trigger item muxing +
+
+__dur__ (frac, default: _1/1_): duration to generate - using 0 will trigger item muxing +
+
+__cloc__ (uint, default: _-1_, minmax: -1,6): set chroma location type +
+
+__stereo__ (bool, default: _false_): dump a stereo image +
+
+__sq__ (flt, default: _0_): generate square patterns instead of columns +
+
+__shade__ (bool, default: _false_): shade pixels from black at bottom to full intensity at top +
+
+__scpt__ (bool, default: _false_): use single color per tile, first tile using the first color in palette +
diff --git a/docs/Filters/unframer.md b/docs/Filters/unframer.md index 7d4e0b4e..0859a503 100644 --- a/docs/Filters/unframer.md +++ b/docs/Filters/unframer.md @@ -9,7 +9,8 @@ This filter is used to force reframing of input sources using the same internal Example ``` gpac -i src.mp4 unframer -o dst.mp4 -``` +``` + This will: - force input PIDs of unframer to be in serialized form (AnnexB, ADTS, ...) diff --git a/docs/Filters/vcrop.md b/docs/Filters/vcrop.md index 2a1ba655..f9adea5f 100644 --- a/docs/Filters/vcrop.md +++ b/docs/Filters/vcrop.md @@ -9,15 +9,21 @@ Filters of this class can connect to each-other. This filter is used to crop raw video data. -# Options +# Options {.no-collapse} -__wnd__ (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 +
+__wnd__ (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 +
+
__copy__ (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) +
+
__round__ (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) +
diff --git a/docs/Filters/vflip.md b/docs/Filters/vflip.md index d9615df9..e98e1917 100644 --- a/docs/Filters/vflip.md +++ b/docs/Filters/vflip.md @@ -9,13 +9,15 @@ Filters of this class can connect to each-other. This filter flips uncompressed video frames vertically, horizontally, in both directions or no flip -# Options +# Options {.no-collapse} +
__mode__ (enum, default: _vert_, updatable): flip mode - off: no flipping (passthrough) - vert: vertical flip - horiz: horizontal flip - both: horizontal and vertical flip +
diff --git a/docs/Filters/vobsubdmx.md b/docs/Filters/vobsubdmx.md index 1442f6f1..65a9f533 100644 --- a/docs/Filters/vobsubdmx.md +++ b/docs/Filters/vobsubdmx.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter parses VobSub files/data to produce media PIDs and frames. -# Options +# Options {.no-collapse} +
__blankframe__ (bool, default: _true_): force inserting a blank frame if first subpic is not at 0 +
diff --git a/docs/Filters/vout.md b/docs/Filters/vout.md index 23cab6b6..df6a4c6e 100644 --- a/docs/Filters/vout.md +++ b/docs/Filters/vout.md @@ -15,45 +15,100 @@ In this case, the window is not visible and only the listed frames are drawn to The pixel format of the dumped frame is always RGB in OpenGL and matches the video backbuffer format in 2D mode. -# Options +# Options {.no-collapse} -__drv__ (cstr): video driver name +
+__drv__ (cstr): video driver name +
+
__vsync__ (bool, default: _true_): enable video screen sync +
+
__drop__ (bool, default: _false_, updatable): enable dropping late frames +
+
__disp__ (enum, default: _gl_): display mode - gl: OpenGL - pbo: OpenGL with PBO - blit: 2D hardware blit - soft: software blit +
-__start__ (dbl, default: _0.0_, updatable): set playback start offset. A negative value means percent of media duration with -1 equal to duration -__dur__ (lfrac, default: _0_): only play the specified duration -__speed__ (dbl, default: _1.0_, updatable): set playback speed when vsync is on. If speed is negative and start is 0, start is set to -1 -__hold__ (dbl, default: _1.0_): number of seconds to hold display for single-frame streams (a negative value force a hold on last frame for single or multi-frames streams) +
+__start__ (dbl, default: _0.0_, updatable): set playback start offset. A negative value means percent of media duration with -1 equal to duration +
+
+__dur__ (lfrac, default: _0_): only play the specified duration +
+
+__speed__ (dbl, default: _1.0_, updatable): set playback speed when vsync is on. If speed is negative and start is 0, start is set to -1 +
+
+__hold__ (dbl, default: _1.0_): number of seconds to hold display for single-frame streams (a negative value force a hold on last frame for single or multi-frames streams) +
+
__linear__ (bool, default: _false_): use linear filtering instead of nearest pixel for GL mode +
+
__back__ (uint, default: _0x808080_): back color for transparent images +
+
__wsize__ (v2di, default: _-1x-1_): default init window size - 0x0 holds the window size of the first frame - negative values indicate video media size +
+
__wpos__ (v2di, default: _-1x-1_): default position (0,0 top-left) +
+
__vdelay__ (frac, default: _0_, updatable): set delay in sec, positive value displays after audio clock -__hide__ (bool, default: _false_): hide output window -__fullscreen__ (bool, default: _false_, updatable): use fullscreen -__buffer__ (uint, default: _100_): set playout buffer in ms -__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer -__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
+__hide__ (bool, default: _false_): hide output window +
+
+__fullscreen__ (bool, default: _false_, updatable): use fullscreen +
+
+__buffer__ (uint, default: _100_): set playout buffer in ms +
+
+__mbuffer__ (uint, default: _0_): set max buffer occupancy in ms. If less than buffer, use buffer +
+
+__rbuffer__ (uint, default: _0_, updatable): rebuffer trigger in ms. If 0 or more than buffer, disable rebuffering +
+
__dumpframes__ (uintl): ordered list of frames to dump, 1 being first frame. Special value `0` means dump all frames +
+
__out__ (str, default: _dump_): radical of dump frame filenames. If no extension provided, frames are exported as `$OUT_%d.PFMT` +
+
__async__ (bool, default: _true_): sync video to audio output if any +
+
__owsize__ (v2di): output window size (readonly) +
+
__buffer_done__ (bool): buffer done indication (readonly) +
+
__rebuffer__ (luint): system time in us at which last rebuffer started, 0 if not rebuffering (readonly) +
+
__vjs__ (bool, default: _true_): use default JS script for vout control +
+
__media_offset__ (dbl, default: _0_): media offset (substract this value to CTS to get media time - readonly) +
+
__wid__ (uint, default: _0_): window id (readonly) +
+
__vflip__ (enum, default: _no_, updatable): flip video (GL only) - no: no flipping @@ -61,12 +116,15 @@ The pixel format of the dumped frame is always RGB in OpenGL and matches the vid - h: horizontal flip - vh: horizontal and vertical - hv: same as vh +
+
__vrot__ (enum, default: _0_, updatable): rotate video by given angle - 0: no rotation - 90: rotate 90 degree counter clockwise - 180: rotate 180 degree - 270: rotate 90 degree clockwise +
diff --git a/docs/Filters/vtbdec.md b/docs/Filters/vtbdec.md index 45adde1e..0c73ff6a 100644 --- a/docs/Filters/vtbdec.md +++ b/docs/Filters/vtbdec.md @@ -1,6 +1,6 @@ -# VideoToolBox decoder +# VideoToolBox decoder {:data-level="all"} Register name used to load filter: __vtbdec__ This filter may be automatically loaded during graph resolution. diff --git a/docs/Filters/vtt2tx3g.md b/docs/Filters/vtt2tx3g.md index 91064c10..021ba165 100644 --- a/docs/Filters/vtt2tx3g.md +++ b/docs/Filters/vtt2tx3g.md @@ -17,8 +17,12 @@ Unframed WebVTT packets consist in single cues: -# Options +# Options {.no-collapse} -__fontname__ (str): default font -__fontsize__ (uint, default: _18_): default font size +
+__fontname__ (str): default font +
+
+__fontsize__ (uint, default: _18_): default font size +
diff --git a/docs/Filters/vttdec.md b/docs/Filters/vttdec.md index 229d8529..e5107e6b 100644 --- a/docs/Filters/vttdec.md +++ b/docs/Filters/vttdec.md @@ -16,13 +16,27 @@ In stand-alone rendering (no associated video), the filter will use: -# Options +# Options {.no-collapse} +
__script__ (str, default: _$GSHARE/scripts/webvtt-renderer.js_): location of WebVTT SVG JS renderer +
+
__font__ (str, default: _SANS_, updatable): font +
+
__fontSize__ (flt, default: _20_, updatable): font size +
+
__color__ (str, default: _white_, updatable): text color +
+
__lineSpacing__ (flt, default: _1.0_, updatable): line spacing as scaling factor to font size +
+
__txtw__ (uint, default: _400_): default width in standalone rendering +
+
__txth__ (uint, default: _200_): default height in standalone rendering +
diff --git a/docs/Filters/writegen.md b/docs/Filters/writegen.md index 9e21a8af..e8d8bdda 100644 --- a/docs/Filters/writegen.md +++ b/docs/Filters/writegen.md @@ -9,30 +9,52 @@ Generic single stream to file converter, used when extracting/converting PIDs. The writegen filter should usually not be explicitly loaded without a source ID specified, since the filter would likely match any PID connection. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results -__pfmt__ (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): pixel format for raw extract. If not set, derived from extension +
+
+__pfmt__ (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): pixel format for raw extract. If not set, derived from extension +
-__afmt__ (afmt, default: _none_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): audio format for raw extract. If not set, derived from extension +
+__afmt__ (afmt, default: _none_, Enum: none|u8|s16|s16b|s24|s24b|s32|s32b|flt|fltb|dbl|dblb|u8p|s16p|s24p|s32p|fltp|dblp): audio format for raw extract. If not set, derived from extension +
+
__decinfo__ (enum, default: _auto_): decoder config insert mode - no: never inserted - first: inserted on first packet - sap: inserted at each SAP - auto: selects between no and first based on media type +
+
__split__ (bool, default: _false_): force one file per decoded frame -__frame__ (bool, default: _false_): force single frame dump with no rewrite. In this mode, all codec types are supported -__sstart__ (uint, default: _0_): start number of frame to forward. If 0, all samples are forwarded -__send__ (uint, default: _0_): end number of frame to forward. If less than start frame, all samples after start are forwarded -__dur__ (frac, default: _0_): duration of media to forward after first sample. If 0, all samples are forwarded -__merge_region__ (bool, default: _false_): merge TTML regions with same ID while reassembling TTML doc -__vtth__ (enum, default: _seg_): vtt header injection mode +
+
+__frame__ (bool, default: _false_): force single frame dump with no rewrite. In this mode, all codec types are supported +
+
+__sstart__ (uint, default: _0_): start number of frame to forward. If 0, all samples are forwarded +
+
+__send__ (uint, default: _0_): end number of frame to forward. If less than start frame, all samples after start are forwarded +
+
+__dur__ (frac, default: _0_): duration of media to forward after first sample. If 0, all samples are forwarded +
+
+__merge_region__ (bool, default: _false_): merge TTML regions with same ID while reassembling TTML doc +
+
+__vtth__ (enum, default: _seg_): vtt header injection mode - single: inject only at first frame of the stream - seg: inject at each non-empty segment - all: inject at each segment even empty ones +
diff --git a/docs/Filters/writeqcp.md b/docs/Filters/writeqcp.md index 822ce2fa..23b17d05 100644 --- a/docs/Filters/writeqcp.md +++ b/docs/Filters/writeqcp.md @@ -8,7 +8,9 @@ This filter may be automatically loaded during graph resolution. This filter converts a single QCELP, EVRC or MSV stream to a QCP output file. -# Options +# Options {.no-collapse} +
__exporter__ (bool, default: _false_): compatibility with old exporter, displays export results +
diff --git a/docs/Filters/xviddec.md b/docs/Filters/xviddec.md index f8606e0a..c9cbc28d 100644 --- a/docs/Filters/xviddec.md +++ b/docs/Filters/xviddec.md @@ -8,11 +8,21 @@ This filter may be automatically loaded during graph resolution. This filter decodes MPEG-4 part 2 (and DivX) through libxvidcore library. -# Options +# Options {.no-collapse} +
__deblock_y__ (bool, default: _false_): enable Y deblocking +
+
__deblock_uv__ (bool, default: _false_): enable UV deblocking +
+
__film_effect__ (bool, default: _false_): enable film effect +
+
__dering_y__ (bool, default: _false_): enable Y deblocking +
+
__dering_uv__ (bool, default: _false_): enable UV deblocking +
diff --git a/docs/Howtos/The-GPAC-Log-System.md b/docs/Howtos/The-GPAC-Log-System.md index 7c6b2013..1009a89e 100644 --- a/docs/Howtos/The-GPAC-Log-System.md +++ b/docs/Howtos/The-GPAC-Log-System.md @@ -1,10 +1,36 @@ -# Introduction +--- +tags: +- pid +- data +- codec +- session +- stream +- xml +- hevc +- dump +- scene +- media +- signal +- compositor +- libgpac +- option +- graph +- source +- input +- output +- mpeg +- sink +--- + + + +# Introduction {:data-level="all"} A log is a way of keeping record of what's happening when executing a software. The GPAC framework has log capabilities to analyze what is going on when running MP4Box, gpac or other libgpac based applications. This article explains the features of the log system and how to use it. For more information on latest syntax and options, [check here](core_logs). -# Overview +# Overview {:data-level="all"} The GPAC log system is based on two orthogonal concepts: @@ -22,8 +48,7 @@ The general syntax is: Concrete examples are given further in this article. -# Example of available Tools - +# 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, ...) @@ -43,7 +68,7 @@ Concrete examples are given further in this article. - GF_LOG_ALL (all) : all available logs -# Available Levels +# Available Levels - GF_LOG_QUIET (quiet) : disable all Log message - GF_LOG_ERROR (error) : log message describes an error diff --git a/docs/Howtos/archives/Language-tagging-in-GPAC.md b/docs/Howtos/archives/Language-tagging-in-GPAC.md index 269614c1..84788058 100644 --- a/docs/Howtos/archives/Language-tagging-in-GPAC.md +++ b/docs/Howtos/archives/Language-tagging-in-GPAC.md @@ -1,3 +1,22 @@ +--- +tags: +- profile +- mp4 +- mpd +- media +- isomedia +- isobmff +- data +- stream +- xml +- mpeg +- box +- dash +- track +--- + + + MP4 files (and GPAC) have been using a 3-character-code to indicate the language of a track, following the standard [ISO 639-2:1998](http://en.wikipedia.org/wiki/List_of_ISO_639-2_codes). This way of language tagging has since then been superseded and the current practice is to use an IETF standard called [BCP-47](http://tools.ietf.org/html/bcp47) (Best Current Practice) a.k.a. RFC 5646. This new language tagging approach is a bit more complex. It uses mainly 2, 3 or 4 characters, possibly followed by extensions separated with "-" for instance for regional or script variations of a language. Examples of tags are: "en", "fr-FR" (French French) vs. "fr-CA" (Canadian French), ... see more examples [here](http://tools.ietf.org/html/rfc5646#appendix-A). diff --git a/docs/Howtos/archives/MPEG-HEVC-Support-in-GPAC.md b/docs/Howtos/archives/MPEG-HEVC-Support-in-GPAC.md index 82ee1ccc..ff965f69 100644 --- a/docs/Howtos/archives/MPEG-HEVC-Support-in-GPAC.md +++ b/docs/Howtos/archives/MPEG-HEVC-Support-in-GPAC.md @@ -1,3 +1,20 @@ +--- +tags: +- mp4 +- source +- isomedia +- compression +- isobmff +- stream +- raw +- codec +- mpeg +- hevc +- dash +--- + + + ## Playback support The playback support is powered by the open-source [OpenHEVC decoder](https://github.com/OpenHEVC/openHEVC).  diff --git a/docs/Howtos/archives/SVC-Support-in-MP4Box.md b/docs/Howtos/archives/SVC-Support-in-MP4Box.md index c2f55e79..7b0471d3 100644 --- a/docs/Howtos/archives/SVC-Support-in-MP4Box.md +++ b/docs/Howtos/archives/SVC-Support-in-MP4Box.md @@ -1,3 +1,26 @@ +--- +tags: +- option +- mp4 +- source +- pid +- compression +- layer +- binary +- data +- raw +- codec +- mpeg +- stream +- bitstream +- hevc +- decoder +- h264 +- track +--- + + + GPAC supports packaging and playback of Scalable Video Coding (SVC) and layered-HEVC (L-HEVC). diff --git a/docs/Howtos/archives/Use-MP4Box-to-dump-and-analyze-broadcast-TS-streams.md b/docs/Howtos/archives/Use-MP4Box-to-dump-and-analyze-broadcast-TS-streams.md index 2c5b6793..515a335d 100644 --- a/docs/Howtos/archives/Use-MP4Box-to-dump-and-analyze-broadcast-TS-streams.md +++ b/docs/Howtos/archives/Use-MP4Box-to-dump-and-analyze-broadcast-TS-streams.md @@ -1,3 +1,15 @@ +--- +tags: +- option +- mp4 +- input +- box +- broadcast +- dump +--- + + + ## Foreword This feature is deprecated in MP4Box starting from GPAC 0.9.0. You can grab input streams using [gpac](gpac_general): diff --git a/docs/Howtos/avmix_tuto.md b/docs/Howtos/avmix_tuto.md index a20ffbe9..51fe2d02 100644 --- a/docs/Howtos/avmix_tuto.md +++ b/docs/Howtos/avmix_tuto.md @@ -1,4 +1,43 @@ -# Overview +--- +tags: +- heif +- data +- overlay +- filter +- pipe +- encrypt +- sample +- manifest +- pipeline +- frame +- raw +- stream +- encode +- bitstream +- avmix +- sequence +- dump +- offscreen +- scene +- media +- isobmff +- property +- group +- track +- option +- mp4 +- source +- chain +- input +- isomedia +- output +- decoding +- sink +--- + + + +# Overview {:data-level="all"} We discuss here how to use the AVMix filter to do offline or live video editing. This filter is a [JS filter](jsf) and can be modified fairly simply. @@ -32,7 +71,7 @@ By default, the filter will run in live mode, and will never stop. You can run i ``` -# General concepts +# General concepts {:data-level="beginner"} ## Declaring media To declare media for the mixer, you need to use a sequence object along with your media source. Typically: @@ -216,6 +255,7 @@ A group with `opacity` less than 1 will be rendered offscreen and drawn with the ]} ] ``` + You can also use the `scaler` property to change the offscreen resolution of the group, to create a pixelated effect, here combined with opacity changing: ``` @@ -337,6 +377,7 @@ For example, load: {"seq": [ { "src": [{"in": "media.mp4"}], "start": 1, "stop": 5} ] } ] ``` + then load (updating `loop` parameter): ``` [ @@ -373,6 +414,7 @@ You should now see "no input" message when playing. Without closing the player, { "id": "scene1", "sources": ["seq1"]} ] ``` + And the video sequence will start ! You can use for start and stop time values: - "now": will resolve to current UTC time @@ -380,7 +422,7 @@ And the video sequence will start ! You can use for start and stop time values: - date: will use the date as the start/stop time -# Some examples +# Some examples {:data-level="beginner"} ## Transparent Logo insertion Simplified version of above example, with a single source and logo @@ -731,6 +773,7 @@ The following shows a cross-fade of two inputs using an offscreen group in alpha ] } ] ``` + In this mode, the texturing parameters used by the offscreen group can be modified using the properties `*_rep`of the shape object. @@ -820,6 +863,7 @@ The simplest usage of a watcher is to forward a property to another object prope {"watch": "s1@y", "target": "s2@y"} ] ``` + In this example, any modification to `s1.x` (resp `s1.y`) through timers, playlist update or other JS code will automatically copy the values to `s2.x` (resp `s2.y`) . If you want to modify the value, simply use a script instead of a builtin target: @@ -827,10 +871,12 @@ If you want to modify the value, simply use a script instead of a builtin target ``` {"watch": "s1@x", "target": "get_scene('s2').set('x', value/2);"}, ``` + If you need to modify something other than group or scene: ``` {"watch": "s1@x", "target": "update_element('timer', 'loop', (x<0) ? false : true);"}, ``` + This will pause the timer `timer` whenever the x coordinate of `s1` is greater than 0, and resume the timer otherwise. @@ -840,6 +886,7 @@ As indicated in the scripting section, you can also add watcher redirecting to m {"id": "mod", "js": "mymod.js"}, {"watch": "s1@x", "target": "mod.on_x"}, ``` + And in `mymod.js`: ``` diff --git a/docs/Howtos/custom-boxes.md b/docs/Howtos/custom-boxes.md index 425b1b78..4ca674dd 100644 --- a/docs/Howtos/custom-boxes.md +++ b/docs/Howtos/custom-boxes.md @@ -1,4 +1,30 @@ -# Overview +--- +tags: +- mpd +- pid +- data +- codec +- multiplexer +- stream +- encode +- xml +- media +- isobmff +- box +- track +- option +- mp4 +- source +- chain +- input +- isomedia +- dash +- encoder +--- + + + +# Overview {:data-level="all"} We discuss here how to customize ISOBMFF files using box patches. Please first check the XML [Box Patch](BoxPatch) syntax before reading. @@ -32,11 +58,13 @@ This patch describes insertion of a box after a track header box, with a 4CC val ``` MP4Box -patch box.xml source.mp4 ``` + This will inject the new box after the track header of the first track in the file. ``` MP4Box -patch 4=box.xml source.mp4 ``` + This will inject the new box after the track header of the track with ID 4. @@ -57,16 +85,18 @@ This patch describes removal of a box with a 4CC value `GPAC`located in the `tra ``` MP4Box -patch box.xml source.mp4 ``` + This will remove the new box if present in the track header of the first track in the file. ``` MP4Box -patch 4=box.xml source.mp4 ``` + This will remove the new box if present in the track header of the track with ID 4. -# Injecting a box patch in your workflow +# Injecting a box patch in your workflow {: data-level="beginner"} You may also want to customize your ISOBMFF files while they are being produced in a filter chain. diff --git a/docs/Howtos/dash/Check-key-frame-alignment-with-MP4Box.md b/docs/Howtos/dash/Check-key-frame-alignment-with-MP4Box.md index 6a14b109..ea8e3ec5 100644 --- a/docs/Howtos/dash/Check-key-frame-alignment-with-MP4Box.md +++ b/docs/Howtos/dash/Check-key-frame-alignment-with-MP4Box.md @@ -1,3 +1,27 @@ +--- +tags: +- mp4 +- encrypt +- source +- sample +- media +- isomedia +- ffmpeg +- data +- encode +- isobmff +- xml +- codec +- mpeg +- stream +- frame +- bitrate +- dash +- encoder +--- + + + When packaging encoded content for DASH, a lot of issues come from misalignment of key-frames across the different encoded qualities. This page describes how to check key-frame alignment. **A packager like MP4Box doesn't re-encode your content** diff --git a/docs/Howtos/dash/DASH-Sequences.md b/docs/Howtos/dash/DASH-Sequences.md index 3deec9f4..b9d030cb 100644 --- a/docs/Howtos/dash/DASH-Sequences.md +++ b/docs/Howtos/dash/DASH-Sequences.md @@ -1,3 +1,40 @@ +--- +tags: +- mpd +- ffmpeg +- data +- codec +- multiplexer +- sample +- compression +- frame +- raw +- stream +- encode +- bitstream +- sequence +- block +- media +- segment +- isobmff +- group +- h264 +- chunk +- track +- profile +- mp4 +- source +- input +- isomedia +- binary +- decoding +- mpeg +- dash +- encoder +--- + + + Telecom Paris has been generating a set of DASH sequences, and is making them available for DASH conformance testing. These sequences are distributed under the terms of the [Creative Common by-nc-nd Licence](http://creativecommons.org/licenses/by-nc-nd/3.0). diff --git a/docs/Howtos/dash/DASH-Support-in-MP4Box.md b/docs/Howtos/dash/DASH-Support-in-MP4Box.md index d46db8ed..23331594 100644 --- a/docs/Howtos/dash/DASH-Support-in-MP4Box.md +++ b/docs/Howtos/dash/DASH-Support-in-MP4Box.md @@ -1,6 +1,42 @@ -MP4Box can be used to generate content compliant to the MPEG-DASH specification, aka ISO/IEC 23009-1 available in [ISO Publicly Available Standards](http://standards.iso.org/ittf/PubliclyAvailableStandards/). - -For more details on what is DASH and HTTP streaming, please refer to [[this post|Fragmentation, segmentation, splitting and interleaving]]. For more help, type [MP4Box -h dash](mp4box-dash-opts) +--- +tags: +- mpd +- data +- codec +- buffer +- sample +- session +- stream +- xml +- bitstream +- bitrate +- dump +- block +- media +- segment +- group +- box +- rebuffer +- chunk +- track +- option +- profile +- mp4 +- source +- chain +- input +- binary +- output +- mpeg +- sink +- dash +--- + + + +_MP4Box can be used to generate content compliant to the MPEG-DASH specification, aka ISO/IEC 23009-1 available in [ISO Publicly Available Standards](http://standards.iso.org/ittf/PubliclyAvailableStandards/)._ +!!! note + For more details on what is DASH and HTTP streaming, please refer to [[this post|Fragmentation, segmentation, splitting and interleaving]]. For more help, type [MP4Box -h dash](mp4box-dash-opts) **`-dash Duration`** : enables DASH segmentation of input files with the given segment duration. For onDemand profile, where each media presentation is a single segment, this option sets the duration of a subsegment. diff --git a/docs/Howtos/dash/DASH-basics.md b/docs/Howtos/dash/DASH-basics.md index 38a62b1b..51abcb6e 100644 --- a/docs/Howtos/dash/DASH-basics.md +++ b/docs/Howtos/dash/DASH-basics.md @@ -1,3 +1,35 @@ +--- +tags: +- mpd +- data +- sample +- session +- pipeline +- frame +- stream +- xml +- bitstream +- sequence +- block +- media +- segment +- isobmff +- box +- track +- chunk +- option +- profile +- mp4 +- chain +- isomedia +- binary +- decoding +- mpeg +- dash +--- + + + ## DASH Basics: MPD and Segments Let's quickly summarize how a DASH content is made of: diff --git a/docs/Howtos/dash/DASH-intro.md b/docs/Howtos/dash/DASH-intro.md index e3128179..f98ea838 100644 --- a/docs/Howtos/dash/DASH-intro.md +++ b/docs/Howtos/dash/DASH-intro.md @@ -1,4 +1,17 @@ -## Foreword +--- +tags: +- option +- session +- media +- mpeg +- filter +- dash +- latency +--- + + + + GPAC has extended support for MPEG-DASH and HLS content generation and playback. diff --git a/docs/Howtos/dash/Fragmentation,-segmentation,-splitting-and-interleaving.md b/docs/Howtos/dash/Fragmentation,-segmentation,-splitting-and-interleaving.md index bf37bf6f..4ca26c15 100644 --- a/docs/Howtos/dash/Fragmentation,-segmentation,-splitting-and-interleaving.md +++ b/docs/Howtos/dash/Fragmentation,-segmentation,-splitting-and-interleaving.md @@ -1,4 +1,23 @@ -With [our work](https://biblio.telecom-paristech.fr/cgi-bin/download.cgi?id=11076) on [Dynamic Adaptive Streaming over HTTP (DASH)](https://www.slideshare.net/christian.timmerer/http-streaming-of-mpeg-media), in the current version of GPAC (revision 2642 on SVN), we now have many options for interleaving, fragmenting and segmenting ... which may be confusing. +--- +tags: +- mp4 +- mpd +- block +- media +- isomedia +- segment +- isobmff +- data +- stream +- xml +- mpeg +- dash +- chunk +--- + + + +_With [our work](https://biblio.telecom-paristech.fr/cgi-bin/download.cgi?id=11076) on [Dynamic Adaptive Streaming over HTTP (DASH)](https://www.slideshare.net/christian.timmerer/http-streaming-of-mpeg-media), in the current version of GPAC (revision 2642 on SVN), we now have many options for interleaving, fragmenting and segmenting ... which may be confusing._ It is time to clarify their usage in MP4Box. Some related aspects using MPEG-2 TS instead of MP4 can be seen in this [previous post](http://concolato.wp.imt.fr/2011/01/10/gpac-and-digital-radio-services/). diff --git a/docs/Howtos/dash/HAS-advanced.md b/docs/Howtos/dash/HAS-advanced.md index 50f27720..5f675001 100644 --- a/docs/Howtos/dash/HAS-advanced.md +++ b/docs/Howtos/dash/HAS-advanced.md @@ -1,3 +1,44 @@ +--- +tags: +- mpd +- pid +- reframer +- data +- filter +- pipe +- sample +- session +- manifest +- pipeline +- frame +- stream +- xml +- bitstream +- sequence +- dump +- block +- link +- media +- cue +- segment +- isobmff +- property +- chunk +- track +- option +- profile +- mp4 +- source +- chain +- input +- isomedia +- output +- sink +- dash +--- + + + # Foreword In this howto, we will study complex use cases for DASH and HLS (and sometimes SmoothStreaming) powered by GPAC. diff --git a/docs/Howtos/dash/HEVC-Tile-based-adaptation-guide.md b/docs/Howtos/dash/HEVC-Tile-based-adaptation-guide.md index 7b6a6fe1..1d31ea06 100644 --- a/docs/Howtos/dash/HEVC-Tile-based-adaptation-guide.md +++ b/docs/Howtos/dash/HEVC-Tile-based-adaptation-guide.md @@ -1,3 +1,50 @@ +--- +tags: +- mpd +- pid +- ffmpeg +- data +- tile +- codec +- filter +- pipe +- encrypt +- sample +- session +- pipeline +- compression +- frame +- raw +- stream +- encode +- hevc +- bitstream +- bitrate +- dump +- media +- compositor +- isobmff +- decoder +- track +- option +- profile +- mp4 +- graph +- source +- chain +- input +- isomedia +- binary +- output +- decoding +- mpeg +- sink +- dash +- encoder +--- + + + GPAC supports HEVC tile-based adaptation in DASH. This page gives a quick walk-through on how to build and play such sequences. # Content Preparation diff --git a/docs/Howtos/dash/HEVC-Tile-multi-resolution-adaptation-guide.md b/docs/Howtos/dash/HEVC-Tile-multi-resolution-adaptation-guide.md index 5ad08dea..898a6909 100644 --- a/docs/Howtos/dash/HEVC-Tile-multi-resolution-adaptation-guide.md +++ b/docs/Howtos/dash/HEVC-Tile-multi-resolution-adaptation-guide.md @@ -1,3 +1,33 @@ +--- +tags: +- mpd +- pid +- tile +- codec +- filter +- compression +- stream +- raw +- hevc +- bitstream +- compositor +- isobmff +- track +- option +- profile +- mp4 +- source +- input +- isomedia +- binary +- output +- decoding +- mpeg +- dash +--- + + + This page gives a quick walk-through on how to build and play tiled HEVC sequences with multiple resolutions diff --git a/docs/Howtos/dash/LL-DASH.md b/docs/Howtos/dash/LL-DASH.md index e2e5b0c0..64b31bfb 100644 --- a/docs/Howtos/dash/LL-DASH.md +++ b/docs/Howtos/dash/LL-DASH.md @@ -1,3 +1,43 @@ +--- +tags: +- mpd +- reframer +- data +- codec +- filter +- multiplexer +- encrypt +- session +- manifest +- compression +- frame +- raw +- xml +- stream +- encode +- dump +- block +- link +- media +- segment +- property +- h264 +- chunk +- latency +- option +- profile +- graph +- source +- packets +- input +- output +- sink +- dash +- encoder +--- + + + # Foreword Please make sure you are familiar with [DASH terminology](DASH-basics) before reading. @@ -79,6 +119,7 @@ You can now do a live (dynamic) DASH session: ``` MP4Box -dash-live 10000 -subdur 10000 -frag 1000 -profile live -out DST_URL source1 ... source2 ``` + This will generate a live session, dashing 10s (`-subdur`) of content into 10s (`-dash-live`) segments, each containing 10 fragments of 1s (`-frag`). If your sources are live, you don't need to specify the `-subdur`option since real-time regulation of source is not needed. or @@ -86,6 +127,7 @@ or ``` gpac -i source1 -i source2 -o DST_URL:segdur=10:cdur=1:profile=live:dmode=dynamic:sreg ``` + This will generate a live session, dashing content into 10s (`segdur`) segments, each containing 10 fragments of 1s (`cdur`), performing real-time regulation after each segment generation (`sreg`). If your sources are live, you don't need to specify the `sreg`option since real-time regulation of source is not needed. @@ -95,6 +137,7 @@ The above commands do not perform fragment regulation, which means that the cont MP4Box -frag-rt -dash-live 10000 -frag 1000 -profile live -out res/live.mpd source1 source2 gpac -i source1 -i source2 reframer:rt=on -o res/live.mpd:segdur=10:cdur=1:profile=live:dmode=dynamic ``` + The `-frag-rt` simply injects a [reframer](reframer) in the filter graph performing real-time regulation on media frames. This will ensure that both segments and fragments are written to disk in real-time. @@ -110,6 +153,7 @@ You now have low-latency producing of your DASH session, however in terms of DAS MP4Box -ast-offset 9000 -dash-live 10000 -frag 1000 -profile live -out res/live.mpd udp://IP:PORT gpac -i udp://IP:PORT -o res/live.mpd:segdur=10:cdur=1:profile=live:dmode=dynamic:asto=9 ``` + In the above example, we indicate the requests can be issued 9s (`asto` or `-ast-offset`) before the segment is fully produced. Your typical setup should have `cdur + asto = segdur`. If `asto` is greater than `segdur + cdur`, this will results in 404; if is is less, this will increase the client delay to the live edge. diff --git a/docs/Howtos/dash/LL-HLS.md b/docs/Howtos/dash/LL-HLS.md index 519662f8..56eee812 100644 --- a/docs/Howtos/dash/LL-HLS.md +++ b/docs/Howtos/dash/LL-HLS.md @@ -1,3 +1,26 @@ +--- +tags: +- option +- mp4 +- profile +- mpd +- block +- session +- media +- reframer +- isomedia +- segment +- data +- isobmff +- stream +- bitrate +- dash +- chunk +- latency +--- + + + # Foreword Please make sure you have read [DASH Low Latency](LL-DASH) and [HLS Generation](hls) before reading this. @@ -24,12 +47,14 @@ In file mode, each part file is the full segment name appended with `.N`, with ` MP4Box -frag-rt -dash-live 10000 -frag 1000 -profile live -out res/live.m3u8:llhls=br source1 source2 gpac -i source1 -i source2 reframer:rt=on -o res/live.m3u8:segdur=10:cdur=1:profile=live:dmode=dynamic:llhls=br ``` + In the above example, we indicate the LLHLS parts are byte-ranges in the segment being produced. ``` MP4Box -frag-rt -dash-live 10000 -frag 1000 -profile live -out res/live.m3u8:llhls=sf source1 source2 gpac -i source1 -i source2 reframer:rt=on -o res/live.m3u8:segdur=10:cdur=1:profile=live:dmode=dynamic:llhls=sf ``` + In the above example, we indicate the LLHLS parts are independent files. diff --git a/docs/Howtos/dash/MPEG-DASH-SRD-and-HEVC-tiling-for-VR-videos.md b/docs/Howtos/dash/MPEG-DASH-SRD-and-HEVC-tiling-for-VR-videos.md index 2484ad01..9a616d9b 100644 --- a/docs/Howtos/dash/MPEG-DASH-SRD-and-HEVC-tiling-for-VR-videos.md +++ b/docs/Howtos/dash/MPEG-DASH-SRD-and-HEVC-tiling-for-VR-videos.md @@ -1,3 +1,25 @@ +--- +tags: +- mp4 +- mpd +- source +- session +- input +- isomedia +- compression +- isobmff +- binary +- tile +- codec +- mpeg +- frame +- bitstream +- hevc +- dash +--- + + + We were at [MMSys 2016](https://mmsys2016.itec.aau.at/) talking about new nice features in GPAC: support for MPEG-DASH Spatial Relation Description and HEVC motion-constrained tiling! We had a [quick poster](https://gpac.io/files/2016/05/ACM-MMSys16-Poster-v1.pdf) presenting our two demos diff --git a/docs/Howtos/dash/Support-for-Apple-fMP4-adaptive-streaming-format.md b/docs/Howtos/dash/Support-for-Apple-fMP4-adaptive-streaming-format.md index 2b45c1d0..41b93d4d 100644 --- a/docs/Howtos/dash/Support-for-Apple-fMP4-adaptive-streaming-format.md +++ b/docs/Howtos/dash/Support-for-Apple-fMP4-adaptive-streaming-format.md @@ -1,3 +1,24 @@ +--- +tags: +- profile +- mp4 +- mpd +- source +- block +- input +- manifest +- media +- sequence +- segment +- stream +- bitstream +- dash +- chunk +- track +--- + + + Apple has announced during WWDC2016 the support for fragmented MP4 files in HLS: [https://developer.apple.com/videos/play/wwdc2016/504/](https://developer.apple.com/videos/play/wwdc2016/504/) diff --git a/docs/Howtos/dash/Tiled-Streaming.md b/docs/Howtos/dash/Tiled-Streaming.md index 212be001..931754fa 100644 --- a/docs/Howtos/dash/Tiled-Streaming.md +++ b/docs/Howtos/dash/Tiled-Streaming.md @@ -1,3 +1,38 @@ +--- +tags: +- mpd +- tile +- codec +- filter +- sample +- compression +- frame +- raw +- stream +- hevc +- bitrate +- dump +- scene +- compositor +- isobmff +- decoder +- track +- option +- profile +- mp4 +- graph +- source +- input +- isomedia +- output +- mpeg +- sink +- dash +- encoder +--- + + + GPAC supports streaming HEVC tiled DASH videos. In this page, you will find some helpful information to get started with this feature. In the following, we assume the input video has resolution of 3840x2160 and a frame rate of 30 frames/sec. # How to generate tiled streamable video content diff --git a/docs/Howtos/dash/cmaf.md b/docs/Howtos/dash/cmaf.md index a6adb670..70b67001 100644 --- a/docs/Howtos/dash/cmaf.md +++ b/docs/Howtos/dash/cmaf.md @@ -1,3 +1,31 @@ +--- +tags: +- mpd +- data +- codec +- isma +- encrypt +- sample +- manifest +- compression +- stream +- xml +- media +- isobmff +- box +- h264 +- track +- option +- profile +- mp4 +- source +- input +- isomedia +- dash +--- + + + # CMAF Generation GPAC can be used to generate DASH or HLS following the CMAF specification. diff --git a/docs/Howtos/dash/dash_low_latency.md b/docs/Howtos/dash/dash_low_latency.md index b50f3a76..d36f07f4 100644 --- a/docs/Howtos/dash/dash_low_latency.md +++ b/docs/Howtos/dash/dash_low_latency.md @@ -1 +1,8 @@ +--- +tags: +- dash +--- + + + This page was moved [here](ll-dash). \ No newline at end of file diff --git a/docs/Howtos/dash/dash_transcoding.md b/docs/Howtos/dash/dash_transcoding.md index 3cfa61a9..dbc84f1b 100644 --- a/docs/Howtos/dash/dash_transcoding.md +++ b/docs/Howtos/dash/dash_transcoding.md @@ -1,3 +1,36 @@ +--- +tags: +- mpd +- transcode +- pid +- reframer +- codec +- filter +- connection +- sample +- session +- compression +- frame +- encode +- block +- link +- media +- segment +- isobmff +- h264 +- chunk +- mp4 +- source +- chain +- input +- isomedia +- output +- dash +- encoder +--- + + + # Foreword In this howto, we will study various setups for DASH transcoding. diff --git a/docs/Howtos/dash/hls.md b/docs/Howtos/dash/hls.md index f7b0312f..33ba5b44 100644 --- a/docs/Howtos/dash/hls.md +++ b/docs/Howtos/dash/hls.md @@ -1,3 +1,34 @@ +--- +tags: +- mpd +- pid +- data +- codec +- sample +- manifest +- frame +- stream +- bitstream +- bitrate +- sequence +- block +- media +- segment +- isobmff +- property +- group +- track +- chunk +- option +- profile +- mp4 +- input +- mpeg +- dash +--- + + + # HLS Generation GPAC can be used to generate HLS rather than MPEG-DASH manifest formats, and can also be used to generate the two manifests in one pass. diff --git a/docs/Howtos/dynamic_rc.md b/docs/Howtos/dynamic_rc.md index 30230939..be631e32 100644 --- a/docs/Howtos/dynamic_rc.md +++ b/docs/Howtos/dynamic_rc.md @@ -1,4 +1,36 @@ -# Overview +--- +tags: +- pid +- ffmpeg +- data +- codec +- filter +- encrypt +- session +- pipeline +- compression +- encode +- dump +- media +- isobmff +- libgpac +- h264 +- option +- mp4 +- source +- packets +- chain +- input +- isomedia +- output +- sink +- rtcp +- encoder +--- + + + +# Overview {: data-level="all"} We discuss here how to implement dynamic rate control using [GPAC Filters](Filters). Examples are in Python but API is also available for [JSF](jsfilter) and [NodeJS](nodejs). diff --git a/docs/Howtos/encoding.md b/docs/Howtos/encoding.md index e533a029..f47ac4b0 100644 --- a/docs/Howtos/encoding.md +++ b/docs/Howtos/encoding.md @@ -1,4 +1,43 @@ -# Overview +--- +tags: +- transcode +- pid +- ffmpeg +- data +- codec +- filter +- connection +- encrypt +- session +- pipeline +- compression +- stream +- raw +- encode +- hevc +- scene +- link +- media +- signal +- isobmff +- decoder +- h264 +- track +- option +- profile +- mp4 +- graph +- source +- chain +- input +- isomedia +- mpeg +- encoder +--- + + + +# Overview {: data-level="all" } We discuss here how to use encoders in GPAC. @@ -6,7 +45,7 @@ GPAC filter graph resolution always targets the shortest possible path between t For example, if the source is an AAC file and the destination is an ISOBMFF file, since ISOBMFF accepts AAC data inputs, no encoder will be used. But if the source is an AAC file and the destination is an MP3 file, the graph resolver will load a decoder and an MP3 encoder to move source data from AAC to MP3. -# Encoding Video +# Encoding Video {: data-level="beginner" } ## Encoding from a raw video file @@ -99,7 +138,7 @@ You can use the [ffsws](ffsws) filter to rescale videos in your pipeline: This will resize (downscale or upscale) input to a resolution of 1280x720 without checking aspect ratio, and encode to AVC at 1 mbps. To keep aspect ratio, use `ffsws:osize=1280x720:keepar=full`. -# Encoding Audio +# Encoding Audio {: data-level="beginner" } ## Encoding from files This is basically the same as video @@ -120,7 +159,7 @@ You can use the [audio resampler](resample) filter to change your input signal c This will resample the input signal to stereo 48000 Hz and encode to AAC at 128k. -# Transcoding AV file +# Transcoding AV file {: data-level="beginner" } Combine the above tow steps: diff --git a/docs/Howtos/encryption/Encryption-Introduction.md b/docs/Howtos/encryption/Encryption-Introduction.md index 8aaa8225..98e52d30 100644 --- a/docs/Howtos/encryption/Encryption-Introduction.md +++ b/docs/Howtos/encryption/Encryption-Introduction.md @@ -1,3 +1,19 @@ +--- +tags: +- isma +- encrypt +- sample +- media +- data +- stream +- xml +- bitstream +- sequence +- track +--- + + + GPAC can be used to encrypt or decrypt media streams in a more or less format-agnostic manner, according to the Common Encryption, ISMA E&A and OMA DRM 2.0 specifications. An XML language is used by GPAC to get/set the encryption parameters. GPAC supports the ISMA E&A specification, better known as ISMACryp. This specification provides reliable transmission of encrypted media data with key signaling and cryptographic re-synchronization in case of packet loss or random access. diff --git a/docs/Howtos/encryption/encryption-clearkey.md b/docs/Howtos/encryption/encryption-clearkey.md index 842effff..8a2d649f 100644 --- a/docs/Howtos/encryption/encryption-clearkey.md +++ b/docs/Howtos/encryption/encryption-clearkey.md @@ -1,4 +1,25 @@ -# Overview +--- +tags: +- option +- mp4 +- encrypt +- mpd +- source +- pid +- input +- media +- manifest +- isomedia +- data +- isobmff +- xml +- property +- dash +--- + + + +# Overview {:data-level="all"} We discuss here how to use ClearKey encryption in GPAC. @@ -10,11 +31,11 @@ For more info, check https://github.com/Dash-Industry-Forum/ClearKey-Content-Pro Fetching of keys through ClearKey is supported in GPAC decryptor and does not need to be configured. -# DRM config file +# DRM config file {:data-level="beginner"} ClearKey can be used with any scheme types defined in CENC, and does not need any specific info (e.g. PSSH). -# Using MP4Box +# Using MP4Box {:data-level="beginner"} You first need to encrypt your source: @@ -35,7 +56,7 @@ If each source has its own licence URL: ``` -# Using gpac for single-pass encrypt and dash +# Using gpac for single-pass encrypt and dash If all streams share the same ClearKey licence server URL, specify `ckurl` option of dasher: diff --git a/docs/Howtos/encryption/encryption-filters.md b/docs/Howtos/encryption/encryption-filters.md index 146e7dce..e4d54b38 100644 --- a/docs/Howtos/encryption/encryption-filters.md +++ b/docs/Howtos/encryption/encryption-filters.md @@ -1,4 +1,35 @@ -# Overview +--- +tags: +- mpd +- pid +- data +- filter +- connection +- isma +- encrypt +- session +- pipeline +- stream +- xml +- dump +- link +- isobmff +- property +- track +- profile +- mp4 +- graph +- source +- chain +- input +- isomedia +- output +- sink +--- + + + +# Overview {:data-level="all"} We discuss here how to use encryption in a filter chain in GPAC. @@ -65,6 +96,7 @@ Another possibility is to define the `CryptInfo` PID property rather than using ``` gpac -i udp://localhost:1234/:#CrypTrack=(audio)drm_audio.xml,(video)drm_video.xml cecrypt -o dest.mpd:profile=live:dmode=dynamic ``` + This example assigns: - a `CryptInfo` property to `drm_audio.xml` for PIDs of type audio diff --git a/docs/Howtos/filters-oneliners.md b/docs/Howtos/filters-oneliners.md index 958e9d4a..35840457 100644 --- a/docs/Howtos/filters-oneliners.md +++ b/docs/Howtos/filters-oneliners.md @@ -1,4 +1,69 @@ -# Foreword +--- +tags: +- mpd +- transcode +- pid +- reframer +- ffmpeg +- data +- overlay +- codec +- filter +- pipe +- multiplexer +- encrypt +- sample +- session +- manifest +- pipeline +- remux +- compression +- frame +- raw +- xml +- stream +- encode +- bitstream +- avmix +- sequence +- dump +- scene +- block +- media +- segment +- compositor +- isobmff +- property +- h264 +- chunk +- latency +- option +- profile +- track +- mp4 +- source +- graph +- packets +- chain +- input +- isomedia +- output +- decoding +- mpeg +- sink +- dash +- encoder +--- + + + + + + + + +# Foreword + This page contains one-liners illustrating the many possibilities of GPAC filters architecture. For a more detailed information, it is highly recommended that you read: @@ -13,7 +78,7 @@ To get a better understanding of each command illustrated in this case, it is re Whenever an option is specified, e.g. `dest.mp4:foo`, you can get more info and locate the parent filter of this option using `gpac -h foo`. The filter session is by default quiet, except for warnings and error reporting. To get information on the session while running, use [-r](gpac_general#r) option. To get more runtime information, use the [log system](core_logs). - +sectionLevel === null || Given the configurable nature of the filter architecture, most examples given in one context can be reused in another context. For example: - from the dump examples: @@ -45,7 +110,7 @@ GPAC filters can use either: _NOTE This page is under permanent construction, feel free to contribute !_ -# Source Inspection +# Source Inspection {: data-level="beginner" } Check if a source is supported and get quick information on the media streams - _see [filter](inspect), [howto](inspecting)_ ``` @@ -95,7 +160,7 @@ Count all AC3 audio streams in a source - _see [filter](probe), [doc](filters_g res = `gpac -i source @#CodecID=ac3 probe` ``` -# Dumping and decoding +# Dumping and decoding Extract AVC track, potentially transcoding - _see [filter](writegen)_ ``` @@ -147,7 +212,7 @@ Extract all AAC audio tracks - _see [doc](filters_general#complex-links)_ gpac -i source reframer @#CodecID=aac -o dump_$ID$:dynext ``` -# Multiplexing +# Multiplexing {: data-level="beginner" } Mux sources to MP4 - _see [filter](mp4mx)_ ``` @@ -192,7 +257,7 @@ Mux sources to MKV (for builds with FFmpeg support) - _see [filter](ffmx)_ gpac -i source -o dst.mkv ``` -# Remultiplexing +# Remultiplexing {: data-level="beginner" } Remux sources to MP4 forcing bitstream reparsing (all syntaxes are equivalent) ``` @@ -201,7 +266,7 @@ MP4Box -add source:unframer -new dst.mp4 ``` -# Encoding +# Encoding {: data-level="beginner" } Encode an MP3 to an AAC file at 100 kbps - _see [filter](ffenc)_ ``` @@ -258,7 +323,7 @@ gpac -i source enc:c=avc:b=3m:pass2 -o dst.mp4 ``` -# Rescaling +# Rescaling rescale without respecting aspect ratio ``` @@ -276,7 +341,7 @@ gpac -i source1.mp4 ffsws:osize=510x512:osr=3/2 vout ``` -# Encryption +# Encryption Encrypt and dash several sources using a single drm configuration - _see [filter](cecrypt)_ ``` @@ -294,7 +359,7 @@ gpac -i source.mp4 dasher:gencues cecrypt:cfile=roll_seg.xml -o live.mpd ``` -# Piping and sockets +# Piping and sockets Grab a compressed stream (e.g. AVC|H264) from stdin, remove all non I-frames and non-video PIDs and output as raw 264 over stdout - _see [filter](fout) [howto](pipes)_ ``` @@ -402,7 +467,7 @@ gpac -i source::#HLSMExt=vfoo,vbar=video::#HLSVExt=#fooVideo,#bar1=optVideo -i s ``` -# Time modification +# Time modification _Note: If the source is an MP4 file, it is much simpler/faster to perform these operations using MP4Box_ @@ -427,7 +492,7 @@ gpac -i source restamp:fps=30000/1001:rawv=force -o dst ``` -# Source splitting +# Source splitting {: data-level="beginner" } Extract from 1min to 2min30s - _see [filter](restamp)_ ``` @@ -457,7 +522,7 @@ gpac -i source reframer:xs=T00:01:00,T00:05:20:xe=T00:02:30 -o dst ``` -# Playlists and source concatenation +# Playlists and source concatenation {: data-level="beginner" } Loop file forever playback - _see [filter](flist)_ ``` @@ -483,7 +548,7 @@ ls *.mp4 > pl.m3u gpac -i pl.m3u vout ``` -# Playback +# Playback { : data-level="beginner" } Basic playback - _see [howto](filters-playback)_ ``` @@ -554,7 +619,7 @@ Decode source MP4 enabling only the minimum filters: gpac -blacklist=-fin,mp4dmx,ffdec,vout source.mp4 vout ``` -# FFmpeg support +# FFmpeg support Set gpac as RTMP output server ``` @@ -771,5 +836,4 @@ Fractal-like animated video reuse ] } ] -``` - +``` \ No newline at end of file diff --git a/docs/Howtos/gpac-mp4box.md b/docs/Howtos/gpac-mp4box.md index 69173f31..95231340 100644 --- a/docs/Howtos/gpac-mp4box.md +++ b/docs/Howtos/gpac-mp4box.md @@ -1,4 +1,43 @@ -# MP4Box vs gpac +--- +tags: +- heif +- reframer +- data +- codec +- filter +- pipe +- encrypt +- session +- pipeline +- compression +- connections +- frame +- raw +- xml +- stream +- encode +- dump +- media +- compositor +- isobmff +- property +- h264 +- track +- option +- mp4 +- graph +- source +- chain +- input +- isomedia +- output +- sink +- dash +--- + + + +# MP4Box vs gpac {: data-level="all" } Following the introduction of the filter architecture and the gpac application, you may have a hard time choosing between MP4Box and gpac. @@ -95,11 +134,13 @@ In both cases, we still use temporary storage for the final file interleaving. S ``` MP4Box -add video.264:options -add audio_en.264:options -add audio_fr.264:options -frag 100 -crypt DRM.xml -new result.mp4 ``` + We got rid of the temporary storage due do file interleaving, but we still need an intermediate file to store the import result. ``` gpac -i video.264:options -i audio_en.264:options -i audio_fr.264:options cecrypt:cfile=DRM.xml -o result.mp4:frag:cdur=100 ``` + We use no longer use temporary storage. @@ -125,8 +166,10 @@ source_vid -> rescale -> encode1 \ -> encode2 -> dasher -> encode3 / ``` + This cannot be described using MP4Box, this must be converted into something like: ``` + source_vid -> rescale -> encode1 -> dasher source_vid -> rescale -> encode2 / source_vid -> rescale -> encode3 / diff --git a/docs/Howtos/heif/GPAC-support-for-HEIF.md b/docs/Howtos/heif/GPAC-support-for-HEIF.md index 306d308c..7478102e 100644 --- a/docs/Howtos/heif/GPAC-support-for-HEIF.md +++ b/docs/Howtos/heif/GPAC-support-for-HEIF.md @@ -1,4 +1,24 @@ -## Context +--- +tags: +- mp4 +- source +- heif +- compression +- data +- isobmff +- tile +- output +- codec +- mpeg +- stream +- frame +- hevc +- box +--- + + + +# Context {:data-level="all"} HEIF is a new image format defined within MPEG, by companies such as Apple, Nokia, Canon, ... and by the GPAC team and Telecom Paris ! diff --git a/docs/Howtos/heif/heif-extraction.md b/docs/Howtos/heif/heif-extraction.md index 7a8a3b84..2e087eaf 100644 --- a/docs/Howtos/heif/heif-extraction.md +++ b/docs/Howtos/heif/heif-extraction.md @@ -1,17 +1,45 @@ -# Overview +--- +tags: +- transcode +- pid +- heif +- data +- codec +- compression +- frame +- stream +- hevc +- dump +- media +- decoder +- box +- track +- option +- mp4 +- source +- input +- output +- mpeg +- encoder +--- + + + +# Overview {:data-level="all"} We discuss here how to extract items from HEIF file collections. For track extraction, use the regular tools from GPAC. A HEIF image collection will contain several items packed in a single `meta` box in ISOBMFF. These items will usually share the same coding type, although this is not a requirement. We only discuss here HEIF version 1 files, for which each item is an intra picture. We assume the image collection is made of HEVC items. -# Extracting images +# Extracting images {:data-level="beginner"} You can use MP4Box to manually extract each item, see [MP4Box -h meta](mp4box-meta-opts): ``` MP4Box -dump-item 1:path=dump.hvc source.heic ``` + This will dump item 2 into `dump.hvc`. This however requires the item ID, hence an inspection of the file prior to extracting the item. @@ -25,7 +53,7 @@ This will dump each item in `dump_$ItemID$.hvc`, with `$ItemID$` being replaced -# Transcoding as images +# Transcoding as images {:data-level="beginner"} Transcoding is not possible using MP4Box. Using gpac, it is a fairly simple process: @@ -37,7 +65,7 @@ This will transcode each item to JPEG in `dump_$ItemID$.jpg`, with `$ItemID$` b Each item will be declared as a media PID. This implies that there will be one decoder instance and one encoder instance created for each media PID. -# Transcoding as a sequence of images +# Transcoding as a sequence of images {:data-level="beginner"} One way to optimize the previous drawback of high resource usage is by declaring all items as a single track using [-itt](mp4dmx#itt) option of the MP4 demultiplexer: diff --git a/docs/Howtos/heif/heif-import.md b/docs/Howtos/heif/heif-import.md index 01a5f29b..2e3fc2a3 100644 --- a/docs/Howtos/heif/heif-import.md +++ b/docs/Howtos/heif/heif-import.md @@ -1,9 +1,30 @@ -# Overview +--- +tags: +- option +- mp4 +- source +- sample +- input +- heif +- media +- reframer +- isomedia +- data +- isobmff +- stream +- output +- frame +- track +--- + + + +# Overview {:data-level="all"} We discuss here how to import items to create HEIF file collections. For track import, use the regular tools from GPAC. -# Importing images +# Importing images {:data-level="beginner"} You can use MP4Box to manually import each item, see [MP4Box -h meta](mp4box-meta-opts). @@ -42,7 +63,7 @@ MP4Box -add-image src.hvc:primary:time=3-180/30 -new image.heic ``` -# Filtering while importing +# Filtering while importing {:data-level="beginner"} MP4Box can be used together with filters in gpac, as discussed [here](mp4box-filters). This section illustrates how this feature can be used in various use cases. ## Importing a subset of frames @@ -59,7 +80,7 @@ The following example imports a JPG image and transcodes it to HEVC at 5 mbps: MP4Box -add-image src.jpg:primary@@enc:c=avc:b=5m -new image.heic ``` -# Creating images in a file with video +# Creating images in a file with video {:data-level="beginner"} MP4Box can create images from a file with one or more video tracks and save the combined video+items. The syntax used is the same as the examples above except the source file is not set. @@ -82,6 +103,7 @@ You can change that by specifying that the item is a reference to the sample dat ``` MP4Box -add-image ref:time=-1/30 image.heic ``` + In this example, the first key frame of every 30s window of the source track will be added as an item sharing the data with the track sample. # Creating grids diff --git a/docs/Howtos/howtos.md b/docs/Howtos/howtos.md index ddcb6580..698c862e 100644 --- a/docs/Howtos/howtos.md +++ b/docs/Howtos/howtos.md @@ -1,3 +1,11 @@ +--- +tags: +- input +- media +--- + + + This part of the wiki describes HOWTOs illustrating the various possibilities of GPAC. Feel free to contribute your own cookbooks for media processing with GPAC ! diff --git a/docs/Howtos/inspecting.md b/docs/Howtos/inspecting.md index 6088c80d..17dadfb0 100644 --- a/docs/Howtos/inspecting.md +++ b/docs/Howtos/inspecting.md @@ -1,9 +1,44 @@ -# Overview +--- +tags: +- interleave +- pid +- reframer +- data +- codec +- filter +- packet +- frame +- raw +- xml +- stream +- encode +- bitstream +- dump +- media +- isobmff +- h264 +- option +- mp4 +- source +- packets +- chain +- input +- isomedia +- binary +- output +- mpeg +- sink +- encoder +--- + + + +# Overview {: data-level="all" } We discuss here how to use the [inspect](inspect) filter to get information on sources in GPAC. -# Media Streams inspection +# Media Streams inspection {: data-level="beginner" } ``` gpac -i source.mp4 inspect @@ -55,6 +90,7 @@ The start and duration of the inspection can be modified: ``` gpac -i source.mp4 inspect:deep:start=10:dur=1 ``` + This will force inspecting from start time 10 second (or previous access point) for 1 second. # Filtering the inspection @@ -76,6 +112,7 @@ The full list of options for the packet information log is given in the [inspect ``` gpac -i source.mp4 inspect:interleave=false:fmt="PCK%num% DTS=%dts% CTS=%cts% SAP=%sap% size=%size%%lf%":log=dump.txt ``` + This is the same as above with some nicer formatting of the output: ``` PCK1 DTS=0 CTS=0 SAP=1 size=200 @@ -111,4 +148,4 @@ Using the mode `analyse=bs` will give, for supported media types, the fields rea This is still a work in progress, more media types need to be added and deeper analysis of the packets should be done (for now only the slice headers are parsed). -This should however help you check consistency of systems layer information (timing, SAP, dependency information) with frame properties. +This should however help you check consistency of systems layer information (timing, SAP, dependency information) with frame properties. \ No newline at end of file diff --git a/docs/Howtos/jsf/evg.md b/docs/Howtos/jsf/evg.md index 481c1d09..f55accde 100644 --- a/docs/Howtos/jsf/evg.md +++ b/docs/Howtos/jsf/evg.md @@ -1,4 +1,33 @@ -# Overview +--- +tags: +- pid +- heif +- data +- overlay +- filter +- buffer +- sample +- packet +- frame +- raw +- stream +- dump +- scene +- media +- compositor +- rebuffer +- track +- source +- packets +- input +- output +- sink +- dash +--- + + + +# Overview {:data-level="all"} We discuss here how to use the [JavaScript Filter](jsf) to generate 2D vector graphics in GPAC. The [JS scripts](https://github.com/gpac/testsuite/tree/filters/media/jsf) in the gpac test suite are also a good source of examples. @@ -12,18 +41,18 @@ For a simpler and/or more customized support of 2D graphics, GPAC includes JavaS Please note that the EVG API is an immediate mode API and does not track objects drawn. If you want to partially redraw the surface, you will need to track changes and use clippers to redraw only changed areas. -# Setting up EVG +# Setting up EVG {:data-level="beginner"} You need to import the EVG JavaScript bindings in your script: ``` import * as evg from 'evg' ``` -# Setting up a canvas +# Setting up a canvas {:data-level="beginner"} In order to draw, a JS EVG filter requires a canvas, called surface in the API. This surface allows writing to a memory buffer in the desired pixel format, and can be setup in different ways. -# Creating a canvas +# Creating a canvas {:data-level="beginner"} The simplest way to create a canvas is to allocate your own memory and setup the canvas: @@ -101,6 +130,7 @@ let circle = new Path(); let circle.add_ellipse(0, 0, 100, 100); ``` + Then create a simple brush: ``` let brush = new SolidBrush(); @@ -108,7 +138,7 @@ brush.set_color('cyan'); ``` Then assign path to surface and draw path - ``` +``` canvas.path = circle; canvas.fill(brush); ``` @@ -116,6 +146,7 @@ canvas.fill(brush); If we put all this together: ``` + import * as evg from 'evg' let width=400; @@ -171,6 +202,7 @@ brush.set_stop(0.0, 'red'); brush.set_stopf(1.0, 0.0, 0.0, 1.0, 0.5); brush.mode = GF_GRADIENT_MODE_SPREAD; ``` + or a linear gradient: ``` @@ -195,6 +227,7 @@ mx.scale(2.0, 0.5); canvas.matrix = mx; canvas.path = circle; canvas.fill(brush); + ``` You can also use a 3D matrix to draw a path, usually to apply perspective transform. In this case, all points in the path are considered to have 0 as Z coordinate. @@ -215,6 +248,7 @@ You can also use a 3D matrix to draw a path, usually to apply perspective transf GPAC EVG handles path outlines ("striking") as a regular path. If you want to outline a path, you first need to create the corresponding outline path using pen properties, then draw it as usual. ``` + let outline = circle.outline({width: 5.0, align: GF_PATH_LINE_OUTSIDE, join: GF_LINE_JOIN_BEVEL, dash: GF_DASH_STYLE_DASH_DASH_DOT}); @@ -231,6 +265,7 @@ GPAC EVG handles text by converting a text string with a given font as a set of ``` /*create a text*/ + let text = new evg.Text(); text.font = 'Times'; text.fontsize = 20; @@ -270,6 +305,7 @@ let tx = new EVG.Texture(2, 2, 'rgba', ab); ``` let tx = new EVG.Texture('myimage.jpg', true); ``` + Note that the image loader can resolve the image path as relative to the source JS or to the current working directory. In this example, we use source JS relative path. Only local files are supported by this API. - create texture from a remote PNG or JPEG file @@ -279,6 +315,7 @@ Note that the image loader can resolve the image path as relative to the source xhr = xhr_fetch_file(file_url); let tx = new EVG.Texture(xhr.response); ``` + Check GPAC [XHR API](https://doxygen.gpac.io/group__xhr__grp.html) for more details. @@ -290,6 +327,7 @@ let pck = ipid.get_packet(); let tx = new EVG.Texture(pck); ``` + In this case, the texture properties are derived from the packet's parent PID properties. @@ -298,6 +336,7 @@ In this case, the texture properties are derived from the packet's parent PID pr ``` let tx = new EVG.Texture(canvas); ``` + In this case, the texture properties are derived from the canvas properties. This is typically used to draw an offscreen canvas and use the result as a texture, similar to MPEG-4 CompositeTexture2D. diff --git a/docs/Howtos/jsf/jsdash.md b/docs/Howtos/jsf/jsdash.md index b0a3c6f2..e9b35415 100644 --- a/docs/Howtos/jsf/jsdash.md +++ b/docs/Howtos/jsf/jsdash.md @@ -1,4 +1,20 @@ -# Overview +--- +tags: +- option +- mpd +- source +- session +- data +- stream +- tile +- filter +- group +- dash +--- + + + +# Overview {:data-level="all"} We discuss here how to implement your custom DASH rate adaptation logic in JS. diff --git a/docs/Howtos/jsf/jsfilter.md b/docs/Howtos/jsf/jsfilter.md index 04e2df5e..52c5adad 100644 --- a/docs/Howtos/jsf/jsfilter.md +++ b/docs/Howtos/jsf/jsfilter.md @@ -1,11 +1,45 @@ -# Overview +--- +tags: +- pid +- data +- codec +- filter +- buffer +- packet +- pipeline +- connections +- frame +- raw +- stream +- hevc +- bitstream +- sequence +- dump +- media +- property +- rebuffer +- track +- option +- mp4 +- graph +- source +- packets +- chain +- input +- output +- sink +--- + + + +# Overview {:data-level="all"} We discuss here how to use the [JavaScript Filter](jsf) to write JavaScript-based custom filters in GPAC. The [JS scripts](https://github.com/gpac/testsuite/tree/filters/media/jsf) in the gpac test suite are also a good source of examples. The JS filter provides JS bindings to the GPAC filter architecture. JavaScript support in GPAC is powered by QuickJS. Check the documentation of the [JS APIs](https://doxygen.gpac.io/group__jsf__grp.html) for more details. -# Principles +# Principles {:data-level="beginner"} In order to load, a JS filter requires a source JS, specified in the filter [js](jsf#js) option. A short-cut syntax is to directly specify the js script. In other words, the following syntaxes are equivalent: ``` @@ -48,7 +82,7 @@ If you need to pass JS data across filters, you will have to serialize to JSON y - send it as associated property on existing packets -# Declaring a filter (optional) +# Declaring a filter (optional) {:data-level="beginner"} The first thing to do when creating a filter is to setup a few things about your filter. @@ -62,6 +96,7 @@ Give a description to your filter (optional): ``` filter.set_desc("A demonstration JS filter"); ``` + This description should provide a quick hint as to what the purpose of the filter is. It will be shown by the command `gpac -h script.js`. @@ -75,6 +110,7 @@ You should finally set some help for your filter (optional): ``` filter.set_help("This filter provides a very simple javascript filter"); ``` + This will help other users understand what your filter does and how to use it. It will be shown by the command `gpac -h script.js`. You can specify arguments to your filter (optional): @@ -83,6 +119,7 @@ filter.set_arg({ name: "raw", desc: "if set, accept non-demultiplexed input PIDs ... filter.set_arg({name: "str", desc: "string to send", type: GF_PROP_STRING, def: "GPAC JS Filter Packet"} ); ``` + Arguments simplify script configuration and usage, and will be shown by the command `gpac -h script.js`. Defined arguments will be parsed from command line. Each defined argument results in a JS property in the `filter` object with the given value. @@ -136,6 +173,7 @@ __Discussion__ GPAC uses a concept of capabilities bundles for complex filters, allowing to describe characteristics of different classes of input or output PIDs. This is also possible using JS filters, by adding an empty cap to your filter: ``` + filter.set_cap({id: "StreamType", value: "Visual", inout: true}); filter.set_cap({id: "CodecID", value: "raw", inout: true} ); //video specific PID characteristics for input and output @@ -156,6 +194,7 @@ You can check your JS filter sources and sinks links by using `gpac -h links scr Once your capabilities are setup, you can get notifications of new inputs through the `filter.configure_pid` callback. This allows you to keep track of PID re-configurations, for later processing. ``` + ... filter.pids=[]; ... @@ -324,6 +363,7 @@ filter.opid.set_prop("StreamType", "Video"); filter.opid.set_prop("CodecID", "raw"); filter.opid.set_prop("PixelFormat", "rgb"); ``` + You can also assign user-defined properties to the PID as follows: ``` filter.opid.set_prop("MyTestProperty", "My Current State", true); @@ -479,6 +519,7 @@ When you're ready, it's time to send your packet: ``` dst_pck.send(); ``` + Once send, the packet cannot be resent: it is in a detached state and has no longer any underlying native packet. As a general rule, you should consider a packet send as no longer accessible. @@ -541,6 +582,7 @@ let src_f = filter.add_destination("myfile.ts"); let src_f = filter.add_destination("pipe://mymux.gsf"); ``` + Any URL supported by GPAC for destination/sink filter loading can be used. * load a generic filter: this allows loading any filter supported by GPAC @@ -548,6 +590,7 @@ Any URL supported by GPAC for destination/sink filter loading can be used. let vout_f = filter.add_filter("vout"); ``` + This will load the video output filter with no specific arguments. For each of these methods, the filter name or URL used can specify filter options, as usual within GPAC filter chains. For example: @@ -555,6 +598,7 @@ For each of these methods, the filter name or URL used can specify filter optio let vout_f = filter.add_filter("vout:vsync=no"); ``` + This will load the video output filter with vsync disabled. @@ -584,7 +628,7 @@ vout_f.set_source(filter, "MuxSrc=myPid"); ``` -# Including filters in your distribution +# Including filters in your distribution {:data-level=beginner"} JS files located in GPAC distribution or in the directories indicated using [-js-dirs](core_options#js-dirs) option can describe filters usable by the filter engine based on their name (file without extension or directory name). diff --git a/docs/Howtos/jsf/jshttp.md b/docs/Howtos/jsf/jshttp.md index 73c077cd..10e98235 100644 --- a/docs/Howtos/jsf/jshttp.md +++ b/docs/Howtos/jsf/jshttp.md @@ -1,11 +1,23 @@ -# Overview +--- +tags: +- option +- mp4 +- session +- media +- data +- filter +--- + + + +# Overview {:data-level="all"} We discuss here how to implement your custom HTTP server logic in JS. A custom logic can be defined using a standalone script, or by attaching a JS object to the httpout filter in a JS session. -# Standalone script +# Standalone script {: data-level ="beginner"} The standalone mode works by specifying a JS file to the httpin filter using its [-js](httpout#js) option: @@ -40,7 +52,7 @@ httpout.on_request = function (request) ``` -# Attaching from a JS session +# Attaching from a JS session {: data-level ="beginner"} The first step in your JS is to create an object implementing the callback previously indicated: diff --git a/docs/Howtos/jsf/jssession.md b/docs/Howtos/jsf/jssession.md index ce959589..0ac0bf7c 100644 --- a/docs/Howtos/jsf/jssession.md +++ b/docs/Howtos/jsf/jssession.md @@ -1,4 +1,32 @@ -# Overview +--- +tags: +- pid +- data +- filter +- multiplexer +- session +- pipeline +- connections +- dump +- media +- compositor +- isobmff +- property +- option +- mp4 +- graph +- source +- packets +- chain +- input +- isomedia +- output +- sink +--- + + + +# Overview {:data-level="all"} We discuss here how to use [gpac](gpac_general) or the [JavaScript Filter](jsf) to query and control from JavaScript the filter session in GPAC. The [JS scripts](https://github.com/gpac/testsuite/tree/filters/media/jsf) in the gpac test suite are also a good source of examples. @@ -314,6 +342,6 @@ my_filter.process = function() ``` -# Other tools +# Other tools {: data-level ="beginner"} Some GPAC core functions are made available through JS for prompt handling, bitstream parsing, file and directory IO, check [the documentation](https://doxygen.gpac.io/group__core__grp.html). diff --git a/docs/Howtos/jsf/webgl.md b/docs/Howtos/jsf/webgl.md index 725971e0..1b9ed9c8 100644 --- a/docs/Howtos/jsf/webgl.md +++ b/docs/Howtos/jsf/webgl.md @@ -1,4 +1,32 @@ -# Overview +--- +tags: +- pid +- webgl +- data +- filter +- buffer +- sample +- packet +- frame +- stream +- dump +- scene +- opengl +- media +- compositor +- property +- rebuffer +- track +- source +- packets +- input +- output +- sink +--- + + + +# Overview We discuss here how to use the [JavaScript Filter](jsf) to generate 3D vector graphics in GPAC. The [JS scripts](https://github.com/gpac/testsuite/tree/filters/media/jsf) in the GPAC test suite are also a good source of examples. @@ -150,6 +178,7 @@ A named texture is a texture created with a name: ``` let tx = gl.createTexture('myVidTex'); ``` + The texture data is then associated using upload(): ``` @@ -160,6 +189,7 @@ tx.upload(pck); //source data is only in system memory tx.upload(some_evg_texture); ``` + Regular bindTexture and texImage2D can also be used if you don't like changing your code too much: ``` let pck = input_pid.get_packet(); @@ -185,6 +215,7 @@ void main(void) { gl_FragColor = vid; } ``` + The resulting fragment shader may contain one or more sampler2D and a few additional uniforms, but they are managed for you by GPAC! The named texture is then used as usual: diff --git a/docs/Howtos/jsf/webgl_three.md b/docs/Howtos/jsf/webgl_three.md index 88a25204..7a326bfb 100644 --- a/docs/Howtos/jsf/webgl_three.md +++ b/docs/Howtos/jsf/webgl_three.md @@ -1,4 +1,31 @@ -# Foreword +--- +tags: +- pid +- heif +- webgl +- data +- filter +- sample +- packet +- connections +- frame +- raw +- dump +- scene +- opengl +- media +- property +- source +- packets +- input +- flush +- output +- sink +--- + + + +# Foreword {:data-level="all"} We discuss here how to use the [JavaScript Filter](jsf) WebGL along with Three.js in GPAC. @@ -68,6 +95,7 @@ console.info = function() { this.loglevel = 1; this._do_log.apply(this, argument console.debug = function() { this.loglevel = 0; this._do_log.apply(this, arguments); }; globalThis.console=console; ``` + Note that we need to export the console object to `globalThis` for Three.js to see it. @@ -146,6 +174,7 @@ filter.process = function() return GF_OK; } ``` + And that's it ! @@ -199,6 +228,7 @@ document.createElementNS = function(ns, tag) } globalThis.document=document; ``` + So far, what we did is create an EVG texture instead of an `img` DOM element, so that any call to `gl.texImage2D` made for that image is indeed passing an EVG texture. @@ -257,6 +287,7 @@ Three.js model loaders rely on XmlHttpRequest to fetch data. You will need to im import { XMLHttpRequest } from 'xhr' globalThis.XMLHttpRequest = XMLHttpRequest; ``` + Again, note that we need to export to `globalThis` for Three.js to see the object. diff --git a/docs/Howtos/mp4box-filters.md b/docs/Howtos/mp4box-filters.md index b9511047..10d97bf1 100644 --- a/docs/Howtos/mp4box-filters.md +++ b/docs/Howtos/mp4box-filters.md @@ -1,4 +1,45 @@ -# Overview +--- +tags: +- mpd +- pid +- reframer +- data +- codec +- filter +- multiplexer +- encrypt +- session +- pipeline +- compression +- stream +- encode +- xml +- dump +- link +- media +- isobmff +- property +- h264 +- track +- option +- profile +- mp4 +- graph +- source +- chain +- input +- isomedia +- output +- mpeg +- sink +- dash +- encoder +--- + + + + +# Overview {: data-level="all" } We discuss here how to use the [MP4Box](MP4Box-introduction) together with filters in GPAC. @@ -12,9 +53,9 @@ As discussed [here](Rearchitecture), the following features of MP4Box are now us At the time being, only media importing and DASHing operations can be extended to use other filters. -# Media Importing +# Media Importing -# Customizing source and mux parameters +# Customizing source and mux parameters {: data-level="beginner" } It is possible to provide additional parameters to both source and destination during an import operations. Most MP4Box parameters are mapped to the filter engine and they have roughly the same names, but the opposite is not true (i.e. most options of the various filters in GPAC are not mapped as MP4Box options). - source options are declared using `:sopt:` separator @@ -53,7 +94,7 @@ The filter statistics can be seen by using the `fstat` option: MP4Box -add source.aac:fstat -new file.mp4 ``` -# Filtering input streams +# 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. @@ -70,6 +111,7 @@ Thanks to the filter design and [link syntax](filters_general#complex-links), yo ``` 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: @@ -97,12 +139,14 @@ 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. @@ -111,6 +155,7 @@ 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 @@ -125,30 +170,34 @@ You may ask yourself whether using MP4Box or gpac is more efficient for such an - 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 +# 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. @@ -162,9 +211,11 @@ Note: sources to MP4Box for dashing are no longer restricted to MP4 files. The d ``` 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. diff --git a/docs/Howtos/mp4box-inplace.md b/docs/Howtos/mp4box-inplace.md index dea65ac0..11b7e2cd 100644 --- a/docs/Howtos/mp4box-inplace.md +++ b/docs/Howtos/mp4box-inplace.md @@ -1,4 +1,19 @@ -# Overview +--- +tags: +- option +- mp4 +- media +- isomedia +- isobmff +- data +- stream +- output +- box +--- + + + +# Overview {: data-level="all" } As of GPAC 2.0, MP4Box supports in-place editing of MP4 files. @@ -32,14 +47,14 @@ MP4Box -ab TEST -itags artist=GPAC movie.mp4 Tests for in-place storage are available [here](https://github.com/gpac/testsuite/blob/master/scripts/mp4box-inplace.sh). -# Flat storage files +# Flat storage files In files stored with flat storage (`-flat` in MP4Box), the media data is placed before the structured data (`moov` and `meta` box) and usually does not need any shifting. There is one exception to this: when adding brands, since they must be located first in the file, it is necessary to shift the media data. There is currently no way to reserve space for future brand edition in MP4Box, and any brand add operation will result in media data shift. We therefore recommend using interleaved storage (`moov`/ `meta` first). -# Interleaved files +# Interleaved files In files stored with interleaved storage (`-inter` in MP4Box), the media data is placed after the structured data (`moov` and `meta` box) and may need shifting whenever the size of {ftyp, moov, meta} boxes changes. In order to avoid shifting when this size decreases, a `free` box is inserted before the media data. When this size increases, the media data is shifted if writing the structured data will overwrite the start of the media data. Otherwise, a `free` box is written between the `moov+meta` boxes and the media data. @@ -57,6 +72,7 @@ You can use `-moovpad` option in your in-place edit operations, to force moving ``` MP4Box -ab GPAC movie.mp4 -moovpad 5000 ``` + This will perform in-place edit if the previously created file, but shift the media data to have 5000 bytes reserved for future edition; if more than 5000 free bytes are available, the media data is not shifted (i.e. `moovpad` is ignored in this case). diff --git a/docs/Howtos/network-capture.md b/docs/Howtos/network-capture.md index f8807fab..35d93eb1 100644 --- a/docs/Howtos/network-capture.md +++ b/docs/Howtos/network-capture.md @@ -1,8 +1,33 @@ -# Overview +--- +tags: +- mpd +- reframer +- data +- filter +- session +- packet +- dump +- media +- isobmff +- option +- mp4 +- source +- packets +- chain +- input +- isomedia +- output +- sink +- dash +--- + + + +# Overview {: data-level="all" } We discuss here how to use network captures with GPAC 2.3-DEV or above. -# Overview + GPAC can: diff --git a/docs/Howtos/nodejs.md b/docs/Howtos/nodejs.md index 5e69a92b..72c71acc 100644 --- a/docs/Howtos/nodejs.md +++ b/docs/Howtos/nodejs.md @@ -1,4 +1,48 @@ -# Overview +--- +tags: +- mpd +- pid +- reframer +- data +- tile +- codec +- filter +- connection +- pipe +- session +- packet +- pipeline +- remux +- stream +- bitstream +- sequence +- dump +- block +- link +- media +- segment +- isobmff +- property +- group +- libgpac +- chunk +- track +- option +- profile +- mp4 +- source +- packets +- chain +- input +- isomedia +- output +- sink +- dash +--- + + + +# Overview {: data-level="all" } We discuss here how to use [GPAC Filters](Filters) in NodeJS. @@ -11,7 +55,7 @@ You can also have a look at the [test script](https://github.com/gpac/gpac/tree __Warning GPAC NodeJS bindings are only available starting from GPAC 2.0.__ -# Before you begin +# Before you begin {: data-level="beginner" } The GPAC NodeJS bindings are using [n-api](https://nodejs.org/api/n-api.html) for interfacing with libgpac filter session, while providing an object-oriented wrapper hiding all GPAC C design. @@ -82,7 +126,7 @@ Running this should print your current GPAC version. A test program [gpac.js](https://github.com/gpac/gpac/blob/master/share/nodejs/test/gpac.js) exercising most of the NodeJS GPAC bindings is available in `gpac/share/nodejs/test` -# Tuning up GPAC +# Tuning up GPAC {: data-level="beginner" } The first thing to do is to initialize libgpac. This is done by default while importing the bindings with the following settings: @@ -95,6 +139,7 @@ If you want to change these, you need to re-init libgpac right after import: ``` gpac.init(1, "customprofile"); ``` + Any call other than `init` to GPAC will prevent any subsequent call to `init` to be executed. Before starting any filter session, you may also need to pass some global configuration options (libgpac core or filter options) to GPAC: @@ -117,7 +162,7 @@ gpac.set_logs("dash@info"); ``` -# Setting up filter sessions +# Setting up filter sessions {: data-level="beginner" } ## Simple sessions To create a filter session, the simplest way is to use all defaults value, creating a single-threaded blocking session: @@ -237,6 +282,7 @@ You can specify the usual link filtering as an optional argument to `set_source` ``` f_dst.set_source(reframer, "#PID=1"); ``` + This will instruct that the destination only accepts PIDs coming from the reframer filter, and with ID 1. @@ -254,7 +300,7 @@ Note that (as in GPAC JS or Python) properties referring to constant values are - AudioFormat: string containing the audio format name -# Custom Filters +# Custom Filters {: data-level="expert" } You can define your own filter(s) to interact with the media pipeline. As usual in GPAC filters, a custom filter can be a source, a sink or any other filter. It can consume packets from input PIDs and produce packets on output PIDs. @@ -437,7 +483,7 @@ fs.run(); -# Custom GPAC callbacks +# Custom GPAC callbacks {: data-level="expert" } Some callbacks from libgpac are made available in NodeJS ## Remotery interaction @@ -716,7 +762,7 @@ _NOTE When running the session in multi-thread mode, file IO callbacks are alway -# Multithread support +# Multithread support {: data-level="expert" } Multithreaded filter sessions can be used with NodeJS, however the binding currently only supports executing callbacks into NodeJS from the main thread (main NodeJS or worker). diff --git a/docs/Howtos/pipes.md b/docs/Howtos/pipes.md index d2642abb..2ebdaf78 100644 --- a/docs/Howtos/pipes.md +++ b/docs/Howtos/pipes.md @@ -1,10 +1,41 @@ -# Overview +--- +tags: +- pid +- data +- codec +- pipe +- multiplexer +- session +- pipeline +- compression +- encode +- dump +- media +- isobmff +- property +- box +- h264 +- option +- mp4 +- source +- chain +- input +- isomedia +- output +- mpeg +- sink +- encoder +--- + + + +# Overview {: data-level="all" } We discuss here how to use pipes in GPAC. GPAC supports data piping on Linux, OSX and Windows. The pipe is unidirectional, and can be used as source or as destination. -# Input pipe +# Input pipe {: data-level="beginner" } ## Simple reception of data @@ -36,7 +67,7 @@ The above command will run forever, since broken pipe messages are ignored. You There is currently no way to signal from the sender that the session should be closed, we might add this feature in the near future. -# Output pipe +# Output pipe Assume you have an app that consumes AVC|H264 in Annex B format from a pipe `myavcpipe`. You can direct GPAC output to this pipe: diff --git a/docs/Howtos/playlist.md b/docs/Howtos/playlist.md index 05a23824..dd0d6364 100644 --- a/docs/Howtos/playlist.md +++ b/docs/Howtos/playlist.md @@ -1,4 +1,41 @@ -# Overview +--- +tags: +- mpd +- transcode +- pid +- heif +- data +- codec +- filter +- sample +- session +- manifest +- frame +- stream +- encode +- bitstream +- sequence +- dump +- scene +- media +- cue +- isobmff +- track +- option +- mp4 +- source +- chain +- input +- isomedia +- output +- sink +- dash +- encoder +--- + + + +# Overview {: data-level="all" } We discuss here how to use the [flist](flist) filter to deal with playlists in GPAC. @@ -10,29 +47,33 @@ In both modes, when switching sources, the filter will match streams (PIDs) base 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 +# 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. -# Playlist mode +# Playlist mode ## 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. @@ -75,6 +116,7 @@ file.aac file.mp3 ##end playlist ``` + This will play twice `file.aac` then once `file.mp3`. @@ -99,10 +141,12 @@ 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 @@ -112,6 +156,7 @@ 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: @@ -134,6 +179,7 @@ v3.264 && a3.aac 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 ...). @@ -179,6 +225,7 @@ s3.mp4 s4.mp4 ##end playlist ``` + In this example, only `s1.mp4` and `s2.mp4` will be deleted. diff --git a/docs/Howtos/python.md b/docs/Howtos/python.md index 514f9514..1fcb0083 100644 --- a/docs/Howtos/python.md +++ b/docs/Howtos/python.md @@ -1,4 +1,55 @@ -# Overview +--- +tags: +- mpd +- pid +- reframer +- data +- tile +- codec +- filter +- buffer +- connection +- pipe +- sample +- session +- packet +- pipeline +- remux +- frame +- raw +- stream +- hevc +- bitrate +- dump +- opengl +- block +- link +- media +- segment +- isobmff +- decoder +- property +- group +- libgpac +- rebuffer +- chunk +- track +- option +- profile +- mp4 +- source +- packets +- chain +- input +- isomedia +- output +- sink +- dash +--- + + + +# Overview {:data-level="all"} We discuss here how to use [GPAC Filters](Filters) in Python. @@ -12,7 +63,7 @@ __Warning__ GPAC Python bindings are only available starting from GPAC 2.0. -# Before you begin +# Before you begin {:data-level="all"} The GPAC Python bindings use [ctypes](https://docs.python.org/3/library/ctypes.html) for interfacing with libgpac filter session, while providing an object-oriented wrapper hiding all ctypes internals and GPAC C design. @@ -49,7 +100,7 @@ Running this should print your current GPAC version. You can also install libgpac bindings using PIP, see [this post](https://github.com/gpac/gpac/issues/2161#issuecomment-1087281505). -# Tuning up GPAC +# Tuning up GPAC The first thing to do is to initialize libgpac. This is done by default while importing the bindings with the following settings: @@ -118,7 +169,7 @@ fs.delete() gpac.close() ``` -## Non-blocking sessions +## Non-blocking sessions A non-blocking session will need to be called on regular basis to process pending filter tasks. It is useful if you need to do other tasks while the session is running and do not want to use callbacks from GPAC for that. @@ -184,6 +235,7 @@ You can specify the usual link filtering as an optional argument to `set_source` ``` f_dst.set_source(reframer, "#PID=1") ``` + This will instruct that the destination only accepts PIDs coming from the reframer filter, and with ID 1. diff --git a/docs/Howtos/raw-formats.md b/docs/Howtos/raw-formats.md index 2adbdb7b..702bcdce 100644 --- a/docs/Howtos/raw-formats.md +++ b/docs/Howtos/raw-formats.md @@ -1,9 +1,38 @@ -# Overview +--- +tags: +- pid +- reframer +- data +- codec +- filter +- connection +- sample +- frame +- raw +- stream +- dump +- link +- media +- isobmff +- track +- option +- mp4 +- source +- chain +- input +- isomedia +- output +- sink +--- + + + +# Overview {: data-level="all" } We discuss here how to work with RAW, uncompressed audio and video data in GPAC. -# RAW Video +# RAW Video {: data-level="beginner" } ## Extracting raw video from a file @@ -89,7 +118,7 @@ This will resize and extract the video frames from start time 10s until end rang The above command will load a raw YUV420 planar 8-bits file using a resolution of 128x128 pixels, and display it using the [video output](vout) filter. The default frame rate is 25, as indicated in [the raw video reframer](rfrawvid). -# RAW Audio +# RAW Audio {: data-level="beginner" } This is very similar to raw video. ## Extracting raw audio from a file @@ -109,7 +138,7 @@ The above command will dump the audio content from `source.mp4` into a 16-bit li The above command will load a raw 16-bit little endian PCM file using 44100 Hz sample rate, and play it using the [audio output](aout) filter. The default channel count is 2, as indicated in [the raw audio reframer](rfpcm). -# RAW Audio and Video +# RAW Audio and Video {: data-level="beginner" } ## Direct extraction ```gpac -i source.mp4 -o test.pcm -o test.yuv``` diff --git a/docs/Howtos/realtime.md b/docs/Howtos/realtime.md index 84e09dd6..162b19b6 100644 --- a/docs/Howtos/realtime.md +++ b/docs/Howtos/realtime.md @@ -1,9 +1,48 @@ -# Overview +--- +tags: +- mpd +- pid +- reframer +- data +- filter +- connection +- sample +- session +- manifest +- frame +- stream +- bitstream +- sequence +- dump +- link +- media +- isobmff +- track +- latency +- option +- profile +- mp4 +- graph +- source +- packets +- chain +- input +- isomedia +- output +- decoding +- mpeg +- sink +- dash +--- + + + +# Overview {:data-level="all"} We discuss here how to simulate real-time sources in GPAC. -# Introduction +# Introduction Assume you have one or several sources dispatching data in a non real-time fashion, such as a local file, an HTTP download or a pipe input. You may want to produce data in real-time, for DASH, HLS, MPEG-2 TS or HTTP delivery. GPAC comes with the [reframer](reframer) filter, in charge of forcing a de-multiplexing of input data. This filter supports several features including: @@ -19,6 +58,7 @@ This is true for GPAC prior to 2.0 or when using complete mode linking [-cl](gpa ``` gpac [-cl] -i source.mp4 reframer -o dest.mp4 -graph ``` + In this example, the `source.mp4` input will produce a PID of type `FILE`, which will be directly connected to the `dest.mp4` output, and the reframer will simply not be connected: ``` diff --git a/docs/Howtos/route.md b/docs/Howtos/route.md index 547738b6..d14be421 100644 --- a/docs/Howtos/route.md +++ b/docs/Howtos/route.md @@ -1,4 +1,25 @@ -# Introduction +--- +tags: +- option +- mpd +- multicast +- session +- source +- input +- media +- data +- stream +- output +- filter +- dash +- dump +- broadcast +- latency +--- + + + +# Introduction {: data-level="all"} GPAC supports both sending and receiving files over unidirectional transport using the following protocols: - [ROUTE](https://www.rfc-editor.org/rfc/rfc9223) (Real-time Object delivery over Unidirectional Transport), and diff --git a/docs/Howtos/scenecoding/MP4Box-tips-and-tricks-with-BT-and-XMT.md b/docs/Howtos/scenecoding/MP4Box-tips-and-tricks-with-BT-and-XMT.md index 886411b5..726c8a2a 100644 --- a/docs/Howtos/scenecoding/MP4Box-tips-and-tricks-with-BT-and-XMT.md +++ b/docs/Howtos/scenecoding/MP4Box-tips-and-tricks-with-BT-and-XMT.md @@ -1,4 +1,20 @@ -## Minimal Stream Descriptors for MP4Box (BT and XMT) +--- +tags: +- scene +- media +- binary +- data +- stream +- xml +- bitstream +- sequence +- track +- macro +--- + + + +# Minimal Stream Descriptors for MP4Box (BT and XMT) {:data-level="all"} When encoding a BIFS or OD ES\_Descriptor, MP4Box must find at least: diff --git a/docs/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format.md b/docs/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format.md index dc690212..e6d54045 100644 --- a/docs/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format.md +++ b/docs/Howtos/scenecoding/MPEG-4-BIFS-Textual-Format.md @@ -1,4 +1,32 @@ -# BT Format +--- +tags: +- data +- codec +- sample +- frame +- stream +- encode +- bitstream +- sequence +- scene +- media +- isobmff +- group +- track +- option +- mp4 +- source +- input +- isomedia +- nhnt +- mpeg +- bifs +- encoder +--- + + + +# BT Format {:data-level="all"} BT stands for BIFS Text and is an exact textual representation of the MPEG-4 BIFS scene. Its syntax is the same as the VRML/X3D (.wrl and .x3dv files) ones for the scene description part, and it has been extended for other MPEG-4 tools (OD, OCI, IPMP). diff --git a/docs/Howtos/scenecoding/MPEG-4-Scene-Commands.md b/docs/Howtos/scenecoding/MPEG-4-Scene-Commands.md index 527ed3c9..630049e0 100644 --- a/docs/Howtos/scenecoding/MPEG-4-Scene-Commands.md +++ b/docs/Howtos/scenecoding/MPEG-4-Scene-Commands.md @@ -1,6 +1,17 @@ +--- +tags: +- scene +- data +- xml +--- + + + +# Foreword {:data-level="all"} + We will now review the syntax of MPEG-4 scene commands in both BT and XMT-A formats. Please remember that BT and XMT languages are case sensitive. -## Command declaration +# Command declaration ### BT format @@ -41,6 +52,7 @@ REPLACE nodeName.fieldName BY NodeDeclaration {... } ``` + Note that the new node can be DEF'ed, or that a null node may be specified (`NULL` ). ## Replacing a value in a multiple field @@ -53,6 +65,7 @@ REPLACE nodeName.fieldName[idx] BY newValue ```xml ``` + For XMT-A, `idx` can also take the special values 'BEGIN' and 'END'. Replacement of a node in an MFNode field is the combination of both syntax ## Replacing a multiple field @@ -74,6 +87,7 @@ REPLACE nodeName.fieldName BY [Node { ... } ... Node { ... }] ... ``` + Replacement of a node in an MFNode field is the combination of both syntax ## Deleting a node @@ -102,6 +116,7 @@ DELETE nodeName.fieldName[idx] ```xml ``` + For XMT-A, `idx` can also take the special values 'BEGIN' and 'END'. ## Inserting a simple value in a multiple field @@ -117,6 +132,7 @@ APPEND TO nodeName.fieldName newValue ```xml ``` + For XMT-A, `idx` can also take the special values 'BEGIN' and 'END'. ## Inserting a node in a node list field @@ -134,6 +150,7 @@ APPEND TO nodeName.fieldName Node { } ... ``` + For XMT-A, `idx` can also take the special values 'BEGIN' and 'END'. ## Replacing a route diff --git a/docs/Howtos/scenecoding/MPEG-4-XMT-Format.md b/docs/Howtos/scenecoding/MPEG-4-XMT-Format.md index 0d299700..c39cf86c 100644 --- a/docs/Howtos/scenecoding/MPEG-4-XMT-Format.md +++ b/docs/Howtos/scenecoding/MPEG-4-XMT-Format.md @@ -1,4 +1,18 @@ -# XMT Format +--- +tags: +- mp4 +- media +- isomedia +- data +- encode +- isobmff +- xml +- stream +--- + + + +# XMT Format {:data-level="all"} XMT is the official textural description of MPEG-4 scenes. It is part of ISO/IEC 14496-11, and is quite similar to the X3D XML language. diff --git a/docs/Howtos/scenecoding/SceneCodingIntro.md b/docs/Howtos/scenecoding/SceneCodingIntro.md index 37796265..023e7d09 100644 --- a/docs/Howtos/scenecoding/SceneCodingIntro.md +++ b/docs/Howtos/scenecoding/SceneCodingIntro.md @@ -1,4 +1,19 @@ -# Multimedia scene description +--- +tags: +- scene +- profile +- media +- data +- stream +- compositor +- xml +- mpeg +- bifs +--- + + + +# Multimedia scene description {:data-level="all" } A scene description is a language describing animations, interactivity, 2D and 3D shapes, audio and video relationship in a presentation. GPAC supports a variety of scene description languages: diff --git a/docs/Howtos/scte35-markers.md b/docs/Howtos/scte35-markers.md index a1719c05..7c11b37f 100644 --- a/docs/Howtos/scte35-markers.md +++ b/docs/Howtos/scte35-markers.md @@ -1,4 +1,32 @@ -# Overview +--- +tags: +- mpd +- pid +- data +- filter +- packet +- remux +- stream +- xml +- dump +- block +- media +- segment +- isobmff +- track +- chunk +- mp4 +- source +- input +- isomedia +- output +- sink +- dash +--- + + + +# Overview {:data-level="all"} We discuss here about the ability to deal with dynamic metadata such as SCTE-35 in GPAC Filters. The information is this page applies to other metadata such as ID3 markers (e.g. Nielsen), timecodes (TEMI, QT), or virtually any type of dynamic metadata. @@ -63,7 +91,7 @@ scte35_dump.xml would contain for instance such descriptions for a sample: ``` -# Remux and transmux +# Remux and transmux {:data-level="beginner"} GPAC is able to remux any to any, including but not limited to: - TS to TS diff --git a/docs/Howtos/sockets.md b/docs/Howtos/sockets.md index 86750e59..276ee7c7 100644 --- a/docs/Howtos/sockets.md +++ b/docs/Howtos/sockets.md @@ -1,4 +1,35 @@ -# Overview +--- +tags: +- pid +- data +- codec +- filter +- connection +- multiplexer +- session +- compression +- encode +- dump +- link +- media +- isobmff +- property +- box +- h264 +- option +- mp4 +- source +- input +- isomedia +- output +- mpeg +- sink +- encoder +--- + + + +# Overview {: data-level="all" } We discuss here how to use sockets in GPAC for generic IO. diff --git a/docs/Howtos/subtitles/EBU-TTD-support-in-GPAC.md b/docs/Howtos/subtitles/EBU-TTD-support-in-GPAC.md index 536c2c1e..9aa1fd13 100644 --- a/docs/Howtos/subtitles/EBU-TTD-support-in-GPAC.md +++ b/docs/Howtos/subtitles/EBU-TTD-support-in-GPAC.md @@ -1,3 +1,19 @@ +--- +tags: +- profile +- mp4 +- sample +- ttml +- isomedia +- isobmff +- stream +- xml +- dash +- track +--- + + + EBU released two specifications recently: * [TECH 3380](https://tech.ebu.ch/docs/tech/tech3380.pdf) v1.0: EBU-TT-D SUBTITLING DISTRIBUTION FORMAT. This document aims to define a distribution subtitling format base on TTML. This is both a restriction (i.e. a profile) and an extension of TTML. The extensions are very limited. The restrictions allow to mitigate most of the TTML criticisms (especially an ability to express things in several ways, which led to a difficult generic parsing process). diff --git a/docs/Howtos/subtitles/Subtitling-with-GPAC.md b/docs/Howtos/subtitles/Subtitling-with-GPAC.md index 5a16fd1a..bf7c8011 100644 --- a/docs/Howtos/subtitles/Subtitling-with-GPAC.md +++ b/docs/Howtos/subtitles/Subtitling-with-GPAC.md @@ -1,3 +1,36 @@ +--- +tags: +- heif +- data +- webvtt +- filter +- sample +- session +- ttml +- frame +- raw +- xml +- stream +- dump +- media +- isobmff +- group +- box +- track +- mp4 +- source +- input +- isomedia +- binary +- output +- decoding +- mpeg +- sink +- dash +--- + + + There are plenty of [subtitle formats](http://en.wikipedia.org/wiki/Subtitle_(captioning)#Subtitle_formats) and plenty of [types](http://en.wikipedia.org/wiki/Subtitle_(captioning)#Types) and [categories](http://en.wikipedia.org/wiki/Subtitle_(captioning)#Categories) of subtitles. GPAC's support for subtitles is based on the support for the ISO Base Media File Format (ISOBMFF). The ISOBMFF considers that any data that produces human readable text to be used as subtitles, closed captions, is, well, ...subtitles. It further considers that there are two major classes of subtitle formats: formats which require only text processing capabilities (text decoding, text layout) and formats which also require image processing capabilities. These classes are identified by the `Track Handler Type`. diff --git a/docs/Howtos/test.md b/docs/Howtos/test.md new file mode 100644 index 00000000..6514b1f2 --- /dev/null +++ b/docs/Howtos/test.md @@ -0,0 +1,13 @@ +## Advanced reception of data +Assume you want gpac to grab from a sbaring some AVC|H264 content which could be sent sequentially by sbaring typically, an sbaring poof encoder processing a playlist and sending each result to a socket. Having the encoder create the socket will result in closing the socket at each file, hence closing gpac after the first file, which is not the goal. We need to +- create the socket by asking the [socket](sockin) input to create it for us using [listen](sockin) option +- tell the socket input to keep the session alive even when socket connection close messages are received, using [ka](sockin) option poof + + +```gpac -i tcp://127.0.0.1:1234/:ext=avc:listen:ka -o test.mp4``` + +This will open the socket, creating it if not found, and we can now start sending data on the socket. + +__Discussion__ +The above command will run forever, since socket connection close messages are ignored. You can abort the session using `ctr+c` and ask to flush pending data to disk. If you have enabled prompt interactivity in gpac [-k](gpac_general), simply press `q`. +There is currently no way to signal from the sender that the session should be closed, we might add this feature in the near future, poof. diff --git a/docs/MP4Box/MP4Box.md b/docs/MP4Box/MP4Box.md index fbb998f1..d0e08109 100644 --- a/docs/MP4Box/MP4Box.md +++ b/docs/MP4Box/MP4Box.md @@ -1,4 +1,4 @@ -# Overview +# Overview {:data-level="all"} The multimedia packager available in GPAC is called MP4Box. It is mostly designed for processing ISOBMF files (e.g. MP4, 3GP), but can also be used to import/export media from container files like AVI, MPG, MKV, MPEG-2 TS ... diff --git a/docs/MP4Box/mp4box-dash-opts.md b/docs/MP4Box/mp4box-dash-opts.md index aae46851..9e375246 100644 --- a/docs/MP4Box/mp4box-dash-opts.md +++ b/docs/MP4Box/mp4box-dash-opts.md @@ -46,12 +46,14 @@ __Warning: This does not modify generated files location (see segment template). Example ``` source.mp4:@c=avc:b=1M@@c=avc:b=500k -``` +``` + This will load a filter chain with two encoders connected to the source and to the dasher. Example ``` source.mp4:@c=avc:b=1M@c=avc:b=500k -``` +``` + This will load a filter chain with the second encoder connected to the output of the first (!!). _Note: `@f` must be placed after all other options._ @@ -60,16 +62,35 @@ _Note: Descriptors value must be a properly formatted XML element(s), value is n # Options -__-dash__ (number): create DASH from input files with given segment (subsegment for onDemand profile) duration in ms -__-dash-live__ (number): generate a live DASH session using the given segment duration in ms; using `-dash-live=F` will also write the live context to `F`. MP4Box will run the live session until `q` is pressed or a fatal error occurs -__-ddbg-live__ (number): same as [-dash-live](#dash-live) without time regulation for debug purposes -__-frag__ (number): specify the fragment duration in ms. If not set, this is the DASH duration (one fragment per segment) -__-out__ (string): specify the output MPD file name -__-profile__,__-dash-profile__ (string): specify the target DASH profile, and set default options to ensure conformance to the desired profile. Default profile is `full` in static mode, `live` in dynamic mode (old syntax using `:live` instead of `.live` as separator still possible). Defined values are onDemand, live, main, simple, full, hbbtv1.5.live, dashavc264.live, dashavc264.onDemand, dashif.ll -__-profile-ext__ (string): specify a list of profile extensions, as used by DASH-IF and DVB. The string will be colon-concatenated with the profile used -__-rap__: ensure that segments begin with random access points, segment durations might vary depending on the source encoding -__-frag-rap__: ensure that all fragments begin with random access points (duration might vary depending on the source encoding) -__-segment-name__ (string): set the segment name for generated segments. If not set (default), segments are concatenated in output file except in `live` profile where `dash_%%s`. Supported replacement strings are: +
+__-dash__ (number): create DASH from input files with given segment (subsegment for onDemand profile) duration in ms +
+
+__-dash-live__ (number): generate a live DASH session using the given segment duration in ms; using `-dash-live=F` will also write the live context to `F`. MP4Box will run the live session until `q` is pressed or a fatal error occurs +
+
+__-ddbg-live__ (number): same as [-dash-live](#dash-live) without time regulation for debug purposes +
+
+__-frag__ (number): specify the fragment duration in ms. If not set, this is the DASH duration (one fragment per segment) +
+
+__-out__ (string): specify the output MPD file name +
+
+__-profile__,__-dash-profile__ (string): specify the target DASH profile, and set default options to ensure conformance to the desired profile. Default profile is `full` in static mode, `live` in dynamic mode (old syntax using `:live` instead of `.live` as separator still possible). Defined values are onDemand, live, main, simple, full, hbbtv1.5.live, dashavc264.live, dashavc264.onDemand, dashif.ll +
+
+__-profile-ext__ (string): specify a list of profile extensions, as used by DASH-IF and DVB. The string will be colon-concatenated with the profile used +
+
+__-rap__: ensure that segments begin with random access points, segment durations might vary depending on the source encoding +
+
+__-frag-rap__: ensure that all fragments begin with random access points (duration might vary depending on the source encoding) +
+
+__-segment-name__ (string): set the segment name for generated segments. If not set (default), segments are concatenated in output file except in `live` profile where `dash_%%s`. Supported replacement strings are: - $Number[%%0Nd]$ is replaced by the segment number, possibly prefixed with 0 - $RepresentationID$ is replaced by representation name @@ -79,34 +100,80 @@ _Note: Descriptors value must be a properly formatted XML element(s), value is n - $Index=NAME$ is replaced by NAME for index segments, ignored otherwise - $Path=PATH$ is replaced by PATH when creating segments, ignored otherwise - $Segment=NAME$ is replaced by NAME for media segments, ignored for init segments +
-__-segment-ext__ (string, default: __m4s__): set the segment extension, `null` means no extension -__-init-segment-ext__ (string, default: __mp4__): set the segment extension for init, index and bitstream switching segments, `null` means no extension +
+__-segment-ext__ (string, default: __m4s__): set the segment extension, `null` means no extension +
+
+__-init-segment-ext__ (string, default: __mp4__): set the segment extension for init, index and bitstream switching segments, `null` means no extension -__-segment-timeline__: use `SegmentTimeline` when generating segments -__-segment-marker__ (string): add a box of given type (4CC) at the end of each DASH segment -__-insert-utc__: insert UTC clock at the beginning of each ISOBMF segment -__-base-url__ (string): set Base url at MPD level. Can be used several times. +
+
+__-segment-timeline__: use `SegmentTimeline` when generating segments +
+
+__-segment-marker__ (string): add a box of given type (4CC) at the end of each DASH segment +
+
+__-insert-utc__: insert UTC clock at the beginning of each ISOBMF segment +
+
+__-base-url__ (string): set Base url at MPD level. Can be used several times. __Warning: this does not modify generated files location__ -__-mpd-title__ (string): set MPD title -__-mpd-source__ (string): set MPD source -__-mpd-info-url__ (string): set MPD info url +
+
+__-mpd-title__ (string): set MPD title +
+
+__-mpd-source__ (string): set MPD source +
+
+__-mpd-info-url__ (string): set MPD info url +
+
__-cprt__ (string): add copyright string to MPD -__-dash-ctx__ (string): store/restore DASH timing from indicated file -__-dynamic__: use dynamic MPD type instead of static -__-last-dynamic__: same as [-dynamic](#dynamic) but close the period (insert lmsg brand if needed and update duration) -__-mpd-duration__ (number): set the duration in second of a live session (if `0`, you must use [-mpd-refresh](#mpd-refresh)) -__-mpd-refresh__ (number): specify MPD update time in seconds -__-time-shift__ (int): specify MPD time shift buffer depth in seconds, `-1` to keep all files) -__-subdur__ (number): specify maximum duration in ms of the input file to be dashed in LIVE or context mode. This does not change the segment duration, but stops dashing once segments produced exceeded the duration. If there is not enough samples to finish a segment, data is looped unless [-no-loop](#no-loop) is used which triggers a period end -__-run-for__ (int): run for given ms the dash-live session then exits -__-min-buffer__ (int): specify MPD min buffer time in ms -__-ast-offset__ (int): specify MPD AvailabilityStartTime offset in ms if positive, or availabilityTimeOffset of each representation if negative -__-dash-scale__ (int): specify that timing for [-dash](#dash), [-dash-live](#dash-live), [-subdur](#subdur) and [-do_frag](#do_frag) are expressed in given timescale (units per seconds) rather than ms -__-mem-frags__: fragmentation happens in memory rather than on disk before flushing to disk -__-pssh__ (int): set pssh store mode +
+
+__-dash-ctx__ (string): store/restore DASH timing from indicated file +
+
+__-dynamic__: use dynamic MPD type instead of static +
+
+__-last-dynamic__: same as [-dynamic](#dynamic) but close the period (insert lmsg brand if needed and update duration) +
+
+__-mpd-duration__ (number): set the duration in second of a live session (if `0`, you must use [-mpd-refresh](#mpd-refresh)) +
+
+__-mpd-refresh__ (number): specify MPD update time in seconds +
+
+__-time-shift__ (int): specify MPD time shift buffer depth in seconds, `-1` to keep all files) +
+
+__-subdur__ (number): specify maximum duration in ms of the input file to be dashed in LIVE or context mode. This does not change the segment duration, but stops dashing once segments produced exceeded the duration. If there is not enough samples to finish a segment, data is looped unless [-no-loop](#no-loop) is used which triggers a period end +
+
+__-run-for__ (int): run for given ms the dash-live session then exits +
+
+__-min-buffer__ (int): specify MPD min buffer time in ms +
+
+__-ast-offset__ (int): specify MPD AvailabilityStartTime offset in ms if positive, or availabilityTimeOffset of each representation if negative +
+
+__-dash-scale__ (int): specify that timing for [-dash](#dash), [-dash-live](#dash-live), [-subdur](#subdur) and [-do_frag](#do_frag) are expressed in given timescale (units per seconds) rather than ms +
+
+__-mem-frags__: fragmentation happens in memory rather than on disk before flushing to disk +
+
+__-pssh__ (int): set pssh store mode - v: initial movie - f: movie fragments @@ -114,32 +181,64 @@ __Warning: this does not modify generated files location__ - mv, vm: in initial movie and MPD - mf, fm: in movie fragments and MPD - n: remove PSSH from MPD, initial movie and movie fragments +
-__-sample-groups-traf__: store sample group descriptions in traf (duplicated for each traf). If not set, sample group descriptions are stored in the initial movie -__-mvex-after-traks__: store `mvex` box after `trak` boxes within the moov box. If not set, `mvex` is before -__-sdtp-traf__ (int): use `sdtp` box in `traf` (Smooth-like) +
+__-sample-groups-traf__: store sample group descriptions in traf (duplicated for each traf). If not set, sample group descriptions are stored in the initial movie +
+
+__-mvex-after-traks__: store `mvex` box after `trak` boxes within the moov box. If not set, `mvex` is before +
+
+__-sdtp-traf__ (int): use `sdtp` box in `traf` (Smooth-like) - no: do not use sdtp - sdtp: use sdtp box to indicate sample dependencies and do not write info in trun sample flags - both: use sdtp box to indicate sample dependencies and also write info in trun sample flags +
-__-no-cache__: disable file cache for dash inputs -__-no-loop__: disable looping content in live mode and uses period switch instead -__-hlsc__: insert UTC in variant playlists for live HLS -__-bound__: segmentation will always try to split before or at, but never after, the segment boundary -__-closest__: segmentation will use the closest frame to the segment boundary (before or after) +
+__-no-cache__: disable file cache for dash inputs +
+
+__-no-loop__: disable looping content in live mode and uses period switch instead +
+
+__-hlsc__: insert UTC in variant playlists for live HLS +
+
+__-bound__: segmentation will always try to split before or at, but never after, the segment boundary +
+
+__-closest__: segmentation will use the closest frame to the segment boundary (before or after) +
+
__-subsegs-per-sidx__,__-frags-per-sidx__ (int): set the number of subsegments to be written in each SIDX box - 0: a single SIDX box is used per segment - -1: no SIDX box is used +
+
__-ssix__: enable SubsegmentIndexBox describing 2 ranges, first one from moof to end of first I-frame, second one unmapped. This does not work with daisy chaining mode enabled +
+
__-url-template__: use SegmentTemplate instead of explicit sources in segments. Ignored if segments are stored in the output file +
+
__-url-template-sim__: use SegmentTemplate simulation while converting HLS to MPD +
+
__-daisy-chain__: use daisy-chain SIDX instead of hierarchical. Ignored if frags/sidx is 0 +
+
__-single-segment__: use a single segment for the whole file (OnDemand profile) +
+
__-single-file__: use a single file for the whole file (default) +
+
__-bs-switching__ (string, default: __inband__, values: _inband|merge|multi|no|single_): set bitstream switching mode - inband: use inband param set and a single init segment @@ -148,24 +247,49 @@ __Warning: this does not modify generated files location__ - no: use one init segment per quality - pps: use out of band VPS,SPS,DCI, inband for PPS,APS and a single init segment - single: to test with single input +
+
__-moof-sn__ (int): set sequence number of first moof to given value +
+
__-tfdt__ (int): set TFDT of first traf to given value in SCALE units (cf -dash-scale) +
+
__-no-frags-default__: disable default fragments flags in trex (required by some dash-if profiles and CMAF/smooth streaming compatibility) +
+
__-single-traf__: use a single track fragment per moof (smooth streaming and derived specs may require this) +
+
__-tfdt-traf__: use a tfdt per track fragment (when -single-traf is used) +
+
__-dash-ts-prog__ (int): program_number to be considered in case of an MPTS input file +
+
__-frag-rt__: when using fragments in live mode, flush fragments according to their timing +
+
__-cp-location__ (string): set ContentProtection element location - as: sets ContentProtection in AdaptationSet element - rep: sets ContentProtection in Representation element - both: sets ContentProtection in both elements +
+
__-start-date__ (string): for live mode, set start date (as xs:date, e.g. YYYY-MM-DDTHH:MM:SSZ). Default is current UTC __Warning: Do not use with multiple periods, nor when DASH duration is not a multiple of GOP size__ +
+
__-cues__ (string): ignore dash duration and segment according to cue times in given XML file (tests/media/dash_cues for examples) +
+
__-strict-cues__: throw error if something is wrong while parsing cues or applying cue-based segmentation +
+
__-merge-last-seg__: merge last segment if shorter than half the target duration +
diff --git a/docs/MP4Box/mp4box-dump-opts.md b/docs/MP4Box/mp4box-dump-opts.md index 3ee51057..172a7ec1 100644 --- a/docs/MP4Box/mp4box-dump-opts.md +++ b/docs/MP4Box/mp4box-dump-opts.md @@ -5,25 +5,53 @@ MP4Box can be used to extract media tracks from MP4 files. If you need to convert these tracks however, please check the [filters doc](Filters). Options: -__-raw__ (string): extract given track in raw format when supported. Use `tkID:output=FileName` to set output file name -__-raws__ (string): extract each sample of the given track to a file. Use `tkID:N` to extract the Nth sample -__-nhnt__ (int): extract given track to [NHNT](nhntr) format -__-nhml__ (string): extract given track to [NHML](nhmlr) format. Use `tkID:full` for full NHML dump with all packet properties -__-webvtt-raw__ (string): extract given track as raw media in WebVTT as metadata. Use `tkID:embedded` to include media data in the WebVTT file -__-single__ (int): extract given track to a new mp4 file -__-six__ (int): extract given track as raw media in __experimental__ XML streaming instructions -__-mux__ (string): multiplex input file to given destination -__-qcp__ (int): same as [-raw](#raw) but defaults to QCP file for EVRC/SMV -__-saf__: multiplex input file to SAF multiplex -__-dvbhdemux__: demultiplex DVB-H file into IP Datagrams sent on the network -__-raw-layer__ (int): same as [-raw](#raw) but skips SVC/MVC/LHVC extractors when extracting -__-diod__: extract file IOD in raw format -__-mpd__ (string): convert given HLS or smooth manifest (local or remote http) to MPD - options `-url-template` and `-segment-timeline`can be used in this mode. +
+__-raw__ (string): extract given track in raw format when supported. Use `tkID:output=FileName` to set output file name +
+
+__-raws__ (string): extract each sample of the given track to a file. Use `tkID:N` to extract the Nth sample +
+
+__-nhnt__ (int): extract given track to [NHNT](nhntr) format +
+
+__-nhml__ (string): extract given track to [NHML](nhmlr) format. Use `tkID:full` for full NHML dump with all packet properties +
+
+__-webvtt-raw__ (string): extract given track as raw media in WebVTT as metadata. Use `tkID:embedded` to include media data in the WebVTT file +
+
+__-single__ (int): extract given track to a new mp4 file +
+
+__-six__ (int): extract given track as raw media in __experimental__ XML streaming instructions +
+
+__-mux__ (string): multiplex input file to given destination +
+
+__-qcp__ (int): same as [-raw](#raw) but defaults to QCP file for EVRC/SMV +
+
+__-saf__: multiplex input file to SAF multiplex +
+
+__-dvbhdemux__: demultiplex DVB-H file into IP Datagrams sent on the network +
+
+__-raw-layer__ (int): same as [-raw](#raw) but skips SVC/MVC/LHVC extractors when extracting +
+
+__-diod__: extract file IOD in raw format +
+
+__-mpd__ (string): convert given HLS or smooth manifest (local or remote http) to MPD - options `-url-template` and `-segment-timeline`can be used in this mode. _Note: This only provides basic conversion, for more advanced conversions, see `gpac -h dasher`_ __Warning: This is not compatible with other DASH options and does not convert associated segments__ +
# File Dumping @@ -32,63 +60,177 @@ __Warning: This is not compatible with other DASH options and does not convert a MP4Box has many dump functionalities, from simple track listing to more complete reporting of special tracks. Options: -__-std__: dump/write to stdout and assume stdout is opened in binary mode -__-stdb__: dump/write to stdout and try to reopen stdout in binary mode -__-tracks__: print the number of tracks on stdout -__-info__ (string): print movie info (no parameter) or track extended info with specified ID -__-infon__ (string): print track info for given track number, 1 being the first track in the file -__-infox__: print movie and track extended info (same as -info N` for each track)` -__-diso__,__-dmp4__: dump IsoMedia file boxes in XML output -__-dxml__: dump IsoMedia file boxes and known track samples in XML output -__-disox__: dump IsoMedia file boxes except sample tables in XML output -__-keep-ods__: do not translate ISOM ODs and ESDs tags (debug purpose only) -__-bt__: dump scene to BT format -__-xmt__: dump scene to XMT format -__-wrl__: dump scene to VRML format -__-x3d__: dump scene to X3D XML format -__-x3dv__: dump scene to X3D VRML format -__-lsr__: dump scene to LASeR XML (XSR) format -__-svg__: dump scene to SVG -__-drtp__: dump rtp hint samples structure to XML output -__-dts__: print sample timing, size and position in file to text output -__-dtsx__: same as [-dts](#dts) but does not print offset -__-dtsc__: same as [-dts](#dts) but analyses each sample for duplicated dts/cts (_slow !_) -__-dtsxc__: same as [-dtsc](#dtsc) but does not print offset (_slow !_) -__-dnal__ (int): print NAL sample info of given track -__-dnalc__ (int): print NAL sample info of given track, adding CRC for each nal -__-dnald__ (int): print NAL sample info of given track without DTS and CTS info -__-dnalx__ (int): print NAL sample info of given track without DTS and CTS info and adding CRC for each nal -__-sdp__: dump SDP description of hinted file -__-dsap__ (int): dump DASH SAP cues (see -cues) for a given track -__-dsaps__ (int): same as [-dsap](#dsap) but only print sample number -__-dsapc__ (int): same as [-dsap](#dsap) but only print CTS -__-dsapd__ (int): same as [-dsap](#dsap) but only print DTS +
+__-std__: dump/write to stdout and assume stdout is opened in binary mode +
+
+__-stdb__: dump/write to stdout and try to reopen stdout in binary mode +
+
+__-tracks__: print the number of tracks on stdout +
+
+__-info__ (string): print movie info (no parameter) or track extended info with specified ID +
+
+__-infon__ (string): print track info for given track number, 1 being the first track in the file +
+
+__-infox__: print movie and track extended info (same as -info N` for each track)` +
+
+__-diso__,__-dmp4__: dump IsoMedia file boxes in XML output +
+
+__-dxml__: dump IsoMedia file boxes and known track samples in XML output +
+
+__-disox__: dump IsoMedia file boxes except sample tables in XML output +
+
+__-keep-ods__: do not translate ISOM ODs and ESDs tags (debug purpose only) +
+
+__-bt__: dump scene to BT format +
+
+__-xmt__: dump scene to XMT format +
+
+__-wrl__: dump scene to VRML format +
+
+__-x3d__: dump scene to X3D XML format +
+
+__-x3dv__: dump scene to X3D VRML format +
+
+__-lsr__: dump scene to LASeR XML (XSR) format +
+
+__-svg__: dump scene to SVG +
+
+__-drtp__: dump rtp hint samples structure to XML output +
+
+__-dts__: print sample timing, size and position in file to text output +
+
+__-dtsx__: same as [-dts](#dts) but does not print offset +
+
+__-dtsc__: same as [-dts](#dts) but analyses each sample for duplicated dts/cts (_slow !_) +
+
+__-dtsxc__: same as [-dtsc](#dtsc) but does not print offset (_slow !_) +
+
+__-dnal__ (int): print NAL sample info of given track +
+
+__-dnalc__ (int): print NAL sample info of given track, adding CRC for each nal +
+
+__-dnald__ (int): print NAL sample info of given track without DTS and CTS info +
+
+__-dnalx__ (int): print NAL sample info of given track without DTS and CTS info and adding CRC for each nal +
+
+__-sdp__: dump SDP description of hinted file +
+
+__-dsap__ (int): dump DASH SAP cues (see -cues) for a given track +
+
+__-dsaps__ (int): same as [-dsap](#dsap) but only print sample number +
+
+__-dsapc__ (int): same as [-dsap](#dsap) but only print CTS +
+
+__-dsapd__ (int): same as [-dsap](#dsap) but only print DTS +
+
__-dsapp__ (int): same as [-dsap](#dsap) but only print presentation time -__-dcr__: dump ISMACryp samples structure to XML output -__-dchunk__: dump chunk info -__-dump-cover__: extract cover art -__-dump-chap__: extract chapter file as TTXT format -__-dump-chap-ogg__: extract chapter file as OGG format -__-dump-chap-zoom__: extract chapter file as zoom format -__-dump-udta__ `[tkID:]4cc`: extract user data for the given 4CC. If `tkID` is given, dumps from UDTA of the given track ID, otherwise moov is used -__-mergevtt__: merge vtt cues while dumping -__-ttxt__ (int): convert input subtitle to GPAC TTXT format if no parameter. Otherwise, dump given text track to GPAC TTXT format -__-srt__ (int): convert input subtitle to SRT format if no parameter. Otherwise, dump given text track to SRT format -__-nstat__: generate node/field statistics for scene -__-nstats__: generate node/field statistics per Access Unit -__-nstatx__: generate node/field statistics for scene after each AU -__-hash__: generate SHA-1 Hash of the input file -__-comp__ (string): replace with compressed version all top level box types given as parameter, formatted as `orig_4cc_1=comp_4cc_1[,orig_4cc_2=comp_4cc_2]` -__-topcount__ (string): print to stdout the number of top-level boxes matching box types given as parameter, formatted as `4cc_1,4cc_2N` -__-topsize__ (string): print to stdout the number of bytes of top-level boxes matching types given as parameter, formatted as `4cc_1,4cc_2N` or `all` for all boxes -__-bin__: convert input XML file using NHML bitstream syntax to binary -__-mpd-rip__: fetch MPD and segment to disk +
+
+__-dcr__: dump ISMACryp samples structure to XML output +
+
+__-dchunk__: dump chunk info +
+
+__-dump-cover__: extract cover art +
+
+__-dump-chap__: extract chapter file as TTXT format +
+
+__-dump-chap-ogg__: extract chapter file as OGG format +
+
+__-dump-chap-zoom__: extract chapter file as zoom format +
+
+__-dump-udta__ `[tkID:]4cc`: extract user data for the given 4CC. If `tkID` is given, dumps from UDTA of the given track ID, otherwise moov is used +
+
+__-mergevtt__: merge vtt cues while dumping +
+
+__-ttxt__ (int): convert input subtitle to GPAC TTXT format if no parameter. Otherwise, dump given text track to GPAC TTXT format +
+
+__-srt__ (int): convert input subtitle to SRT format if no parameter. Otherwise, dump given text track to SRT format +
+
+__-nstat__: generate node/field statistics for scene +
+
+__-nstats__: generate node/field statistics per Access Unit +
+
+__-nstatx__: generate node/field statistics for scene after each AU +
+
+__-hash__: generate SHA-1 Hash of the input file +
+
+__-comp__ (string): replace with compressed version all top level box types given as parameter, formatted as `orig_4cc_1=comp_4cc_1[,orig_4cc_2=comp_4cc_2]` +
+
+__-topcount__ (string): print to stdout the number of top-level boxes matching box types given as parameter, formatted as `4cc_1,4cc_2N` +
+
+__-topsize__ (string): print to stdout the number of bytes of top-level boxes matching types given as parameter, formatted as `4cc_1,4cc_2N` or `all` for all boxes +
+
+__-bin__: convert input XML file using NHML bitstream syntax to binary +
+
+__-mpd-rip__: fetch MPD and segment to disk +
+
__-udp-write__ (string, default: __IP[:port]__): write input name to UDP (default port 2345) +
+
__-raw-cat__ (string): raw concatenation of given file with input file +
+
__-wget__ (string): fetch resource from http(s) URL -__-dm2ts__: dump timing of an input MPEG-2 TS stream sample timing -__-check-xml__: check XML output format for -dnal*, -diso* and -dxml options +
+
+__-dm2ts__: dump timing of an input MPEG-2 TS stream sample timing +
+
+__-check-xml__: check XML output format for -dnal*, -diso* and -dxml options +
+
__-fuzz-chk__: open file without probing and exit (for fuzz tests) +
# File splitting @@ -121,31 +263,45 @@ The default output storage mode is to full interleave and will require a temp fi The output file name(s) can be specified using `-out` and templates (e.g. `-out split$num%04d$.mp4` produces split0001.mp4, split0002.mp4, ...). Multiple time ranges can be specified as a comma-separated list for `-splitx`, `-splitz` and `-splitg`. -__-split__ (string): split in files of given max duration (float number) in seconds. A trailing unit can be specified: +
+__-split__ (string): split in files of given max duration (float number) in seconds. A trailing unit can be specified: - `M`, `m`: duration is in minutes - `H`, `h`: size is in hours +
-__-split-rap__,__-splitr__ (string): split in files at each new RAP -__-split-size__,__-splits__ (string): split in files of given max size (integer number) in kilobytes. A trailing unit can be specified: +
+__-split-rap__,__-splitr__ (string): split in files at each new RAP +
+
+__-split-size__,__-splits__ (string): split in files of given max size (integer number) in kilobytes. A trailing unit can be specified: - `M`, `m`: size is in megabytes - `G`, `g`: size is in gigabytes +
-__-split-chunk__,__-splitx__ (string): extract the specified time range as follows: +
+__-split-chunk__,__-splitx__ (string): extract the specified time range as follows: - the start time is moved to the RAP sample closest to the specified start time - the end time is kept as requested +
-__-splitz__ (string): extract the specified time range so that ranges `A:B` and `B:C` share exactly the same boundary `B`: +
+__-splitz__ (string): extract the specified time range so that ranges `A:B` and `B:C` share exactly the same boundary `B`: - the start time is moved to the RAP sample at or after the specified start time - the end time is moved to the frame preceding the RAP sample at or following the specified end time +
-__-splitg__ (string): extract the specified time range as follows: +
+__-splitg__ (string): extract the specified time range as follows: - the start time is moved to the RAP sample at or before the specified start time - the end time is moved to the frame preceding the RAP sample at or following the specified end time +
-__-splitf__ (string): extract the specified time range and insert edits such that the extracted output is exactly the specified range +
+__-splitf__ (string): extract the specified time range and insert edits such that the extracted output is exactly the specified range +
diff --git a/docs/MP4Box/mp4box-gen-opts.md b/docs/MP4Box/mp4box-gen-opts.md index 57c85060..8ee16b58 100644 --- a/docs/MP4Box/mp4box-gen-opts.md +++ b/docs/MP4Box/mp4box-gen-opts.md @@ -25,48 +25,115 @@ Option values: Unless specified otherwise, a track operation option of type `integer` expects a track identifier value following it. An option of type `boolean` expects no following value. -__-mem-track__: enable memory tracker -__-mem-track-stack__: enable memory tracker with stack dumping +
__-p__ (string): use indicated profile for the global GPAC config. If not found, config file is created. If a file path is indicated, this will load profile from that file. Otherwise, this will create a directory of the specified name and store new config there. Reserved name `0` means a new profile, not stored to disk. Works using -p=NAME or -p NAME -__-inter__ (number, default: __0.5__): interleave file, producing track chunks with given duration in ms. A value of 0 disables interleaving +
+
+__-inter__ (number, default: __0.5__): interleave file, producing track chunks with given duration in ms. A value of 0 disables interleaving +
+
__-old-inter__ (number): same as [-inter](#inter) but without drift correction +
+
__-tight__: tight interleaving (sample based) of the file. This reduces disk seek operations but increases file size -__-flat__: store file with all media data first, non-interleaved. This speeds up writing time when creating new files -__-frag__ (number): fragment file, producing track fragments of given duration in ms. This disables interleaving -__-out__ (string): specify ISOBMFF output file name. By default input file is overwritten +
+
+__-flat__: store file with all media data first, non-interleaved. This speeds up writing time when creating new files +
+
+__-frag__ (number): fragment file, producing track fragments of given duration in ms. This disables interleaving +
+
+__-out__ (string): specify ISOBMFF output file name. By default input file is overwritten +
+
__-co64__: force usage of 64-bit chunk offsets for ISOBMF files +
+
__-new__: force creation of a new destination file +
+
__-newfs__: force creation of a new destination file without temp file but interleaving support +
+
__-no-sys__,__-nosys__: remove all MPEG-4 Systems info except IOD, kept for profiles. This is the default when creating regular AV content +
+
__-no-iod__: remove MPEG-4 InitialObjectDescriptor from file +
+
__-mfra__: insert movie fragment random offset when fragmenting file (ignored in dash mode) +
+
__-isma__: rewrite the file as an ISMA 1.0 file +
+
__-ismax__: same as [-isma](#isma) and remove all clock references +
+
__-3gp__: rewrite as 3GPP(2) file (no more MPEG-4 Systems Info), always enabled if destination file extension is `.3gp`, `.3g2` or `.3gpp`. Some tracks may be removed in the process +
+
__-ipod__: rewrite the file for iPod/old iTunes +
+
__-psp__: rewrite the file for PSP devices +
+
__-brand__ (string): set major brand of file (`ABCD`) or brand with optional version (`ABCD:v`) +
+
__-ab__ (string): add given brand to file's alternate brand list +
+
__-rb__ (string): remove given brand to file's alternate brand list +
+
__-cprt__ (string): add copyright string to file +
+
__-chap__ (string): set chapter information from given file. The following formats are supported (but cannot be mixed) in the chapter text file: - ZoomPlayer: `AddChapter(nb_frames,chapter name)`, `AddChapterBySeconds(nb_sec,chapter name)` and `AddChapterByTime(h,m,s,chapter name)` with 1 chapter per line - Time codes: `h:m:s chapter_name`, `h:m:s:ms chapter_name` and `h:m:s.ms chapter_name` with 1 chapter per line - SMPTE codes: `h:m:s;nb_f/fps chapter_name` and `h:m:s;nb_f chapter_name` with `nb_f` the number of frames and `fps` the framerate with 1 chapter per line - Common syntax: `CHAPTERX=h:m:s[:ms or .ms]` on first line and `CHAPTERXNAME=name` on next line (reverse order accepted) +
+
__-chapqt__ (string): set chapter information from given file, using QT signaling for text tracks -__-set-track-id__ `tkID:id2`: change id of track to id2 -__-swap-track-id__ `tkID1:tkID1`: swap the id between tracks with id1 to id2 -__-rem__ (int): remove given track from file +
+
+__-set-track-id__ `tkID:id2`: change id of track to id2 +
+
+__-swap-track-id__ `tkID1:tkID1`: swap the id between tracks with id1 to id2 +
+
+__-rem__ (int): remove given track from file +
+
__-rap__ (int): remove all non-RAP samples from given track +
+
__-refonly__ (int): remove all non-reference pictures from given track -__-enable__ (int): enable given track -__-disable__ (int): disable given track -__-timescale__ (int, default: __600__): set movie timescale to given value (ticks per second) -__-lang__ `[tkID=]LAN`: set language. LAN is the BCP-47 code (eng, en-UK, ...). If no track ID is given, sets language to all tracks -__-delay__ `tkID=TIME`: set track start delay (>0) or initial skip (<0) in ms or in fractional seconds (`N/D`) +
+
+__-enable__ (int): enable given track +
+
+__-disable__ (int): disable given track +
+
+__-timescale__ (int, default: __600__): set movie timescale to given value (ticks per second) +
+
+__-lang__ `[tkID=]LAN`: set language. LAN is the BCP-47 code (eng, en-UK, ...). If no track ID is given, sets language to all tracks +
+
+__-delay__ `tkID=TIME`: set track start delay (>0) or initial skip (<0) in ms or in fractional seconds (`N/D`) +
+
__-par__ `tkID=PAR`: set visual track pixel aspect ratio. PAR is: - N:D: set PAR to N:D in track, do not modify the bitstream @@ -74,18 +141,32 @@ An option of type `boolean` expects no following value. - none: remove PAR info from track, do not modify the bitstream - auto: retrieve PAR info from bitstream and set it in track - force: force 1:1 PAR in track, do not modify the bitstream +
+
__-clap__ `tkID=CLAP`: set visual track clean aperture. CLAP is `Wn,Wd,Hn,Hd,HOn,HOd,VOn,VOd` or `none` - n, d: numerator, denominator - W, H, HO, VO: clap width, clap height, clap horizontal offset, clap vertical offset +
+
__-mx__ `tkID=MX`: set track matrix, with MX is M1:M2:M3:M4:M5:M6:M7:M8:M9 in 16.16 fixed point integers or hexa -__-kind__ `tkID=schemeURI=value`: set kind for the track or for all tracks using `all=schemeURI=value` -__-kind-rem__ `tkID=schemeURI=value`: remove kind if given schemeID for the track or for all tracks with `all=schemeURI=value` +
+
+__-kind__ `tkID=schemeURI=value`: set kind for the track or for all tracks using `all=schemeURI=value` +
+
+__-kind-rem__ `tkID=schemeURI=value`: remove kind if given schemeID for the track or for all tracks with `all=schemeURI=value` +
+
__-name__ `tkID=NAME`: set track handler name to NAME (UTF-8 string) +
+
__-tags__,__-itags__ (string): set iTunes tags to file, see `-h tags` +
+
__-group-add__ (string): create a new grouping information in the file. Format is a colon-separated list of following options: - refTrack=ID: track used as a group reference. If not set, the track will belong to the same group as the previous trackID specified. If 0 or no previous track specified, a new alternate group will be created @@ -98,12 +179,24 @@ An option of type `boolean` expects no following value. __Warning: Options modify state as they are parsed, `trackID=1:criteria=lang:trackID=2` is different from `criteria=lang:trackID=1:trackID=2`__ +
+
__-group-rem-track__ (int): remove given track from its group +
+
__-group-rem__ (int): remove the track's group +
+
__-group-clean__: remove all group information from all tracks +
+
__-ref__ `tkID:R4CC:refID`: add a reference of type R4CC from track ID to track refID (remove track reference if refID is 0) +
+
__-keep-utc__: keep UTC timing in the file after edit +
+
__-udta__ `tkID:[OPTS]`: set udta for given track or movie if tkID is 0. OPTS is a colon separated list of: - type=CODE: 4CC code of the UDTA (not needed for `box=` option) @@ -115,13 +208,25 @@ __Warning: Options modify state as they are parsed, `trackID=1:criteria=lang:tra _Note: If no source is set, UDTA of type CODE will be removed_ +
+
__-patch__ `[tkID=]FILE`: apply box patch described in FILE, for given trackID if set +
+
__-bo__: freeze the order of boxes in input file +
+
__-init-seg__ (string): use the given file as an init segment for dumping or for encryption +
+
__-zmov__: compress movie box according to ISOBMFF box compression or QT if mov extension +
+
__-xmov__: same as zmov and wraps ftyp in otyp -__-edits__ `tkID=EDITS`: set edit list. The following syntax is used (no separators between entries): +
+
+__-edits__ `tkID=EDITS`: set edit list. The following syntax is used (no separators between entries): - `r`: removes all edits - `eSTART`: add empty edit with given start time. START can be @@ -135,13 +240,24 @@ _Note: If no source is set, UDTA of type CODE will be removed_ - `re0-5e5-3,4`: remove edits, add empty edit at 0s for 5s, then add regular edit at 5s for 3s starting at 4s in media track - `re0-4,0,0.5`: remove edits, add single edit at 0s for 4s starting at 0s in media track and playing at speed 0.5 +
+
__-moovpad__ (int): specify amount of padding to keep after moov box for later inplace editing - if 0, moov padding is disabled +
+
__-no-inplace__: disable inplace rewrite +
+
__-hdr__ (string): update HDR information based on given XML, 'none' removes HDR info +
+
__-time__ `[tkID=]DAY/MONTH/YEAR-H:M:S`: set movie or track creation time +
+
__-mtime__ `tkID=DAY/MONTH/YEAR-H:M:S`: set media creation time +
# Encryption/Decryption Options @@ -150,11 +266,18 @@ It requires a specific XML file called `CryptFile`, whose syntax is available at Image files (HEIF) can also be crypted / decrypted, using CENC only. Options: -__-crypt__ (string): encrypt the input file using the given `CryptFile` -__-decrypt__ (string): decrypt the input file, potentially using the given `CryptFile`. If `CryptFile` is not given, will fail if the key management system is not supported -__-set-kms__ `tkID=kms_uri`: change ISMA/OMA KMS location for a given track or for all tracks if `all=` is used +
+__-crypt__ (string): encrypt the input file using the given `CryptFile` +
+
+__-decrypt__ (string): decrypt the input file, potentially using the given `CryptFile`. If `CryptFile` is not given, will fail if the key management system is not supported +
+
+__-set-kms__ `tkID=kms_uri`: change ISMA/OMA KMS location for a given track or for all tracks if `all=` is used +
# Help Options -__-h__ (string): print help +
+__-h__ (string): print help - general: general options help - hint: hinting options help @@ -176,19 +299,50 @@ Options: - cicp: print various CICP code points - VAL: search for option named `VAL` (without `-` or `--`) in MP4Box, libgpac core and all filters +
-__-hx__ (string): look for given string in name and descriptions of all MP4Box and filters options -__-nodes__: list supported MPEG4 nodes -__-nodex__: list supported MPEG4 nodes and print nodes -__-node__ (string): get given MPEG4 node syntax and QP infolist -__-xnodes__: list supported X3D nodes -__-xnodex__: list supported X3D nodes and print nodes -__-xnode__ (string): get given X3D node syntax -__-snodes__: list supported SVG nodes -__-languages__: list supported ISO 639 languages -__-boxes__: list all supported ISOBMF boxes and their syntax -__-stats__,__-fstat__: print filter session statistics (import/export/encrypt/decrypt/dashing) -__-graph__,__-fgraph__: print filter session graph (import/export/encrypt/decrypt/dashing) -__-v__: verbose mode -__-version__: get build version -__--__ `INPUT`: escape option if INPUT starts with `-` character +
+__-hx__ (string): look for given string in name and descriptions of all MP4Box and filters options +
+
+__-nodes__: list supported MPEG4 nodes +
+
+__-nodex__: list supported MPEG4 nodes and print nodes +
+
+__-node__ (string): get given MPEG4 node syntax and QP infolist +
+
+__-xnodes__: list supported X3D nodes +
+
+__-xnodex__: list supported X3D nodes and print nodes +
+
+__-xnode__ (string): get given X3D node syntax +
+
+__-snodes__: list supported SVG nodes +
+
+__-languages__: list supported ISO 639 languages +
+
+__-boxes__: list all supported ISOBMF boxes and their syntax +
+
+__-stats__,__-fstat__: print filter session statistics (import/export/encrypt/decrypt/dashing) +
+
+__-graph__,__-fgraph__: print filter session graph (import/export/encrypt/decrypt/dashing) +
+
+__-v__: verbose mode +
+
+__-version__: get build version +
+
+__--__ `INPUT`: escape option if INPUT starts with `-` character +
diff --git a/docs/MP4Box/mp4box-import-opts.md b/docs/MP4Box/mp4box-import-opts.md index 398b0db0..19da317e 100644 --- a/docs/MP4Box/mp4box-import-opts.md +++ b/docs/MP4Box/mp4box-import-opts.md @@ -39,12 +39,14 @@ The import file name may be set to empty or `self`, indicating that the import o Example ``` -add self:moovts=-1:noedit src.mp4 -``` +``` + This will apply `moovts` and `noedit` option to all tracks in src.mp4 Example ``` -add self#2:moovts=-1:noedit src.mp4 -``` +``` + This will apply `moovts` and `noedit` option to track with `ID=2` in src.mp4 Only per-file options marked with a `S` are possible in this mode. @@ -52,53 +54,126 @@ When importing an ISOBMFF/QT file, only options marked as `C` or `S` can be used Allowed per-file options: +
__dur__ (int): `XC` import only the specified duration from the media. Value can be: - positive float: specifies duration in seconds - fraction: specifies duration as NUM/DEN fraction - negative integer: specifies duration in number of coded frames +
+
__start__ (number): `C` target start time in source media, may not be supported depending on the source +
+
__lang__ (string): `S` set imported media language code +
+
__delay__ (int): `S` set imported media initial delay (>0) or initial skip (<0) in ms or as fractional seconds (`N/D`) +
+
__par__ (string): `S` set visual pixel aspect ratio (see [-par](mp4box-gen-opts/#par) ) +
+
__clap__ (string): `S` set visual clean aperture (see [-clap](mp4box-gen-opts/#clap) ) +
+
__mx__ (string): `S` set track matrix (see [-mx](mp4box-gen-opts/#mx) ) +
+
__name__ (string): `S` set track handler name +
+
__ext__ (string): override file extension when importing +
+
__hdlr__ (string): `S` set track handler type to the given code point (4CC) +
+
__stype__ (string): `S` force sample description type to given code point (4CC), may likely break the file +
+
__tkhd__ (int): `S` set track header flags has hex integer or as comma-separated list of `enable`, `movie`, `preview`, `size_ar` keywords (use `tkhd+=FLAGS` to add and `tkhd-=FLAGS` to remove) +
+
__disable__: `S` disable imported track(s), use `disable=no` to force enabling a disabled track +
+
__group__ (int): `S` add the track as part of the G alternate group. If G is 0, the first available GroupID will be picked +
+
__fps__ (string): `S` same as [-fps](#fps) +
+
__rap__: `DS` import only RAP samples +
+
__refs__: `DS` import only reference pictures +
+
__trailing__: keep trailing 0-bytes in AVC/HEVC samples +
+
__agg__ (int): `X` same as [-agg](#agg) +
+
__dref__: `XC` same as [-dref](#dref) +
+
__keep_refs__: `C` keep track reference when importing a single track +
+
__nodrop__: same as [-nodrop](#nodrop) +
+
__packed__: `X` same as [-packed](#packed) +
+
__sbr__: same as [-sbr](#sbr) +
+
__sbrx__: same as [-sbrx](#sbrx) +
+
__ovsbr__: same as [-ovsbr](#ovsbr) +
+
__ps__: same as [-ps](#ps) +
+
__psx__: same as [-psx](#psx) +
+
__asemode__ (string): `XS` set the mode to create the AudioSampleEntry. Value can be: - v0-bs: use MPEG AudioSampleEntry v0 and the channel count from the bitstream (even if greater than 2) - default - v0-2: use MPEG AudioSampleEntry v0 and the channel count is forced to 2 - v1: use MPEG AudioSampleEntry v1 and the channel count from the bitstream - v1-qt: use QuickTime Sound Sample Description Version 1 and the channel count from the bitstream (even if greater than 2). This will also trigger using alis data references instead of url, even for non-audio tracks +
+
__audio_roll__ (int): `S` add a roll sample group with roll_distance `N` for audio tracks +
+
__roll__ (int): `S` add a roll sample group with roll_distance `N` +
+
__proll__ (int): `S` add a preroll sample group with roll_distance `N` +
+
__mpeg4__: `X` same as [-mpeg4](#mpeg4) option +
+
__nosei__: discard all SEI messages during import +
+
__svc__: import SVC/LHVC with explicit signaling (no AVC base compatibility) +
+
__nosvc__: discard SVC/LHVC data when importing +
+
__svcmode__ (string): `DS` set SVC/LHVC import mode. Value can be: - split: each layer is in its own track @@ -106,75 +181,175 @@ __svcmode__ (string): `DS` set SVC/LHVC import mode. Value can be: - splitbase: all layers are merged in a track, and the AVC base in another - splitnox: each layer is in its own track, and no extractors are written - splitnoxib: each layer is in its own track, no extractors are written, using inband param set signaling +
+
__temporal__ (string): `DS` set HEVC/LHVC temporal sublayer import mode. Value can be: - split: each sublayer is in its own track - splitbase: all sublayers are merged in a track, and the HEVC base in another - splitnox: each layer is in its own track, and no extractors are written +
+
__subsamples__: add SubSample information for AVC+SVC +
+
__deps__: import sample dependency information for AVC and HEVC +
+
__ccst__: `S` add default HEIF ccst box to visual sample entry +
+
__forcesync__: force non IDR samples with I slices (OpenGOP or GDR) to be marked as sync points __Warning: RESULTING FILE IS NOT COMPLIANT WITH THE SPEC but will fix seeking in most players__ +
+
__xps_inband__: `XC` set xPS inband for AVC/H264 and HEVC (for reverse operation, re-import from raw media) +
+
__xps_inbandx__: `XC` same as xps_inband and also keep first xPS in sample description +
+
__au_delim__: keep AU delimiter NAL units in the imported file +
+
__max_lid__ (int): set HEVC max layer ID to be imported to `N` (by default imports all layers) +
+
__max_tid__ (int): set HEVC max temporal ID to be imported to `N` (by default imports all temporal sublayers) +
+
__tiles__: `S` add HEVC tiles signaling and NALU maps without splitting the tiles into different tile tracks +
+
__split_tiles__: `DS` split HEVC tiles into different tile tracks, one tile (or all tiles of one slice) per track +
+
__negctts__: `S` use negative CTS-DTS offsets (ISO4 brand). Use `negctts=no` to force using positive offset on existing track +
+
__chap__: `S` specify the track is a chapter track +
+
__chapter__ (string): `S` add a single chapter (old nero format) with given name lasting the entire file +
+
__chapfile__ (string): `S` add a chapter file (old nero format) +
+
__layout__ (string): `S` specify the track layout as `WxH[xXxY][xLAYER]`. If `W` (resp `H`) is 0, the max width (resp height) of the tracks in the file are used +
+
__rescale__ (int): `S` force media timescale to TS (int or fraction) and change the media duration +
+
__sampdur__ (int): `S` force all samples duration (`D`) or sample durations and media timescale (`D/TS`), used to patch CFR files with broken timings +
+
__timescale__ (int): `S` set imported media timescale to TS +
+
__moovts__ (int): `S` set movie timescale to TS. A negative value picks the media timescale of the first track imported +
+
__noedit__: `XS` do not set edit list when importing B-frames video tracks +
+
__rvc__ (string): `S` set RVC configuration for the media +
+
__fmt__ (string): override format detection with given format - disable data probing and force `ext` option on source +
+
__profile__ (int): `S` override AVC profile. Integer value, or `high444`, `high`, `extended`, `main`, `baseline` +
+
__level__ (int): `S` override AVC level, if value < 6, interpreted as decimal expression +
+
__compat__ (int): `S` force the profile compatibility flags for the H.264 content +
+
__novpsext__: remove VPS extensions from HEVC VPS +
+
__keepav1t__: keep AV1 temporal delimiter OBU in samples, might help if source file had losses +
+
__dlba__ (string): `S` force DolbyAtmos mode for EAC3. Value can be - no: disable Atmos signaling - auto: use Atmos signaling from first sample - N: force Atmos signaling using compatibility type index N +
+
__font__ (string): specify font name for text import (default `Serif`) +
+
__size__ (int): specify font size for text import (default `18`) +
+
__text_layout__ (string): specify the track text layout as WxHxXxY - if W (resp H) = 0: the max width (resp height) of the tracks in the file are used - if Y=-1: the layout is moved to the bottom of the track area - X and Y can be omitted: `:layout=WxH` +
+
__swf-global__: all SWF defines are placed in first scene replace rather than when needed +
+
__swf-no-ctrl__: use a single stream for movie control and dictionary (this will disable ActionScript) +
+
__swf-no-text__: remove all SWF text +
+
__swf-no-font__: remove all embedded SWF Fonts (local playback host fonts used) +
+
__swf-no-line__: remove all lines from SWF shapes +
+
__swf-no-grad__: remove all gradients from SWF shapes +
+
__swf-quad__: use quadratic bezier curves instead of cubic ones +
+
__swf-xlp__: support for lines transparency and scalability +
+
__swf-ic2d__: use indexed curve 2D hardcoded proto +
+
__swf-same-app__: appearance nodes are reused +
+
__swf-flatten__ (number): complementary angle below which 2 lines are merged, `0` means no flattening +
+
__kind__ (string): `S` set kind for the track as `schemeURI=value` +
+
__txtflags__ (int): set display flags (hexa number) of text track. Use `txtflags+=FLAGS` to add flags and `txtflags-=FLAGS` to remove flags +
+
__rate__ (int): force average rate and max rate to VAL (in bps) in btrt box. If 0, removes btrt box +
+
__stz2__: `S` use compact size table (for low-bitrates) +
+
__bitdepth__ (int): set bit depth to VAL for imported video content (default is 24) +
+
__colr__ (string): `S` set color profile for imported video content. Value is formatted as: - nclc,p,t,m: with `p` colour primary (int or string), `t` transfer characteristics (int or string) and `m` matrix coef (int or string), cf `-h cicp` @@ -182,73 +357,146 @@ __colr__ (string): `S` set color profile for imported video content. - prof,path: with path indicating the file containing the ICC color profile - rICC,path: with path indicating the file containing the restricted ICC color profile - 'none': removes color info +
+
__hdr__ (string): `S` set HDR info on track (see [-hdr](mp4box-gen-opts/#hdr) ), 'none' removes HDR info +
+
__dvp__,__-dv-profile__ (string): `S` set the Dolby Vision profile on imported track - Profile is an integer, or `none` to remove DV signaling - Profile can be suffixed with compatibility ID, e.g. `5.hdr10` - Allowed compatibility ID are `none`, `hdr10`, `bt709`, `hlg709`, `hlg2100`, `bt2020`, `brd`, or integer value as per DV spec - Profile can be prefixed with 'f' to force DV codec type signaling, e.g. `f8.2` +
+
__fullrange__ (string): `S` force the video fullrange type in VUI for the AVC|H264 content (value `yes`, `on` or `no`, `off`) +
+
__videofmt__ (string): `S` force the video format in VUI for AVC|H264 and HEVC content, value can be `component`, `pal`, `ntsc`, `secam`, `mac`, `undef` +
+
__colorprim__ (string): `S` force the colour primaries in VUI for AVC|H264 and HEVC (int or string, cf `-h cicp`) +
+
__colortfc__ (string): `S` force transfer characteristics in VUI for AVC|H264 and HEVC (int or string, cf `-h cicp`) +
+
__colormx__ (string): `S` force the matrix coefficients in VUI for the AVC|H264 and HEVC content (int or string, cf `-h cicp`) +
+
__tc__ (string): `S` inject a single QT timecode. Value is formatted as: - [d]FPS[/FPS_den],h,m,s,f[,framespertick]: optional drop flag, framerate (integer or fractional), hours, minutes, seconds and frame number - : `d` is an optional flag used to indicate that the counter is in drop-frame format - : the `framespertick` is optional and defaults to round(framerate); it indicates the number of frames per counter tick +
+
__edits__ (string): `S` override edit list, same syntax as [-edits](#edits) +
+
__lastsampdur__ (string): `S` set duration of the last sample. Value is formatted as: - no value: use the previous sample duration - integer: indicate the duration in milliseconds - N/D: indicate the duration as fractional second +
+
__ID__ (int): `S` set target ID - a value of 0 (default) will try to keep source track ID - a value of -1 will ignore source track ID - other value will try to set track ID to this value if no other track with same ID is present +
+
__tkgp__ (string): `S` assign track group to track. Value is formatted as `TYPE,N` with TYPE the track group type (4CC) and N the track group ID. A negative ID removes from track group ID -N +
+
__tkidx__ (string): `S` set track position in track list, 1 being first track in file +
+
__stats__,__-fstat__: `C` print filter session stats after import +
+
__graph__,__-fgraph__: `C` print filter session graph after import +
+
__sopt:[OPTS]__: set `OPTS` as additional arguments to source filter. `OPTS` can be any usual filter argument, see [filter doc `gpac -h doc`](Filters) +
+
__dopt:[OPTS]__: `X` set `OPTS` as additional arguments to [destination filter](mp4mx). OPTS can be any usual filter argument, see [filter doc `gpac -h doc`](Filters) +
+
__@f1[:args][@fN:args]__: set a filter chain to insert before the multiplexer. Each filter in the chain is formatted as a regular filter, see [filter doc `gpac -h doc`](Filters). A `@@` separator starts a new chain (see DASH help). The last filter in each chain shall not have any ID specified +
_Note: `sopt`, `dopt` and `@f` must be placed after all other options._ # Global import options -__-add__ (string): add given file tracks to file. Multiple inputs can be specified using `+`, e.g. `-add url1+url2` -__-cat__ (string): concatenate given file samples to file, creating tracks if needed. Multiple inputs can be specified using `+`, e.g/ `-cat url1+url2`. +
+__-add__ (string): add given file tracks to file. Multiple inputs can be specified using `+`, e.g. `-add url1+url2` +
+
+__-cat__ (string): concatenate given file samples to file, creating tracks if needed. Multiple inputs can be specified using `+`, e.g/ `-cat url1+url2`. _Note: This aligns initial timestamp of the file to be concatenated_ -__-catx__ (string): same as [-cat](#cat) but new tracks can be imported before concatenation by specifying `+ADD_COMMAND` where `ADD_COMMAND` is a regular [-add](#add) syntax -__-catpl__ (string): concatenate files listed in the given playlist file (one file per line, lines starting with # are comments). +
+
+__-catx__ (string): same as [-cat](#cat) but new tracks can be imported before concatenation by specifying `+ADD_COMMAND` where `ADD_COMMAND` is a regular [-add](#add) syntax +
+
+__-catpl__ (string): concatenate files listed in the given playlist file (one file per line, lines starting with # are comments). _Note: Each listed file is concatenated as if called with -cat_ -__-unalign-cat__: do not attempt to align timestamps of samples in-between tracks -__-force-cat__: skip media configuration check when concatenating file. +
+
+__-unalign-cat__: do not attempt to align timestamps of samples in-between tracks +
+
+__-force-cat__: skip media configuration check when concatenating file. __Warning: THIS MAY BREAK THE CONCATENATED TRACK(S)__ -__-keep-sys__: keep all MPEG-4 Systems info when using [-add](#add) and [-cat](#cat) (only used when adding IsoMedia files) -__-dref__: keep media data in original file using `data referencing`. The resulting file only contains the meta-data of the presentation (frame sizes, timing, etc...) and references media data in the original file. This is extremely useful when developing content, since importing and storage of the MP4 file is much faster and the resulting file much smaller. +
+
+__-keep-sys__: keep all MPEG-4 Systems info when using [-add](#add) and [-cat](#cat) (only used when adding IsoMedia files) +
+
+__-dref__: keep media data in original file using `data referencing`. The resulting file only contains the meta-data of the presentation (frame sizes, timing, etc...) and references media data in the original file. This is extremely useful when developing content, since importing and storage of the MP4 file is much faster and the resulting file much smaller. _Note: Data referencing may fail on some files because it requires the framed data (e.g. an IsoMedia sample) to be continuous in the original file, which is not always the case depending on the original interleaving or bitstream format (_AVC_ or _HEVC_ cannot use this option)_ -__-no-drop__,__-nodrop__: force constant FPS when importing AVI video -__-packed__: force packed bitstream when importing raw MPEG-4 part 2 Advanced Simple Profile -__-sbr__: backward compatible signaling of AAC-SBR -__-sbrx__: non-backward compatible signaling of AAC-SBR -__-ps__: backward compatible signaling of AAC-PS -__-psx__: non-backward compatible signaling of AAC-PS -__-ovsbr__: oversample SBR import (SBR AAC, PS AAC and oversampled SBR cannot be detected at import time) -__-fps__ (string): force frame rate for video and SUB subtitles import to the given value, expressed as a number, as `TS-inc` or `TS/inc`. +
+
+__-no-drop__,__-nodrop__: force constant FPS when importing AVI video +
+
+__-packed__: force packed bitstream when importing raw MPEG-4 part 2 Advanced Simple Profile +
+
+__-sbr__: backward compatible signaling of AAC-SBR +
+
+__-sbrx__: non-backward compatible signaling of AAC-SBR +
+
+__-ps__: backward compatible signaling of AAC-PS +
+
+__-psx__: non-backward compatible signaling of AAC-PS +
+
+__-ovsbr__: oversample SBR import (SBR AAC, PS AAC and oversampled SBR cannot be detected at import time) +
+
+__-fps__ (string): force frame rate for video and SUB subtitles import to the given value, expressed as a number, as `TS-inc` or `TS/inc`. _Note: For raw H263 import, default FPS is `15`, otherwise `25`. This is accepted for ISOBMFF import but `:rescale` option should be preferred_ -__-mpeg4__: force MPEG-4 sample descriptions when possible. For AAC, forces MPEG-4 AAC signaling even if MPEG-2 -__-agg__ (int): aggregate N audio frames in 1 sample (3GP media only, maximum value is 15) +
+
+__-mpeg4__: force MPEG-4 sample descriptions when possible. For AAC, forces MPEG-4 AAC signaling even if MPEG-2 +
+
+__-agg__ (int): aggregate N audio frames in 1 sample (3GP media only, maximum value is 15) +
diff --git a/docs/MP4Box/mp4box-meta-opts.md b/docs/MP4Box/mp4box-meta-opts.md index 94344433..d5606720 100644 --- a/docs/MP4Box/mp4box-meta-opts.md +++ b/docs/MP4Box/mp4box-meta-opts.md @@ -6,13 +6,16 @@ IsoMedia files can be used as generic meta-data containers, for examples storing These information can be stored at the file root level, as is the case for HEIF/IFF and MPEG-21 file formats, or at the movie or track level for a regular movie. -__-set-meta__ `ABCD[:tk=tkID]`: set meta box type, with `ABCD` the four char meta type (NULL or 0 to remove meta) +
+__-set-meta__ `ABCD[:tk=tkID]`: set meta box type, with `ABCD` the four char meta type (NULL or 0 to remove meta) - tk not set: use root (file) meta - tkID == 0: use moov meta - tkID != 0: use meta of given track +
-__-add-item__ (string): add resource to meta, with parameter syntax `file_path[:opt1:optN]` +
+__-add-item__ (string): add resource to meta, with parameter syntax `file_path[:opt1:optN]` - file_path `this` or `self`: item is the file itself - tk=tkID: meta location (file, moov, track) @@ -24,8 +27,10 @@ These information can be stored at the file root level, as is the case for HEIF/ - ref=4cc,id: reference of type 4cc to an other item (can be set multiple times) - group=id,type: indicate the id and type of an alternate group for this item - replace: replace existing item by new item +
-__-add-image__ (string): add the given file as HEIF image item, with parameter syntax `file_path[:opt1:optN]`. If `filepath` is omitted, source is the input MP4 file +
+__-add-image__ (string): add the given file as HEIF image item, with parameter syntax `file_path[:opt1:optN]`. If `filepath` is omitted, source is the input MP4 file - name, id, ref: see [-add-item](#add-item) - primary: indicate that this item should be the primary item @@ -57,20 +62,39 @@ These information can be stored at the file root level, as is the case for HEIF/ - auxt=URN: mark image as auxiliary using given `URN` - auxd=FILE: use data from `FILE` as auxiliary extensions (cf `auxC` box) - any other options will be passed as options to the media importer, see [-add](#add) +
-__-add-derived-image__ (string): create an image grid, overlay or identity item, with parameter syntax `:type=(grid|iovl|iden)[:opt1:optN]` +
+__-add-derived-image__ (string): create an image grid, overlay or identity item, with parameter syntax `:type=(grid|iovl|iden)[:opt1:optN]` - image-grid-size=rxc: set the number of rows and columns of the grid - image-overlay-offsets=h,v[,h,v]*: set the horizontal and vertical offsets of the images in the overlay - image-overlay-color=r,g,b,a: set the canvas color of the overlay [0-65535] - any other options from [-add-image](#add-image) can be used +
-__-rem-item__,__-rem-image__ `item_ID[:tk=tkID]`: remove resource from meta -__-set-primary__ `item_ID[:tk=tkID]`: set item as primary for meta -__-set-xml__ `xml_file_path[:tk=tkID][:binary]`: set meta XML data -__-rem-xml__ `[tk=tkID]`: remove meta XML data -__-dump-xml__ `file_path[:tk=tkID]`: dump meta XML to file -__-dump-item__ `item_ID[:tk=tkID][:path=fileName]`: dump item to file -__-package__ (string): package input XML file into an ISO container, all media referenced except hyperlinks are added to file -__-mgt__ (string): package input XML file into an MPEG-U widget with ISO container, all files contained in the current folder are added to the widget package +
+__-rem-item__,__-rem-image__ `item_ID[:tk=tkID]`: remove resource from meta +
+
+__-set-primary__ `item_ID[:tk=tkID]`: set item as primary for meta +
+
+__-set-xml__ `xml_file_path[:tk=tkID][:binary]`: set meta XML data +
+
+__-rem-xml__ `[tk=tkID]`: remove meta XML data +
+
+__-dump-xml__ `file_path[:tk=tkID]`: dump meta XML to file +
+
+__-dump-item__ `item_ID[:tk=tkID][:path=fileName]`: dump item to file +
+
+__-package__ (string): package input XML file into an ISO container, all media referenced except hyperlinks are added to file +
+
+__-mgt__ (string): package input XML file into an MPEG-U widget with ISO container, all files contained in the current folder are added to the widget package +
diff --git a/docs/MP4Box/mp4box-other-opts.md b/docs/MP4Box/mp4box-other-opts.md index c0830837..4ab90555 100644 --- a/docs/MP4Box/mp4box-other-opts.md +++ b/docs/MP4Box/mp4box-other-opts.md @@ -7,24 +7,60 @@ MP4Box supports creation of hint tracks for RTSP servers supporting these such a _Note: GPAC streaming tools [rtp output](rtpout) and [rtsp server](rtspout) do not use hint tracks, they use on-the-fly packetization from any media sources, not just MP4_ Options: -__-hint__: hint the file for RTP/RTSP -__-mtu__ (int, default: __1450__): specify RTP MTU (max size) in bytes (this includes 12 bytes RTP header) -__-copy__: copy media data to hint track rather than reference (speeds up server but takes much more space) -__-multi__ `[maxptime]`: enable frame concatenation in RTP packets if possible (with max duration 100 ms or `maxptime` ms if given) -__-rate__ (int, default: __90000__): specify rtp rate in Hz when no default for payload -__-mpeg4__: force MPEG-4 generic payload whenever possible -__-latm__: force MPG4-LATM transport for AAC streams -__-static__: enable static RTP payload IDs whenever possible (by default, dynamic payloads are always used) -__-add-sdp__ (string): add given SDP string to movie (`string`) or track (`tkID:string`), `tkID` being the track ID or the hint track ID -__-no-offset__: signal no random offset for sequence number and timestamp (support will depend on server) -__-unhint__: remove all hinting information from file -__-group-single__: put all tracks in a single hint group -__-ocr__: force all MPEG-4 streams to be synchronized (MPEG-4 Systems only) -__-rap__: signal random access points in RTP packets (MPEG-4 Systems) -__-ts__: signal AU Time Stamps in RTP packets (MPEG-4 Systems) -__-size__: signal AU size in RTP packets (MPEG-4 Systems) -__-idx__: signal AU sequence numbers in RTP packets (MPEG-4 Systems) -__-iod__: prevent systems tracks embedding in IOD (MPEG-4 Systems), not compatible with [-isma](#isma) +
+__-hint__: hint the file for RTP/RTSP +
+
+__-mtu__ (int, default: __1450__): specify RTP MTU (max size) in bytes (this includes 12 bytes RTP header) +
+
+__-copy__: copy media data to hint track rather than reference (speeds up server but takes much more space) +
+
+__-multi__ `[maxptime]`: enable frame concatenation in RTP packets if possible (with max duration 100 ms or `maxptime` ms if given) +
+
+__-rate__ (int, default: __90000__): specify rtp rate in Hz when no default for payload +
+
+__-mpeg4__: force MPEG-4 generic payload whenever possible +
+
+__-latm__: force MPG4-LATM transport for AAC streams +
+
+__-static__: enable static RTP payload IDs whenever possible (by default, dynamic payloads are always used) +
+
+__-add-sdp__ (string): add given SDP string to movie (`string`) or track (`tkID:string`), `tkID` being the track ID or the hint track ID +
+
+__-no-offset__: signal no random offset for sequence number and timestamp (support will depend on server) +
+
+__-unhint__: remove all hinting information from file +
+
+__-group-single__: put all tracks in a single hint group +
+
+__-ocr__: force all MPEG-4 streams to be synchronized (MPEG-4 Systems only) +
+
+__-rap__: signal random access points in RTP packets (MPEG-4 Systems) +
+
+__-ts__: signal AU Time Stamps in RTP packets (MPEG-4 Systems) +
+
+__-size__: signal AU size in RTP packets (MPEG-4 Systems) +
+
+__-idx__: signal AU sequence numbers in RTP packets (MPEG-4 Systems) +
+
+__-iod__: prevent systems tracks embedding in IOD (MPEG-4 Systems), not compatible with [-isma](#isma) +
# Tagging support @@ -65,7 +101,8 @@ To force a positive integer to use signed storage, add `+` in front of the numbe Example ``` -tags io.gpac.some_tag=s+32 -``` +``` + This will force storing value `32` in signed 16 bit format. The `tag_value` can also be formatted as: diff --git a/docs/MP4Box/mp4box-scene-opts.md b/docs/MP4Box/mp4box-scene-opts.md index 28ba79bd..80066bfc 100644 --- a/docs/MP4Box/mp4box-scene-opts.md +++ b/docs/MP4Box/mp4box-scene-opts.md @@ -15,37 +15,87 @@ Commands with a timing of 0 in the input will modify the carousel version only ( Commands with a timing different from 0 in the input will generate new AUs. Options: -__-mp4__: specify input file is for BIFS/LASeR encoding -__-def__: encode DEF names in BIFS -__-sync__ (int): force BIFS sync sample generation every given time in ms (cannot be used with [-shadow](#shadow) or [-carousel](#carousel) ) -__-shadow__ (int): force BIFS sync shadow sample generation every given time in ms (cannot be used with [-sync](#sync) or [-carousel](#carousel) ) -__-carousel__ (int): use BIFS carousel (cannot be used with [-sync](#sync) or [-shadow](#shadow) ) -__-sclog__: generate scene codec log file if available -__-ms__ (string): import tracks from the given file -__-ctx-in__ (string): specify initial context (MP4/BT/XMT) file for chunk processing. Input file must be a commands-only file -__-ctx-out__ (string): specify storage of updated context (MP4/BT/XMT) file for chunk processing, optional -__-resolution__ (int): resolution factor (-8 to 7, default 0) for LASeR encoding, and all coordinates are multiplied by `2^res` before truncation (LASeR encoding) -__-coord-bits__ (int): number of bits used for encoding truncated coordinates (0 to 31, default 12) (LASeR encoding) -__-scale-bits__ (int): extra bits used for encoding truncated scales (0 to 4, default 0) (LASeR encoding) -__-auto-quant__ (int): resolution is given as if using [-resolution](#resolution) but coord-bits and scale-bits are inferred (LASeR encoding) -__-global-quant__ (int): resolution is given as if using [-resolution](#resolution) but the res is inferred (BIFS encoding) +
+__-mp4__: specify input file is for BIFS/LASeR encoding +
+
+__-def__: encode DEF names in BIFS +
+
+__-sync__ (int): force BIFS sync sample generation every given time in ms (cannot be used with [-shadow](#shadow) or [-carousel](#carousel) ) +
+
+__-shadow__ (int): force BIFS sync shadow sample generation every given time in ms (cannot be used with [-sync](#sync) or [-carousel](#carousel) ) +
+
+__-carousel__ (int): use BIFS carousel (cannot be used with [-sync](#sync) or [-shadow](#shadow) ) +
+
+__-sclog__: generate scene codec log file if available +
+
+__-ms__ (string): import tracks from the given file +
+
+__-ctx-in__ (string): specify initial context (MP4/BT/XMT) file for chunk processing. Input file must be a commands-only file +
+
+__-ctx-out__ (string): specify storage of updated context (MP4/BT/XMT) file for chunk processing, optional +
+
+__-resolution__ (int): resolution factor (-8 to 7, default 0) for LASeR encoding, and all coordinates are multiplied by `2^res` before truncation (LASeR encoding) +
+
+__-coord-bits__ (int): number of bits used for encoding truncated coordinates (0 to 31, default 12) (LASeR encoding) +
+
+__-scale-bits__ (int): extra bits used for encoding truncated scales (0 to 4, default 0) (LASeR encoding) +
+
+__-auto-quant__ (int): resolution is given as if using [-resolution](#resolution) but coord-bits and scale-bits are inferred (LASeR encoding) +
+
+__-global-quant__ (int): resolution is given as if using [-resolution](#resolution) but the res is inferred (BIFS encoding) +
# Live Scene Encoder Options The options shall be specified as `opt_name=opt_val.` Options: -__-live__: enable live BIFS/LASeR encoder -__-dst__ (string): destination IP -__-port__ (int, default: __7000__): destination port -__-mtu__ (int, default: __1450__): path MTU for RTP packets -__-ifce__ (string): IP address of the physical interface to use -__-ttl__ (int, default: __1__): time to live for multicast packets -__-sdp__ (string, default: __session.sdp__): output SDP file -__-dims__: turn on DIMS mode for SVG input -__-no-rap__: disable RAP sending and carousel generation -__-src__ (string): source of scene updates -__-rap__ (int): duration in ms of base carousel; you can specify the RAP period of a single ESID (not in DIMS) using `ESID=X:time` +
+__-live__: enable live BIFS/LASeR encoder +
+
+__-dst__ (string): destination IP +
+
+__-port__ (int, default: __7000__): destination port +
+
+__-mtu__ (int, default: __1450__): path MTU for RTP packets +
+
+__-ifce__ (string): IP address of the physical interface to use +
+
+__-ttl__ (int, default: __1__): time to live for multicast packets +
+
+__-sdp__ (string, default: __session.sdp__): output SDP file +
+
+__-dims__: turn on DIMS mode for SVG input +
+
+__-no-rap__: disable RAP sending and carousel generation +
+
+__-src__ (string): source of scene updates +
+
+__-rap__ (int): duration in ms of base carousel; you can specify the RAP period of a single ESID (not in DIMS) using `ESID=X:time` +
Runtime options: @@ -64,14 +114,36 @@ MP4Box can import simple Macromedia Flash files (".SWF") You can specify a SWF input file with '-bt', '-xmt' and '-mp4' options Options: -__-global__: all SWF defines are placed in first scene replace rather than when needed -__-no-ctrl__: use a single stream for movie control and dictionary (this will disable ActionScript) -__-no-text__: remove all SWF text -__-no-font__: remove all embedded SWF Fonts (local playback host fonts used) -__-no-line__: remove all lines from SWF shapes -__-no-grad__: remove all gradients from swf shapes -__-quad__: use quadratic bezier curves instead of cubic ones -__-xlp__: support for lines transparency and scalability -__-ic2d__: use indexed curve 2D hardcoded proto -__-same-app__: appearance nodes are reused -__-flatten__ (number): complementary angle below which 2 lines are merged, value `0` means no flattening +
+__-global__: all SWF defines are placed in first scene replace rather than when needed +
+
+__-no-ctrl__: use a single stream for movie control and dictionary (this will disable ActionScript) +
+
+__-no-text__: remove all SWF text +
+
+__-no-font__: remove all embedded SWF Fonts (local playback host fonts used) +
+
+__-no-line__: remove all lines from SWF shapes +
+
+__-no-grad__: remove all gradients from swf shapes +
+
+__-quad__: use quadratic bezier curves instead of cubic ones +
+
+__-xlp__: support for lines transparency and scalability +
+
+__-ic2d__: use indexed curve 2D hardcoded proto +
+
+__-same-app__: appearance nodes are reused +
+
+__-flatten__ (number): complementary angle below which 2 lines are merged, value `0` means no flattening +
diff --git a/docs/Player/BIFS-Implementation-Status.md b/docs/Player/BIFS-Implementation-Status.md index f98489c9..4fde74e1 100644 --- a/docs/Player/BIFS-Implementation-Status.md +++ b/docs/Player/BIFS-Implementation-Status.md @@ -1,3 +1,13 @@ +--- +tags: +- scene +- box +- group +- mpeg +--- + + + The following table is a detailed listing of supported MPEG-4 nodes in GPAC. This is not a bug tracker page, in other words it is quite possible that some nodes listed as supported have strange behaviors. In such a case please report on [our tracker](https://github.com/gpac/gpac/issues). diff --git a/docs/Player/Deferred-rendering-in-GPAC.md b/docs/Player/Deferred-rendering-in-GPAC.md index cb0a0833..e551e224 100644 --- a/docs/Player/Deferred-rendering-in-GPAC.md +++ b/docs/Player/Deferred-rendering-in-GPAC.md @@ -1,3 +1,18 @@ +--- +tags: +- mp4 +- sample +- isomedia +- compression +- isobmff +- frame +- compositor +- codec +- h264 +--- + + + The GPAC compositor can render content in a special mode allowing to debug deferred rendering in 2D. In this mode, only the rectangular regions of the window that have changed since the previous frame are drawn in each frame. To enable this mode, you need to modify the GPAC configuration file, by setting `mode2d` to `debug` in the `filter@compositor` section, or using `--mode2d=debug`. diff --git a/docs/Player/GPAC-10bit-support.md b/docs/Player/GPAC-10bit-support.md index 927f9af7..c0e195ef 100644 --- a/docs/Player/GPAC-10bit-support.md +++ b/docs/Player/GPAC-10bit-support.md @@ -1,3 +1,13 @@ +--- +tags: +- option +- opengl +- decoding +- output +--- + + + GPAC supports 10bit display and 10bit video decoding. The support requires a graphics card capable of driving a 10 bit display; this support is usually enabled via the control application of your GPU. Do not worry, 10-bit video will still show in 8 bit if your graphics card doesn't handle 10 bit output ! diff --git a/docs/Player/Playback.md b/docs/Player/Playback.md index 74a3d720..2dbaf242 100644 --- a/docs/Player/Playback.md +++ b/docs/Player/Playback.md @@ -1,3 +1,22 @@ +--- +tags: +- source +- session +- input +- media +- data +- stream +- compositor +- output +- filter +- bitstream +- sequence +- bifs +- track +--- + + + # Introduction GPAC can playback content in two main ways: diff --git a/docs/Player/Player-Features.md b/docs/Player/Player-Features.md index c47c98bc..62264f98 100644 --- a/docs/Player/Player-Features.md +++ b/docs/Player/Player-Features.md @@ -1,4 +1,54 @@ -# Foreword +--- +tags: +- mpd +- ffmpeg +- data +- webvtt +- codec +- filter +- session +- compression +- frame +- raw +- xml +- stream +- encode +- bitstream +- hevc +- sequence +- dump +- scene +- opengl +- block +- media +- segment +- compositor +- isobmff +- decoder +- group +- h264 +- chunk +- track +- profile +- mp4 +- graph +- source +- chain +- input +- isomedia +- binary +- output +- decoding +- mpeg +- sink +- dash +- bifs +- encoder +--- + + + +# 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. @@ -63,7 +113,7 @@ The media stream composition (renderer) is performed by the [Compositor](composi - Dynamic insertion/update/removal of objects and streams - Inline scene support (local or remote) with MediaControl/MediaSensor support - ## Audio rendering +## Audio rendering - Multichannel support - Integer up/down sampling with mediaSpeed handling in 8, 16, 24, 32 bit or 32 floating point - Multichannel to stereo mapper @@ -106,31 +156,32 @@ Any possible input from GPAC filter architecture is supported by the player. Thi - 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 + - 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) + - 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 # Available plugins + ## Audio output - Microsoft DirectSound (with multichannel support) - Microsoft WaveOut diff --git a/docs/Player/Player.md b/docs/Player/Player.md index 0536a761..c73b5745 100644 --- a/docs/Player/Player.md +++ b/docs/Player/Player.md @@ -1,4 +1,27 @@ -# Overview +--- +tags: +- mp4 +- source +- session +- input +- media +- isomedia +- data +- isobmff +- raw +- stream +- mpeg +- filter +- bitstream +- compositor +- sequence +- bifs +- track +--- + + + +# 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. diff --git a/docs/Player/SVG-Implementation-Status.md b/docs/Player/SVG-Implementation-Status.md index fdf87686..b9a14ded 100644 --- a/docs/Player/SVG-Implementation-Status.md +++ b/docs/Player/SVG-Implementation-Status.md @@ -1,3 +1,18 @@ +--- +tags: +- scene +- graph +- source +- input +- data +- compositor +- xml +- property +- bifs +--- + + + # 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. diff --git a/docs/Player/Some-fun-with-multiview-rendering-on-3D-screens.md b/docs/Player/Some-fun-with-multiview-rendering-on-3D-screens.md index a365806f..26dfffa1 100644 --- a/docs/Player/Some-fun-with-multiview-rendering-on-3D-screens.md +++ b/docs/Player/Some-fun-with-multiview-rendering-on-3D-screens.md @@ -1,6 +1,32 @@ +--- +tags: +- heif +- data +- filter +- frame +- stream +- bitstream +- sequence +- dump +- scene +- opengl +- media +- compositor +- track +- option +- mp4 +- source +- output +- mpeg +- sink +--- + + + GPAC can support various output type and view number, but requires OpenGL to do so. -Warning, multi-view rendering is a costly operation. The scene gets rendered multiple times, and you will need a decent graphic card to try that, especially support for [VBO](http://en.wikipedia.org/wiki/Vertex_Buffer_Object)s to avoid sending the geometry data repeatedly, and OpenGL shaders for most screen configurations. +!!! warning + Multi-view rendering is a costly operation. The scene gets rendered multiple times, and you will need a decent graphic card to try that, especially support for [VBO](http://en.wikipedia.org/wiki/Vertex_Buffer_Object)s to avoid sending the geometry data repeatedly, and OpenGL shaders for most screen configurations. The output type is selected in GPAC configuration file by the following keys diff --git a/docs/Player/X3D-Implementation-Status.md b/docs/Player/X3D-Implementation-Status.md index 82e299b8..8b554c2f 100644 --- a/docs/Player/X3D-Implementation-Status.md +++ b/docs/Player/X3D-Implementation-Status.md @@ -1,3 +1,12 @@ +--- +tags: +- box +- group +- bifs +--- + + + The following table is a detailed listing of supported X3D nodes in GPAC. This is not a bug tracker page, in other words it is quite possible that some nodes listed as supported have strange behaviors. In such a case please report on [our tracker](https://github.com/gpac/gpac/issues). diff --git a/docs/Player/filters-playback.md b/docs/Player/filters-playback.md index 207e2d21..19268359 100644 --- a/docs/Player/filters-playback.md +++ b/docs/Player/filters-playback.md @@ -1,4 +1,28 @@ -# Overview +--- +tags: +- option +- mp4 +- graph +- source +- session +- input +- media +- isomedia +- data +- isobmff +- stream +- output +- filter +- buffer +- sink +- rebuffer +- track +- dump +--- + + + +# Overview {: data-level="all"} We discuss here how to work with audio and video outputs in GPAC in filter chains, we do not discuss media playback through [GPAC player](player). diff --git a/docs/Player/olay-composition.md b/docs/Player/olay-composition.md index 9ff60085..af6c0c22 100644 --- a/docs/Player/olay-composition.md +++ b/docs/Player/olay-composition.md @@ -1,4 +1,35 @@ -# Overview +--- +tags: +- pid +- reframer +- data +- overlay +- filter +- pipe +- sample +- pipeline +- frame +- raw +- stream +- avmix +- dump +- scene +- media +- compositor +- mp4 +- source +- packets +- chain +- input +- output +- sink +- dash +- bifs +--- + + + +# Overview {: data-level="all"} We discuss here how to use GPAC's compositor for complex scenes or simple AV as a filter rather than the player. diff --git a/docs/data/keywords.json b/docs/data/keywords.json new file mode 100644 index 00000000..dec41034 --- /dev/null +++ b/docs/data/keywords.json @@ -0,0 +1,613 @@ +{ + "definitions": { + "SOURCE": { + "description": "In GPAC, a source is an input element that provides media data to be processed. It is typically the starting point of a media processing pipeline.", + "level": "beginner", + "aliases": [ + "INPUT" + ], + "category": ["Media Processing "] + }, + "SINK": { + "description": "A sink in GPAC is an output element that receives processed media data. It is usually the endpoint of a media processing pipeline.", + "level": "beginner", + "aliases": [ + "OUTPUT" + ], + "category": "Media Processing " + }, + "INPUT": { + "description": "An input refers to any data fed into the GPAC processing system, including video, audio, and other multimedia streams.", + "level": "beginner", + "aliases": [ + "SOURCE" + ], + "category": "Media Processing" + }, + "OUTPUT": { + "description": "Output in GPAC refers to the processed data that is generated after media processing, ready for storage or display.", + "level": "beginner", + "aliases": [ + "SINK" + ], + "category": "Media Processing " + }, + "PID": { + "description": "PID stands for Packet Identifier. It is used in GPAC to uniquely identify different streams within a media file, such as audio, video, and subtitles.", + "level": "expert", + "aliases": [ + "PACKET IDENTIFIER" + ], + "category": "Data Structures and Formats " + }, + "PACKET": { + "description": "Packets is unit of data transmitted over a network or stored in a media file. In GPAC, packets are processed to extract media streams.", + "level": "beginner", + "category": "Data Structures and Formats " + }, + "DATA": { + "description": "Data in GPAC refers to the raw media content, including video frames, audio samples, and subtitles, that is processed and manipulated.", + "level": "beginner", + "aliases": [ + "MEDIA" + ], + "category": "Data Structures and Formats " + }, + "STREAM": { + "description": "A stream is a sequence of media data (audio, video, etc.) that is processed by GPAC. Streams are identified by PIDs and can be multiplexed or demultiplexed.", + "level": "beginner", + "aliases": [ + "MEDIA", + "TRACK" + ], + "category": "Streaming Technologies" + }, + "MEDIA": { + "description": "Media refers to various types of content such as video, audio, and images. GPAC processes different media types to enable playback, editing, and streaming.", + "level": "beginner", + "aliases": [ + "DATA", + "STREAM" + ], + "category": "Media Processing" + }, + "FRAME": { + "description": "A frame is a single image in a sequence of images that make up a video. GPAC processes frames during video encoding and decoding.", + "level": "beginner", + "aliases": [ + "IMAGE" + ], + "category": "Data Structures and Formats " + }, + "PROPERTY": { + "description": "Properties in GPAC refer to attributes of media streams or filters, such as resolution, bitrate, and codec type, that affect processing.", + "level": "expert", + "aliases": [ + "ATTRIBUTE" + ], + "category": "GPAC Core " + }, + "CODEC": { + "description": "A codec is a software or hardware tool that encodes or decodes media data. GPAC supports various codecs for compressing and decompressing media streams.", + "level": "beginner", + "aliases": [ + "AVC", + "HEVC", + "AAC", + "MP3", + "AAC", + "VORBIS" + ], + "category": "Codecs and Compression" + }, + "SESSION": { + "description": "A session in GPAC is a context for managing the lifecycle of media processing tasks, including loading, configuring, and executing filters.", + "level": "expert", + "category": "GPAC Core " + }, + "LINK": { + "description": "Links in GPAC connect different filters and processing elements, forming a processing chain or graph. They facilitate the flow of media data.", + "level": "beginner", + "aliases": [ + "CONNECTION" + ], + "category": "GPAC Core " + }, + "REMUX": { + "description": "Remuxing is the process of taking encoded media streams from one container format and repackaging them into another container format without altering the actual media data.", + "level": "beginner", + "aliases": [ + "REMUXING" + ], + "category": "Media Processing " + }, + "CHAIN": { + "description": "A chain in GPAC is a sequence of connected filters that process media data in a specific order. Chains define the processing pipeline.", + "level": "beginner", + "aliases": [ + "PIPELINE","PIPE" + ], + "category": "GPAC Core" + }, + "GRAPH": { + "description": "A graph in GPAC represents the entire media processing workflow, consisting of nodes (filters) and edges (connections) that define data flow.", + "level": "all", + "aliases": [ + + ], + + "category": "GPAC Core " + }, + "DECODING": { + "description": "Decoding is the process of converting compressed media data back into its original format. GPAC uses various codecs to decode audio and video streams.", + "level": "beginner", + "aliases": [ + "DEC","FFDEC","AACD","MP3D" + ], + "category": "Codecs and Compression" + }, + "REFRAMER": { + "description": "A reframer in GPAC adjusts the timing and structure of media frames to meet specific requirements, such as alignment for streaming.", + "level": "expert", + + "category": "Media Processing" + }, + "ENCRYPT": { + "description": "Encryption in GPAC refers to the process of securing media content by converting it into a code to prevent unauthorized access. GPAC supports various encryption standards like CENC and ISMA.", + "level": "expert", + "aliases": [ + "ENCRYPTION","CRYPT","ENC" + ], + "category": "Security and Encryption" + }, + "ENCODE": { + "description": "Encoding in GPAC is the process of converting raw media data into a compressed format using codecs. This is essential for reducing file sizes and preparing media for streaming or storage.", + "level": "beginner", + "aliases": [ + "ENC","FFENC","X264","X265","AAC","LIBOPUS" + ], + "category": "Codecs and Compression" + }, + "MP4": { + "description": "MP4 is a standardized multimedia file format for storing video, audio, subtitles and still images. It is widely used for streaming and media storage.", + "level": "beginner", + "aliases": [ + "MOV", + "ISO", + "ISOBMFF" + ], + "category": "File Formats and Containers" + }, + "FILTER": { + "description": "In GPAC, a filter is a processing unit that consumes and produces data packets. Filters can be chained together to form a media processing pipeline.", + "level": "all", + "category": "GPAC Core" + }, + "TRACK": { + "description": "A track is a single stream of media data, such as audio or video, within a multimedia file.", + "level": "beginner", + "aliases": [ + "STREAM" + ], + "category": "Data Structures and Formats" + }, + "CHUNK": { + "description": "A chunk is a portion of media data used for storage and transmission. Chunks are relatively small blocks of data that can be used to divide larger multimedia files into more manageable parts.", + "level": "beginner", + "aliases": [ + "SEGMENT" + ], + "category": "Data Structures and Formats" + }, + "SEGMENT": { + "description": "A segment is a timed portion of a media file used primarily in adaptive streaming protocols like DASH and HLS. Each segment represents a specific time interval of the media content, allowing for dynamic adaptation to network conditions.", + "level": "beginner", + "aliases": [ + "CHUNK","SEG" + ], + "category": "Streaming Technologies" + }, + "SAMPLE": { + "description": "A sample is an individual unit of audio or video data used in encoding and decoding processes.", + "level": "beginner", + "aliases": [ + "FRAME" + ], + "category": "Data Structures and Formats" + }, + "MPEG": { + "description": "MPEG (Moving Picture Experts Group) is a working group that sets standards for audio and video compression and transmission.", + "level": "all", + "aliases": [ + "H264", + "HEVC" + ], + "category": "Standards and Specifications" + }, + "TILE": { + "description": "A tile is a portion of a video frame, often used in advanced video coding techniques like HEVC.", + "level": "expert", + "aliases": [ + "BLOCK" + ], + "category": "Data Structures and Formats" + }, + "HEVC": { + "description": "HEVC (High Efficiency Video Coding) is a video compression standard designed as a successor to the widely used AVC (H.264).", + "level": "beginner", + "aliases": [ + "CODEC" + ], + "category": "Codecs and Compression" + }, + "PIPE": { + "description": "A pipe is a method of inter-process communication that allows data to flow from one process to another.", + "level": "beginner", + "aliases": [ + "PIPELINE" + ], + "category": "Networking and Protocols" + }, + "DUMP": { + "description": "A dump in GPAC refers to the process of outputting raw media data to a file or stream.", + "level": "beginner", + "aliases": [ + "OUTPUT" + ], + "category": "Tools and Utilities" + }, + "ISOBMFF": { + "description": "ISOBMF (ISO Base Media File Format) is a file format that forms the basis for many other file formats, such as MP4 and MOV.", + "level": "all", + "aliases": [ + "MP4", + "MOV" + ], + "category": "File Formats and Containers" + }, + "RTCP": { + "description": "RTCP (Real-Time Control Protocol) is a companion protocol to RTP (Real-Time Protocol) that provides out-of-band control information for an RTP flow. It is primarily used for quality of service (QoS) monitoring and to convey information about participants in ongoing RTP sessions.", + "level": "beginner", + "aliases": [ + "REAL-TIME CONTROL PROTOCOL", + "RTP CONTROL PROTOCOL" + ], + "category": "Networking and Protocols" + }, + "TIMESHIFT" :{ + "description": "Timeshift refers to the capability of a media player or streaming service to pause, rewind, or fast-forward live broadcast content. This feature allows users to view content on their own schedule without missing any part of the broadcast.", + "level": "beginner", + "aliases": [ + "LIVE PAUSE", + "DELAYED VIEWING" + ], + "category": "Streaming Technologies" + }, + "BITSTREAM": { + "description": "A bitstream is a sequence of bits that represent encoded media data.", + "level": "beginner", + "aliases": [ + "STREAM" + ], + "category": "Streaming Technologies" + }, + "SEQUENCE": { + "description": "A sequence in GPAC refers to a series of frames or samples that are processed together.", + "level": "all", + "aliases": [ + "STREAM" + ], + "category": "Data Structures and Formats" + }, + "COMPOSITOR": { + "description": "The compositor in GPAC is a filter used for rendering video and graphics, managing the display of visual elements.", + "level": "expert", + "category": "Graphics and Rendering" + }, + "FFMPEG": { + "description": "FFmpeg is a free and open-source project consisting of a vast software suite for handling video, audio, and other multimedia files and streams.", + "level": "all", + "aliases": [ + "FFENC","FFDEC" + ], + "category": "Libraries and Dependencies ", + "url":"https://www.ffmpeg.org/documentation.html" + }, + "BIFS": { + "description": "BIFS (Binary Format for Scenes) is a binary format used to represent and encode multimedia scenes, part of the MPEG-4 standard.", + "level": "expert", + "aliases": [ + "X3D" + ], + "category": "Standards and Specifications" + }, + "H264": { + "description": "H.264 is a widely used video compression standard that allows for high-quality video at lower bitrates.", + "level": "all", + "aliases": [ + "AVC" + ], + "category": "Codecs and Compression" + }, + "BLOCK": { + "description": "A block is a chunk of media data processed as a unit in encoding and decoding.", + "level": "beginner", + "aliases": [ + "CHUNK","SEGMENT" + ], + "category": "Data Structures and Formats" + }, + "MULTICAST": { + "description": "Multicast is a method of data transmission where data is sent to multiple destinations simultaneously.", + "level": "expert", + "category": "Networking and Protocols" + }, + "LATENCY": { + "description": "Latency is the delay between the input and output of a data processing system, important in streaming and real-time applications.", + "level": "all", + "aliases": [ + "DELAY" + ], + "category": "Performance and Optimization" + }, + "SIGNAL": { + "description": "A signal in GPAC refers to a type of data that triggers events or actions in media processing.", + "level": "expert", + "category": "GPAC Core " + }, + "OFFSCREEN": { + "description": "Offscreen processing in GPAC involves rendering or processing media data outside the visible display area.", + "level": "expert", + "category": "GPAC Core " + }, + "RFRAWID": { + "description": "RFRAWID is a unique identifier used in GPAC to reference raw data streams.", + "level": "expert", + "category": "Graphics and Rendering", + "aliases": [ + " RAW FILE IDENTIFIER" + ] + }, + "TTML": { + "description": "TTML (Timed Text Markup Language) is a standard for representing timed text media, such as subtitles and captions.", + "level": "all", + "aliases": [ + "SUBTITLE","XML SUBTITLE" + ], + "category": "Subtitles and Captioning" + }, + "BINARY": { + "description": "Binary data in GPAC refers to data represented in binary format, essential for encoding and processing media files.", + "level": "beginner", + "aliases": [ + "BITSTREAM" + ], + "category": "Data Structures and Formats" + }, + "BITRATE": { + "description": "Bitrate is the number of bits processed per unit of time, important for defining the quality and bandwidth usage of multimedia streams.", + "level": "beginner", + "aliases": [ + "BANDWIDTH" + ], + "category": "Performance and Optimization" + }, + "LIBGPAC": { + "description": "LibGPAC is the core library of GPAC, providing essential functionalities for multimedia processing.", + "level": "expert", + "category": "Libraries and Dependencies ", + "url": "https://doxygen.gpac.io/" + }, + "HEIF": { + "description": "HEIF (High Efficiency Image File Format) is a file format for individual images and image sequences, based on the HEVC standard.", + "level": "all", + "aliases": [ + "IMAGE" + ], + "category": "File Formats and Containers" + }, + "WEBVTT": { + "description": "WebVTT (Web Video Text Tracks) is a format used for displaying timed text tracks, such as subtitles or captions, with HTML5 video.", + "level": "all", + "aliases": [ + "SUBTITLE" + ], + "category": "Subtitles and Captioning" + }, + "NHNT": { + "description": "NHNT (Non-Hierarchical Naming Tables) is a format used in GPAC for structuring media data.", + "level": "expert", + "category": "File Formats and Containers" + }, + "ISMA": { + "description": "ISMA (Internet Streaming Media Alliance) is a standard for streaming multimedia content over the internet.", + "level": "expert", + "aliases": [ + "CENC" + ], + "category": "Security and Encryption" + }, + "CAROUSEL": { + "description": "A carousel in GPAC refers to a method of cyclically transmitting media data, often used in broadcast and streaming applications.", + "level": "expert", + "category": "Streaming Technologies" + }, + "SUBSAMPLE": { + "description": "Subsampling in GPAC involves reducing the resolution or frequency of media data for efficient processing and transmission.", + "level": "expert", + "category": "Media Processing " + }, + "AVMIX": { + "description": "AVMix is a process in GPAC for mixing audio and video streams into a single synchronized output.", + "level": "expert", + "category": "Media Processing " + }, + "CUE": { + "description": "A cue in GPAC is a marker used to indicate specific points in a media stream for navigation or synchronization.", + "level": "all", + "aliases": [ + "MARKER" + ], + "category": "Media Processing " + }, + "FLUSH": { + "description": "Flushing in GPAC involves clearing buffers and ensuring all processed data is output, important for maintaining data integrity.", + "level": "all", + "aliases": [ + "FLUSHING" + ], + "category": "Media Processing " + }, + "DASH": { + "description": "DASH (Dynamic Adaptive Streaming over HTTP) is an adaptive bitrate streaming technique that enables high-quality streaming of media content over the internet delivered from conventional HTTP web servers.", + "level": "all", + "aliases": [ + "HLS" + ], + "category": "Streaming Technologies" + }, + "DECODER": { + "description": "A decoder is a device or software that converts compressed media data back into its original format. GPAC uses various codecs to decode audio and video streams.", + "level": "beginner", + "aliases": [ + "AVDEC","HEVCD","VP9D","MPEG4D","AACD","MP3D" + ], + "category": "Codecs and Compression" + }, + "MANIFEST": { + "description": "A manifest is a file that provides information about the structure and components of a multimedia presentation, often used in streaming protocols like DASH and HLS.", + "level": "beginner", + "aliases": [ + "PLAYLIST" + ], + "category": "Streaming Technologies" + }, + "BUFFER": { + "description": "Rebuffering in GPAC refers to the process of refilling the buffer when data is being streamed, helping to prevent playback interruptions due to insufficient data.", + "level": "all", + "aliases": ["REBUFFER"], + "category": ["Streaming Technologies"] + + }, + "ENCODER": { + "description": "An encoder is a device or software that converts raw media data into a compressed format using codecs. This is essential for reducing file sizes and preparing media for streaming or storage.", + "level": "beginner", + "aliases": [ + "FFENC","X264","X265","AAC","LIBOPUS" + ], + "category": "Codecs and Compression" + }, + "MULTIPLEXER": { + "description": "A multiplexer is a device or software that combines multiple signals into one signal over a shared medium. In GPAC, multiplexing is used to combine audio, video, and other data streams into a single container file like MP4.", + "level": "all", + "aliases": [ + "MUX" + ], + "category": "Media Processing " + }, + "CONNECTION": { + "description": "A connection in GPAC refers to the relationship between filters in a processing graph. They define how data flows from one filter to another.", + "level": "beginner", + "aliases": [ + "LINK" + ], + "category": "GPAC Core" + }, + "LAYER": { + "description": "A layer in GPAC refers to the hierarchical levels of data processing or display, such as video layers in a compositing process.", + "level": "beginner", + "category": "Graphics and Rendering" + }, + "PIPELINE": { + "description": "A pipeline in GPAC is a sequence of connected filters that process media data in a specific order, defining the media processing workflow.", + "level": "beginner", + "aliases": [ + "CHAIN", + "PIPE" + ], + "category": "GPAC Core" + }, + "TRANSCODE": { + "description": "Transcoding is the process of converting a media file from one format to another. GPAC supports transcoding for various media formats to ensure compatibility and optimize playback.", + "level": "beginner", + "aliases": [ + "TRANSCODING" + ], + "category": "Media Processing " + }, + "TEMI": { + "description": "TEMI (Timed External Media Information) is a standard used to synchronize external media with broadcast content, allowing for accurate timing and synchronization of additional media streams.", + "level": "expert", + "category": "GPAC Core" + }, + "OVERLAY": { + "description": "An overlay in GPAC is a graphical element that is superimposed on a video stream, such as subtitles, watermarks, or interactive graphics.", + "level": "beginner", + "category": "Standards and Specifications" + }, + "ISOMEDIA": { + "description": "ISO Media refers to the family of media file formats based on the ISO Base Media File Format (ISOBMFF), including MP4 and MOV.", + "level": "all", + "aliases": [ + "MP4", + "MOV" + ], + "category": "File Formats and Containers" + }, + + "COMPRESSION": { + "description": "Compression is the process of reducing the size of a media file by encoding data using fewer bits. GPAC supports various compression algorithms to optimize storage and transmission.", + "level": "beginner", + "aliases": [ + "AVC","HEVC","VP9" + ], + "category": "Codecs and Compression" + }, + "BROADCAST": { + "description": "Broadcast in GPAC refers to the transmission of multimedia content to multiple receivers simultaneously, often used in live streaming and TV broadcasting.", + "level": "all", + "category": "Streaming Technologies" + }, + "REPAIR": { + "description": "Repair in GPAC refers to the process of fixing errors or corruption in media files to ensure proper playback and processing.", + "level": "all", + "category": "Tools and Utilities" + }, + "INTERLEAVE": { + "description": "Interleaving in GPAC refers to the process of mixing different types of media data for synchronous playback, ensuring that audio and video streams remain in sync.", + "level": "expert", + "category": "Media Processing " + }, + "MACRO": { + "description": "A macro in GPAC is a predefined sequence of instructions or commands that can be used to automate repetitive tasks in media processing.", + "level": "expert", + "category": "Tools and Utilities " + }, + "REBUFFER": { + "description": "Rebuffering in GPAC refers to the process of refilling the buffer when data is being streamed, helping to prevent playback interruptions due to insufficient data.", + "level": "all", + "aliases": [ + "BUFFER" + ], + "category": "Streaming Technologies" + }, + "OPENGL": { + "description": "OpenGL (Open Graphics Library) is a cross-language, cross-platform API for rendering 2D and 3D vector graphics.", + "level": "expert", + "aliases": [ + "GL" + ], + "category": "Graphics and Rendering", + "url": "https://www.opengl.org/" + }, + "WEBGL": { + "description": "WebGL (Web Graphics Library) is a JavaScript API for rendering high-performance interactive 3D and 2D graphics within any compatible web browser without the use of plug-ins.", + "level": "expert", + "aliases": [ + "Web Graphics Library" + ], + "category": "Graphics and Rendering", + "url": "https://www.khronos.org/webgl/" + } + } +} \ No newline at end of file diff --git a/docs/glossary/bitrate.md b/docs/glossary/bitrate.md new file mode 100644 index 00000000..2f779615 --- /dev/null +++ b/docs/glossary/bitrate.md @@ -0,0 +1,60 @@ +--- +hide: +- toc +tags: +- mp4 +- transcode +- input +- isomedia +- bitrate +- data +- isobmff +- output +- codec +- hevc +- sink +- dump +--- + + + + + +`bitrate` refers to the amount of data processed per unit of time during encoding or streaming. It directly impacts the quality and size of multimedia files. + +## Reference + +### +```bash +bitrate(input_file, output_file, bitrate_value) +``` + +## Usage + +- **Setting specific bitrates for encoding to optimize for quality or file size** +- **Adjusting audio/video bitrates to control bandwidth usage for streaming** + +## Troubleshooting + +### File size too large +- Reduce the bitrate for a smaller file size. + +### Quality is poor +- Increase the bitrate for better quality. + +## Example + +```bash +bitrate("input.mp4", "output.mp4", "1000k") +``` + +## Parameters + +- **input_file**: Path to the file. +- **output_file**: Output path. +- **bitrate_value**: Desired bitrate (e.g., `1000k` for 1000 kbps). + +## See Also: +- [Codec](codec.md) +- [Transcode](transcode.md) + diff --git a/docs/glossary/codec.md b/docs/glossary/codec.md new file mode 100644 index 00000000..ec2fd93d --- /dev/null +++ b/docs/glossary/codec.md @@ -0,0 +1,71 @@ +--- +hide: +- toc +tags: +- mp4 +- graph +- source +- transcode +- input +- media +- isomedia +- bitrate +- data +- encode +- isobmff +- output +- codec +- hevc +- sink +- dump +--- + + + + +`codec` refers to a compression algorithm used to encode and decode multimedia data (such as video, audio, etc.) into different formats for transmission and storage. + +## Reference + +### +```bash +codec(input_file, output_file, codec_name) +``` +## Usage + +- **Compressing video or audio using different codecs** +- **Optimizing multimedia files for storage or streaming** +- **Converting between different codecs for compatibility** + +## Troubleshooting + +### File not playing correctly +- Ensure the codec used is compatible with the media player. + +### Poor quality +- Verify that the encoding settings for the codec are optimized, such as using higher bitrates. + +## Example + +```bash +codec("input.mp4", "output.mp4", "libx265") +``` + +```mermaid + +graph LR; + A[input.mp4] --> B[libx265]; + B --> C[output.mp4]; +``` + + +## Parameters + +- **input_file**: Path to the multimedia file. +- **output_file**: Path where the output file will be saved. +- **codec_name**: The codec to be used for encoding, e.g., `libx265` for HEVC. + +## See Also +- [Bitrate](bitrate.md) +- [Transcode](transcode.md) + diff --git a/docs/glossary/decoder.md b/docs/glossary/decoder.md new file mode 100644 index 00000000..01612598 --- /dev/null +++ b/docs/glossary/decoder.md @@ -0,0 +1,62 @@ +--- +hide: +- toc +tags: +- mp4 +- input +- media +- data +- decoder +- raw +- output +- codec +- hevc +- decoding +- bitrate +--- + + + + + +### **Decoder** + +A `decoder` is responsible for converting encoded multimedia data back into its original format or an uncompressed format that can be processed by media players or other applications. + +## Reference + +### +```bash +decoder(input_file, output_file, codec) +``` +## Usage + +- **Decoding video files for playback** +- **Decoding audio files for editing or playback** +- **Converting encoded formats into raw data for further processing** + +## Troubleshooting + +### File not playing correctly after decoding +- Ensure the correct codec was used for decoding. + +### Decoding is slow +- Check if the system has enough resources or try using a different decoder. + +## Example + +```bash +decoder("input.mp4", "output.yuv", "libx264") +``` + +## Parameters + +- **input_file**: Path to the encoded multimedia file. +- **output_file**: Path where the decoded file will be saved. +- **codec**: Codec used for decoding (e.g., `libx264` for H.264). + +## See Also: +- [Codec](codec.md) +- [Bitrate](bitrate.md) + + diff --git a/docs/glossary/encode.md b/docs/glossary/encode.md new file mode 100644 index 00000000..d5a48fc3 --- /dev/null +++ b/docs/glossary/encode.md @@ -0,0 +1,62 @@ +--- + + +tags: +- mp4 +- source +- transcode +- input +- isomedia +- bitrate +- isobmff +- encode +- output +- codec +- hevc +- sink +- dump +--- + + + + + +`encode` is a function that allows you to encode multimedia files into various formats using specified codecs. + +## Reference + +### +```bash +encode(input_file, output_file, codec)` +``` +## Usage + +- **Encoding video files** +- **Encoding audio files** +- **Transcoding multimedia streams to different formats** +- **Setting encoding parameters such as bitrate and resolution** + +## Troubleshooting + +### The output file is not playing correctly +- Verify that the codec specified is compatible with the input multimedia file. + +### Encoding is very slow +- Ensure your system has sufficient resources and consider reducing the quality or complexity of the encoding settings. + +## Example + +```bash +encode("input.mp4", "output.mp4", "libx264") +``` + +## Parameters + +- **input_file**: Path to the multimedia file to be encoded. +- **output_file**: Path where the encoded file will be saved. +- **codec**: Codec to be used for encoding (e.g., libx264 for H.264 encoding). + +## See Also +- [Codec](codec.md) +- [Bitrate](bitrate.md) +- [Transcode](transcode.md) \ No newline at end of file diff --git a/docs/glossary/encrypt.md b/docs/glossary/encrypt.md new file mode 100644 index 00000000..20c7e0df --- /dev/null +++ b/docs/glossary/encrypt.md @@ -0,0 +1,60 @@ +--- +hide: +- toc +tags: +- mp4 +- encrypt +- source +- input +- isomedia +- isobmff +- decoder +- output +- xml +- sink +- dump +--- + + + + + +`encrypt` is a function that allows you to encrypt multimedia files using specified encryption keys. + +```bash +encrypt(input_file, output_file, key_file) +``` + +## Reference +```bash +encrypt("input.mp4", "output.mp4", "keyfile.xml") +``` + +## Usage + +- Encrypting video files +- Encrypting audio files +- Encrypting live multimedia streams +- Managing encryption keys + +## Troubleshooting + +### My output file is corrupted after encryption +- Verify that the key file is correct and compatible with the input multimedia file. + +### Permission error when accessing the key file +- Ensure you have the necessary permissions to read the key file. +## Example + +```bash +encrypt("input.mp4", "output.mp4", "keyfile.xml") +``` + +## Parameters + +- **input_file**: Path to the multimedia file to be encrypted. +- **output_file**: Path where the encrypted file will be saved. +- **key_file**: Path to the key file used for encryption. + +## See Also +- [Decoder](decoder) diff --git a/docs/glossary/output.md b/docs/glossary/output.md new file mode 100644 index 00000000..71d7cec4 --- /dev/null +++ b/docs/glossary/output.md @@ -0,0 +1,60 @@ +--- +hide: +- toc +tags: +- mp4 +- media +- isomedia +- data +- isobmff +- stream +- output +- codec +- hevc +- decoding +- decoder +- sink +- dump +--- + + + + + +`output` refers to the destination file or format where the result of encoding, decoding, or transcoding processes will be stored. + +## Reference + +### +```bash +output(output_file, format) +``` +## Usage + +- **Saving encoded or decoded multimedia files** +- **Specifying the format of the output file** +- **Exporting processed media streams** + +## Troubleshooting + +### Output file is corrupted or not working +- Verify the format and codec compatibility with the output media player. + +### Output file size is too large +- Consider adjusting the bitrate or encoding settings. + +## Example + +```bash +output("output.mp4", "mp4") +``` + +## Parameters + +- **output_file**: Path to save the output file. +- **format**: Format of the output file (e.g., `mp4`, `mkv`, `avi`). + +## See Also: +- [Decoder](decoder.md) +- [Codec](codec.md) + diff --git a/docs/glossary/sink.md b/docs/glossary/sink.md new file mode 100644 index 00000000..1bd291d9 --- /dev/null +++ b/docs/glossary/sink.md @@ -0,0 +1,61 @@ +--- +hide: +- toc +tags: +- mp4 +- source +- transcode +- chain +- input +- media +- isomedia +- data +- isobmff +- stream +- output +- codec +- hevc +- sink +- dump +--- + + + + + +`sink` refers to an output element that receives processed media data. It is usually the endpoint of a media processing pipeline. + +## Reference + +`SINK` + +## Usage + +- **Finalizing the media processing chain by writing the output data.** +- **Exporting media streams to various file formats (e.g., MP4, AVI).** +- **Displaying processed media in a player or exporting to a network stream.** + +## Troubleshooting + +### Output file not created +- Check the file path permissions and ensure the output format is supported. + +### Corrupted output data +- Confirm that the input data is correctly processed and compatible with the specified output format. + +## Example + +```plaintext +gpac -i input.mp4 -o output.avi +``` + +## Parameters + +- **output_file**: Path where the processed media data will be saved. +- **options**: Additional parameters to control the output settings (e.g., format, quality). + +## See Also +- [Output](output.md) +- [Codec](codec.md) +- [Transcode](transcode.md) + diff --git a/docs/glossary/source.md b/docs/glossary/source.md new file mode 100644 index 00000000..8a798629 --- /dev/null +++ b/docs/glossary/source.md @@ -0,0 +1,59 @@ +--- +hide: +- toc +tags: +- mp4 +- source +- input +- chain +- media +- isomedia +- isobmff +- data +- stream +- output +- filter +- decoder +--- + + + + + + +`source` is a keyword in GPAC representing an input element that provides media data to be processed. It is typically the starting point of a media processing pipeline. + +## Reference + +`SOURCE` + +## Usage + +- Serving as the entry point in a media processing chain. +- Loading various media types (e.g., video, audio) for further processing. +- Configuring the initial properties of media streams before processing. + +## Troubleshooting + +### No input data available +- Ensure the correct path or media source is specified and accessible. + +### Invalid media format +- Verify that the source format is supported by GPAC and correctly configured. + +## Example + +```plaintext +gpac -i input.mp4 -o output.mp4 +``` + +## Parameters + +- **input_file**: Path to the multimedia file to be loaded as a source. +- **options**: Additional parameters to control the behavior of the source filter (e.g., loop, start time). + +## See Also +- [Input](input) +- [Filter](filter.md) +- [Decoder](decoder.md) + diff --git a/docs/glossary/transcode.md b/docs/glossary/transcode.md new file mode 100644 index 00000000..56429966 --- /dev/null +++ b/docs/glossary/transcode.md @@ -0,0 +1,62 @@ +--- +hide: +- toc +tags: +- mp4 +- transcode +- input +- isomedia +- bitrate +- isobmff +- output +- codec +- hevc +- decoding +- sink +- dump +--- + + + + + +`transcode` is the process of converting a multimedia file from one format to another by decoding and re-encoding the file. + +## Reference + +### +```bash +transcode(input_file, output_file, codec, bitrate) +``` + +## Usage + +- **Converting between formats for different devices** +- **Changing video resolution or quality while preserving content** +- **Adjusting parameters like codec and bitrate for various outputs** + +## Troubleshooting + +### File does not play after transcoding +- Ensure you used the correct codec and bitrate for the target platform. + +### File quality is too low +- Check your codec and bitrate settings for proper optimization. + +## Example + +```bash +transcode("input.mp4", "output.mp4", "libvpx", "500k") +``` + +## Parameters + +- **input_file**: File to be transcoded. +- **output_file**: Output file path. +- **codec**: Codec to be used (e.g., `libvpx` for VP8). +- **bitrate**: Desired bitrate for the output file. + +## See Also: +- [Codec](codec.md) +- [Bitrate](bitrate.md) + diff --git a/docs/images/bad_format.png b/docs/images/bad_format.png new file mode 100644 index 00000000..21cc8d56 Binary files /dev/null and b/docs/images/bad_format.png differ diff --git a/docs/images/ex_beginner.png b/docs/images/ex_beginner.png new file mode 100644 index 00000000..4cb8e86e Binary files /dev/null and b/docs/images/ex_beginner.png differ diff --git a/docs/images/ex_expert.png b/docs/images/ex_expert.png new file mode 100644 index 00000000..e8fec143 Binary files /dev/null and b/docs/images/ex_expert.png differ diff --git a/docs/images/good_format.png b/docs/images/good_format.png new file mode 100644 index 00000000..c8585317 Binary files /dev/null and b/docs/images/good_format.png differ diff --git a/docs/index.md b/docs/index.md index 2bb3909a..76e95023 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,18 @@ --- hide: - - toc - - navigation - - feedback +- toc +- navigation +- feedback +tags: +- stream +- data +- media --- + + + +


@@ -32,3 +40,5 @@ hide: The documentation assumes GPAC 2.0 or above. Some informations relative to MP4Box may still be useful for older versions. . + + diff --git a/docs/javascripts/cache.js b/docs/javascripts/cache.js new file mode 100644 index 00000000..39195a13 --- /dev/null +++ b/docs/javascripts/cache.js @@ -0,0 +1,17 @@ +function getCache(key) { + try { + let cache = localStorage.getItem(key); + return cache ? JSON.parse(cache) : {}; + } catch (error) { + console.error(`Error getting cache for key "${key}":`, error); + return {}; + } +} + +function setCache(key, value) { + try { + localStorage.setItem(key, JSON.stringify(value)); + } catch (error) { + console.error(`Error setting cache for key "${key}":`, error); + } +} \ No newline at end of file diff --git a/docs/javascripts/domManipulation.js b/docs/javascripts/domManipulation.js new file mode 100644 index 00000000..0064f1db --- /dev/null +++ b/docs/javascripts/domManipulation.js @@ -0,0 +1,220 @@ +document.addEventListener("DOMContentLoaded", function () { + try { + const tocContent = document.getElementById("toc-content"); + const navContent = document.getElementById("nav-content"); + + tocContent.style.display = "none"; + navContent.style.display = "block"; + + initializeGlossaryPage(); + initializeCollapseSections(); + handleTOCLinks(); + handleInitialHash(); + initializeHeaderTitle(); + } catch (error) { + console.error("Error during DOMContentLoaded:", error); + } +}); + +function initializeGlossaryPage() { + try { + if (window.location.pathname.includes("/glossary/")) { + document.body.classList.add("glossary-page"); + } + } catch (error) { + console.error("Error in initializeGlossaryPage:", error); + } +} + +function initializeCollapseSections() { + try { + const articleInner = document.querySelector('.md-content__inner'); + if (!articleInner) return; + + const articleContentDiv = document.createElement('div'); + articleContentDiv.classList.add('article-content'); + + while (articleInner.firstChild) { + articleContentDiv.appendChild(articleInner.firstChild); + } + + articleInner.appendChild(articleContentDiv); + + const h2Elements = articleContentDiv.querySelectorAll('h2'); + h2Elements.forEach(createCollapseSection); + } catch (error) { + console.error("Error in initializeCollapseSections:", error); + } +} + +function createArticleContentDiv(h1Element, feedbackForm) { + try { + const articleContentDiv = document.createElement('div'); + articleContentDiv.classList.add('article-content'); + + const fragment = document.createDocumentFragment(); + let sibling = h1Element.nextElementSibling; + while (sibling && sibling !== feedbackForm) { + const nextSibling = sibling.nextElementSibling; + fragment.appendChild(sibling); + sibling = nextSibling; + } + + articleContentDiv.appendChild(fragment); + h1Element.insertAdjacentElement('afterend', articleContentDiv); + } catch (error) { + console.error("Error in createArticleContentDiv:", error); + } +} + +function createCollapseSection(h2) { + try { + const content = []; + let sibling = h2.nextElementSibling; + while (sibling && sibling.tagName !== 'H2') { + content.push(sibling); + sibling = sibling.nextElementSibling; + } + + if (content.length === 0) { + h2.classList.add('no-collapse'); + return; + } + const noCollapse = h2.classList.contains('no-collapse'); + if (noCollapse) { + return; + } + const collapseSection = document.createElement('div'); + collapseSection.classList.add('collapse-section', 'active'); + + const collapseContent = document.createElement('div'); + collapseContent.classList.add('collapse-content'); + content.forEach(element => collapseContent.appendChild(element)); + + h2.parentNode.insertBefore(collapseSection, h2); + collapseSection.appendChild(h2); + collapseSection.appendChild(collapseContent); + + addCollapseIcon(h2); + + h2.addEventListener('click', function () { + toggleSection(collapseSection); + if (h2.dataset.level === 'all') { + handleAllSection(collapseSection, h2); + } + }); + + return collapseSection; + } catch (error) { + console.error("Error in createCollapseSection:", error); + } +} + +function addCollapseIcon(h2) { + try { + if (!h2.querySelector('.collapse-icon')) { + const collapseIcon = document.createElement('span'); + collapseIcon.classList.add('collapse-icon'); + collapseIcon.innerHTML = ''; + h2.appendChild(collapseIcon); + } + } catch (error) { + console.error("Error in addCollapseIcon:", error); + } +} + +function toggleSection(section) { + try { + section.classList.toggle('active'); + } catch (error) { + console.error("Error in toggleSection:", error); + } +} + +function handleTOCLinks() { + try { + const tocLinks = document.querySelectorAll('.md-nav__link'); + tocLinks.forEach(link => { + if (link && link.hasAttribute('href')) { + link.addEventListener('click', function (e) { + const hash = this.getAttribute('href'); + if (hash.startsWith('#')) { + openCollapsedSection(hash); + } + }); + } + }); + } catch (error) { + console.error("Error in handleTOCLinks:", error); + } +} + +function handleInitialHash() { + try { + if (window.location.hash) { + openCollapsedSection(window.location.hash); + } + } catch (error) { + console.error("Error in handleInitialHash:", error); + } +} + +function openCollapsedSection(hash) { + try { + if (hash) { + const targetElement = document.querySelector(hash); + if (targetElement) { + const collapseSection = targetElement.closest('.collapse-section'); + if (collapseSection && !collapseSection.classList.contains('active')) { + collapseSection.classList.add('active'); + } + } + } + } catch (error) { + console.error("Error in openCollapsedSection:", error); + } +} + +function handleAllSection(section, h2) { + try { + if (section.classList.contains('active')) { + section.setAttribute('data-was-active', 'true'); + } else { + section.removeAttribute('data-was-active'); + } + } catch (error) { + console.error("Error in handleAllSection:", error); + } +} + +function initializeHeaderTitle() { + try { + const header = document.querySelector('.md-header'); + const siteNameTopic = document.querySelector('.md-header__topic--site-name'); + const pageTitleTopic = document.querySelector('.md-header__topic--page-title'); + + if (!header || !siteNameTopic || !pageTitleTopic) { + console.error('Required elements not found for header title initialization'); + return; + } + + const showHeaderTitleThreshold = 100; + let isTransitioning = false; + + window.addEventListener('scroll', () => { + if (isTransitioning) return; + + if (window.scrollY > showHeaderTitleThreshold && !header.classList.contains('show-page-title')) { + isTransitioning = true; + header.classList.add('show-page-title'); + setTimeout(() => { isTransitioning = false; }, 100); + } else if (window.scrollY <= showHeaderTitleThreshold && header.classList.contains('show-page-title')) { + isTransitioning = true; + header.classList.remove('show-page-title'); + setTimeout(() => { isTransitioning = false; }, 100); + } + }); + } catch (error) { + console.error("Error in initializeHeaderTitle:", error); + } +} \ No newline at end of file diff --git a/docs/javascripts/fetchFunctions.js b/docs/javascripts/fetchFunctions.js new file mode 100644 index 00000000..768465a1 --- /dev/null +++ b/docs/javascripts/fetchFunctions.js @@ -0,0 +1,81 @@ +function fetchKeywords(currentPageMdPath, cachedKeywords, cachedDefinitions) { + try { + fetch('/data/keywords.json') + .then(response => { + if (!response.ok) { + throw new Error('Network response was not ok'); + } + return response.json(); + }) + .then(data => { + const allDefinitions = data.definitions; + const lexique = Object.keys(allDefinitions); + + + findKeywordsInContent(currentPageMdPath, lexique, (filteredKeywords) => { + cachedKeywords[currentPageMdPath] = filteredKeywords; + setCache('keywordsCache', cachedKeywords); + const selectedLevel = localStorage.getItem('userLevel') || 'beginner'; + displayKeywords(filteredKeywords, cachedDefinitions, allDefinitions, selectedLevel); + }); + }) + .catch(error => { + console.error('Error fetching keywords:', error); + }); + } catch (error) { + console.error('Unexpected error in fetchKeywords:', error); + } +} + +function fetchDefinitions(keyword, cachedDefinitions) { + return new Promise((resolve, reject) => { + fetch('/data/keywords.json') + .then(response => response.json()) + .then(data => { + const definition = data.definitions[keyword]; + if (definition) { + cachedDefinitions[keyword] = definition; + setCache('definitionsCache', cachedDefinitions); + resolve(definition); + } else { + console.error('Definition not found for keyword:', keyword); + resolve({ description: 'Definition not found' }); + } + }) + .catch(error => { + console.error('Error fetching definition:', error); + reject(error); + }); + }); +} + + +function fetchMarkdownContent(currentPageMdPath) { + try { + return fetch(currentPageMdPath) + .then(response => { + if (!response.ok) { + throw new Error('Network response was not ok'); + } + return response.text(); + }) + .then(htmlContent => { + const parser = new DOMParser(); + const doc = parser.parseFromString(htmlContent, 'text/html'); + const mdContent = doc.querySelector('.md-content[data-md-component="content"]'); + if (mdContent) { + return mdContent.textContent; + } else { + console.warn('Content element not found in the parsed HTML'); + return ''; + } + }) + .catch(error => { + console.error('Error fetching markdown content:', error); + throw error; + }); + } catch (error) { + console.error('Unexpected error in fetchMarkdownContent:', error); + return Promise.reject(error); + } +} \ No newline at end of file diff --git a/docs/javascripts/keywordsDisplay.js b/docs/javascripts/keywordsDisplay.js new file mode 100644 index 00000000..4fe5da85 --- /dev/null +++ b/docs/javascripts/keywordsDisplay.js @@ -0,0 +1,99 @@ +function displayKeywords( + keywords, + cachedDefinitions, + allDefinitions, + selectedLevel +) { + try { + const wordCloudElement = document.querySelector(".words-cloud"); + const wordCloudList = document.getElementById("dynamic-words-cloud"); + if (!wordCloudElement || !wordCloudList) { + throw new Error("Word cloud elements not found"); + } + wordCloudList.innerHTML = ""; + + const sizes = ["size-1", "size-2", "size-3", "size-4", "size-5"]; + const colors = ["color-1", "color-2", "color-3", "color-4"]; + + let displayedKeywordsCount = 0; + + const totalRelevantKeywords = keywords.filter((keyword) => { + const definition = allDefinitions[keyword]; + return ( + definition && + (definition.level === selectedLevel || definition.level === "all") + ); + }).length; + + keywords.forEach((keyword, index) => { + try { + const definition = allDefinitions[keyword]; + + if ( + definition && + (definition.level === selectedLevel || definition.level === "all") + ) { + displayedKeywordsCount++; + + const li = document.createElement("li"); + const a = document.createElement("a"); + a.href = "#"; + a.textContent = keyword; + a.className = + sizes[index % sizes.length] + " " + colors[index % colors.length]; + + a.addEventListener("mouseenter", function (event) { + try { + event.preventDefault(); + clearTimeout(closeModalTimer); + if (cachedDefinitions[keyword]) { + openModal(keyword, cachedDefinitions[keyword], event); + } else { + fetchDefinitions(keyword, cachedDefinitions) + .then((definition) => { + openModal(keyword, definition, event); + }) + .catch((error) => { + console.error("Error fetching definition:", error); + }); + } + } catch (error) { + console.error("Error handling mouseenter event:", error); + } + }); + + a.addEventListener("mouseleave", startCloseModalTimer); + + li.appendChild(a); + wordCloudList.appendChild(li); + } + } catch (error) { + console.error(`Error processing keyword "${keyword}":`, error); + } + }); + + if (displayedKeywordsCount > 0) { + wordCloudElement.classList.remove("hidden"); + } else { + wordCloudElement.classList.add("hidden"); + } + + if (displayedKeywordsCount < totalRelevantKeywords) { + console.warn( + `Some relevant keywords (${ + totalRelevantKeywords - displayedKeywordsCount + }) could not be displayed.` + ); + } + } catch (error) { + console.error("Error displaying keywords:", error); + } +} + +function navigateToTagPage(keyword) { + try { + window.location.href = `/tags/#${keyword.toLowerCase()}`; + } catch (error) { + console.error("Error navigating to tag page:", error); + } +} diff --git a/docs/javascripts/keywordsFinder.js b/docs/javascripts/keywordsFinder.js new file mode 100644 index 00000000..2f3c741e --- /dev/null +++ b/docs/javascripts/keywordsFinder.js @@ -0,0 +1,36 @@ +//delete links in markdown content +function cleanMarkdownContent(content) { + return content.replace(/\[[^\]]*\]\([^)]*\)/g, ""); +} + +function cleanWord(word) { + return word.replace(/[.,!?(){}[\]`-]/g, "").toUpperCase(); +} + +function findKeywordsInContent(currentPageMdPath, lexique, callback) { + fetchMarkdownContent(currentPageMdPath) + .then((content) => { + try { + const cleanContent = cleanMarkdownContent(content); + const wordCounts = {}; + + const words = cleanContent.split(/\s+/); + + words.forEach((word) => { + const cleanedWord = cleanWord(word); + if (lexique.includes(cleanedWord)) { + wordCounts[cleanedWord] = (wordCounts[cleanedWord] || 0) + 1; + } + }); + + const filteredKeywords = Object.keys(wordCounts).filter( + (word) => wordCounts[word] >= 2 + ); + + callback(filteredKeywords); + } catch (error) { + console.error("Error processing markdown content:", error); + } + }) + .catch((error) => console.error("Error fetching markdown content:", error)); +} diff --git a/docs/javascripts/levels.js b/docs/javascripts/levels.js new file mode 100644 index 00000000..5d6078a6 --- /dev/null +++ b/docs/javascripts/levels.js @@ -0,0 +1,423 @@ +let levelSwitch, switchLabel, currentPageMdPath, collapseAllSwitch, settingsButton, settingsDropdown; + +/** + * Settings Management + * This section contains functions related to initializing and managing user settings. + */ + +/** + * Initializes the settings functionality. + * Sets up event listeners and loads saved preferences. + */ +function initializeSettings() { + try { + collapseAllSwitch = document.getElementById('collapse-all-switch'); + settingsButton = document.querySelector('.md-header__settings-button'); + settingsDropdown = document.querySelector('.md-header__settings-dropdown'); + + const savedLevel = localStorage.getItem('userLevel') || 'expert'; + const savedCollapseAll = localStorage.getItem('collapseAll') === 'true'; + collapseAllSwitch.checked = savedCollapseAll; + toggleAllSections(savedCollapseAll); + + collapseAllSwitch.addEventListener('change', handleCollapseAllChange); + settingsButton.addEventListener('click', toggleSettingsDropdown); + + document.addEventListener('click', closeSettingsDropdown); + } catch (error) { + console.error("Error in initializeSettings:", error); + } +} + +/** + * Handles the change event of the collapse all switch. + * Updates localStorage and toggles all sections accordingly. + */ +function handleCollapseAllChange() { + try { + const collapseAll = collapseAllSwitch.checked; + localStorage.setItem('collapseAll', collapseAll); + toggleAllSections(collapseAll); + } catch (error) { + console.error("Error in handleCollapseAllChange:", error); + } +} + +/** + * Toggles the visibility of the settings dropdown. + */ +function toggleSettingsDropdown() { + try { + settingsDropdown.classList.toggle('hidden'); + } catch (error) { + console.error("Error in toggleSettingsDropdown:", error); + } +} + +/** + * Closes the settings dropdown when clicking outside of it. + * @param {Event} event - The click event + */ +function closeSettingsDropdown(event) { + try { + if (!settingsDropdown.contains(event.target) && !settingsButton.contains(event.target)) { + settingsDropdown.classList.add('hidden'); + } + } catch (error) { + console.error("Error in closeSettingsDropdown:", error); + } +} + +/** + * Toggles all collapsible sections based on the collapse parameter. + * @param {boolean} collapse - Whether to collapse or expand all sections + */ +function toggleAllSections(collapse) { + try { + const sections = document.querySelectorAll('.collapse-section'); + sections.forEach(section => { + if (collapse) { + section.classList.remove('active'); + } else { + section.classList.add('active'); + } + }); + } catch (error) { + console.error("Error in toggleAllSections:", error); + } +} + +/** + * Level Management + * This section contains functions related to managing user expertise levels. + */ + +/** + * Initializes the level management functionality. + * Sets up event listeners and applies initial level settings. + */ +function initializeLevelManagement() { + try { + levelSwitch = document.getElementById('level-switch'); + switchLabel = document.querySelector('.switch-label'); + + if (!levelSwitch || !switchLabel) { + console.error('Level switch or switch label not found'); + return; + } + const savedLevel = localStorage.getItem("userLevel") || "expert"; + + if (isSearchResultPage()) { + if (setTemporaryExpertMode()) { + filterContent('expert'); + updateTOCVisibility('expert'); + updateOptionsVisibility('expert'); + } + } else { + if (revertFromTemporaryExpertMode()) { + filterContent('beginner'); + updateTOCVisibility('beginner'); + updateOptionsVisibility('beginner'); + } + } + levelSwitch.checked = savedLevel === "expert"; + updateSwitchLabel(); + + filterContent(savedLevel); + updateTOCVisibility(savedLevel); + + currentPageMdPath = getCurrentPageMdPath(); + levelSwitch.addEventListener("change", handleLevelChange); + } catch (error) { + console.error("Error in initializeLevelManagement:", error); + } +} + +/** + * Gets the current page's Markdown path. + * @returns {string} The current page's Markdown path + */ +function getCurrentPageMdPath() { + try { + let currentPagePath = window.location.pathname; + if (currentPagePath.endsWith("/")) { + currentPagePath = currentPagePath.slice(0, -1); + } + return currentPagePath.replace(".html", ".md"); + } catch (error) { + console.error("Error in getCurrentPageMdPath:", error); + return ''; + } +} + +/** + * Handles the change event of the level switch. + * Updates localStorage and applies new level settings. + */ +function handleLevelChange() { + try { + const selectedLevel = levelSwitch.checked ? "expert" : "beginner"; + localStorage.setItem("userLevel", selectedLevel); + updateSwitchLabel(); + filterContent(selectedLevel); + updateTOCVisibility(selectedLevel); + updateOptionsVisibility(selectedLevel); + + let cachedKeywords = getCache("keywordsCache"); + let cachedDefinitions = getCache("definitionsCache"); + fetchKeywords(currentPageMdPath, cachedKeywords, cachedDefinitions); + + document.dispatchEvent(new CustomEvent('userLevelChanged', { detail: selectedLevel })); + } catch (error) { + console.error("Error in handleLevelChange:", error); + } +} + +/** + * Updates the switch label text based on the current level. + */ +function updateSwitchLabel() { + try { + if (switchLabel && levelSwitch) { + switchLabel.textContent = levelSwitch.checked ? "Expert" : "Beginner"; + } else { + console.error('switchLabel or levelSwitch is undefined'); + } + } catch (error) { + console.error("Error in updateSwitchLabel:", error); + } +} + +/** + * Content Filtering + * This section contains functions related to filtering content based on user level. + */ + +/** + * Checks if the current page is in the Howtos section. + * @returns {boolean} True if the current page is in the Howtos section + */ +function isHowtosSection() { + try { + return window.location.pathname.includes('/Howtos/'); + } catch (error) { + console.error("Error in isHowtosSection:", error); + return false; + } +} + +/** + * Filters content based on the user's level. + * @param {string} level - The user's level ('expert' or 'beginner') + */ +function filterContent(level) { + try { + const articleContent = document.querySelector('.article-content'); + if (!articleContent) return; + + const sections = articleContent.querySelectorAll('.collapse-section'); + + if (isHowtosSection()) { + const hasBeginnerSections = Array.from(sections).some(section => + section.querySelector('h2[data-level="beginner"]') + ); + + sections.forEach(section => { + const h2Element = section.querySelector('h2'); + const sectionLevel = h2Element ? h2Element.dataset.level : null; + const isAllSection = sectionLevel === 'all'; + const span = section.querySelector('.level-tag'); + + if (level === 'expert' || isAllSection) { + handleExpertOrAllSection(section, span, level, isAllSection); + } else if (level === 'beginner') { + if (hasBeginnerSections) { + handleBeginnerSectionWithTags(section, sectionLevel, isAllSection, span); + } else { + handleBeginnerSectionWithoutTags(section, sectionLevel, isAllSection, span); + } + } + }); + } else { + sections.forEach(section => { + section.classList.remove('hidden-level'); + const span = section.querySelector('.level-tag'); + if (span) span.style.display = 'none'; + }); + } + } catch (error) { + console.error("Error in filterContent:", error); + } +} + +function handleBeginnerSectionWithTags(section, sectionLevel, isAllSection, span) { + try { + if (sectionLevel === "beginner" || isAllSection) { + section.classList.remove("hidden-level"); + if (span) { + span.style.display = sectionLevel === "beginner" ? "" : "none"; + } + } else { + section.classList.add("hidden-level"); + } + } catch (error) { + console.error("Error in handleBeginnerSectionWithTags:", error); + } +} + +function handleBeginnerSectionWithoutTags(section, sectionLevel, isAllSection, span) { + try { + section.classList.remove("hidden-level"); + if (span) { + span.style.display = "none"; + } + } catch (error) { + console.error("Error in handleBeginnerSectionWithoutTags:", error); + } +} + +// Remove tag "expert" and "all" +function handleExpertOrAllSection(section, span, level, isAllSection) { + try { + section.classList.remove("hidden-level"); + if (span && (level === "expert" || isAllSection)) { + span.style.display = "none"; + } + } catch (error) { + console.error("Error in handleExpertOrAllSection:", error); + } +} + +function updateTOCVisibility(level) { + try { + if (!document.body) { + console.warn('Document body not ready, deferring TOC update'); + return; + } + if (level !== 'beginner') { + document.querySelectorAll('.md-nav__item').forEach(item => { + item.style.display = ''; + }); + return; + } + + const h2Elements = document.querySelectorAll('h2[data-level]'); + const tocItems = document.querySelectorAll('.md-nav__item'); + + const beginnerIds = new Set(); + const sectionWithSubsections = new Set(); + h2Elements.forEach(h2 => { + if (h2.getAttribute('data-level') === 'beginner' && h2.id) { + beginnerIds.add(h2.id); + } + }); + if (beginnerIds.size === 0) { + tocItems.forEach(item => { + item.style.display = ''; + }); + } else { + // Hide non-beginner TOC items and show beginner ones. + tocItems.forEach(item => { + const link = item.querySelector('a.md-nav__link'); + if (link) { + const href = link.getAttribute('href'); + if (href && href.startsWith('#')) { + const id = href.slice(1); + if (!beginnerIds.has(id)) { + item.style.display = 'none'; + } else { + item.style.display = ''; + } + } + } + }); + } + } catch (error) { + console.error("Error in updateTOCVisibility:", error); + } +} + +function updateOptionsVisibility(level) { + try { + const optionDivs = document.querySelectorAll('.option'); + optionDivs.forEach(div => { + const aElement = div.querySelector('a[id]'); + if (level === 'beginner') { + if (aElement && aElement.getAttribute('data-level') === 'basic') { + div.style.display = ''; + } else { + div.style.display = 'none'; + } + } else { + div.style.display = ''; + } + }); + } catch (error) { + console.error("Error in updateOptionsVisibility:", error); + } +} + +// Levels with search feature +function isSearchResultPage() { + try { + return new URLSearchParams(window.location.search).has('h'); + } catch (error) { + console.error("Error in isSearchResultPage:", error); + return false; + } +} + +function setTemporaryExpertMode() { + try { + const currentLevel = localStorage.getItem('userLevel'); + if (currentLevel === 'beginner' && isSearchResultPage()) { + localStorage.setItem('tempExpertMode', 'true'); + localStorage.setItem('userLevel', 'expert'); + return true; + } + return false; + } catch (error) { + console.error("Error in setTemporaryExpertMode:", error); + return false; + } +} + +function revertFromTemporaryExpertMode() { + try { + if (localStorage.getItem('tempExpertMode') === 'true') { + localStorage.setItem('userLevel', 'beginner'); + localStorage.removeItem('tempExpertMode'); + return true; + } + return false; + } catch (error) { + console.error("Error in revertFromTemporaryExpertMode:", error); + return false; + } +} + +/** + * Event Listeners + * This section sets up the main event listeners when the DOM is loaded. + */ +document.addEventListener("DOMContentLoaded", function () { + try { + initializeSettings(); + initializeLevelManagement(); + const savedLevel = localStorage.getItem("userLevel") || "expert"; + updateTOCVisibility(savedLevel); + updateOptionsVisibility(savedLevel); + + let cachedKeywords = getCache("keywordsCache"); + let cachedDefinitions = getCache("definitionsCache"); + + fetchKeywords(currentPageMdPath, cachedKeywords, cachedDefinitions); + + const levelSwitch = document.getElementById('level-switch'); + if (levelSwitch) { + levelSwitch.addEventListener('change', handleLevelChange); + } + } catch (error) { + console.error("Error during DOMContentLoaded:", error); + } +}); \ No newline at end of file diff --git a/docs/javascripts/main.js b/docs/javascripts/main.js new file mode 100644 index 00000000..a1ed4f08 --- /dev/null +++ b/docs/javascripts/main.js @@ -0,0 +1,246 @@ +const EXPERT_LEVEL = 'expert'; +const BEGINNER_LEVEL = 'beginner'; + +// initialize functions +function initializeApp() { + try { + initializeSettings(); + initializeLevelManagement(); + initializeFeedback('.md-nav__feedback--desktop'); + initializeFeedback('.md-feedback--mobile'); + initializeTagNavigation(); + setupEventListeners(); + handleInitialPageLoad(); + } catch (error) { + console.error("Error in initializeApp:", error); + } +} + +function setupEventListeners() { + try { + document.body.addEventListener('click', handleNavigation); + window.addEventListener('popstate', handlePopState); + window.addEventListener('load', handleSearchPageCollapse); + } catch (error) { + console.error("Error in setupEventListeners:", error); + } +} + +function handleInitialPageLoad() { + try { + const savedLevel = localStorage.getItem("userLevel") || EXPERT_LEVEL; + updateTOCVisibility(savedLevel); + updateOptionsVisibility(savedLevel); + + const currentPagePath = getCurrentPagePath(); + const cachedKeywords = getCache('keywordsCache'); + const cachedDefinitions = getCache('definitionsCache'); + + fetchKeywords(currentPagePath, cachedKeywords, cachedDefinitions); + } catch (error) { + console.error("Error in handleInitialPageLoad:", error); + } +} + +// Handlers +function handleNavigation(event) { + try { + const target = event.target.closest('a'); + if (!isValidNavigationTarget(target)) return; + + const currentUrl = new URL(window.location.href); + const targetUrl = new URL(target.href); + + if (shouldHandleNavigation(currentUrl, targetUrl)) { + handleNavigationChange(event, target); + } + } catch (error) { + console.error("Error in handleNavigation:", error); + } +} + +function isValidNavigationTarget(target) { + try { + return target && target.href && !target.href.startsWith('javascript:'); + } catch (error) { + console.error("Error in isValidNavigationTarget:", error); + return false; + } +} + +function shouldHandleNavigation(currentUrl, targetUrl) { + try { + return currentUrl.pathname !== targetUrl.pathname || !targetUrl.searchParams.has('h'); + } catch (error) { + console.error("Error in shouldHandleNavigation:", error); + return false; + } +} + +function handleNavigationChange(event, target) { + try { + if (localStorage.getItem('tempExpertMode') === 'true') { + event.preventDefault(); + revertFromTemporaryExpertMode(); + updateContentVisibility(BEGINNER_LEVEL); + setTimeout(() => { + window.location.href = target.href; + }, 0); + } + } catch (error) { + console.error("Error in handleNavigationChange:", error); + } +} + +function handlePopState() { + try { + if (!isSearchResultPage() && revertFromTemporaryExpertMode()) { + updateContentVisibility(BEGINNER_LEVEL); + } + } catch (error) { + console.error("Error in handlePopState:", error); + } +} + +// Feedback +function initializeFeedback(selector) { + try { + const feedback = document.querySelector(selector); + if (!feedback) return; + + const buttons = feedback.querySelectorAll('.md-feedback__icon:not(.md-feedback__contribute)'); + const note = getFeedbackNote(feedback); + + buttons.forEach(button => { + button.addEventListener('click', () => handleFeedbackClick(button, buttons, note)); + }); + + initializeContributeIcon(feedback); + } catch (error) { + console.error("Error in initializeFeedback:", error); + } +} + +function getFeedbackNote(feedback) { + try { + let note = feedback.querySelector('.md-feedback__note'); + if (!note) { + note = document.createElement('div'); + note.className = 'md-feedback__note'; + note.hidden = true; + feedback.querySelector('.md-feedback__inner').appendChild(note); + } + return note; + } catch (error) { + console.error("Error in getFeedbackNote:", error); + return null; + } +} + +function handleFeedbackClick(button, allButtons, note) { + try { + const data = button.getAttribute('data-md-value'); + const url = `/${window.location.pathname}`; + const title = document.querySelector('.md-content__inner h1')?.textContent || ''; + + console.log(`Feedback: ${data} for page ${url} (${title})`); + + note.textContent = `Thank you for your feedback!`; + note.hidden = false; + + allButtons.forEach(btn => btn.disabled = true); + } catch (error) { + console.error("Error in handleFeedbackClick:", error); + } +} + +function initializeContributeIcon(feedback) { + try { + const contributeIcon = feedback.querySelector('.md-feedback__contribute'); + const contributeNote = feedback.querySelector('.md-feedback__contribute-note'); + + if (contributeIcon && contributeNote) { + contributeIcon.addEventListener('mouseenter', () => contributeNote.hidden = false); + contributeIcon.addEventListener('mouseleave', () => contributeNote.hidden = true); + } + } catch (error) { + console.error("Error in initializeContributeIcon:", error); + } +} + +// Collapse +function handleSearchPageCollapse() { + try { + const isSearchPage = new URLSearchParams(window.location.search).has('h'); + const wasCollapsed = localStorage.getItem('wasCollapsed'); + + if (isSearchPage && localStorage.getItem('collapseAll') === 'true') { + localStorage.setItem('wasCollapsed', 'true'); + toggleAllSections(false); + } else if (wasCollapsed === 'true') { + localStorage.removeItem('wasCollapsed'); + toggleAllSections(true); + } + } catch (error) { + console.error("Error in handleSearchPageCollapse:", error); + } +} + +// Tags navigation +function initializeTagNavigation() { + try { + const wordCloudLinks = document.querySelectorAll('#dynamic-words-cloud a'); + wordCloudLinks.forEach(link => { + link.addEventListener('click', (event) => { + try { + event.preventDefault(); + navigateToTagPage(event.target.textContent); + } catch (error) { + console.error("Error in wordCloudLinks click event:", error); + } + }); + }); + } catch (error) { + console.error("Error in initializeTagNavigation:", error); + } +} + +function navigateToTagPage(keyword) { + try { + window.location.href = `/tags/#${keyword.toLowerCase()}`; + } catch (error) { + console.error("Error in navigateToTagPage:", error); + } +} + +// Utils +function getCurrentPagePath() { + try { + let currentPagePath = window.location.pathname; + if (currentPagePath.endsWith('/')) { + currentPagePath = currentPagePath.slice(0, -1); + } + return currentPagePath.replace('.html', '.md'); + } catch (error) { + console.error("Error in getCurrentPagePath:", error); + return ''; + } +} + +function updateContentVisibility(level) { + try { + filterContent(level); + updateTOCVisibility(level); + updateOptionsVisibility(level); + } catch (error) { + console.error("Error in updateContentVisibility:", error); + } +} + +document.addEventListener('DOMContentLoaded', function () { + try { + initializeApp(); + } catch (error) { + console.error("Error during DOMContentLoaded:", error); + } +}); \ No newline at end of file diff --git a/docs/javascripts/modalFunctions.js b/docs/javascripts/modalFunctions.js new file mode 100644 index 00000000..12c6ecba --- /dev/null +++ b/docs/javascripts/modalFunctions.js @@ -0,0 +1,223 @@ +let closeModalTimer; + +function keepModalOpen() { + clearTimeout(closeModalTimer); +} + +function startCloseModalTimer() { + closeModalTimer = setTimeout(closeModal, 300); +} + +function openModal(keyword, definition, event) { + try { + const modal = document.getElementById("modal"); + const modalTitle = document.getElementById("modal-title"); + const modalDefinition = document.getElementById("modal-definition"); + const modalLink = document.getElementById("modal-link"); + + if (!modalTitle || !modalDefinition || !modalLink) { + throw new Error("Modal elements not found"); + } + + setModalContent(modalTitle, modalDefinition, modalLink, keyword, definition); + + if (event && event.target) { + const rect = event.target.getBoundingClientRect(); + const parentRect = document.querySelector('.words-cloud-container').getBoundingClientRect(); + + const offsetLeft = rect.left - parentRect.left; + const offsetTop = rect.bottom - parentRect.top; + + modal.style.position = "absolute"; + modal.style.left = `${offsetLeft - 80}px`; + modal.style.top = `${offsetTop + 40}px`; + } + + showModal(modal, modalLink); + + modal.addEventListener("mouseenter", keepModalOpen); + modal.addEventListener("mouseleave", startCloseModalTimer); + } catch (error) { + console.error("Error opening modal:", error); + } +} + +function setModalContent(modalTitle, modalDefinition, modalLink, keyword, definition) { + try { + let descriptionText = "Definition not available"; + if (typeof definition === "string") { + descriptionText = definition; + } else if (definition && typeof definition === "object" && definition.description) { + descriptionText = definition.description; + } + + const glossaryPageUrl = `${window.location.origin}/glossary//`; + const tagsPageUrl = `/tags/#${keyword.toLowerCase()}`; + + modalTitle.textContent = keyword; + modalTitle.onclick = function () { + window.location.href = tagsPageUrl; + }; + + modalDefinition.innerHTML = ''; + + // Description + const descriptionElement = document.createElement('p'); + descriptionElement.textContent = descriptionText; + modalDefinition.appendChild(descriptionElement); + + // Aliases section + if (definition.aliases && definition.aliases.length > 0) { + const aliasesSection = createAliasesSection(definition.aliases); + modalDefinition.appendChild(aliasesSection); + } + + modalLink.href = definition.url || glossaryPageUrl; + } catch (error) { + console.error("Error setting modal content:", error); + } +} + +function createAliasesSection(aliases) { + try { + const aliasesSection = document.createElement("div"); + aliasesSection.classList.add("modal-aliases"); + + const aliasesTitle = document.createElement("h3"); + aliasesTitle.textContent = "See also:"; + aliasesSection.appendChild(aliasesTitle); + + const aliasesList = document.createElement("ul"); + aliases.forEach((alias) => { + const aliasItem = document.createElement("li"); + const aliasLink = createAliasLink(alias); + aliasItem.appendChild(aliasLink); + aliasesList.appendChild(aliasItem); + }); + + aliasesSection.appendChild(aliasesList); + return aliasesSection; + } catch (error) { + console.error("Error creating aliases section:", error); + } +} + +function createAliasLink(alias) { + try { + const link = document.createElement("a"); + link.textContent = alias; + link.href = `/tags/#${alias.toLowerCase()}`; + link.className = "alias-link"; + return link; + } catch (error) { + console.error("Error creating alias link:", error); + } +} + +function showModal(modal, modalLink) { + try { + modal.style.display = "block"; + modal.classList.remove("hidden"); + modalLink.classList.remove("hidden"); + + modal.offsetHeight; + + requestAnimationFrame(() => { + requestAnimationFrame(() => { + modal.classList.add("visible"); + + }); + }); + + setTimeout(() => { + modal.classList.add("visible"); + }, 10); + } catch (error) { + console.error("Error showing modal:", error); + } +} + +function closeModal() { + try { + const modal = document.getElementById("modal"); + if (modal) { + modal.classList.remove("visible"); + + setTimeout(() => { + modal.style.display = "none"; + }, 300); + } + } catch (error) { + console.error("Error closing modal:", error); + } +} + + +document.addEventListener("DOMContentLoaded", function () { + try { + const closeModalButton = document.getElementById("close-modal"); + const modal = document.getElementById("modal"); + + if (!closeModalButton || !modal) { + throw new Error("Required modal elements not found"); + } + + closeModalButton.addEventListener("click", function () { + try { + modal.classList.add("hidden"); + modal.style.display = "none"; + } catch (error) { + console.error("Error closing modal:", error); + } + }); + + modal.addEventListener("click", function (event) { + try { + if (event.target === event.currentTarget) { + modal.classList.add("hidden"); + modal.style.display = "none"; + } + } catch (error) { + console.error("Error handling modal click:", error); + } + }); + + window.openModal = openModal; + window.closeModal = closeModal; + } catch (error) { + console.error("Error initializing modal event listeners:", error); + } +}); + +window.addEventListener('resize', function() { + try { + const modal = document.getElementById("modal"); + if (!modal) { + throw new Error("Modal element not found"); + } + + if (modal.style.display === "block") { + const wordCloudElement = document.querySelector('.words-cloud'); + if (!wordCloudElement) { + throw new Error("Word cloud element not found"); + } + + const wordCloudRect = wordCloudElement.getBoundingClientRect(); + const modalRect = modal.getBoundingClientRect(); + + + modal.style.left = `${wordCloudRect.left + (wordCloudRect.width - modalRect.width) / 2}px`; + + + const computedStyle = window.getComputedStyle(modal); + let currentTop = parseFloat(computedStyle.top); + + const newTop = currentTop - 50; + modal.style.top = `${newTop}px`; + + console.log('Previous top:', currentTop, 'New top:', newTop); + } + } catch (error) { + console.error("Error handling window resize:", error); + } +}); \ No newline at end of file diff --git a/docs/stylesheets/collapse_section.css b/docs/stylesheets/collapse_section.css new file mode 100644 index 00000000..0bbbc34d --- /dev/null +++ b/docs/stylesheets/collapse_section.css @@ -0,0 +1,111 @@ +.collapse-section { + margin-bottom: 1.5em; + border-radius: 8px; + overflow: hidden; + transition: box-shadow 0.1s ease; + box-shadow: 0 0 0 rgba(0, 0, 0, 0); +} + +.collapse-section:hover { + border-color: transparent; +} + +.collapse-section h2 { + margin: 0; + padding: 1em; + background: var(--collapse-bg-light); + cursor: pointer; + align-items: center; + font-size: 1.2em; + color: #333; + transition: background-color 0.3s ease-in-out; + position: relative; +} + +.collapse-section h2 .headerlink { + position: absolute; + right: 10px; + top: 50%; + transform: translateY(-50%); +} + +.collapse-section h2 .collapse-icon { + margin-right: 30px; + margin-left: 15px; +} + +.collapse-section h2:hover { + background: var(--collapse-hover-bg-light); +} + +.collapse-section.active h2 { + color: #d94412; +} + +[data-md-color-scheme="slate"] .collapse-section { + background-color: #333; +} + +[data-md-color-scheme="slate"] .collapse-section h2 { + background: var(--collapse-bg-dark); + color: #e0e0e0; +} + +[data-md-color-scheme="slate"] .collapse-section h2:hover { + background: var(--collapse-hover-bg-dark); +} + +[data-md-color-scheme="slate"] .collapse-section.active h2 { + color: #ff6e42; +} + +[data-md-color-scheme="slate"] .collapse-section.active h2 { + color: #ff6e42; +} + +.collapse-icon { + transition: transform 0.3s ease; +} + +.collapse-section.active { + max-height: none; +} + +.collapse-section.active .collapse-icon { + transform: rotate(180deg); +} + +.collapse-content { + max-height: 0; + overflow: hidden; + transition: max-height 0.1s ease-in-out; + padding: 0 1em; +} + +.collapse-section.active .collapse-content { + max-height: 100%; + padding: 1em; +} + +[data-md-color-scheme="slate"] .collapse-content { + background-color: #1e2229; + color: #e0e0e0; +} + +.content-wrapper { + display: flex; + flex-direction: column; + min-height: 100vh; + overflow-y: auto; +} + +.article-content { + flex-grow: 1; +} + +.md-footer { + position: sticky; + bottom: 0; + width: 100%; + z-index: 10; +} diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index b56f5af1..31cc8969 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -1,56 +1,190 @@ #welcome { - text-align: center; - margin-bottom: 1em; + text-align: center; + margin-bottom: 1em; } #home-logo { - margin-bottom: 1em; + margin-bottom: 1em; } +:root { + --word-cloud-bg-light: linear-gradient(to right, #faf7f7, #d7d6d6); + --word-cloud-border-light: #e0e0e0; + --word-cloud-shadow-light: rgba(0, 0, 0, 0.05); + --word-cloud-bg-dark: linear-gradient(to right, #2a2a2a, #333333); + --word-cloud-border-dark: #444444; + --word-cloud-shadow-dark: rgba(0, 0, 0, 0.2); + + --collapse-bg-light: linear-gradient(to right, #d7d6d6, #faf7f7); + --collapse-hover-bg-light: linear-gradient(to right, #cdcccc, #dddcdc); + + /* Mode sombre */ + --collapse-bg-dark: linear-gradient(to right, #333333, #2a2a2a); + --collapse-hover-bg-dark: linear-gradient(to right, #3a3a3a, #313131); +} [data-md-color-scheme="slate"] { - --md-hue: 217; - --md-typeset-a-color: #d94412 !important; + --md-hue: 217; + --md-typeset-a-color: #d94412 !important; + --md-accent-keywords-color: hsla(0, 0%, 75%, 1) !important; + --md-icon-color: #a7a7a7; + + --md-glossary-bg-color: #2e2e2e; + --md-glossary-text-color: #e0e0e0; + --md-keyword-cloud-bg-color: #3a3a3a; + --md-keyword-cloud-text-color: #f0f0f0; } [data-md-color-scheme="gpac"] { - /* header background */ - --md-primary-fg-color: #d7d7d7; - /* header text */ - --md-primary-bg-color: #141414; - - --md-primary-fg-color--light: hsla(0, 0, 95%, 1); - --md-primary-fg-color--dark: hsla(0, 0, 25%, 1); - - --md-primary-bg-color--light: hsla(0, 0%, 100%, 0.7); - - --md-accent-fg-color: #d94412; - --md-accent-fg-color--transparent: #d944121f; - --md-accent-bg-color: #d94412; - --md-accent-bg-color--light: #d94412e0; - - --md-typeset-a-color: #d94412; - - /* default is too bright on pourly calibrated screens */ - --md-code-bg-color: #e0e0e0; - - /* - force tabs to match gpac.io styles - */ - .md-tabs__item .md-tabs__link { - transition: unset !important; - background: none !important; - color: inherit!important; - opacity: 1 !important; - } - .md-tabs__item:focus, - .md-tabs__item:hover { - background-color: #151515 !important; - color: #fff !important; - } - - .md-tabs__item--active { - color: var(--md-typeset-a-color); - font-style: italic; - } + /* header background */ + --md-primary-fg-color: #e0e0e0; + /* header text */ + --md-primary-bg-color: #141414; + + --md-primary-fg-color--light: hsla(0, 0%, 95%, 1); + --md-primary-fg-color--dark: hsla(0, 0%, 25%, 1); + + --md-primary-bg-color--light: #f0f0f0; + + --md-accent-fg-color: #d94412; + --md-accent-fg-color--transparent: #d944121f; + --md-accent-keywords-color: hsla(0, 0%, 25%, 1) !important; + --md-accent-bg-color: #d94412; + --md-accent-bg-color--light: #d94412e0; + + --md-typeset-a-color: #d94412; + --md-icon-color: #8e8686; + + /* default is too bright on poorly calibrated screens */ + --md-code-bg-color: #e0e0e0; + + --md-glossary-bg-color: #f5f5f5; + --md-glossary-text-color: #333333; + --md-keyword-cloud-bg-color: #ffffff; + --md-keyword-cloud-text-color: #000000; + + /* force tabs to match gpac.io styles */ + .md-tabs__item .md-tabs__link { + transition: unset !important; + background: none !important; + color: inherit !important; + opacity: 1 !important; + } + .tabs__item:focus, + .md-tabs__item:hover { + background-color: #151515 !important; + color: #fff !important; + } + + .md-tabs__item--active { + color: var(--md-typeset-a-color); + font-style: italic; + } + + .md-header__option { + background-color: var(--md-primary-fg-color) !important; + } +} + +.md-typeset .highlight button { + display: block !important; +} + +.md-footer { + flex-shrink: 0; +} + +.glossary-container, +.words-cloud { + background-color: var(--md-glossary-bg-color); + color: var(--md-glossary-text-color); +} + +.words-cloud-container { + background-color: var(--md-keyword-cloud-bg-color); + color: var(--md-keyword-cloud-text-color); +} + +.words-cloud a { + color: var(--md-typeset-a-color); +} + +.md-sidebar--secondary .md-sidebar__inner { + display: flex; + flex-direction: column; +} + +.md-nav--secondary { + flex: 1; + margin-bottom: 5rem; +} + +.keywords-cloud-container { + max-height: 40vh; + overflow-y: auto; +} + +.md-header__topic { + position: absolute; + width: 100%; + transition: opacity 0.1s ease-in-out, transform 0.1s ease-in-out; +} + +.md-header__topic--site-name { + opacity: 1; + transform: translateX(0); +} + +.md-header__topic--page-title { + opacity: 0; + transform: translateX(20px); +} + +.md-header.show-page-title .md-header__topic--site-name { + opacity: 0; + transform: translateX(-20px); +} + +.md-header.show-page-title .md-header__topic--page-title { + opacity: 1; + transform: translateX(0); +} + +.highlight { + border-radius: 0.5rem; + margin: 1rem 0; + padding: 0.5rem; + position: relative; +} + +.highlight pre { + margin: 0; + padding: 0; +} + +.highlight code { + font-family: "Fira Code", monospace; + font-size: 0.6rem; + line-height: 1.5; +} + +.highlight::before { + content: attr(data-language); + position: absolute; + top: 0.3rem; + right: 0.5rem; + font-size: 0.7rem; + color: #abb2bf; + text-transform: uppercase; +} + +@media screen and (max-width: 76.1875em) { + .md-sidebar--secondary { + display: none; + } +} +@media screen and (max-width: 59.9844em) { + .md-nav__source { + background-color: #ffffff; + } } diff --git a/docs/stylesheets/feedback.css b/docs/stylesheets/feedback.css new file mode 100644 index 00000000..f39e7b90 --- /dev/null +++ b/docs/stylesheets/feedback.css @@ -0,0 +1,115 @@ +.md-feedback__icon.md-icon[data-md-value="1"]:hover svg path { + fill: #45a049; +} +.md-feedback, +.md-nav__feedback { + padding: 1rem; + margin-top: 1rem; + border-top: 1px solid var(--md-default-fg-color--lightest); +} + +.md-feedback p, +.md-nav__feedback p { + margin: 0 0 0.5rem; + font-weight: 700; + font-size: 0.8rem; + color: var(--md-default-fg-color--light); +} + +.md-feedback__inner, +.md-nav__feedback .md-feedback__inner { + display: flex; + flex-direction: column; + align-items: flex-start; +} + +.md-feedback__list, +.md-nav__feedback .md-feedback__list { + display: flex; + justify-content: flex-start; + margin-bottom: 0.5rem; +} + +.md-feedback__icon, +.md-nav__feedback .md-feedback__icon { + margin-right: 0.5rem; + padding: 0.25rem; + background: none; + border: none; + cursor: pointer; + transition: color 0.25s; +} + +.md-feedback__icon:hover, +.md-nav__feedback .md-feedback__icon:hover { + color: var(--md-accent-fg-color); +} + +.md-feedback__contribute, +.md-nav__feedback .md-feedback__contribute { + color: var(--md-default-fg-color--lighter); + transition: color 0.25s, background-color 0.25s; +} + +.md-feedback__contribute:hover, +.md-nav__feedback .md-feedback__contribute:hover { + color: var(--md-accent-fg-color); + background-color: transparent; +} + +.md-feedback__note, +.md-nav__feedback .md-feedback__note { + font-size: 0.7rem; + color: var(--md-default-fg-color--light); + margin-top: 0.5rem; +} + +@media screen and (min-width: 76.25em) { + .md-nav__feedback--desktop { + display: block; + position: fixed; + bottom: 4%; + background-color: var(--md-default-bg-color); + box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1), + 0 4px 6px -2px rgba(0, 0, 0, 0.05); + border-radius: 0.2rem; + } + + .md-feedback--mobile { + display: none; + } +} + +@media screen and (max-width: 76.1875em) { + .md-nav__feedback--desktop { + display: none; + } + + .md-feedback--mobile { + display: block; + background-color: var(--md-default-bg-color); + border-top: 1px solid var(--md-default-fg-color--lightest); + margin-top: 2rem; + margin-left: auto; + margin-right: auto; + width: 75%; + } + .md-feedback__inner { + align-items: center; + } +} + +[data-md-color-scheme="slate"] .md-feedback--mobile, +[data-md-color-scheme="slate"] .md-nav__feedback--desktop { + background-color: var(--md-default-bg-color); +} + +[data-md-color-scheme="slate"] .md-feedback__icon, +[data-md-color-scheme="slate"] .md-nav__feedback .md-feedback__icon { + color: var(--md-default-fg-color--light); +} + +[data-md-color-scheme="slate"] .md-feedback__icon:hover, +[data-md-color-scheme="slate"] .md-nav__feedback .md-feedback__icon:hover { + color: var(--md-accent-fg-color); +} diff --git a/docs/stylesheets/glossary-pages.css b/docs/stylesheets/glossary-pages.css new file mode 100644 index 00000000..558ab371 --- /dev/null +++ b/docs/stylesheets/glossary-pages.css @@ -0,0 +1,6 @@ + + +body.glossary-page h1 { + color: #d94412 !important; + font-weight: bold; +} \ No newline at end of file diff --git a/docs/stylesheets/keyword-cloud.css b/docs/stylesheets/keyword-cloud.css new file mode 100644 index 00000000..04078117 --- /dev/null +++ b/docs/stylesheets/keyword-cloud.css @@ -0,0 +1,137 @@ +.words-cloud-container { + overflow-y: auto; + text-align: center; + border-radius: 8px; + overflow: hidden; + margin-bottom: 1rem; + position: relative; +} +[data-md-color-scheme="slate"] .words-cloud-container { + background-color: #333; +} + +.words-cloud { + padding: 0.5rem; + background: var(--word-cloud-bg-light); + /* border: 1px solid var(--word-cloud-border-light); */ + border-radius: 8px; + margin-right: 1rem; + box-shadow: 0 1px 2px var(--word-cloud-shadow-light); + transition: all 0.3s ease-in-out; +} + +[data-md-color-scheme="slate"] .words-cloud { + background: var(--word-cloud-bg-dark); + border-color: var(--word-cloud-border-dark); + box-shadow: 0 1px 2px var(--word-cloud-shadow-dark); +} +.words-cloud-container:hover .words-cloud { + background-color: #dddcdc; +} + +[data-md-color-scheme="slate"] .words-cloud-container:hover .words-cloud { + background-color: #333; +} + +.words-cloud__title { + font-size: 14px; + text-transform: uppercase; + text-align: center; + padding: 0.5rem; + margin-bottom: 0.5rem; + color: #333; + border-bottom: 1px solid #e0e0e0; +} + +[data-md-color-scheme="slate"] .words-cloud__title { + color: #e0e0e0; + border-bottom-color: #333; +} + +.words-container { + display: flex; + justify-content: center; + align-items: center; + flex-wrap: wrap; +} + +#dynamic-words-cloud { + display: flex; + justify-content: center; + align-items: center; + flex-wrap: wrap; + margin: 0; + padding: 0; + list-style: none; +} + +.words-cloud li { + display: inline-block; + padding: 0.25rem 0.5rem; + transition: transform 0.3s, color 0.3s; +} + +.words-cloud a { + text-decoration: none; +} + +.words-cloud .size-1 { + font-size: 8px; +} +.words-cloud .size-2 { + font-size: 10px; +} +.words-cloud .size-3 { + font-size: 12px; +} +.words-cloud .size-4 { + font-size: 14px; +} +.words-cloud .size-5 { + font-size: 16px; +} + +.words-cloud .color-1 { + color: var(--md-accent-fg-color); +} +.words-cloud .color-2 { + color: #666; +} +.words-cloud .color-3 { + color: #333; +} +.words-cloud .color-4 { + color: #d94412; +} + +[data-md-color-scheme="slate"] .words-cloud .color-1 { + color: var(--md-accent-fg-color); +} +[data-md-color-scheme="slate"] .words-cloud .color-2 { + color: #bbb; +} +[data-md-color-scheme="slate"] .words-cloud .color-3 { + color: #ddd; +} +[data-md-color-scheme="slate"] .words-cloud .color-4 { + color: #ff6633; +} + +.words-cloud li:hover { + transform: scale(1.1); + color: var(--md-accent-fg-color); +} + +.modal-link { + display: inline-block; + margin-top: 1rem; + font-size: 14px; + color: var(--md-accent-fg-color); + text-decoration: none; + border-bottom: 1px dotted var(--md-accent-fg-color); +} + +[data-md-color-scheme="slate"] .modal-link { + color: var(--md-accent-fg-color); + border-bottom-color: var(--md-accent-fg-color); +} diff --git a/docs/stylesheets/levels.css b/docs/stylesheets/levels.css new file mode 100644 index 00000000..ba1c5d92 --- /dev/null +++ b/docs/stylesheets/levels.css @@ -0,0 +1,100 @@ +.hidden-level { + display: none; +} + +.level-tag { + padding: 2px 6px; + border-radius: 4px; + font-size: 0.8em; + font-weight: bold; + margin-right: 15px; +} + +.level-beginner { + background-color: #e6f3e6; + color: #2e7d32; +} +.level-expert { + background-color: #ffebee; + color: #c62828; +} + +[data-md-color-scheme="slate"] .level-beginner { + font-weight: 600; + color: #86efac; + background-color: #14532d; +} + +.switch-container { + display: flex; + align-items: center; +} + +.switch { + position: relative; + display: inline-block; + width: 60px; + height: 34px; +} + +.switch input { + opacity: 0; + width: 0; + height: 0; +} + +.slider { + position: absolute; + cursor: pointer; + top: 10px; + left: 0; + right: 0; + bottom: 0; + background-color: #ccc; + transition: 0.4s; +} + +.slider:before { + position: absolute; + content: ""; + height: 26px; + width: 26px; + left: 4px; + bottom: 0; + background-color: white; + transition: 0.4s; +} + +input:checked + .slider { + background-color: #d94412; +} + +input:checked + .slider:before { + transform: translateX(30px); +} + +.slider.round { + border-radius: 34px; +} + +.slider.round:before { + border-radius: 50%; +} + +.switch-label { + margin-top: 10px; + margin-left: 10px; + font-weight: bold; +} + +.md-nav__item--nested .toc-toggle { + background: none; + border: none; + cursor: pointer; + padding: 0; + margin-right: 5px; +} + +.md-nav__item--nested.toc-collapsed > .md-nav__list { + display: none; +} diff --git a/docs/stylesheets/modal.css b/docs/stylesheets/modal.css new file mode 100644 index 00000000..27bd12c3 --- /dev/null +++ b/docs/stylesheets/modal.css @@ -0,0 +1,162 @@ +.modal { + z-index: 1000; + position: absolute !important; + width: 90%; + width: 200px; + opacity: 0; + visibility: hidden; + transition: opacity 0.3s ease, visibility 0.3s ease; + display: none; +} + +.modal.visible { + opacity: 1 !important; + visibility: visible !important; + display: block !important; + pointer-events: auto !important; +} +.modal-content { + background-color: #e8eaed; + border: 1px solid #e0e0e0; + border-left: none; + border-bottom: none; + box-shadow: 3px 0px 10px rgba(0, 0, 0, 0.1); + border-radius: 4px; + padding: 7px 12px; + width: 100%; + transition: opacity 0.3s ease; +} + +.modal-header { + display: flex; + justify-content: center; + align-items: center; + margin-bottom: 16px; +} + +.modal-header i { + color: #d94412; + font-size: 16px; + margin-right: 8px; +} + +.modal-header h2 { + margin: 0; + font-size: 0.7rem; + font-weight: bold; + color: #333; + cursor: pointer; + transition: background-color 0.3s ease, color 0.3s ease; + padding: 2px 4px; + border-radius: 5px; + background-color: #c5c5c5; + display: inline-flex; + align-items: center; +} + +.modal-header h2::before { + content: "#"; + margin-right: 4px; + color: black; +} + +.modal-header h2:hover { + background-color: #d94412; + color: white; +} + +.modal-header h2:hover::before { + color: white; +} +.modal-content__definition { + font-size: 14px; + line-height: 1.6; + color: #4a4a4a; + text-align: justify; + margin-bottom: 16px; +} + +.modal-close { + position: absolute; + top: 8px; + right: 8px; + background: none; + border: none; + font-size: 18px; + cursor: pointer; + color: #666; + transition: color 0.2s ease; +} + +.modal-close:hover { + color: #d94412; +} + +.modal-link { + display: inline-block; + padding: 3px 6px; + background-color: #d94412; + color: #ffffff !important; + text-decoration: none; + border-radius: 4px; + font-size: 14px; + transition: background-color 0.2s ease; +} + +.modal-link:hover { + background-color: #b23600; +} + +.hidden { + display: none !important; +} + +.modal-aliases { + margin-top: 8px; + font-size: 12px; +} + +.modal-aliases h3 { + font-size: 12px; + margin-bottom: 4px; + color: #333; +} + +.modal-aliases ul { + list-style-type: none; + padding-left: 0; + margin: 0; + display: flex; + flex-wrap: wrap; +} + +.modal-aliases li { + margin-bottom: 2px; +} + +.alias-link { + font-size: 0.45rem; + font-weight: bold; + color: #333 !important; + text-decoration: none; + background-color: #c5c5c5; + padding: 2px 2px; + border-radius: 5px; + transition: background-color 0.3s ease, color 0.3s ease; + align-items: self-start; +} + +.alias-link::before { + content: "#"; + margin-right: 2px; + color: black; +} + +.alias-link:hover { + background-color: #d94412; + color: white !important; +} + +.alias-link:hover::before { + color: white; +} diff --git a/docs/stylesheets/settings.css b/docs/stylesheets/settings.css new file mode 100644 index 00000000..36724d0b --- /dev/null +++ b/docs/stylesheets/settings.css @@ -0,0 +1,144 @@ +.md-header__settings { + position: relative; +} + +.md-header__settings-button { + background: none; + border: none; + color: var(--md-primary-bg-color); + cursor: pointer; + font-size: 1.2rem; + margin-right: 1rem; +} + +.md-header__settings-dropdown { + position: absolute; + top: 120%; + left: -276%; + font-weight: 600; + background-color: var(--md-primary-fg-color); + border-radius: 4px; + box-shadow: 0 2px 5px rgba(0, 0, 0, 0.2); + padding: 0rem 1.5rem; + z-index: 1000; +} + +.md-header__settings-title { + text-align: center; +} +.md-header__settings-separator { + height: 1px; + background: linear-gradient( + to right, + transparent, + var(--md-primary-bg-color, #ffffff) 50%, + transparent + ); + margin: 0.5rem 0 1rem; + opacity: 0.2; + position: relative; +} + +.md-header__settings-separator::before { + content: ""; + position: absolute; + top: -2px; + left: 50%; + transform: translateX(-50%); + width: 6px; + height: 6px; + background-color: var(--md-primary-bg-color, #ffffff); + border-radius: 50%; + opacity: 0.6; +} +.md-header__settings-item { + display: flex; + justify-content: space-between; + align-items: center; + margin-bottom: 0.5rem; + transition: background-color 0.3s ease, border-radius 0.3s ease; +} + +.md-header__settings-item:hover { + opacity: 0.7; + border-radius: 4px; + cursor: pointer; +} +[data-md-color-scheme="slate"] .md-header__settings-item { + transition: background-color 0.3s ease; +} + +[data-md-color-scheme="slate"] .md-header__settings-item:hover { + background-color: #3a3a3a; + cursor: pointer; +} +.switch { + position: relative; + display: inline-block; + width: 40px; + height: 20px; +} + +.switch input { + opacity: 0; + width: 0; + height: 0; +} + +.slider { + position: absolute; + cursor: pointer; + top: 0; + left: 0; + right: 0; + bottom: 0; + background-color: #ccc; + transition: 0.4s; + border-radius: 20px; +} + +.slider:before { + position: absolute; + content: ""; + height: 16px; + width: 16px; + left: 2px; + bottom: 2px; + background-color: white; + transition: 0.4s; + border-radius: 50%; +} + +input:checked + .slider { + background-color: var(--md-accent-fg-color); +} + +input:checked + .slider:before { + transform: translateX(20px); +} + +.slider.round { + border-radius: 30px; +} + +.slider.round:before { + border-radius: 50%; +} +@media screen and (max-width: 1024px) { + .md-header__settings-dropdown { + padding: 0rem 0.5rem; + width: 211%; + left: -120%; + top: 110%; + font-size: 0.7rem; + } + .md-header__settings-button { + margin-right: 2rem; + } + .md-header__settings-item { + margin: 0rem; + } + .md-header__settings-item { + margin-bottom: 1.5rem; + } +} diff --git a/docs/stylesheets/tags.css b/docs/stylesheets/tags.css new file mode 100644 index 00000000..e45454bb --- /dev/null +++ b/docs/stylesheets/tags.css @@ -0,0 +1,65 @@ +#returnButton { + position: fixed; + top: 120px; + left: 20px; + padding: 10px 15px; + background-color: var(--md-primary-fg-color); + color: var(--md-primary-bg-color); + border: none; + border-radius: 50px; + cursor: pointer; + font-weight: 500; + font-size: 14px; + box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1); + transition: all 0.3s ease; + display: flex; + align-items: center; + gap: 8px; + z-index: 10; +} + +#returnButton:hover { + background-color: var(--md-accent-fg-color); + box-shadow: 0 4px 15px rgba(0, 0, 0, 0.15); + transform: translateY(-2px); +} + +#returnButton:active { + transform: translateY(0); + box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1); +} + +#returnButton i { + font-size: 16px; +} + +#returnButton span { + position: relative; + overflow: hidden; + max-width: 0; + opacity: 0; + transition: max-width 0.3s ease, opacity 0.3s ease, margin-left 0.3s ease; +} + +#returnButton:hover span { + max-width: 100px; + opacity: 1; + margin-left: 6px; +} + +@media (max-width: 76.1875em) { + #returnButton { + top: 80px; + left: 10px; + } +} + +[data-md-color-scheme="slate"] #returnButton { + background-color: var(--md-default-bg-color--lightest); + color: var(--md-default-fg-color); +} + +[data-md-color-scheme="slate"] #returnButton:hover { + background-color: var(--md-accent-fg-color); + color: var(--md-default-bg-color); +} diff --git a/docs/stylesheets/toggle.css b/docs/stylesheets/toggle.css new file mode 100644 index 00000000..e258b746 --- /dev/null +++ b/docs/stylesheets/toggle.css @@ -0,0 +1,25 @@ +@media screen and (min-width: 76.25em) { + .md-nav--secondary .md-nav__title .md-nav__icon { + display: block; + } +} +@media screen and (min-width: 76.25em) { + .md-nav__icon { + transition: background-color 0.25s; + } +} +@media screen and (min-width: 76.25em) { + label[for="__toc"] .md-nav__icon.md-icon { + width: auto; + } +} + +@media screen and (min-width: 76.25em) { + .md-nav__icon:hover { + background-color: transparent; + } +} + +.toggle-btn { + display: none; +} diff --git a/docs/stylesheets/top.css b/docs/stylesheets/top.css new file mode 100644 index 00000000..24907f84 --- /dev/null +++ b/docs/stylesheets/top.css @@ -0,0 +1,31 @@ +.md-top.md-icon { + + background-color: #fff !important; + color: #8e8686; + transition: background-color 0.3s ease, color 0.3s ease, border 0.3s ease; +} + +.md-top:focus, .md-top:hover { + background-color: #d7d7d7 !important; + color: black !important; + border: 1px solid var(--md-default-fg-color--light) !important; + transition-duration: 300ms !important; +} + +.md-top[hidden] { + transition-duration: 300ms !important; +} + + +[data-md-color-scheme="slate"] .md-top.md-icon { + background-color: #2e2e2e !important; + color: #a7a7a7; + border: 1px solid #444; +} + +[data-md-color-scheme="slate"] .md-top:focus, +[data-md-color-scheme="slate"] .md-top:hover { + background-color: #3a3a3a !important; + color: #ffffff !important; + border: 1px solid #ff6633 !important; +} \ No newline at end of file diff --git a/docs/tags.md b/docs/tags.md new file mode 100644 index 00000000..d55ad378 --- /dev/null +++ b/docs/tags.md @@ -0,0 +1,20 @@ +--- +hide: +- nav + +--- + +# Tags {.no-collapse} + +Following is a list of relevant tags: + + + + \ No newline at end of file diff --git a/docs/xmlformats/BoxPatch.md b/docs/xmlformats/BoxPatch.md index 24a81fea..a9b31e4b 100644 --- a/docs/xmlformats/BoxPatch.md +++ b/docs/xmlformats/BoxPatch.md @@ -1,4 +1,18 @@ -GPAC allows adding or removing boxes in an ISOBMFF file through patches, in order to customize files. This box patching uses an XML description of where the box should be added or removed, and what the new box content is in case of box addition. +--- +tags: +- pid +- media +- binary +- stream +- xml +- property +- box +- track +--- + + + +_GPAC allows adding or removing boxes in an ISOBMFF file through patches, in order to customize files. This box patching uses an XML description of where the box should be added or removed, and what the new box content is in case of box addition._ The XML syntax used is: diff --git a/docs/xmlformats/Common-Encryption.md b/docs/xmlformats/Common-Encryption.md index 58b8a607..4d4fcf4a 100644 --- a/docs/xmlformats/Common-Encryption.md +++ b/docs/xmlformats/Common-Encryption.md @@ -1,11 +1,44 @@ -MP4Box is able to encrypt and decrypt ISOBMFF files according to CENC specification (ISO/IEC 23001-7:2016), including latest pattern encryption tools introduced in the standard. - -In order to encrypt or decrypt an MP4 file, MP4Box will need a side file containing all information about crypto/DRM system and the information needed to encrypt a given track, hereafter referred as `drm_file`. Sample files are available in [GPAC's test suite](https://github.com/gpac/testsuite/tree/filters/media/encryption). - -The file is an XML with a root element called `GPACDRM` with one or more `CrypTrack` children, zero or more `DRMInfo` children and zero or more `DRMInfoTemplate` children. -Just like any XML file, the file must begin with the usual xml header. The file MUST be encoded in UTF-8. - -## XML Syntax +--- +tags: +- data +- tile +- codec +- isma +- encrypt +- sample +- compression +- stream +- subsample +- xml +- block +- media +- segment +- isobmff +- property +- group +- box +- h264 +- chunk +- track +- mp4 +- source +- packets +- input +- isomedia +- binary +- dash +--- + + + +_MP4Box is able to encrypt and decrypt ISOBMFF files according to CENC specification (ISO/IEC 23001-7:2016), including latest pattern encryption tools introduced in the standard._ + +_In order to encrypt or decrypt an MP4 file, MP4Box will need a side file containing all information about crypto/DRM system and the information needed to encrypt a given track, hereafter referred as `drm_file`. Sample files are available in [GPAC's test suite](https://github.com/gpac/testsuite/tree/filters/media/encryption)._ + +_The file is an XML with a root element called `GPACDRM` with one or more `CrypTrack` children, zero or more `DRMInfo` children and zero or more `DRMInfoTemplate` children._ +_Just like any XML file, the file must begin with the usual xml header. The file MUST be encoded in UTF-8._ + +# XML Syntax {: data-level="all"} ```xml @@ -19,7 +52,7 @@ Just like any XML file, the file must begin with the usual xml header. The file ``` -## GPACDRM Element Semantics +# GPACDRM Element Semantics * `type` : is the default protection scheme type used for all tracks in the source media file. The possible values are (full name or 4 char code): * **ISMA** or **iAEC**: ISMA E&A (ISMACryp) Scheme @@ -52,7 +85,7 @@ The payload of a DRMInfo describing a PSSH blob can be encrypted using AES-128 C The following example shows a simple GPAC DRM system info: - ### Simple GPAC DRM system info +### Simple GPAC DRM system info ```xml diff --git a/docs/xmlformats/ISMACryp.md b/docs/xmlformats/ISMACryp.md index 76dd825f..01e2d3c2 100644 --- a/docs/xmlformats/ISMACryp.md +++ b/docs/xmlformats/ISMACryp.md @@ -1,4 +1,22 @@ -# ISMACryp authoring +--- +tags: +- isma +- encrypt +- mp4 +- source +- media +- isomedia +- isobmff +- data +- stream +- xml +- mpeg +- track +--- + + + +# ISMACryp authoring {: data-level="all"} In order to encrypt an MP4 file, MP4Box will need a specific file containing all cryptographic information, usually referred to as `drm_file` in MP4Box documentation. The command line is as follows: diff --git a/docs/xmlformats/NHML-Format.md b/docs/xmlformats/NHML-Format.md index fcf89bbb..25c75ff5 100644 --- a/docs/xmlformats/NHML-Format.md +++ b/docs/xmlformats/NHML-Format.md @@ -1,3 +1,38 @@ +--- +tags: +- pid +- data +- codec +- sample +- packet +- compression +- frame +- subsample +- xml +- stream +- hevc +- bitstream +- sequence +- scene +- media +- isobmff +- decoder +- property +- group +- box +- track +- profile +- mp4 +- source +- input +- isomedia +- binary +- decoding +- mpeg +--- + + + # NHML Overview The `NHML` (Network Hint Markup Language) format has been developed at Telecom Paris in order to provide import support on media formats not natively supported by GPAC, typically for ISOBMFF file constructions. It is an XML translation and extension of a binary format called [[NHNT Format]] used during the development of MPEG-4 Systems. diff --git a/docs/xmlformats/NHNT-Format.md b/docs/xmlformats/NHNT-Format.md index bf4524e6..871ac01f 100644 --- a/docs/xmlformats/NHNT-Format.md +++ b/docs/xmlformats/NHNT-Format.md @@ -1,4 +1,30 @@ -# NHNT Overview +--- +tags: +- data +- codec +- multiplexer +- sample +- frame +- stream +- encode +- bitstream +- bitrate +- sequence +- media +- decoder +- track +- mp4 +- source +- input +- nhnt +- decoding +- mpeg +- encoder +--- + + + +# NHNT Overview {: data-level="all"} The NHNT format has been developed during the MPEG-4 Systems implementation phase, as a way to easily mux unknown media formats to an MP4 file or an MPEG-4 multiplex. The goal was to have the media encoder produce a description of the media time fragmentation (access units and timestamps) that could be reused by a media-unaware MPEG-4 multiplexer. A NHNT source is composed of 2 or 3 parts: diff --git a/docs/xmlformats/OMA-DRM.md b/docs/xmlformats/OMA-DRM.md index 2133de7f..d258d321 100644 --- a/docs/xmlformats/OMA-DRM.md +++ b/docs/xmlformats/OMA-DRM.md @@ -1,4 +1,16 @@ -# OMA DRM authoring +--- +tags: +- mp4 +- encrypt +- data +- stream +- xml +- track +--- + + + +# OMA DRM authoring {: data-level="all"} In order to encrypt a 3GP/MP4 file into a PDCF file, MP4Box uses the same process as CENC or ISMA encryption, only the drm file syntax changes. diff --git a/docs/xmlformats/TTXT-Format-Documentation.md b/docs/xmlformats/TTXT-Format-Documentation.md index 7d796b4a..964778f2 100644 --- a/docs/xmlformats/TTXT-Format-Documentation.md +++ b/docs/xmlformats/TTXT-Format-Documentation.md @@ -1,4 +1,32 @@ -# Foreword +--- +tags: +- data +- connection +- sample +- session +- stream +- encode +- xml +- bitstream +- sequence +- scene +- link +- media +- decoder +- property +- box +- track +- latency +- option +- layer +- decoding +- mpeg +- bifs +--- + + + +# Foreword {: data-level="all"} The 3GPP consortium has defined a standard for text streaming, independent of any scene description such as SMIL, SVG or BIFS: 3GPP Timed Text. MP4Box supports this standard and uses its own textual format to describe a streaming text session. diff --git a/docs/xmlformats/XML-Binary.md b/docs/xmlformats/XML-Binary.md index cadbbbd8..6c1eb2ea 100644 --- a/docs/xmlformats/XML-Binary.md +++ b/docs/xmlformats/XML-Binary.md @@ -1,3 +1,26 @@ +--- +tags: +- mp4 +- encrypt +- source +- sample +- pid +- input +- media +- binary +- data +- isobmff +- xml +- stream +- filter +- bitstream +- property +- box +- track +--- + + + It is possible to describe bit sequences when importing XML data. This applies to: - [NHML](NHML-Format): some elements in the format may or must have child bitstream constructors diff --git a/docs/xmlformats/xmlformats.md b/docs/xmlformats/xmlformats.md index 89893bff..28c53116 100644 --- a/docs/xmlformats/xmlformats.md +++ b/docs/xmlformats/xmlformats.md @@ -1 +1,8 @@ +--- +tags: +- xml +--- + + + This part of the wiki describes the syntax of the different XML formats used by some filters in GPAC. diff --git a/mkdocs.yml b/mkdocs.yml index 440a1754..b5f67a38 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,10 +1,38 @@ site_name: GPAC wiki site_url: https://wiki.gpac.io/ site_author: GPAC contributors +extra: + + keywords_file: 'data/keywords.json' +extra_javascript: + - javascripts/levels.js + - javascripts/main.js + - javascripts/fetchFunctions.js + - javascripts/domManipulation.js + - javascripts/keywordsFinder.js + - javascripts/keywordsDisplay.js + - javascripts/cache.js + - javascripts/modalFunctions.js + + + + extra_css: - stylesheets/extra.css + - stylesheets/keyword-cloud.css + - stylesheets/top.css + - stylesheets/toggle.css + - stylesheets/modal.css + - stylesheets/glossary-pages.css + - stylesheets/collapse_section.css + - stylesheets/feedback.css + - stylesheets/levels.css + - stylesheets/settings.css + - stylesheets/tags.css + - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css theme: name: material + custom_dir: overrides logo: images/gpac-logo.svg favicon: images/favicon-32x32.png palette: @@ -25,12 +53,13 @@ theme: icon: material/brightness-4 name: Switch to light mode features: + - navigation.top - tables - def_list + - content.code.select - content.code.annotate - content.code.copy - content.tooltips - - navigation.expand - navigation.path - navigation.tabs - navigation.tracking @@ -42,18 +71,36 @@ theme: repo_url: https://github.com/gpac/gpac/ plugins: - search - - tags + - tags: + tags_file: tags.md + + hooks: - scripts/mkdocs_hooks.py markdown_extensions: - - admonition - - attr_list - - toc: +- pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- admonition +- attr_list +- toc: permalink: true - - nl2br - - sane_lists - - pymdownx.details - - pymdownx.superfences +- nl2br +- sane_lists +- md_in_html + +- pymdownx.snippets +- pymdownx.details +- pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + +- pymdownx.inlinehilite + + extra: analytics: provider: google @@ -73,27 +120,29 @@ extra: Thanks for your feedback! nav: - Howtos: + - Howtos/howtos.md - - Filters One-Liners: Howtos/filters-oneliners.md - - File Inspection: Howtos/inspecting.md - - Using RAW formats: Howtos/raw-formats.md - - Encoding: Howtos/encoding.md - - Using data pipes: Howtos/pipes.md - - Using sockets: Howtos/sockets.md - - MP4Box vs gpac: Howtos/gpac-mp4box.md - - MP4Box and filters: Howtos/mp4box-filters.md - - Custom ISOBMFF files: Howtos/custom-boxes.md - - Logging in GPAC: Howtos/The-GPAC-Log-System.md - - Audio-Video Mixer: Howtos/avmix_tuto.md - - Dynamic Rate Control: Howtos/dynamic_rc.md - - In-place Editing: Howtos/mp4box-inplace.md - - Working with Network Captures: Howtos/network-capture.md - - GPAC and NodeJS: Howtos/nodejs.md - - Playlists/Splicing/Ad Insertion: Howtos/playlist.md - - GPAC and Python: Howtos/python.md - - Simulating Real-Time sources: Howtos/realtime.md - - ROUTE & ATSC3.0 services: Howtos/route.md - - SCTE-35, id3 markers, dynamic metadata: Howtos/scte35-markers.md + - Command Operations: + - Filters One-Liners: Howtos/filters-oneliners.md + - File Inspection: Howtos/inspecting.md + - Using RAW formats: Howtos/raw-formats.md + - Encoding: Howtos/encoding.md + - Using data pipes: Howtos/pipes.md + - Using sockets: Howtos/sockets.md + - MP4Box vs gpac: Howtos/gpac-mp4box.md + - MP4Box and filters: Howtos/mp4box-filters.md + - Custom ISOBMFF files: Howtos/custom-boxes.md + - Logging in GPAC: Howtos/The-GPAC-Log-System.md + - Audio-Video Mixer: Howtos/avmix_tuto.md + - Dynamic Rate Control: Howtos/dynamic_rc.md + - In-place Editing: Howtos/mp4box-inplace.md + - Working with Network Captures: Howtos/network-capture.md + - GPAC and NodeJS: Howtos/nodejs.md + - Playlists/Splicing/Ad Insertion: Howtos/playlist.md + - GPAC and Python: Howtos/python.md + - Simulating Real-Time sources: Howtos/realtime.md + - ROUTE & ATSC3.0 services: Howtos/route.md + - SCTE-35, id3 markers, dynamic metadata: Howtos/scte35-markers.md - DASH & HLS: - Introduction: Howtos/dash/DASH-intro.md - MPEG-DASH basics: Howtos/dash/DASH-basics.md @@ -355,4 +404,4 @@ nav: - XML Binary Format: xmlformats/XML-Binary.md - TTXT Format: xmlformats/TTXT-Format-Documentation.md - NHML format: xmlformats/NHML-Format.md - - NHNT format: xmlformats/NHNT-Format.md + - NHNT format: xmlformats/NHNT-Format.md \ No newline at end of file diff --git a/overrides/404.html b/overrides/404.html new file mode 100644 index 00000000..3a696109 --- /dev/null +++ b/overrides/404.html @@ -0,0 +1,168 @@ +{#- This file was automatically generated - do not edit -#} +{% extends "main.html" %} +{% block content %} +

+ GPAC Logo +

404 - Page Not Found

+
+ + + + +
+ + + + +{% endblock %} \ No newline at end of file diff --git a/overrides/base.html b/overrides/base.html new file mode 100644 index 00000000..66cfd32f --- /dev/null +++ b/overrides/base.html @@ -0,0 +1,352 @@ +{#- + This file was automatically generated - do not edit +-#} +{% import "partials/language.html" as lang with context %} + + + + {% block site_meta %} + + + {% if page.meta and page.meta.description %} + + {% elif config.site_description %} + + {% endif %} + {% if page.meta and page.meta.author %} + + {% elif config.site_author %} + + {% endif %} + {% if page.canonical_url %} + + {% endif %} + {% if page.previous_page %} + + {% endif %} + {% if page.next_page %} + + {% endif %} + {% if "rss" in config.plugins %} + + + {% endif %} + + + {% endblock %} + {% block htmltitle %} + {% if page.meta and page.meta.title %} + {{ page.meta.title }} - {{ config.site_name }} + {% elif page.title and not page.is_homepage %} + {{ page.title | striptags }} - {{ config.site_name }} + {% else %} + {{ config.site_name }} + {% endif %} + {% endblock %} + {% block styles %} + + {% if config.theme.palette %} + {% set palette = config.theme.palette %} + + {% endif %} + + {% include "partials/icons.html" %} + {% endblock %} + {% block libs %} + {% for script in config.extra.polyfills %} + {{ script | script_tag }} + {% endfor %} + {% endblock %} + {% block fonts %} + {% if config.theme.font != false %} + {% set text = config.theme.font.get("text", "Roboto") %} + {% set code = config.theme.font.get("code", "Roboto Mono") %} + + + + {% endif %} + {% endblock %} + {% for path in config.extra_css %} + + {% endfor %} + {% include "partials/javascripts/base.html" %} + {% block analytics %} + {% include "partials/integrations/analytics.html" %} + {% endblock %} + {% if page.meta and page.meta.meta %} + {% for tag in page.meta.meta %} + + {% endfor %} + {% endif %} + {% block extrahead %}{% endblock %} + + + + + {% set direction = config.theme.direction or lang.t("direction") %} + {% if config.theme.palette %} + {% set palette = config.theme.palette %} + {% if not palette is mapping %} + {% set palette = palette | first %} + {% endif %} + {% set scheme = palette.scheme | d("default", true) %} + {% set primary = palette.primary | d("indigo", true) %} + {% set accent = palette.accent | d("indigo", true) %} + + {% else %} + + {% endif %} + {% set features = config.theme.features or [] %} + + + + +
+ {% if page.toc | first is defined %} + {% set skip = page.toc | first %} + + {{ lang.t("action.skip") }} + + {% endif %} +
+
+ {% if self.announce() %} + + {% endif %} +
+ {% if config.extra.version %} + + {% endif %} + {% block header %} + {% include "partials/header.html" %} + {% endblock %} +
+ {% block hero %}{% endblock %} + {% block tabs %} + {% if "navigation.tabs.sticky" not in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} + {% endblock %} +
+
+ {% block site_nav %} + {% if nav %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "navigation" in page.meta.hide %} + {% endif %} + + {% endif %} + {% if "toc.integrate" not in features %} + {% if page.meta and page.meta.hide %} + {% set hidden = "hidden" if "toc" in page.meta.hide %} + {% endif %} + + + {% endif %} + {% endblock %} + {% block container %} +
+
+ {% block content %} + {% include "partials/content.html" %} + {% endblock %} +
+
+ {% endblock %} + {% include "partials/javascripts/content.html" %} +
+ {% if config.extra.analytics %} + {% set feedback = config.extra.analytics.feedback %} + {% if feedback %} +
+

{{ feedback.title }}

+
+
+ {% for rating in feedback.ratings %} + + {% endfor %} + + {% include ".icons/material/plus-circle.svg" %} + +
+ +
+
+ {% endif %} + {% endif %} + + + + {% if "navigation.top" in features %} + {% include "partials/top.html" %} + {% endif %} +
+ {% block footer %} + {% include "partials/footer.html" %} + {% endblock %} +
+
+
+
+ {% if "navigation.instant.progress" in features %} + {% include "partials/progress.html" %} + {% endif %} + {% if config.extra.consent %} + + {% include "partials/javascripts/consent.html" %} + {% endif %} + {% block config %} + {%- set app = { + "base": base_url, + "features": features, + "translations": {}, + "search": "assets/javascripts/workers/search.07f07601.min.js" | url + } -%} + {%- if config.extra.version -%} + {%- set mike = config.plugins.get("mike") -%} + {%- if not mike or mike.config.version_selector -%} + {%- set _ = app.update({ "version": config.extra.version }) -%} + {%- endif -%} + {%- endif -%} + {%- if config.extra.tags -%} + {%- set _ = app.update({ "tags": config.extra.tags }) -%} + {%- endif -%} + {%- set translations = app.translations -%} + {%- for key in [ + "clipboard.copy", + "clipboard.copied", + "search.result.placeholder", + "search.result.none", + "search.result.one", + "search.result.other", + "search.result.more.one", + "search.result.more.other", + "search.result.term.missing", + "select.version" + ] -%} + {%- set _ = translations.update({ key: lang.t(key) }) -%} + {%- endfor -%} + + {% endblock %} + {% block scripts %} + + + + {% for script in config.extra_javascript %} + {{ script | script_tag }} + {% endfor %} + {% endblock %} + + + + \ No newline at end of file diff --git a/overrides/main.html b/overrides/main.html new file mode 100644 index 00000000..d2c31128 --- /dev/null +++ b/overrides/main.html @@ -0,0 +1,10 @@ +{#- + This file was automatically generated - do not edit + -#} + {% extends "base.html" %} + + {% block content %} +
+ {{ page.content }} +
+{% endblock %} \ No newline at end of file diff --git a/overrides/partials/feedback.html b/overrides/partials/feedback.html new file mode 100644 index 00000000..d48551f3 --- /dev/null +++ b/overrides/partials/feedback.html @@ -0,0 +1,50 @@ + + + \ No newline at end of file diff --git a/overrides/partials/header.html b/overrides/partials/header.html new file mode 100644 index 00000000..5771a03a --- /dev/null +++ b/overrides/partials/header.html @@ -0,0 +1,111 @@ +{#- + This file was automatically generated - do not edit +-#} +{% set class = "md-header" %} +{% if "navigation.tabs.sticky" in features %} + {% set class = class ~ " md-header--shadow md-header--lifted" %} +{% elif "navigation.tabs" not in features %} + {% set class = class ~ " md-header--shadow" %} +{% endif %} +
+ + + + + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
\ No newline at end of file diff --git a/overrides/partials/keywords-cloud.html b/overrides/partials/keywords-cloud.html new file mode 100644 index 00000000..f0b54115 --- /dev/null +++ b/overrides/partials/keywords-cloud.html @@ -0,0 +1,28 @@ + + + \ No newline at end of file diff --git a/overrides/partials/nav-items.html b/overrides/partials/nav-items.html new file mode 100644 index 00000000..5089a60e --- /dev/null +++ b/overrides/partials/nav-items.html @@ -0,0 +1,152 @@ +{#- + This file was automatically generated - do not edit + -#} + {% macro render_status(nav_item, type) %} + {% set class = "md-status md-status--" ~ type %} + {% if config.extra.status and config.extra.status[type] %} + + + {% else %} + + {% endif %} + {% endmacro %} + {% macro render_content(nav_item, ref = nav_item) %} + {% if nav_item.is_page and nav_item.meta.icon %} + {% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %} + {% endif %} + + {{ ref.title }} + + {% if nav_item.is_page and nav_item.meta.status %} + {{ render_status(nav_item, nav_item.meta.status) }} + {% endif %} + {% endmacro %} + {% macro render_pruned(nav_item, ref = nav_item) %} + {% set first = nav_item.children | first %} + {% if first and first.children %} + {{ render_pruned(first, ref) }} + {% else %} + + {{ render_content(ref) }} + {% if nav_item.children | length > 0 %} + + {% endif %} + + {% endif %} + {% endmacro %} + {% macro render(nav_item, path, level) %} + {% set class = "md-nav__item" %} + {% if nav_item.active %} + {% set class = class ~ " md-nav__item--active" %} + {% endif %} + {% if nav_item.pages %} + {% if page in nav_item.pages %} + {% set nav_item = page %} + {% endif %} + {% endif %} + {% if nav_item.children %} + {% set indexes = [] %} + {% if "navigation.indexes" in features %} + {% for nav_item in nav_item.children %} + {% if nav_item.is_index and not index is defined %} + {% set _ = indexes.append(nav_item) %} + {% endif %} + {% endfor %} + {% endif %} + {% if "navigation.tabs" in features %} + {% if level == 1 and nav_item.active %} + {% set class = class ~ " md-nav__item--section" %} + {% set is_section = true %} + {% endif %} + {% if "navigation.sections" in features %} + {% if level == 2 and nav_item.parent.active %} + {% set class = class ~ " md-nav__item--section" %} + {% set is_section = true %} + {% endif %} + {% endif %} + {% elif "navigation.sections" in features %} + {% if level == 1 %} + {% set class = class ~ " md-nav__item--section" %} + {% set is_section = true %} + {% endif %} + {% endif %} + {% if "navigation.prune" in features %} + {% if not is_section and not nav_item.active %} + {% set class = class ~ " md-nav__item--pruned" %} + {% set is_pruned = true %} + {% endif %} + {% endif %} +
  • + {% if not is_pruned %} + {% set checked = "checked" if nav_item.active %} + {% if "navigation.expand" in features and not checked %} + {% set indeterminate = "md-toggle--indeterminate" %} + {% endif %} + + {% if not indexes %} + {% set tabindex = "0" if not is_section %} + + {% else %} + {% set index = indexes | first %} + {% set class = "md-nav__link--active" if index == page %} +
    + + {{ render_content(index, nav_item) }} + + {% if nav_item.children | length > 1 %} + {% set tabindex = "0" if not is_section %} + + {% endif %} +
    + {% endif %} + + {% else %} + {{ render_pruned(nav_item) }} + {% endif %} +
    • + {% elif nav_item == page %} +
  • + {% set toc = page.toc %} + + {% set first = toc | first %} + {% if first and first.level == 1 %} + {% set toc = first.children %} + {% endif %} + {% if toc %} + + {% endif %} + + {{ render_content(nav_item) }} + + {% if toc %} + {% include "partials/toc.html" %} + {% endif %} +
    • + {% else %} +
  • + + {{ render_content(nav_item) }} + +
    • + {% endif %} + {% endmacro %} \ No newline at end of file diff --git a/overrides/partials/nav.html b/overrides/partials/nav.html new file mode 100644 index 00000000..38a2d63a --- /dev/null +++ b/overrides/partials/nav.html @@ -0,0 +1,31 @@ +{#- + This file was automatically generated - do not edit + -#} + {% import "partials/nav-item.html" as item with context %} + {% set class = "md-nav md-nav--primary" %} + {% if "navigation.tabs" in features %} + {% set class = class ~ " md-nav--lifted" %} + {% endif %} + {% if "toc.integrate" in features %} + {% set class = class ~ " md-nav--integrated" %} + {% endif %} + \ No newline at end of file diff --git a/overrides/partials/search.html b/overrides/partials/search.html new file mode 100644 index 00000000..44a023bf --- /dev/null +++ b/overrides/partials/search.html @@ -0,0 +1,44 @@ + +{#- + This file was automatically generated - do not edit + -#} + + \ No newline at end of file diff --git a/overrides/partials/toc-item.html b/overrides/partials/toc-item.html new file mode 100644 index 00000000..eac8d153 --- /dev/null +++ b/overrides/partials/toc-item.html @@ -0,0 +1,19 @@ +{#- + This file was automatically generated - do not edit + -#} +
  • + + + {{ toc_item.title }} + + + {% if toc_item.children %} + + {% endif %} +
    • \ No newline at end of file diff --git a/overrides/partials/toc.html b/overrides/partials/toc.html new file mode 100644 index 00000000..305ace79 --- /dev/null +++ b/overrides/partials/toc.html @@ -0,0 +1,29 @@ +{#- + This file was automatically generated - do not edit + -#} + {% set title = lang.t("toc") %} + {% if config.mdx_configs.toc and config.mdx_configs.toc.title %} + {% set title = config.mdx_configs.toc.title %} + {% endif %} + \ No newline at end of file diff --git a/overrides/partials/top.html b/overrides/partials/top.html new file mode 100644 index 00000000..0095af3f --- /dev/null +++ b/overrides/partials/top.html @@ -0,0 +1,8 @@ +{#- + This file was automatically generated - do not edit + -#} + \ No newline at end of file