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.

You can find instructions for Windows below.

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 and put the ninja binary in your PATH.

You can find instructions for Windows below.

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: 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 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, 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 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 experiment