Customizing the video layout for composed archives
You can use the Vonage Video REST API to customize the layout of videos in an archive.
This feature applies to composed archives, not individual archives. For general information on archives, see the Archiving guide.
Overview
By default, archives arrange videos from the 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 Vonage Video stream to determine how it will appear in the layout. (See Predefined layout types.)
You can also define your own custom layouts using CSS. See Defining custom layouts.
By default, the composed archive is 640x480 pixels (SD landscape, 4:3 aspect ratio). Individual Vonage videos are arranged in container rectangles within the recorded 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 SD landscape (4:3) videos (1 and 4) and two HD landscape (16:9) videos (2 and 3):
You can also set a composed archive to use a 480x640 (SD portrait, 3:4 aspect ratio), 1280x720 (HD landscape, 16:9 aspect ratio), 720x1280 (HD portrait, 9:16 aspect ratio), 1920x1080 (FHD landscape, 16:9 aspect ratio), or 1080x1920 (FHD portrait, 9:16 aspect ratio) resolution when you call the start archive method of the Vonage Video REST API. You may want to use a portrait aspect ratio when recording archives that include video streams from mobile devices (which often use the portrait aspect ratio).
To use this feature:
Specify the layout type for the composed archive - see Specifying the initial layout type and Dynamically changing the layout type while the session is being recorded.
You can also define your own custom layouts.
Specifying the initial layout type
When you start the archiving of a session, using the Vonage Video REST API, you can optionally, specify the initial archive layout type.
Set the request URL for the POST request to the following:
/v2/project/{appId}/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:
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:
You can also specify a layout type to use when there is a screen-sharing stream in the session by setting the screenshareType property of the layout property - see screen-sharing layouts:
Authenticate the REST call using a JWT token. see Vonage Video REST API authentication:
The request returns a 400 error response code if you specify an invalid type.
You can also specify the initial layout type when starting a recording using the server SDKs:
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 Vonage Video session
See Assigning layout classes to Vonage Video streams and Predefined layout types.
Dynamically changing the layout type during archiving
You can dynamically change the layout type by calling the /archive/layout REST API.
Make a PUT request to the following URL:
/v2/project/{appId}/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:
If you are using a custom layout set the type property to custom and pass in the stylesheet as an additional property — stylesheet: