Crate gstreamer_editing_services
source · [−]Expand description
gstreamer-rs

GStreamer Editing Services bindings for Rust. Documentation can be found here.
NOTE: The GStreamer Editing Services API is not Thread Safe and before the 1.16 release this was not properly expressed in the code, leading to possible data unsafety even in the rust bindings. We strongly encourage you to run with GES >= 1.16.
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-dev
The 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-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.
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
If 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/Current/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-server
If 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
Modules
Structs
A Asset
in the GStreamer Editing Services represents a resources
that can be used. In particular, any class that implements the
Extractable
interface may have some associated assets with a
corresponding property::Asset::extractable-type
, from which its objects can be
extracted using AssetExt::extract()
. Some examples would be
Clip
, Formatter
and TrackElement
.
Children Properties
Outputs a test audio stream using audiotestsrc. The default property values output silence. Useful for testing pipelines, or to fill gaps in an audio track.
A AudioTrack
is a default audio Track
, with a
TrackType::AUDIO
property::Track::track-type
and “audio/x-raw(ANY)”
property::Track::caps
.
Implements
Children Properties
A BaseEffect
is some operation that applies an effect to the data
it receives.
BaseEffectClip
-s are clips whose core elements are
BaseEffect
-s.
This is an Abstract Base Class, you cannot instantiate it.
This is an Abstract Base Class, you cannot instantiate it.
Clip
-s are the core objects of a Layer
. Each clip may exist in
a single layer but may control several TrackElement
-s that span
several Track
-s. A clip will ensure that all its children share the
same property::TimelineElement::start
and property::TimelineElement::duration
in
their tracks, which will match the property::TimelineElement::start
and
property::TimelineElement::duration
of the clip itself. Therefore, changing
the timing of the clip will change the timing of the children, and a
change in the timing of a child will change the timing of the clip and
subsequently all its siblings. As such, a clip can be treated as a
singular object in its layer.
The UriClipAsset
is a special Asset
specilized in Clip
.
it is mostly used to get information about the TrackType
-s the objects extracted
from it can potentialy create TrackElement
for.
Implements
A Container
is a timeline element that controls other
TimelineElement
-s, which are its children. In particular, it is
responsible for maintaining the relative property::TimelineElement::start
and
property::TimelineElement::duration
times of its children. Therefore, if a
container is temporally adjusted or moved to a new layer, it may
accordingly adjust and move its children. Similarly, a change in one of
its children may prompt the parent to correspondingly change its
siblings.
Currently we only support effects with N sinkpads and one single srcpad.
Apart from gesaudiomixer
and gescompositor
which can be used as effects
and where sinkpads will be requested as needed based on the timeline topology
GES will always request at most one sinkpad per effect (when required).
This asset has a GStreamer bin-description as ID and is able to determine to what track type the effect should be used in.
The effect will be applied on the sources that have lower priorities (higher number) between the inpoint and the end of it.
A glib::Object
that implements the Extractable
interface can be
extracted from a Asset
using AssetExt::extract()
.
Base class for timeline data serialization and deserialization.
This won’t be used anymore and has been replaced by
GESUriSource
instead which now plugs an imagefreeze
element when
ges_uri_source_asset_is_image
returns true
.
Outputs the video stream from a given file as a still frame. The frame chosen
will be determined by the in-point property on the track element. For image
files, do not set the in-point property.
A timed MetaContainer
object.
v1_20
A Marker
can be colored by setting the GES_META_MARKER_COLOR
meta.
A glib::Object
that implements MetaContainer
can have metadata set on
it, that is data that is unimportant to its function within GES, but
may hold some useful information. In particular,
MetaContainerExt::set_meta()
can be used to store any glib::Value
under
any generic field (specified by a string key). The same method can also
be used to remove the field by passing None
. A number of convenience
methods are also provided to make it easier to set common value types.
The metadata can then be read with MetaContainerExt::meta()
and
similar convenience methods.
Use GESUriSource
instead
Outputs the video stream from a given image sequence. The start frame chosen
will be determined by the in-point property on the track element.
Base class for overlays, transitions, and effects
Operations are any kind of object that both outputs AND consumes data.
Overlays are objects which modify the underlying layer(s).
A Pipeline
can take an audio-video Timeline
and conveniently
link its Track
-s to an internal playsink
element, for
preview/playback, and an internal encodebin
element, for rendering.
You can switch between these modes using GESPipelineExt::set_mode()
.
The various modes a Pipeline
can be configured to.
Base class for single-media sources
SourceClip
-s are clips whose core elements are Source
-s.
An asset types from which SourceClip
will be extracted
Useful for testing purposes.
Implements
Renders text onto the next lower priority stream using textrender.
A TimelineElement
will have some temporal extent in its
corresponding property::TimelineElement::timeline
, controlled by its
property::TimelineElement::start
and property::TimelineElement::duration
. This
determines when its content will be displayed, or its effect applied,
in the timeline. Several objects may overlap within a given
Timeline
, in which case their property::TimelineElement::priority
is used
to determine their ordering in the timeline. Priority is mostly handled
internally by Layer
-s and Clip
-s.
Renders the given text in the specified font, at specified position, and with the specified background pattern.
TitleSource
is a GESTimelineElement that implements the notion
of titles in GES.
A TrackElement
is a TimelineElement
that specifically belongs
to a single Track
of its property::TimelineElement::timeline
. Its
property::TimelineElement::start
and property::TimelineElement::duration
specify its
temporal extent in the track. Specifically, a track element wraps some
nleobject, such as an nlesource
or nleoperation
, which can be
retrieved with TrackElementExt::nleobject()
, and its
property::TimelineElement::start
, property::TimelineElement::duration
,
property::TimelineElement::in-point
, property::TimelineElement::priority
and
property::TrackElement::active
properties expose the corresponding nleobject
properties. When a track element is added to a track, its nleobject is
added to the corresponding nlecomposition
that the track wraps.
Implements
Base class for media transitions.
Creates an object that mixes together the two underlying objects, A and B. The A object is assumed to have a higher prioirity (lower number) than the B object. At the transition in point, only A will be visible, and by the end only B will be visible.
Represents all the output streams from a particular uri. It is assumed that the URI points to a file of some type.
Implements
Asset to create a stream specific Source
for a media file.
Base class for video sources
Children Properties
A VideoTrack
is a default video Track
, with a
TrackType::VIDEO
property::Track::track-type
and “video/x-raw(ANY)”
property::Track::caps
.
Implements
Children Properties
Implements
Enums
To be used by subclasses only. This indicate how to handle a change in a child.
When a single timeline element is edited within its timeline at some
position, using TimelineElementExt::edit()
, depending on the edit
mode, its property::TimelineElement::start
, property::TimelineElement::duration
or
property::TimelineElement::in-point
will be adjusted accordingly. In addition,
any clips may change property::Clip::layer
.
Horizontal alignment of the text.
Vertical alignment of the text.
The test pattern to produce