【HarmonyOS 6.0】AVCodec Kit 视频解码器平滑停用机制详解

文章目录

[1 -> 概述](#1 -> 概述)
[2 -> 问题背景：传统解码器停用的痛点](#2 -> 问题背景：传统解码器停用的痛点)
[3 -> 新特性详解：空白帧平滑过渡](#3 -> 新特性详解：空白帧平滑过渡)
- [3.1 -> 关键属性一览](#3.1 -> 关键属性一览)
- [3.2 -> 为什么选择黑色空白帧](#3.2 -> 为什么选择黑色空白帧)
[4 -> 代码示例：如何配置与使用](#4 -> 代码示例：如何配置与使用)
- [4.1 -> 步骤一：包含必要的头文件](#4.1 -> 步骤一：包含必要的头文件)
- [4.2 -> 步骤二：创建解码器实例并配置参数](#4.2 -> 步骤二：创建解码器实例并配置参数)
- [4.3 -> 步骤三：绑定 Surface 并准备解码器](#4.3 -> 步骤三：绑定 Surface 并准备解码器)
- [4.4 -> 步骤四：回调函数的实现框架](#4.4 -> 步骤四：回调函数的实现框架)
- [4.5 -> 步骤五：停止解码器（体验空白帧输出效果）](#4.5 -> 步骤五：停止解码器（体验空白帧输出效果）)
- [4.6 -> 步骤六：销毁解码器（完整清理）](#4.6 -> 步骤六：销毁解码器（完整清理）)
[5 -> 典型应用场景](#5 -> 典型应用场景)
- [5.1 -> 场景一：视频播放器的关闭与退出](#5.1 -> 场景一：视频播放器的关闭与退出)
- [5.2 -> 场景二：多应用/多页面切换](#5.2 -> 场景二：多应用/多页面切换)
- [5.3 -> 场景三：广告插播与内容切换](#5.3 -> 场景三：广告插播与内容切换)
- [5.4 -> 场景四：多解码器共用 Surface 的复杂场景](#5.4 -> 场景四：多解码器共用 Surface 的复杂场景)
[6 -> 注意事项与最佳实践](#6 -> 注意事项与最佳实践)
[7 -> 技术实现简述](#7 -> 技术实现简述)
[8 -> 总结](#8 -> 总结)

1 -> 概述

在 HarmonyOS 6.0（API 20）版本中，AVCodec Kit 迎来了一项对视频播放体验影响深远的新特性：视频解码器在停止（Stop）或释放（Destroy）时可主动输出一帧空白帧（通常为黑色），以确保显示设备能够平滑过渡到无信号状态，避免画面残留、闪烁或其他视觉异常。

这项特性通过一个可配置的参数 OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN 来控制。当视频解码器停止工作或资源被释放时，传统的处理方式会导致显示设备直接面对"无信号"状态。由于解码器停止后不再向绑定的 Surface（NativeWindow）输送任何新的帧数据，显示设备将保持最后一帧画面，直至系统或驱动层介入将其清除。这个过程极易引发画面残留、短暂闪烁甚至花屏等现象，尤其是在多应用频繁切换、播放器快速启停或涉及多解码器共用同一 Surface 的复杂场景中，用户体验会受到明显的负面影响。

2 -> 问题背景：传统解码器停用的痛点

在深入讲解这项新特性之前，有必要先回顾一下传统的解码器停用流程及其存在的问题。

在 HarmonyOS 的 AVCodec Kit 框架下，一个视频解码器的生命周期通常包括以下几个阶段：创建（CreateByMime / CreateByName）→ 配置（Configure）→ 准备（Prepare）→ 启动（Start）→ 运行（PushInputBuffer / RenderOutputBuffer / FreeOutputBuffer）→ 停止（Stop）→ 销毁（Destroy）。其中，OH_VideoDecoder_Stop 接口用于暂停解码操作并释放输入输出 buffer，解码器进入 Stopped 状态，但资源配置得以保留；OH_VideoDecoder_Destroy 接口则用于彻底清理解码器内部资源，销毁解码器实例。

问题在于：当 Stop 或 Destroy 被调用后，解码器将不再向与之绑定的 Surface（通常来自 XComponent 或 OpenGL 渲染表面）输出任何新的视频帧。此时，如果显示设备（如屏幕或外部显示器）没有收到新的帧数据，驱动层通常会保持最后一帧的画面。这种情况在视频播放器关闭、应用切换、或用户快速切换播放内容时尤为明显，最后一帧会短暂"残留在屏幕上"，随后屏幕可能闪烁一下才恢复正常------这正是传统解码器停用流程在视觉层面的"硬着陆"问题。

更复杂的场景还包括多解码器共用同一个 Surface 的情况------如果在一个解码器停止后、另一个解码器启动之前，Surface 上残留的最后一帧画面会直接呈现给用户，造成视觉上的混乱。开发者需要额外编写大量的"擦屁股"代码来主动清除 Surface 上的残留画面，增加了实现的复杂度和维护成本。

3 -> 新特性详解：空白帧平滑过渡

HarmonyOS 6.0 引入的空白帧输出特性，从系统层面优雅地解决了上述问题。其核心思想非常直观：在视频解码器即将停止或销毁之前，主动向 Surface 输出一帧空白帧（通常为黑色），用一帧"干净"的画面替代可能造成视觉残留的最后一帧，从而实现显示设备到无信号状态之间的平滑过渡。

这项特性通过配置参数 OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN 来控制。该参数定义在 native_avcodec_base.h 头文件中，属于 CodecBase 模块的能力范围。

3.1 -> 关键属性一览

属性	说明
键名	`OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN`
值类型	`int32_t`（0 或 1）
1（启用）	解码器在 Stop 或 Destroy 时输出一帧空白帧（通常为黑色）
0（禁用）	解码器直接停止，不输出空白帧
默认值	0（禁用）
适用模式	仅 Surface 模式
可用版本	API Level 20（HarmonyOS 6.0）及以上
可选性	可选参数

以上信息整理自 API 文档。

需要特别说明的是，该参数仅在 Surface 模式下生效 。所谓 Surface 模式，是指解码器通过 OH_VideoDecoder_SetSurface 接口绑定一个 OHNativeWindow 实例，解码后的帧直接渲染到该 Surface 上（通常对应屏幕上的一个显示区域）。与之相对的是 Buffer 模式------解码器将解码后的 YUV 数据输出到共享内存 buffer 中，由应用自行处理（如二次处理、编码或拷贝到渲染管线）。由于 Buffer 模式下解码器不直接控制屏幕显示，空白帧的主动输出并无实际意义。

3.2 -> 为什么选择黑色空白帧

从心理学和视觉体验的角度来看，黑色是最理想的"过渡色"。在大多数观看场景中，黑色意味着"无内容"，与随后出现的无信号状态（通常是黑屏）在视觉上保持了连贯性。如果选择其他颜色（如白色或蓝色），在过渡瞬间会给用户造成"画面闪了一下"的感觉，反而适得其反。因此，系统默认输出黑色空白帧是一个经过深思熟虑的设计决策。

4 -> 代码示例：如何配置与使用

下面通过完整的代码示例，演示如何在 Surface 模式下正确配置并使用空白帧输出特性。以下代码以 C/C++ 编写，基于 HarmonyOS 6.0（API 20）及以上版本的 AVCodec Kit API。

4.1 -> 步骤一：包含必要的头文件

cpp 复制代码

#include <multimedia/player_framework/native_avcodec_videodecoder.h>
#include <multimedia/player_framework/native_avcodec_base.h>
#include <multimedia/player_framework/native_avcapability.h>
#include <multimedia/player_framework/native_avformat.h>
#include <multimedia/player_framework/native_avbuffer.h>
#include <multimedia/player_framework/native_window.h>

native_avcodec_base.h 提供了 OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN 等编解码基础参数的定义，必须包含。

4.2 -> 步骤二：创建解码器实例并配置参数

cpp 复制代码

// 根据 MIME 类型创建视频解码器实例
OH_AVCodec *videoDecoder = OH_VideoDecoder_CreateByMime(OH_AVCODEC_MIMETYPE_VIDEO_AVC);
if (videoDecoder == nullptr) {
    // 创建失败处理
    return;
}

// 创建 AVFormat 用于配置解码器参数
OH_AVFormat *format = OH_AVFormat_Create();

// 设置视频基本参数
OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, 1920);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, 1080);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV12);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_FRAME_RATE, 30);
OH_AVFormat_SetLongValue(format, OH_MD_KEY_BITRATE, 4000000);

// ★ 核心配置：启用停止/销毁时输出空白帧
OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN, 1);

// 配置解码器
OH_AVErrCode ret = OH_VideoDecoder_Configure(videoDecoder, format);
if (ret != AV_ERR_OK) {
    // 配置失败处理
    OH_AVFormat_Destroy(format);
    OH_VideoDecoder_Destroy(videoDecoder);
    return;
}

OH_AVFormat_Destroy(format);

以上代码中，最关键的一行是 OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN, 1)，它正是开启空白帧输出功能的开关。如果不设置或设置为 0，解码器将按传统方式运行，停止时不会输出空白帧。

4.3 -> 步骤三：绑定 Surface 并准备解码器

cpp 复制代码

// 获取 Surface 对应的 OHNativeWindow（通常来自 XComponent）
// 此处假设已经通过 XComponent 或图形接口获取到了 nativeWindow
OHNativeWindow *nativeWindow = /* 从 XComponent 或其他途径获取 */;

// 将 Surface 绑定到解码器（Surface 模式）
ret = OH_VideoDecoder_SetSurface(videoDecoder, nativeWindow);
if (ret != AV_ERR_OK) {
    // 绑定失败处理
    OH_VideoDecoder_Destroy(videoDecoder);
    return;
}

// 注册异步回调函数（在 Prepare 之前调用）
OH_AVCodecCallback callback = {
    .onError = OnError,
    .onStreamChanged = OnStreamChanged,
    .onNeedInputBuffer = OnNeedInputBuffer,
    .onNewOutputBuffer = OnNewOutputBuffer
};
ret = OH_VideoDecoder_RegisterCallback(videoDecoder, callback, nullptr);
if (ret != AV_ERR_OK) {
    // 回调注册失败处理
    OH_VideoDecoder_Destroy(videoDecoder);
    return;
}

// 准备解码器（预分配编解码资源）
ret = OH_VideoDecoder_Prepare(videoDecoder);
if (ret != AV_ERR_OK) {
    // 准备失败处理
    OH_VideoDecoder_Destroy(videoDecoder);
    return;
}

// 启动解码器，进入 Running 状态
ret = OH_VideoDecoder_Start(videoDecoder);
if (ret != AV_ERR_OK) {
    // 启动失败处理
    OH_VideoDecoder_Destroy(videoDecoder);
    return;
}

值得注意的是，空白帧输出特性仅在 Surface 模式下有意义。如果解码器没有通过 OH_VideoDecoder_SetSurface 绑定 Surface，配置该参数不会产生任何实际效果。

4.4 -> 步骤四：回调函数的实现框架

cpp 复制代码

// 错误回调
void OnError(OH_AVCodec *codec, int32_t errorCode, void *userData) {
    // 处理解码错误
}

// 流信息变更回调
void OnStreamChanged(OH_AVCodec *codec, OH_AVFormat *format, void *userData) {
    // 处理流信息变更（如分辨率变化等）
}

// 需要输入数据回调
void OnNeedInputBuffer(OH_AVCodec *codec, uint32_t index, OH_AVBuffer *buffer, void *userData) {
    // 将要解码的码流数据写入 buffer
    // 示例：从码流队列中获取一帧数据
    // size_t dataSize = GetNextFrameData(bufferData);
    // OH_AVBuffer_SetRange(buffer, 0, dataSize);
    // OH_AVBuffer_SetFlag(buffer, AVCODEC_BUFFER_FLAGS_NONE);
    // OH_VideoDecoder_PushInputBuffer(codec, index);
}

// 新输出数据回调（Surface 模式下通常不在此处显式处理）
void OnNewOutputBuffer(OH_AVCodec *codec, uint32_t index, OH_AVBuffer *buffer, void *userData) {
    // Surface 模式下，解码帧会自动渲染到绑定的 Surface
    // 可在此处获取输出 buffer 的元信息，如 PTS 等
    // OH_VideoDecoder_RenderOutputBuffer(codec, index);  // Surface 模式
    // 或 OH_VideoDecoder_FreeOutputBuffer(codec, index); // Buffer 模式
}

回调函数的具体实现需要根据业务场景进行定制。在 Surface 模式下，OnNewOutputBuffer 回调中通常调用 OH_VideoDecoder_RenderOutputBuffer 将解码帧送入 Surface 进行渲染。

4.5 -> 步骤五：停止解码器（体验空白帧输出效果）

cpp 复制代码

// 停止解码器（此时将输出一帧黑色空白帧）
ret = OH_VideoDecoder_Stop(videoDecoder);
if (ret != AV_ERR_OK) {
    // 停止失败处理
}

当 Stop 被调用时，如果已经通过配置参数启用了空白帧输出功能，解码器将在停止流程中向绑定的 Surface 输出一帧黑色空白帧。用户将看到最后一帧画面被黑色帧"替换"，随后屏幕保持黑屏状态（或根据应用场景显示其他 UI），整个过程自然平滑，没有突兀的画面残留或闪烁。

4.6 -> 步骤六：销毁解码器（完整清理）

cpp 复制代码

// 销毁解码器实例，彻底释放资源
ret = OH_VideoDecoder_Destroy(videoDecoder);
if (ret != AV_ERR_OK) {
    // 销毁失败处理
}
videoDecoder = nullptr;

Destroy 同样会触发空白帧输出（如果已启用）。需要注意的是，Destroy 不能在回调线程中调用，否则可能导致死锁或资源释放异常。在实际开发中，Flush、Reset、Stop 和 Destroy 在非回调线程中执行时，系统会等待所有回调执行完成后才返回结果。

5 -> 典型应用场景

这项新特性在以下场景中具有重要的实用价值：

5.1 -> 场景一：视频播放器的关闭与退出

用户点击播放器的"关闭"按钮或退出应用时，视频解码器被销毁。启用空白帧输出后，播放画面会平滑过渡到黑屏，而不是在最后一帧上"定格"后再消失，大大提升了应用的精致感和专业性。

5.2 -> 场景二：多应用/多页面切换

在平板、折叠屏或车载系统等大屏设备上，用户可能频繁在多个应用或页面之间切换。每个应用退出时输出一帧黑色空白帧，可以避免上一应用的最后一帧"残留在屏幕上"并闪现到下一个应用的启动画面中，确保多任务切换时的视觉连贯性。

5.3 -> 场景三：广告插播与内容切换

在视频点播（VOD）或直播应用中，播放器需要在正片和广告之间快速切换。传统的切换方式可能在正片最后一帧和广告首帧之间出现短暂的画面残留或撕裂。启用空白帧输出后，切换过程变为"正片 → 黑帧 → 广告"，过渡更加平滑。

5.4 -> 场景四：多解码器共用 Surface 的复杂场景

某些高性能应用（如 VR 播放器或视频编辑器）可能需要多个解码器共用同一个 Surface 进行渲染。当一个解码器停止而另一个尚未启动时，空白帧输出可以确保 Surface 上不会残留上一个解码器的最后一帧，避免了"画面错乱"的问题。

6 -> 注意事项与最佳实践

尽管这项特性本身设计得相当简洁，但在实际开发中仍有几个细节值得留意：

Surface 模式前提：该特性仅在 Surface 模式下生效。如果解码器没有绑定 Surface，配置该参数不会有任何效果。
API 版本要求 ：OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN 从 API Level 20（HarmonyOS 6.0）开始支持。开发时请确保项目的 targetSdkVersion 不低于 20，并在代码中做好版本兼容性检查。
Stop 后重新启动的注意事项 ：停止解码器后，可以通过 OH_VideoDecoder_Start 重新进入 Running 状态。但需要注意的是，如果编解码器特定数据（Codec-Specific-Data，如 H.264 的 SPS/PPS）先前已经输入过解码器，重新启动后需要再次输入。
与其他清理操作的关系 ：Flush 操作用于清除解码器中缓存的输入和输出数据及参数集（如 H.264 格式的 PPS/SPS），但 Flush 本身不会触发空白帧输出。空白帧输出仅与 Stop 和 Destroy 操作相关联。
性能开销：输出一帧空白帧的开销极小（通常只是向 Surface 写入一帧纯色像素数据），对系统资源和性能几乎没有影响。开发者可以放心地在所有适用场景中启用该功能。
与其他参数的协同配置 ：在 Configure 阶段配置解码器参数时，除了 OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN，还需要正确配置 OH_MD_KEY_WIDTH、OH_MD_KEY_HEIGHT、OH_MD_KEY_PIXEL_FORMAT 等基础参数，否则解码器可能无法正常工作。

7 -> 技术实现简述

从系统实现的角度来看，空白帧输出功能的引入涉及 AVCodec Kit 底层解码器管线的改造。当 OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN 被设置为 1 时，解码器的 Stop 和 Destroy 流程中会触发一个特殊的分支：在释放硬件解码资源之前，系统会生成一帧固定颜色（黑色）的帧数据，并通过与 Surface 绑定的 OHNativeWindow 输出到显示设备。这一帧数据在格式、尺寸和时序上与解码器正在处理的视频流保持兼容，确保显示设备能够正确接收和渲染。

由于这一过程发生在解码器内部，应用层无需感知其具体实现细节，只需在配置阶段设置好参数，后续的 Stop 和 Destroy 调用会自动触发空白帧输出。

8 -> 总结

HarmonyOS 6.0 AVCodec Kit 新增的视频解码器停止/释放时输出空白帧特性，是一个看似微小但意义深远的用户体验优化。它从系统层面解决了长期困扰视频应用开发者的"最后一帧残留"问题，让应用退出和内容切换的视觉体验更加顺滑自然。

对于开发者而言，启用这项特性只需在配置解码器时添加一行代码：

cpp 复制代码

OH_AVFormat_SetIntValue(format, OH_MD_KEY_VIDEO_DECODER_BLANK_FRAME_ON_SHUTDOWN, 1);

极低的接入成本换来的却是用户可感知的体验提升。无论是在视频播放器、直播应用、VR/AR 应用还是车载信息娱乐系统中，这项特性都值得被纳入开发者的"最佳实践清单"。

随着 HarmonyOS 生态的不断成熟，AVCodec Kit 作为媒体子系统的原子能力支柱，将持续为开发者提供更加完善、更加人性化的音视频处理能力。空白帧输出特性的加入，正是这一演进方向上的一个缩影。

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