OpenTok archiving lets you record, save, and retrieve OpenTok sessions.
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.
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 120 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:
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)
Use your TokBox Account 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 by 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 recording starts and stops, events are sent in the clients. For example, the
OpenTok.js library includes archiveStarted and archiveStopped events
dispatched by the Session object.
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.)
Archive output file can be of one of the following formats:
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"
},
{
"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"
}
],
"id" : "297b9c62-78b3-4152-9e98-7e167354c9e6",
"name" : "archive name",
"sessionId" : "2_MX4xMDB-fjE0MjkzMDQ3NzY3NTZ-WUpRUGVFUmhFSkRmVGljeU5zVnJpaXYxfn4"
}
This JSON file includes the following properties:
id — The unique identifier of this archive.
name — The name of this archive.
createdAt — The Unix time in milliseconds for when the archive
started.
files — An array of files included in the ZIP container. Each has
the following properties:
streamId — The corresponding stream ID for the stream
recorded to this file
filename — The name of the recorded media file
startTimeOffset — The offset, in milliseconds, for when this
file started recording (from the createdAt time for the archive)
stopTimeOffset — The offset, in milliseconds, for when this
file stopped recording (from the createdAt time for the archive)
connectionData — The
connection data
for the publishing client.
You can also have a session be automatically archived. You can specify this when you create the session, using one of the OpenTok server SDKs. The archive for an automatically archived session starts as soon as a client connected to the session starts publishing a stream. 60 seconds after the last client disconnects from the session, the archive stops, and it is made available or uploaded.
Automatically archived sessions include both audio and video, and they record all streams to a single (composed) MP4 file.
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 TokBox Account 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:
You can also view the status of archives at the TokBox Account:
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.