Start recording

After getting a resource ID, call the start method to begin cloud recording. The Cloud Recording service does the following after you call start:

1. Subscribes to the audio and video streams in the channel according to recordingConfig.
2. Processes the subscribed media streams, such as generating recorded files in the specified file format, taking video screenshots, or uploading recorded files to an extension service.
3. Uploads the recorded files or screenshots to your third-party cloud storage according to storageConfig.

The HTTP method and endpoint of start:

• Method: POST
• Endpoint: /v1/apps/<appid>/cloud_recording/resourceid/<resourceid>/mode/<mode>/start

The request frequency limit is 10 requests per second for each Agora account. Contact Agora technical support if you need to raise the limit.

The following parameters are required in the URL.

Parameter	Type	Description
appid	String	Your App ID.
resourceid	String	The resource ID requested by the acquire method.
mode	String	One of the following three recording modes: Individual recording (individual): Records the audio and video of each user ID in separate files. Composite recording (mix): (Default) Records the audio and video of multiple user IDs in a single file. Web page recording (web): Records the content and audio on a specified web page in a single file.

The following parameters are required in the request body.

Parameter	Type	Description
cname	String	In web page recording mode, use cname to distinguish between recording sessions. In other recording modes, use cname to set the name of the channel to be recorded.
uid	String	A string containing the user ID of the recording client. Must be the same uid used in the acquire method.
clientRequest	JSON	A specific client request that requires the following parameters: token: String. The dynamic key used for the channel to record. Ensure that you set this parameter if App Certificate is enabled for your application. See Authenticate Your Users with Tokens. recordingConfig: JSON. Configurations for subscribing to media streams. recordingFileConfig: JSON. Configurations for the recorded files. snapshotConfig: JSON. Video screenshot configurations. storageConfig: JSON. Third-party cloud storage configurations. extensionServiceConfig: JSON. Configurations for third-party extension services. Currently supports ApsaraVideo for VoD and web page recording.

appsCollection is a JSON Object for configuring how the application services are combined and applied. It contains the following fields:

• combinationPolicy: (Optional) JSON Object. The combination method of various Cloud Recording applications.
  • default: (Default) String. Use this method for all application services except for Postpone Audio Mixing.
  • postpone_transcoding: Use this method if you use Postpone Audio Mixing and Postpone Transcoding.

recordingConfig is a JSON object for configuring how the Cloud Recording service subscribes to the media streams in the channel. recordingConfig has the following fields:

• channelType: Number. The channel profile. Agora Cloud Recording must use the same channel profile as the Agora Video SDK. Otherwise, issues may occur.

  • 0: (Default) Communication profile.
  • 1: Live broadcast profile.

• streamTypes: (Optional) Number. The type of the media stream to subscribe to:

  • 0: Subscribes to audio streams only.
  • 1: Subscribes to video streams only.
  • 2: (Default) Subscribes to both audio and video streams.

• streamMode: (Optional) String. The output mode of the media stream in individual recording mode.

• default: Default mode. The Cloud Recording service transcodes the audio stream during recording and generates a M3U8 audio index file and a M3U8 video index file.

• standard: Standard mode. Agora recommends that you use this mode. The Cloud Recording service transcodes the audio stream during recording and generates a M3U8 audio index file, a M3U8 video index file and a combined M3U8 audio and video index file. If VP8 encoding is used on the web side, a combined MPD audio and video index file are generated. When using the standard mode to generate MPD files, the player compatibility is as follows:

  • macOS: Movist/Chrome (47.0.2526.111+)
  • Windows: Media Player/KM Player/VLC Player/Chrome (49.0.2623+)
  • Linux: FFplay

• original: Original encoding mode, which takes effect only when streamTypes is 0. The Cloud Recording service does not transcode the audio stream during recording and generates a M3U8 audio index file. The following table compares various aspects of the three modes of streamMode:

  streamMode	Description	Index file generated	Slice file generated	Video encoded	Audio encoded	Features supported
  default	Default mode.	One M3U8 audio index file and one M3U8 video index file are generated per user ID.	Multiple TS audio slice files and multiple TS video slice files are generated per user ID.	Does not transcode.	Transcodes.	Individual Recording, Capturing Screenshots, ApsaraVideo for VoD (VoD).
  standard	Standard mode.	One M3U8 audio index file, one M3U8 video index file, and one combined M3U8 audio and video index file are generated per user ID. If VP8 encoding is used on the web side, a combined MPD audio and video index file is generated per user ID.	Multiple TS audio slice files and multiple TS video slice files are generated per user ID.If VP8 encoding is used on the web side, multiple WebM audio slice files and multiple WebM video slice files are generated per user ID.	Does not transcode.	Transcodes.	Individual Recording and Capturing Screenshots.
  original	Original encoding mode, which takes effect only when streamTypes is 0.	One M3U8 audio index file is generated per user ID.	Multiple TS audio slice files per user ID.	Not applicable.	Does not transcode.	Individual Audio Non-transcoding Recording and Postpone Audio Mixing.

• decryptionMode: (Optional) Number. The decryption mode, which corresponds to the encryption mode set by the Agora Native/Web SDK. When the channel is encrypted, Agora Cloud Recording uses decryptionMode to enable the built-in decryption function.

  • 0: (Default) None.
  • 1: AES_128_XTS. 128-bit AES encryption, XTS mode.
  • 2: AES_128_ECB. 128-bit AES encryption, ECB mode.
  • 3: AES_256_XTS. 256-bit AES encryption, XTS mode.
  • 4: SM4_128_ECB. 128-bit SM4 encryption, ECB mode.
  • 5: AES_128_GCM. 128-bit AES encryption, GCM mode.
  • 6: AES_256_GCM. 256-bit AES encryption, GCM mode.
  • 7: AES_128_GCM2. 128-bit AES encryption, GCM mode. Compared to AES_128_GCM encryption mode, AES_128_GCM2 encryption mode is more secure and requires you to set the secret and salt.

• 8: AES_256_GCM2. 256-bit AES encryption, GCM mode. Compared to AES_256_GCM encryption mode, AES_256_GCM2 encryption mode is more secure and requires you to set the secret and salt.

• secret: (Optional) String. The decryption password when decryption mode is enabled. If decryptionMode is not 0, you need to set this value.

• salt: (Optional) Base64 encoding, 32-bit bytes. The decryption salt that needs to be set for the GCM2 encryption mode. If decryptionMode is 7 or 8, you need to set this value.

• audioProfile: (Optional) Number. The profile of the output audio stream, including the sample rate, bitrate, encoding mode, and the number of channels. You cannot set this parameter in individual recording mode.

  • 0: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
  • 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
  • 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.

• videoStreamType: (Optional) Number. The type of the video stream to subscribe to.

  • 0: (Default) Subscribes to the high-quality stream.
  • 1: Subscribes to the low-quality stream.

• maxIdleTime: (Optional) Number. Agora Cloud Recording automatically stops recording and leaves the channel when there is no user in the recording channel after a time period (30 seconds by default) set by this parameter. The value range is from 5 to 2,592,000 (30 days). Once the recording stops, the recording service generates new recorded files if you call start for the second time.

  • In a communication channel, the recording service does not recognize a channel as an idle channel, so long as the channel has users, regardless of whether they send stream or not.
  • If a live broadcast channel has an audience without a host for a set time (maxIdleTime), the recording service automatically stops and leaves the channel.

• transcodingConfig: (Optional) JSON. The video transcoding configuration. You cannot set this parameter in individual recording mode. If you set this parameter, ensure that you set width, height, fps, and bitrate. Refer to Set the Video Profile for detailed information about setting transcodingConfig.

  • width: Number. The width of the mixed video (pixels). The default value is 360. width should not exceed 1920, and width*height should not exceed 1920 * 1080; otherwise, an error occurs.
  • height: Number. The height of the mixed video (pixels). The default value is 640. height should not exceed 1920, and width*height should not exceed 1920 * 1080; otherwise, an error occurs.
  • fps: Number. The video frame rate (fps). The default value is 15.
  • bitrate: Number. The video bitrate (Kbps). The default value is 500.
  • maxResolutionUid: (Optional) String. When mixedVideoLayout is set as 2 (vertical layout), you can specify the user ID of the large video window by this parameter. It is a 32-bit unsigned integer within the range between 1 and (2³²-1).
  • mixedVideoLayout: (Optional) Number. The video mixing layout. 0, 1, and 2 are the predefined layouts. If you set this parameter as 3, you need to set the layout by the layoutConfig parameter.
    • 0: (Default) Floating layout. The first user in the channel occupies the full canvas. The other users occupy the small regions on top of the canvas, starting from the bottom left corner. The small regions are arranged in the order of the users joining the channel. This layout supports one full-size region and up to four rows of small regions on top with four regions per row, comprising 17 users.
    • 1: Best fit layout. This is a grid layout. The number of columns and rows and the grid size vary depending on the number of users in the channel. This layout supports up to 17 users.
    • 2: Vertical layout. One large region is displayed on the left edge of the canvas, and several smaller regions are displayed along the right edge of the canvas. The space on the right supports up to 2 columns of small regions with 8 regions per column. This layout supports up to 17 users. When mixedVideoLayout is set as 2, you can specify the user ID of the large video window by maxResolutionUid.
    • 3: Customized layout. Set the layoutConfig parameter to customize the layout.
  • backgroundColor: (Optional) String. The background color of the video canvas. Supports RGB color codes that start with a hashtag(#) followed by six hexadecimal numbers. The default value is "#000000", the black color.
  • backgroundImage: (Optional) String. The URL address of the background image of the video canvas. The display mode of the background image is cropped mode. In cropped mode, the recording service uniformly scales the image until it fills the visible boundaries (cropped). One dimension of the image may have clipped contents.
  • defaultUserBackgroundImage: (Optional) String. The URL address of the default background image of the user regions. After you set this parameter, the user region switches to the background image 3.5 seconds after a user stops sending the video stream; if you set a different background image for a specific user ID, this setting is overridden for that user ID.
  • layoutConfig: (Optional) JSONArray. An array of the configuration of each user's region. Supports 17 users at most. Each user's region configuration is a JSON object with the following parameters:
    • uid: (Optional) String. The string contains the user ID of the user displaying the video in the region. If this parameter is not specified, the configurations apply in the order of the users joining the channel.
    • x_axis: Float. The relative horizontal position of the top-left corner of the region. The value is between 0.0 (leftmost) and 1.0 (rightmost), and is accurate to six decimal places.
    • y_axis: Float. The relative vertical position of the top-left corner of the region. The value is between 0.0 (top) and 1.0 (bottom), and is accurate to six decimal places.
    • width: Float. The relative width of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.
    • height: Float. The relative height of the region. The value is between 0.0 and 1.0, and is accurate to six decimal places.
    • alpha: (Optional) Float. The transparency of the image. The value is between 0.0 (transparent) and 1.0 (opaque), and is accurate to six decimal places. The default value is 1.0.
    • render_mode: (Optional) Number. The video display mode:
      • 0: (Default) Cropped mode. Uniformly scales the video until it fills the visible boundaries (cropped). One dimension of the video may have clipped contents.
      • 1: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.
  • backgroundConfig: (Optional) JSONArray. The array contains the background configuration for specific user IDs.
    • uid: String. User ID (user ID).
    • image_url: String. The URL address of the background image of the user ID. After you set the background image, the user region switches to the background image 3.5 seconds after the user stops sending the video stream.
    • render_mode: (Optional) Number. The display mode.
      • 0: (Default) Cropped mode. Uniformly scales the image until it fills the visible boundaries (cropped). One dimension of the image may have clipped contents.
      • 1: Fit mode. Uniformly scales the video until one of its dimension fits the boundary (zoomed to fit). Areas that are not filled due to the disparity in the aspect ratio will be filled with black.

In the above background image settings, the URL supports the HTTP and HTTPS protocols, and the background image supports the JPG and BMP formats. The size of the image should not exceed 6MB. The settings take effect only after the recording service successfully downloads the picture. Settings may be overridden if their priorities are low. See Set the background color or background image for details.

• subscribeAudioUids: (Optional) JSONArray. An array of the user IDs (user IDs) of the users whose audio you want to subscribe. If you want to subscribe to all user IDs, you do not need to set this parameter. The length of the array should not exceed 32 user IDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 1. See Set up subscription lists for details.

• unSubscribeAudioUids: (Optional) JSONArray. An array of the user IDs (user IDs) of the users whose audio you do not want to subscribe. Once you set this parameter, the recording service subscribes to the audio of all user IDs except the specified ones. The length of the array should not exceed 32 user IDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 1. See Set up subscription lists for details.

• subscribeVideoUids: (Optional) JSONArray. An array of the user IDs (user IDs) of the users whose video you want to subscribe. If you want to subscribe to all user IDs, you do not need to set this parameter. The length of the array should not exceed 32 user IDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 0. See Set up subscription lists for details.

• unSubscribeVideoUids: (Optional) JSONArray. An array of the user IDs (user IDs) of the users whose video you do not want to subscribe. Once you set this parameter, the recording service subscribes to the video of all user IDs except the specified ones. The length of the array should not exceed 32 user IDs. Agora recommends that you do not set the array as empty. Once you set the parameter, do not set streamTypes in recordingConfig as 0. See Set up subscription lists for details.

If you set up a subscription list for audio, but not for video, then Agora Cloud Recording will not subscribe to any video streams. If you set up a subscription list for video, but not for audio, then Agora Cloud Recording will not subscribe to any audio streams.

• subscribeUidGroup: (Optional) Number. The estimated maximum number of subscribed users. You must set this parameter in individual mode. For example, if subscribeVideoUids is ["100","101","102"] and subscribeAudioUids is ["101","102","103"], the number of subscribed users is 4.

  • 0: 1 to 2 user IDs
  • 1: 3 to 7 user IDs
  • 2: 8 to 12 user IDs
  • 3: 13 to 17 user IDs

• 4: 17 to 32 user IDs

• 5: 32 to 49 user IDs

transcodeOptions is a JSON Object for configuring how the Cloud Recording service transcodes the recording files. It is applicable to Postpone Audio mixing and contains the following fields:

• container: (Optional) JSON, transcoding profile：
  • format: String. Format of output audio file. It can be set to mp3, m4a, or aac. The default value is mp3.
• transConfig: (Required) JSON. Transcoding configuration：
  • transMode: String. Transcoding mode. It can only be set to audioMix.
• audio: JSON. Audio profile of the output recording file:
  • sampleRate: String. Audio sample rate (Hz). It can be set to 48000, 32000, or 16000. The default value is 48000.
  • bitrate: String. Audio bitrate (Kbps). It can only be set to the default value of 48000.
  • channels: String. The number of channels. It can be set to 1 or 2. The default value is 2.

recordingFileConfig is a JSON Object for configuring recorded files. You cannot set both recordingFileConfig and snapshotConfig at the same time, otherwise an error will occur. recordingFileConfig includes the following fields:

avFileType: (Optional) JSONArray. An array of strings. Sets the format of the recorded files.

• "hls": (Default) M3U8 and TS files.
• "mp4": MP4 files. This value is for composite recording (mix) and web page recording (web) only. For composite recording, when the length of the recorded file reaches approximately 2 hours, or when the size of the file exceeds approximately 2 GB, the recording service automatically creates an additional MP4 file. For web page recording, when the length of the recorded file reaches maxVideoDuration, the recording service automatically creates an additional MP4 file.

You must set "mp4" together with "hls" (otherwise, the recording service returns error code 2). After the recording is over, you will get both MP4 and HLS files.

Agora supports only taking screenshots in a recording process or recording and taking screenshots in a recording process. snapshotConfig is a JSON object for configuring how Cloud Recording takes screenshots. Pay attention to the following parameters, as incorrect settings result in errors or failure to capture screenshots.

• In the URL of your request, mode must be individual.
• If you are recording and taking screenshots in a recording process, the recordingFileConfig parameter is required; if you are only taking screenshots in a recording process, you cannot set recordingFileConfig parameter.
• streamTypes must be 1 or 2.
• If you have set subscribeAudioUid, you must also set subscribeVideoUids.

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.

storageConfig is a JSON object that configures the third-party cloud storage with the following fields.

• vendor: Number. The third-party cloud storage vendor.

  • 0: Qiniu Cloud
  • 1: Amazon S3
  • 2: Alibaba Cloud
  • 3: Tencent Cloud
  • 4: Kingsoft Cloud
  • 5: Microsoft Azure
  • 6: Google Cloud
  • 7: Huawei Cloud
  • 8: Baidu AI Cloud

• region: Number. The region information specified for the third-party cloud storage. The recording service only supports regions in the following lists:

  In order to improve the success rate and real-time performance when uploading recording files, if you set the region of the cloud recording service in the acquire method, make sure that the region of the third-party cloud storage corresponds to the same geographical region. For example, if the region of the cloud recording service is set to NA (North America), the third-party cloud storage needs to be set to a location within North America.

  • Third-party cloud storage is Qiniu Cloud (vendor = 0):
    • 0: East China
    • 1: North China
    • 2: South China
    • 3: North America
    • 4: Southeast Asia
  • Third-party cloud storage is Amazon S3 (vendor = 1):
    • 0: US_EAST_1
    • 1: US_EAST_2
    • 2: US_WEST_1
    • 3: US_WEST_2
    • 4: EU_WEST_1
    • 5: EU_WEST_2
    • 6: EU_WEST_3
    • 7: EU_CENTRAL_1
    • 8: AP_SOUTHEAST_1
    • 9: AP_SOUTHEAST_2
    • 10: AP_NORTHEAST_1
    • 11: AP_NORTHEAST_2
    • 12: SA_EAST_1
    • 13: CA_CENTRAL_1
    • 14: AP_SOUTH_1
    • 15: CN_NORTH_1
    • 16: CN_NORTHWEST_1
    • 17: US_GOV_WEST_1
    • 20：AP_NORTHEAST_3
    • 21：EU_NORTH_1
    • 22：ME_SOUTH_1
    • 23：US_GOV_EAST_1
    • 24: AP_SOUTHEAST_3
    • 25: EU_SOUTH_1
    • 26: AWS_REGION_NUM
  • Third-party cloud storage is Alibaba Cloud (vendor = 2):
    • 0: CN_Hangzhou
    • 1: CN_Shanghai
    • 2: CN_Qingdao
    • 3: CN_Beijing
    • 4: CN_Zhangjiakou
    • 5: CN_Huhehaote
    • 6: CN_Shenzhen
    • 7: CN_Hongkong
    • 8: US_West_1
    • 9: US_East_1
    • 10: AP_Southeast_1
    • 11: AP_Southeast_2
    • 12: AP_Southeast_3
    • 13: AP_Southeast_5
    • 14: AP_Northeast_1
    • 15: AP_South_1
    • 16: EU_Central_1
    • 17: EU_West_1
    • 18: EU_East_1
    • 19：AP_Southeast_6
    • 20：CN_Heyuan
    • 21：CN_Guangzhou
    • 22：CN_Chengdu For details, see Alibaba Cloud Documentation.
  • Third-party cloud storage is Tencent Cloud (vendor = 3):
    • 0：AP_Beijing_1
    • 1：AP_Beijing
    • 2：AP_Shanghai
    • 3：AP_Guangzhou
    • 4：AP_Chengdu
    • 5：AP_Chongqing
    • 6：AP_Shenzhen_FSI
    • 7：AP_Shanghai_FSI
    • 8：AP_Beijing_FSI
    • 9：AP_Hongkong
    • 10：AP_Singapore
    • 11：AP_Mumbai
    • 12：AP_Seoul
    • 13：AP_Bangkok
    • 14：AP_Tokyo
    • 15：NA_Siliconvalley
    • 16：NA_Ashburn
    • 17：NA_Toronto
    • 18：EU_Frankfurt
    • 19：EU_Moscow
  • Third-party cloud storage is Kingsoft Cloud (vendor = 4):
    • 0：CN_Hangzhou
    • 1：CN_Shanghai
    • 2：CN_Qingdao
    • 3：CN_Beijing
    • 4：CN_Guangzhou
    • 5：CN_Hongkong
    • 6：JR_Beijing
    • 7：JR_Shanghai
    • 8：NA_Russia_1
    • 9：NA_Singapore_1
  • Third-party cloud storage is Microsoft Azure (vendor = 5), the region parameter has no effect, if it is set or not.
  • Third-party cloud storage is Google Cloud (vendor = 6), the region parameter has no effect, if it is set or not.
  • Third-party cloud storage is Huawei Cloud (vendor = 7):
    • 0：CN_North_1
    • 1：CN_North_4
    • 2：CN_East_2
    • 3：CN_East_3
    • 4：CN_South_1
    • 5：CN_Southwest_2
    • 6：AP_Southeast_1
    • 7：AP_Southeast_2
    • 8：AP_Southeast_3
    • 9：AF_South_1
    • 10：SA_Argentina_1
    • 11：SA_Peru_1
    • 12：NA_Mexico_1
    • 13：SA_Brazil_1
    • 14：LA_South_2
    • 15：SA_Chile_1
  • Third-party cloud storage is Huawei Cloud (vendor = 7):
    • 0：CN_North_1
    • 1：CN_North_4
    • 2：CN_East_2
    • 3：CN_East_3
    • 4：CN_South_1
    • 5：CN_Southwest_2
    • 6：AP_Southeast_1
    • 7：AP_Southeast_2
    • 8：AP_Southeast_3
    • 9：AF_South_1
    • 10：SA_Argentina_1
    • 11：SA_Peru_1
    • 12：NA_Mexico_1
    • 13：SA_Brazil_1
    • 14：LA_South_2
    • 15：SA_Chile_1
  • Third-party cloud storage is Baidu AI Cloud (vendor = 8):
    • 0：Beijing
    • 1：Baoding
    • 2：Suzhou
    • 3：Guangzhou
    • 4：Hongkong
    • 5：Singapore
    • 6：Wuhan
    • 7：Shanghai

• bucket: String. The bucket name of the third-party cloud storage.

• accessKey: String. The access key of the third-party cloud storage. Agora suggests that you use a write-only access key.

• secretKey: String. The secret key of the third-party cloud storage.

• fileNamePrefix: (Optional) JSONArray. An array of strings. Sets the path of the recorded files in the third-party cloud storage. For example, if fileNamePrefix = ["directory1","directory2"], Agora Cloud Recording will add the prefix "directory1/directory2/" before the name of the recorded file, that is, directory1/directory2/xxx.m3u8. The prefix's length, including the slashes, should not exceed 128 characters. The string itself should not contain symbols such as slash, underscore, or parenthesis. The supported characters are as follows:

  • The 26 lowercase English letters: a to z
  • The 26 uppercase English letters: A to Z
  • The 10 numbers: 0 to 9

• extensionParams: (Optional) JSON Object. The third-party cloud storage service encrypts and labels the uploaded recording files according to extensionParams, which contains the following fields:

  • sse：Encryption mode. The third-party cloud storage service encrypts the uploaded recording file according to the encryption mode. This field is only applicable to Amazon S3. See official Amazon S3 documentation for details. It can be set to:
    • kms: KMS encryption.
    • aes256: AES256 encryption.
  • tag: Tag content. The third-party cloud storage service tags the uploaded recording file according to the tag content. This field is only applicable to Alibaba Cloud and Amazon S3. See Alibaba Cloud official documentation and Amazon S3 official documentation for details.

extensionServiceConfig is a JSON Object for extension service configurations. Extension services are a collection of applications that process the media streams generated from the Agora Video SDK. One example extension service is VoD service.

extensionServiceConfig has the following fields:

• errorHandlePolicy: (Optional) String. Error handling policy. You can only set it to the default value, "error_abort", which means that once an error occurs to an extension service, all other non-extension services, such as stream subscription, also stop.
• apiVersion: (Optional) String. The version of the Cloud Recording RESTful API. The default value is "v1".
• extensionServices: JSONArray. An array of the configuration for each extension service.

Currently you cannot configure more than one extension service per recording session.

ApsaraVideo for VoD When using ApsaraVideo for VoD, extensionServicesextensionServices includes the following fields:

• serviceName: String. The name of the extension service. To use ApsaraVideo for VoD, set it as "aliyun_vod_service".
• errorHandlePolicy: (Optional) String. Error handling policy. You can only set it to the default value, "error_abort", which means that if an error occurs to the current extension service, other extension services also stop.
  • serviceParam: JSON. Configurations for an extension service. To use ApsaraVideo for VoD, configure as follows:
  • accessKey: String. Corresponds to the AccessKeyId in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.
  • secretKey: String. Corresponds to the AccessKeySecret in the AccessKey of Alibaba Cloud. For details, see Alibaba Cloud's documentation.
  • regionId: String. The service region. For details, see Alibaba Cloud's documentation.
  • apiData: JSON. Configurations for ApsaraVideo for VoD.
    • videoData: JSON. Video configurations. See Alibaba Cloud's documentation for details about the following parameters:
      • title: String. The title of the video.
      • description: (Optional) String. The description of the video.
      • coverUrl: (Optional) String. The URL of the custom video thumbnail.
      • cateId: (Optional) String. The ID of the video category. The ID must be an integer.
      • tags: (Optional) String. The tags of the video.
      • templateGroupId: (Optional) String. The ID of the transcoding template group.
      • userData: (Optional) String. The custom configurations.
      • storageLocation: (Optional) String. The bucket.
      • workflowId: (Optional) String. The ID of the workflow.

Currently only composite recording is supported.

Web page recording When using web page recording, extensionServices includes the following fields:

• serviceName: String. The name of the extension service. To use web page recording, set it as "web_recorder_service".
• errorHandlePolicy: (Optional) String. Error handling policy. Currently you can only set it to the default value, "error_abort", which means that if an error occurs to the current extension service, other extension services also stop.
• serviceParam: JSON. Configurations for an extension service. To use web page recording, configure as follows:
• url：String. Sets the address of the web page to record.
• videoBitrate：(Optional) Number. Sets the bitrate of the video (Kbps). The value range is [50,8000]. The default value of videoBitrate varies according to the resolution of the output video:
  • If the resolution of the output video is greater than or equal to 1280 × 720, the default value of videoBitrate is 2000.
  • If the resolution of the output video is less than 1280 × 720, the default value of videoBitrate is 1500.
• videoFps: (Optional)Number. Sets the frame rate of the video (fps). The value range is [5,60]. The default value is 15.
• audioProfile：Number. Sets the sample rate, encoding mode, number of audio channels, and bitrate.
  • 0: (Default) Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 48 Kbps.
  • 1: Sample rate of 48 kHz, music encoding, mono, and a bitrate of up to 128 Kbps.
  • 2: Sample rate of 48 kHz, music encoding, stereo, and a bitrate of up to 192 Kbps.
• videoWidth：Number. Sets the width of the video (pixels). The value range is [480,1920]. The product of videoWidth and videoHeight should not exceed 2,073,600 (1920 × 1080).
• videoHeight：Number. Sets the height of the video (pixels). The value range is [480,1920]. The product of videoWidth and videoHeight should not exceed 2,073,600 (1920 × 1080).
• maxRecordingHour: Number. Sets the maximum recording length (hours). If the limit is exceeded, the recording stops automatically. The value range is [1,720]. Agora recommend that you set a value smaller than the value of resourceExpiredHour specified in the acquire method. The charging will continue until the web page recording stops. You should set a reasonable maxRecordingHour based on the actual business scenario or actively stop the web page recording.
  • maxVideoDuration: (Optional) Number. Sets the maximum duration (in minutes) of the MP4 slice file generated by the web page recording. The value range is [30,240], and the default value is 120 minutes. During a web page recording, when the length of the recorded file reaches around maxVideoDuration, the recording service creates another MP4 slice file.
  • onhold: (Optional) Bool. Sets whether to pause the web page recording when starting the web page recording task.
  • true：Pauses the web page recording when starting the web page recording task. After the web page recording task is started, the web page recording is paused immediately. The recording service opens and renders the page to be recorded, but does not generate a slice file.
  • (Default) false: Starts the web page recording task and continue web page recording.

Agora recommends that you use the onhold parameter as follows: When calling the start method, set the onhold parameter to true, start and pause the web page recording, determine the appropriate time to start the web page recording, and call the update method and set the onhold parameter to false to continue the web page recording. If you need to continuously call the update method to pause or resume page recording, call it after receiving the last HTTP response of update; otherwise the actual result may be inconsistent with your expectation.

• readyTimeout: (optional) Number. Sets the web page loading timeout limit, in seconds.The value range is [0,60].
• 0 or null, which means the web page loading status is not detected.
• An integer greater than or equal to 1, which sets the web page load timeout limit. If you set readyTimeout to less than 0 or a non-integer, an error code 2 is received.

Push media stream to the CDN during a web page recording When pushing media stream to the CDN during a web page recording, extensionServices includes fields of web page recording and streaming. The fields of streaming are as follows:

• serviceName: String. The name of the extension service. To use web page recording, set it as "rtmp_publish_service".
• errorHandlePolicy: (Optional) String. Error handling policy. Currently you can only set it to the default value, "error_ignore", which means that if an error occurs to the current extension service, other extension services are not affected.
• serviceParam: JSON. Configurations for an extension service. To push media stream to the CDN during a web page recording, configure as follows:
• outputs：JSON Array. Configure as follows:
  • rtmpUrl：String. The CDN address which you want to push stream to.

• The request URL is：

_1

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

• Content-type is application/json;charset=utf-8.
• Authorization is basic HTTP authentication, see RESTful API authentication for details.
• The request body:

_50

{

_50

"uid": "527841",

_50

"cname": "httpClient463224",

_50

"clientRequest": {

_50

"token": "<token>",

_50

"recordingConfig": {

_50

"maxIdleTime": 30,

_50

"streamMode": "default",

_50

"streamTypes": 2,

_50

"channelType": 0,

_50

"transcodingConfig": {

_50

"height": 640,

_50

"width": 360,

_50

"bitrate": 500,

_50

"fps": 15,

_50

"mixedVideoLayout": 1,

_50

"backgroundColor": "#FF0000"

_50

},

_50

"subscribeVideoUids": [

_50

"123",

_50

"456"

_50

],

_50

"subscribeAudioUids": [

_50

"123",

_50

"456"

_50

],

_50

"subscribeUidGroup": 0

_50

},

_50

"recordingFileConfig": {

_50

"avFileType": [

_50

"hls"

_50

]

_50

},

_50

"storageConfig": {

_50

"accessKey": "xxxxxxf",

_50

"region": 3,

_50

"bucket": "xxxxx",

_50

"secretKey": "xxxxx",

_50

"vendor": 2,

_50

"fileNamePrefix": [

_50

"directory1",

_50

"directory2"

_50

]

_50

"extensionParams": {

_50

"tag":"xxxxxx",

_50

"sse":"kms"

_50

}

_50

}

_50

}

_50

}

_32

{

_32

"uid": "527841",

_32

"cname": "httpClient463224",

_32

"clientRequest": {

_32

"token": "<token>",

_32

"recordingConfig": {

_32

"maxIdleTime": 30,

_32

"streamTypes": 2,

_32

"channelType": 0,

_32

"subscribeUidGroup": 0

_32

},

_32

"extensionServiceConfig": {

_32

"extensionServices": [

_32

{

_32

"serviceName": "aliyun_vod_service",

_32

"serviceParam": {

_32

"secretKey": "xxxxxx",

_32

"accessKey": "xxxxxx",

_32

"regionId": "cn-shanghai",

_32

"apiData": {

_32

"videoData": {

_32

"title": "My Video",

_32

"description": "This is my first video",

_32

"coverUrl": "http://xxxxx"

_32

}

_32

}

_32

}

_32

}

_32

]

_32

}

_32

}

_32

}

_30

{

_30

"uid": "527841",

_30

"cname": "httpClient463224",

_30

"clientRequest": {

_30

"token": "<token>",

_30

"recordingConfig": {

_30

"maxIdleTime": 30,

_30

"streamTypes": 2,

_30

"channelType": 0,

_30

"subscribeUidGroup": 0

_30

},

_30

"snapshotConfig": {

_30

"captureInterval": 5,

_30

"fileType": [

_30

"jpg"

_30

]

_30

},

_30

"storageConfig": {

_30

"accessKey": "xxxxxxf",

_30

"region": 3,

_30

"bucket": "xxxxx",

_30

"secretKey": "xxxxx",

_30

"vendor": 2,

_30

"fileNamePrefix": [

_30

"directory1",

_30

"directory2"

_30

]

_30

}

_30

}

_30

}

_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

}

_41

{

_41

"cname": "httpClient463224",

_41

"uid": "527841",

_41

"clientRequest": {

_41

"token": "<token>",

_41

"extensionServiceConfig": {

_41

"errorHandlePolicy": "error_abort",

_41

"extensionServices": [

_41

{

_41

"serviceName": "web_recorder_service",

_41

"errorHandlePolicy": "error_abort",

_41

"serviceParam": {

_41

"url": "https://xxxxx",

_41

"audioProfile": 0,

_41

"videoWidth": 1280,

_41

"videoHeight": 720,

_41

"maxRecordingHour": 3,

_41

"maxVideoDuration": 200

_41

}

_41

}

_41

]

_41

},

_41

"recordingFileConfig": {

_41

"avFileType": [

_41

"hls",

_41

"mp4"

_41

]

_41

},

_41

"storageConfig": {

_41

"vendor": 2,

_41

"region": 3,

_41

"bucket": "xxxxx",

_41

"accessKey": "xxxxx",

_41

"secretKey": "xxxxx",

_41

"fileNamePrefix": [

_41

"directory1",

_41

"directory2"

_41

]

_41

}

_41

}

_41

}

_51

{

_51

"cname": "httpClient463224",

_51

"uid": "527841",

_51

"clientRequest": {

_51

"token": "<token>",

_51

"extensionServiceConfig": {

_51

"extensionServices": [

_51

{

_51

"serviceName": "web_recorder_service",

_51

"errorHandlePolicy": "error_abort",

_51

"serviceParam": {

_51

"url": "https://xxxxx",

_51

"audioProfile": 0,

_51

"videoWidth": 1280,

_51

"videoHeight": 720,

_51

"maxRecordingHour": 3,

_51

"maxVideoDuration": 200

_51

}

_51

},

_51

{

_51

"serviceName": "rtmp_publish_service",

_51

"errorHandlePolicy": "error_ignore",

_51

"serviceParam": {

_51

"outputs": [

_51

{

_51

"rtmpUrl": "rtmp://xxx"

_51

}

_51

]

_51

}

_51

}

_51

]

_51

},

_51

"recordingFileConfig": {

_51

"avFileType": [

_51

"hls",

_51

"mp4"

_51

]

_51

},

_51

"storageConfig": {

_51

"vendor": 2,

_51

"region": 3,

_51

"bucket": "xxxxx",

_51

"accessKey": "xxxxx",

_51

"secretKey": "xxxxx",

_51

"fileNamePrefix": [

_51

"directory1",

_51

"directory2"

_51

]

_51

}

_51

}

_51

}

_24

{

_24

"uid": "527841",

_24

"cname": "httpClient463224",

_24

"clientRequest": {

_24

"token": "<token if any>",

_24

"recordingConfig": {

_24

"maxIdleTime": 30,

_24

"streamTypes": 0,

_24

"streamMode": "original",

_24

"channelType": 0,

_24

"videoStreamType": 0,

_24

"subscribeAudioUids": ["123","456"],

_24

"subscribeUidGroup": 0

_24

},

_24

"storageConfig": {

_24

"accessKey": "xxxxx",

_24

"region": 3,

_24

"bucket": "xxxxx",

_24

"secretKey": "xxxxx",

_24

"vendor": 2,

_24

"fileNamePrefix": ["directory1","directory2"]

_24

}

_24

}

_24

}

_46

{

_46

"uid": "527841",

_46

"cname": "httpClient463224",

_46

"clientRequest": {

_46

"appsCollection": {

_46

"combinationPolicy": "postpone_transcoding"

_46

},

_46

"token": "<token if any>",

_46

"recordingConfig": {

_46

"maxIdleTime": 30,

_46

"streamTypes": 0,

_46

"streamMode": "original",

_46

"channelType": 0,

_46

"videoStreamType": 0,

_46

"subscribeAudioUids": [

_46

"123",

_46

"456"

_46

],

_46

"subscribeUidGroup": 0

_46

},

_46

"transcodeOptions": {

_46

"container": {

_46

"format": "m4a"

_46

},

_46

"transConfig": {

_46

"transMode": "audioMix"

_46

},

_46

"audio": {

_46

"sampleRate": "xxxx",

_46

"bitrate": "xxxx",

_46

"channels": "xxxx"

_46

}

_46

},

_46

"storageConfig": {

_46

"accessKey": "xxxxx",

_46

"region": 3,

_46

"bucket": "xxxxx",

_46

"secretKey": "xxxxx",

_46

"vendor": 2,

_46

"fileNamePrefix": [

_46

"directory1",

_46

"directory2"

_46

]

_46

}

_46

}

_46

}

_36

{

_36

"uid": "527841",

_36

"cname": "httpClient463224",

_36

"clientRequest": {

_36

"token": "",

_36

"appsCollection": {

_36

"combinationPolicy": "postpone_transcoding"

_36

},

_36

"recordingConfig": {

_36

"maxIdleTime": 30,

_36

"streamTypes": 2,

_36

"channelType": 0,

_36

"videoStreamType": 1,

_36

"subscribeVideoUids": [

_36

"123",

_36

"456"

_36

],

_36

"subscribeAudioUids": [

_36

"123",

_36

"456"

_36

],

_36

"subscribeUidGroup": 0

_36

},

_36

"storageConfig": {

_36

"accessKey": "xxxxxxf",

_36

"region": 3,

_36

"bucket": "xxxxx",

_36

"secretKey": "xxxxx",

_36

"vendor": 2,

_36

"fileNamePrefix": [

_36

"directory1",

_36

"directory2"

_36

]

_36

}

_36

}

_36

}

If the returned HTTP status code is 200, it means the request was successful, and the response body contains the following fields:

• code: Number. Status code.
• resourceId: String. The resource ID for cloud recording. The resource ID is valid for five minutes.
• sid: String. The recording ID. The unique identification of the current recording.

_6

"Code": 200,

_6

"Body":

_6

{

_6

"sid": "38f8e3cfdc474cd56fc1ceba380d7e1a",

_6

"resourceId": "JyvK8nXHuV1BE64GDkAaBGEscvtHW7v8BrQoRPCHxmeVxwY22-x-kv4GdPcjZeMzoCBUCOr9q-k6wBWMC7SaAkZ_4nO3JLqYwM1bL1n6wKnnD9EC9waxJboci9KUz2WZ4YJrmcJmA7xWkzs_L3AnNwdtcI1kr_u1cWFmi9BWAWAlNd7S7gfoGuH0tGi6CNaOomvr7-ILjPXdCYwgty1hwT6tbAuaW1eqR0kOYTO0Z1SobpBxu1czSFh1GbzGvTZG"

_6

}