README.md 7.09 KB
Newer Older
1
# gstreamer-rs [![crates.io](https://img.shields.io/crates/v/gstreamer.svg)](https://crates.io/crates/gstreamer) [![Build Status](https://travis-ci.org/sdroege/gstreamer-rs.svg?branch=master)](https://travis-ci.org/sdroege/gstreamer-rs)
Sebastian Dröge's avatar
Sebastian Dröge committed
2
3

[GStreamer](https://gstreamer.freedesktop.org/) bindings for Rust.
4
Documentation can be found [here](https://sdroege.github.io/rustdoc/gstreamer/gstreamer/).
Sebastian Dröge's avatar
Sebastian Dröge committed
5
6
7
8
9
10

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

For background and motivation, see the [announcement blogpost](https://coaxion.net/blog/2017/07/writing-gstreamer-applications-in-rust/).

11
The bindings (since 0.8.0) are autogenerated with [gir](https://github.com/gtk-rs/gir/)
Sebastian Dröge's avatar
Sebastian Dröge committed
12
based on the [GObject-Introspection](https://wiki.gnome.org/Projects/GObjectIntrospection/)
13
14
15
API metadata provided by the GStreamer project. Older versions before 0.8.0 were manually
written and the repository can be found [here](https://github.com/arturoc/gstreamer1.0-rs).
The API of the two is incompatible.
Sebastian Dröge's avatar
Sebastian Dröge committed
16
17
18

A crate for writing GStreamer plugins in Rust can be found here: https://github.com/sdroege/gst-plugin-rs

19
20
21
22
23
24
25
26
27
28
29
## Table of Contents
1. [Installation](#installation)
   1. [Linux/BSDs](#installation-linux)
   1. [macOS](#installation-macos)
   1. [Windows](#installation-windows)
1. [Getting Started](#getting-started)
1. [License](#license)
1. [Contribution](#contribution)

<a name="installation"/>

30
31
32
33
34
35
36
37
## 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.

38
39
<a name="installation-linux"/>

40
41
42
43
44
45
46
47
48
49
50
### 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 \
51
      gstreamer1.0-libav libgstrtspserver-1.0-dev
52
53
```

Charlie Turner's avatar
Charlie Turner committed
54
55
56
57
58
59
60
61
62
63
64
65
66
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
```

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

70
71
<a name="installation-macos"/>

72
73
74
75
76
77
78
79
80
81
### macOS

You can install GStreamer and the plugins via [Homebrew](https://brew.sh/) or
by installing the [binaries](https://gstreamer.freedesktop.org/data/pkg/osx/)
provided by the GStreamer project.

#### Homebrew

```
$ brew install gstreamer gst-plugins-base gst-plugins-good \
82
      gst-plugins-bad gst-plugins-ugly gst-libav gst-rtsp-server
83
84
```

Charlie Turner's avatar
Charlie Turner committed
85
86
87
88
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.

89
90
91
92
93
94
95
96
97
98
#### 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

```
99
$ export PKG_CONFIG_PATH="/Library/Frameworks/GStreamer.framework/Versions/Current/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}"
100
101
```

102
103
<a name="installation-windows"/>

104
105
106
107
108
109
110
111
112
113
114
115
### Windows

You can install GStreamer and the plugins via [MSYS2](http://www.msys2.org/)
with `pacman` or by installing the
[binaries](https://gstreamer.freedesktop.org/data/pkg/windows/) provided by
the GStreamer project.

#### MSYS2 / pacman

```
$ pacman -S 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 \
116
117
      mingw-w64-x86_64-gst-plugins-ugly mingw-w64-x86_64-gst-libav \
      mingw-w64-x86_64-gst-rtsp-server
118
119
```

Charlie Turner's avatar
Charlie Turner committed
120
121
122
123
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.

124
125
126
127
128
129
130
131
132
133
134
135
136
137
#### 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](https://sourceforge.net/projects/pkgconfiglite/))
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}"
```

138
139
<a name="getting-started"/>

140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
## Getting Started

The API reference can be found
[here](https://sdroege.github.io/rustdoc/gstreamer/gstreamer/), 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](https://gstreamer.freedesktop.org/documentation/) on the
GStreamer website, especially the [Application Development
Manual](https://gstreamer.freedesktop.org/documentation/application-development/).
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](https://gstreamer.freedesktop.org/documentation/tutorials/) on the
GStreamer website. Many of them were ported to Rust already and the code can
be found in the
[tutorials](https://github.com/sdroege/gstreamer-rs/tree/master/tutorials)
directory.

Some further examples for various aspects of GStreamer and how to use it from
Rust can be found in the
[examples](https://github.com/sdroege/gstreamer-rs/tree/master/examples)
directory.

167
168
<a name="license"/>

Sebastian Dröge's avatar
Sebastian Dröge committed
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
## LICENSE

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

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
   http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](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

184
185
<a name="contribution"/>

Sebastian Dröge's avatar
Sebastian Dröge committed
186
187
188
189
190
191
192
## 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.