gst-plugins-rs/net/webrtc/gstwebrtc-api/README.md

# gstwebrtc-api

[![License: MPL 2.0](https://img.shields.io/badge/License-MPL_2.0-brightgreen.svg)](https://opensource.org/licenses/MPL-2.0)

Javascript API used to integrate GStreamer WebRTC streams produced and consumed by webrtcsink and webrtcsrc elements
into a web browser or a mobile WebView.

This API allows a complete 360º interconnection between GStreamer and web interfaces for realtime streaming using the
WebRTC protocol.

This API is released under the Mozilla Public License Version 2.0 (MPL-2.0) that can be found in the LICENSE-MPL-2.0
file or at https://opensource.org/licenses/MPL-2.0

Copyright (C) 2022 Igalia S.L. <<info@igalia.com>><br>
Author: Loïc Le Page <<llepage@igalia.com>>

It includes external source code from [webrtc-adapter](https://github.com/webrtcHacks/adapter) that is embedded with
the API. The webrtc-adapter BSD 3-Clause license is available at
https://github.com/webrtcHacks/adapter/blob/master/LICENSE.md

Webrtc-adapter is Copyright (c) 2014, The WebRTC project authors, All rights reserved.<br>
Copyright (c) 2018, The adapter.js project authors, All rights reserved.

It also includes Keyboard.js source code from the Apache [guacamole-client](https://github.com/apache/guacamole-client)
that is embedded with the API to enable remote control of the webrtcsink producer.

Keyboard.js is released under the Apache 2.0 license available at:
https://github.com/apache/guacamole-client/blob/master/LICENSE

## Building the API

The GstWebRTC API uses [Webpack](https://webpack.js.org/) to bundle all source files and dependencies together.

You only need to install [Node.js](https://nodejs.org/en/) to run all commands.

On first time, install the dependencies by calling:
```shell
$ npm install
```

Then build the bundle by calling:
```shell
$ npm run make
```

It will build and compress the code into the *dist/* folder, there you will find 2 files:
- *gstwebrtc-api-[version].min.js* which is the only file you need to include into your web application to use the API.
  It already embeds all dependencies.
- *gstwebrtc-api-[version].min.js.map* which is useful for debugging the API code, you need to put it in the same
  folder as the API script on your web server if you want to allow debugging, else you can just ignore it.

The API documentation is created into the *docs/* folder. It is automatically created when building the whole API.

If you want to build the documentation only, you can call:
```shell
$ npm run docs
```

If you only want to build the API without the documentation, you can call:
```shell
$ npm run build
```

## Packaging the API

You can create a portable package of the API by calling:
```shell
$ npm pack
```

It will create a *gstwebrtc-api-[version].tgz* file that contains all source code, documentation and built API. This
portable package can be installed as a dependency in any Node.js project by calling:
```shell
$ npm install gstwebrtc-api-[version].tgz
```

## Testing and debugging the API

To easily test and debug the GstWebRTC API, you just need to:
1. launch the webrtc signalling server by calling (from the repository *gst-plugins-rs* root folder):
   ```shell
   $ cargo run --bin gst-webrtc-signalling-server
   ```
2. launch the GstWebRTC API server by calling (from the *net/webrtc/gstwebrtc-api* sub-folder):
   ```shell
   $ npm start
   ```

It will launch a local HTTPS server listening on port 9090 and using an automatically generated self-signed
certificate.

With this server you can test the reference example shipped in *index.html* from a web browser on your local computer
or a mobile device.

## Interconnect with GStreamer pipelines

Once the signalling and gstwebrtc-api servers launched, you can interconnect the streams produced and consumed from
the web browser with GStreamer pipelines using the webrtcsink and webrtcsrc elements.

### Consume a WebRTC stream produced by the gstwebrtc-api

On the web browser side, click on the *Start Capture* button and give access to the webcam. The gstwebrtc-api will
start producing a video stream.

The signalling server logs will show the registration of a new producer with the same *peer_id* as the *Client ID*
that appears on the webpage.

Then launch the following GStreamer pipeline:
```shell
$ gst-launch-1.0 playbin uri=gstwebrtc://[signalling server]?peer-id=[client ID of the producer]
```

Using the local signalling server, it will look like this:
```shell
$ gst-launch-1.0 playbin uri=gstwebrtc://127.0.0.1:8443?peer-id=e54e5d6b-f597-4e8f-bc96-2cc3765b6567
```

The underlying *uridecodebin* element recognizes the *gstwebrtc://* scheme as a WebRTC stream compatible with the
gstwebrtc-api and will correctly use a *webrtcsrc* element to manage this stream.

The *gstwebrtc://* scheme is used for normal WebSocket connections to the signalling server, and the *gstwebrtcs://*
scheme for secured connections over SSL or TLS.

### Produce a GStreamer WebRTC stream consumed by the gstwebrtc-api

Launch the following GStreamer pipeline:
```shell
$ gst-launch-1.0 videotestsrc ! agingtv ! webrtcsink meta="meta,name=native-stream"
```

By default *webrtcsink* element uses *ws://127.0.0.1:8443* for the signalling server address, so there is no need
for more arguments. If you're hosting the signalling server elsewhere, you can specify its address by adding
`signaller::uri="ws[s]://[signalling server]"` to the list of *webrtcsink* properties.

Once the GStreamer pipeline launched, you will see the registration of a new producer in the logs of the signalling
server and a new remote stream, with the name *native-stream*, will appear on the webpage.

You just need to click on the corresponding entry to connect as a consumer to the remote native stream.

### Produce a GStreamer interactive WebRTC stream with remote control

Launch the following GStreamer pipeline:
```shell
$ gst-launch-1.0 wpesrc location=https://gstreamer.freedesktop.org/documentation ! queue ! webrtcsink enable-data-channel-navigation=true meta="meta,name=web-stream"
```

Once the GStreamer pipeline launched, you will see a new producer with the name *web-stream*. When connecting to this
producer you will see the remote rendering of the web page. You can interact remotely with this web page, controls are
sent through a special WebRTC data channel while the rendering is done remotely by the
[wpesrc](https://gstreamer.freedesktop.org/documentation/wpe/wpesrc.html) element.