base on GStreamer open-source multimedia framework # GStreamer This is GStreamer, a framework for streaming media. ## Where to start We have a website at https://gstreamer.freedesktop.org Our documentation, including tutorials, API reference and FAQ can be found at https://gstreamer.freedesktop.org/documentation/ You can ask questions on the GStreamer Discourse at https://discourse.gstreamer.org/ We track bugs, feature requests and merge requests (patches) in GitLab at https://gitlab.freedesktop.org/gstreamer/ You can join us on our Matrix room at https://matrix.to/#/#gstreamer:gstreamer.org This repository contains all official modules supported by the GStreamer community which can be found in the `subprojects/` directory. ## Getting started ### Install git and python 3.8+ If you're on Linux, you probably already have these. On macOS, new versions of Xcode ship Python 3 already. If you're on an older Xcode, you can use the [official Python installer](https://www.python.org/downloads/mac-osx/). You can find [instructions for Windows below](#windows-prerequisites-setup). ### Install meson and ninja Meson 1.1 or newer is required. On Linux and macOS you can get meson through your package manager or using: ``` $ pip3 install --user meson ``` This will install meson into `~/.local/bin` which may or may not be included automatically in your PATH by default. You should get `ninja` using your package manager or download the [official release](https://github.com/ninja-build/ninja/releases) and put the `ninja` binary in your PATH. You can find [instructions for Windows below](#windows-prerequisites-setup). If you used the official Python installer on macOS instead of the Python 3 shipped with Xcode, you might need to execute "Install Certificates.command" from the Python folder in the user Applications folder: ``` $ /Applications/Python\ 3.*/Install\ Certificates.command ``` Otherwise you will get this error when downloading meson wraps: ``` urllib.error.URLError: urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed ``` ### Build GStreamer and its modules You can get all GStreamer built running: ``` meson setup builddir meson compile -C builddir ``` This will automatically create the `builddir` directory and build everything inside it. NOTE: On Windows, meson will automatically detect and use the latest Visual Studio if GCC, clang, etc are not available in `PATH`. Use the `--vsenv` argument to force the use of Visual Studio. NOTE: Meson will not update subprojects automatically once a subproject has been fetched. Remember to update subprojects if wrap files are updated. ``` meson subprojects update ``` ### External dependencies All mandatory dependencies of GStreamer are included as [meson subprojects](https://mesonbuild.com/Subprojects.html): libintl, zlib, libffi, glib. Some optional dependencies are also included as subprojects, such as ffmpeg, x264, json-glib, graphene, openh264, orc, etc. Mandatory dependencies will be automatically built if meson cannot find them on your system using pkg-config. The same is true for optional dependencies that are included as subprojects. You can find a full list by looking at the `subprojects` directory. Plugins that need optional dependencies that aren't included can only be built if they are provided by the system. Instructions on how to build some common ones such as Qt5/QML are listed below. If you do not know how to provide an optional dependency needed by a plugin, you should use [Cerbero](https://gitlab.freedesktop.org/gstreamer/cerbero/#description) which handles this for you automatically. Plugins will be automatically enabled if possible, but you can ensure that a particular plugin (especially if it has external dependencies) is built by enabling the gstreamer repository that ships it and the plugin inside it. For example, to enable the Qt5 plugin in the gst-plugins-good repository, you need to run meson as follows: ``` meson -Dgood=enabled -Dgst-plugins-good:qt5=enabled builddir ``` This will cause Meson to error out if the plugin could not be enabled. You can also flip the default and disable all plugins except those explicitly enabled like so: ``` meson -Dauto_features=disabled -Dgstreamer:tools=enabled -Dbad=enabled -Dgst-plugins-bad:openh264=enabled ``` This will disable all optional features and then enable the `openh264` plugin and the tools that ship with the core gstreamer repository: `gst-inspect-1.0`, `gst-launch-1.0`, etc. As usual, you can change these values on a builddir that has already been setup with `meson configure -Doption=value`. ### Building the Qt5 QML plugin If `qmake` is not in `PATH` and pkgconfig files are not available, you can point the `QMAKE` env var to the Qt5 installation of your choosing before running `meson` as shown above. The plugin will be automatically enabled if possible, but you can ensure that it is built by passing `-Dgood=enabled -Dgst-plugins-good:qt5=enabled` to `meson`. ### Building the Intel MSDK plugin On Linux, you need to have development files for `libmfx` installed. On Windows, if you have the [Intel Media SDK](https://software.intel.com/en-us/media-sdk), it will set the `INTELMEDIASDKROOT` environment variable, which will be used by the build files to find `libmfx`. The plugin will be automatically enabled if possible, but you can ensure it by passing `-Dbad=enabled -Dgst-plugins-bad:msdk=enabled` to `meson`. ### Building plugins with (A)GPL-licensed dependencies Some plugins have GPL- or AGPL-licensed dependencies and will only be built if you have explicitly opted in to allow (A)GPL-licensed dependencies by passing `-Dgpl=enabled` to Meson. List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-bad: - dts (DTS audio decoder plugin) - faad (Free AAC audio decoder plugin) - iqa (Image quality assessment plugin based on dssim-c) - mpeg2enc (MPEG-2 video encoder plugin) - mplex (audio/video multiplexer plugin) - ofa (Open Fingerprint Architecture library plugin) - resindvd (Resin DVD playback plugin) - x265 (HEVC/H.265 video encoder plugin) List of plugins with (A)GPL-licensed dependencies (non-exhaustive) in gst-plugins-ugly: - a52dec (Dolby Digital (AC-3) audio decoder plugin) - cdio (CD audio source plugin based on libcdio) - dvdread (DVD video source plugin based on libdvdread) - mpeg2dec (MPEG-2 video decoder plugin based on libmpeg2) - sidplay (Commodore 64 audio decoder plugin based on libsidplay) - x264 (H.264 video encoder plugin based on libx264) ### Static build Since *1.18.0*, when doing a static build using `--default-library=static`, a shared library `gstreamer-full-1.0`, in addition to a package config file, will be produced and includes all enabled GStreamer plugins and libraries. A list of libraries that needs to be exposed in `gstreamer-full-1.0` ABI can be set using `gst-full-libraries` option. glib-2.0, gobject-2.0 and gstreamer-1.0 are always included. ``` meson setup --default-library=static -Dgst-full-libraries=gstreamer-app-1.0,gstreamer-video-1.0 builddir ``` GStreamer *1.18* requires applications using gstreamer-full-1.0 to initialize static plugins by calling `gst_init_static_plugins()` after `gst_init()`. That function is defined in `gst/gstinitstaticplugins.h` header file. Since *1.20.0*, `gst_init_static_plugins()` is called automatically by `gst_init()` and applications don't have to call it manually any more. The header file has been removed from public API. One can use the `gst-full-version-script` option to pass a [version script](https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html) to the linker. This can be used to control the exact symbols that are exported by the `gstreamer-full` library, allowing the linker to garbage collect unused code and so, reduce the total library size. A default script `gstreamer-full-default.map` declares only glib/gstreamer symbols as public. One can use the `gst-full-plugins` option to pass a list of plugins to be registered in the `gstreamer-full` library. The default value is '*' which means that all the plugins selected during the build process will be registered statically. An empty value will prevent any plugins to be registered. One can select a specific set of features with `gst-full-elements`, `gst-full-typefind-functions`, `gst-full-device-providers` or `gst-full-dynamic-types` to select specific feature from a plugin. When a feature has been listed in one of those options, the other features from its plugin will no longer be automatically included, even if the plugin is listed in `gst-full-plugins`. The user must insure that all selected plugins and features (element, typefind, etc.) have been enabled during the build configuration. To register features, the syntax is the following: plugins are separated by ';' and features from a plugin starts after ':' and are ',' separated. As an example: * `-Dgst-full-plugins=coreelements;typefindfunctions;alsa;pbtypes`: Enable only `coreelements`, `typefindfunctions`, `alsa`, `pbtypes` plugins. * `-Dgst-full-elements=coreelements:filesrc,fakesink,identity;alsa:alsasrc`: Enable only `filesrc`, `identity` and `fakesink` elements from `coreelements` plugin and `alsasrc` element from `alsa` plugin. * `-Dgst-full-typefind-functions=typefindfunctions:wav,flv`: Enable only typefind func `wav` and `flv` from `typefindfunctions` * `-Dgst-full-device-providers=alsa:alsadeviceprovider`: Enable `alsadeviceprovider` from `alsa` plugin. * `-Dgst-full-dynamic-types=pbtypes:video_multiview_flagset`: Enable `video_multiview_flagset` from `pbtypes`. All features from the `playback` plugin will be enabled and the other plugins will be restricted to the specific features requested. All the selected features will be registered into a dedicated `NULL` plugin name. This will cause the features/plugins that are not registered to not be included in the final gstreamer-full library. This is an experimental feature, backward incompatible changes could still be made in the future. Only linux-like platforms are currently well supported when Windows, MSVC and MinGW, should be considered as *experimental* as the symbols export is still under discussion. Since 1.24.7, it is possible to disable the `gstreamer-full` library by passing `-Dgst-full=disabled`. This can be useful in cases where you want a static build of gstreamer, but you do not want to use gst-full, since linking the static executables associated with it can be quite CPU/RAM intensive. #### Full-static build Since *1.24.0*, it is also possible to link an application with GStreamer statically. It means that all the gstreamer libraries will be linked within your library or application. However, it is important to note that even though the `gstreamer-full` library can be statically built into the application, it does not contain all of the code (core libraries and plugins). Instead, it relies on all the other static libraries. Hence, while the `gstreamer-full` library provides a cohesive access point, the actual functionality is distributed across various static libraries. You can enable this option using `-Dgst-full-target-type=static_library` which is by default set to `shared_library`. The buildsystem will produce a set of archives depending on your `gstreamer-full` configuration as explained above. Your application can now check the `gstreamer-full` dependency within meson or with the package config file. In both case, the application can rely on the `gstreamer-full-1.0.pc` file generated during the build process to retrieve all its dependencies. In that configuration, the *features* selected during the build configuration will be automatically registered during the call of `gst_init()`. ### Building documentation Documentation is not built by default because it is slow to generate. To build the documentation, first ensure that `hotdoc` is installed and `doc` option is enabled. For API documentation, gobject introspection must also be enabled. The special target `gst-doc` can then be used to (re)generate the documentation. ```sh $ pip install hotdoc $ meson setup -Ddoc=enabled -Dintrospection=enabled builddir $ meson compile -C builddir gst-doc ``` NOTE: To visualize the documentation, `devhelp` can be run inside the development environment (see below). # Development environment ## Development environment target GStreamer ships a script that drops you into a development environment where all the plugins, libraries, and tools you just built are available: ``` ./gst-env.py ``` Or with a custom builddir (i.e., not `build`, `_build` or `builddir`): ``` ./gst-env.py --builddir <BUILDDIR> ``` You can also use `ninja devenv` inside your build directory to achieve the same effect. However, this may not work on Windows if meson has auto-detected the visual studio environment. Alternatively, if you'd rather not start a shell in your workflow, you can mutate the current environment into a suitable state like so: ``` ./gst-env.py --only-environment ``` This will print output suitable for an sh-compatible `eval` function, just like `ssh-agent -s`. An external script can be run in development environment with: ``` ./gst-env.py external_script.sh ``` NOTE: In the development environment, a fully usable prefix is also configured in `gstreamer/prefix` where you can install any extra dependency/project. For more extensive documentation about the development environment go to [the documentation](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-meson.html). ## Custom subprojects We also added a meson option, `custom_subprojects`, that allows the user to provide a comma-separated list of meson subprojects that should be built alongside the default ones. To use it: ```sh # Clone into the subprojects directory $ git -C subprojects clone my_subproject # Wipe dependency detection state, in case you have an existing build dir $ meson setup --wipe builddir -Dcustom_subprojects=my_subproject $ meson compile -C builddir ``` ## Run tests You can easily run the test of all the components: ``` meson test -C builddir ``` To list all available tests: ``` meson test -C builddir --list ``` To run all the tests of a specific component: ``` meson test -C builddir --suite gst-plugins-base ``` Or to run a specific test file: ``` meson test -C builddir --suite gstreamer gst_gstbuffer ``` Run a specific test from a specific test file: ``` GST_CHECKS=test_subbuffer meson test -C builddir --suite gstreamer gst_gstbuffer ``` ## Optional Installation You can also install everything that is built into a predetermined prefix like so: ``` meson setup --prefix=/path/to/install/prefix builddir meson compile -C builddir meson install -C builddir ``` Note that the installed files have `RPATH` stripped, so you will need to set `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, or `PATH` as appropriate for your platform for things to work. ## Add information about GStreamer development environment in your prompt line ### Bash prompt We automatically handle `bash` and set `$PS1` accordingly. If the automatic `$PS1` override is not desired (maybe you have a fancy custom prompt), set the `$GST_BUILD_DISABLE_PS1_OVERRIDE` environment variable to `TRUE` and use `$GST_ENV` when setting the custom prompt, for example with a snippet like the following: ```bash ... if [[ -n "${GST_ENV-}" ]]; then PS1+="[ ${GST_ENV} ]" fi ... ``` ### Using powerline In your powerline theme configuration file (by default in `{POWERLINE INSTALLATION DIR}/config_files/themes/shell/default.json`) you should add a new environment segment as follow: ``` { "function": "powerline.segments.common.env.environment", "args": { "variable": "GST_ENV" }, "priority": 50 }, ``` ## Windows Prerequisites Setup On Windows, some of the components may require special care. ### Git for Windows Use the [Git for Windows](https://gitforwindows.org/) installer. It will install a `bash` prompt with basic shell utils and up-to-date git binaries. During installation, when prompted about `PATH`, you should select the following option:  ### Python 3.8+ on Windows Use the [official Python installer](https://www.python.org/downloads/windows/). You must ensure that Python is installed into `PATH`:  You may also want to customize the installation and install it into a system-wide location such as `C:\PythonXY`, but this is not required. ### Ninja on Windows If you are using Visual Studio 2019 or newer, Ninja is already provided. In other cases, the easiest way to install Ninja on Windows is with `pip3`, which will download the compiled binary and place it into the `Scripts` directory inside your Python installation: ``` pip3 install ninja ``` You can also download the [official release](https://github.com/ninja-build/ninja/releases) and place it into `PATH`, or use MSYS2. ### Meson on Windows **IMPORTANT**: Do not use the Meson MSI installer since it is experimental and known to not work with `GStreamer`. You can use `pip3` to install Meson, same as Ninja above: ``` pip3 install meson ``` Note that Meson is written entirely in Python, so you can also run it as-is from the [git repository](https://github.com/mesonbuild/meson/) if you want to use the latest master branch for some reason. ### Running Meson on Windows Since version 0.59.0, Meson automatically activates the Visual Studio environment on Windows if no other compilers (gcc, clang, etc) are found. To force the use of Visual Studio in such cases, you can use: ``` meson setup --vsenv builddir ``` ### Setup a mingw/wine based development environment on linux #### Install wine and mingw ##### On fedora x64 ``` sh sudo dnf install mingw64-gcc mingw64-gcc-c++ mingw64-pkg-config mingw64-winpthreads wine ``` FIXME: Figure out what needs to be installed on other distros #### Get meson from git This simplifies the process and allows us to use the cross files defined in meson itself. ``` sh git clone https://github.com/mesonbuild/meson.git ``` #### Build and install ``` BUILDDIR=$PWD/winebuild/ export WINEPREFIX=$BUILDDIR/wine-prefix/ && mkdir -p $WINEPREFIX # Setting the prefix is mandatory as it is used to setup symlinks within the development environment meson/meson.py $BUILDDIR --cross-file meson/cross/linux-mingw-w64-64bit.txt -Dgst-plugins-bad:vulkan=disabled -Dorc:gtk_doc=disabled --prefix=$BUILDDIR/wininstall/ -Djson-glib:gtk_doc=disabled meson/meson.py install -C $BUILDDIR/ ``` > __NOTE__: You should use `meson install -C $BUILDDIR` each time you make a change > instead of the usual `meson compile -C $BUILDDIR` as this is not in the > development environment. Alternatively, you can also use `mingw64-meson` on Fedora, which is a wrapper script that sets things up to use Fedora's cross files and settings. However, the wrapper script can be buggy in some cases. #### cross-mingw development environment You can get into the development environment as usual with the gst-env.py script: ``` ./gst-env.py ``` See [above](#development-environment) for more details. After setting up [binfmt] to use wine for windows binaries, you can run GStreamer tools under wine by running: ``` gst-launch-1.0.exe videotestsrc ! glimagesink ``` [binfmt]: http://man7.org/linux/man-pages/man5/binfmt.d.5.html ", Assign "at most 3 tags" to the expected json: {"id":"602","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"