Configuring Recording Callback

Updated on 2023-10-16 GMT+08:00

View PDF

You can configure an HTTP/HTTPS URL to receive recording task status callback. SparkRTC will send POST requests to your server, so that you can know the recording task status.

Callback Protocols

Request: HTTP POST. The request body is in JSON format.
Response: HTTP STATUS CODE = 200. The response body is in JSON format. You can customize the response body.
Example:
```
{ 
  "status": 1, 
  "result" : "success" 
}
```

Prerequisites

You have created an app.

Procedure

Log in to the SparkRTC console.
In the navigation pane, choose Apps.
Click Configure in the row of the app for which a recording callback needs to be created.

The Configuration page is displayed.
In the Recording Callback area, click Edit and configure callback information, as shown in Figure 1.

Figure 1 Adding a callback URL
- Callback URL: address of the server that receives callback information. Only the HTTP and HTTPS protocols are supported.
- Private Key: authentication key for recording callback. The key can contain 32 to 64 characters. For details about how to generate a recording callback authentication signature, see "How Do I Authenticate a Recording Callback?" in FAQs.

Callback Example

Table 1 describes the fields in a callback message body.

{
  "event_type": "RECORD_FILE_COMPLETE",
  "stream_name": "mystream",
  "record_format": "HLS",
  "download_url": "https://abc-rtc-bucket2.obs.cn-north-4.myhuaweicloud.com/Record/Record/5fcdf5651xxxxxx6f835d0d4.SparkRTC.myhuaweicloud.com/live/continuous_record/hls/mystream_2021-04-28-08-57-07/mystream_2021-04-28-08-57-07.m3u8",
  "file_size": 26254952,
  "record_duration": 65,
  "start_time": "2021-04-28T08:56:57Z",
  "end_time": "2021-04-28T08:58:02Z",
  "width": 1280,
  "height": 720,
  "obs_location": "http://obs.cn-north-4.myhuaweicloud.com",
  "obs_bucket": "abc-rtc-bucket2",
  "obs_object": "Record/Record/5fcdf5651xxxxxx6f835d0d4.SparkRTC.myhuaweicloud.com/live/continuous_record/hls/mystream_2021-04-28-08-57-07/mystream_2021-04-28-08-57-07.m3u8",
  "app_id": "5fcdf5651xxxxxx6f835d0d4",
  "job_id": "608196a2fa1xxxxxx515147f32ef463b",
  "room_id": "room01"
}

**Table 1** JSON message body
Field	Description
event_type	Notification event type. Values: RECORD_NEW_FILE_START. This event is triggered in either of the following scenarios: The system starts creating the first recording file. When a stream is resumed, if Max Stream Pause Length is set to Generate a new file when a stream is paused, the system starts creating another recording file. If the current recording duration exceeds the configured recording length, the system starts creating another recording file. RECORD_FILE_COMPLETE. This event is triggered in either of the following scenarios: When the recording duration reaches the configured recording length, the current recording file recording is complete and the system starts creating another recording file. When a stream is interrupted, if Max Stream Pause Length is set to Generate a new file when a stream is paused, the current recording file recording is complete.
stream_name	Stream name.
record_format	Recording format, which can be HLS and MP4.
download_url	URL for downloading the recording. This field is used only when event_type is RECORD_FILE_COMPLETE. NOTE: The address cannot be used for playback.
file_size	File size. Unit: byte.
record_duration	Duration of a recording. Unit: second. This field is used only when event_type is RECORD_FILE_COMPLETE.
start_time	UTC time when the recording starts, which is, time when the first frame is received. The format is YYYY-MM-DDThh:mm:ssZ. This field is used only when event_type is RECORD_FILE_COMPLETE.
end_time	UTC time when the recording ends. The format is YYYY-MM-DDThh:mm:ssZ. This field is used only when event_type is RECORD_FILE_COMPLETE.
width	Width of the recording. This field is used only when event_type is RECORD_FILE_COMPLETE.
height	Height of the recording. This field is used only when event_type is RECORD_FILE_COMPLETE.
obs_location	Region where the OBS bucket for storing the recording is located. This field is used only when event_type is RECORD_FILE_COMPLETE.
obs_bucket	OBS bucket where the recording is stored. This field is used only when event_type is RECORD_FILE_COMPLETE.
obs_object	OBS storage path. This field is used only when event_type is RECORD_FILE_COMPLETE.
app_id	App ID.
job_id	Recording task ID, which can be used to modify, view, or stop the task.
room_id	Room ID.
detail_message	Recording task status description.