Live stream snapshots - ApsaraVideo Live - Alibaba Cloud Documentation Center

ApsaraVideo Live allows you to capture snapshots during live streaming. This topic describes the snapshot feature in detail.

Prerequisites

Object Storage Service (OSS) is activated and an OSS bucket is created. The OSS bucket is used to store the snapshots captured during live streaming. For more information, see Activate OSS and Create a bucket.

Important

The bucket must reside in the same region as the live center of the streaming domain.

Snapshot rules

Snapshot rules are configured based on the AppName parameter of ingested streams.
- If you specify an application name, the snapshot rule applies to all ingested streams of the application.
- If you set the AppName parameter to an asterisk (*), the snapshot rule applies to all ingested streams within the domain.
ApsaraVideo Live supports capturing snapshots in overwrite mode and real-time mode.
- In overwrite mode, the latest snapshot overwrites the existing snapshot.
- In real-time mode, each snapshot is saved without overwriting the previous ones.
The two modes can be selected at the same time. You must select at least one mode.
ApsaraVideo Live supports capturing snapshots only in JPG format.

Use the snapshot feature

Note

A newly configured or modified snapshot template does not take effect on an ongoing live stream. You must re-ingest the stream.

Configure the feature

You can configure the snapshot feature in the ApsaraVideo Live console or through API operations.

ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Snapshots. On the Snapshots page, click the Snapshot Settings tab.
Select the streaming domain that you want to manage.
Click Add.

Configure the snapshot template.

The following table describes the parameters of a snapshot template.

Parameter	Description
Application Name	The name of the application. The value must be the same as the application name specified in the ingest URL. If you want to configure snapshot settings for all applications under the domain name, enter an asterisk (*).
Snapshot Interval	The interval between two consecutive snapshots. Unit: seconds. Valid values: 5 to 3600.
Storage Location	The storage location of snapshots in OSS. The OSS bucket must reside in the same region as the live center of the streaming domain.
Storage Mode	Two storage modes are available. You can select them at the same time. Overwrite: Snapshots are captured in sequence based on the snapshot interval. A newly captured snapshot overwrites the previous one. New: Snapshots are captured based on the snapshot interval and stored in OSS incrementally following a sequential order. If you select two modes, snapshots are captured in both manners.

Click OK.

API

Java

// Replace the placeholders with actual values.
DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
IAcsClient client = new DefaultAcsClient(profile);
AddLiveAppSnapshotConfigRequest addLiveAppSnapshotConfigRequest = new AddLiveAppSnapshotConfigRequest();
addLiveAppSnapshotConfigRequest.setDomainName("<DomainName>");
addLiveAppSnapshotConfigRequest.setAppName("<AppName>");
// The interval at which snapshots are captured. Valid values: 5 to 3600.
addLiveAppSnapshotConfigRequest.setTimeInterval(5);
addLiveAppSnapshotConfigRequest.setOssEndpoint("<Endpoint>");
addLiveAppSnapshotConfigRequest.setOssBucket("<BucketName>");
// The name of the OSS object to be generated when a snapshot is captured in overwrite mode. The name must be less than 256 bytes in length. The name can contain variables, such as {AppName} and {StreamName}.
addLiveAppSnapshotConfigRequest.setOverwriteOssObject("<{AppName}/{StreamName}.jpg>");
// The name of the OSS object to be generated when a snapshot is captured in real-time mode. The name must be less than 256 bytes in length. The name can contain variables, such as {AppName}, {StreamName}, {UnixTimestamp}, and {Sequence}. You must specify one of {UnixTimestamp} and {Sequence}.
addLiveAppSnapshotConfigRequest.setSequenceOssObject("<{AppName}/{StreamName}/{UnixTimestamp}.jpg>");
try {
    AddLiveAppSnapshotConfigResponse addLiveAppSnapshotConfigResponse = client.getAcsResponse(addLiveAppSnapshotConfigRequest);
    System.out.println(addLiveAppSnapshotConfigResponse.getRequestId());
    // todo something.
} catch (ServerException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
} catch (ClientException e) {
    // TODO Auto-generated catch block
    e.printStackTrace();
}

Note

The captured snapshots are stored in the OSS bucket specified by the BucketName parameter. If you configure the storage paths for overwrite and real-time modes at the same time, the snapshots are generated in both manners. The path of the snapshots captured in overwrite mode is <{AppName}/{StreamName}.jpg>. The path of the snapshots captured in real-time mode is <{AppName}/{StreamName}/{UnixTimestamp}.jpg>.
For differences between the overwrite and real-time modes, see the Snapshot rules section of this topic.
For more information about API parameters, see AddLiveAppSnapshotConfig.

Manage snapshots

View snapshots

You can use the ApsaraVideo Live console, call API operations, or list objects in the OSS bucket to view snapshots captured.

ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Snapshots. On the Snapshots page, click the Snapshot Management tab.
Select a streaming domain. On the page that appears, specify the date and enter an application name and a stream name.
Click Search to view snapshots captured on the specified date. If no snapshots are displayed, check whether the access control list (ACL) of the OSS bucket is set to Public Read. For more information, see Configure the bucket ACL.
Move the pointer over a snapshot to zoom in the snapshot or copy the URL.

API

Java

// Replace the placeholders with actual values.
DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
IAcsClient client = new DefaultAcsClient(profile);
DescribeLiveStreamSnapshotInfoRequest describeLiveStreamSnapshotInfoRequest=new DescribeLiveStreamSnapshotInfoRequest();
describeLiveStreamSnapshotInfoRequest.setAppName("<AppName>");
describeLiveStreamSnapshotInfoRequest.setStreamName("<StreamName>");
describeLiveStreamSnapshotInfoRequest.setDomainName("<DomainName>");
// The beginning of the time range to query. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC.
describeLiveStreamSnapshotInfoRequest.setStartTime("<StartTime>");
// The end of the time range to query. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format and is displayed in UTC. The duration specified by the StartTime and EndTime parameters cannot exceed one day. 
describeLiveStreamSnapshotInfoRequest.setEndTime("<EndTime>");
DescribeLiveStreamSnapshotInfoResponse describeLiveStreamSnapshotInfoResponse = null;
try {
    describeLiveStreamSnapshotInfoResponse = client.getAcsResponse(describeLiveStreamSnapshotInfoRequest);
} catch (ClientException e) {
    e.printStackTrace();
}
System.out.println(new Gson().toJson(describeLiveStreamSnapshotInfoResponse));

Important

You can query only snapshots captured within one year. The time period to query cannot exceed 24 hours.
You can call the API to query only snapshots captured in real-time mode. To view snapshots captured in overwrite mode, list objects in the OSS bucket. For more information, see List objects.
The API does not support paged queries and can return a maximum of 100 entries at a time. By default, 10 entries are returned.
For more information about API parameters, see DescribeLiveStreamSnapshotInfo.

OSS

To view snapshots stored in the specified OSS bucket, you can use methods provided by OSS. For more information, see List objects.

Delete snapshots

ApsaraVideo Live stores only information about snapshot files, such as AppName, StreamName, and OSS storage path. The files are stored in OSS. To delete files from OSS when removing snapshot information from ApsaraVideo Live, you must first create the AliyunMTSVideoLifecycleRole role and attach the AliyunMTSVideoLifecycleRolePolicy policy to the role.

Authorization process

Log on to the RAM console with your Alibaba Cloud account.
In the left navigation bar, choose Identities > Roles.
On the Roles page, click Create Role.
In the Select Role Type step, select Alibaba Cloud Service as the type of trusted entity. Then, click Next.
In the Configure Role step, configure the following parameters:
- Set Role Type to Normal Service Role.
- Enter AliyunMTSVideoLifecycleRole in the RAM Role Name field.
- (Optional) Enter content in the Note field based on your needs.
- Select Media Transcoding Service from the Select Trusted Service drop-down list.
Click OK.
In the Finish step, click Input and Attach. On the role details page, click Precise Permission.
In the Precise Permission panel, configure the following parameters:
- Set Type to System Policy.
- Enter AliyunMTSVideoLifecycleRolePolicy in the Policy Name field.
Click OK.

You can use the ApsaraVideo Live console, API operations, or other methods supported by OSS to delete snapshots.

ApsaraVideo Live console

Log on to the ApsaraVideo Live console.
In the left-side navigation pane, choose Feature Management > Snapshots. On the Snapshots page, click the Snapshot Management tab.
Select a streaming domain. On the page that appears, specify the date and enter an application name and a stream name.
Move the pointer over a snapshot and click Delete to delete the snapshot.
Select multiple snapshots and click Batch Delete to delete them at a time. You can select up to 200 snapshots.

API

Java

// Replace the placeholders with actual values. 
DefaultProfile profile = DefaultProfile.getProfile("<regionId>", "<ALIBABA_CLOUD_ACCESS_KEY_ID>", "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>");
IAcsClient client = new DefaultAcsClient(profile);        
DeleteSnapshotFilesRequest deleteSnapshotFilesRequest=new DeleteSnapshotFilesRequest();
deleteSnapshotFilesRequest.setAppName("<AppName>");
deleteSnapshotFilesRequest.setStreamName("<StreamName>");
deleteSnapshotFilesRequest.setDomainName("<DomainName>");
// Specify whether to delete the corresponding snapshots stored in OSS.
deleteSnapshotFilesRequest.setRemoveFile(true);
List<Long> createTimestampLists=new ArrayList<>();
// Specify the timestamp of the snapshot that you want to delete.
// createTimestampLists.add(<Timestamp>);
deleteSnapshotFilesRequest.setCreateTimestampLists(createTimestampLists);
DeleteSnapshotFilesResponse deleteSnapshotFilesResponse= null;
try {
    deleteSnapshotFilesResponse = client.getAcsResponse(deleteSnapshotFilesRequest);
} catch (ClientException e) {
    e.printStackTrace();
}
System.out.println(new Gson().toJson(deleteSnapshotFilesResponse));

Important

This API operation supports deleting only snapshots captured in real-time mode within one year. To delete snapshots captured in overwrite mode, see Delete objects.
You can query snapshots to obtain the corresponding timestamps. For more information, see View snapshots in this topic.
For more information about API parameters, see DeleteSnapshotFiles.

You can add an event listener for this feature to receive a callback whenever a snapshot is captured, which includes detailed information about the snapshot. You can save the snapshot information and timestamps in your business system, which allows you to query timestamps and identify snapshots to be deleted. For example, you can set up a system policy for a scheduled task that runs daily to query and delete snapshots older than the specified number of months. For more information, see Callbacks for live stream snapshot.

OSS

It is not recommended to directly delete snapshots from OSS. You can synchronize file deletion when you remove snapshot information from ApsaraVideo Live. If your business requires direct deletion in OSS, see Delete objects.

References

For information about how to use the server SDK for Java, see Use the server SDK for Java.

For information about APIs related to the snapshot feature, see API reference for snapshot.