Archiving Overview

OpenTok archiving lets you record, save, and retrieve OpenTok sessions. The archiving feature for OpenTok 2.0 is currently in beta.

Basic workflow

You 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 three minutes or the archive stops.)

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

The recommended maximum number of streams in an archive is five. You can record up to nine streams; however, quality may degrade if you record more than five streams. If more than nine streams are published to the session, they are not recorded. Also, archive recordings are limited to 90 minutes in length. There is no limit to the number of archives you can record.

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

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

When you stop recording an archive, the OpenTok server creates an MP4 file (H.264 video, AAC audio) containing a recording of the streams in the session.

Use the OpenTok dashboard to specify your own Amazon S3 bucket or Windows Azure container for completed archive files to be uploaded to. See Using an Amazon S3 bucket with OpenTok archiving and Using an Windows Azure container with OpenTok archiving.

If you do not set an Amazon S3 bucket or Windows Azure container, or if uploading to the specified bucket or container fails, recorded archives are available for retrieval from download from the OpenTok cloud. Archives made available on the OpenTok cloud are available for 72 hours from the time they are created.

When an archive recordings start and stop, events are sent in the clients. For example, the OpenTok.js library includes archiveStarted and archiveStopped events dispatched by the Session object.

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:

  • "started" — The archive started and is in the process of being recorded.
  • "stopped" — The archive stopped recording.
  • "uploaded" — The archive is available for download from the Amazon S3 bucket or Windows Azure container you specified at the OpenTok dashboard.
  • "available" — The archive is available for download from the OpenTok cloud.
  • "expired" — The archive is no longer available for download from the OpenTok cloud. (Archives on the OpenTok cloud are only available for 72 hours from the time they are created.)
  • "failed" — The archive recording failed.

Use the OpenTok dashboard to specify a callback URL. 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" : "",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
}

The JSON object includes the following properties:

  • createdAt — The timestamp for when the archive started recording, expressed in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • duration — The duration of the archive in seconds. For archives that have are being recorded (with the status property set "started"), this value is set to 0.
  • id — The unique archive ID.
  • name — The name of the archive you supplied (this is optional)
  • partnerId — Your OpenTok API key.
  • reason — For archives with the status "stopped", this can be set to "90 mins exceeded", "failure", "session ended", "user initiated". For archives with the status "failed", this can be set to "system failure".
  • sessionId — The session ID of the OpenTok session that was archived.
  • size — The size of the MP4 file. For archives that have not been generated, this value is set to 0.
  • status — The status of the archive:
    • "available" — The archive is available for download from OpenTok.
    • "expired" — The archive is no longer available for download from the OpenTok cloud. (Archives on the OpenTok cloud are only available for 72 hours from the time they are created.)
    • "failed" — The archive recording failed.
    • "started" — The archive started and is in the process of being recorded.
    • "stopped" — The archive stopped recording.
    • "uploaded" — The archive is available for download from theAmazon S3 bucket or Windows Azure container you specified at the OpenTok dashboard.
  • url — The download URL of the available MP4 file. This is only set for an archive with the status set to "available"; for other archives, (including archives with the status "uploaded") this property is set to null. The download URL is obfuscated, and the file is only available from the URL for 10 minutes. To generate a new URL, use the REST API for retrieving archive information or listing archives.

You can also view the status of archives at the OpenTok dashboard:

  1. Click the Projects button on the OpenTok dashboard.
  2. From the list of projects in the top right-hand corner of the page, select the project that will contain sessions that you are archiving.
  3. Click the Project Archives tab. Details on archives in the project are listed at the bottom of the pages

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, the server SDKs each include a sample archiving application.

IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat