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

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

适用场景：

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

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

1. 接口概览

1.1 视频录制

1.2 视频截图

2. 使用前提

已完成 SDK 初始化

已启动游戏并成功建联

当前存在可用远端视频流

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

3. 视频录制接口

3.1 开始录制

说明：

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

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

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

返回 false 表示当前没有有效会话、已有录制任务正在进行中，或开启水印但未传图片附件

示例：

图片附件水印示例：

按坐标定位时，坐标表示水印左上角在最终录制画面中的像素位置：

watermarkCoordinateEnabled 默认为 true，水印默认位于坐标 (0, 0)。需要使用 watermarkPosition 和 watermarkMarginX/Y 时，应显式设置为 false。坐标模式下位置枚举和边距不参与定位；超出画面的坐标会自动限制在画面内。由于录制帧使用 I420 色度采样，奇数坐标会向下对齐到相邻偶数像素。

SDK 不包含任何默认水印图片。watermarkImageData 支持 Android BitmapFactory 可解析的 PNG、JPEG、WebP 等图片字节；透明 PNG 的 Alpha 会保留。调用方可从 ContentResolver.openInputStream(uri) 得到附件流并自行读取为 byte[]。

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`	自定义 AAC 音频码率；`<= 0` 时使用默认 `128000` bps
`bitsPerSecond`	`int`	自定义总码率，优先级高于 `videoBitsPerSecond`
`mimeType`	`String`	预留字段，当前版本未生效
`filename`	`String`	输出文件名，为空时自动生成
`outputPath`	`String`	自定义输出路径，支持完整文件路径和目录路径
`timeslice`	`int`	预留字段，当前版本未生效
`watermark`	`boolean`	是否启用图片附件水印，默认 `false`
`watermarkImageData`	`byte[]`	调用方提供的图片附件字节；启用水印时必填，SDK 不内置图片
`watermarkPosition`	`int`	水印位置枚举，支持左上、右上、左下、右下；字段默认右下，仅关闭坐标模式后生效
`watermarkCoordinateEnabled`	`boolean`	是否使用绝对坐标定位，默认 `true`；关闭时使用位置枚举和边距
`watermarkX`	`int`	坐标模式下水印左上角的横坐标，默认 `0`
`watermarkY`	`int`	坐标模式下水印左上角的纵坐标，默认 `0`
`watermarkWidth`	`int`	水印目标宽度（视频像素）；`<= 0` 使用图片原始宽度并在超出画面时等比缩小
`watermarkMarginX`	`int`	位置枚举模式下距对应水平边缘的像素距离，默认 `16`
`watermarkMarginY`	`int`	位置枚举模式下距对应垂直边缘的像素距离，默认 `16`
`watermarkOpacity`	`float`	整体透明度 `0-1`，默认 `1.0`；与图片自身 Alpha 共同生效

说明：

quality、videoBitsPerSecond、audioBitsPerSecond、bitsPerSecond、filename、outputPath 和录制水印字段均已生效

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

水印位置常量为 WATERMARK_POSITION_TOP_LEFT、WATERMARK_POSITION_TOP_RIGHT、WATERMARK_POSITION_BOTTOM_LEFT、WATERMARK_POSITION_BOTTOM_RIGHT

VideoRecordOptions.copy() 会复制附件字节，录制开始后调用方修改原数组不会改变本次水印

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. AAC 初始化失败降级与提醒

当设备的 AAC 编码器在创建、配置或启动阶段失败时，SDK 不再终止整次录制，而是自动降级为无声的 H.264 MP4：

视频编码和文件保存继续执行

录制成功结束后仍调用 VideoRecordCallback.onSuccess(...)

不会因为本次 AAC 初始化失败调用 VideoRecordCallback.onError(...)

SDK 通过全局 JyGameStatusListener.onEvent(int code, String msg) 立即发出警告事件

警告事件：

字段	值
`code`	`JyCode.WRN_VIDEO_RECORD_AUDIO_FALLBACK`（`30005`）
`msg`	`AAC 编码器初始化失败: <设备异常信息>`
含义	当前录制已降级为无声视频，业务方可提示用户，但无需主动停止录制

说明：该降级只覆盖 AAC 初始化阶段失败。AAC 已成功启动后发生的编码器运行异常仍按录制失败处理，通过 VideoRecordCallback.onError(...) 返回。

8. 视频录制机型兼容范围与风险

以下结论基于当前代码、设备编码能力和已完成的真机验证，不能解释为“所有 Android 机型无条件兼容”。

8.1 当前支持条件

设备同时满足以下条件时可使用录制：

Android API 19 及以上

存在 H.264/AVC 编码器

H.264 编码器支持标准线性 COLOR_FormatYUV420Planar（I420）或 COLOR_FormatYUV420SemiPlanar（NV12）输入

编码器支持当前远端视频的输出宽高、目标 30fps 和目标码率

AAC-LC 可用时输出有声 MP4；AAC 初始化失败时降级为无声 MP4

8.2 已验证范围

环境	验证状态	结果
小米 M2002J9E / Android 11 / Qualcomm	真机端到端录制	1080p、音画同步、无绿屏，实际约 `29.74fps`
AOSP arm64 模拟器 / Android 14	编码能力检查	H.264、AAC 和当前使用的标准 YUV 格式匹配；未替代多品牌真机录制验证

8.3 已知兼容风险

风险机型或场景	当前行为	影响
H.264 编码器只提供 `COLOR_FormatYUV420Flexible` 或厂商私有 YUV 格式	当前不会选用该编码器	录制启动失败，但避免把私有内存布局误当 NV12 导致绿屏
低端或较老设备不支持输入分辨率、`30fps` 或目标码率	当前尚未在初始化前完整调用 `VideoCapabilities` 做预检和自动降级	可能配置失败、掉帧或录制不流畅
MediaTek、Samsung Exynos、Android 4.4/5.x、Android TV	尚无完整真机矩阵	不能对外承诺全部兼容
AAC 创建、配置或启动失败	自动降级为无声视频并回调 `30005`	保住视频文件，但没有音轨
AAC 启动后的运行期编码异常	结束录制并返回失败	当前没有运行期音频降级

建议发布前至少覆盖 Qualcomm、MediaTek、Exynos 三类芯片，以及 Android 4.4/5.x、Android 11 和 Android 14；每类验证 720p/1080p、横竖屏切换、音频有无、连续录制和会话异常退出。

9. 视频录制后台事件上报

本节是根据当前 SDK 实现整理的内部上报契约。SDK 复用现有 /api/report 通道，接入方不需要额外调用接口。

正文统一采用：

video_record|event=<event>|key=value|...

`event`	`code`	触发时机	关键字段
`start`	`game_event`	开始请求已受理	`status=accepted`、`quality`、`video_bitrate`、`total_bitrate`、`audio_bitrate`、`custom_output`
`audio_fallback`	`game_event`	AAC 初始化失败并降级	`status=degraded`、`reason`
`error`	`game_exception`	开始/停止请求被拒绝，或录制过程异常	`stage`、`status`/`message`/`reason`
`end`	`game_event`	录制生命周期结束	`status=success/failed/cancelled`；成功时还包含 `duration_ms`、`size_bytes`、`width`、`height`、`audio`、`persisted`

契约说明：

start 表示 SDK 已受理录制，不等同于编码器已产出第一帧

录制过程失败时依次上报 error 和 end(status=failed)，便于后台同时统计异常原因和生命周期闭环

会话退出导致录制被取消时上报 end(status=cancelled)

上报不包含本地文件路径和文件名

上报请求失败不会中断或改变本地录制结果

10. 视频录制存储规则

10.1 默认路径

当 outputPath 为空时：

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

10.2 自定义路径

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

支持两种写法：

完整文件路径

目录路径

路径规则：

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

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

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

11. 视频截图接口

11.1 基础截图

说明：

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

默认不缩放画面，并以无损 PNG 格式导出

示例：

11.2 自定义截图参数

参数说明：

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

示例：

12. VideoScreenshotOptions

字段说明：

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

说明：

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

maxWidth、maxHeight 都不限制时，普通渲染模式按解码帧旋转后的原始像素尺寸导出，不进行二次缩放

format 为空或传入不支持的值时按默认 png 处理

JPEG 即使质量设置为 1.0 仍属于有损编码；要求截图文件不再产生有损压缩时请使用 png

指定最大宽高后，SDK 会按原始宽高比缩小，不会放大低分辨率画面

13. VideoScreenshotResult

字段说明：

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

14. VideoScreenshotCallback

说明：

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

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

回调在主线程触发

15. 视频截图存储规则

15.1 默认路径

当 outputPath 为空时：

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

15.2 自定义路径

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

支持两种写法：

完整文件路径

目录路径

路径规则：

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

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

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

16. 返回失败的常见场景

当前没有有效游戏会话

当前没有可用远端视频流

已有录制任务正在进行中

durationMs <= 0

文件路径无效

文件写入失败

截图超时

已有进行中的视频截图任务

已开启录制水印但图片附件为空，或附件图片无法解析

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

17. 注意事项

17.1 视频录制

当前录制输出固定为 MP4，视频轨为 H.264；音频可用时包含 AAC 音轨

当前视频录制目标帧率为 30fps；输入流帧率不足时以实际输入帧率为准

默认录制远端播放音频；远端没有音频数据时会自动降级为纯视频文件

AAC 初始化失败时也会自动降级为纯视频文件，并通过 onEvent(30005, ...) 提醒

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

录制水印图片必须由调用方通过 watermarkImageData 动态提供，不会被写死或打包在 SDK 中

水印附件在录制首帧到达时解码一次，并在旋转后的 I420 录制帧上合成；不会改变游戏画面渲染

17.2 视频截图

当前支持导出 jpeg/jpg/png

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

普通渲染模式直接抓取下一帧渲染画面；只在渲染线程完成一次 GPU 像素读回，缩放后的补充处理、编码和文件写入均在低优先级后台线程执行

兼容渲染模式在 Android 7.0 及以上通过异步 PixelCopy 抓取视频 Surface；导出尺寸以视频 Surface 为准

Android 7.0 以下的兼容渲染模式受系统能力限制，会尝试从远端视频轨道兜底抓帧，部分机型可能截图超时

同一时间只允许一个截图任务，避免并发像素读回和图片编码抢占游戏资源

不设置最大宽高时尽量保持解码帧像素尺寸；使用 png 可避免导出阶段再次进行有损压缩

17.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. AAC 初始化失败降级与提醒#

8. 视频录制机型兼容范围与风险#

8.1 当前支持条件#

8.2 已验证范围#

8.3 已知兼容风险#

9. 视频录制后台事件上报#

10. 视频录制存储规则#

10.1 默认路径#

10.2 自定义路径#

11. 视频截图接口#

11.1 基础截图#

11.2 自定义截图参数#

12. VideoScreenshotOptions#

13. VideoScreenshotResult#

14. VideoScreenshotCallback#

15. 视频截图存储规则#

15.1 默认路径#

15.2 自定义路径#

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

17. 注意事项#

17.1 视频录制#

17.2 视频截图#

17.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. AAC 初始化失败降级与提醒

8. 视频录制机型兼容范围与风险

8.1 当前支持条件

8.2 已验证范围

8.3 已知兼容风险

9. 视频录制后台事件上报

10. 视频录制存储规则

10.1 默认路径

10.2 自定义路径

11. 视频截图接口

11.1 基础截图

11.2 自定义截图参数

12. VideoScreenshotOptions

13. VideoScreenshotResult

14. VideoScreenshotCallback

15. 视频截图存储规则

15.1 默认路径

15.2 自定义路径

16. 返回失败的常见场景

17. 注意事项

17.1 视频录制

17.2 视频截图

17.3 路径建议