subprojects/gst-examples/webrtc/README.md

   1 # GStreamer WebRTC demos
   2
   3 All demos use the same signalling server in the `signalling/` directory
   4
   5 ## Downloading GStreamer
   6
   7 The GStreamer WebRTC implementation has now been merged upstream, and is in the GStreamer 1.14 release. Binaries can be found here:
   8
   9 https://gstreamer.freedesktop.org/download/
  10
  11 ## Building GStreamer from source
  12
  13 If you don't want to use the binaries provided by GStreamer or on your Linux distro, you can build GStreamer from source.
  14
  15 The easiest way to build the webrtc plugin and all the plugins it needs, is to [use Cerbero](https://gstreamer.freedesktop.org/documentation/installing/building-from-source-using-cerbero.html). These instructions should work out of the box for all platforms, including cross-compiling for iOS and Android.
  16
  17 ## Building GStreamer manually from source
  18
  19 For hacking on the webrtc plugin, you may want to build manually using the git repositories:
  20
  21  - http://gitlab.freedesktop.org/gstreamer/gstreamer
  22  - http://gitlab.freedesktop.org/gstreamer/gst-plugins-base
  23  - http://gitlab.freedesktop.org/gstreamer/gst-plugins-good
  24  - http://gitlab.freedesktop.org/gstreamer/gst-plugins-bad
  25  - http://gitlab.freedesktop.org/libnice/libnice
  26
  27 Or with Meson gst-build:
  28
  29 https://gitlab.freedesktop.org/gstreamer/gst-build/
  30
  31 You may need to install the following packages using your package manager:
  32
  33 json-glib, libsoup, libnice, libnice-gstreamer1 (the gstreamer plugin for libnice, called gstreamer1.0-nice Debian)
  34
  35 ### Ubuntu 18.04
  36
  37 Here are the commands for Ubuntu 18.04.
  38
  39 ```
  40 sudo apt-get install -y gstreamer1.0-tools gstreamer1.0-nice gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-plugins-good libgstreamer1.0-dev git libglib2.0-dev libgstreamer-plugins-bad1.0-dev libsoup2.4-dev libjson-glib-dev
  41 ```
  42
  43 ## Filing bugs
  44
  45 Please only file bugs about the demos here. Bugs about GStreamer's WebRTC implementation should be filed on the [GStreamer gitlab](https://gitlab.freedesktop.org/gstreamer/gst-plugins-bad/-/issues/new).
  46
  47 You can also find us on IRC by joining #gstreamer @ FreeNode.
  48
  49 ## Documentation
  50
  51 Currently, the best way to understand the API is to read the examples. This post breaking down the API should help with that:
  52
  53 http://blog.nirbheek.in/2018/02/gstreamer-webrtc.html
  54
  55 ## Examples
  56
  57 ### Building
  58
  59 Most of the examples that require a build process can be built using the meson build system in the top-level gst-examples directory by using the following commands:
  60
  61 ```console
  62 cd /path/to/gst-examples
  63 meson _builddir
  64 ninja -C _builddir
  65 ```
  66
  67 Build outputs will be placed in the directory `_builddir`.
  68
  69 ### sendrecv: Send and receive audio and video
  70
  71 * Serve the `js/` directory on the root of your website, or open https://webrtc.nirbheek.in
  72   - The JS code assumes the signalling server is on port 8443 of the same server serving the HTML
  73
  74 * Open the website in a browser and ensure that the status is "Registered with server, waiting for call", and note the `id` too.
  75
  76 #### Running the C version
  77
  78 * Run `webrtc-sendrecv --peer-id=ID` with the `id` from the browser. You will see state changes and an SDP exchange.
  79
  80 #### Running the Python version
  81
  82 * python3 -m pip install --user websockets
  83 * run `python3 sendrecv/gst/webrtc_sendrecv.py ID` with the `id` from the browser. You will see state changes and an SDP exchange.
  84
  85 > The python version requires at least version 1.14.2 of gstreamer and its plugins.
  86
  87 #### Running the Rust version
  88
  89 * Install a recent Rust toolchain, e.g. via [rustup](https://rustup.rs/).
  90 * Run `cargo build` for building the executable.
  91 * Run `cargo run -- --peer-id=ID` with the `id` from the browser. You will see state changes and an SDP exchange.
  92
  93 With all versions, you will see a bouncing ball + hear red noise in the browser, and your browser's webcam + mic in the gst app.
  94
  95 You can pass a --server argument to all versions, for example `--server=wss://127.0.0.1:8443`.
  96
  97 #### Running the Java version
  98
  99 `cd sendrecv/gst-java`\
 100 `./gradlew build`\
 101 `java -jar build/libs/gst-java.jar --peer-id=ID` with the `id` from the browser.
 102
 103 You can optionally specify the server URL too (it defaults to wss://webrtc.nirbheek.in:8443):
 104
 105 `java -jar build/libs/gst-java.jar --peer-id=1 --server=ws://localhost:8443`
 106
 107 ### multiparty-sendrecv: Multiparty audio conference with N peers
 108
 109 * Run `_builddir/multiparty-sendrecv/gst/mp-webrtc-sendrecv --room-id=ID` with `ID` as a room name. The peer will connect to the signalling server and setup a conference room.
 110 * Run this as many times as you like, each will spawn a peer that sends red noise and outputs the red noise it receives from other peers.
 111   - To change what a peer sends, find the `audiotestsrc` element in the source and change the `wave` property.
 112   - You can, of course, also replace `audiotestsrc` itself with `autoaudiosrc` (any platform) or `pulsesink` (on linux).
 113 * TODO: implement JS to do the same, derived from the JS for the `sendrecv` example.
 114
 115 ### TODO: Selective Forwarding Unit (SFU) example
 116
 117 * Server routes media between peers
 118 * Participant sends 1 stream, receives n-1 streams
 119
 120 ### TODO: Multipoint Control Unit (MCU) example
 121
 122 * Server mixes media from all participants
 123 * Participant sends 1 stream, receives 1 stream