Crate gstreamer

source ·
Expand description

§gstreamer-rs crates.io pipeline status

GStreamer bindings for Rust. Documentation can be found here.

These bindings are providing a safe API that can be used to interface with GStreamer, e.g. for writing GStreamer-based applications and GStreamer plugins.

The bindings are mostly autogenerated with gir based on the GObject-Introspection API metadata provided by the GStreamer project.

§Table of Contents

  1. Installation
    1. Linux/BSDs
    2. macOS
    3. Windows
  2. Getting Started
  3. License
  4. Contribution

§Installation

To build the GStreamer bindings or anything depending on them, you need to have at least GStreamer 1.14 and gst-plugins-base 1.14 installed. In addition, some of the examples/tutorials require various GStreamer plugins to be available, which can be found in gst-plugins-base, gst-plugins-good, gst-plugins-bad, gst-plugins-ugly and/or gst-libav.

§Linux/BSDs

You need to install the above mentioned packages with your distributions package manager, or build them from source.

On Debian/Ubuntu they can be installed with

$ 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

The minimum required version of the above libraries is >= 1.14. If you build the gstreamer-player sub-crate, or any of the examples that depend on gstreamer-player, you must ensure that in addition to the above packages, libgstreamer-plugins-bad1.0-dev is installed. See the Cargo.toml files for the full details,

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

Package names on other distributions should be similar. Please submit a pull request with instructions for yours.

§macOS

You can install GStreamer and the plugins via Homebrew or by installing the binaries provided by the GStreamer project.

We recommend using the official GStreamer binaries over Homebrew, especially as GStreamer in Homebrew is currently broken.

§GStreamer Binaries

You need to download the two .pkg files from the GStreamer website and install them, e.g. gstreamer-1.0-1.20.4-universal.pkg and gstreamer-1.0-devel-1.20.4-universal.pkg.

After installation, you also need to set the PATH environment variable as follows

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

Also note that the pkg-config from GStreamer should be the first one in the PATH as other versions have all kinds of quirks that will cause problems.

§Homebrew

Homebrew only installs various plugins if explicitly enabled, so some extra --with-* flags may be required.

$ brew install gstreamer gst-plugins-base gst-plugins-good \
      gst-plugins-bad gst-plugins-ugly gst-libav gst-rtsp-server \
      gst-editing-services --with-orc --with-libogg --with-opus \
      --with-pango --with-theora --with-libvorbis --with-libvpx \
      --enable-gtk3

Make sure the version of these libraries is >= 1.14.

§Windows

You can install GStreamer and the plugins via MSYS2 with pacman or by installing the binaries provided by the GStreamer project.

We recommend using the official GStreamer binaries over MSYS2.

§GStreamer Binaries

You need to download the two .msi files for your platform from the GStreamer website and install them, e.g. gstreamer-1.0-x86_64-1.20.4.msi and gstreamer-1.0-devel-x86_64-1.20.4.msi. Make sure to select the version that matches your Rust toolchain, i.e. MinGW or MSVC.

After installation set the ``PATH` environment variable as follows:

# For a UNIX-style shell:
$ export PATH="c:/gstreamer/1.0/msvc_x86_64/bin${PATH:+:$PATH}"

# For cmd.exe:
$ set PATH=C:\gstreamer\1.0\msvc_x86_64\bin;%PATH%

Make sure to update the path to where you have actually installed GStreamer and for the corresponding toolchain.

Also note that the pkg-config.exe from GStreamer should be the first one in the PATH as other versions have all kinds of quirks that will cause problems.

§MSYS2 / pacman
$ pacman -S glib2-devel pkg-config \
      mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base \
      mingw-w64-x86_64-gst-plugins-good mingw-w64-x86_64-gst-plugins-bad \
      mingw-w64-x86_64-gst-plugins-ugly mingw-w64-x86_64-gst-libav \
      mingw-w64-x86_64-gst-rtsp-server

Make sure the version of these libraries is >= 1.14.

Note that the version of pkg-config included in MSYS2 is known to have problems compiling GStreamer, so you may need to install another version. One option would be pkg-config-lite.

§Getting Started

The API reference can be found here, however it is only the Rust API reference and does not explain any of the concepts.

For getting started with GStreamer development, the best would be to follow the documentation on the GStreamer website, especially the Application Development Manual. While being C-centric, it explains all the fundamental concepts of GStreamer and the code examples should be relatively easily translatable to Rust. The API is basically the same, function/struct names are the same and everything is only more convenient (hopefully) and safer.

In addition there are tutorials on the GStreamer website. Many of them were ported to Rust already and the code can be found in the tutorials directory.

Some further examples for various aspects of GStreamer and how to use it from Rust can be found in the examples directory.

Various GStreamer plugins written in Rust can be found in the gst-plugins-rs repository.

§LICENSE

gstreamer-rs and all crates contained in here are licensed under either of

  • Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
  • MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

GStreamer itself is licensed under the Lesser General Public License version 2.1 or (at your option) any later version: https://www.gnu.org/licenses/lgpl-2.1.html

§Contribution

Any kinds of contributions are welcome as a pull request.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in gstreamer-rs by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

Modules§

Macros§

Structs§

  • AllocationParams
    Parameters to control the allocation of memory
  • Allocator
    Memory is usually created by allocators with a AllocatorExt::alloc() method call. When None is used as the allocator, the default allocator will be used.
  • Array
  • ArrayRef
  • AtomicClockReturn
  • Bin
    Bin is an element that can contain other Element, allowing them to be managed as a group. Pads from the child elements can be ghosted to the bin, see GhostPad. This makes the bin look like any other elements and enables creation of higher-level abstraction elements.
  • BinBuilder
    A builder-pattern type to construct Bin objects.
  • BinFlags
    GstBinFlags are a set of flags specific to bins. Most are set/used internally. They can be checked using the GST_OBJECT_FLAG_IS_SET() macro, and (un)set using GST_OBJECT_FLAG_SET() and GST_OBJECT_FLAG_UNSET().
  • Bitmask
  • BufferCopyFlags
    A set of flags that can be provided to the [Buffer::copy_into()][crate::Buffer::copy_into()] function to specify which items should be copied.
  • BufferCursor
  • BufferFlags
    A set of buffer flags used to describe properties of a Buffer.
  • BufferPool
    A BufferPool is an object that can be used to pre-allocate and recycle buffers of the same size and with the same properties.
  • BufferPoolAcquireFlags
    Additional flags to control the allocation of a buffer
  • BufferPoolAcquireParams
  • BufferPoolConfig
  • BufferPoolConfigRef
  • BufferRefCursor
  • Bus
    The Bus is an object responsible for delivering Message packets in a first-in first-out way from the streaming threads (see Task) to the application.
  • CapsFeatures
    CapsFeatures can optionally be set on a Caps to add requirements for additional features for a specific Structure. Caps structures with the same name but with a non-equal set of caps features are not compatible. If a pad supports multiple sets of features it has to add multiple equal structures with different feature sets to the caps.
  • CapsFeaturesRef
  • ChildProxy
    This interface abstracts handling of property sets for elements with children. Imagine elements such as mixers or polyphonic generators. They all have multiple Pad or some kind of voice objects. Another use case are container elements like Bin. The element implementing the interface acts as a parent for those child objects.
  • Clock
    GStreamer uses a global clock to synchronize the plugins in a pipeline. Different clock implementations are possible by implementing this abstract base class or, more conveniently, by subclassing SystemClock.
  • ClockFlags
    The capabilities of this clock
  • ClockId
    GLib type: Shared boxed type with reference counted clone semantics.
  • ControlBinding
    A base class for value mapping objects that attaches control sources to glib::Object properties. Such an object is taking one or more ControlSource instances, combines them and maps the resulting value to the type and value range of the bound property.
  • ControlSource
    The ControlSource is a base class for control value sources that could be used to get timestamp-value pairs. A control source essentially is a function over time.
  • DateTime
    Struct to store date, time and timezone information altogether. DateTime is refcounted and immutable.
  • DebugColorFlags
    These are some terminal style flags you can use when creating your debugging categories to make them stand out in debugging output.
  • DebugGraphDetails
    Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS().
  • Device
    Device are objects representing a device, they contain relevant metadata about the device, such as its class and the Caps representing the media types it can produce or handle.
  • DeviceMonitor
    Applications should create a DeviceMonitor when they want to probe, list and monitor devices of a specific type. The DeviceMonitor will create the appropriate DeviceProvider objects and manage them. It will then post messages on its Bus for devices that have been added and removed.
  • DeviceMonitorFilterId
  • DeviceProvider
    A DeviceProvider subclass is provided by a plugin that handles devices if there is a way to programmatically list connected devices. It can also optionally provide updates to the list of connected devices.
  • DeviceProviderFactory
    DeviceProviderFactory is used to create instances of device providers. A GstDeviceProviderfactory can be added to a Plugin as it is also a PluginFeature.
  • Element
    GstElement is the abstract base class needed to construct an element that can be used in a GStreamer pipeline. Please refer to the plugin writers guide for more information on creating Element subclasses.
  • ElementFactory
    ElementFactory is used to create instances of elements. A GstElementFactory can be added to a Plugin as it is also a PluginFeature.
  • ElementFactoryType
  • ElementFlags
    The standard flags that an element may have.
  • ErrorMessage
  • EventTypeFlags
    EventTypeFlags indicate the aspects of the different EventType values. You can get the type flags of a EventType with the EventType::flags() function.
  • FormattedSegment
    GLib type: Inline allocated boxed type with stack copy semantics.
  • Fraction
  • FractionRange
  • GapFlags
    The different flags that can be set on EventType::Gap events. See [Event::set_gap_flags()][crate::Event::set_gap_flags()] for details.
  • GhostPad
    GhostPads are useful when organizing pipelines with Bin like elements. The idea here is to create hierarchical element graphs. The bin element contains a sub-graph. Now one would like to treat the bin-element like any other Element. This is where GhostPads come into play. A GhostPad acts as a proxy for another pad. Thus the bin can have sink and source ghost-pads that are associated with sink and source pads of the child elements.
  • IntRange
  • Iterator
  • List
  • ListRef
  • LoggableError
  • MemoryFlags
    Flags for wrapped memory.
  • MetaFlags
    Extra metadata flags.
  • NotifyWatchId
  • Object
    Object provides a root for the object hierarchy tree filed in by the GStreamer library. It is currently a thin wrapper on top of GInitiallyUnowned. It is an abstract class that is not very usable on its own.
  • ObjectFlags
    The standard flags that an gstobject may have.
  • ObjectLockGuard
  • Pad
    A Element is linked to other elements via “pads”, which are extremely light-weight generic link points.
  • PadBuilder
  • PadFlags
    Pad state flags
  • PadLinkCheck
    The amount of checking to be done when linking pads. CAPS and TEMPLATE_CAPS are mutually exclusive. If both are specified, expensive but safe CAPS are performed.
  • PadLinkSuccess
  • PadProbeId
  • PadProbeInfo
  • PadProbeType
    The different probing types that can occur. When either one of IDLE or BLOCK is used, the probe will be a blocking probe.
  • PadTemplate
    Padtemplates describe the possible media types a pad or an elementfactory can handle. This allows for both inspection of handled types before loading the element plugin as well as identifying pads on elements that are not yet created (request or sometimes pads).
  • PadTemplateBuilder
  • ParseContext
    Opaque structure.
  • ParseFlags
    Parsing options.
  • PeriodicClockId
  • Pipeline
    A Pipeline is a special Bin used as the toplevel container for the filter graph. The Pipeline will manage the selection and distribution of a global Clock as well as provide a Bus to the application.
  • PipelineBuilder
    A builder-pattern type to construct Pipeline objects.
  • PipelineFlags
    Pipeline flags
  • Plugin
    GStreamer is extensible, so Element instances can be loaded at runtime. A plugin system can provide one or more of the basic GStreamer PluginFeature subclasses.
  • PluginAPIFlags
  • PluginDependencyFlags
    Flags used in connection with Plugin::add_dependency().
  • PluginFeature
    This is a base class for anything that can be added to a Plugin.
  • PluginFlags
    The plugin loading state
  • Preset
    This interface offers methods to query and manipulate parameter preset sets. A preset is a bunch of property settings, together with meta data and a name. The name of a preset serves as key for subsequent method calls to manipulate single presets. All instances of one type will share the list of presets. The list is created on demand, if presets are not used, the list is not created.
  • ProxyPad
    Implements
  • Rank
  • Registry
    One registry holds the metadata of a set of plugins.
  • SchedulingFlags
    The different scheduling flags.
  • SeekFlags
    Flags to be used with ElementExtManual::seek() or gst_event_new_seek(). All flags can be used together.
  • SegmentFlags
    Flags for the GstSegment structure. Currently mapped to the corresponding values of the seek flags.
  • SerializeFlags
  • SingleShotClockId
  • SliceTypeFind
  • StackTraceFlags
  • StateChangeError
  • StaticCaps
    Data structure to initialize Caps from a string description usually used in conjunction with GST_STATIC_CAPS() and get() to instantiate a Caps.
  • StaticPadTemplate
    Structure describing the StaticPadTemplate.
  • StdIterator
  • Stream
    A high-level object representing a single stream. It might be backed, or not, by an actual flow of data in a pipeline (Pad).
  • StreamCollection
    A collection of Stream that are available.
  • StreamFlags
  • StreamLock
  • StreamType
    StreamType describes a high level classification set for flows of data in Stream objects.
  • SystemClock
    The GStreamer core provides a GstSystemClock based on the system time. Asynchronous callbacks are scheduled from an internal thread.
  • TagSetter
    Element interface that allows setting of media metadata.
  • Task
    Task is used by Element and Pad to provide the data passing threads in a Pipeline.
  • TaskPool
    This object provides an abstraction for creating threads. The default implementation uses a regular GThreadPool to start tasks.
  • TaskPoolTaskHandle
    An opaque handle for a task associated with a particular task pool.
  • TocSetter
    Element interface that allows setting of the TOC.
  • Tracer
    Tracing modules will subclass Tracer and register through gst_tracer_register(). Modules can attach to various hook-types - see [tracing_register_hook()][crate::tracing_register_hook()]. When invoked they receive hook specific contextual data, which they must not modify.
  • TracerFactory
    Use factories() to get a list of tracer factories known to GStreamer.
  • TypeFind
    The following functions allow you to detect the media type of an unknown stream.
  • TypeFindFactory
    These functions allow querying information about registered typefind functions. How to create and register these functions is described in the section “Writing typefind functions”</link>.
  • URIHandler
    The URIHandler is an interface that is implemented by Source and Sink Element to unify handling of URI.

Enums§

Constants§

Statics§

Traits§

Functions§

  • active_tracers
    Get a list of all active tracer objects owned by the tracing framework for the entirety of the run-time of the process or till gst_deinit() is called.
  • assert_initialized
  • calculate_linear_regression
  • ceil_log2
    Return a max num of log2.
  • deinit⚠
    Deinitialize GStreamer
  • filename_compare
  • get_timestamp
    Get a timestamp as GstClockTime to be used for interval measurements. The timestamp should not be interpreted in any other way.
  • init
  • main_executable_path
    This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features.
  • version
    Gets the version number of the GStreamer library.
  • version_string
    This function returns a string that is useful for describing this version of GStreamer to the outside world: user agent strings, logging, …

Type Aliases§