Overview

As you develop applications that leverage Vidyo.io, you may want to include a feature for recording and distributing recordings for private or public viewing. You may also want to include SIP-enabled participants in your calls. By integrating the Media Bridge Docker image with your Vidyo application, you can record and distribute or live-stream multiple Vidyo conferences across your organization's network simultaneously. You can also incorporate SIP-enabled video conferencing systems into your recordings and live streams.

What's Docker?

Docker is a robust software container platform you install on a dedicated server and use to run the Media Bridge image. The Media Bridge image provides record/playback functionality you might want to integrate with your Vidyo.io-based application. Docker provides the thorough resources and documentation you need to integrate basic or extensive Media Bridge features. See the Docker Overview here.

What's Media Bridge?

Media Bridge is a downloadable Docker image that provides the following:

  • Recorder for the archiving of Vidyo.io-based video conferences
  • Streamer for the distribution of Vidyo.io-based video conferences
  • Gateway for SIP-enabled systems

From Docker, you pull the Media Bridge image, create a config file, create a container, drop in your config file, then start recording.

Before You Begin

Before you begin, ensure that your Linux server is configured with a running Docker Engine.

What you will need

Server platforms other than Ubuntu Linux 14.04+ have not been tested; they might not run smoothly or predictably in your deployment.

Set-up

To set up your server with Media Bridge for managing video conference recordings, follow these steps:

        1. Install the Media Bridge docker image:
          docker pull vidyo/mediabridge
        2. Create a recording configuration file (see Recording Configuration File).
        3. Create a container from the Media Bridge image:
          docker run -d --name my_mediabridge vidyo/mediabridge
        4. Copy your config file to the container:
          docker cp config my_mediabridge:/opt/vidyo

To record or live-stream multiple Vidyo conferences simultaneously, you need to create and deploy a separate Docker container for each recording and live stream.

Start a Recording

To start the container, enter:

docker exec -d my_mediabridge /opt/vidyo/connect

Monitor a Recording

You can check whether an ongoing recording is still in progress by checking its process ID. To do so, enter the following command:

docker exec -it my_mediabridge pgrep -x call
If a recording is active, the command returns the process ID; otherwise, it returns nothing.

You can also check all available statistics of an ongoing recording. To do so, enter the following command:

docker exec my_mediabridge /opt/vidyo/getCallStatus.sh

Sample response:

{
  "status": {
    "call": {
      "legs": [
        {
          "participantsMedia": [
            {
              "appPktLossPercent": 0,
              "videoDecoderKbps": 831,
              "videoDecodeFps": 32,
              "id": 1,
              "audioReceiveKbps": 18,
              "videoPktLossPercent": 0,
              "audioPktLossPercent": 0,
              "appDecoderKbps": 0,
              "appDecodeFps": 0
            },
            {
              "appPktLossPercent": 0,
              "appDecoderKbps": 0,
              "audioPktLossPercent": 0,
              "videoDecodeFps": 32,
              "videoDecoderKbps": 831,
              "appEncodeFps": 0,
              "videoEncodeIframes": 0,
              "videoEncodeKbps": 0,
              "audioSendKbps": 0,
              "videoPktLossPercent": 0,
              "audioReceiveKbps": 18,
              "appEncodeIframes": 0,
              "videoEncodeFps": 0,
              "appEncodeKbps": 0,
              "appDecodeFps": 0
            }
          ],
          "numParticipants": 2,
          "remoteDisplayName": "Recorder / Streamer",
          "protocol": "xmpp",
          "remoteUri": "room:room~token:cHJvdmlzaW9uAGdhdGV3YXlVc2VyODRAZGVmYXVsdC5kZWZhdWx0LmNvbQA2NDg3NTQ2NjQ2MgA8dkNhcmQgeG1sbnM9J3ZjYXJkLXRlbXAnPjxGTj5HYXRld2F5IFRlc3QgVXNlcjg0PC9GTj48TklDS05BTUU+Z2F0ZXdheVVzZXI4NDwvTklDS05BTUU+PC92Q2FyZD4AY2ExNzdkZTEzYTA2MWM3ZGZjOTljZWQ4ZWFiYWI2ZjkyNjVhODMwODhlMzRhYjNhOWZlZWY3NmFkZDg0Njc1YjhiMWMzOGU5ODU3MTUzYzE1NDNiZmY0NzkyOWY1YWQ1~server:nj1-qa-trinity01.vidyoqa.com"
        },
        {
          "numParticipants": 1,
          "participantsMedia": [
            {
              "videoEncodeIframes": 1,
              "videoEncodeFps": 29,
              "videoEncoder": "VP8",
              "videoEncodeKbps": 2112,
              "audioSendKbps": 0,
              "videoEncodeResolution": "1280x720",
              "destination": "mkv:./recording.mkv",
              "audioEncoder": "OPUS"
            }
          ],
          "remoteDisplayName": "Recorder",
          "protocol": "rtmp",
          "remoteUri": "N/A"
        }
      ],
      "meminfo": {
        "spaceinuse": 68857504,
        "keepcost": 40128,
        "fordblks": 4833632,
        "arena": 26320896,
        "ordblks": 454,
        "smblks": 328,
        "hblks": 27,
        "hblkhd": 47370240,
        "usmblks": 0,
        "fsmblks": 16080,
        "uordblks": 21487264
      }
    }
  },
  "response": "call_status"
}

Stop a Recording

The recording stops automatically when the last participant leaves the room. When you are done, run: docker stop and docker rm to release the resources used by the container.

To force the recording to stop with a SIGINT call, enter:

docker exec my_mediabridge pkill -x --signal INT call

Retrieve a Recording

By default, the recording is saved to a file named recording.flv at this path:
/opt/vidyo folder

To retrieve the recording, enter:

docker cp my_mediabridge:/opt/vidyo/recording.flv $HOME

To override this, use the destination option described in the Recording Configuration File Options table below.

Include SIP-enabled systems

To make a SIP outbound call, set the destination key in the config file to the full SIP URI:

destination=sip:mary@5.6.7.8

To receive an incoming SIP call, leave the destination key empty:

destination=     

To start the Docker container for SIP calls, use the -p parameter to map host ports to the container for both media and signaling. For example, if the mediaPorts key in the config file is set to 50000-50100, the Docker command is:

docker run -d --name sipCall -p 50000-50100:50000-50100/udp -p 5060:5060/udp vidyo/mediabridge
You must map SIP signaling UDP port 5060 from the host to the container.

Convert FLV Files to MP4 Format

You can use FFMPEG to convert an FLV file to MP4. The FFMPEG conversion command is ffmpeg -i <flv file name> -c:v copy -c:a aac -strinct -2 <mp4 file name>. You can download FFMPEG at: https://ffmpeg.org/https://ffmpeg.org/

Install a Customer Certificate Authority

To install a customer certificate authority, the Certificate Authority (CA) file has to be copied to the /opt/vidyo folder in the Docker container. The file name must be ca-certificates.crt. For example, assuming the CA file is named ca.crt and the container is named recorder, issue the command docker cp ca.crt recorder:/opt/vidyo/ca-certificates.crt. Do this before starting any recording using Customer Certificate Authority.

When a recorder first establishes a connection, it verifies the server's certificate. If the certificate fails verification, the recorder's log contains the following error message:
call [47]: XmppGateway ERROR gwXmpp xmpp.c:723 LoginCompleted failed result 2

Troubleshooting

If you encounter a problem, retrieve the log file gw.log from the container at this path and use it to troubleshoot:
/var/log

To enable full logging, add log=full|debug|info,|warn|error|none. The default is debug.

Resource Requirements

To ensure Media Bridge has sufficient resources for smooth HD streaming and playback, use the following CPU and memory reservation guidelines for each deployed Media Bridge container. If you are running multiple recordings or live streams, ensure you have reserved sufficient resources as outlined here for each deployed container.

Resolution (fps) CPU [GHz] RAM [GB]
HD @ 720p (30) 2.2 2
HD @ 1080p (30) 4.0 4

Recording Configuration File

The recording configuration file is a plain text file with key-value pairs. Name this file config and place it at this path:
/opt/vidyo

Each key-value pair must be on a separate line.

The key is separated from the value with an equal (=) sign only; do not use spaces in key-value pairs.

Use a # before comments; text appearing on a line after a # is ignored at runtime.

The following table describes the options available for the recording configuration file.

Recording Configuration File Options
Option Description
width The width of the video stream.
height The height of the video stream.
fps The frame rate of the video stream in frames per second.
kbps The bandwidth of the recording in kilo-bits per second.
layout Set to 1 for a basic layout, set to 2 for a presenter layout, where the current speaker occupies a larger tile than the rest, set to 3 for a film strip layout, where the current speaker occupies most of the screen and other participants appear in a film strip at the bottom.
maxParticipants The maximum number of participants to be rendered in the video stream.  Minimum is 1, maximum is 8.
overlay When set to 1, Media Bridge displays each participant's name as an overlay in the video stream.
videoCodec

You can set the video codec to the following lossy compression standards: H264H263VP8VP9. The default setting is H264.

Note: FLV format only supports H264 and H263 video codecs. Recordings configured for unsupported codecs fail to start.

audioCodec

You can set the audio codec to the following lossy compression standards: AAC (32K kHZ), PCM (11.025K kHZ), OPUS (48K kHZ), SILK8 (8K kHz), SILK16 (16K kHz), SPEEX (32K kHz). The default setting is AAC.

Note: FLV format only supports AAC and PCM audio codecs. Recordings configured for unsupported codecs fail to start.

presentationAllowed When set to 0, Media Bridge ignores presentations during the conference. When set to 1, Media Bridge records presentations instead of the main video streams.
presWidth The maximum width of the presentation stream.
presHeight The maximum height of the presentation stream.
presFps The frame rate of the presentation stream in frames per second.
presKbps The bandwidth used for the presentation stream in kilo-bits per second.
destination

This can be a file name, a folder name, or an RTMP URI. When you set this field to a folder name, Media Bridge randomly generates the file name. This directs the recording to a central storage location you mount inside the docker container (use the -v option). Media Bridge supports FLV and MKV video file formats with the following syntax: flv:/filename.flv or mkv:/filename.mkv. When you set this field to an RTMP URI such as rtmp://a.rtmp.youtube.com/live2/my_stream_name, Media Bridge streams the recording to that destination. No permanent record is stored.

resourceId The vidyo.io resource to connect to and record.
token The access token to the vidyo.io system.
host The vidyo.io host name to connect to. Make sure that this host name can be resolved inside your container. This can be done using the --add-host parameter when creating the container.
mediaPorts The ports used to send and receive media from the SIP endpoint (e.g. mediaPorts=50000-50100). When you start the Docker container, map these ports to the same port numbers on the host via the -p parameter.
publicIp The IP address of the host. It must be reachable by the SIP endpoint participating in the call (e.g. publicIp=1.2.3.4).

Sample configuration file for a recording targeted to a folder

#main video/audio settings
width=1280
height=720
fps=30
kbps=2000
layout=1
maxParticipants=8
overlay=1
videoCodec=H264
audioCodec=AAC

#Presentation settings
presentationAllowed=1 #0 - ignore presentations 1 - replace main video with presentation
presWidth=1280
presHeight=720
presFps=5
presKbps=300
destination="flv:/opt/vidyo/recording.flv"

#vidyo.io connection info
resourceId="my_room"
token="cHJvdmlzaW9uAHVzZXIwQGRlZmF1bHQuZGVmYXVsdC5jb20ANjQ4NzU0NjY0NjIAPHZDYXJkIHhtbG5zPSd2Y2FyZC10ZW1wJz48Rk4+RnVsbCBVc2VybmFtZTA8L0ZOPjxOSUNLTkFNRT51c2VyMDwvTklDS05BTUU+PC92Q2FyZD4AOWRiN2QxN2ZjMTNiOTc2ZTIxZjcwMjY4NmNjNzdkMzEwOTM2ODBkOTk3ZWJhN2Y2OTQ1ZmEwNTA5Njc4MWZlOTU1YTlmM2M4ODExNGQ5YzIwMjFhNjhlNmJlOGMwMmY1"
host="prod.vidyo.io"

#SIP gateway info mediaPorts="min_port_number-max_port_number" publicIp="host_ip_address"

Sample configuration file for a live stream targeted to an RTMP server

#main video/audio settings
width=1280
height=720
fps=30
kbps=2000
layout=1
maxParticipants=8
overlay=1
videoCodec=H264
audioCodec=AAC

#Presentation settings
presentationAllowed=1 #0 - ignore presentations 1 - replace main video with presentation
presWidth=1280
presHeight=720
presFps=5
presKbps=300
destination="rtmp://a.rtmp.youtube.com/live2/my_stream_name

#vidyo.io connection info
resourceId="my_room"
token="cHJvdmlzaW9uAHVzZXIwQGRlZmF1bHQuZGVmYXVsdC5jb20ANjQ4NzU0NjY0NjIAPHZDYXJkIHhtbG5zPSd2Y2FyZC10ZW1wJz48Rk4+RnVsbCBVc2VybmFtZTA8L0ZOPjxOSUNLTkFNRT51c2VyMDwvTklDS05BTUU+PC92Q2FyZD4AOWRiN2QxN2ZjMTNiOTc2ZTIxZjcwMjY4NmNjNzdkMzEwOTM2ODBkOTk3ZWJhN2Y2OTQ1ZmEwNTA5Njc4MWZlOTU1YTlmM2M4ODExNGQ5YzIwMjFhNjhlNmJlOGMwMmY1"
host="prod.vidyo.io"

#SIP gateway info mediaPorts="min_port_number-max_port_number" publicIp="host_ip_address"
Was this article helpful?
1 out of 1 found this helpful

0 Comments

Follow
Please sign in to leave a comment.