Crate gstreamer_editing_services
source ·Expand description
§gstreamer-rs
![pipeline status](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/badges/main/pipeline.svg)
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.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§
pub use gio;
pub use glib;
pub use gst;
pub use gst_base;
pub use gst_pbutils;
pub use gstreamer_editing_services_sys as ffi;
Modules§
Structs§
- A
Asset
in the GStreamer Editing Services represents a resources that can be used. In particular, any class that implements theExtractable
interface may have some associated assets with a correspondingextractable-type
, from which its objects can be extracted usingAssetExt::extract()
. Some examples would beClip
,Formatter
andTrackElement
. - 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 audioTrack
, with aTrackType::AUDIO
track-type
and “audio/x-raw(ANY)”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 areBaseEffect
-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 aLayer
. Each clip may exist in a single layer but may control severalTrackElement
-s that span severalTrack
-s. A clip will ensure that all its children share the samestart
andduration
in their tracks, which will match thestart
andduration
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 specialAsset
specilized inClip
. it is mostly used to get information about theTrackType
-s the objects extracted from it can potentialy createTrackElement
for. - Implements
- A
Container
is a timeline element that controls otherTimelineElement
-s, which are its children. In particular, it is responsible for maintaining the relativestart
andduration
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. - Properties
- 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 theExtractable
interface can be extracted from aAsset
usingAssetExt::extract()
. - Base class for timeline data serialization and deserialization.
- ImageSourceDeprecatedThis won’t be used anymore and has been replaced by
GESUriSource
instead which now plugs animagefreeze
element whenges_uri_source_asset_is_image
returnstrue
. 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. - A
Marker
can be colored by setting theGES_META_MARKER_COLOR
meta. - A
glib::Object
that implementsMetaContainer
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 anyglib::Value
under any generic field (specified by a string key). The same method can also be used to remove the field by passingNone
. A number of convenience methods are also provided to make it easier to set common value types. The metadata can then be read withMetaContainerExt::meta()
and similar convenience methods. - MultiFileSourceDeprecatedUse
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-videoTimeline
and conveniently link itsTrack
-s to an internalplaysink
element, for preview/playback, and an internalencodebin
element, for rendering. You can switch between these modes usingGESPipelineExt::set_mode()
. - The various modes a
Pipeline
can be configured to. - Base class for single-media sources
SourceClip
-s are clips whose core elements areSource
-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.
Timeline
is the central object for any multimedia timeline.- A
TimelineElement
will have some temporal extent in its correspondingtimeline
, controlled by itsstart
andduration
. This determines when its content will be displayed, or its effect applied, in the timeline. Several objects may overlap within a givenTimeline
, in which case theirpriority
is used to determine their ordering in the timeline. Priority is mostly handled internally byLayer
-s andClip
-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
Track
acts an output source for aTimeline
. Each one essentially provides an additionalgst::Pad
for the timeline, withrestriction-caps
capabilities. Internally, a track wraps annlecomposition
filtered by acapsfilter
. - A
TrackElement
is aTimelineElement
that specifically belongs to a singleTrack
of itstimeline
. Itsstart
andduration
specify its temporal extent in the track. Specifically, a track element wraps some nleobject, such as annlesource
ornleoperation
, which can be retrieved withTrackElementExt::nleobject()
, and itsstart
,duration
,in-point
,priority
andactive
properties expose the corresponding nleobject properties. When a track element is added to a track, its nleobject is added to the correspondingnlecomposition
that the track wraps. - Properties
- 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.
- Properties
- Asset to create a stream specific
Source
for a media file. - Base class for video sources
- Children Properties
- A
VideoTrack
is a default videoTrack
, with aTrackType::VIDEO
track-type
and “video/x-raw(ANY)”caps
. - Properties
- 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, itsstart
,duration
orin-point
will be adjusted accordingly. In addition, any clips may changelayer
. - Horizontal alignment of the text.
- Vertical alignment of the text.
- The test pattern to produce