Suggestions

close search

Customizing the video layout for composed archives

You can use the OpenTok REST API to customize the layout of videos in an OpenTok archive.

This feature applies to composed archives, not individual archives. (For general information on OpenTok archives, see the OpenTok archive developer's guide.)

Overview

By default, OpenTok archives arrange videos from the OpenTok session in a tiled layout. For example, the following illustrates the layout when there are 1, 2, 4, or 5 streams in a session:

This is known as the "best fit" layout. Alternately, you can select from a number of other predefined layouts. For the other layouts, you assign a class name to each OpenTok video streams to determine how it will appear in the layout. (See the next section, Predefined layout types.)

You can also define your own custom layouts, using CSS.

Currently, the composed archive is 640 x 480 pixels. Individual OpenTok videos are arranged in container rectangles within the archive video. If the aspect ratio of an individual stream's video does not match that of the container (for example, if it is an HD video or screen-sharing video), it is letterboxed to fit within the container. For example, the following illustration shows a best-fit layout with two 4:3 videos (1 and 4) and two HD videos (2 and 3):

To use this feature:

You can also define your own custom layouts.

Predefined layout types

There are four predefined layout types available: best fit, picture-in-picture, vertical presentation, and horizontal presentation.

Best Fit

To choose this layout, set the the type property to "bestFit". (See Specifying the initial layout type and Dynamically changing the layout type during an archive recording.) This is the default initial layout type.

This is a tiled layout, which scales according to the number of videos. The number of columns and rows of varies depending on the number of OpenTok streams in the archive. For example, the following illustrates the layout when there are 1, 2, 4, or 5 streams in a session:

Layout classes on these streams will have no effect on the layout. Each position in the list will be translated to a position in the grid.

This layout supports up to 9 OpenTok streams. However, we recommend adding no more than 5 streams, or quality will degrade.

Picture-in-Picture

To choose this layout, set the type property to "pip". (See Specifying the initial layout type and Dynamically changing the layout type during an archive recording.)

This is a picture-in-picture layout, where a small stream is visible over a full-size stream.


C = corner

Set the layout class of the full-size stream to "full". (See Assigning layout classes to OpenTok streams.) The first stream without this class occupies the corner position. If more than two streams are present in the archive, only the first two streams will be visible in the output.

Vertical Presentation

To choose this layout, set the the type property to "verticalPresentation". (See Specifying the initial layout type and Dynamically changing the layout type during an archive recording.)

This is a layout with one large stream on the right edge of the output, and several smaller streams along the left edge of the output.

Set the layout class of the focus stream to "focus". (See Assigning layout classes to OpenTok streams.) The streams without the focus class will occupy the left edge and divide the space evenly. If only one stream is present, it will occupy the full output size.

This layout supports 1 focus stream and up to 5 other streams. However, we recommend adding no more than 5 total streams, or quality will degrade.

Horizontal Presentation

To choose this layout, set the the type property to "horizontalPresentation". (See Specifying the initial layout type and Dynamically changing the layout type during an archive recording.)

This is a layout with one large stream on the top edge of the output, and several smaller streams along the bottom edge of the output.

There is one layout class used to specify the position of streams in this layout: focus. (See Assigning layout classes to OpenTok streams) The streams without this class will occupy the bottom edge and divide the space evenly. If only one stream is present, it will occupy the full output size. The positions can be visualized as such:

This layout supports 1 focus stream and up to 5 other streams. However, we recommend adding no more than 5 total streams, or quality will degrade.

Specifying the initial layout type

When you start the archive for a session, using the OpenTok REST API, you can, optionally, specify the initial archive layout type.

Set the request URL for the POST request to the following:

https://api.opentok.com/v2/project/{apiKey}/archive

Set the Content-Type to application/json and set the layout type as a property of the JSON data sent in the POST request:

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "pip"
  }
  "name" : "archive_name"
  "outputMode" : "composed",
}

If you are using a custom layout (see Defining custom layouts), set the type property to "custom" and pass in the stylesheet as an additional property—stylesheet:

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "custom",
    "stylesheet": "stream.instructor {\n  width: 100%;\n  height:50%;\n}"
  }
  "name" : "archive_name"
  "outputMode" : "composed",
}

Authenticate the REST call using a JWT token (see OpenTok REST API authentication):

X-OPENTOK-AUTH: <token>

The request returns a 400 error response code if you specify an invalid type.

If you do not specify an initial layout type, the composed archive uses the Best Fit layout type. If you specify any other layout type, be sure to apply appropriate layout classes for streams in the OpenTok session (see Assigning layout classes to OpenTok streams).

See Predefined layout types.

Dynamically changing the layout type during an archive recording

You can dynamically change the layout type by calling the /archive/layout REST API. Make a PUT request to the following URL:

https://api.opentok.com/v2/project/{apiKey}/archive/{archiveId}/layout

Set the Content-Type to "application/json" and include the layout type as a property of the JSON data in the PUT request:

{
  "type": "pip"
}

If you are using a custom layout) set the type property to "custom" and pass in the stylesheet as an additional property—stylesheet:

{
  "type": "custom",
  "stylesheet": "stream.instructor {\n  width: 100%;\n  height:50%;\n}"
}

Authenticate the REST call using a JWT token (see OpenTok REST API authentication):

X-OPENTOK-AUTH: <token>

The request returns a 400 error response code if you specify an invalid type.

When specifying a layout type other than the default Best Fit layout type, be sure to apply appropriate layout classes for streams in the OpenTok session (see Assigning layout classes to OpenTok streams).

Assigning layout classes to OpenTok streams

When using a layout type other than the default Best Fit, you must set the layout class for an OpenTok stream to use, based on the layout type:

Setting the initial layout class list for a client's streams

When you create a token for a client to connect to the OpenTok session, you can (optionally) specify the initial layout class list for streams published by the client. To do this, generate a token that includes the undocumented initial_layout_class_list setting. Set this to a string containing a space-separated list of layout classes.

Important: This feature is currently implemented the OpenTok server SDKs for Node v2.5.1, Python v2.5.0, and Ruby v2.4.0.beta.1.

Node:

var OpenTok = require('opentok'),
    opentok = new OpenTok(apiKey, apiSecret);

opentok.createSession({mediaMode:"routed"}, function(err, session) {
  if (err) return console.log(err);

  token = session.generateToken({
    expireTime : (new Date().getTime() / 1000)+(7 * 24 * 60 * 60), // in one week
    data :       'name=Johnny',
    initialLayoutClassList : ['focus', 'inactive']
  });
});

Python:

from opentok import OpenTok
from opentok import MediaModes
from opentok import Roles

opentok = OpenTok(api_key, api_secret)
session = opentok.create_session(media_mode=MediaModes.routed)
token = session.generate_token(expire_time=int(time.time()) + 10,
                               data=u'name=Johnny'
                               initial_layout_class_list=[u'focus'])

Ruby:

opentok = OpenTok::OpenTok.new api_key, api_secret

session = opentok.create_session :media_mode => :routed
token = session.generate_token({
    :role                      => :moderator
    :expire_time               => Time.now.to_i+(7 * 24 * 60 * 60) # in one week
    :data                      => 'name=Johnny',
    :initial_layout_class_list => ['focus', 'inactive']
});
Modifying the layout class list for a stream

You can dynamically change the layout class list for a stream by calling the OpenTok /session/{sessionId}/stream REST API. Make a PUT request to the following URL:

https://api.opentok.com/v2/project/{apiKey}/session/{sessionId}/stream

Set the Content-Type to "application/json" and include the layout class list as a property of the JSON data in the PUT request:

{
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "layoutClassList": ["full"]
    }
  ]
}

The id property is the stream ID. Note that you can update the layout class list for multiple streams by passing in multiple JSON objects in the items array.

The request returns a 400 response code if you specify an invalid layoutClassList value. The value must be an array of strings.

Getting the layout class list for a stream

You can get the layout class list for a stream by calling the OpenTok /session/{sessionId}/stream/{streamId} REST API. Make a GET request to the following URL:

https://api.opentok.com/v2/project/{apiKey}/session/{sessionId}/stream/{streamId}

The response includes JSON data, which includes a layoutClassList array:

{
  "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
  "videoType": "camera",
  "name": "",
  "layoutClassList": ["full"]
}

The request returns a 408 error response code if you specify an invalid stream ID.

Getting the layout class list for multiple streams

You can get the layout class list for all streams in a session by calling the /session/{sessionId}/stream REST API. Make a GET request to the following URL:

https://api.opentok.com/v2/project/{apiKey}/session/{sessionId}/stream/

The response includes JSON data, which includes an items property, which is array containing layout information for streams in the session:

{
  "count": 2
  "items": [
    {
      "id": "8b732909-0a06-46a2-8ea8-074e64d43422",
      "videoType": "camera",
      "name": "",
      "layoutClassList": ["full"]
    },
    ...
  ]
}

Defining custom layouts

In addition to the predefined layouts, you can use CSS to define your own custom layout for composed archive videos.

To use a custom layout, set the type property for the layout to "custom" and set an additional property, stylesheet, which is set to the CSS. (See Specifying the initial layout type and Dynamically changing the layout type while the session is being archived.)

CSS used in the stylesheet property of the layout resource will apply to a virtual DOM, which can be described in the following format:

<archive class="container">
  <stream class="{layoutClassList}" />
  <stream class="{layoutClassList}" />
  <stream class="{layoutClassList}" />
  ...
</archive>
Rules

The following default rules are applied to the <archive> element:

archive {
  position: relative;
  padding:0;
  margin:0;
  width: 640px;
  height:480px;
  overflow: hidden;
}

The following default rules are applied to <stream> elements:

stream {
  display: block;
  padding: 0;
  margin: 0;
}

Note: The container resolution is fixed and cannot be overridden by CSS.

Selectors

The following CSS selectors are supported:

The following pseudo-class selectors are supported:

The following CSS selectors are not supported:

Properties

The following table describes the supported CSS properties and their possible values:

Name Value
width, height positive number ( px/ %)
min-width, min-height positive number ( px/ %)
max-width, max-height] positive number ( px/ %)
left, right, top, bottom number ( px/ %)
margin, margin-left, margin-right,
margin-top, margin-bottom
number ( px/ %)
z-index positive number
position 'relative', 'absolute'
display 'inline', 'block', 'inline-block'
float 'none', 'left', 'right'
object-fit 'contain' (the default), 'cover'
Sample CSS

The following CSS arranges two streams with class names main and lower-left:

stream.main {
  position: absolute;
  left: 0;
  top: 0;
  width: 100%;
  height: 100%;
  z-index: 100;
}
stream.lower-left {
  position: absolute;
  left: 10%;
  bottom: 10%;
  width: 20%;
  height: 20%;
  z-index: 200;
}

The following CSS is based on the best fit predefined layout:

stream {
  float: left;
}
stream:first-child:nth-last-child(1) {
  width: 100%;
  height: 100%;
}

stream:first-child:nth-last-child(2),
stream:first-child:nth-last-child(2) ~ stream {
  width: 50%;
  height: 100%;
}
stream:first-child:nth-last-child(3),
stream:first-child:nth-last-child(3) ~ stream,
stream:first-child:nth-last-child(4),
stream:first-child:nth-last-child(4) ~ stream {
  width: 50%;
  height: 50%;
}
stream:first-child:nth-last-child(5),
stream:first-child:nth-last-child(5) ~ stream,
stream:first-child:nth-last-child(6),
stream:first-child:nth-last-child(6) ~ stream,
stream:first-child:nth-last-child(7),
stream:first-child:nth-last-child(7) ~ stream,
stream:first-child:nth-last-child(8),
stream:first-child:nth-last-child(8) ~ stream,
stream:first-child:nth-last-child(9),
stream:first-child:nth-last-child(9) ~ stream
{
  width: 33.33%;
  height: 33.33%;
}

The following CSS is based on the horizontal presentation predefined layout:

stream {
  float:left;
  margin-top: 60%;
  width: 20%;
  height: 20%;
}
stream.focus {
  position: absolute;
  top: 0;
  left: 0;
  margin-top: 0px;
  height: 80%;
  width: 100%;
}

The following CSS is based on the vertical presentation predefined layout:

stream {
  float: left;
  left: 0px;
  clear: left;
  width: 20%;
  height: 20%;
  padding: 0px;
}
stream.focus {
  position: absolute;
  padding: 0px;
  top: 0;
  left: 0;
  margin: 0px;
  left: 20%;
  height: 100%;
  width: 80%;
}

The following CSS is based on the picture-in-picture predefined layout:

stream.full {
  position: absolute;
  top: 0;
  right: 0;
  width: 100%;
  height: 100%;
  z-index: 100;
}
stream {
  position: absolute;
  right: 10%;
  top: 10%;
  width: 20%;
  height: 20%;
  z-index: 200;
}

Note: The CSS used by the predefined layouts are subject to change.