Carbonio VideoServer

The Carbonio VideoServer is a WebRTC stream aggregator that improves Carbonio Chats‘s performance by merging and decoding/re-encoding all streams in a Meeting.

While the default WebRTC creates one incoming and one outgoing stream per meeting participant, with the Carbonio VideoServer, each client will only have one aggregated inbound stream and one aggregated outbound stream. This applies for both video and audio.

Example

In our simple scenario, 5 people are participating in a meeting.

• Without Carbonio VideoServer: each client generates 4x outgoing video/audio streams and receives 4 incoming video/audio streams

• With Carbonio VideoServer: each client generates 1 outgoing video/audio stream and receives 1 incoming video/audio stream

In summary:

Carbonio VideoServer	Incoming Connections	Outgoing Connections
No	4 (1 from each other client)	4 (1 to each other client)
Yes	1	1

By default, the Carbonio VideoServer uses conservative Codecs (VP8 and Opus) to ensure the broadest compatibility, but more codecs can be enabled. It also splits the Webcam and Screen Sharing streams and reserves the same bandwidth for both.

A properly set up Carbonio VideoServer will supersede the need of a TURN server, provided that all clients can reach the Carbonio VideoServer’s public IP and that UDP traffic is not filtered.

Carbonio VideoServer Installation

The installation process of Carbonio VideoServer has been moved as part of the main installation, please refer to the corresponding Step.

Architecture and Service Control

A Carbonio Chats meeting is hosted on one mailbox, which also keeps the state of the meeting. It is a responsibility of that mailbox to communicate with a videoserver instance to start a meeting and controlling it.

Therefore, each mailbox has its own connection pool, which can be controlled via the Carbonio CLI. The commands to control the service are straightforward:

• Start the connection pool

  zextras$ carbonio chats doStartService chats-video-server-connection-pool
  

• Shutdown the connection pool

  zextras$ carbonio chats doStopService chats-video-server-connection-pool
  

• Check a connection pool status. This command reports information about the node on which it is executed.

  zextras$ carbonio chats clusterstatus
  
       isFullySynced                                       true
       servers
        <ip_server>
            online                                          true
            min_api_version                                 1
            max_api_version                                 22
       meeting_servers
           <ip_videoserver>:8188
               id                                           123
               hostname                                     <ip_videoserver>:8188
               status                                       online
               servlet_port                                 8090
               last_failure
               local_meetings_hosted                        2
  

  The output of this command contains this information:

  • Should the remote Carbonio VideoServer be offline or unreachable, the status will be offline instead of online.

  • The API versions supported by the server (min_api_version and min_api_version)

  • last failure shows an error message (e.g., Unauthorized request (wrong or missing secret/token) or a generic Runtime Exception) if the last connection attempt to the videoserver was unsuccessful. The message is cleared when the connection is successful.

  • local_meetings_hosted reports the number of meetings hosted on the current mailbox.

Carbonio VideoServer Scaling

Multiple Carbonio VideoServer can be run on the same infrastructure.

To add a new Carbonio VideoServer to the configuration, run the Carbonio VideoServer installer on a new server and follow the instructions - the installer will provide the required commands (carbonio chats video-server add with the appropriate parameters) needed to add the server to the infrastructure once packages are installed.

To remove a Carbonio VideoServer from the configuration, use the carbonio chats video-server remove command from any mailbox server - this will remove the appropriate entries from the Zextras Config (manual package removal on the video server is required).

Warning

When using multiple video servers, meetings are instanced on any of the available instances.

CLI Commands

The CLI command to manage Carbonio VideoServer installations is :command`carbonio team` with the sub-command video-server and the parameters add and remove.

Quick reference:

zextras$ carbonio chats video-server add *videoserver.example.com* [param VALUE[,VALUE]]

zextras$ carbonio chats video-server remove *videoserver.example.com* [param VALUE[,VALUE]]

Bandwidth and Codecs

Video Bandwidth

The administrator can set the webcam stream quality and the screenshare stream quality specifing the relative bitrate in Kbps. The values must be at least 100 Kbps and can be increased as desired.

Higher values mean more quality but more used bandwidth.

• carbonio config global set attribute teamChatWebcamBitrateCap value 200: is the command for the webcam stream quality/bandwidth

• carbonio config global set attribute teamChatScreenBitrateCap value 200: is the command for the screenshare stream qualitybandwidth

Tip

By default both the webcam bandwidth and the screen sharing bandwidth are set to 200 Kbps.

Video Codecs

By default, the VP8 video codec is used. This is to ensure the best compatibility, as this codec is available in all supported browsers, but other codecs can be enabled:

• AV1: carbonio config global set attribute teamChatVideoCodecAV1 value true

• H264: carbonio config global set attribute teamChatVideoCodecH264 value true

• H265: carbonio config global set attribute teamChatVideoCodecH265 value true

• VP8: carbonio config global set attribute teamChatVideoCodecVP8 value true

• VP9: carbonio config global set attribute teamChatVideoCodecVP9 value true

Only one codec can be enabled at the time, so before enabling a new codec remember to disable the previous one using the same command as the one in the list above but substituting value true with value false.

E.g. to enable the H264 codec run:

carbonio config global set attribute teamChatVideoCodecVP8 value false

carbonio config global set attribute teamChatVideoCodecH264 value true

Audio Codec

The audio codec used by the Carbonio VideoServer is Opus. No other codecs are supported, as Opus is currently the only reliable one available across all supported browsers.

See also

Wikipedia page on Opus

Advanced Settings

The following settings influence the audio experience.

Audio Quality

The administrator can set the Opus audio quality by setting the sampling rate (in Hz) in the teamChatAudioSamplingRate global attribute.

The available values are:

• 8000 → represents the narrowband bandwidth

• 12000 → represents the mediumband bandwidth

• 16000 → represents the wideband bandwidth (default)

• 24000 → represents the superwideband bandwidth

• 48000 → represents the fullband bandwidth

Audio Sensitivity

The administrator can optimize the audio sensitivity with these two commands:

zextras$ carbonio config global set attribute teamChatAudioLevelSensitivity value 55

zextras$ carbonio config global set attribute teamChatAudioSamplingSensitivityInterval value 10

The audio level sensitivity defines how much the audio should be normalized between all the audio sources. The value has a range between 0 and 100 where 0 represents the audio muted and 100 the maximum audio level (too loud).

By default the value is set to 55, which is also the value suggested for optimal performances

The audio sampling sensitivity interval defines the interval in seconds used to compute the audio sensitivity level. By default the value is set to 2 seconds, this means that the video server normalizes the audio level considering the audio sources of the last 2 seconds.

The value should be at least 0, but it should be set to 10 seconds to provide the best performances.

Recording a Video Meeting

The owner or moderator of a room can record any meeting and make it available for people to watch it later. A meeting can be recorded only once, meaning that an ongoing recording will be unique for that meeting. In case a recording is interrupted, it can be restarted at a later point. Every user will be notified of the ongoing recording, while any moderator in the room can stop it, even if it was started by another moderator, and save it to a file or to the moderator’s Carbonio Files.

Note

Regardless if the recording is terminated by the person who started it or not, a copy of the recording will always be saved in the Carbonio Files account of who started the recording.

This functionality is provided by a specific package, called carbonio-videoserver-recorder, that must be installed together with carbonio-videoserver. On a Multi-Server, this means that the package must be installed on each node on which carbonio-videoserver is installed.

Note

All the instructions below must be executed on every node on which carbonio-videoserver is installed, unless differently specified.

Ubuntu

# apt install carbonio-videoserver-recorder

RHEL

# yum install carbonio-videoserver-recorder

The package installs a service that needs to be associated with the Carbonio VideoServer instance, a task that needs to be executed from the CLI on a Node which installs the carbonio-advanced package (which is SRV3 in our Scenario), using a command that differ depending if you already installed and configured the Carbonio VideoServer or not.

Carbonio VideoServer already installed

If you already installed Carbonio VideoServer, execute this command on SRV3:

zextras$ carbonio chats video-server update-servlet example.com:8188 8090

Here, replace example.com with the domain name or IP on which the Carbonio VideoServer is installed, 8188 the Carbonio VideoServer port, and 8090 (which is the default value) with the servlet port that will be used only for recording.

Warning

The value of the servlet port (8090) must match the one defined in file /etc/carbonio/videoserver-recorder/recordingEnv on SRV5.

Carbonio VideoServer not yet installed

If you did not yet install Carbonio VideoServer, you can execute the following command on SRV3, which configures at the same time both the Carbonio VideoServer and the recording servlet.

zextras$ carbonio chats video-server add example.com port 8188 servlet_port 8090 secret A_SECRET_PASSWORD

Replace example.com with the actual domain name or IP, 8188 and 8090 with the ports associated with the Carbonio VideoServer and the recorder, respectively, and A_SECRET_PASSWORD with the value of the variable api_secret in file /etc/janus/janus.jcfg on SRV5, for example:

api_secret = "+xpghXktjPGGRIs7Y7ryoeBvW9ReS8RQ"

In both cases

In both cases, edit the file /etc/janus/janus.jcfg, find the variable nat_1_1_mapping and write the public IP address of Carbonio as the value for that variable, for example: nat_1_1_mapping = "93.184.216.34".

Configure Carbonio VideoServer Recording

To complete the setup, you need to execute a few commands as the zextras user on SRV3. First, make sure that the functionality is enabled on the infrastructure at COS level.

zextras$ carbonio config set cos attribute teamChatEnabled value true

You need then to enable the actual recording on the rooms.

zextras$ carbonio config set global teamVideoServerRecordingEnabled true

Finally, allow all users to start a recording.

zextras$ carbonio config set global teamMeetingRecordingEnabled true

Note

In this command, the policy allows every user to record a meeting. It is however possible to enforce this policy at user or COS level, to allow only selected users or members of a COS to record meetings.

Modify or Move a Carbonio VideoServer Installation

To reconfigure an existing Carbonio VideoServer instance, simply use the various commands previously mentioned in this Section, then restart the Carbonio VideoServer service.

If you prefer to move the Carbonio VideoServer to a different Node, or need to do so because for example the current Node must be decommissioned, you first need to remove the Carbonio VideoServer instance: as the zextras user run

zextras$ carbonio chats videoserver remove video.example.com

Here, video.example.com is the name of the Carbonio VideoServer instance, that you can retrieve as the hostname in the output of

zextras$ carbonio chats clusterstatus

Once done, remove the package

Ubuntu

# apt remove service-discover-agent carbonio-videoserver

RHEL

# dnf remove service-discover-agent carbonio-videoserver

Now the Carbonio VideoServer is completely removed from the node and you can install it on a different Node, using the installation procedure.