视频截图

更新时间 2023/08/10 02:49:42

本文介绍使用云端录制 RESTful API 进行视频截图的重点步骤。建议你同时参考云端录制 RESTful API 快速开始了解云端录制的基础流程。
声网推荐你使用客户端视频截图上传功能，详见视频截图上传。

自 2023 年 1 月 1 日起，声网对该功能收取录制费用，计费方式详见计费说明。

功能描述

云端录制支持对频道内的视频流进行截图，并将图片上传至你的第三方云存储。

支持以下两种截图方式：

在一个单流录制进程中仅截图。
在一个单流录制进程中同时进行录制和截图。声网仅收取一次录制费用。

实现方法

获取 resource ID

在开始录制前，必须调用 acquire 方法请求一个用于云端录制的 resource ID。

请求示例

请求 URL：

https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/acquire

Content-type 为 application/json;charset=utf-8
Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
请求包体内容：

{
    "cname": "httpClient463224",
    "uid": "527841",
    "clientRequest": {
        "resourceExpiredHour": 24,
        "scene": 0
    }
}

开始截图

在调用 start 方法时，你需要将 mode 参数设置为 individual，开启单流录制模式。

录制模式的设置必须在开始录制的时候完成，不支持在录制开始后切换模式。

视频截图支持的 clientRequest 参数包括：

参数	配置内容	是否选填
`token`	动态密钥	如频道使用了 token，则为必填
`recordingConfig`	媒体流订阅、转码、输出音视频属性	必填
`snapshotConfig`	截图周期、截图文件。`snapshotConfig` 包含以下字段： `captureInterval`：（选填）Integer 类型，截图周期（s），云端录制会按此周期定期截图。取值范围是 [1, 3600]，默认值 `10`。 `fileType`：JSON Array，由多个字符串组成的数组，指定截图的文件格式。目前只支持 ["jpg"]，即生成 JPG 截图文件。	必填
`storageConfig`	第三方云存储	必填
`recordingFileConfig`	录制文件的设置	如果在一个录制进程中同时进行录制和截图，则该参数为必填；如果在一个录制进程中仅截图，则不可填写该参数。

请求示例

请求 URL：

https://api.sd-rtn.com/v1/apps/{yourappid}/cloud_recording/resourceid/{resourceid}/mode/individual/start

Content-type 为 application/json;charset=utf-8
Authorization 为 Basic authorization，生成方法请参考 RESTful API 认证。
请求包体内容：

仅截图

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "channelType": 1,
            "subscribeUidGroup": 0
        },
        "snapshotConfig": {
            "captureInterval": 5,
            "fileType": [
                "jpg"
            ]
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

录制并截图：

{
    "uid": "527841",
    "cname": "httpClient463224",
    "clientRequest": {
        "token": "<token if any>",
        "recordingConfig": {
            "maxIdleTime": 30,
            "streamTypes": 1,
            "channelType": 0
        },
        "snapshotConfig": {
            "captureInterval": 5,
            "fileType": [
                "jpg"
            ]
        },
        "recordingFileConfig": {
            "avFileType": [
                "hls"
            ]
        },
        "storageConfig": {
            "accessKey": "xxxxxxf",
            "region": 3,
            "bucket": "xxxxx",
            "secretKey": "xxxxx",
            "vendor": 2,
            "fileNamePrefix": [
                "directory1",
                "directory2"
            ]
        }
    }
}

截图文件

云端录制生成的截图文件的命名规则为 <sid>_<cname>__uid_s_<uid>__uid_e_video_<utc>.jpg。文件类型取决于你在 start 方法中设置的 fileType，目前只支持 JPG。

上述文件名中各字段含义如下：

<sid>：录制 ID
<cname>：频道名
<uid>：用户 ID
<utc>：该截图文件生成时的 UTC 时间，时区为 UTC+0，由年、月、日、小时、分钟、秒和毫秒组成。例如，utc 等于 20190611073246073，表示该截图文件生成时间为 UTC 2019 年 6 月 11 日 7 点 32 分 46 秒 73 毫秒。

当出现服务器断网、进程被杀时，云端录制会自动启用高可用机制，在 90 秒内切换到新的服务器，自动恢复截图服务。启用高可用机制后，截图文件的文件名会增加 bak<n> 前缀，n 为高可用机制在该次截图进程中被启用的 index, 0 表示第一次启用。以文件名 bak0_sid_channel1__uid_s_123__uid_e_video_20190611073246073.jpg 为例，bak0 表示该文件为本次截图中第一次启用高可用机制后生成的截图文件。

开发注意事项

在进行视频截图时，需要注意以下参数的设置。如设置错误，会收到报错，导致截图失败。

请求 URL 中的 mode 参数必须设为 individual。
streamTypes 必须设置为 1 或 2。
如果设置了 subscribeAudioUid，则必须同时设置 subscribeVideoUids。
如果录制服务或录制上传服务异常，则导致截图失败。

另外，在截图过程中，如果某用户中途停止发布视频流，云端录制会停止对其截图，并发送声网消息通知服务的回调。其他用户的截图不受影响。当该用户再次发布视频流时，云端录制会恢复对其截图。

这篇文章对你有帮助吗？

是

否