gst-plugins-rs/net/webrtc/examples
Mathieu Duponchelle 87c6719e1d webrtcsink: add define-encoder-bitrates signal
When congestion control is used for a session with multiple encoders,
the default implementation simply divides the overall bitrate equally
between encoders.

This is not always desirable, and this patch exposes a new signal
that users can register to, with two arguments:

* The overall bitrate to allocate
* A structure with an encoder.stream_name -> bitrate mapping

Handlers should return a similar structure with a custom mapping.

An example is also provided.

Part-of: <https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/-/merge_requests/1792>
2024-09-25 15:19:44 +00:00
..
android/webrtcsrc webrtc: add android webrtcsrc example 2024-05-24 16:14:13 +00:00
webrtcsink-custom-signaller webrtc: Remove unnecessary manual Send+Sync implementations for signallers 2024-01-18 10:01:25 +02:00
webrtcsink-stats webrtc: examples: Update package-lock.json 2022-12-26 23:10:40 +00:00
README.md webrtc: add raw payload support 2024-07-16 19:32:02 +00:00
webrtc-precise-sync-recv.rs webrtc: add raw payload support 2024-07-16 19:32:02 +00:00
webrtc-precise-sync-send.rs webrtc: add raw payload support 2024-07-16 19:32:02 +00:00
webrtcsink-custom-signaller.py webrtcsink: Add a custom signaller example in Python 2024-05-10 15:59:12 +00:00
webrtcsink-define-encoder-bitrates.rs webrtcsink: add define-encoder-bitrates signal 2024-09-25 15:19:44 +00:00
webrtcsink-high-quality-tune.rs Slightly improve code making use of element factories retrieved from an element 2024-06-19 13:03:37 +00:00
webrtcsink-stats-server.rs Slightly improve code making use of element factories retrieved from an element 2024-06-19 13:03:37 +00:00
whipserver.rs net/webrtc: Example for whipserver 2024-05-29 21:03:27 +00:00

webrtcsink examples

Collection of webrtcsink examples

webrtcsink-stats-server

A simple application that instantiates a webrtcsink and serves stats over websockets.

The application expects a signalling server to be running at ws://localhost:8443, similar to the usage example in the main README.

cargo run --example webrtcsink-stats-server

Once it is running, follow the instruction in the webrtcsink-stats folder to run an example client.

webrtcsink-custom-signaller

An example of custom signaller implementation, see the corresponding README for more details on code and usage.

WebRTC precise synchronization example

This example demonstrates a sender / receiver setup which ensures precise synchronization of multiple streams in a single session.

RFC 6051-style rapid synchronization of RTP streams is available as an option. Se the Instantaneous RTP synchronization... blog post for details about this mode and an example based on RTSP instead of WebRTC.

The examples can also be used for RFC 7273 NTP or PTP clock signalling and synchronization.

Finally, raw payloads (e.g. L24 audio) can be negotiated.

Note: you can have your host act as an NTP server, which can help the examples with clock synchronization. For chrony, this can be configure by editing /etc/chrony.conf and uncommenting / editing the allow entry. The examples can then be launched with --ntp-server _ip_address_.

Signaller

The example uses the default WebRTC signaller. Launch it using the following command:

cargo run --bin gst-webrtc-signalling-server --no-default-features

Receiver

The receiver awaits for new audio & video stream publishers and render the streams using auto sink elements. Launch it using the following command:

cargo r --example webrtc-precise-sync-recv --no-default-features

The default configuration should work for a local test. For a multi-host setup, see the available options:

cargo r --example webrtc-precise-sync-recv --no-default-features -- --help

E.g.: the following will force avdec_h264 over hardware decoders, activate debug logs for the receiver and connect to the signalling server at the specified address:

GST_PLUGIN_FEATURE_RANK=avdec_h264:MAX \
WEBRTC_PRECISE_SYNC_RECV_LOG=debug \
cargo r --example webrtc-precise-sync-recv --no-default-features -- \
  --server 192.168.1.22

Sender

The sender publishes audio & video test streams. Launch it using the following command:

cargo r --example webrtc-precise-sync-send --no-default-features

The default configuration should work for a local test. For a multi-host setup, to set the number of audio / video streams, to enable rapid synchronization or to force the video encoder, see the available options:

cargo r --example webrtc-precise-sync-send --no-default-features -- --help

E.g.: the following will force H264 and x264enc over hardware encoders, activate debug logs for the sender and connect to the signalling server at the specified address:

GST_PLUGIN_FEATURE_RANK=264enc:MAX \
WEBRTC_PRECISE_SYNC_SEND_LOG=debug \
cargo r --example webrtc-precise-sync-send --no-default-features -- \
  --server 192.168.1.22 --video-caps video/x-h264

The pipeline latency

The --pipeline-latency argument configures a static latency of 1s by default. This needs to be higher than the sum of the sender latency and the receiver latency of the receiver with the highest latency. As this can't be known automatically and depends on many factors, this has to be known for the overall system and configured accordingly.

The default configuration is on the safe side and favors synchronization over low latency. Depending on the use case, shorter or larger values should be used.

RFC 7273 NTP or PTP clock signalling and synchronization

For RFC 7273 NTP or PTP clock signalling and synchronization, you can use commands such as:

Receiver

cargo r --example webrtc-precise-sync-recv --no-default-features -- \
  --expect-clock-signalling

Sender

cargo r --example webrtc-precise-sync-send --no-default-features -- \
  --clock ntp --do-clock-signalling \
  --video-streams 0 --audio-streams 2

Raw payload

The sender can be instructed to send raw payloads. Note that raw payloads are not activated by default and must be selected explicitly.

This command will stream two stereo L24 streams:

cargo r --example webrtc-precise-sync-send --no-default-features -- \
  --video-streams 0 \
  --audio-streams 2 --audio-codecs L24

Launch the receiver with:

cargo r --example webrtc-precise-sync-recv --no-default-features -- \
  --audio-codecs L24

This can be used to stream multiple RAW video streams using specific CAPS for the streams and allowing fallback to VP8 & OPUS if remote doesn't support raw payloads:

cargo r --example webrtc-precise-sync-send --no-default-features -- \
  --video-streams 2 --audio-streams 1 \
  --video-codecs RAW --video-codecs VP8 --video-caps video/x-raw,format=I420,width=400 \
  --audio-codecs L24 --audio-codecs OPUS --audio-caps audio/x-raw,rate=48000,channels=2

Android

webrtcsrc based Android application

An Android demonstration application which retrieves available producers from the signaller and renders audio and video streams.

Important: in order to ease testing, this demonstration application enables unencrypted network communication. See app/src/main/AndroidManifest.xml for details.

Build the application

  • Download the latest Android prebuilt binaries from: https://gstreamer.freedesktop.org/download/
  • Uncompress / untar the package, e.g. under /opt/android/.
  • Define the GSTREAMER_ROOT_ANDROID environment variable with the directory chosen at previous step.
  • Install a recent version of Android Studio (tested with 2023.3.1.18).
  • Open the project from the folder android/webrtcsrc.
  • Have Android Studio download and install the required SDK & NDK.
  • Click the build button or build and run on the target device.
  • The resulting apk is generated under: android/webrtcsrc/app/build/outputs/apk/debug.

For more details, refer to:

Once the SDK & NDK are installed, you can use gradlew to build and install the apk (make sure the device is visible from adb):

# From the android/webrtcsrc directory
./gradlew installDebug

Install the application

Prerequisites: activate developer mode on the target device.

There are several ways to install the application:

  • The easiest is to click the run button in Android Studio.
  • You can also install the apk using adb.

Depending on your host OS, you might need to define udev rules. See: https://github.com/M0Rf30/android-udev-rules

Setup

  1. Run the Signaller from the gst-plugins-rs root directory:
    cargo run --bin gst-webrtc-signalling-server
    
  2. In the Android app, tap the 3 dots button -> Settings and edit the Signaller URI.
  3. Add a producer, e.g. using gst-launch & webrtcsink or run:
    cargo r --example webrtc-precise-sync-send
    
  4. Click the Refresh button on the Producer List view of the app.