Recording

(since v1.7.0)

OpenVidu Server can be configured to record sessions. In the current version 1.8.0, every publisher stream is composed in the same video file in a grid layout, generating a unique MP4 file when the recording stops.

For example, in a session with two publishers the video file will look like this:

This type of grid recording is a pretty heavy consuming process. In order to record sessions and achieve good quality in the resulting videos it is strongly recommended to launch OpenVidu Server in a host with generous computing resources (Multicore >= 1GHz, 16GB of RAM)


To start OpenVidu Server properly configured to allow session recording it is necessary to:

1. Have Docker CE installed in the host machine

OpenVidu recording module consists of a Docker image that needs to be downloaded from the cloud. The process is 100% automatic, but you will need Docker CE installed in your server. If you enable OpenVidu recording service but there's no Docker installed, OpenVidu Server will fail to init, throwing the following exception:

Exception connecting to Docker daemon: you need Docker installed in this machine to enable OpenVidu recorder service


OpenVidu CloudFormation already includes the Docker image for recording service. You don't need to install anything or wait during the first execution if you use this type of deployment for OpenVidu Server


2. Launch OpenVidu Server with new environment variables

(Only variables related with OpenVidu recording service are stated below. To see a complete list of available environment variables, visit OpenVidu Server configuration)

For OpenVidu Server JAR

java -jar \
    -Dopenvidu.recording=true \
    -Dopenvidu.recording.path=/path/to/video/files \
    -Dopenvidu.recording.free-access=true \
openvidu-server.jar
  • openvidu.recording: if true OpenVidu recording service is enabled and sessions can be configured to be recorded. During the first execution of openvidu-server.jar, a Docker image (openvidu/openvidu-recording) will be downloaded.
  • openvidu.recording.path: where to store the recorded video files on the host machine.
  • openvidu.recording.free-access: if true any client can connect to

    https://OPENVIDU_SERVER_IP:OPENVIDU_PORT/recordings/any_session_file.mp4

    and access any recorded video file. If false this path will be secured with openvidu.secret param just as OpenVidu Server dashboard at https://OPENVIDU_SERVER_IP:OPENVIDU_PORT

For OpenVidu Server Docker image

openvidu/openvidu-server-kms

docker run -p 8443:8443 --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /PATH/TO/VIDEO/FILES:/PATH/TO/VIDEO/FILES \
    -e openvidu.recording=true \
    -e MY_UID=$(id -u $USER) \
    -e openvidu.recording.path=/PATH/TO/VIDEO/FILES \
    -e openvidu.recording.free-access=true \
openvidu/openvidu-server-kms

openvidu/openvidu-server (KMS up and running in the host machine)

docker run --net="host" -p 8443:8443 --rm \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /PATH/TO/VIDEO/FILES:/PATH/TO/VIDEO/FILES \
    -e openvidu.recording=true \
    -e MY_UID=$(id -u $USER) \
    -e openvidu.recording.path=/PATH/TO/VIDEO/FILES \
    -e openvidu.recording.free-access=true \
openvidu/openvidu-server
  • openvidu.recording: same as for OpenVidu Server JAR
  • openvidu.recording.path: same for in OpenVidu Server JAR
  • openvidu.recording.free-access: same as for OpenVidu Server JAR

It is also necessary to mount 2 volumes and pass MY_UID variable:

  • -v /var/run/docker.sock:/var/run/docker.sock: gives openvidu-server container access to the local Docker daemon
  • -v /PATH/TO/VIDEO/FILES:/PATH/TO/VIDEO/FILES: gives access to the recorded video files through the container
  • -e MY_UID=$(id -u $USER): for permission reasons


IMPORTANT! /PATH/TO/VIDEO/FILES must be the same in openvidu.recording.path=/PATH/TO/VIDEO/FILES property and in both sides of -v /PATH/TO/VIDEO/FILES:/PATH/TO/VIDEO/FILES flag


3. Configure your Sessions to be recorded

Setting property openvidu.recording to true only automatically enables recordings for insecure sessions (those directly created from the client side. See this FAQ and this FAQ).

In order to record a regular securized session, it is necessary to explicitly configure it through the REST API or any of the server clients (openvidu-java-client, openvidu-node-client).

Recording can be configured in two ways: automatic recording (since v1.7.0) or manual recording (since v1.7.0):

  • Automatic recording: your sessions will be recorded from the moment the first participant starts publishing media until the last participant leaves the session.
  • Manual recording: you will have to tell openvidu-server to start and to stop the recording. The recording will never be automatically stopped even though all participants leave the session (in fact the session will not be closed until the recording stops).

API REST

  1. Initialize your sessions with this POST method: POST /api/sessions. For sessions configured for automatic recording no more steps are needed
  2. If you have configured your session for manual recording

openvidu-java-client

Call OpenVidu.createSession() passing as optional parameter a SessionProperties object properly configured:

OpenVidu openvidu = new OpenVidu(OPENVIDU_URL, OPENVIDU_SECRET);
SessionProperties properties = new SessionProperties.Builder()
    .archiveMode(ArchiveMode.MANUAL) // ArchiveMode.ALWAYS for automatic recording
    .archiveLayout(ArchiveLayout.BEST_FIT)
    .mediaMode(MediaMode.ROUTED)
    .build();
Session session = openVidu.createSession(properties);

If Session is configured with ArchiveMode.MANUAL:

Archive archive = openVidu.startRecording(session.getSessionId()); // Starts recording
archive = openVidu.stopRecording(archive.getId()); // Stops recording

openvidu-node-client

Call OpenVidu.createSession() passing as optional parameter a SessionProperties object properly configured:

var openvidu = new OpenVidu(OPENVIDU_URL, OPENVIDU_SECRET);
var properties = new SessionProperties.Builder()
    .archiveMode(ArchiveMode.MANUAL) // ArchiveMode.ALWAYS for automatic recording
    .archiveLayout(ArchiveLayout.BEST_FIT)
    .mediaMode(MediaMode.ROUTED)
    .build();
var mySession = openvidu.createSession(properties);

If Session is configured with ArchiveMode.MANUAL:

var archive;

openvidu.startRecording(sessionId) // Starts recording
.then(response => {
    archive = response;
})
.catch(error => console.error(error));

openvidu.stopRecording(archive.getId()) // Stops recording
.then(response => {
    archive = response
})
.catch(error => console.error(error));

Future updates

  • Single stream recording: right now only grid layout recording is supported, but in the near future it is planned to support single stream recording for each participant publishing to the session. This type of video recording is intended to be much less demanding in terms of computing resources, and will provide developers greater freedom in the later processing of their videos.

  • More grid layouts: only BEST_FIT layout is supported right now, but there are more layouts that will be available in next development iterations. Moreover, developers will be able to provide their own custom layout if they want.


Local recording

OpenVidu Browser offers an extremely simple API to record Streams directly in the client's browser. Check it out here.