-
Notifications
You must be signed in to change notification settings - Fork 59
Videoconferencing Mode
UltraGrid allows for multipoint video and audio distribution in a videoconferencing mode. In such a case UltraGrid acts as a mixer. Audio and video mixers are separate in UltraGrid.
For the video UltraGrid scales and composes the incoming video streams in a specified layout and sends the resulting video stream to given hosts or IPs. It is possible to specify different video compressions and stream parameters for individual target hosts in the same way as with the reflector (see Reflector settings for reference).
Audio is mixed using linear (or logarithmic) audio mixer and the audio is sent back to all source hosts. For each host its own source audio is omitted from the resulting audio mix.
See also Multipoint Setup if you want to omit mixing and run the multipoint directly. This is usually only suitable for few parties (3-4) otherwise it is rather complex to setup provided that it should be a full mesh setup.
Note: Videoconference must be compiled-in. If not, check Compile UltraGrid (Source)#Conference. You can verify presence of the module with following command:
uv -d help | grep conference
To start the video mixer run:
hd-rum-transcode --conference <width>:<height>:<fps> 8M 5004 <host1_opts> <host1> \
<host2_opts> <host2> ... <hostn_opts> <hostn>
Sample usage is:
hd-rum-transcode -conference 1920:1080:30 8M 5004 -c libavcodec:codec=H.264:bitrate=10M receiver1 \
receiver2 -c JPEG receiver3
Notes:
-
If you want to run the mixer on a machine that is part of the conference, change RX video any unused port, eg. 5008:
nodeX$ uv -d gl -t <vcapture> -P 5008:5004for the UltraGrid instance that is part of the conference (not the mixer) and use that port with the mixer for this particular host:
nodeX$ hd-rum-transcode -conference 1920:1080:30 8M 5004 -c libavcodec:codec=H.264:bitrate=10M nodeY \ -P 5008 localhost
The control port can be used in videoconferencing mode to change layout or to get information about participants. To change layout use:
display.data layout=<layout>
where layout can be tiled - participants are laid out evenly in a grid, or one_big - one selected participant takes 2/3 of available space. The primary participant for the one_big layout can be set like this:
display.data primary_ssrc=<ssrc>
To get info about selected layout and connected participants including their ssrc's call:
display.data info
To start the audio mixer run:
uv -r mixer:algo=linear
The general usage of the audio mixer is as follows:
uv -r mixer[:codec=<codec>][:algo={linear|logarithmic}]
<codec>
audio codec to use
linear
linear sum of signals (with clamping)
logarithmic
linear sum of signals to threshold, above threshold logarithmic dynamic range compression is used
Notes:
-
You do not need to specify audio participants explicitly, UltraGrid simply sends the the stream back to the host that is sending to mixer. Therefore it is necessary to use single UltraGrid instance for both sending and receiving audio.
-
Mixer uses default port for receiving, therefore if you want to use it on machine that is a part of the conference, you must change the default audio RX port, eg. to 5010:
uv -s <acapture> -r <aplayback> -P 5004:5004:5010:5006for the UltraGrid instance that is part of the conference (not the mixer!).
-
you can use
--param low-latency-audioto improve the latency (but double check if the audio is stable in this case)
Passive participants can join the conference by using passive pseudo-capture, eg.:
$ uv -s passive -r portaudio <mixer>
The mixer can be restricted to a single sender by the message over control
socket to audio.receiver.data. Assuming that the mixer was run with
--control-port 8888:
# restrict to stream from 10.0.1.111:54181
mixer$ echo 'audio.receiver.data restrict 10.0.1.111:54181' | nc localhost 8888
# if the command on 10.0.1.111 is run with: -P 5004:5004:6000:5006
mixer$ echo 'audio.receiver.data restrict 10.0.1.111:6000' | nc localhost 8888
# IPv6, including link-local addresses are supported as well, eg.:
mixer$ echo 'audio.receiver.data restrict [100::1234:5678]:6000' | nc localhost 8888
mixer$ echo 'audio.receiver.data restrict [fe80::111%p7p1.54]:55754' | nc localhost 8888
# to return back to normal operation (mixing all /active/ participants, issue):
mixer$ echo 'audio.receiver.data restrict flush' | busybox nc localhost 8888
# "help" is understood as well (prints to UltraGrid terminal):
mixer$ echo 'audio.receiver.data help' | busybox nc localhost 8888
Currently it is possible to restrict to just one sender (or mix all together normally).
In this use case will be presented case with 3 parties A, B and C. Mixers will be running on A - without that it will be easier because you won't need to fiddle with ports:
A$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS -P 5008:5004:5010:5006 localhost
A$ uv -r mixer:codec=OPUS
A$ hd-rum-transcode -conference 1920:1080:30 8M 5004 -c libavcodec:codec=H.264:bitrate=10M B C -P 5008 localhost
B$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS A
C$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS A
If there is a separate host M that mixes the streams, commands will be:
A$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS M
B$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS M
C$ uv -t testcard -s testcard -d gl -r alsa -c libavcodec --audio-codec OPUS M
M$ uv -r mixer:codec=OPUS
M$ hd-rum-transcode -conference 1920:1080:30 8M 5004 -c libavcodec:codec=H.264:bitrate=10M A B C
A reflector hd-rum-av is able to handle both audio and video, in case of the videoconferencing mode it means that it starts both video and audio mixer at the same time. The usage is simple:
hd-rum-av -r 1920:1080 8M 5004
(parameters identical as those for video mixer)
If you have any technical or non-technical question or suggestion please feel free to contact us at