Starting an Archive Recording with the Video API

The Vonage Video API allows you to archive, save and retrieve sessions.

Basic workflow

You can create an archive recording for a session using one of the Server SDKs. When you create an archive, the recording starts.

You can only create an archive for sessions that have at least one client connected. (A client must start publishing a stream within one minute or the archive recording stops.)

As clients start and stop publishing streams, the streams are recorded.

There is no limit to the number of archives you can record; however, automatically archived sessions will restart a new recording every 4 hours until the recording stops.

The Server SDKs include methods for the following:

• Starting an archive recording
• Stopping an archive recording
• Listing archive recordings
• Retrieving archive recording information
• Deleting an archive

When you stop recording an archive, the Vonage video platform creates an MP4 file or (in the case of individual stream archives) a ZIP file. (See Individual stream and composed archives.)

When an archive recording starts and stops, events are emitted in the clients. For example, the OpenTok.js library includes archiveStarted and archiveStopped events dispatched by the Session object.

Composed vs. individual archives at a glance

• Composed archives are the default. Vonage renders a single MP4 (H.264/AAC) using all published streams and the layout rules you configure. They are immediately playable and automatically used for automatically archived sessions. Composed archives record up to 16 concurrent video streams (and up to 50 audio streams).
• Individual stream archives produce a ZIP that contains a media file for each stream ( .webm or .mkv) plus a JSON manifest. Choose this when you plan to post-process or remix streams. Individual archives can capture up to 50 video streams (and up to 50 audio streams) but require downstream processing before playback and are not supported for automatic archiving.
• Specify the format by setting outputMode to composed (default) or individual when you call the archiving REST API or a Server SDK. The comparison below expands on the differences.

Archive recording duration

The maximum recorded length of an archive recording is 4 hours (14,400 seconds). This recorded length refers to the cumulative time in which streams are published (and being recorded).

While streams are published (and recorded), the archive's status is set to "started". (See Archive status changes).

While an archive is recording without any streams published, the status is set to "paused".

The maximum total length of an archive recording, including "started" and "paused" states, is 12 hours (43,200 seconds). Recordings automatically time out (and stop recording) after 1 hour (3,600 seconds) of inactivity (when no clients are publishing streams).

Notes:

• Automatically archived sessions result in one or more consecutive recordings, which have a maximum length of 4 hours each.
• Archives in progress end during server rotation (with the exception of automatic archives, which restart automatically when the session migrates during server rotation). You can restart archives in response to server rotation notification events. See Server Rotation and Session Migration.

Archive Recording Storage

Use your Vonage Account to specify a target for completed archive recording files to be uploaded to.

This can be your own Amazon S3 bucket, a bucket at an S3-compliant storage provider other than Amazon, or a Windows Azure container.

For S3-compliant storage providers other than Amazon S3, we support Cloudian and Google Cloud Storage (accessed using the AWS S3 API). Other S3-compatible services may have feature limitations.

See using S3 storage with Vonage Video API archiving and using a Windows Azure container with Vonage Video API archiving.

When the archive recording is completed (the archive recording status change is set to "stopped"), we will attempt to upload the archive recordingfile to the specified target (such as an S3 bucket or Azure container) for up to 72 hours after the archive recording iscreated (or at least 6 hours if fallback is enabled), retrying multiple times through a distributed upload scheduling policy.

If upload to the specified target is successful, the archive recording status is set to "uploaded".

If you do not define an Amazon S3 bucket or Azure container, or if uploading to the specified bucket/container fails (after retries), recorded archives are available for download from the Vonage cloud. In such case the archive recording status is set to "available". Archives made available on the Vonage cloud can be downloaded for 72 hours from the time they are created. You will also receive an email reporting the upload failure to the email address listed on your Vonage account.

To prevent fallback storage to the Vonage cloud, log in to your Vonage Account, head over to Applications > Select your video application and set the option to disable the archive recording storage option.

If upload to the specified target fails (after attempted retries) and fallback to Vonage storage is disabled, the archive recording status is set to "failed".

You cannot access the archive recording until it is uploaded to your specified target or available on Vonage storage.

For archives stored in the Vonage cloud, the download URL is provided in the url property of the archive recording when the status is set to "available".

Each download URL used with archive recording storage fallback is a pre-signed URL that uses security credentials to grant time-limited permission to download the archive.

After 10 minutes the pre-signed URL will expire and a new pre-signed URL must be requested using the REST API or server method to retrieve the download URL.

For security, the download URL is only available from making the REST API calls or server SDK methods for listing archives (which require your account credentials).

Audio-only and video-only archives

When you create an archive recording using one of the Vonage Video Server SDKs, you can specify whether it will record audio, video, or both. (The default is to record both.)

Individual stream and composed archives

The archive recording output file can be of one of the following formats:

Choose composed archiving when you want Vonage to deliver a playable MP4 as soon as the recording finishes. Choose individual stream archives when you need raw stream captures for editing, compliance, or bespoke playback experiences.

Composed archives

The archive recording is a single MP4 file composed of all streams. This is the default setting. It is also used for automatically archived sessions.

The MP4 file uses H.264 video and AAC audio (at 128 Kbps and a 48-Khz sample rate).

You can customize the layout of a composed archive, adjusting the visual arrangement of streams and which streams are displayed. See Customizing the video layout for composed archives.

By default, composed archives have a 640x480-pixel (SD landscape) resolution. To set a composed archive to have a 480x640 (SD portrait), 1280x720 (HD landscape), 720x1280 (HD portrait), 1920x1080 (FHD landscape), 1080x1920 (FHD portrait) resolution, set the resolution property to 480x640, 1280x720, 1920x1080, 720x1280, or 1080x1920 when calling the start archive method of the Vonage Video server SDK. 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).

You can set the maximum video bitrate of a composed archive recording to control the size of the archive. Set the maxBitrate option when calling the create new archive method. Specify a bitrate, in bits per second, between 100,000 and 6,000,000. This setting only applies to the video bitrate of the archive. If the output archive has audio, those bits will be excluded from the limit. This option is only available for composed archives (not for individual stream archives). When you set the maximum bitrate, the archive uses a constant bitrate.

You can set the quantization parameter (QP) for a composed archive, to adjust the trade-off between video quality and file size. Set the quantizationParameter option when calling the create new archive method. Setting the quantization parameter causes the archive to use a variable bitrate and a constant compression quantization, resulting in a consistent quality level across scene changes. Valid values are from 15 to 40, and 20 to 30 produce reasonable results without a large perceptual quality difference. Lower QP values produce finer video compression quantization, resulting in increased video quality (retaining more video detail) and a larger file size. Higher QP values produce coarser video compression quantization, decreasing video quality and resulting in a smaller file size. You cannot set both the quantizationParameter property and the maxBitrate property — doing so results in an error.

Note: Currently, the quantization parameter setting is only available in the REST API, not in the Vonage Video API server SDKs.

By default, if you do not set quantizationParameter or maxBitrate when creating a composed archive, the archive uses a variable bitrate encoding with a quantization parameter of 19 (very high quality).

Individual stream archive recordings

The archive is a ZIP container file with multiple individual media files for each stream, and a JSON metadata file for video synchronization.

You can specify this format when you use one of the Vonage Video server SDKs to start the archive. This format is not available for automatically archived sessions.

Working with individual stream archive recordings

Individual stream archive mode is intended for use with a post-processing tool, to produce customized content generated by your application. There are some considerations that developers should evaluate when choosing to use the feature.

Individual stream containers

Individual stream archive media is delivered as a ZIP archive, containing files for each audio-video stream:

• Each stream container in the archive corresponds to a stream published to Vonage video platform. The publisher's stream ID matches its corresponding file name, and each stream ID is declared in the archive manifest.

When a stream is interrupted and resumed because of automatic reconnection or when a stream is added and removed repeatedly in a manual stream mode archive, the ZIP archive will include separate files for each of the stream's individual segments.

• Stream containers are either of type .webm, or .mkv, depending on your application's configuration. Archives for applications that have VP8 set as the preferred video codec have webm containers, and applications that have H.264 set as the preferred video codec use the mkv format. See Notes on archiving with VP9 videos for more important details on VP9 video in indivi

• Individual stream archive containers are a capture of all the video and audio received by the archive server. This media is not processed, and therefore in most cases the container is not suitable for direct playback.

The stream container is treated like a transport stream — all media received at the archive server is written directly to file, without inspection or post-processing. This design has implications for downstream consumption of stream containers. In most cases, direct playback of an individual stream archive container will not be possible, or will have issues because of the contents of the container:

• The declared dimensions for the stream header are seldom correct. Currently, the headers for the container will show a video track with 640x480-pixel dimensions, regardless of the dimensions of encoded video frames.

• Video frames will change in dimensions over time. This can also include aspect ratio changes, particularly with screen-sharing streams.

• Audio and video frames may not arrive with monotonic timestamps; frame rates are not always consistent. This is especially relevant if either the video or audio track is disabled for a time, using one of publishVideo or publishAudio publisher properties.

Frame presentation timestamps (PTS) are written based on NTP timestamps taken at the time of capture, offset by the timestamp of the first received frame. Even if a track is muted and later unmuted, the timestamp offset should remain consistent throughout the duration of the entire stream. When decoding in post-processing, a gap in PTS between consecutive frames will exist for the duration of the track mute: there are no "silent" frames in the container.

To produce viewable content from individual stream archiving files, you need to run the media through a post processor to repair individual stream containers or multiplex/composite multiple containers into a final product.

Individual stream recording manifest

Individual stream archives include a JSON metadata file, which provides information on the stream recordings included in the archive. It is of the following format:

{
  "createdAt" : 1429305105162,
  "files" : [
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "a1475893-99f5-4f02-b697-5d69e8e30d19.webm",
      "size" : 5558064,
      "startTimeOffset" : 3119,
      "stopTimeOffset" : 48765,
      "streamId" : "a1475893-99f5-4f02-b697-5d69e8e30d19",
      "videoType": "camera"
    },
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "5ab71b7b-d998-4683-ad2b-7769d6533666.webm",
      "size" : 5396527,
      "startTimeOffset" : 2799,
      "stopTimeOffset" : 48764,
      "streamId" : "5ab71b7b-d998-4683-ad2b-7769d6533666",
      "videoType": "screen"
    }
  ],
  "id" : "297b9c62-78b3-4152-9e98-7e167354c9e6",
  "name" : "archive name",
  "partnerId" : 123456,
  "sessionId" : "2_MX4xMDB-fjE0MjkzMDQ3NzY3NTZ-WUpRUGVFUmhFSkRmVGljeU5zVnJpaXYxfn4"
}

Selecting streams to be included in a archives

When you start an archive, if you set the streamMode to manual, you can choose the streams to include in the archive.

You can add and remove streams during the archive recording. And you can specify whether the archive recording will include a stream's audio or video (or both).

Otherwise, with the streamMode set to auto (the default), all streams are included (with audio and video) in the archive. See Starting an archive recording and Selecting streams to be included in an archive.

However, in a composed archive there is a limit of 16 video streams and 50 audio streams included at one time (for both automatic and manual stream modes), and streams are included based on stream prioritization rules. For manual stream mode archives, stream updates are sent as Archive status changes.

Automatically archived recording sessions

You can have a session be automatically archive by specifying this when you create the session, using one of the Vonage Video server SDKs.

The archive for an automatically archived session starts as soon as a client connects to the session.

Automatically archived sessions include both audio and video, and they record all streams to the same (composed) MP4 file.

However, if the recording lasts longer than 4 hours (14,400 seconds), the session is recorded to multiple, consecutive MP4 files, of up to 4 hours each in length, until the recording is stopped. Consecutive automatic archives for a session will overlap slightly, so that no recorded data is missed.

You can call the Vonage Video server-side SDK method for listing archive and pass in the sessionID parameter to list archives for a specified session ID.

You can then determine the sequence of the separate MP4 files, by looking at the createdAt property of each archive listed in the JSON data returned.

You cannot stop an automatic archive using the server SDKs. Automatic archives stop 60 seconds after the last client disconnects from the session or 60 minutes after the last client stops publishing a stream to the session.

You should strictly avoid reusing session IDs if you will be using automatic archiving. Reusing a session ID can cause automatic archives to fail if a previous automatic archive for the session has timed out.

Do not use automatic archives for short-lived sessions, such as those used for pre-call or connectivity tests. You will be billed for excessive archive resource usage, because automatic archives stop 60 seconds after the last client disconnects from the session or 60 minutes after the last client stops publishing a stream to the session (if the client remains connected after publishing).

Post processing composed archives

Video archive recordings have an archive recording duration of up to 4 hours, 14,400 seconds. Therefore, a longer video session will not be recorded in a single archive file. To avoid losing a part of the session, use the automatically archived sessions feature, which enables the generation of several files to cover the entire session. Alternatively, use the simultaneous archives feature to start a second recording prior to ending the previous recording. In both cases, these archives are generated with a short overlap between the end of one file and the beginning of the next.

If you prefer to have a single file containing the entire session, you can use the Post-processing composed-archives tool, which merges consecutive overlapping recordings and attemps to make the transition as perceptually smooth as possible. You can use this tool to generate a single but longer file that contains media from several shorter archive files. For more details, see the developer guide Post Processing Composed Archives. The tool is available at https://github.com/Vonage/archive-post-processing.

You can also use this tool with video recordings that are not created as Vonage Video archives, as long as some media overlapping is present and the video recordings fulfill a series of characteristics, such as the use of the H264 and AAC LC codecs for respectively video and audio.

Simultaneous archive recordings

To record multiple archives for the same session simultaneously, set the multiArchiveTag option when starting each archive. You must set this to a unique string for each simultaneous archive recording of an ongoing session.

You can use different layouts and assign different streams to each simultaneous archive recording.

In automatically archived sessions, set the multiArchiveTag option to start a new simultaneous archive that is archives simultaneously with the automatic archives. Automatic archives start and end when the session starts and stops on its own (following the rules for automatic archives), while you stop manually started separately.

Archive recording status changes

You can register a callback URL for notification when an archive's status changes. The status of an archive is set to one of the following:

Use your Vonage Account to specify a callback URL. When an archive status changes, the server sends HTTP POST requests to the URL you specify. The Content-Type for the request is application/json. The data of the request is a JSON object of the following form:

{
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "event": "archive",
    "createdAt" : 1384221380000,
    "duration" : 328,
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "https://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
}

The JSON object includes the following properties:

You can also view the status of archives in your Vonage Account:

1. Navigate to your Vonage Account dashboard.
2. From the list of applications in the left of the page, select the application that will contain sessions that you are archiving.
3. In the archiving section, click the Archive List tab. Details on archives in the application are listed.

Archive recording security

You can secure your archives in the following ways:

• Turn off archive recording storage fallback — By default, Vonage stores an archive file on Vonage servers if it was unable to upload the file to your specified S3 or Azure server. To prevent this fallback storage (which is enabled by default), log in to your Vonage Account, select the application, and set the option to disable archive storage fallback.
• Use Vonage encryption — This allows you to create Vonage archives where the data is never at rest in an unencrypted state. Of the available methods of securing your Vonage recordings, this provides the highest level of security. This is available as an add-on feature. For more information, see the Vonage encryption documentation.
• Use Amazon S3 server-side encryption — This uses Amazon S3-managed encryption keys for encryption. Learn about Amazon S3 server-side encryption here.

Combining Archiving with Experience Composer

It is possible to combine archiving and Experience Composer.