Live Recording

This guide explains how to configure, automate, control, and monitor live stream recordings on Media Acceleration Live Broadcast by using the Recording API.

How the APIs fit together

The recording workflow has four parts:

1. Recording parameter templates define how to record, including the storage destination, output format, file naming, segmentation, retention, and callback settings.
2. Recording rules define when to record by associating a template with matching live streams.
3. Real-time controls start or stop an on-demand recording for an active stream.
4. Task queries track recording status and return information about generated files.

Templates are the foundation. Both recording rules and on-demand recordings require a templateId, so create at least one template before using those APIs.

All recording APIs share a rate limit of 300 requests per 5 minutes per user. Design retries and polling intervals so your integration stays within this limit.

Typical recording workflow

1. Create a recording parameter template and save its templateId.
2. Choose how recording starts:
   • Create a recording rule for automatic recording.
   • Call StartRealTimeRecord for an on-demand recording.
3. Save the identifiers returned by the API, especially each recording task’s persistentId.
4. Use ListRecordings to find recording tasks within a time range.
5. Use GetRecordingTaskDetail with a persistentId to check status and retrieve file information.
6. If necessary, call StopRealTimeRecord to end an active recording before the stream ends naturally.

Manage recording parameter templates

A recording parameter template controls where and how recordings are stored. It can define the Object Storage bucket and management endpoint, file path, file format, segmentation behavior, retention period, audio and video handling, timeout behavior, and callback URL.

When modifying a template:

• If you include recordParams, the supplied list replaces the entire existing storage and format configuration list.
• Set notifyUrl to an empty string to remove the callback configuration. Omit it to keep the current value.
• If you provide ak, you must also provide its matching sk. You can omit both to use the current account’s credentials.

Important: You cannot delete a template while it is associated with an active recording rule. Remove the template from all rules before deleting it.

Automate recordings with rules

A recording rule associates a templateId with live streams so recording can start automatically when a matching stream goes live.

Every new rule requires a Delivery Domain in pullDomain. You can narrow the match with these optional fields:

• domain: Ingest Domain
• appName: Application Name
• streamName: Stream Name
• streamParams: stream-name suffix, such as _720P, for a transcoded stream

The system uses the longest, most specific match. For example, a rule for push.example.com/live/stream1 takes precedence over a rule for push.example.com/live, which takes precedence over a rule for push.example.com.

Important: A rule cannot be deleted while it is active or executing a recording. Delete it only after it is no longer in either state.

Start and stop on-demand recordings

Use the real-time control APIs when you need to record active streams immediately without relying on an automatic rule.

1. Call StartRealTimeRecord with a templateId and up to five stream delivery URLs in urlList.
2. Read the result for each URL. Each successful stream operation returns its own persistentId.
3. Store every returned persistentId. Use the relevant ID to query or stop that recording task.
4. Let the recording end when the stream ends, or call StopRealTimeRecord to terminate it earlier.

Query recording tasks and files

Use the task query APIs to find recording tasks, monitor their progress, diagnose failures, and obtain information about generated recording files.