diff --git a/README.md b/README.md index f608b09..7529899 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,9 @@ $ modprobe bcm2835-v4l2 max_video_width=2592 max_video_height=1944 ----- # Integrations +## Janus +µStreamer supports bandwidth-efficient streaming using [H.264 compression](https://en.wikipedia.org/wiki/Advanced_Video_Coding) and the Janus WebRTC server. See the [Janus integration guide](docs/h264.md) for full details. + ## Nginx When uStreamer is behind an Nginx proxy, it's buffering behavior introduces latency into the video stream. It's possible to disable Nginx's buffering to eliminate the additional latency: diff --git a/docs/h264.md b/docs/h264.md new file mode 100644 index 0000000..ed95f64 --- /dev/null +++ b/docs/h264.md @@ -0,0 +1,231 @@ +# Streaming H.264 Video over WebRTC with Janus + +µStreamer supports bandwidth-efficient streaming using [H.264 compression](https://en.wikipedia.org/wiki/Advanced_Video_Coding) and the Janus WebRTC server. + +This guide explains how to configure µStreamer to provide an H.264 video stream and consume it within a web application using WebRTC. + +## Components + +In addition to µStreamer, H.264 streaming involves the following components: + +- [**Janus**](https://janus.conf.meetecho.com/): A general-purpose WebRTC server. +- [**µStreamer Janus Plugin**](https://github.com/pikvm/ustreamer/tree/master/janus): A Janus plugin that allows Janus to consume a video stream from µStreamer via shared memory. +- [**Janus JavaScript Client**](https://janus.conf.meetecho.com/docs/JS.html): A frontend library that communicates with the Janus server and the µStreamer Janus plugin. + +## Control Flow + +To connect to a µStreamer video stream over WebRTC, an application must establish the following control flow: + +1. The backend server starts the µStreamer service. +1. The backend server starts the Janus WebRTC server with the µStreamer Janus plugin. +1. The client-side JavaScript application establishes a connection to the Janus server. +1. The client-side JavaScript application instructs the Janus server to attach the µStreamer Janus plugin and start the video stream. +1. The client-side JavaScript application renders the video stream in the web browser. + +## Server Setup + +### Prerequisites + +To integrate with Janus, µStreamer has the following prerequisites: + +- The system packages that µStreamer depends on (see the [main build instructions](../README.md#building)). +- The Janus WebRTC server with WebSockets transport enabled (see the [Janus documentation](https://github.com/meetecho/janus-gateway)). + +### Fixing Janus C Headers + +To compile µStreamer with the Janus option, (see [“Installation”](#installation)), you need to make the Janus header files available within µStreamer's build context. + +First, create a symbolic link from `/usr/include` to the Janus install directory. By default, Janus installs to `/opt/janus`. + +```sh +ln -s /opt/janus/include/janus /usr/include/janus +``` + +Janus uses `#include` paths that make it difficult for third-party libraries to build against its headers. To fix this, modify the `#include` directive in `janus/plugins/plugin.h` to prepend a `../` to the included file name (`#include "refcount.h"` → `#include "../refcount.h"`). + +```sh +sed \ + --in-place \ + --expression 's|^#include "refcount.h"$|#include "../refcount.h"|g' \ + /usr/include/janus/plugins/plugin.h +``` + +### Installation + +First, compile µStreamer with the Janus plugin option (`WITH_JANUS`). + +```sh +git clone --depth=1 https://github.com/pikvm/ustreamer +cd ustreamer +make WITH_JANUS=1 +``` + +The `WITH_JANUS` option compiles the µStreamer Janus plugin and outputs it to `janus/libjanus_ustreamer.so`. Move this file to the plugin directory of your Janus installation. + +```sh +mv \ + janus/libjanus_ustreamer.so \ + /opt/janus/lib/janus/plugins/libjanus_ustreamer.so +``` + +Finally, specify a qualifier for the shared memory object so that the µStreamer Janus plugin can read µStreamer's video data. + +```sh +cat > /opt/janus/lib/janus/configs/janus.plugin.ustreamer.jcfg <` element, rendering the video stream in the browser window. + +### Sample Code + +```html + + + + + µStreamer H.264 demo + + + + + + + + + + +```