Release v1.9.0

CUSTOM LAYOUT RECORDING

Now you can create your own layouts for Session recording process. They are implemented with HTML/CSS/JS files, just as your OpenVidu application client-side.

1. Create your layout with HTML/CSS/JS files and put them in a path accessible to openvidu-server. There must be an index.html file as entrypoint for your custom layout:

   • WHAT SHOULD YOUR JS CODE DO: by making use of openvidu-browser-1.9.0.js library, you need to connect a recorder participant to the session. This means:

     1. Your layout must create the Session object like this:

     var session = OV.initSession('wss://' + location.hostname + ':8443/' + SESSION_ID + '?secret=' + SECRET + '&recorder=true');

     Being SESSION_ID and SECRET two parameters that will be url-encoded under ids sessionId and secret respectively. So, for example:

     var url = new URL(window.location.href);
     var SESSION_ID = url.searchParams.get("sessionId");
     var SECRET = url.searchParams.get("secret");
     var session = OV.initSession('wss://' + location.hostname + ':8443/' + SESSION_ID + '?secret=' + SECRET + '&recorder=true');

     1. You will need to subscribe to, at least, two events: streamCreated and streamDestroyed of Session object. That way you can update your video layout when any user starts or stops publishing. To sum up, this would be the simplest code you need to properly start your recorder participant:

     var OV = new OpenVidu();
     
     var url = new URL(window.location.href);
     var SESSION_ID = url.searchParams.get("sessionId");
     var SECRET = url.searchParams.get("secret");
     var session = OV.initSession('wss://' + location.hostname + ':8443/' + SESSION_ID + '?secret=' + SECRET + '&recorder=true');
     
     session.on("streamCreated", (event) => {
       session.subscribe(event.stream, 'html-id-where-insert-video');
     });
     session.on("streamDestroyed", (event) => {
       // The video is automatically removed by default but you can do whatever
       // you want here to update your layout when any user stops publishing
     });
     
     session.connect(null, (error) => {
       if (error) {
         console.error(error);
       }
     });

   • HOW TO IDENTIFY YOUR USERS: you can identify them by making use of property Stream.connection.data of the Stream object retrieved in Session event "streamCreated". That way you may know which particular user should be displayed in which particular HTML element of your layout. For example:

     session.on("streamCreated", (event) => {
       var stream = event.stream;
       if (stream.connection.data === 'userBigVideo') {
         session.subscribe(stream, 'big-video-div');
       } else if (stream.connection.data === 'userSmallVideo') {
         session.subscribe(stream, 'small-video-div');
       }
     });

1. Add new properties when launching openvidu-server (openvidu.recording.custom-layout and a new -v option if using Docker images):

   • openvidu-server-1.9.0.jar:

     java -jar \
       -Dopenvidu.recording=true \
       -Dopenvidu.recording.path=/PATH/TO/VIDEO/FILES \
       -Dopenvidu.recording.custom-layout: /PATH/TO/INDEX/CUSTOM/LAYOUT \
     openvidu-server-1.9.0.jar
     

   • openvidu-server-kms:1.9.0:

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

   • openvidu-server:1.9.0 (KMS running as a native service in the same 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 \
       -v /PATH/TO/INDEX/CUSTOM/LAYOUT:/PATH/TO/INDEX/CUSTOM/LAYOUT \
       -e MY_UID=$(id -u $USER) \
       -e openvidu.recording=true \
       -e openvidu.recording.path=/PATH/TO/VIDEO/FILES \
       -e openvidu.recording.custom-layout=/PATH/TO/INDEX/CUSTOM/LAYOUT \
     openvidu/openvidu-server:1.9.0
     

1. Configure your sessions to use your custom layout:

   Do exactly the same process explained here, but changing archiveLayout from BEST_FIT to CUSTOM.

   • If you are using the API REST, just change json body parameter "archiveLayout":"BEST_FIT" to "archiveLayout":"CUSTOM".
   • If you are using openvidu-java-client or openvidu-node-client, change SessionProperties.Builder().archiveLayout(ArchiveLayout.BEST_FIT) to SessionProperties.Builder().archiveLayout(ArchiveLayout.CUSTOM).

CONFIGURING MULIPLE CUSTOM LAYOUTS

You can implement as many custom recording layouts as you want. Simply store each one of them (each one with its own index.html entrypoint file) in a subfolder under path /PATH/TO/INDEX/CUSTOM/LAYOUT. Then, when configuring your sessions as stated above in point 3, just add a new parameter besides changing archiveLayout property:

• If you are using the API REST, add an additional field to json body: "archiveLayout":"CUSTOM", "customLayout":"RELATIVE/PATH/TO/INDEX"
• If you are using openvidu-java-client or openvidu-node-client, create SessionProperties object with a new step: new SessionProperties.Builder() .archiveLayout(ArchiveLayout.CUSTOM).customLayout("RELATIVE/PATH/TO/INDEX").build())

Path RELATIVE/PATH/TO/INDEX is the path from openvidu-server configuration property openvidu.recording.custom-layout to the specific index.html you want to use for a particular session recording. So, if you have the following folder tree structure:

/opt
+-- /openvidu
|   +-- /my_custom_layouts
|       +-- index.html
|       +-- /layout1
|           +-- index.html
|       +-- /layout2
|           +-- index.html
/etc
    ...

You should start openvidu-server with property openvidu.recording.custom-layout=/opt/openvidu/my_custom_layouts and you can use any of the 3 index.html files for recording any of your sessions. To use the outer layout, just configure archiveLayout to CUSTOM. To use any of the inner layouts, also configure customLayout to layout1 or layout2.

SAMPLE index.html

This is literally the simplest HTML for a custom recording layout. Use it as a template for building more complex ones.

<html>

<head><script src="openvidu-browser-1.9.0.min.js"></script></head>

<body>
    <div id="videos"></div>
</body>

<script>
    var url = new URL(window.location.href);
    var SESSION_ID = url.searchParams.get("sessionId");
    var SECRET = url.searchParams.get("secret");

    var OV = new OpenVidu();
    var session = OV.initSession('wss://localhost:8443/' + SESSION_ID + '?secret=' + SECRET + '&recorder=true');

    session.on("streamCreated", (event) => {
        session.subscribe(event.stream, 'videos');
    });
    session.on("streamDestroyed", (event) => {});
    session.connect(null, (error) => {
        if (error) {
            console.error(error);
        }
    });
</script>

</html>