Skip to main content

Standard recording post-processing

Standard recording supports creating clips and snapshots out of a video recording file, as well as querying the existing recording files for a live stream.

Create a clip

Cuts out a specific part of a video recording of a live stream and generates an M3U8 file.

HTTP request


_1
POST https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/admin/record/standard/regions/{region}/cutting/{stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.
regionStringRequired. The area corresponding to the video recording.
stream_nameStringRequired. The stream name.

Request body

The request body is in the JSON Object type and contains the following fields:

FieldTypeDescription
startTimeStringRequired. The starting time of the clip on the video recording's timeline, in the RFC3339 format, for example, 2019-01-07T12:00:00+08:00.
endTimeStringOptional. The ending time of the clip on the video recording's timeline, in the RFC3339 format, for example, 2019-01-07T12:30:00+08:00. This value cannot exceed the current time. If empty, this field is set as the time when the latest recording file was created.
fileNameStringRequired. The name of the generated M3U8 file. This field must be unique.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
POST https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/admin/record/standard/regions/{region}/cutting/{stream_name} HTTP/1.1

Request body


_5
{
_5
"startTime": "2019-01-07T12:00:00+08:00",
_5
"endTime": "2019-01-07T12:30:00+08:00",
_5
"fileName": "test.m3u8"
_5
}

Response line


_1
HTTP/1.1 200 OK

Create a snapshot

Takes a snapshot from a video recording of a live stream and generates a JPEG file.

HTTP request


_1
POST https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/admin/record/standard/regions/{region}/snapshot/{stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.
regionStringRequired. The area corresponding to the video recording.
stream_nameStringRequired. The stream name.

Request body

The request body is in the JSON Object type and contains the following fields:

FieldTypeDescription
timeStringOptional. The time on the video recording's timeline when the snapshot is taken, in the RFC3339 format, for example, 2019-01-07T12:00:00+08:00. This value cannot exceed the current time. If empty, this field is set as the time when the latest recording file was created.
fileNameStringRequired. The name of the generated JPEG file. This field must be unique.

HTTP response

If the returned HTTP status code is 200, the request is successful.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
POST https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/admin/record/standard/regions/{region}/snapshot/{stream_name} HTTP/1.1

Request body


_4
{
_4
"time": "2019-01-07T12:30:00+08:00",
_4
"fileName": "test.jpg"
_4
}

Response line


_1
HTTP/1.1 200 OK

List recording files

Lists the recording files for the specified live stream within a time range.

HTTP request


_1
GET https://api.agora.io/v1/projects/{appid}/fls/entry_points/{entry_point}/admin/record/standard/regions/{region}/preview_list?start_time={start_time}&end_time={end_time}&stream_name={stream_name}

Path parameter

ParameterTypeDescription
appidStringRequired. The App ID retrieved from Agora Console.
entry_pointStringRequired. The entry point name.
regionStringRequired. The area corresponding to the video recording.

Query parameter

ParameterTypeDescription
start_timeStringRequired. The starting point of the time range to query recording files, in the RFC3339 format. For example, 2019-01-07T12:00:00Z.
end_timeStringRequired. The end point of the time range to query recording files, in the RFC3339 format. For example, 2019-01-07T12:00:00Z.
stream_nameStringRequired. The stream name.

HTTP response

If the returned HTTP status code is 200, the request is successful. The response body contains the following fields:

list:JSON Array. The list of recording files, in ascending order of the time when the recording starts. Each recording attempt corresponds to a JSON Object and contains the following fields:

  • startTime:String. The start time of the recording in the RFC3339 format, for example "2019-01-07T12:00:00Z".
  • endTime:String. The end time of the recording in the RFC3339 format, for example"2019-01-07T12:00:00Z".
  • fileName:String. The path to the recording file.
  • position:Integer. The time offset (in seconds) from startTime to the playback position.

If the returned HTTP status code is not 200, the request fails. You can refer to the HTTP status codes for possible reasons.

Example

Request line


_1
GET https://api.agora.io/v1/projects/{your_appid}/fls/entry_points/live/admin/record/standard/regions/{region}/preview_list?start_time={start_time}&end_time={end_time}&stream_name={stream_name} HTTP/1.1

Response line


_1
HTTP/1.1 200 OK

Request body


_16
{
_16
"list": [
_16
{
_16
"fileName": "record/{entry_point}/{stream_name}/{m3u8_file_name}",
_16
"startTime": "2021-08-25T10:44:40+08:00",
_16
"endTime": "2021-08-25T11:01:49+08:00",
_16
"position": 3
_16
},
_16
{
_16
"fileName": "record/{entry_point}/{stream_name}/{m3u8_file_name}",
_16
"startTime": "2021-08-25T12:19:23+08:00",
_16
"endTime": "2021-08-25T14:42:58+08:00",
_16
"position": 2
_16
}
_16
]
_16
}

HTTP status codes

Status codeDescription
200The request succeeds.
400The parameter is invalid, for example the appid or the entry_point is empty, or the region parameter value is invalid.
401Unauthorized (the customer ID and the customer secret do not match).
404The server cannot find the resource according to the request, which means the requested entry point does not exist or the requested URI path is invalid.
500An internal error occurs in the server, so the server is not able to complete the request.
504An internal error occurs in the server. The gateway or the proxy server did not receive a timely request from the remote server.