文档开发者中心
我的
|

HarmonyOS 5

屏幕采集场景下,想要动态控制采集帧率,在不绕过系统隐私授权的前提下,现有 API 有没有折中方案,怎么实时拿到采集链路真实输出帧率?

屏幕采集场景下,想要动态控制采集帧率,在不绕过系统隐私授权的前提下,现有 API 有没有折中方案,怎么实时拿到采集链路真实输出帧率?
点赞
收藏
回复
1
分享
举报
浏览7 发布于昨天07:29广东
全部评论
最多点赞
最新发布
最早发布
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 的取码流方案。这个接口有几个关键特性:

  1. 调用时机是"录屏启动之后",也就是说它天然支持运行中多次调用、动态调整。
  2. 它设置的是"最大帧率"而非"固定帧率",实际输出帧率受设备能力和屏幕内容变化影响(静态画面下系统可能主动降帧),由底层系统能力决定。
  3. 入参上限不设限制,但当前支持的最高帧率为 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 的组合实践)。
  • 调帧率属于正常采集参数调整,不会触发重新授权,也不会影响系统隐私保护机制(如隐私窗口过滤、内容过滤策略)。
展开全部
1楼回复于18小时前 来自广东
写回答
新增插入模板功能
一键使用模板,快速填写内容,轻松发帖~
知道了
  • 为了保障您的信息安全,请勿上传您的敏感个人信息(如您的密码等信息)和您的敏感资产信息(如关键源代码、签名私钥、调试安装包、业务日志等信息),且您需自行承担由此产生的信息泄露等安全风险。
  • 如您发布的内容为转载内容,请注明内容来源。

我要提问题

了解社区公约,与您携手共创和谐专业的开发者社区。