Document V4L2 output.

[nageru-docs] / v4l2.rst

diff --git a/v4l2.rst b/v4l2.rst
new file mode 100644 (file)
index 0000000..8adde62
--- /dev/null
+++ b/v4l2.rst
@@ -0,0 +1,43 @@
+V4L2 output
+===========
+
+Since Nageru 1.9.3, Nageru has had (in addition to the regular
+:doc:`hdmisdi`) support for output to Linux' Video4Linux API
+(also known as V4L2, or just V4L). This is intended for one
+specific purpose, namely using Nageru as a camera/mixer for
+input to a video conference, such at Jitsi, Google Meet or
+similar—it may not be all that suitable for an actual
+output, since it does not carry audio (and does not synchronize
+to any V4L clock).
+
+To use it as an input, you will first need to install
+`v4l2loopback <https://github.com/umlaeute/v4l2loopback>`_,
+which turns V4L outputs into V4L inputs. If you are on
+Debian or Ubuntu, the following should suffice to install::
+
+  sudo apt install v4l2loopback-dkms
+
+You will also need to load and configure the module,
+using a command line such as::
+
+  sudo modprobe v4l2loopback video_nr=2 card_label='Nageru loopback' max_width=1280 max_height=720 exclusive_caps=1
+
+The *exclusive_caps=1* parameter is so that once you start
+outputting, the virtual card will appear only as an input
+card to other V4L clients; in particular, Google Chrome
+needs this, or the card will not show up. However, this means
+that you will need to start Nageru output *before* trying to
+use it in the browser.
+
+Finally, you can start Nageru as usual with the *--v4l-output*
+flag, outputting to the device you just created::
+
+  nageru --v4l-output /dev/video2
+
+Nageru should then show up as a device in your browser
+or videoconferencing client.
+
+V4L output is in addition to any other output you may have
+(whether stream output, :doc:`hdmisdi`, or both), and can
+only be configured from the command line. It does not control
+the master clock, is always 4:2:0; and does not include audio.