WhaleCloud Android SDK 视频录制与截图接口说明

本文档用于对外说明 WhaleCloud Android SDK 的视频录制和视频截图接口。

适用场景：

游戏已成功建联，客户端需要录制当前远端游戏画面

游戏已成功建联，客户端需要导出当前画面截图

1. 接口概览

1.1 视频录制

1.2 视频截图

2. 使用前提

已完成 SDK 初始化

已启动游戏并成功建联

当前存在可用远端视频流

未建联或当前无可用视频流时，接口会通过回调返回失败信息，或直接返回 false

3. 视频录制接口

3.1 开始录制

说明：

startVideoRecord() 使用默认参数开始录制

startVideoRecord(options) 使用自定义参数开始录制

返回 true 表示 SDK 已受理本次录制请求

返回 false 表示当前没有有效会话，或已有录制任务正在进行中

示例：

3.2 停止录制

参数说明：

参数	类型	必填	说明
`shouldDownload`	`boolean`	是	`true` 时按持久化目录规则保存；`false` 时按缓存目录规则保存
`callback`	`VideoRecordCallback`	否	停止录制后的结果回调

说明：

如果在 startVideoRecord(options) 中传入了 outputPath，则优先使用自定义路径

如果当前没有进行中的录制任务，会通过 callback.onError(...) 返回失败

示例：

3.3 截取固定时长片段

参数说明：

参数	类型	必填	说明
`durationMs`	`long`	是	录制片段时长，单位毫秒，必须大于 0
`filename`	`String`	否	片段文件名；如果非空，会覆盖 `options.filename`
`callback`	`VideoRecordCallback`	否	片段录制完成后的结果回调
`options`	`VideoRecordOptions`	否	录制参数

说明：

SDK 会先开始录制

达到 durationMs 后自动停止并回调结果

片段录制内部按持久化目录规则保存

示例：

3.4 查询录制状态

说明：

返回 true 表示当前存在进行中的录制任务

返回 false 表示当前没有录制任务

4. VideoRecordOptions

字段说明：

字段	类型	说明
`quality`	`int`	清晰度档位，范围 `1-5`
`videoBitsPerSecond`	`int`	自定义视频码率
`audioBitsPerSecond`	`int`	预留字段，当前版本未生效
`bitsPerSecond`	`int`	自定义总码率，优先级高于 `videoBitsPerSecond`
`mimeType`	`String`	预留字段，当前版本未生效
`filename`	`String`	输出文件名，为空时自动生成
`outputPath`	`String`	自定义输出路径，支持完整文件路径和目录路径
`timeslice`	`int`	预留字段，当前版本未生效
`watermark`	`boolean`	预留字段，当前版本未生效

说明：

quality、videoBitsPerSecond、bitsPerSecond、filename、outputPath 为当前版本可用字段

如果同时设置了 bitsPerSecond 和 videoBitsPerSecond，以 bitsPerSecond 为准

5. VideoRecordResult

字段说明：

字段	类型	说明
`file`	`File`	输出文件对象
`path`	`String`	输出文件绝对路径
`filename`	`String`	文件名
`size`	`long`	文件大小，单位字节
`type`	`String`	当前固定为 `video/mp4`
`durationMs`	`long`	录制时长，单位毫秒
`width`	`int`	导出视频宽度
`height`	`int`	导出视频高度
`persisted`	`boolean`	是否按持久化目录规则保存

6. VideoRecordCallback

说明：

onSuccess(...) 在录制成功结束后回调

onError(...) 在录制失败时回调

回调在主线程触发

7. 视频录制存储规则

7.1 默认路径

当 outputPath 为空时：

场景	默认路径
`stopVideoRecord(true, ...)`	`externalFilesDir/Movies/WhaleCloud`
`stopVideoRecord(false, ...)`	`cacheDir/whalecloud/record`

7.2 自定义路径

当 outputPath 不为空时，优先使用自定义路径。

支持两种写法：

完整文件路径

目录路径

路径规则：

如果传目录路径且目录当前还不存在，建议以 / 结尾

相对路径会解析到应用 filesDir 下

如果目标文件已存在，SDK 会自动追加 _1、_2 等后缀，避免覆盖

8. 视频截图接口

8.1 基础截图

说明：

使用默认参数导出当前远端视频流的一帧截图

示例：

8.2 自定义截图参数

参数说明：

参数	类型	必填	说明
`options`	`VideoScreenshotOptions`	否	截图参数
`callback`	`VideoScreenshotCallback`	否	截图结果回调

示例：

9. VideoScreenshotOptions

字段说明：

字段	类型	说明
`format`	`String`	导出格式，支持 `jpeg`、`jpg`、`png`，默认 `jpeg`
`jpegQuality`	`float`	JPEG 压缩质量，范围 `0-1`，仅 `jpeg/jpg` 生效
`maxWidth`	`int`	导出图片最大宽度，`<= 0` 表示不限制
`maxHeight`	`int`	导出图片最大高度，`<= 0` 表示不限制
`shouldDownload`	`boolean`	`true` 时按持久化目录规则保存；`false` 时按缓存目录规则保存
`filename`	`String`	输出文件名，为空时自动生成
`outputPath`	`String`	自定义输出路径，支持完整文件路径和目录路径
`watermark`	`boolean`	预留字段，当前版本未生效

说明：

format、jpegQuality、maxWidth、maxHeight、shouldDownload、filename、outputPath 为当前版本可用字段

10. VideoScreenshotResult

字段说明：

字段	类型	说明
`file`	`File`	输出文件对象
`path`	`String`	输出文件绝对路径
`filename`	`String`	文件名
`size`	`long`	文件大小，单位字节
`type`	`String`	`image/jpeg` 或 `image/png`
`url`	`String`	文件 URI 字符串
`width`	`int`	导出图片宽度
`height`	`int`	导出图片高度
`persisted`	`boolean`	是否按持久化目录规则保存

11. VideoScreenshotCallback

说明：

onSuccess(...) 在截图成功后回调

onError(...) 在截图失败时回调

回调在主线程触发

12. 视频截图存储规则

12.1 默认路径

当 outputPath 为空时：

场景	默认路径
`shouldDownload = true`	`externalFilesDir/Pictures/WhaleCloud`
`shouldDownload = false`	`cacheDir/whalecloud/screenshot`

12.2 自定义路径

当 outputPath 不为空时，优先使用自定义路径。

支持两种写法：

完整文件路径

目录路径

路径规则：

如果传目录路径且目录当前还不存在，建议以 / 结尾

相对路径会解析到应用 filesDir 下

如果目标文件已存在，SDK 会自动追加 _1、_2 等后缀，避免覆盖

13. 返回失败的常见场景

当前没有有效游戏会话

当前没有可用远端视频流

已有录制任务正在进行中

durationMs <= 0

文件路径无效

文件写入失败

截图超时

建议接入方始终处理 onError(int code, String msg)。

14. 注意事项

14.1 视频录制

当前录制输出固定为 mp4(H.264)

当前仅录制视频，不包含远端音频

如果远端流为 H.265，当前录制结果仍为 H.264 mp4

14.2 视频截图

当前支持导出 jpeg/jpg/png

watermark 为预留字段，当前版本未生效

截图对象为当前远端游戏视频流的一帧画面

14.3 路径建议

建议优先使用应用可写目录

对自定义目录场景，建议由业务方自行规划文件命名规则

视频录制和截屏

WhaleCloud Android SDK 视频录制与截图接口说明#

1. 接口概览#

1.1 视频录制#

1.2 视频截图#

2. 使用前提#

3. 视频录制接口#

3.1 开始录制#

3.2 停止录制#

3.3 截取固定时长片段#

3.4 查询录制状态#

4. VideoRecordOptions#

5. VideoRecordResult#

6. VideoRecordCallback#

7. 视频录制存储规则#

7.1 默认路径#

7.2 自定义路径#

8. 视频截图接口#

8.1 基础截图#

8.2 自定义截图参数#

9. VideoScreenshotOptions#

10. VideoScreenshotResult#

11. VideoScreenshotCallback#

12. 视频截图存储规则#

12.1 默认路径#

12.2 自定义路径#

13. 返回失败的常见场景#

14. 注意事项#

14.1 视频录制#

14.2 视频截图#

14.3 路径建议#

WhaleCloud Android SDK 视频录制与截图接口说明

1. 接口概览

1.1 视频录制

1.2 视频截图

2. 使用前提

3. 视频录制接口

3.1 开始录制

3.2 停止录制

3.3 截取固定时长片段

3.4 查询录制状态

4. VideoRecordOptions

5. VideoRecordResult

6. VideoRecordCallback

7. 视频录制存储规则

7.1 默认路径

7.2 自定义路径

8. 视频截图接口

8.1 基础截图

8.2 自定义截图参数

9. VideoScreenshotOptions

10. VideoScreenshotResult

11. VideoScreenshotCallback

12. 视频截图存储规则

12.1 默认路径

12.2 自定义路径

13. 返回失败的常见场景

14. 注意事项

14.1 视频录制

14.2 视频截图

14.3 路径建议