Expand description
gstreamer-rs 
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
Installation
To build the GStreamer bindings or anything depending on them, you need to have at least GStreamer 1.8 and gst-plugins-base 1.8 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-devThe minimum required version of the above libraries is >= 1.8. 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 and
that the version is >= 1.12. See the Cargo.toml files for the full
details,
$ # Only if you wish to install gstreamer-player, make sure the version
$ # of this package is >= 1.12.
$ apt-get install libgstreamer-plugins-bad1.0-devPackage 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.
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-gtk3If you wish to install the gstreamer-player sub-crate, make sure the version of these libraries is >= 1.12. Otherwise, a version >= 1.8 is sufficient.
GStreamer Binaries
You need to download the two .pkg files from the GStreamer website and
install them, e.g. gstreamer-1.0-1.12.3-x86_64.pkg and
gstreamer-1.0-devel-1.12.3-x86_64.pkg.
After installation, you also need to install pkg-config (e.g. via Homebrew)
and set the PKG_CONFIG_PATH environment variable
$ export PKG_CONFIG_PATH="/Library/Frameworks/GStreamer.framework/Versions/1.0/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"Windows
You can install GStreamer and the plugins via MSYS2
with pacman or by installing the
binaries provided by
the GStreamer project.
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-serverIf you wish to install the gstreamer-player sub-crate, make sure the version of these libraries is >= 1.12. Otherwise, a version >= 1.8 is sufficient.
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.
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.12.3.msi and
gstreamer-1.0-devel-x86_64-1.12.3.msi.
After installation, you also need to install pkg-config (e.g. via MSYS2 or
from here)
and set the PKG_CONFIG_PATH environment variable
$ export PKG_CONFIG_PATH="c:\\gstreamer\\1.0\\x86_64\\lib\\pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"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
pub use ffi;pub use glib;pub use paste;pub use miniobject::MiniObject;pub use miniobject::MiniObjectRef;pub use crate::message::Message;pub use crate::message::MessageErrorDomain;pub use crate::message::MessageRef;pub use crate::message::MessageView;pub use crate::structure::Structure;pub use crate::structure::StructureRef;pub use crate::caps::Caps;pub use crate::caps::CapsFilterMapAction;pub use crate::caps::CapsRef;pub use crate::tags::tag_exists;pub use crate::tags::tag_get_description;pub use crate::tags::tag_get_flag;pub use crate::tags::tag_get_nick;pub use crate::tags::tag_get_type;pub use crate::tags::Tag;pub use crate::tags::TagList;pub use crate::tags::TagListRef;pub use crate::meta::MetaSeqnum;v1_16pub use crate::meta::ReferenceTimestampMeta;v1_14pub use crate::meta::Meta;pub use crate::meta::MetaAPI;pub use crate::meta::MetaRef;pub use crate::meta::MetaRefMut;pub use crate::meta::ParentBufferMeta;pub use crate::meta::ProtectionMeta;pub use crate::buffer::Buffer;pub use crate::buffer::BufferMap;pub use crate::buffer::BufferRef;pub use crate::buffer::MappedBuffer;pub use crate::buffer::BUFFER_COPY_ALL;pub use crate::buffer::BUFFER_COPY_METADATA;pub use crate::memory::MappedMemory;pub use crate::memory::Memory;pub use crate::memory::MemoryMap;pub use crate::memory::MemoryRef;pub use crate::sample::Sample;pub use crate::sample::SampleRef;pub use crate::bufferlist::BufferList;pub use crate::bufferlist::BufferListRef;pub use crate::query::Query;pub use crate::query::QueryRef;pub use crate::query::QueryView;pub use crate::event::Event;pub use crate::event::EventRef;pub use crate::event::EventView;pub use crate::event::GroupId;pub use crate::event::Seqnum;pub use crate::context::Context;pub use crate::context::ContextRef;pub use promise::Promise;pub use promise::PromiseError;pub use task::TaskLock;pub use task::TaskLockGuard;pub use crate::format::FormattedValue;pub use crate::format::FormattedValueIntrinsic;pub use crate::format::GenericFormattedValue;pub use crate::format::SpecificFormattedValue;pub use crate::format::SpecificFormattedValueIntrinsic;pub use crate::toc::Toc;pub use crate::toc::TocEntry;pub use crate::toc::TocEntryRef;pub use crate::toc::TocRef;pub use crate::functions::*;Modules
Macros
Structs
Parameters to control the allocation of memory
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.
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().
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.
A set of buffer flags used to describe properties of a Buffer.
A BufferPool is an object that can be used to pre-allocate and recycle
buffers of the same size and with the same properties.
Additional flags to control the allocation of a buffer
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.
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.
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.
The capabilities of this clock
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.
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.
Struct to store date, time and timezone information altogether.
DateTime is refcounted and immutable.
This is the struct that describes the categories. Once initialized with
GST_DEBUG_CATEGORY_INIT, its values can’t be changed anymore.
These are some terminal style flags you can use when creating your debugging categories to make them stand out in debugging output.
Available details for pipeline graphs produced by GST_DEBUG_BIN_TO_DOT_FILE() and GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS().
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.
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 is used to create instances of device providers. A
GstDeviceProviderfactory can be added to a Plugin as it is also a
PluginFeature.
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 is used to create instances of elements. A
GstElementFactory can be added to a Plugin as it is also a
PluginFeature.
The standard flags that an element may have.
EventTypeFlags indicate the aspects of the different EventType
values. You can get the type flags of a EventType with the
EventType::flags() function.
v1_20The different flags that can be set on EventType::Gap events. See
[Event::set_gap_flags()][crate::Event::set_gap_flags()] for details.
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.
Flags for wrapped memory.
Extra metadata flags.
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.
The standard flags that an gstobject may have.
A Element is linked to other elements via “pads”, which are extremely
light-weight generic link points.
Pad state flags
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.
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).
Opaque structure.
Parsing options.
Pipeline flags
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.
v1_18Flags used in connection with Plugin::add_dependency().
This is a base class for anything that can be added to a Plugin.
The plugin loading state
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.
Implements
One registry holds the metadata of a set of plugins.
The different scheduling flags.
Flags to be used with ElementExtManual::seek() or gst_event_new_seek(). All flags
can be used together.
Flags for the GstSegment structure. Currently mapped to the corresponding values of the seek flags.
v1_20v1_12Structure describing the StaticPadTemplate.
A high-level object representing a single stream. It might be backed, or
not, by an actual flow of data in a pipeline (Pad).
A collection of Stream that are available.
v1_10StreamType describes a high level classification set for
flows of data in Stream objects.
The GStreamer core provides a GstSystemClock based on the system time. Asynchronous callbacks are scheduled from an internal thread.
Element interface that allows setting of media metadata.
This object provides an abstraction for creating threads. The default implementation uses a regular GThreadPool to start tasks.
An opaque handle for a task associated with a particular task pool.
Element interface that allows setting of the TOC.
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.
Use factories() to get a list of tracer factories known to
GStreamer.
The following functions allow you to detect the media type of an unknown stream.
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>.
The URIHandler is an interface that is implemented by Source and Sink
Element to unify handling of URI.
Enums
The different types of buffering methods.
The result values for a GstBusSyncHandler.
Modes of caps intersection
The type of the clock entry
The return value of a clock operation.
The different kind of clocks.
Core errors are errors inside the core GStreamer library.
The level defines the importance of a debugging message. The more important a message is, the greater the probability that the debugging system outputs it.
The result of passing data to a pad.
Standard predefined formats
Library errors are for errors from the library being used by elements (initializing, finalizing, settings, …)
The direction of a pad.
Result values from gst_pad_link and friends.
The status of a GstPad. After activating a pad, which usually happens when the parent element goes from READY to PAUSED, the GstPadMode defines if the pad operates in push or pull mode.
Indicates when this pad will become available.
Different return values for the GstPadProbeCallback.
The different parsing errors that can occur.
The plugin loading errors
The type of a GST_MESSAGE_PROGRESS. The progress messages inform the
application of the status of asynchronous tasks.
v1_14The result of a Promise
The different types of QoS events that can be given to the
gst_event_new_qos() method.
Element priority ranks. Defines the order in which the autoplugger (or
similar rank-picking mechanisms, such as e.g. Element::make_from_uri())
will choose this element over an alternative one with the same function.
Resource errors are for any resource used by an element: memory, files, network connections, process space, … They’re typically used by source and sink elements.
The different types of seek events. When constructing a seek event with
gst_event_new_seek() or when doing gst_segment_do_seek ().
The possible states an element can be in. States can be changed using
ElementExt::set_state() and checked using ElementExt::state().
These are the different state changes an element goes through.
State::Null ⇒ State::Playing is called an upwards state change
and State::Playing ⇒ State::Null a downwards state change.
The possible return values from a state change function such as
ElementExt::set_state(). Only Failure is a real failure.
Stream errors are for anything related to the stream being processed: format errors, media type errors, … They’re typically used by decoders, demuxers, converters, …
The type of a GST_MESSAGE_STREAM_STATUS. The stream status messages inform the
application of new streaming threads and their status.
The type of a GST_MESSAGE_STRUCTURE_CHANGE.
Extra tag flags used when registering tags.
The different tag merging modes are basically replace, overwrite and append,
but they can be seen from two directions. Given two taglists: (A) the tags
already in the element and (B) the ones that are supplied to the element (
e.g. via TagSetterExt::merge_tags() / gst_tag_setter_add_tags() or a
EventType::Tag), how are these tags merged?
In the table below this is shown for the cases that a tag exists in the list
(A) or does not exists (!A) and combinations thereof.
GstTagScope specifies if a taglist applies to the complete medium or only to one single stream.
The different states a task can be in
The different types of TOC entries (see TocEntry).
How a TocEntry should be repeated. By default, entries are played a
single time.
The scope of a TOC.
The probability of the typefind function. Higher values have more certainty in doing a reliable typefind.
Different URI-related errors that can occur.
The different types of URI direction.
Constants
Statics
Traits
A handle for a task which was pushed to a task pool.
Functions
Adds a memory ringbuffer based debug logger that stores up to
max_size_per_thread bytes of logs per thread and times out threads after
thread_timeout seconds of inactivity.
To aid debugging applications one can use this method to obtain the whole network of gstreamer elements that form the pipeline into a dot file. This data can be processed with graphviz to get an image.
To aid debugging applications one can use this method to write out the whole network of gstreamer elements that form the pipeline into a dot file. This file can be processed with graphviz to get an image.
This works like debug_bin_to_dot_file(), but adds the current timestamp
to the filename, so that it can be used to take multiple snapshots.
Returns the default threshold that is used for new categories.
flags
Checks if debugging output is activated.
Checks if the debugging output should be colored.
If libunwind, glibc backtrace or DbgHelp are present a stack trace is printed.
Removes any previously added ring buffer logger with
debug_add_ring_buffer_logger().
Fetches the current logs per thread from the ring buffer logger. See
debug_add_ring_buffer_logger() for details.
If activated, debugging messages are sent to the debugging handlers. It makes sense to deactivate it for speed issues.
Sets or unsets the use of coloured debugging output. Same as gst_debug_set_color_mode () with the argument being being GST_DEBUG_COLOR_MODE_ON or GST_DEBUG_COLOR_MODE_OFF.
Sets the default threshold to the given level and updates all categories to use this threshold.
Sets all categories which match the given glob style pattern to the given level.
Sets the debug logging wanted in the same form as with the GST_DEBUG environment variable. You can use wildcards such as ‘*’, but note that the order matters when you use wild cards, e.g. “foosrc:6,src:3,:2” sets everything to log level 2.
Resets all categories with the given name back to the default level.
v1_14This helper is mostly helpful for plugins that need to inspect the folder of the main executable to determine their set of features.
This is a convenience wrapper around parse_launch() to create a
Bin from a gst-launch-style pipeline description. See
parse_launch() and the gst-launch man page for details about the
syntax. Ghost pads on the bin for unlinked source or sink pads
within the bin can automatically be created (but only a maximum of
one ghost pad for each direction will be created; if you expect
multiple unlinked source pads or multiple unlinked sink pads
and want them all ghosted, you will have to create the ghost pads
yourself).
Create a new pipeline based on command line syntax.
Please note that you might get a return value that is not None even though
the error is set. In this case there was a recoverable parsing error and you
can try to play the pipeline.
Create a new element based on command line syntax.
error will contain an error message if an erroneous pipeline is specified.
An error does not mean that the pipeline could not be constructed.
Forces GStreamer to re-scan its plugin paths and update the default plugin registry.
Get a timestamp as GstClockTime to be used for interval measurements. The timestamp should not be interpreted in any other way.
Gets the version number of the GStreamer library.
This function returns a string that is useful for describing this version of GStreamer to the outside world: user agent strings, logging, …