API Calls | Screenleap API

Screenleap

Recording

You can now easily record your share sessions using the recording feature. To enable recording for a share session, add record=true to your API request when creating the share session. Audio will also be recorded if you enable broadcast audio.

Each share session supports one recording, meaning you can start and stop recording only once during the duration of the share session. We automatically start recording on start of your share session. You can disable auto-record-on-start by adding autoRecord=false to the request to create a share session. When auto-record-on-start is disabled, you can start the recording using the screenleap.startRecording() JavaScript call. A recording is automatically stopped when the share session ends. You can stop recording before the share session ends by making a call to screenleap.stopRecording(). The duration of each recording is limited to 8 hours.

A share session started in paused mode will not be recorded. Recording will start once the share session is unpaused.

Pricing

The cost of a recording is based on the duration of the recording. It can be calculated by multiplying the duration of the recording by the cost of 5 participants at the selected tier:

Cost of Recording = Recording Duration X Cost of 5 Participants

For example, if a recording is 30 minutes long and you are using the SSL tier, the recording will cost $1.50 (30 x $0.01 x 5).

JavaScript Calls

The recording can be controlled during the share session using the following JavaScript calls:

screenleap.startRecording(successCallback, errorCallback)

Start recording the share session that wasn't automatically started when the share session started. If an error callback is not passed in, screenleap.onRecordStartError will be called.

screenleap.stopRecording(successCallback, errorCallback)

Stops recording a share session that is being recording. An error will be logged to the errorCallback if the recording has not been started yet.

Recording Processing

Screenleap processes completed recordings and converts them to MP4 videos files that you can download:

Processing - Completed recordings are processed and converted into MP4 video files. You will be notified when the recording has been processed. Notifications occur either via email or through a HTTP callback.

Downloading - The email or callback will contain a link that you can use to download the processed MP4 video file.

The HTTP webhook URL can be specified by editing your Developer Account. You will not receive a callbacks for share sessions where the recording was not started.

The processing time for a recording depends on a number of factors. Principally, it depends on the number of recordings in the queue and the size of the recording. The average processing time for a recording is about equal to the duration of the recording. If you have not been notified that a recording has been processed after 24 hours, please contact us so we can investigate.

You can monitor the status of your recordings from the API activity report. To access the report, click on Developer from the Account menu and then click on View monthly API activity report. If recording has been enabled for a share session, you will see its status under the Recording column.

The link to download the recording will also be shown in this section after processing is complete. Completed recordings will be retained for one month and then deleted. Please make sure that you download a copy of the processed MP4 video file before then.

HTTP Callbacks

Below is an example of the JSON data returned for a RECORDING_COMPLETE callback:

{
    "eventType": "RECORDING_COMPLETE",
    "screenShareCode": "123456789",
    "externalId": "my-meeting-1234",
    "recordingId": 1234,
    "recordingStartTime": 1429211907496,
    "recordingEndTime": 1429211926154,
    "recordingDurationInMinutes": 34,
    "recordingVideoUrl": "https://assets.screenleap.com.s3.amazonaws.com//mp4/...",
    "encryptionKey": "sTQy22NWJQzPDFKk5BbOuaUNcvpKSLBzBYy+aymzk08="
}

If there is an error in the recording, you will get a callback with the event type of RECORDING_ERROR:

{
    "eventType": "RECORDING_ERROR",
    "screenShareCode": "123456789",
    "externalId": "my-meeting-1234",
    "recordingId": 1234,
    "recordingStartTime": 1429211907496,
    "recordingEndTime": 1429211926154,
    "recordingDurationInMinutes": 34
}

Encryption of Stored Recordings

You can encrypt your recordings by passing "encryptRecording=true" when making the API call to create your share sessions. Encrypted recordings are not downloadable or viewable by anyone (including us) without the encryption key. In general, you should only enable encryption for extremely sensitive recordings as the retrieval of encrypted recordings can be tricky.

When encryption is enabled, your recordings will be encrypted after being processed before being stored in Amazon S3. Recordings are encrypted using an encryption key that 1) you specify by passing the "encryptionKey" parameter or 2) we auto-generate and pass back to you. If you provide your own encryption key, you need to ensure that it is a base64-encoded AES256 string.

To retrieve an encrypted recording, you will need to make a request to the recordingVideoUrl along with the correct headers. The required headers are x-amz-server-side-encryption-customer-algorithm, x-amz-server-side-encryption-customer-key, and x-amz-server-side-encryption-customer-key-MD5. Please see the Amazon S3 Server-Side Encryption documentation for information on how to make a proper request using the encryption key.

Please note that once a recording has been processed and a server-side callback has been made to your server with the download URL and the encryption key, we will delete the encryption key from our servers. If you lose the encryption key, the recording will not be recoverable.

Continue to HTTP Calls »