OpenTok archiving lets you record, save and retrieve OpenTok sessions.
This topic includes the following sections:
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: The recommended maximum number of streams in an archive is five. You can record up to nine streams; however, in a composed archive 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. (Note, however, that automatically archived sessions will restart a new recording every 120 minutes 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 sent in the clients. For example, the
OpenTok.js library includes archiveStarted and archiveStopped events
dispatched by the Session object.
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. To prevent this fallback storage, log in to your TokBox Account, select the project, and set the option to disable the archive storage fallback.
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:
Composed archives — The archive is a single MP4 file composed of all streams. This is the default setting. It is also used for automatically archived sessions (see Automatically archived sessions). The MP4 file uses H.264 video and AAC audio.
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) resolution. To set a composed
archive to have a 1280x720 (HD) resolution, set the resolution property to
"1280x720" when calling the start archive method
of the OpenTok REST API.
Individual stream archives — 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 OpenTok server SDKs to start the archive. This format is not available for automatically archived sessions (see Automatically archived sessions).
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 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 OpenTok. The publisher's stream ID matches its corresponding file name, and each stream ID is declared in the archive manifest.
Stream containers are either of type .webm, or .mkv, depending on
your project's configuration. Archives for projects that have VP8 set as the
preferred video codec
have webm containers, and projects that have H.264 set as the preferred video codec use the
mkv format.
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 be 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 of an individual stream archive container will not be possible, or will have issues because of the contents of the container:
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. Suggestions for getting started with downstream processing are outlined in our archiving-composer GitHub repository: https://github.com/opentok/archiving-composer.
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",
"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 file has the following properties:
streamId — The corresponding stream ID for the stream
recorded to this file.filename — The name of the recorded media file. This will be
a .webm for an archive of a session in a standard OpenTok project, and it will
be a .mkv for an archive of a session in a Safari OpenTok
project.
If a stream is disrupted or interrupted by a network problem, several files may be present for the same stream (corresponding to each segment), and the filename for each stream segment will be appended with an index number (such as "_1" or "_2") after the stream ID to identify the order of the segment.
startTimeOffset — The offset, in milliseconds, for when
this file started recording (from the createdAt time for the
archive)—see the important note below.
stopTimeOffset — The offset, in milliseconds, for when
this file stopped recording (from the createdAt time for the
archive)—see the important note below.connectionData — The
connection data
for the publishing client.videoType — Either "camera" or "screen". A "screen" video uses
screen sharing on the publisher as the video source; for other videos, this property
is set to "camera". For a stream published from a mobile device, the screen type
can change from a camera to a screen-sharing video type. However, the property
in the archive manifest only indicates the initial video type.
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.
A sample post processor application is available at https://github.com/opentok/archiving-composer.
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.
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 2 hours (120 minutes), the session is recorded to multiple, consecutive MP4 files, of up to 2 hours each in length, until the archive is stopped.
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 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.
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."paused" — When an archive is paused, nothing is recorded. The archive is paused
if any of the the following conditions occur:
"stopped".
"stopped".
"started".
"stopped" — The archive stopped recording."uploaded" — The archive is available for download from the Amazon S3 bucket or
Windows Azure container you specified at your
TokBox Account. Note that for very small archives, the
"uploaded" status event may occur before the "stopped" status event."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 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" : "",
"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:
createdAt — The timestamp for when the call to
start the archive occurred, expressed in milliseconds since the Unix epoch
(January 1, 1970, 00:00:00 UTC). Note that this value is rounded to the
nearest second. Also note that this value differs from the createdAt
value in the REST method for retrieving archive
information and the createdAt value in the
manifest for an individual stream archive.
In those, the createdAt value is set to the time the recording effectively started
on the OpenTok servers (not the time when the call to start the recording occurred).
Note that even if a call to start an archive is issued, the archive will not start
effectively recording on the OpenTok server until at least one client publishes a
stream in the session.duration — The duration of the archive in seconds. For archives that 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.resolution — The resolution of the archive (either "640x480" or "1280x720").
This property is only set for composed archives. You can set the resolution of a composed archive
when callin the start archive method
of the OpenTok REST API.reason — For archives with the status "stopped" or "failed", this string
describes the reason the archive stopped (such as "maximum duration exceeded") or failed.sessionId — The session ID of the OpenTok session that was archived.size — The size of the archive 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."paused" — When an archive is paused, nothing is recorded. The archive is paused
if any of the the following conditions occur:
"stopped".
"stopped".
"started".
"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 in your TokBox Account.
Note that for very small archives, the "uploaded" status event may occur before the
"stopped" status event.url — The download URL of the available archive 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 TokBox Account:
You can secure your archives in the following ways:
The following sample apps demonstrate archiving with OpenTok:
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.