README.md 8.48 KB
Newer Older
1
# gst-plugins-rs [![crates.io](https://img.shields.io/crates/v/gst-plugin.svg)](https://crates.io/crates/gst-plugin) [![pipeline status](https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/badges/main/pipeline.svg)](https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/commits/main)
2

3
4
5
6
7
Repository containing various [GStreamer](https://gstreamer.freedesktop.org/)
plugins and elements written in the [Rust programming
language](https://www.rust-lang.org/).

The plugins build upon the [GStreamer Rust bindings](https://gitlab.freedesktop.org/gstreamer/gstreamer-rs).
8
9
10
Check the README.md of that repository also for details about how to set-up
your development environment.

11
12
13
14
15
## Plugins

You will find the following plugins in this repository:

  * `generic`
16
    - `file`: A Rust implementation of the standard `filesrc` and `filesink` elements
17

18
    - `fmp4`: A fragmented MP4/ISOBMFF/CMAF muxer for generating e.g. DASH/HLS media fragments.
19

20
21
22
    - `sodium`: Elements to perform encryption and decryption using [libsodium](https://libsodium.org).

    - `threadshare`: Some popular threaded elements reimplemented using common thread-sharing infrastructure.
23
24

  * `net`
25
    - `hlssink3`: An element for generating MPEG-TS HLS streams.
26

27
    - `reqwest`: An HTTP source element based on the [reqwest](https://github.com/seanmonstar/reqwest) library.
28

Sanchayan Maity's avatar
Sanchayan Maity committed
29
    - `aws`: Various elements for Amazon AWS services using the [AWS SDK](https://awslabs.github.io/aws-sdk-rust/) library
30
      - `s3src`/`s3sink`: A source and sink element to talk to the Amazon S3 object storage system.
31
      - `s3hlssink`: A sink element to store HLS streams on Amazon S3.
32
      - `aws_transcriber`: an element wrapping the AWS Transcriber service.
33

34
35
    - `raptorq`: Encoder/decoder element for RaptorQ RTP FEC mechanism.

36
37
38
39
40
41
42
43
  * `audio`
    - `audiofx`: Elements to apply audio effects to a stream
      - `rsaudioecho`: a simple echo/reverb filter.
      - `rsaudioloudnorm`: [audio normalization](http://k.ylo.ph/2016/04/04/loudnorm.html) filter.
      - `audiornnoise`: Filter for [removing noise](https://jmvalin.ca/demo/rnnoise/).
      - `ebur128level`: Filter for measuring audio loudness according to EBU R-128.
      - `hrtfrender`: Filter for rendering audio according to a [head-related transfer
        function](https://en.wikipedia.org/wiki/Head-related_transfer_function).
44

45
    - `claxon`: A FLAC decoder based on the [Claxon](https://github.com/ruuda/claxon) library.
46

47
    - `csound`: A plugin to implement audio effects using the [Csound](https://csound.com/) library.
48

49
    - `lewton`: A Vorbis decoder based on the [lewton](https://github.com/RustAudio/lewton) library.
Guillaume Desmottes's avatar
Guillaume Desmottes committed
50

51
    - `spotify`: A plugin to access content from [Spotify](https://www.spotify.com/) based on the [librespot](https://github.com/librespot-org/) library.
Guillaume Desmottes's avatar
Guillaume Desmottes committed
52

53
  * `video`
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
    - `cdg`: A parser and renderer for [CD+G karaoke data](https://docs.rs/cdg/0.1.0/cdg/).

    - `closedcaption`: Plugin to deal with closed caption streams
      - `ccdetect`: Detects if a stream contains active Closed Captions.
      - `cea608overlay`: Overlay CEA-608 / EIA-608 closed captions over a
        video stream.
      - `cea608tojson`: Convert CEA-608 / EIA-608 closed captions to a JSON
        stream.
      - `cea608tott`: Convert CEA-608 / EIA-608 closed captions to timed text.
      - `jsontovtt`: Convert JSON to timed text.
      - `mccenc`: Convert CEA-608 / EIA-608 and CEA-708 / EIA-708 closed captions to the MCC format.
      - `mccparse`: Parse CEA-608 / EIA-608 and CEA-708 / EIA-708 closed captions from the MCC format.
      - `sccenc`: Convert CEA-608 / EIA-608 closed captions to the MCC format.
      - `sccparse`: Parse CEA-608 / EIA-608 closed captions from the MCC format.
      - `transcriberbin`: Convenience bin around transcriber elements like `aws_transcriber`.
      - `tttocea608`: Convert timed text to CEA-608 / EIA-608 closed captions.
      - `tttojson`: Convert timed text to JSON.

    - `dav1d`: AV1 decoder based on the [dav1d](https://code.videolan.org/videolan/dav1d) library.
73

74
    - `ffv1`: FFV1 decoder based on the [ffv1](https://github.com/rust-av/ffv1) library.
75

76
    - `flavors`: FLV demuxer based on the [flavors](https://github.com/rust-av/flavors) library.
77

78
    - `gif`: A GIF encoder based on the [gif](https://github.com/image-rs/image-gif) library.
79

80
    - `gtk4`: A [GTK4](https://www.gtk.org) video sink that provides a `GdkPaintable` for UI integration.
81

82
83
84
    - `hsv`: Plugin with various elements to work with video data in hue, saturation, value format
       - `hsvdetector`: Mark pixels that are close to a configured color in HSV format.
       - `hsvfilter`: Apply various transformations in the HSV colorspace.
85

86
    - `png`: PNG encoder based on the [png](https://github.com/image-rs/image-png) library.
87

88
    - `rav1e`: AV1 encoder based on the [rav1e](https://github.com/xiph/rav1e) library.
89

90
91
    - `videofx`: Plugin with various video filters.
      - `roundedcorners`: Element to make the corners of a video rounded via the alpha channel.
92
      - `colordetect`: A pass-through filter able to detect the dominant color(s) on incoming frames, using [color-thief](https://github.com/RazrFalcon/color-thief-rs).
93

94
    - `webp`: WebP decoder based on the [libwebp-sys-2](https://github.com/qnighy/libwebp-sys2-rs) library.
95
96

  * `text`
97
98
99
    - `ahead`: A plugin to display upcoming text buffers ahead.

    - `json`: A plugin to convert a stream of JSON objects to a higher level wrapped NDJSON output.
100
101
102
103
104

    - `regex`: A regular expression text filter plugin.

    - `wrap`: A plugin to perform text wrapping with hyphenation.

105
  * `utils`
106
107
108
109
110
111
112
113
    - `fallbackswitch`:
      - `fallbackswitch`: An element that allows falling back to different
        sink pads after a timeout based on the sink pads' priorities.
      - `fallbacksrc`: Element similar to `urisourcebin` that allows
        configuring a fallback audio/video if there are problems with the main
        source.

    - `togglerecord`: Element to enable starting and stopping multiple streams together.
114

115
116
117
118
119
120
121
122
123
124
125
    - `tracers`: Plugin with multiple tracers:
      - `buffer-lateness`: Records lateness of buffers and the reported
        latency for each pad in a CSV file. Contains a script for
        visualization.
      - `pipeline-snapshot`: Creates a .dot file of all pipelines in the
        application whenever requested.
      - `queue-levels`: Records queue levels for each queue in a CSV file.
        Contains a script for visualization.

    - `uriplaylistbin`: Helper bin to gaplessly play a list of URIs.

126
127
128
129
130
131
132
133
134
135
136
137
## Building

gst-plugins-rs relies on [cargo-c](https://github.com/lu-zero/cargo-c/) to
generate shared and static C libraries. It can be installed using:

```
$ cargo install cargo-c
```

Then you can easily build and test a specific plugin:

```
138
$ cargo cbuild -p gst-plugin-cdg
139
$ GST_PLUGIN_PATH="target/x86_64-unknown-linux-gnu/debug:$GST_PLUGIN_PATH" gst-inspect-1.0 cdgdec
140
141
```

142
143
Replace `x86_64-unknown-linux-gnu` with your system's Rust target triple (`rustc -vV`).

144
145
146
The plugin can also be installed system-wide:

```
147
148
$ cargo cbuild -p gst-plugin-cdg --prefix=/usr
$ cargo cinstall -p gst-plugin-cdg --prefix=/usr
149
150
151
152
153
154
155
156
157
158
```

This will install the plugin to `/usr/lib/gstreamer-1.0`.
You can use `--libdir` to pass a custom `lib` directory
such as `/usr/lib/x86_64-linux-gnu` for example.

Note that you can also just use `cargo` directly to build Rust static libraries
and shared C libraries. `cargo-c` is mostly useful to build static C libraries
and generate `pkg-config` files.

159
160
161
In case cargo complains about dependency versions after a `git pull`, `cargo update` may
be able to resolve those.

162
163
## LICENSE

164
165
gst-plugins-rs and all crates contained in here are licensed under one of the
following licenses
166

167
168
169
170
 * Mozilla Public License Version 2.0 ([LICENSE-MPL-2.0](LICENSE-MPL-2.0) or http://opensource.org/licenses/MPL-2.0)
 * 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)
 * Lesser General Public License ([LICENSE-LGPLv2](LICENSE-LGPLv2)) version 2.1 or (at your option) any later version
171

172
GStreamer itself is licensed under the Lesser General Public License version
173
2.1 or (at your option) any later version: https://www.gnu.org/licenses/lgpl-2.1.html
174
175
176

## Contribution

177
Any kinds of contributions are welcome as a merge request.
178
179

Unless you explicitly state otherwise, any contribution intentionally submitted
180
181
182
183
for inclusion in gst-plugins-rs by you shall be licensed under the license of
the plugin it is added to.

For new plugins the MPL-2 license is preferred.