【HarmonyOS 6.0】Camera Kit 新增系统性能压力监听功能全解析

文章目录

[1 -> 概述](#1 -> 概述)
[2 -> 核心能力与接口详解](#2 -> 核心能力与接口详解)
- [2.1 -> SystemPressureLevel 枚举](#2.1 -> SystemPressureLevel 枚举)
- [2.2 -> ArkTS 接口（PhotoSession / VideoSession）](#2.2 -> ArkTS 接口（PhotoSession / VideoSession）)
- [2.3 -> C/C++ 接口（NDK 层）](#2.3 -> C/C++ 接口（NDK 层）)
[3 -> 实战开发：ArkTS 中的实现](#3 -> 实战开发：ArkTS 中的实现)
- [3.1 -> 导入模块并初始化 CameraManager](#3.1 -> 导入模块并初始化 CameraManager)
- [3.2 -> 创建 VideoSession 并配置输入/输出](#3.2 -> 创建 VideoSession 并配置输入/输出)
- [3.3 -> 注册系统压力监听](#3.3 -> 注册系统压力监听)
- [3.4 -> 资源释放](#3.4 -> 资源释放)
[4 -> C/C++ 开发实现](#4 -> C/C++ 开发实现)
- [4.1 -> 示例代码](#4.1 -> 示例代码)
- [4.2 -> 关于跨语言开销的优势](#4.2 -> 关于跨语言开销的优势)
[5 -> 典型应用场景与实际调优策略](#5 -> 典型应用场景与实际调优策略)
- [5.1 -> 直播应用：长时稳定性优先](#5.1 -> 直播应用：长时稳定性优先)
- [5.2 -> AR 玩法 / 手势识别场景](#5.2 -> AR 玩法 / 手势识别场景)
- [5.3 -> 高帧率录制：优先保障核心体验](#5.3 -> 高帧率录制：优先保障核心体验)
- [5.4 -> 监控类相机：稳定性和续航并重](#5.4 -> 监控类相机：稳定性和续航并重)
[6 -> 调试技巧与开发建议](#6 -> 调试技巧与开发建议)
- [6.1 -> 压力等级的触发条件测试](#6.1 -> 压力等级的触发条件测试)
- [6.2 -> 避免频繁重建流](#6.2 -> 避免频繁重建流)
- [6.3 -> 将压力状态与现有监控机制结合](#6.3 -> 将压力状态与现有监控机制结合)
- [6.4 -> 压力监听对设备兼容性的考量](#6.4 -> 压力监听对设备兼容性的考量)
[7 -> 总结](#7 -> 总结)

1 -> 概述

在移动设备上运行高性能相机应用，开发者始终需要在画质、帧率和功耗之间做出权衡。长时间运行相机------特别是直播、视频会议、连续拍摄等场景------极易引发设备发热、CPU/GPU 负载飙升，最终触发系统热降频或强制限流，导致取景卡顿、录像丢帧甚至应用闪退。过去开发者对系统的性能压力状态几乎是"黑盒"操作，只能被动依赖硬件惯性或粗暴地降低画质来勉强维持稳定性。

HarmonyOS 6.0（对应 API version 20）在 Camera Kit 中引入了一项重要能力：系统压力水平监听的全面支持。无论是 ArkTS 还是 C/C++ 开发场景，开发者都可以在 PhotoSession 或 VideoSession 中注册 systemPressureLevelChange 回调。该回调会在系统性能压力等级发生变化时主动通知应用层，返回一个明确的 SystemPressureLevel 枚举值。应用可以据此实时调整图像质量参数，例如降低帧率、下调分辨率或关闭次要特效，从而与系统的热管理和功耗调度策略形成良性联动，实现功耗、发热和系统负载之间的动态平衡。

本文将从 API 设计、多语言实现、典型应用策略及调试技巧四个维度，系统解析这一新特性的落地方式。

2 -> 核心能力与接口详解

2.1 -> SystemPressureLevel 枚举

在 HarmonyOS 6.0 的 Camera API（API version 20）中，系统压力水平被抽象为以下枚举值（参考官方定义）：

NORMAL：系统处于正常运行状态，无额外压力。相机应用可以保持最高质量的拍摄参数。
SEMI_WARNING：系统进入半预警状态。此时可能伴随轻微发热或 CPU 负载上升，建议应用适度降低非关键负载（如预览帧率从 60fps 降低至 30fps）。
WARNING：系统发出明确压力预警。通常意味着设备温度上升较快或资源调度持续紧张，相机服务本身可能面临降频风险。应用应主动降低图像质量参数，例如缩小预览或录像分辨率。
CRITICAL：系统处于高压力状态。相机服务可能被系统强制限流或暂停部分输出流，应用应尽可能切换到最低功耗模式，甚至提醒用户暂停拍摄。

注：不同设备的具体级别划分可能因芯片热管理策略而略有差异，但上述四级划分是面向开发者的上层抽象。

这一枚举值的引入，使得相机应用可以像监听系统内存水位（onMemoryLevel）一样，对系统的"压力水位"做出分级响应。与内存管理不同的是，压力响应更强调实时性和热管理联动，要求应用在数十毫秒内完成参数切换并生效。

2.2 -> ArkTS 接口（PhotoSession / VideoSession）

在 ArkTS 开发中，开发者可以通过 PhotoSession 或 VideoSession 对象的 on 方法注册 systemPressureLevelChange 回调。回调函数中接收两个参数：err 错误对象和 systemPressureLevel 枚举值。

接口签名：

typescript 复制代码

on(type: 'systemPressureLevelChange', callback: AsyncCallback<SystemPressureLevel>): void;

当系统压力水平发生变化时（例如温度上升或系统负载加剧），该回调会被触发，并通过异步回调返回当前的压力等级。此接口使用标准的 AsyncCallback 异步回调模式，err 为 BusinessError 类型，用于判断是否发生异常；systemPressureLevel 为 camera.SystemPressureLevel 枚举值。

2.3 -> C/C++ 接口（NDK 层）

对于需要高性能或深度集成的场景，开发者可以使用 C/C++ API。与此对应的回调注册基于 CaptureSession：

通过 OH_CaptureSession_RegisterSystemPressureLevelChangeCallback 注册回调函数。
当系统压力等级发生变化时，回调函数返回 Camera_SystemPressureLevel 枚举值。
回调函数原型为 SystemPressureLevelChangeCallback(Camera_CaptureSession* captureSession, Camera_SystemPressureLevel systemPressureLevel)。

相比 ArkTS 版本，C/C++ 接口绕过了跨语言调用开销，在需要高频处理相机帧且对压力响应延迟有严苛要求的 Pipeline 中（如实时滤镜 + 编码录制），可以避免 JNI 或 NAPI 桥接带来的额外抖动。

3 -> 实战开发：ArkTS 中的实现

下面我们以 VideoSession 为例，完整演示如何从零开始集成系统压力监听，并实现自适应的图像质量降级策略。

3.1 -> 导入模块并初始化 CameraManager

首先需要导入 Camera Kit，获取 CameraManager 实例并打开相机设备。

typescript 复制代码

import { camera } from '@kit.CameraKit';
import { BusinessError } from '@kit.BasicServicesKit';

let cameraManager: camera.CameraManager = camera.getCameraManager();
let cameras: Array<camera.CameraDevice> = cameraManager.getSupportedCameras();
// 假设取第一个后置摄像头
let cameraDevice: camera.CameraDevice = cameras.find(device => device.position === camera.CameraPosition.BACK);

if (!cameraDevice) {
    console.error("No back camera found.");
    return;
}

3.2 -> 创建 VideoSession 并配置输入/输出

typescript 复制代码

let videoSession: camera.VideoSession = cameraManager.createSession(camera.SceneMode.NORMAL_VIDEO) as camera.VideoSession;

// 配置输入流
let videoInput: camera.VideoInput = cameraManager.createCameraInput(cameraDevice);
await videoInput.open();

// 配置预览输出 Surface
let previewSurfaceId: string = await this.getPreviewSurfaceId(); // 自定义获取 Surface 的方法
let previewOutput: camera.PreviewOutput = cameraManager.createPreviewOutput(previewSurfaceId);

// 配置录像输出 Surface
let recorderSurfaceId: string = await this.getRecorderSurfaceId(); // 自定义获取 Surface ID 的方法
let videoOutput: camera.VideoOutput = cameraManager.createVideoOutput(recorderSurfaceId);

// 开始会话配置
await videoSession.beginConfig();
videoSession.addInput(videoInput);
videoSession.addOutput(previewOutput);
videoSession.addOutput(videoOutput);
await videoSession.commitConfig();

await videoSession.start();

3.3 -> 注册系统压力监听

核心步骤：在会话启动后（或配置完成后），通过 on('systemPressureLevelChange', callback) 注册监听。

typescript 复制代码

// 定义一个状态管理对象，用于追踪当前压力状态和当前的图像质量等级
interface PressureState {
    level: camera.SystemPressureLevel;
    currentQuality: 'HIGH' | 'MEDIUM' | 'LOW';
}

let pressureState: PressureState = {
    level: camera.SystemPressureLevel.NORMAL,
    currentQuality: 'HIGH'
};

// 压力回调的实现
function onSystemPressureLevelChange(err: BusinessError, systemPressureLevel: camera.SystemPressureLevel): void {
    if (err && err.code !== 0) {
        console.error(`System pressure callback error: code ${err.code}, message ${err.message}`);
        return;
    }

    console.info(`System pressure level changed to: ${systemPressureLevel}`);

    // 更新状态
    pressureState.level = systemPressureLevel;

    // 根据压力等级动态调整图像质量
    switch (systemPressureLevel) {
        case camera.SystemPressureLevel.NORMAL:
            if (pressureState.currentQuality !== 'HIGH') {
                console.info("Restoring high-quality video parameters...");
                // 示例：提升帧率为 60fps，恢复高分辨率输出
                // 注意：部分设备可能需要先 stop 再重新配置 VideoOutput
                // 此处仅示意降级/恢复逻辑的骨架
                // 实际操作可调用 videoOutput.setFrameRateRange([60, 60])
                // 和调整预览分辨率等（需重构流）
                pressureState.currentQuality = 'HIGH';
            }
            break;

        case camera.SystemPressureLevel.SEMI_WARNING:
            if (pressureState.currentQuality === 'HIGH') {
                // 轻度降级：维持分辨率不变，但降低预览帧率以减轻 ISP 负载
                console.info("Entering mid-quality mode: reduce preview FPS...");
                // 示例：将预览帧率从 60fps 调整为 30fps
                // previewOutput.setFrameRateRange([30, 30]);
                pressureState.currentQuality = 'MEDIUM';
            }
            break;

        case camera.SystemPressureLevel.WARNING:
            // 中度降级：主动降低录像分辨率和帧率（例如从 4K 30fps 降至 1080p 30fps）
            console.info("Warning mode: reducing video resolution...");
            // 此步骤可能需要重建 VideoOutput 或调整对应参数
            // 实际操作可调用 videoOutput.setFrameRateRange([15, 30]) 
            // 此时建议同步降低预览分辨率
            pressureState.currentQuality = 'LOW';
            break;

        case camera.SystemPressureLevel.CRITICAL:
            // 严重压力：强制执行最激进的降级，例如降至 720p 15fps，甚至暂停预览特效
            console.info("Critical mode: aggressive power-saving, low-quality mode activated...");
            pressureState.currentQuality = 'LOW';
            // 可选：给出用户提示，建议保存录制并稍作等待。
            this.showUserHint("设备发热严重，正在切换至低功耗模式以保证录制稳定性。");
            break;

        default:
            console.warn(`Unknown system pressure level: ${systemPressureLevel}`);
            break;
    }
}

// 注册监听
videoSession.on('systemPressureLevelChange', onSystemPressureLevelChange);

3.4 -> 资源释放

当 Session 不再需要时，务必移除压力监听并释放相机资源。

typescript 复制代码

// 移除监听
videoSession.off('systemPressureLevelChange');

// 停止会话并释放资源
await videoSession.stop();
await videoInput.close();
previewOutput.release();
videoOutput.release();
await videoSession.release();

4 -> C/C++ 开发实现

对于一些高性能相机应用（如含有自定义人脸识别算法的实时流），直接使用 C/C++ Camera API 可以大幅降低采集流水线开销。在压力监听方面，C/C++ 接口同样提供了配套的支持。

4.1 -> 示例代码

c 复制代码

#include "multimedia/camera_framework/native_camera.h"
#include "multimedia/camera_framework/camera_input.h"
#include "multimedia/camera_framework/capture_session.h"
#include "hilog/log.h"

// 回调函数的实现
void SystemPressureLevelChangeCallback(Camera_CaptureSession* captureSession,
                                       Camera_SystemPressureLevel systemPressureLevel) {
    OH_LOG_INFO(LOG_APP, "SystemPressureLevelChangeCallback is called. Level: %{public}d", 
                systemPressureLevel);
    
    // 根据压力等级更新相机的配置参数
    switch(systemPressureLevel) {
        case CAMERA_SEMI_WARNING:
            // 调整预览或录像参数（示例：降低帧率设置）
            // 具体操作需根据实际输出流类型调用相应的 SetFrameRate 接口
            OH_LOG_INFO(LOG_APP, "Semi-warning: reducing frame rate");
            break;
        case CAMERA_WARNING:
            OH_LOG_INFO(LOG_APP, "Warning: reducing resolution");
            break;
        case CAMERA_CRITICAL:
            OH_LOG_INFO(LOG_APP, "Critical: entering low power mode");
            break;
        default:
            break;
    }
}

// 在应用初始化阶段注册回调
Camera_ErrorCode RegisterSystemPressureCallback(Camera_CaptureSession* captureSession) {
    Camera_ErrorCode ret = OH_CaptureSession_RegisterSystemPressureLevelChangeCallback(
        captureSession,
        SystemPressureLevelChangeCallback
    );
    
    if (ret != CAMERA_OK) {
        OH_LOG_ERROR(LOG_APP, 
                     "OH_CaptureSession_RegisterSystemPressureLevelChangeCallback failed: %{public}d", 
                     ret);
        return ret;
    }
    
    OH_LOG_INFO(LOG_APP, "System pressure callback registered successfully");
    return CAMERA_OK;
}

4.2 -> 关于跨语言开销的优势

当压力等级发生变化时，C/C++ 回调直接运行在相机服务所在线程，无需经过 NAPI 调度。对于极其敏感的编码 Pipeline------比如实时游戏直播中需要根据设备温度在 2-3 帧内 调整编码参数------C/C++ 接口的低延迟特性尤为关键。

5 -> 典型应用场景与实际调优策略

5.1 -> 直播应用：长时稳定性优先

直播往往持续数十分钟甚至数小时，对设备发热的挑战最为显著。借助压力监听，直播应用可以实现：

阶梯式降级 ：当系统压力从 SEMI_WARNING 升级至 WARNING 时，立即通知编解码模块将每秒关键帧（IDR）间隔从 2 秒拉长至 5 秒，同时通知推流端降低码率。
主动恢复 ：当压力恢复至 NORMAL 级别时，自动提升码率和帧率，恢复到主播设定的高画质状态。
用户预警 ：在 CRITICAL 状态时在 UI 上弹出非模态提示条，建议主播暂停或结束推流，避免过热导致系统强杀相机服务。

5.2 -> AR 玩法 / 手势识别场景

与 AI 算法集成的相机场景通常会在预览帧上叠加 CPU/NPU 计算负载（例如人脸关键点跟踪、手势识别、动态贴纸）。系统压力监听可以指导应用动态决定是否关闭部分特效层：

NORMAL 状态：所有特效全开。
SEMI_WARNING 状态：关闭部分较耗资源的特效（例如背景替换），保留人脸关键点。
WARNING 状态：仅保留基本的预览和录像功能，关闭所有 NPU 计算类特效。
CRITICAL 状态：停止所有算法推理，仅保留基础相机流。

5.3 -> 高帧率录制：优先保障核心体验

对于高帧率（>60fps）慢动作或运动抓拍场景，当系统压力上升至 WARNING 级别时，应用可以放弃对最大帧率的追求，主动将录制帧率从 120fps 降至 60fps 或 30fps，确保录像不会因过热提前中断。

5.4 -> 监控类相机：稳定性和续航并重

对于安防监控、运动相机等长时间无人值守场景，压力监听可以触发更激进的策略：在 SEMI_WARNING 时即降低预览分辨率，缩减传输带宽；在 CRITICAL 时切换至低分辨率运动检测模式，仅在检测到事件时才输出高画质，从而在续航与关键图像质量之间取得动态平衡。

6 -> 调试技巧与开发建议

6.1 -> 压力等级的触发条件测试

开发者在真机上调试时，可以通过以下手段人为触发压力等级变化：

高强度 CPU 负载法：在测试设备上同时运行后台的性能测试工具（如持续跑 Geekbench 多核负载），然后启动相机应用，观察回调是否如期触发。
发热触发法：连接充电器并关闭散热条件，长时间录制 4K 视频，一段时间后设备温度自然会上升，从而观察到系统压力回调的级别切换。
模拟工具（若厂商提供） ：部分开发版镜像支持通过命令行工具 thermal_service 注入不同的热场景（例如模拟外壳温度 simulate_temperature 55），从而在不实际发热的情况下测试每个压力等级下的应用响应逻辑。

6.2 -> 避免频繁重建流

在压力等级发生变化时，修改 VideoOutput 的分辨率通常涉及先停止流、重新配置 Session 再启动。过于频繁的重建（例如压力在 SEMI_WARNING 和 NORMAL 之间反复震荡）会导致取景画面闪黑。建议的策略是设置防抖动（debounce）计时器，即压力等级变化后延迟 500 毫秒再执行降级动作，若在定时器触发前压力恢复则取消本次降级。

6.3 -> 将压力状态与现有监控机制结合

除了单独监听压力外，建议与此前已有的相机帧率监控机制结合。例如，通过上层的取景渲染回调去计算实际显示的帧率**（实际渲染帧率而非 Surface 提交率）** ，若压力等级为 NORMAL 但实际帧率已明显低于预期（<24fps），可主动触发一次降级，而不完全依赖系统的压力回调，以应对某些未映射到系统压力的个别性能瓶颈。

6.4 -> 压力监听对设备兼容性的考量

需要特别注意的是，并非所有 HarmonyOS 设备都上报完整的四级压力状态。部分中低端设备可能只上报 NORMAL 和 WARNING 两级。开发者在实现业务逻辑时应做好"默认安全"的设计：对于识别不到的压力等级或者未收到任何回调的旧设备，依旧保留原有的固定参数或简单的功耗模式开关。

7 -> 总结

HarmonyOS 6.0 Camera Kit 新增的系统性能压力监听功能，填补了相机应用在系统资源感知层面的长期空白。通过 systemPressureLevelChange 回调，开发者可以将应用的图像质量调度与设备的实时热管理和资源分配策略联动起来。在长时拍摄、直播、高帧率录像和高负载 AI 相机场景中，这一接口使应用能够实现智能化的阶梯式降级和自主恢复，大幅提升了长时运行的稳定性和用户体验。

与此同时，HarmonyOS 6.0 在相机能力上还新增了微距模式切换监听等特性，两者结合更是将相机应用从"被动工具"推向"主动感知、智能响应"的新阶段，也为未来设备折叠形态适配、跨设备分布式相机等高级场景提供了更稳固的性能调度基础。

开发者在主动拥抱该能力的同时，也需结合具体场景的特点设计合理的参数调整策略，并充分考虑中低端设备的兼容性问题。唯有在代码层面精细处理好「何时降级、降级到什么程度、何时恢复」的全流程，才能真正发挥出系统压力监听给应用带来的潜力。

感谢各位大佬支持！！！
互三啦！！！