From cbdd3a7f26dfc231ca05a2fe261e0beb78c966d6 Mon Sep 17 00:00:00 2001 From: Thibault Saunier Date: Thu, 20 Oct 2022 12:25:32 +0200 Subject: [PATCH] webrtc: Enhance documentation --- docs/meson.build | 1 + net/webrtc/README.md | 35 ++++++-------------------------- net/webrtc/src/gcc/imp.rs | 29 +++++++++++++++++--------- net/webrtc/src/webrtcsink/mod.rs | 6 ++++++ 4 files changed, 32 insertions(+), 39 deletions(-) diff --git a/docs/meson.build b/docs/meson.build index a6f09891..1d79a90a 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -97,6 +97,7 @@ foreach plugin_name: list_plugin_res.stdout().split(':') sitemap: 'plugins/sitemap.txt', index: 'plugins/index.md', gst_index: 'plugins/index.md', + include_paths: join_paths(meson.current_source_dir(), '..'), gst_smart_index: true, gst_c_sources: [ '../*/*/*/*.rs', diff --git a/net/webrtc/README.md b/net/webrtc/README.md index 5380f260..45c4dd67 100644 --- a/net/webrtc/README.md +++ b/net/webrtc/README.md @@ -64,27 +64,10 @@ expose more interfaces to guide and tune the heuristics it employs. ## Building -### Prerequisites - -The element has only been tested for now against GStreamer main. - -For testing, it is recommended to simply build GStreamer locally and run -in the uninstalled devenv. - > Make sure to install the development packages for some codec libraries > beforehand, such as libx264, libvpx and libopusenc, exact names depend > on your distribution. -``` -git clone --depth 1 --single-branch --branch main https://gitlab.freedesktop.org/gstreamer/gstreamer -cd gstreamer -meson build -ninja -C build -ninja -C build devenv -``` - -### Compiling - ``` shell cargo build ``` @@ -110,11 +93,11 @@ export GST_PLUGIN_PATH=$PWD/target/debug:$GST_PLUGIN_PATH gst-launch-1.0 webrtcsink name=ws videotestsrc ! ws. audiotestsrc ! ws. ``` -When the pipeline above is running succesfully, open a browser and +When the pipeline above is running successfully, open a browser and point it to the http server: ``` shell -xdg-open http://127.0.0.1:8000 +gio open http://127.0.0.1:8000 ``` You should see an identifier listed in the left-hand panel, click on @@ -133,12 +116,6 @@ with gst-launch: gst-launch-1.0 webrtcsink signaller::address="ws://127.0.0.1:8443" .. ``` -The signaller object can not be inspected, refer to [the source code] -for the list of properties. - -[the source code]: plugins/src/signaller/imp.rs - - ### Enable 'navigation' a.k.a user interactivity with the content `webrtcsink` implements the [`GstNavigation`] interface which allows interacting @@ -152,7 +129,7 @@ As an example, the following pipeline allows you to navigate the GStreamer documentation inside the video running within your web browser (in http://127.0.0.1:8000 if you followed previous steps of that readme): -``` +``` shell gst-launch-1.0 wpesrc location=https://gstreamer.freedesktop.org/documentation/ ! webrtcsink enable-data-channel-navigation=true ``` @@ -181,7 +158,7 @@ My testing procedure was: * Run a `comcast` command on the server machine, for instance: ``` shell - /home/meh/go/bin/comcast --device=$SERVER_INTERFACE --target-bw 3000 --target-addr=$CLIENT_IP --target-port=1:65535 --target-proto=udp + $HOME/go/bin/comcast --device=$SERVER_INTERFACE --target-bw 3000 --target-addr=$CLIENT_IP --target-port=1:65535 --target-proto=udp ``` * Observe the bitrate sharply decreasing, playback should slow down briefly @@ -191,7 +168,7 @@ My testing procedure was: back to a maximum: ``` shell - /home/meh/go/bin/comcast --device=$SERVER_INTERFACE --stop + $HOME/go/bin/comcast --device=$SERVER_INTERFACE --stop ``` For comparison, the congestion control property can be set to disabled on @@ -210,7 +187,7 @@ gst-launch-1.0 webrtcsink congestion-control=disabled An example server / client application for monitoring per-consumer stats can be found [here]. -[here]: plugins/examples/README.md +[here]: https://gitlab.freedesktop.org/gstreamer/gst-plugins-rs/-/tree/main/net/webrtc/examples ## License diff --git a/net/webrtc/src/gcc/imp.rs b/net/webrtc/src/gcc/imp.rs index 68d53ec6..4899e8ea 100644 --- a/net/webrtc/src/gcc/imp.rs +++ b/net/webrtc/src/gcc/imp.rs @@ -1,13 +1,22 @@ -///! Implements https://datatracker.ietf.org/doc/html/draft-ietf-rmcat-gcc-02 -///! -///! This element implements the pacing as describe in the spec by running its -///! own streaming thread on its srcpad. It implements the mathematic as closely -///! to the specs as possible and sets the #rtpgccbwe:estimated-bitrate property -///! each time a new estimate is produced. User should connect to the -///! `rtpgccbwe::notify::estimated-bitrate` signal to make the encoders target -///! that new estimated bitrate (the overall target bitrate of the potentially -///! multiple encore should match that target bitrate, the application is -///! responsible for determining what bitrate to give to each encode) +/** + * element-rtpgccbwe: + * + * Implements the [Google Congestion Control algorithm](https://datatracker.ietf.org/doc/html/draft-ietf-rmcat-gcc-02). + * + * This element should always be placed right before a `rtpsession` and will only work + * when [twcc](https://datatracker.ietf.org/doc/html/draft-holmer-rmcat-transport-wide-cc-extensions-01) is enabled + * as the bandwidth estimation relies on it. + * + * This element implements the pacing as describe in the spec by running its + * own streaming thread on its srcpad. It implements the mathematic as closely + * to the specs as possible and sets the #rtpgccbwe:estimated-bitrate property + * each time a new estimate is produced. User should connect to the + * `rtpgccbwe::notify::estimated-bitrate` signal to make the encoders target + * that new estimated bitrate (the overall target bitrate of the potentially + * multiple encoders should match that target bitrate, the application is + * responsible for determining what bitrate to give to each encode) + * + */ use chrono::Duration; use gst::{ glib::{self}, diff --git a/net/webrtc/src/webrtcsink/mod.rs b/net/webrtc/src/webrtcsink/mod.rs index b5df7543..0c03e380 100644 --- a/net/webrtc/src/webrtcsink/mod.rs +++ b/net/webrtc/src/webrtcsink/mod.rs @@ -1,5 +1,11 @@ // SPDX-License-Identifier: MPL-2.0 +/** + * element-webrtcsink: + * + * {{ net/webrtc/README.md[0:190] }} + * + */ use gst::glib; use gst::prelude::*; use gst::subclass::prelude::*;