On-demand recording

ApsaraVideo Live manages recording configurations using recording templates. The system matches an ingest URL to the corresponding recording template based on the ingest domain, application name, and stream name in the URL. Recording templates support two methods for on-demand recording: Control by ingest parameters and Control by HTTP callback. You can use these methods to dynamically decide whether to record a specific live stream based on your business rules.

Control by ingest parameters

If a recording template's trigger method is set to Ingest parameter confirmation, you can directly control whether to record the current stream by using the record_config parameter in the ingest URL.

Parameter format: record_config={"NeedRecord": <true/false>}
Parameter description: true enables recording, and false disables recording.
Note: When you construct the ingest URL, you must URL-encode the parameter.

For example, assume the ingest URL is: rtmp://push.example.com/live/stream1

To enable recording with this parameter, construct the URL as follows: rtmp://push.example.com/live/stream1?record_config=%7B%22NeedRecord%22%3Atrue%7D&auth_key=xxx

Limitations:

This trigger method supports recording only the source stream, not transcoded streams. If your recording includes transcoded streams, select a different trigger method.

Control by HTTP callback

How it works

When a live stream is ingested, if the trigger method for the matching recording template is set to Callback confirmation, ApsaraVideo Live sends an HTTP request to your preconfigured callback URL to check whether to record the current stream.
Your application server receives the request and returns a recording instruction (allow or deny) based on your current business logic.
ApsaraVideo Live then starts or skips recording based on your response.

You must first configure the callback URL in the domain's event callback settings. For more information, see Live recording callbacks and On-demand recording callbacks.

Request parameters

Parameter	Type	Description
domain	String	The ingest domain.
app	String	The application name.
stream	String	The stream name.
codec	String	The encoding format. Valid values: h264 h265
vbitrate	String	The video bitrate. Unit: kbps.

Request example

GET /?app=seq_all&domain=demo.aliyundoc.com&stream=ondemand8&vbitrate=2000&codec=h264 HTTP/1.1
Host: pull.aliyundoc.com
User-Agent: Go-http-client/1.1
Accept-Encoding: gzip

Response parameters

After your server receives the callback request, it must return an HTTP 200 status code and a JSON body containing the following parameters:

Parameter	Type	Required	Description
ApiVersion	String	No	The API version. Default value: 1.0.
NeedRecord	Bool	Yes	Specifies whether to record the stream.
Interval	JSONObject	No	Specifies the recording interval for each format. Valid range: 5 to 21600. Unit: seconds.
Format	JSONArray	No	The recording format. Supported formats include MP4, FLV, and M3U8.

Response example

{
  "ApiVersion": "1.0",
  "NeedRecord": true,
  "Interval": {
    "Mp4": 300,
    "Flv": 120,
    "M3U8": 180
  },
  "Format": ["mp4","flv"]
}

Response parameter handling

After the recording service receives your server's response, it compares the returned parameters with the original recording configuration and overrides them as follows:

Interval override: If the response includes the Interval parameter, its value overrides the recording interval in the original recording configuration.
Format intersection: The Format parameter in the response is intersected with the formats specified in the original recording configuration. For example, if the original recording template is configured for MP4 and FLV formats, and the callback response is ["mp4", "m3u8"], only the MP4 format is recorded. If the intersection is empty, the stream is not recorded.

Your callback endpoint must return an HTTP 200 status code. Any other status code is considered a callback failure, and recording is disabled by default.

The maximum size of the callback response body is 2,048 bytes. Responses that exceed this limit are truncated to prevent malicious attacks.

Usage notes

If your service uses the on-demand stream pulling feature, where ApsaraVideo Live pulls a stream from the origin server only when a user initiates playback and stops pulling when there are no viewers, the following conditions apply:

Recording prerequisite: In an on-demand stream pulling scenario, recording (whether automatic, on-demand, or manual) starts only after a user initiates playback.
No recording without playback: If no clients are playing the stream, ApsaraVideo Live does not pull the stream from the origin server, and therefore, no recording files are generated.