API Calls | Screenleap API

Recording

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

Each screen share supports one recording, meaning you can start and stop recording only once during the duration of the screen share. You can start the recording when the screen share starts by adding the autoRecord=true to the request to create a screen share. Otherwise, you can start the recording after the screen share has started using the screenleap.startRecording() JavaScript call. A recording is automatically stopped when the screen share ends. You can stop recording before the screen share ends by making a call to screenleap.stopRecording(). The duration of each recording is limited to 8 hours.

A screen share started in paused mode will not be recorded. Recording will start once the screen share 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 screen share using the following JavaScript calls:

screenleap.startRecording(successCallback, errorCallback)

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

screenleap.pauseRecording(successCallback, errorCallback)

Pause recording for a screen share that is currently being recorded. When a recording is paused, the recording will pause on the last image shown until recording is resumed.

screenleap.resumeRecording(successCallback, errorCallback)

Resumes recording for a screen share that is being recorded but paused.

screenleap.stopRecording(successCallback, errorCallback)

Stops recording a screen share 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 screen shares 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 screen share, 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 screen shares. 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 »