Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Vonage Communications APIs

Visit the Vonage API Developer Portal

Archiving

Vonage Video API archiving lets you record, save and retrieve sessions.

This topic includes the following sections:

Basic workflow

Important: You can only archive sessions that use the OpenTok Media Router (sessions with the media mode set to routed).

You can create an archive for an OpenTok session using the OpenTok REST API or one of the OpenTok 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 stops.)

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

Important: You can record up to 16 video streams with composed archiving, or 50 with individual stream archiving. (Both composed and individual stream archives can include up to 50 audio streams.) See Individual stream and composed archives. After this limit is reached, if additional streams are published to the session, they are not recorded. The maximum recorded length of an archive (the cumulative length of time when streams are published in the session) is 4 hours (14,400 seconds). See Archive duration for more details.

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

The OpenTok REST API and the OpenTok Server SDKs include methods for the following:

When you stop recording an archive, the OpenTok server 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.

Archive duration

The maximum recorded length of an archive 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, including "started" and "paused" states, is 12 hours (43,200 seconds). Archives automatically time out (and stop recording) after 1 hour (3,600 seconds) of inactivity (when no clients are publishing streams).

Note: Automatically archived sessions result in one or more consecutive recordings, which have a maximum length of 4 hours each.

Archive storage

Use your Video API account to specify a target for completed archive 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 OpenTok archiving and Using a Windows Azure container with OpenTok archiving.

When the archive is completed (the archive status is set to "stopped"), we will attempt to upload the archive file to the specified target (such as an S3 bucket or Azure container) for up to 72 hours after the archive is created (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 status is set to "uploaded".

If upload to the specified target fails (after retries) and fallback to OpenTok storage is enabled, we make the archive available for download from the OpenTok cloud, and the archive status is set to "available". Once the file is available for download from the OpenTok cloud, we will no longer attempt to upload to your specified target. Archives made available on the OpenTok cloud are available for 72 hours from the time they are created.

To prevent fallback storage to the OpenTok cloud, log in to your Video API account, select the project, and set the option to disable the archive storage fallback.

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

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

For archives stored in the OpenTok cloud, the download URL is provided in the url property of the archive when the archive status is set to "available". Each download URL used with archive 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 retrieving archive information or listing archives (which require your account credentials).

Audio-only and video-only archives

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

Individual stream and composed archives

Archive output file can be of one of the following formats:

Notes:
  • In a composed archive, if archiving is started and no data is streamed during the duration of the archive (no audio or video is published), the size of archive file will be 0 bytes.
  • In a composed archive, the video for each included stream may start slightly behind the audio (with the video appearing black until it starts).

Working with individual stream archives

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:

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:

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. Suggestions for getting started with downstream processing are outlined in our archiving-composer GitHub repository: https://github.com/opentok/archiving-composer.

Individual stream archive 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"
}

This JSON file includes the following properties:

Important: In an individual stream archive, if there is a short period where no streams are published during the recording, the startTimeOffset and stopTimeOffset values can be off by a bit. This is a known issue.

Post processing individual archives

A sample post processor application is available at https://github.com/opentok/archiving-composer.

Selecting streams to be included in an archive

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 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.

Automatically archived sessions

You can also have a session be automatically archived. You can specify this when you create the session, using the OpenTok REST API or one of the OpenTok server SDKs:

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

The REST API method to create a session includes an option to set the archive name and the archive resolution when creating an automatically archived session.

Note: If archiving is started and no data is streamed during the duration of the archive (no audio or video is published), the size of archive file will be 0 bytes.

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 archive is stopped. Consecutive automatic archives for a session will overlap slightly, so that no recorded data is missed.

You can call the OpenTok REST method for listing archives and pass in the sessionID query 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 by the call the REST method.

You cannot stop an automatic archive using the OpenTok REST API or 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.

Important:
  • If you expect to have long periods during which archiving will be paused, you should consider starting and stopping archives using the methods in the OpenTok REST API or one of the OpenTok Server SDKs (instead of having the session be archived automatically).
  • 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).

Simultaneous archives

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 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 recorded 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 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 Video API account to specify a callback URL.

Secure callbacks: You can secure webhook callback requests with signed callbacks, using a signature secret. See Secure callbacks.

When an archive's status changes, the server sends HTTP POST requests to the URL you supply. 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 at the Video API account:

  1. Navigate to your Video API account page.
  2. From the list of projects in the left of the page, select the project that will contain sessions that you are archiving.
  3. In the Archiving section, click the Archive List tab. Details on archives in the project are listed.

Archive security

You can secure your archives in the following ways:

Sample apps

The following sample apps demonstrate archiving with OpenTok:

More information

See the documentation for the archiving-related methods in the OpenTok REST API and in the API references for the OpenTok server SDKs. Also, each of the server SDKs includes a sample archiving application.