全部产品
Search

搜索本产品

    视频直播：直播截图

    文档中心

    视频直播：直播截图

    更新时间：Nov 04, 2024

    直播截图提供实时截图功能，满足您在观看直播同时的截图需求。本文详细为您介绍视频直播截图功能。

    前提条件

    视频直播截图功能需要将截图文件存放在Bucket中，因此需要开通OSS服务并且拥有至少一个Bucket用于存储这些截图文件。更多详情，请参见开通OSS服务和创建存储空间。

    重要

    Bucket必须与播流域名的直播中心同地域，不支持跨地域截图。

    直播截图规则

    • 直播截图是针对推流的AppName为粒度设置的。您可以设置某个AppName下所有推流的截图规则。

      说明

      如果设置AppName为星号（*），则表示截图规则适用于该直播域名下的所有推流。

    • 直播截图功能配置时，可以定义覆盖截图和实时截图两种类型。

      • 覆盖截图是每次新生成截图覆盖之前生成的截图文件。

      • 实时截图是每次新生成的截图不覆盖之前生成的截图文件，截图递增存储。

      • 目前直播截图仅支持生成JPG格式。

        说明

        两种类型可同时设置，且必须设置其中之一。

    直播截图功能介绍

    说明

    新配置的截图模板对正在进行的直播流不生效，需要重新推流才生效。

    视频截图功能配置

    配置视频直播截图功能可以通过以下两种方法：

    控制台配置截图功能

    1. 登录视频直播控制台。

    2. 在左侧导航栏选择功能管理>直播截图，进入直播截图页面，选择截图配置页签。

    3. 选择待配置的播流域名。

    4. 单击添加。

    5. 配置截图模板。

      image

      截图模板参数及说明如下表所示。

      参数

      描述

      AppName

      视频的应用名称，输入的AppName必须与直播推流的AppName保持一致，方可生效。如果您想要进行域名级别截图配置，输入星号（*）即可。

      截图频率

      截图频率，单位：秒，取值范围：5~3600。

      存储位置

      选择截图文件在OSS上的存储位置。

      OSS Bucket必须与播流域名的直播中心同地域，不支持跨地域截图。

      存储方式

      存储方式分两种类型，支持复选。

      • 覆盖截图：视频截图按照截图频率依次截图，新截取的图片覆盖上一张旧图。

      • 实时截图：视频截图按照截图频率依次截图，新图片按照N+1（N≥0）的顺序依次存储在OSS中。

      说明

      复选时，会同时以两种方式进行截图。

      说明

      配置完成后该域名下所有AppName（设置好的AppName），都会按照设置好的模板配置进行截图并存储。

      截图设置修改后，会在下次推流后生效。

    6. 单击确定。

    API配置截图功能

    //需要将<>内容替换成实际使用的值
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>");
//截图周期,取值(5-3600)
addLiveAppSnapshotConfigRequest.setTimeInterval(5);
addLiveAppSnapshotConfigRequest.setOssEndpoint("<Endpoint>");
addLiveAppSnapshotConfigRequest.setOssBucket("<BucketName>");
//定义覆盖截图存储文件名(小于256 Byte，支持变量匹配，包含{AppName}、{StreamName})
addLiveAppSnapshotConfigRequest.setOverwriteOssObject("<{AppName}/{StreamName}.jpg>");
//定义实时截图存储文件名(小于256 Byte，支持变量匹配，包含{AppName}、{StreamName}、{UnixTimestamp}、{Sequence}，其中 {UnixTimestamp}、{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();
}
    说明

    • 配置成功后，重新推流将会产生截图文件。截图文件将会储存至OSS的<BucketName>中，由于同时配置了覆盖截图和实时截图文件路径，将会同时产生覆盖截图文件和实时截图文件。覆盖截图文件储存路径为<{AppName}/{StreamName}.jpg>。实时截图文件储存路径为<{AppName}/{StreamName}/{UnixTimestamp}.jpg>。

    • 若对覆盖截图和实时截图的区别还不了解，请参见文档开头部分直播截图规则。

    • 更多参数说明请参见AddLiveAppSnapshotConfig。

    截图文件管理

    查看截图文件

    您可以通过三种方式查看截图文件。

    控制台查看截图文件

    1. 登录视频直播控制台。

    2. 在左侧导航栏选择功能管理>直播截图，进入直播截图页面，选择截图管理。

    3. 选择待查询的域名及时间，然后输入或选择AppName和StreamName。

    4. 单击查询，查看选择时间段内的截图。若截图无法查看，请确定OSS Bucket读写权限是否为公共读，具体操作，请参见配置OSS bucket读写权限。

      image

    5. 将鼠标移动到某一图片上方，可以查看大图或复制截图的流地址。

    API查看截图文件

    //需要将<>内容替换成实际使用的值 
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>");
//UTC时间，格式为：yyyy-MM-ddTHH:mm:ssZ
describeLiveStreamSnapshotInfoRequest.setStartTime("<StartTime>");
//UTC时间，格式为：yyyy-MM-ddTHH:mm:ssZ，EndTime和StartTime之间的间隔不能超过1天。
describeLiveStreamSnapshotInfoRequest.setEndTime("<EndTime>");
DescribeLiveStreamSnapshotInfoResponse describeLiveStreamSnapshotInfoResponse = null;
try {
    describeLiveStreamSnapshotInfoResponse = client.getAcsResponse(describeLiveStreamSnapshotInfoRequest);
} catch (ClientException e) {
    e.printStackTrace();
}
System.out.println(new Gson().toJson(describeLiveStreamSnapshotInfoResponse));
    重要

    • 目前只支持查询一年内其中某一天（EndTime和StartTime之间的间隔不能超过1天）的截图文件。

    • 截图类型配置为覆盖截图+实时截图的情况下，只能查询出实时截图的文件内容。若在此情况下要查看覆盖截图的截图文件，请在OSS中查看，详情可参见OSS列举文件。

    • 接口暂不支持分页，且一次最多返回100条数据（默认返回10条数据）。

    • 更多查询截图文件内容接口说明，请参见DescribeLiveStreamSnapshotInfo。

    OSS查看截图文件

    在配置截图功能时，您已指定了截图文件在OSS中的存储地址。如果需要在OSS中查看截图文件，可参见OSS列举文件。

    删除截图文件

    视频直播储存的是截图文件信息，如AppName，StreamName，OSS文件储存路径等，文件是储存在OSS中。如果在删除截图时需要同步删除储存在OSS中的文件，则需要创建服务角色AliyunMTSVideoLifecycleRole，并精确授权AliyunMTSVideoLifecycleRolePolicy系统策略。

    详细授权过程

    在直播控制台删除截图或录制文件时需要先进行授权，您需要按照如下步骤在RAM控制台创建并授权RAM角色后，再登录直播控制台删除截图或录制文件。

    1. 使用阿里云账号登录RAM控制台。

    2. 在左侧导航栏，选择身份管理 > 角色。

    3. 在角色页面，单击创建角色。

    4. 在选择类型页签，可信实体类型选择阿里云服务，单击下一步。image

    5. 在配置角色页签，请按照以下参数配置：

      • 角色类型：普通服务角色

      • 角色名称：AliyunMTSVideoLifecycleRole

      • 备注：该参数为可选，您可以按照需求自定义填写。

      • 选择受信服务：多媒体转码服务

      配置完成后，单击完成。image

    6. 在创建完成页签，提示角色创建成功后，单击精确授权。

    7. 在添加权限页签，请按照以下参数配置：

      • 选择权限类型：系统策略

      • 输入策略名称：AliyunMTSVideoLifecycleRolePolicy

      配置完成后，单击确定。image

    您可以通过三种方式删除截图文件：

    控制台删除截图文件

    1. 登录视频直播控制台。

    2. 在左侧导航栏选择功能管理>直播截图，进入直播截图页面，选择截图管理。

    3. 选择待查询的域名及时间，然后输入或选择AppName和StreamName。

    4. 将鼠标移动到某一图片上方，单击删除按钮可进行单张删除。

      勾选多张截图后单击批量删除，可批量删除截图。最多可支持批量删除200张截图。

    API删除截图文件

    //需要将<>内容替换成实际使用的值 
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>");
//是否同步删除OSS中的文件
deleteSnapshotFilesRequest.setRemoveFile(true);
List<Long> createTimestampLists=new ArrayList<>();
//添加需要删除的截图文件时间戳
//createTimestampLists.add(<截图文件时间戳>);
deleteSnapshotFilesRequest.setCreateTimestampLists(createTimestampLists);
DeleteSnapshotFilesResponse deleteSnapshotFilesResponse= null;
try {
    deleteSnapshotFilesResponse = client.getAcsResponse(deleteSnapshotFilesRequest);
} catch (ClientException e) {
    e.printStackTrace();
}
System.out.println(new Gson().toJson(deleteSnapshotFilesResponse));
    重要

    • 目前只支持删除一年内的截图文件。

    • 截图文件时间戳可通过查询截图文件获取。详情可参见查看截图文件。

    • 对于覆盖截图的截图文件，目前只能在OSS中进行删除，具体操作可参见OSS删除文件。

    • 更多删除直播截图文件接口说明，请参见DeleteSnapshotFiles。

    以上示例实现了对截图文件的删除（同时删除了储存在OSS中的文件）。

    您可以为截图功能设置回调事件，获取回调参数将截图信息保存至您自己的业务系统（同时储存时间戳），在需要删除文件时，您就可以根据您系统的策略（如通过定时任务每天定时删除N个月以前的截图文件）查询出截图文件时间戳对截图文件进行删除。若想了解截图回调，可参见直播截图回调开发指南。

    OSS删除截图文件

    一般情况下，不建议您直接删除存储在OSS中的截图文件。如果需要删除存储在OSS中的截图文件，可以通过视频直播删除截图文件时同步删除存储在OSS中的文件。如果您因为业务需求需要直接删除存储在OSS中的截图文件，可参考文档OSS删除文件。

    相关文档

    使用Java SDK，请参见Java SDK使用说明。

    更多直播截图API，可参见直播截图相关API。