视频截图

功能描述

本文介绍如何通过设置 RESTful API 参数对视频进行截图，并将图片上传至你的第三方云存储。

支持以下两种截图方式：

在一个录制进程中同时进行录制和截图。
仅截图。

云端录制只支持在单流录制模式（individual）下进行截图。

阅读本文前，请确保你已了解如何使用 RESTful API 进行云端录制，详见快速开始。

实现方法

获取 resource ID

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

请求示例

请求 URL：

https://api.agrtc.cn/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
    }
}

开始录制

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

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

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

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

请求示例

请求 URL：

https://api.agrtc.cn/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 need>",
            "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。
不可设置 recordingFileConfig。
streamType 必须设置为 1 或 2
如果设置了 subscribeAudioUid，则必须同时设置 subscribeVideoUids。

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