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.
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
4 (1 from each other client)
4 (1 to each other client)
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.
The Carbonio VideoServer must be installed on a dedicated server and has the following requirements:
Minimum 4 CPU cores, suggested at least 8 to handle more than 100 users at the same time
1024mb of ram + 1mb of ram for each connected user
The Carbonio VideoServer mainly scales on the CPU, so more CPU cores and power means more connected users.
A public IP address. This is either the IP address of Carbonio VideoServer, if it is directly accessible from remote clients on the Internet, or—if there is a NAT-ting device in front of it (e.g., a firewall or router)–the IP address with which the Carbonio VideoServer is reachable.
A publicly resolvable FQDN
With the default settings, 200kb/s (0.2 mb/s) bandwidth for each connected user
The mailbox server will establish a WebSocket on port 8188 (TCP) to communicate with the Carbonio VideoServer
Clients will use a random UDP port between 20000 and 40000
The Carbonio VideoServer installer requires the fully qualified hostname
to be correctly configured in
/etc/hostname. Failing to comply will likely cause the
sample commands provided at the end of the installation to be
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 zextras_team_full_cli. The commands to control the service are straightforward:
Start the connection pool:
# carbonio chats doStartService team-videoserver-pool.
Shutdown the connection pool:
# carbonio chats doStopService team-videoserver-pool
Check a connection pool status. This command reports information about the node on which it is executed.
# carbonio chats clusterstatus isFullySynced true servers meeting_servers <ip_videoserver>:8188 id 123 hostname <ip_videoserver>:8188 status online 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.
last failureshows 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_hostedreports 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
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).
When using multiple video servers, meetings are instanced on any of the available instances.
The CLI command to manage Carbonio VideoServer installations is :command`carbonio team` with the sub-command
video-serverand the parameters add and remove.
# carbonio chats video-server add *videoserver.example.com* [param VALUE[,VALUE]] # carbonio chats video-server remove *videoserver.example.com* [param VALUE[,VALUE]]
Bandwidth and Codecs
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
By default both the webcam bandwidth and the screen sharing bandwidth are set to 200 Kbps.
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
E.g. to enable the H264 codec run:
carbonio config global set attribute teamChatVideoCodecVP8 value false
carbonio config global set attribute teamChatVideoCodecH264 value true
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.
The following settings influence the audio experience.
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
The administrator can optimize the audio sensitivity with these two commands:
carbonio config global set attribute teamChatAudioLevelSensitivity value 25
carbonio config global set attribute teamChatAudioSamplingSensitivityInterval value 2
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 25.
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.
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.
This functionality is provided by a specific package, called
carbonio-videoserver-recorder, that must be installed together
carbonio-videoserver. On a Multi-Server, this means that the
package must be installed on each node on which
carbonio-videoserver is installed.
All the instructions below must be executed on every node on
carbonio-videoserver is installed, unless differently
# apt install carbonio-videoserver-recorder
# 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, 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:
# 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 port that will be used only for
recording. The value of the servlet port must match the one
defined in file
Carbonio VideoServer not yet installed
If you did not yet install Carbonio VideoServer, you can execute the following command, which configures at the same time both the Carbonio VideoServer and the recording servlet.
# 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 a robust password.
To complete the setup, execute the command
# carbonio config set global teamVideoServerRecordingEnabled true