1# gstreamer-rs [![crates.io](https://img.shields.io/crates/v/gstreamer-net.svg)](https://crates.io/crates/gstreamer-net) [![pipeline status](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/badges/master/pipeline.svg)](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/commits/master) 2 3[GStreamer](https://gstreamer.freedesktop.org/) (Net library) bindings for Rust. 4Documentation can be found [here](https://slomo.pages.freedesktop.org/rustdocs/gstreamer/gstreamer_net/). 5 6These bindings are providing a safe API that can be used to interface with 7GStreamer, e.g. for writing GStreamer-based applications and GStreamer plugins. 8 9The bindings are mostly autogenerated with [gir](https://github.com/gtk-rs/gir/) 10based on the [GObject-Introspection](https://wiki.gnome.org/Projects/GObjectIntrospection/) 11API metadata provided by the GStreamer project. 12 13## Table of Contents 141. [Installation](#installation) 15 1. [Linux/BSDs](#installation-linux) 16 1. [macOS](#installation-macos) 17 1. [Windows](#installation-windows) 181. [Getting Started](#getting-started) 191. [License](#license) 201. [Contribution](#contribution) 21 22<a name="installation"/> 23 24## Installation 25 26To build the GStreamer bindings or anything depending on them, you need to 27have at least GStreamer 1.8 and gst-plugins-base 1.8 installed. In addition, 28some of the examples/tutorials require various GStreamer plugins to be 29available, which can be found in gst-plugins-base, gst-plugins-good, 30gst-plugins-bad, gst-plugins-ugly and/or gst-libav. 31 32<a name="installation-linux"/> 33 34### Linux/BSDs 35 36You need to install the above mentioned packages with your distributions 37package manager, or build them from source. 38 39On Debian/Ubuntu they can be installed with 40 41``` 42$ apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \ 43 gstreamer1.0-plugins-base gstreamer1.0-plugins-good \ 44 gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly \ 45 gstreamer1.0-libav libgstrtspserver-1.0-dev 46``` 47 48The minimum required version of the above libraries is >= 1.8. If you 49build the gstreamer-player sub-crate, or any of the examples that 50depend on gstreamer-player, you must ensure that in addition to the 51above packages, `libgstreamer-plugins-bad1.0-dev` is installed and 52that the version is >= 1.12. See the `Cargo.toml` files for the full 53details, 54 55``` 56# Only if you wish to install gstreamer-player, make sure the version 57# of this package is >= 1.12. 58$ apt-get install libgstreamer-plugins-bad1.0-dev 59``` 60 61Package names on other distributions should be similar. 62Please submit a pull request with instructions for yours. 63 64<a name="installation-macos"/> 65 66### macOS 67 68You can install GStreamer and the plugins via [Homebrew](https://brew.sh/) or 69by installing the [binaries](https://gstreamer.freedesktop.org/data/pkg/osx/) 70provided by the GStreamer project. 71 72#### Homebrew 73 74Homebrew only installs various plugins if explicitly enabled, so some extra 75`--with-*` flags may be required. 76 77``` 78$ brew install gstreamer gst-plugins-base gst-plugins-good \ 79 gst-plugins-bad gst-plugins-ugly gst-libav gst-rtsp-server \ 80 gst-editing-services --with-orc --with-libogg --with-opus \ 81 --with-pango --with-theora --with-libvorbis --with-libvpx \ 82 --enable-gtk3 83``` 84 85If you wish to install the gstreamer-player sub-crate, make sure the 86version of these libraries is >= 1.12. Otherwise, a version >= 1.8 is 87sufficient. 88 89#### GStreamer Binaries 90 91You need to download the *two* `.pkg` files from the GStreamer website and 92install them, e.g. `gstreamer-1.0-1.12.3-x86_64.pkg` and 93`gstreamer-1.0-devel-1.12.3-x86_64.pkg`. 94 95After installation, you also need to install `pkg-config` (e.g. via Homebrew) 96and set the `PKG_CONFIG_PATH` environment variable 97 98``` 99$ export PKG_CONFIG_PATH="/Library/Frameworks/GStreamer.framework/Versions/Current/lib/pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}" 100``` 101 102<a name="installation-windows"/> 103 104### Windows 105 106You can install GStreamer and the plugins via [MSYS2](http://www.msys2.org/) 107with `pacman` or by installing the 108[binaries](https://gstreamer.freedesktop.org/data/pkg/windows/) provided by 109the GStreamer project. 110 111#### MSYS2 / pacman 112 113``` 114$ pacman -S pkg-config mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base \ 115 mingw-w64-x86_64-gst-plugins-good mingw-w64-x86_64-gst-plugins-bad \ 116 mingw-w64-x86_64-gst-plugins-ugly mingw-w64-x86_64-gst-libav \ 117 mingw-w64-x86_64-gst-rtsp-server 118``` 119 120If you wish to install the gstreamer-player sub-crate, make sure the 121version of these libraries is >= 1.12. Otherwise, a version >= 1.8 is 122sufficient. 123 124#### GStreamer Binaries 125 126You need to download the *two* `.msi` files for your platform from the 127GStreamer website and install them, e.g. `gstreamer-1.0-x86_64-1.12.3.msi` and 128`gstreamer-1.0-devel-x86_64-1.12.3.msi`. 129 130After installation, you also need to install `pkg-config` (e.g. via MSYS2 or 131from [here](https://sourceforge.net/projects/pkgconfiglite/)) 132and set the `PKG_CONFIG_PATH` environment variable 133 134``` 135$ export PKG_CONFIG_PATH="c:\\gstreamer\\1.0\\x86_64\\lib\\pkgconfig${PKG_CONFIG_PATH:+:$PKG_CONFIG_PATH}" 136``` 137 138<a name="getting-started"/> 139 140## Getting Started 141 142The API reference can be found 143[here](https://gstreamer.pages.freedesktop.org/gstreamer-rs/stable/latest/docs/gstreamer/), however it is 144only the Rust API reference and does not explain any of the concepts. 145 146For getting started with GStreamer development, the best would be to follow 147the [documentation](https://gstreamer.freedesktop.org/documentation/) on the 148GStreamer website, especially the [Application Development 149Manual](https://gstreamer.freedesktop.org/documentation/application-development/). 150While being C-centric, it explains all the fundamental concepts of GStreamer 151and the code examples should be relatively easily translatable to Rust. The 152API is basically the same, function/struct names are the same and everything 153is only more convenient (hopefully) and safer. 154 155In addition there are 156[tutorials](https://gstreamer.freedesktop.org/documentation/tutorials/) on the 157GStreamer website. Many of them were ported to Rust already and the code can 158be found in the 159[tutorials](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/tree/master/tutorials) 160directory. 161 162Some further examples for various aspects of GStreamer and how to use it from 163Rust can be found in the 164[examples](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs/tree/master/examples) 165directory. 166 167Various GStreamer plugins written in Rust can be found in the 168[gst-plugins-rs](https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs) 169repository. 170 171<a name="license"/> 172 173## LICENSE 174 175gstreamer-rs and all crates contained in here are licensed under either of 176 177 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or 178 http://www.apache.org/licenses/LICENSE-2.0) 179 * MIT license ([LICENSE-MIT](LICENSE-MIT) or 180 http://opensource.org/licenses/MIT) 181 182at your option. 183 184GStreamer itself is licensed under the Lesser General Public License version 1852.1 or (at your option) any later version: 186https://www.gnu.org/licenses/lgpl-2.1.html 187 188<a name="contribution"/> 189 190## Contribution 191 192Any kinds of contributions are welcome as a pull request. 193 194Unless you explicitly state otherwise, any contribution intentionally submitted 195for inclusion in gstreamer-rs by you, as defined in the Apache-2.0 license, shall be 196dual licensed as above, without any additional terms or conditions. 197