Skip to main content

Capture screenshots

Overview

You can use Cloud Recording RESTful API to take screenshots of a video stream in a channel and upload the screenshots to your third-party cloud storage.

The following two screenshot methods are supported:

  • Take screenshots only.
  • Capture screenshots and recording during a recording process. Agora only charges recording fees.

Implementation

Get a resource ID

Before recording, call the acquire method to apply for a resource ID.

An HTTP request example of acquire

  • Request URL:


    _1
    https://api.agora.io/v1/apps/<yourappid>/cloud_recording/acquire

  • Content-type: application/json;charset=utf-8

  • Authorization: Basic authorization. For more information, see How to pass the basic HTTP authentication.

  • Request body:


    _8
    {
    _8
    "cname": "httpClient463224",
    _8
    "uid": "527841",
    _8
    "clientRequest": {
    _8
    "resourceExpiredHour": 24,
    _8
    "scene": 0
    _8
    }
    _8
    }

Start recording

Set mode to individual when calling start to enable individual recording mode.

You cannot switch to a different recording mode once you start recording.

To capture screenshots, you need to configure the following parameters in clientRequest:

ParameterDescriptionNote
tokenThe dynamic key used for the channel to record.Required if the channel uses a token
recordingConfigConfigures stream subscription, transcoding, and the profile of the output audio and video.Required
snapshotConfigConfigures the time interval between two successive screenshots and the file format of the screenshots. snapshotConfig includes the following fields:
  • captureInterval: (Optional) Integer. The time interval (in seconds) between two successive screenshots. captureInterval should be within the range [1, 3600]. The default value is 10.
  • fileType: JSONArray. File format of the screenshots. fileType can only take ["jpg"], setting screenshots to the JPG format.
  • Required
    storageConfigConfigures the third-party cloud storage.Required
    recordingFileConfigConfigurations for the recorded files.If you are recording and taking screenshots in a recording process, this parameter is required; if you are only taking screenshots in a recording process, you cannot fill in this parameter.

    An HTTP request example of start

    • Request URL:


      _1
      https://api.agora.io/v1/apps/<yourappid>/cloud_recording/resourceid/<resourceid>/mode/individual/start

    • Content-type: application/json;charset=utf-8

    • Authorization: Basic authorization. For more information, see How to pass the basic HTTP authentication.

    • Request body:

    Capture screenshots only


    _28
    {
    _28
    "uid": "527841",
    _28
    "cname": "httpClient463224",
    _28
    "clientRequest": {
    _28
    "token": "<token if any>",
    _28
    "recordingConfig": {
    _28
    "channelType": 1,
    _28
    "subscribeUidGroup": 0
    _28
    },
    _28
    "snapshotConfig": {
    _28
    "captureInterval": 5,
    _28
    "fileType": [
    _28
    "jpg"
    _28
    ]
    _28
    },
    _28
    "storageConfig": {
    _28
    "accessKey": "xxxxxxf",
    _28
    "region": 3,
    _28
    "bucket": "xxxxx",
    _28
    "secretKey": "xxxxx",
    _28
    "vendor": 2,
    _28
    "fileNamePrefix": [
    _28
    "directory1",
    _28
    "directory2"
    _28
    ]
    _28
    }
    _28
    }
    _28
    }

    Capture screenshots and recording


    _34
    {
    _34
    "uid": "527841",
    _34
    "cname": "httpClient463224",
    _34
    "clientRequest": {
    _34
    "token": "<token if any>",
    _34
    "recordingConfig": {
    _34
    "maxIdleTime": 30,
    _34
    "streamTypes": 1,
    _34
    "channelType": 0
    _34
    },
    _34
    "snapshotConfig": {
    _34
    "captureInterval": 5,
    _34
    "fileType": [
    _34
    "jpg"
    _34
    ]
    _34
    },
    _34
    "recordingFileConfig": {
    _34
    "avFileType": [
    _34
    "hls"
    _34
    ]
    _34
    },
    _34
    "storageConfig": {
    _34
    "accessKey": "xxxxxxf",
    _34
    "region": 3,
    _34
    "bucket": "xxxxx",
    _34
    "secretKey": "xxxxx",
    _34
    "vendor": 2,
    _34
    "fileNamePrefix": [
    _34
    "directory1",
    _34
    "directory2"
    _34
    ]
    _34
    }
    _34
    }
    _34
    }

    Screenshot files

    The naming convention of screenshot files is <sid>_<cname>__uid_s_<uid>__uid_e_video_<utc>.jpg, where

    • <sid> is the recording ID.
    • <cname> is the channel name.
    • <uid> is the user ID.
    • <utc> is the UTC time when the screenshot was generated. The time zone is UTC+0, and the timestamp consists of the year, month, day, hour, minute, second, and millisecond. For example, if utc is 20190611073246073, the screenshot was generated on June 11, 2019, at 07:32:46.073 a.m.

    The screenshot file format is determined by fileType you set in start. Currently only the JPG format is supported.

    When a cloud recording server is disconnected or the process killed, the cloud recording service enables the high availability mechanism, where the fault processing center automatically switches to a new server within 90 seconds to resume the service. When the service enables the mechanism, the screenshot filenames are prepended with bak<n>, where n stands for the number of times the mechanism is enabled in a recording and starts off with 0. Taking the filename bak0_sid_channel1__uid_s_123__uid_e_video_20190611073246073.jpg as an example, bak0 indicates that this file was generated after the service enabled the high availability mechanism for the first time.

    Considerations

    Pay attention to the following parameters as incorrect settings result in errors and failure to capture screenshots:

    • In the URL of your request, you must set mode as individual.
    • Do not set recordingFileConfig.
    • streamTypes must be 1 or 2.
    • If you set subscribeAudioUid, you must also set subscribeVideoUids.

    If a user stops sending video stream during a session, the Cloud Recording service stops taking screenshots until the stream resumes.