hid31955859HarmonyOS 5
屏幕采集场景下,想要动态控制采集帧率,在不绕过系统隐私授权的前提下,现有 API 有没有折中方案,怎么实时拿到采集链路真实输出帧率?
AI助手屏幕采集场景下,现有 API 是有折中方案的:HarmonyOS 的录屏能力(AVScreenCapture,C API)从 API version 14 开始提供了 OH_AVScreenCapture_SetMaxVideoFrameRate 接口,可以在录屏启动之后动态调整采集的最大帧率,且整个过程完全走系统官方录屏链路和隐私授权弹窗,不存在绕过授权的问题。至于"实时拿到采集链路真实输出帧率",系统目前没有提供类似相机 getActiveFrameRate 那样的直接查询接口,折中做法是在录屏数据回调中自行统计视频帧的到达节奏,用滑动窗口计算真实输出 FPS。
一、动态控制帧率的折中方案
需要先明确一个背景:屏幕采集有两套接口形态。
- ArkTS 的
AVScreenCaptureRecorder(录屏写文件):其配置项AVScreenCaptureRecordConfig中只有videoBitrate、frameWidth等参数,没有帧率配置项,也不支持运行中动态调帧率。 - C/C++ 的
OH_AVScreenCapture(录屏取码流):支持OH_AVScreenCapture_SetMaxVideoFrameRate,这是目前唯一的动态帧率控制入口。
因此,如果业务上必须动态控制采集帧率,建议采用 C API 的取码流方案。这个接口有几个关键特性:
- 调用时机是"录屏启动之后",也就是说它天然支持运行中多次调用、动态调整。
- 它设置的是"最大帧率"而非"固定帧率",实际输出帧率受设备能力和屏幕内容变化影响(静态画面下系统可能主动降帧),由底层系统能力决定。
- 入参上限不设限制,但当前支持的最高帧率为 60FPS,超过 60 按 60 处理;低帧率(1-15)适合静态内容,中帧率(16-30)适合普通场景,高帧率(31-60)适合流畅度要求高的场景。
隐私授权方面完全不需要担心:OH_AVScreenCapture 走的是系统标准录屏授权流程,用户在弹窗中确认后才开始采集,调整帧率只是改变采集节奏,不涉及任何授权绕过。若业务还需要过滤通知音、排除指定窗口,可以配合内容过滤接口(OH_AVScreenCapture_ContentFilter 系列)使用。
二、实时统计真实输出帧率
系统没有提供"查询当前采集链路实际输出帧率"的接口,所以真实帧率需要自己统计。推荐做法是:注册 OH_AVScreenCapture_SetDataCallback(API 12+,统一回调,音视频 buffer 都会触发),在回调中只对视频类型的 buffer 计数,用滑动窗口(例如最近 1 秒或最近 N 帧)计算实际 FPS。这样统计出来的是"采集链路真实吐出的帧率",而不是配置值,能准确反映设备能力限制和系统降帧行为。
三、示例代码(C/C++,API 14+)
#include <multimedia/player_framework/native_avscreen_capture.h>
#include <multimedia/player_framework/native_avscreen_capture_base.h>
#include <multimedia/player_framework/native_avscreen_capture_errors.h>
#include <chrono>
#include <mutex>
// 帧率统计器:滑动窗口统计真实输出帧率
class FrameRateMeter {
public:
void OnVideoFrame()
{
std::lock_guard<std::mutex> lock(mutex_);
auto now = std::chrono::steady_clock::now();
timestamps_.push_back(now);
// 只保留最近 1 秒内的帧时间戳
auto windowStart = now - std::chrono::seconds(1);
while (!timestamps_.empty() && timestamps_.front() < windowStart) {
timestamps_.pop_front();
}
}
// 返回最近 1 秒的真实输出帧率
double GetRealFps() const
{
std::lock_guard<std::mutex> lock(mutex_);
return static_cast<double>(timestamps_.size());
}
private:
mutable std::mutex mutex_;
std::deque<std::chrono::steady_clock::time_point> timestamps_;
};
static FrameRateMeter g_frameRateMeter;
// 统一数据回调:音视频 buffer 可用时触发,回调返回后 buffer 失效
static void OnBufferAvailable(OH_AVBuffer *buffer, OH_AVScreenCapture_BufferType bufferType, void *userData)
{
if (bufferType == OH_AVScreenCapture_BufferType::OH_SCREEN_CAPTURE_BUFFERTYPE_VIDEO) {
// 仅对视频帧计数,用于统计真实输出帧率
g_frameRateMeter.OnVideoFrame();
// 此处可继续做取流/编码/发送等处理
}
}
// 动态调整采集最大帧率(可在录屏启动后任意时刻调用)
static void AdjustFrameRate(OH_AVScreenCapture *capture, int32_t targetFps)
{
// 上限 60FPS,超过按 60 处理;实际帧率受设备能力限制
OH_AVSCREEN_CAPTURE_ErrCode ret = OH_AVScreenCapture_SetMaxVideoFrameRate(capture, targetFps);
if (ret != AV_SCREEN_CAPTURE_ERR_OK) {
// 处理失败:检查 capture 是否为空指针、入参是否支持、设备是否支持录屏
}
}
static void StartCapture(OH_AVScreenCapture *capture)
{
// 1. 录屏启动前注册统一数据回调(API 12+)
OH_AVScreenCapture_SetDataCallback(capture, OnBufferAvailable, nullptr);
// 2. 启动录屏(走系统隐私授权弹窗,用户确认后开始采集)
OH_AVScreenCapture_StartScreenCapture(capture);
// 3. 启动后即可动态调帧率,例如先降到 15FPS 省电
AdjustFrameRate(capture, 15);
}
典型使用流程如下:
四、补充说明
- 版本要求:
OH_AVScreenCapture_SetMaxVideoFrameRate起始版本为 API 14;OH_AVScreenCapture_SetDataCallback起始版本为 API 12。若使用旧版分离回调(OH_AVScreenCapture_SetCallback中的OH_AVScreenCaptureOnVideoBufferAvailable),同样可以统计帧率,但官方推荐使用 API 12 之后的统一回调。 - 统计窗口建议:1 秒窗口对低帧率(如 5FPS)会显得抖动较大,可以改用"最近 N 帧的间隔均值"来计算,低帧率下更平滑。
- 帧率语义要区分清楚:
videoFrameRate(配置在OH_VideoEncInfo中)是编码器的目标帧率,SetMaxVideoFrameRate是采集链路的上限帧率,两者配合使用时,真实输出帧率以采集回调统计值为准。 - ArkTS 侧如果只做录屏写文件且对动态帧率没有强需求,继续使用
AVScreenCaptureRecorder即可;一旦需要动态帧率控制,就应切换到 C API 取码流方案,再自行接编码器(可参考 AVCodec Kit 的 Surface 模式视频编码,官方指南中有 AVScreenCapture + AVCodec 的组合实践)。 - 调帧率属于正常采集参数调整,不会触发重新授权,也不会影响系统隐私保护机制(如隐私窗口过滤、内容过滤策略)。
- 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
- 如您发布的内容为转载内容,请注明内容来源。
我要提问题
HarmonyOS 应用APMS实现方案 (API12+)
HarmonyOS RN是否有拆包方案(API12+)
HarmonyOS 边缘手势是哪个API控制的 (API12+)
HarmonyOS AGC后台PROCESS_KILL排查方案 (API12)
HarmonyOS 父子组件,想要实现数据同步,@Link需要如何使用?(API12+)
HarmonyOS 如何控制多个请求执行顺序?(API12+)
HarmonyOS bindSheet如何设置可以和外部交互,并且控制下滑不关闭?(API12+)
HarmonyOS 有没有列表头部滑动常驻悬停的示例?(API12+)




































苏公安网备 32011402010933号