Creating a Video Recording Index

Function

A recording index is a TS file recorded in HLS video streams. A new M3U8 file is generated based on the specified time range.

Constraints

In the recording configuration, the recording format must contain HLS, and the record_ts_prefix parameter must be set to the default value {file_start_time_unix}{file_end_time_unix}{ts_sequence_number}. There must be streams that are successfully pushed in the requested time range. The recording files involved in the same request must be in the same OBS bucket. A recording index can be created only when its start time is within 30 days later than the current time. If the duration of the request time segment is shorter than the TS segment duration in the HLS recording configuration, the TS segment that overlaps the request time segment is returned and the TS file is not tailored. If the interval between the request time and the start time in the request is less than the duration of a TS segment, the request may fail because the TS segment recording is not complete.

Calling Method

For details, see Calling APIs.

URI

POST /v1/{project_id}/record/indexes

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	No	String	User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is a token.
Authorization	No	String	Authentication information. This parameter is mandatory for AK/SK authentication.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory for AK/SK authentication.
X-Project-Id	No	String	Project ID. This parameter is mandatory for AK/SK authentication.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
publish_domain	Yes	String	Ingest domain name
app	Yes	String	App name
stream	Yes	String	Stream name
start_time	Yes	String	Start time. The format is YYYY-MM-DDTHH:mm:ssZ (UTC time). The maximum interval between the start time and end time is 12 hours. The start time cannot be later than the current time.
end_time	Yes	String	End time. The format is YYYY-MM-DDTHH:mm:ssZ (UTC time). The maximum interval between the start time and end time is 12 hours. The start time must be earlier than the end time.
object	No	String	Path for storing M3U8 files in an OBS bucket. The following strings can be escaped: - {publish_domain} - {app} - {stream} - {start_time} - {end_time} - {start_time_unix} - {end_time_unix}, where {start_time}, {end_time}, {start_time_unix}, and {end_time_unix} indicate the actual time when the result is returned. The default value is Index/{publish_domain}/{app}/{stream}/{stream}-{start_time}-{end_time}.

Response Parameters

Status code: 201

**Table 4** Response header parameters
Parameter	Type	Description
X-request-id	String	Request ID for task tracing. Format: request_id-timestamp-hostname. (request_id is the UUID generated on the server. timestamp is the current timestamp, and hostname is the name of the server that processes the current request.)

**Table 5** Response body parameters
Parameter	Type	Description
index_url	String	Index file address
publish_domain	String	Ingest domain name
app	String	App name
stream	String	Stream name
start_time	String	Start time. The format is yyyy-MM-ddTHH:mm:ssZ (UTC time). (Actual video start time)
end_time	String	End time. The format is yyyy-MM-ddTHH:mm:ssZ (UTC time). (Actual video end time)
duration	Integer	Recording duration Unit: second
width	Integer	Video width.
height	Integer	Video height
location	String	ID of the region where the OBS bucket resides
bucket	String	Bucket name
object	String	M3U8 file path, which defaults to Index/{publish_domain}/{app}/{stream}-{start_time}-{end_time}

Status code: 400

**Table 6** Response header parameters
Parameter	Type	Description
X-request-id	String	Request ID for task tracing. Format: request_id-timestamp-hostname. (request_id is the UUID generated on the server. timestamp is the current timestamp, and hostname is the name of the server that processes the current request.)

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Error Code
error_msg	String	Error description

Example Requests

Creates a video recording index.

POST https://{endpoint}/v1/{project_id}/record/indexes

{
  "publish_domain" : "push.example.com",
  "app" : "live",
  "stream" : "index",
  "start_time" : "2022-07-25T16:20:00+08:00",
  "end_time" : "2022-07-25T16:30:00+08:00",
  "object" : "Index/{publish_domain}/{app}/{stream}/{stream}-{start_time}-{end_time}"
}

Example Responses

Status code: 201

Creation of the video recording index succeeded.

{
  "index_url" : "http://obs***.com/push.test.com/live/stream01-20220901000000-20220901001000.m3u8",
  "duration" : 600,
  "height" : 1080,
  "width" : 720,
  "publish_domain" : "push.test.com",
  "app" : "live",
  "stream" : "stream01",
  "start_time" : "2022-09-01T00:00:00Z",
  "end_time" : "2022-09-01T00:10:00Z",
  "bucket" : "obs_bucket_name",
  "location" : "cn-north-5",
  "object" : "push.test.com/live/stream01-20220901000000-20220901001000.m3u8"
}

Status code: 400

Create a video recording index failed. Common errors:

illegal time range: The request time range is incorrect. Check the start_time and end_time.
no record info found: No recording task is found in the request time segment. The possible cause is that no livestream is successfully pushed in the time segment or command recording is not started under the command recording rule.
no ts info found: No TS file is found in the request time segment. The possible cause is that stream interruption occurs in the request time segment or the TS segment recording is not complete when the request is sent.

{
  "error_code" : "LIVE.100011001",
  "error_msg" : "Parameter verification failed."
}

Status Codes

Status Code	Description
201	Creation of the video recording index succeeded.
400	Create a video recording index failed. Common errors: illegal time range: The request time range is incorrect. Check the start_time and end_time. no record info found: No recording task is found in the request time segment. The possible cause is that no livestream is successfully pushed in the time segment or command recording is not started under the command recording rule. no ts info found: No TS file is found in the request time segment. The possible cause is that stream interruption occurs in the request time segment or the TS segment recording is not complete when the request is sent.

Status Code

Description

201

Creation of the video recording index succeeded.

400

Create a video recording index failed. Common errors:

illegal time range: The request time range is incorrect. Check the start_time and end_time.
no record info found: No recording task is found in the request time segment. The possible cause is that no livestream is successfully pushed in the time segment or command recording is not started under the command recording rule.
no ts info found: No TS file is found in the request time segment. The possible cause is that stream interruption occurs in the request time segment or the TS segment recording is not complete when the request is sent.