gstreamer-rs: safe Rust bindings for a C multimedia pipeline

Bindings generated from introspection metadata

gstreamer-rs is a set of Rust bindings for GStreamer that provide a safe API for interfacing with it, for writing GStreamer based applications and for writing GStreamer plugins. The key implementation detail is that the bindings are mostly autogenerated, using the gir tool from the gtk-rs project, on top of the GObject Introspection API metadata that the GStreamer project provides.

That provenance explains most of what you will notice about the API. The method names, the type hierarchy and the property names follow the C library rather than a Rust designer's preferences, because they are derived from the same metadata that the bindings for every other GObject based library use. It also explains the crate split: each GStreamer module becomes a workspace crate, and each one has a raw layer and a safe layer, with the raw layer giving you the unsafe escape hatch and the safe layer wrapping it. The crates are published on crates.io, and the documentation is generated and hosted on the GStreamer documentation site.

Why the bindings live outside the GStreamer monorepo

The project answers the question of why it is separate from the main GStreamer repository, and it does so with technical reasons rather than organisational ones. The Rust bindings and the Rust plugins live in their own git repositories with an independent release schedule, unlike the Python bindings which are part of the main GStreamer repository, and the project says this separation will not change in the foreseeable future. It also says explicitly that the separation does not make them second-class citizens within GStreamer.

Two reasons are given. The first is release cycle alignment. Both repositories depend on gtk-rs for the GLib and GObject bindings, and gtk-rs follows GNOME's six-monthly release cycle, so gstreamer-rs and the Rust plugin repository are aligned to it as well. That keeps the APIs synchronised as breaking changes happen every six, twelve or eighteen months, and the crates follow cargo's semantic versioning rules so those breaking changes are handled in the way Rust users expect.

The second reason is the cargo ecosystem. Cargo based projects expect to pull functionality in as crates, so each plugin in the Rust plugin repository is published as a crate. A project that wanted a git version of one plugin, or the bindings, would otherwise have to pull in the entire GStreamer monorepo, which the documentation calls excessive because of the network bandwidth, disk usage and build times involved. Depending on plugins as a cargo dependency is explicitly supported and widely used by Rust projects that want to link plugins statically into their applications, and all the plugins are published to crates.io while git versions remain supported as well.

The build needs GStreamer on the system

This is where most of the friction lives. To build the bindings, or anything that depends on them, you need at least GStreamer 1.14 and gst-plugins-base 1.14 installed. Some examples and tutorials also need plugins from the other plugin sets, which are named as gst-plugins-base, gst-plugins-good, gst-plugins-bad, gst-plugins-ugly and gst-libav.

On Debian and Ubuntu the packages come from the distribution:

$ apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
      gstreamer1.0-plugins-base gstreamer1.0-plugins-good \
      gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \
      gstreamer1.0-libav libgstrtspserver-1.0-dev libges-1.0-dev

Fedora names them differently:

dnf install gstreamer1-devel gstreamer1-plugins-base-devel \
      gstreamer1-plugins-good gstreamer1-plugins-bad-free \
      gstreamer1-plugin-libav gstreamer1-rtsp-server-devel \
      gst-editing-services-devel

and the packages that Fedora splits out live in RPMFusion. There is one conditional dependency worth noting: if you build the gstreamer-player sub-crate, or any of the examples that depend on it, you also need the bad plugins development package, which on Debian is:

$ apt-get install libgstreamer-plugins-bad1.0-dev

The project asks for pull requests with instructions for other distributions, so the package list is expected to grow.

macOS: take the official binaries, not Homebrew

The macOS guidance is the most opinionated part of the installation documentation. You can install GStreamer and the plugins through Homebrew or from the binaries provided by the GStreamer project, but the project recommends the official binaries, and gives a reason: GStreamer in Homebrew is described as currently broken, with a link to the discussion where that is tracked.

The binary route means downloading two .pkg files, the runtime one and the development one, for example the 1.20.4 universal packages, and installing both. After that the path has to be set so the tools are found:

$ export PATH="/Library/Frameworks/GStreamer.framework/Versions/1.0/bin${PATH:+:$PATH}"

There is a second, easily missed instruction: the pkg-config that ships with GStreamer has to be the first one on the path, because the documentation says other versions have quirks that cause problems. That one causes confusing build failures, since a mismatched pkg-config reports the wrong versions of everything.

The Homebrew route is a single command, and the note is to make sure the version is 1.14 or newer:

$ brew install gstreamer

Windows: match the installer to your Rust toolchain

On Windows there are two routes as well, through MSYS2 with pacman or through the official binaries, and again the official binaries are the recommendation. The binary route needs two .msi files for your platform, the runtime and the development one, for example the 1.20.4 x86_64 pair, and the important instruction is to select the version that matches your Rust toolchain, which means MinGW or MSVC.

Getting that wrong produces link errors rather than anything obviously about GStreamer, so it is the first thing to verify. The path then has to be set for whichever shell you use, and both forms are given, a UNIX style shell and cmd.exe:

$ export PATH="c:/gstreamer/1.0/msvc_x86_64/bin${PATH:+:$PATH}"

$ set PATH=C:\gstreamer\1.0\msvc_x86_64\bin;%PATH%

The reminder at the end applies to all of this: update the path to where you actually installed GStreamer and to the corresponding toolchain, because the documented values are examples rather than the truth about your machine.

A workspace with a crate per module

The repository layout is what a generated binding set looks like. Each GStreamer module has its own directory, and inside it a sys crate and a safe crate: gstreamer itself, then gstreamer-app, gstreamer-audio, gstreamer-base, gstreamer-check, gstreamer-controller, gstreamer-editing-services, gstreamer-mpegts, gstreamer-mse, gstreamer-net, gstreamer-pbutils, gstreamer-play, gstreamer-player, gstreamer-rtp, gstreamer-rtsp, gstreamer-rtsp-server, gstreamer-sdp, gstreamer-tag, gstreamer-validate, gstreamer-video and gstreamer-webrtc, with others for allocators, analytics, tracing, gl and vulkan among them.

The workspace manifest uses resolver 3 and, unusually, defines a default member list that includes both the sys and the safe crates for each module plus the examples and the tutorials. That is a convenience decision, since a plain cargo build in the repository root would otherwise compile every crate in the workspace, including the platform specific ones you do not need.

The generation side of the repository holds the introspection files, the generator script and a public directory of shared code, and the metadata files for each library that the bindings are produced from. There is a deny directory for dependency policy checks, a CI directory and a GitLab CI configuration, plus a development document and an agents file. The licence situation is two files, one for the Apache licence and one for the MIT licence, which is the same dual licensing that gtk-rs uses.

Where the costs land

Three costs are visible from the documentation, and none of them are hidden. The first is the system dependency, and it is not small: a build needs the development packages for GStreamer and several plugin sets, on three platforms with different package names and different instructions, including a case where the project tells you the package manager route is broken. In a container, that means an image with a large layer of multimedia libraries rather than a self contained crate.

The second is the release rhythm. The crates are aligned to the six-monthly GNOME cycle, which is a deliberate choice to keep them in step with the C library, but it means a breaking change arrives on a schedule you do not control, at intervals of six, twelve or eighteen months, handled through semantic versioning.

The third is where the work happens. The repository description on GitHub says the project has moved to the GStreamer GitLab, and the homepage is the GitLab URL, so issues and pull requests go there rather than to the GitHub copy. The GitHub repository publishes no releases of its own, so the versions to track are the crates.io ones.

Editorial conclusion

gstreamer-rs suits a Rust team that has to build on GStreamer rather than replace it, because the safe wrappers are generated from the same introspection metadata the rest of the GObject world uses, so the API stays in step with the C library rather than drifting. It is the wrong choice if you cannot install system packages, since the bindings link against GStreamer and the plugin sets and will not build without them, and it is the wrong choice if you need a stable API across years, because the crates are aligned to the six-monthly GNOME cycle and take breaking changes when it turns over. Before you start, install GStreamer 1.14 or newer with the base, good, bad and ugly plugin sets, and if you are on macOS or Windows take the official binaries rather than the package manager route the project warns about. Note also that the work happens on GitLab now, and the licence files in the repository are the Apache and MIT texts.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. sdroege/gstreamer-rs on GitHub