!19919 添加av_codec指南

Merge pull request !19919 from hongran1206/master

zh-cn/application-dev/media/audio-decoding.md

+# 音频解码
+
+开发者可以调用本模块的Native API接口，完成音频解码，即将媒体数据解码为PCM码流。
+
+当前支持的解码能力如下:
+
+| 容器规格 | 音频解码类型                 |
+| -------- | :--------------------------- |
+| mp4      | AAC、MPEG(MP3)、Flac、Vorbis |
+| m4a      | AAC                          |
+| flac     | Flac                         |
+| ogg      | Vorbis                       |
+| aac      | AAC                          |
+| mp3      | MPEG(MP3)                    |
+
+**适用场景**
+
+- 音频播放
+
+  在播放音频之前，需要先解码音频，再将数据输送到硬件扬声器播放。
+- 音频渲染
+
+  在对音频文件进行音效处理之前，需要先解码再由音频处理模块进行音频渲染。
+- 音频编辑
+
+  音频编辑（如调整单个声道的播放倍速等）需要基于PCM码流进行，所以需要先将音频文件解码。
+
+## 开发步骤
+
+详细的API说明请参考[API文档](../reference/native-apis/_audio_decoder.md)。
+参考以下示例代码，完成音频解码的全流程，包括：创建解码器，设置解码参数（采样率/码率/声道数等），开始，刷新，重置，销毁资源。
+
+在应用开发过程中，开发者应按一定顺序调用方法，执行对应操作，否则系统可能会抛出异常或生成其他未定义的行为。具体顺序可参考下列开发步骤及对应说明。
+完整代码请参考[示例程序](https://gitee.com/openharmony/multimedia_av_codec/blob/master/test/nativedemo/audio_demo/avcodec_audio_decoder_demo.cpp)
+
+1. 创建解码器实例对象
+
+```cpp
+//通过 codecname 创建解码器
+OH_AVCapability *capability = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_AUDIO_MPEG, false);
+const char *name = OH_AVCapability_GetName(capability);
+OH_AVCodec *audioDec = OH_AudioDecoder_CreateByName(name);
+```
+
+```cpp
+//通过 Mimetype 创建解码器
+OH_AVCodec *audioDec = OH_AudioDecoder_CreateByMime(OH_AVCODEC_MIMETYPE_AUDIO_MPEG);
+```
+
+```cpp
+// 初始化队列
+class ADecSignal {
+public:
+    std::mutex inMutex_;
+    std::mutex outMutex_;
+    std::mutex startMutex_;
+    std::condition_variable inCond_;
+    std::condition_variable outCond_;
+    std::condition_variable startCond_;
+    std::queue<uint32_t> inQueue_;
+    std::queue<uint32_t> outQueue_;
+    std::queue<OH_AVMemory *> inBufferQueue_;
+    std::queue<OH_AVMemory *> outBufferQueue_;
+    std::queue<OH_AVCodecBufferAttr> attrQueue_;
+};
+ADecSignal *signal_;
+```
+
+2. 调用OH_AudioDecoder_SetCallback()设置回调函数。
+   注册回调函数指针集合OH_AVCodecAsyncCallback，包括：
+   - 解码器运行错误
+   - 码流信息变化，如声道变化等。
+   - 运行过程中需要新的输入数据，即解码器已准备好，可以输入数据。
+   - 运行过程中产生了新的输出数据，即解码完成。
+
+   开发者可以通过处理该回调报告的信息，确保解码器正常运转。
+
+ ```cpp
+ // 设置 OnError 回调函数
+ static void OnError(OH_AVCodec *codec, int32_t errorCode, void *userData)
+ {
+     (void)codec;
+     (void)errorCode;
+     (void)userData;
+ }
+ // 设置 FormatChange 回调函数
+ static void OnOutputFormatChanged(OH_AVCodec *codec, OH_AVFormat *format, void*userData)
+ {
+     (void)codec;
+     (void)format;
+     (void)userData;
+ }
+ // 解码输入码流送入InputBuffer 队列
+ static void OnInputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory*data, void *userData)
+ {
+     (void)codec;
+     ADecSignal *signal = static_cast<ADecSignal *>(userData);
+     unique_lock<mutex> lock(signal->inMutex_);
+     signal->inQueue_.push(index);
+     signal->inBufferQueue_.push(data);
+     signal->inCond_.notify_all();
+     // 解码输入码流送入InputBuffer 队列
+ }
+ // 解码完成的PCM送入OutputBuffer队列
+ static void OnOutputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory*data, OH_AVCodecBufferAttr *attr,
+                                         void *userData)
+ {
+     (void)codec;
+     ADecSignal *signal = static_cast<ADecSignal *>(userData);
+     unique_lock<mutex> lock(signal->outMutex_);
+     signal->outQueue_.push(index);
+     signal->outBufferQueue_.push(data);
+     if (attr) {
+         signal->attrQueue_.push(*attr);
+     }
+     signal->outCond_.notify_all();
+     // 将对应输出buffer的 index 送入OutputQueue_队列
+     // 将对应解码完成的数据data送入outBuffer队列
+ }
+ signal_ = new ADecSignal();
+ OH_AVCodecAsyncCallback cb = {&OnError, &OnOutputFormatChanged, OnInputBufferAvailable, &OnOutputBufferAvailable};
+ // 配置异步回调
+ int32_t ret = OH_AudioDecoder_SetCallback(audioDec, cb, signal_);
+ if (ret != AV_ERR_OK) {
+     // 异常处理
+ }
+ ```
+3. 调用OH_AudioDecoder_Configure()配置解码器。
+   配置必选项：采样率、码率、声道数；可选项：最大输入长度。
+
+   - AAC解码 需要额外标识是否为adts类型否则会被认为是latm类型
+
+   - vorbis解码 需要额外标识ID Header和Setup Header数据
+```cpp
+enum AudioFormatType : int32_t {
+    TYPE_AAC = 0,
+    TYPE_FLAC = 1,
+    TYPE_MP3 = 2,
+    TYPE_VORBIS = 3,
+};  
+// 设置解码分辨率
+int32_t ret;
+// 配置音频采样率（必须）
+constexpr uint32_t DEFAULT_SMAPLERATE = 44100; 
+// 配置音频码率（必须）
+constexpr uint32_t DEFAULT_BITRATE = 32000;
+// 配置音频声道数（必须）
+constexpr uint32_t DEFAULT_CHANNEL_COUNT = 2;
+// 配置最大输入长度（可选）
+constexpr uint32_t DEFAULT_MAX_INPUT_SIZE = 1152;
+OH_AVFormat *format = OH_AVFormat_Create();
+// 写入format
+OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_SAMPLE_RATE.data(),DEFAULT_SMAPLERATE);
+OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_BITRATE.data(),DEFAULT_BITRATE);
+OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_CHANNEL_COUNT.data(),DEFAULT_CHANNEL_COUNT);
+OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_MAX_INPUT_SIZE.data(),DEFAULT_MAX_INPUT_SIZE);
+if (audioType == TYPE_AAC) {
+    OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_AAC_IS_ADTS.data(), DEFAULT_AAC_TYPE);
+}
+if (audioType == TYPE_VORBIS) {
+    OH_AVFormat_SetStringValue(format, MediaDescriptionKey::MD_KEY_IDENTIFICATION_HEADER.data(), DEFAULT_ID_HEADER);
+    OH_AVFormat_SetStringValue(format, MediaDescriptionKey::MD_KEY_SETUP_HEADER.data(), DEFAULT_SETUP_HEADER);
+}
+// 配置解码器
+ret = OH_AudioDecoder_Configure(audioDec, format);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+4. 调用OH_AudioDecoder_Prepare()，解码器就绪。
+
+```cpp
+ret = OH_AudioDecoder_Prepare(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+5. 调用OH_AudioDecoder_Start()启动解码器，进入运行态。
+
+```c++
+inputFile_ = std::make_unique<std::ifstream>();
+// 打开待解码二进制文件路径
+inputFile_->open(inputFilePath.data(), std::ios::in | std::ios::binary); 
+//配置解码文件输出路径
+outFile_ = std::make_unique<std::ofstream>();
+outFile_->open(outputFilePath.data(), std::ios::out | std::ios::binary);
+// 开始解码
+ret = OH_AudioDecoder_Start(audioDec);
+if (ret != AV_ERR_OK) {
+   // 异常处理
+}
+```
+6. 调用OH_AudioDecoder_PushInputData()，写入待解码的数据。
+   如果是结束，需要对flag标识成AVCODEC_BUFFER_FLAGS_EOS
+```c++
+// 配置buffer info信息
+OH_AVCodecBufferAttr info;
+// 设置输入pkt尺寸、偏移量、时间戳等信息
+info.size = pkt_->size;
+info.offset = 0;
+info.pts = pkt_->pts;
+info.flags = AVCODEC_BUFFER_FLAGS_CODEC_DATA;
+auto buffer = signal_->inBufferQueue_.front();
+if (inputFile_->eof()){
+     info.size = 0;
+     info.flags = AVCODEC_BUFFER_FLAGS_EOS;
+}else{
+    inputFile_->read((char *)OH_AVMemory_GetAddr(buffer), INPUT_FRAME_BYTES);
+}
+uint32_t index = signal_->inQueue_.front();
+// 送入解码输入队列进行解码, index为对应队列下标
+int32_t ret = OH_AudioDecoder_PushInputData(audioDec, index, info);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+7. 调用OH_AudioDecoder_FreeOutputData()，输出解码后的PCM码流
+
+```c++
+OH_AVCodecBufferAttr attr = signal_->attrQueue_.front();
+OH_AVMemory *data = signal_->outBufferQueue_.front();
+uint32_t index = signal_->outQueue_.front();
+// 将解码完成数据data写入到对应输出文件中
+outFile_->write(reinterpret_cast<char *>(OH_AVMemory_GetAddr(data)), attr.size);
+// buffer 模式, 释放已完成写入的数据
+ret = OH_AudioDecoder_FreeOutputData(audioDec, index);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+8. （可选）调用OH_AudioDecoder_Flush()刷新解码器。
+    调用OH_AudioDecoder_Flush()后，解码器仍处于运行态，但会将当前队列清空，将已解码的数据释放。
+    此时需要调用OH_AudioDecoder_Start()重新开始解码。
+    使用情况：
+    * 在文件EOS之后，需要调用刷新
+    * 在执行过程中遇到可继续执行的错误时（即OH_AudioDecoder_IsValid 为true）调用
+```c++
+// 刷新解码器 audioDec
+ret = OH_AudioDecoder_Flush(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+// 重新开始解码
+ret = OH_AudioDecoder_Start(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+9. （可选）调用OH_AudioDecoder_Reset()重置解码器。
+调用OH_AudioDecoder_Reset()后，解码器回到初始化的状态，需要调用OH_AudioDecoder_Configure()重新配置，然后调用OH_AudioDecoder_Start()重新开始解码。
+```c++
+// 重置解码器 audioDec
+ret = OH_AudioDecoder_Reset(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+// 重新配置解码器参数
+ret = OH_AudioDecoder_Configure(audioDec, format);
+if (ret != AV_ERR_OK) {
+   // 异常处理
+}
+```
+10. 调用OH_AudioDecoder_Stop()停止解码器。
+
+```c++
+// 终止解码器 audioDec
+ret = OH_AudioDecoder_Stop(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+return ret;
+```
+11. 调用OH_AudioDecoder_Destroy()销毁解码器实例，释放资源。
+    **注意**：不要重复销毁解码器
+
+```c++
+// 调用OH_AudioDecoder_Destroy, 注销解码器
+ret = OH_AudioDecoder_Destroy(audioDec);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+} else {
+    audioDec = NULL; //不可重复destroy
+}
+return ret;
+```

zh-cn/application-dev/media/audio-encoding.md

+# 音频编码
+
+开发者可以调用本模块的Native API接口，完成音频编码，即将音频PCM编码压缩成不同的格式。
+
+接口不限制PCM数据的来源，开发者可以调用麦克风录制获取、也可以导入编辑后的PCM数据，通过音频编码，输出对应格式的码流，最后封装为目标格式文件。
+
+当前支持的编码能力如下：
+
+| 容器规格 | 音频编码类型 |
+| -------- | :----------- |
+| mp4      | AAC、Flac    |
+| m4a      | AAC          |
+| flac     | Flac         |
+| aac      | AAC          |
+
+**适用场景**
+
+- 音频录制
+
+  通过录制传入PCM，然后编码出对应格式的码流，最后封装成想要的格式
+- 音频编辑
+
+  编辑PCM后导出音频文件的场景，需要编码成对应音频格式后再封装成文件
+
+## 开发步骤
+
+详细的API说明请参考[API文档](../reference/native-apis/_audio_encoder.md)。
+
+参考以下示例代码，完成音频编码的全流程，包括：创建编码器，设置编码参数（采样率/码率/声道数等），开始，刷新，重置，销毁资源。
+
+在应用开发过程中，开发者应按一定顺序调用方法，执行对应操作，否则系统可能会抛出异常或生成其他未定义的行为。具体顺序可参考下列开发步骤及对应说明。
+
+完整代码请参考[示例程序](https://gitee.com/openharmony/multimedia_av_codec/blob/master/test/nativedemo/audio_demo/avcodec_audio_aac_encoder_demo.cpp)
+
+1. 创建编码器实例对象
+
+   应用可以通过名称或媒体类型创建编码器。
+
+```cpp
+//通过 codecname 创建编码器
+OH_AVCapability *capability = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_AUDIO_AAC, true);
+const char *name = OH_AVCapability_GetName(capability);
+OH_AVCodec *audioEnc = OH_AudioEncoder_CreateByName(name);
+```
+
+```cpp
+//通过 codecname 创建编码器
+OH_AVCodec *audioEnc = OH_AudioEncoder_CreateByMime(OH_AVCODEC_MIMETYPE_AUDIO_AAC); 
+```
+
+```cpp
+// 初始化队列
+class AEncSignal {
+public:
+    std::mutex inMutex_;
+    std::mutex outMutex_;
+    std::mutex startMutex_;
+    std::condition_variable inCond_;
+    std::condition_variable outCond_;
+    std::condition_variable startCond_;
+    std::queue<uint32_t> inQueue_;
+    std::queue<uint32_t> outQueue_;
+    std::queue<OH_AVMemory *> inBufferQueue_;
+    std::queue<OH_AVMemory *> outBufferQueue_;
+    std::queue<OH_AVCodecBufferAttr> attrQueue_;
+};
+AEncSignal *signal_ = new AEncSignal();
+```
+
+2. 调用OH_AudioEncoder_SetCallback()设置回调函数。
+
+   注册回调函数指针集合OH_AVCodecAsyncCallback，包括：
+
+   - 编码器运行错误
+   - 码流信息变化，如声道变化等。
+   - 运行过程中需要新的输入数据，即编码器已准备好，可以输入PCM数据。
+   - 运行过程中产生了新的输出数据，即编码完成。
+
+   开发者可以通过处理该回调报告的信息，确保编码器正常运转。
+
+```cpp
+// 设置 OnError 回调函数
+static void OnError(OH_AVCodec *codec, int32_t errorCode, void *userData)
+{
+    (void)codec;
+    (void)errorCode;
+    (void)userData;
+}
+// 设置 FormatChange 回调函数
+static void OnOutputFormatChanged(OH_AVCodec *codec, OH_AVFormat *format, void *userData)
+{
+    (void)codec;
+    (void)format;
+    (void)userData;
+}
+// 编码输入PCM送入InputBuffer 队列
+static void OnInputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory *data, void *userData)
+{
+    (void)codec;
+    // 编码输入码流送入InputBuffer 队列
+    AEncSignal *signal = static_cast<AEncSignal *>(userData);
+    cout << "OnInputBufferAvailable received, index:" << index << endl;
+    unique_lock<mutex> lock(signal->inMutex_);
+    signal->inQueue_.push(index);
+    signal->inBufferQueue_.push(data);
+    signal->inCond_.notify_all();
+}
+// 编码完成的码流送入OutputBuffer队列
+static void OnOutputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory *data, OH_AVCodecBufferAttr *attr,
+                                           void *userData)
+{
+    (void)codec;
+    // 将对应输出buffer的 index 送入OutputQueue_队列
+    // 将对应编码完成的数据data送入outBuffer队列
+    AEncSignal *signal = static_cast<AEncSignal *>(userData);
+    unique_lock<mutex> lock(signal->outMutex_);
+    signal->outQueue_.push(index);
+    signal->outBufferQueue_.push(data);
+    if (attr) {
+        signal->attrQueue_.push(*attr);
+    }
+}
+OH_AVCodecAsyncCallback cb = {&OnError, &OnOutputFormatChanged, &OnInputBufferAvailable, &OnOutputBufferAvailable};
+// 配置异步回调
+int32_t ret = OH_AudioEncoder_SetCallback(audioEnc, cb, userData);
+```
+
+3. 调用OH_AudioEncoder_Configure设置编码器
+   设置必选项：采样率，码率，以及声道数，声道类型、位深；可选项：最大输入长度
+   flac编码： 需要额外标识兼容性级别(Compliance Level)和采样精度
+
+```cpp
+enum AudioFormatType : int32_t {
+    TYPE_AAC = 0,
+    TYPE_FLAC = 1,
+};
+int32_t ret;
+// 配置音频采样率（必须）
+constexpr uint32_t DEFAULT_SMAPLERATE = 44100; 
+// 配置音频码率（必须）
+constexpr uint32_t DEFAULT_BITRATE = 32000;
+// 配置音频声道数（必须）
+constexpr uint32_t DEFAULT_CHANNEL_COUNT = 2;
+// 配置音频声道类型（必须）
+constexpr AudioChannelLayout CHANNEL_LAYOUT =AudioChannelLayout::STEREO;
+// 配置音频位深（必须） flac 只有SAMPLE_S16LE和SAMPLE_S32LE
+constexpr OH_BitsPerSample SAMPLE_FORMAT =OH_BitsPerSample::SAMPLE_S32LE;
+// 配置音频位深（必须）aac只有SAMPLE_S32P
+constexpr OH_BitsPerSample SAMPLE_AAC_FORMAT =OH_BitsPerSample::SAMPLE_S32P;
+// 配置音频compliance level (默认值0，取值范围-2~2)
+constexpr int32_t COMPLIANCE_LEVEL = 0;
+// 配置音频精度（必须） SAMPLE_S16LE和SAMPLE_S24LE和SAMPLE_S32LE
+constexpr BITS_PER_CODED_SAMPLE BITS_PER_CODED_SAMPLE =OH_BitsPerSample::SAMPLE_S24LE;
+// 配置最大输入长度（可选）
+constexpr uint32_t DEFAULT_MAX_INPUT_SIZE = 1024*2*4;//aac
+OH_AVFormat *format = OH_AVFormat_Create();
+// 写入format
+OH_AVFormat_SetIntValue(format,MediaDescriptionKey::MD_KEY_SAMPLE_RATE.data(),DEFAULT_SMAPLERATE);
+OH_AVFormat_SetIntValue(format,MediaDescriptionKey::MD_KEY_BITRATE.data(), DEFAULT_BITRATE);
+OH_AVFormat_SetIntValue(format,MediaDescriptionKey::MD_KEY_CHANNEL_COUNT.data(),DEFAULT_CHANNEL_COUNT);
+OH_AVFormat_SetIntValue(format,MediaDescriptionKey::MD_KEY_MAX_INPUT_SIZE.data(),DEFAULT_MAX_INPUT_SIZE);
+OH_AVFormat_SetLongValue(format,MediaDescriptionKey::MD_KEY_CHANNEL_LAYOUT.data(),CHANNEL_LAYOUT);
+OH_AVFormat_SetIntValue(format,MediaDescriptionKey::MD_KEY_AUDIO_SAMPLE_FORMAT.data(),SAMPLE_FORMAT);
+if(audioType == TYPE_AAC){
+    OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_AUDIO_SAMPLE_FORMAT.data(), SAMPLE_AAC_FORMAT);
+}
+if (audioType == TYPE_FLAC) {
+    OH_AVFormat_SetIntValue(format, MediaDescriptionKey::MD_KEY_BITS_PER_CODED_SAMPLE.data(), BITS_PER_CODED_SAMPLE);
+    OH_AVFormat_SetLongValue(format, MediaDescriptionKey::MD_KEY_COMPLIANCE_LEVEL.data(), COMPLIANCE_LEVEL);
+}
+// 配置编码器
+ret = OH_AudioEncoder_Configure(audioEnc, format);
+if (ret != AV_ERR_OK) {
+     // 异常处理
+}
+```
+
+4. 调用OH_AudioEncoder_Prepare()，编码器就绪。
+
+```c++
+OH_AudioEncoder_Prepare(audioEnc);
+```
+
+5. 调用OH_AudioEncoder_Start()启动编码器，进入运行态。
+
+```c++
+inputFile_ = std::make_unique<std::ifstream>();
+// 打开待编码二进制文件路径
+inputFile_->open(inputFilePath.data(), std::ios::in |std::ios::binary); 
+//配置编码文件输出路径
+outFile_ = std::make_unique<std::ofstream>();
+outFile_->open(outputFilePath.data(), std::ios::out |std::ios::binary);
+// 开始编码
+ret = OH_AudioEncoder_Start(audioEnc);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+
+6. 调用OH_AudioEncoder_PushInputData()，写入待编码器的数据。
+   如果是结束，需要对flag标识成AVCODEC_BUFFER_FLAGS_EOS
+
+```c++
+constexpr int32_t INPUT_FRAME_BYTES = 2 * 1024 * 4;
+// 配置buffer info信息
+OH_AVCodecBufferAttr info;
+// 设置输入pkt尺寸、偏移量、时间戳等信息
+info.size = pkt_->size;
+info.offset = 0;
+info.pts = pkt_->pts;
+info.flags = AVCODEC_BUFFER_FLAGS_CODEC_DATA;
+auto buffer = signal_->inBufferQueue_.front();
+if (inputFile_->eof()){
+     info.size = 0;
+     info.flags = AVCODEC_BUFFER_FLAGS_EOS;
+}else{
+    inputFile_->read((char *)OH_AVMemory_GetAddr(buffer), INPUT_FRAME_BYTES);
+}
+uint32_t index = signal_->inQueue_.front();
+// 送入编码输入队列进行编码, index为对应队列下标
+int32_t ret = OH_AudioEncoder_PushInputData(audioEnc, index,info);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+```
+
+7. 调用OH_AudioEncoder_FreeOutputData()，输出编码格式码流
+
+```c++
+OH_AVCodecBufferAttr attr = signal_->attrQueue_.front();
+OH_AVMemory *data = signal_->outBufferQueue_.front();
+uint32_t index = signal_->outQueue_.front();
+// 将编码完成数据data写入到对应输出文件中
+outFile_->write(reinterpret_cast<char *>(OH_AVMemory_GetAdd(data)), attr.size);
+// 释放已完成写入的数据
+ret = OH_AudioEncoder_FreeOutputData(audioEnc, index);
+if (ret != AV_ERR_OK) {
+    // 异常处理
+}
+if (attr.flags == AVCODEC_BUFFER_FLAGS_EOS) {
+    cout << "decode eos" << endl;
+    isRunning_.store(false);
+    break;
+}
+```
+
+8. （可选）调用OH_AudioEncoder_Flush()刷新编码器。
+   调用OH_AudioEncoder_Flush()后，编码器处于Flush状态，会将当前编码队列清空。
+   此时需要调用OH_AudioEncoder_Start()重新开始编码。
+   使用情况：
+   * 在文件EOS之后，需要调用刷新
+   * 在执行过程中遇到可继续执行的错误时（即OH_AudioEncoder_IsValid 为true）可以调用，然后重新调用OH_AudioEncoder_Start
+
+```c++
+   // 刷新编码器 audioEnc
+   ret = OH_AudioEncoder_Flush(audioEnc);
+   if (ret != AV_ERR_OK) {
+       // 异常处理
+   }
+   // 重新开始编码
+   ret = OH_AudioEncoder_Start(audioEnc);
+   if (ret != AV_ERR_OK) {
+       // 异常处理
+   }
+```
+
+9. （可选）调用OH_AudioEncoder_Reset()重置编码器。
+   调用OH_AudioEncoder_Reset()后，编码器回到初始化的状态，需要调用OH_AudioEncoder_Configure()重新配置，然后调用OH_AudioEncoder_Start()重新开始编码。。
+
+   ```c++
+   // 重置编码器 audioEnc
+   ret = OH_AudioEncoder_Reset(audioEnc);
+   if (ret != AV_ERR_OK) {
+       // 异常处理
+   }
+   // 重新配置编码器参数
+   ret = OH_AudioEncoder_Configure(audioEnc, format);
+   if (ret != AV_ERR_OK) {
+       // 异常处理
+   }
+   ```
+10. 调用OH_AudioEncoder_Stop()停止编码器。
+
+    ```c++
+    // 终止编码器 audioEnc
+    ret = OH_AudioEncoder_Stop(audioEnc);
+    if (ret != AV_ERR_OK) {
+        // 异常处理
+    }
+        return ret;
+    ```
+11. 调用OH_AudioEncoder_Destroy()销毁编码器实例，释放资源。
+    **注意**：资源不能重复销毁
+
+    ```c++
+    // 调用OH_AudioEncoder_Destroy, 注销编码器
+    ret = OH_AudioEncoder_Destroy(audioEnc);
+    if (ret != AV_ERR_OK) {
+        // 异常处理
+    } else {
+        audioEnc = NULL; //不可重复destroy
+    }
+    return ret;
+    ```

zh-cn/application-dev/media/audio-video-decapsulation.md

+# 音视频解封装
+
+开发者可以调用本模块的Native API接口，完成音视频解封装，即从比特流数据中取出音频、视频等媒体帧数据。
+
+当前支持的数据输入类型有：远程连接(http协议)和文件描述符(fd)。
+
+支持的解封装格式如下：
+
+| 媒体格式  | 封装格式                      |
+| -------- | :----------------------------|
+| 视频     | mp4、mpeg-ts                  |
+| 音频      | m4a、aac、mp3、ogg、flac、wav |
+
+
+
+**适用场景**：
+
+- 播放
+  
+  播放媒体文件时，需要先对音视频流进行解封装，然后使用解封装获取的帧数据进行解码和播放。
+
+- 音视频编辑
+  
+  编辑媒体文件时，需要先对音视频流进行解封装，获取到指定帧进行编辑。
+
+- 媒体文件格式转换（转封装）
+
+  媒体文件格式转换时，需要先对音视频流进行解封装，然后按需将音视频流封装至新的格式文件内。
+
+## 开发步骤
+详细的API说明参考[AVDemuxer](../reference/native-apis/_a_v_demuxer.md)和[AVSource](../reference/native-apis/_a_v_source.md)
+
+> **说明**
+>
+> - 调用解封装能力解析网络播放路径，需要[申请相关权限](../security/accesstoken-guidelines.md)：ohos.permission.INTERNET
+> - 调用解封装能力解析本地文件，需要[申请相关权限](../security/accesstoken-guidelines.md)：ohos.permission.READ_MEDIA
+> - 如果使用ResourceManager.getRawFd打开HAP资源文件描述符，使用方法请参考[ResourceManager API参考](../reference/apis/js-apis-resource-manager.md#getrawfd9)
+
+1. 创建解封装器实例对象
+
+   ``` c++
+   // 创建文件操作符 fd，打开时对文件句柄必须有读权限
+   std::string fileName = "test.mp4";
+   int fd = open(fileName.c_str(), O_RDONLY);
+   struct stat fileStatus {};
+   size_t fileSize = 0;
+   if (stat(fileName.c_str(), &fileStatus) == 0) {
+      fileSize = static_cast<size_t>(fileStatus.st_size);
+   } else {
+      printf("get stat failed");
+      return;
+   }
+   // 为 fd 资源文件创建 source 资源对象, 传入 offset 不为文件起始位置 或 size 不为文件大小时，可能会因不能获取完整数据导致 source 创建失败、或后续解封装失败等问题
+   OH_AVSource *source = OH_AVSource_CreateWithFD(fd, 0, fileSize);
+   if (source == nullptr) {
+      printf("create source failed");
+      return;
+   }
+   // 为 uri 资源文件创建 source 资源对象(可选)
+   // OH_AVSource *source = OH_AVSource_CreateWithURI(uri);
+   ```
+   ```c++
+   // 为资源对象创建对应的解封装器
+   OH_AVDemuxer *demuxer = OH_AVDemuxer_CreateWithSource(source);
+   if (demuxer == nullptr) {
+      printf("create demuxer failed");
+      return;
+   }
+   ```
+
+
+
+2. 获取文件轨道数（可选，若用户已知轨道信息，可跳过此步）
+
+   ``` c++
+   // 从文件 source 信息获取文件轨道数
+   OH_AVFormat *sourceFormat = OH_AVSource_GetSourceFormat(source);
+   if (sourceFormat == nullptr) {
+      printf("get source format failed");
+      return;
+   }
+   int32_t trackCount = 0;
+   OH_AVFormat_GetIntValue(sourceFormat, OH_MD_KEY_TRACK_COUNT, &trackCount);
+   OH_AVFormat_Destroy(sourceFormat);
+   ```
+
+   
+
+3. 获取轨道index及信息（可选，若用户已知轨道信息，可跳过此步）
+
+   ``` c++
+   uint32_t audioTrackIndex = 0;
+   uint32_t videoTrackIndex = 0;
+   int32_t w = 0;
+   int32_t h = 0;
+   int32_t trackType;
+   for (uint32_t index = 0; index < (static_cast<uint32_t>(trackCount)); index++) {
+      // 获取轨道信息
+      OH_AVFormat *trackFormat = OH_AVSource_GetTrackFormat(source, index);
+      if (trackFormat == nullptr) {
+         printf("get track format failed");
+         return;
+      }
+      OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_TRACK_TYPE, &trackType);
+      static_cast<OH_MediaType>(trackType) == OH_MediaType::MEDIA_TYPE_AUD ? audioTrackIndex = index : videoTrackIndex = index;
+      // 获取视频轨宽高
+      if (trackType == OH_MediaType::MEDIA_TYPE_VID) {
+         OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_WIDTH, &w);
+         OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_HEIGHT, &h);
+      }
+      OH_AVFormat_Destroy(trackFormat);
+   }
+   ```
+
+   
+
+4. 添加解封装轨道
+
+   ``` c++
+   if(OH_AVDemuxer_SelectTrackByID(demuxer, audioTrackIndex) != AV_ERR_OK){
+      printf("select audio track failed: %d", audioTrackIndex);
+      return;
+   }
+   if(OH_AVDemuxer_SelectTrackByID(demuxer, videoTrackIndex) != AV_ERR_OK){
+      printf("select video track failed: %d", videoTrackIndex);
+      return;
+   }
+   // 取消选择轨道(可选)
+   // OH_AVDemuxer_UnselectTrackByID(demuxer, audioTrackIndex);
+   ```
+
+
+
+5. 调整轨道到指定时间点(可选)
+
+   ``` c++
+   // 调整轨道到指定时间点，后续从该时间点进行解封装
+   OH_AVDemuxer_SeekToTime(demuxer, 0, OH_AVSeekMode::SEEK_MODE_CLOSEST_SYNC);
+   ```
+
+6. 开始解封装，循环获取帧数据(以含音频、视频两轨的文件为例)
+
+   ``` c++
+   // 创建 buffer，用与保存用户解封装得到的数据
+   OH_AVMemory *buffer = OH_AVMemory_Create(w * h * 3 >> 1);
+   if (buffer == nullptr) {
+      printf("build buffer failed");
+      return;
+   }
+   OH_AVCodecBufferAttr info;
+   bool videoIsEnd = false;
+   bool audioIsEnd = false;
+   int32_t ret;
+   while (!audioIsEnd || !videoIsEnd) {
+      // 在调用 OH_AVDemuxer_ReadSample 接口获取数据前，需要先调用 OH_AVDemuxer_SelectTrackByID 选中需要获取数据的轨道
+      // 获取音频帧数据
+      if(!audioIsEnd) {
+         ret = OH_AVDemuxer_ReadSample(demuxer, audioTrackIndex, buffer, &info);
+         if (ret == AV_ERR_OK) {
+            // 可通过 buffer 获取并处理音频帧数据
+            printf("audio info.size: %d\n", info.size);
+            if (info.flags == OH_AVCodecBufferFlags::AVCODEC_BUFFER_FLAGS_EOS) {
+               audioIsEnd = true;
+            }
+         }
+      }
+      if(!videoIsEnd) {
+         ret = OH_AVDemuxer_ReadSample(demuxer, videoTrackIndex, buffer, &info);
+         if (ret == AV_ERR_OK) {
+            // 可通过 buffer 获取并处理视频帧数据
+            printf("video info.size: %d\n", info.size);
+            if (info.flags == OH_AVCodecBufferFlags::AVCODEC_BUFFER_FLAGS_EOS) {
+               videoIsEnd = true;
+            }
+         }
+      }
+   }
+   OH_AVMemory_Destroy(buffer);
+   ```
+
+   
+
+7. 销毁解封装实例
+
+   ``` c++
+   // 需要用户调用 OH_AVSource_Destroy 接口成功后，手动将对象置为 NULL，对同一对象重复调用 OH_AVSource_Destroy 会导致程序错误
+   if (OH_AVSource_Destroy(source) != AV_ERR_OK) {
+      printf("destroy source pointer error");
+   }
+   source = NULL;
+   // 需要用户调用 OH_AVDemuxer_Destroy 接口成功后，手动将对象置为 NULL，对同一对象重复调用 OH_AVDemuxer_Destroy 会导致程序错误
+   if (OH_AVDemuxer_Destroy(demuxer) != AV_ERR_OK) {
+      printf("destroy demuxer pointer error");
+   }
+   demuxer = NULL;
+   close(fd);
+   ```
\ No newline at end of file

zh-cn/application-dev/media/audio-video-encapsulation.md

+# 音视频封装
+
+开发者可以调用本模块的Native API接口，完成音视频封装，即将音频、视频等编码后的媒体数据，按一定的格式存储到文件里。
+
+当前支持的封装能力如下：
+
+| 封装格式 | 视频编解码类型        | 音频编解码类型   | 封面类型       |
+| -------- | --------------------- | ---------------- | -------------- |
+| mp4      | MPEG-4、 AVC（H.264） | AAC、MPEG（MP3） | jpeg、png、bmp |
+| m4a      | MPEG-4、 AVC（H.264） | AAC              | jpeg、png、bmp |
+
+**适用场景**
+
+- 录像、录音
+  
+  保存录像、录音文件时，需要先对音视频流进行编码，再封装为文件。
+
+- 音视频编辑
+  
+  完成编辑后的音视频，需要封装为文件。
+
+- 音视频转码
+
+  转码后，保存文件时需要封装。
+
+## 开发步骤
+
+详细的API说明请参考[API文档](../reference/native-apis/_a_v_muxer.md)。
+
+> **说明：**
+> 
+> 如果调用封装能力写本地文件，需要[申请相关权限](../security/accesstoken-guidelines.md)：ohos.permission.READ_MEDIA, ohos.permission.WRITE_MEDIA
+
+参考以下示例代码，完成音视频封装的全流程。以封装mp4格式的音视频文件为例。
+
+1. 调用OH_AVMuxer_Create()创建封装器实例对象。
+
+   ``` c++
+   // 设置封装格式为mp4
+   OH_AVOutputFormat format = AV_OUTPUT_FORMAT_MPEG_4;
+   // 以读写方式创建fd
+   int32_t fd = open("test.mp4", O_CREAT | O_RDWR | O_TRUNC, S_IRUSR | S_IWUSR);
+   OH_AVMuxer *muxer = OH_AVMuxer_Create(fd, format);
+   ```
+
+2. （可选）调用OH_AVMuxer_SetRotation()设置旋转角度。
+   
+   ``` c++
+   // 旋转角度，视频画面需要旋转的时候设置
+   OH_AVMuxer_SetRotation(muxer, 0);
+   ```
+
+3. 添加音频轨。
+   
+   **方法一：用OH_AVFormat_Create创建format**
+
+   ``` c++
+   int audioTrackId = -1;
+   OH_AVFormat *formatAudio = OH_AVFormat_Create();
+   OH_AVFormat_SetStringValue(formatAudio, OH_MD_KEY_CODEC_MIME, OH_AVCODEC_MIMETYPE_AUDIO_AAC); // 必填
+   OH_AVFormat_SetIntValue(formatAudio, OH_MD_KEY_AUD_SAMPLE_RATE, 44100); // 必填
+   OH_AVFormat_SetIntValue(formatAudio, OH_MD_KEY_AUD_CHANNEL_COUNT, 2); // 必填
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &audioTrackId, formatAudio);
+   if (ret != AV_ERR_OK || audioTrackId < 0) {
+       // 音频轨添加失败
+   }
+   OH_AVFormat_Destroy(formatAudio); // 销毁
+   ```
+   
+   **方法二：用OH_AVFormat_CreateAudioFormat创建format**
+   
+   ``` c++
+   int audioTrackId = -1;
+   OH_AVFormat *formatAudio = OH_AVFormat_CreateAudioFormat(OH_AVCODEC_MIMETYPE_AUDIO_AAC, 44100, 2);
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &audioTrackId, formatAudio);
+   if (ret != AV_ERR_OK || audioTrackId < 0) {
+       // 音频轨添加失败
+   }
+   OH_AVFormat_Destroy(formatAudio); // 销毁
+   ```
+
+4. 添加视频轨。
+
+   **方法一：用OH_AVFormat_Create创建format**
+
+   ``` c++
+   int videoTrackId = -1;
+   char *buffer = ...; // 编码config data，如果没有可以不传
+   size_t size = ...;  // 编码config data的长度，根据实际情况配置
+   OH_AVFormat *formatVideo = OH_AVFormat_Create();
+   OH_AVFormat_SetStringValue(formatVideo, OH_MD_KEY_CODEC_MIME, OH_AVCODEC_MIMETYPE_VIDEO_MPEG4); // 必填
+   OH_AVFormat_SetIntValue(formatVideo, OH_MD_KEY_WIDTH, 1280); // 必填
+   OH_AVFormat_SetIntValue(formatVideo, OH_MD_KEY_HEIGHT, 720); // 必填
+   OH_AVFormat_SetBuffer(formatVideo, OH_MD_KEY_CODEC_CONFIG, buffer, size); // 非必须
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &videoTrackId, formatVideo);
+   if (ret != AV_ERR_OK || videoTrackId < 0) {
+       // 视频轨添加失败
+   }
+   OH_AVFormat_Destroy(formatVideo); // 销毁
+   ```
+   
+   **方法二：用OH_AVFormat_CreateVideoFormat创建format**
+   
+   ``` c++
+   int videoTrackId = -1;
+   char *buffer = ...; // 编码config data，如果没有可以不传
+   size_t size = ...;  // 编码config data的长度，根据实际情况配置
+   OH_AVFormat *formatVideo = OH_AVFormat_CreateVideoFormat(OH_AVCODEC_MIMETYPE_VIDEO_MPEG4, 1280, 720);
+   OH_AVFormat_SetBuffer(formatVideo, OH_MD_KEY_CODEC_CONFIG, buffer, size); // 非必须
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &videoTrackId, formatVideo);
+   if (ret != AV_ERR_OK || videoTrackId < 0) {
+       // 视频轨添加失败
+   }
+   OH_AVFormat_Destroy(formatVideo); // 销毁
+   ```
+
+5. 添加封面轨。
+
+   **方法一：用OH_AVFormat_Create创建format**
+
+   ``` c++
+   int coverTrackId = -1;
+   OH_AVFormat *formatCover = OH_AVFormat_Create();
+   OH_AVFormat_SetStringValue(formatCover, OH_MD_KEY_CODEC_MIME, OH_AVCODEC_MIMETYPE_IMAGE_JPG);
+   OH_AVFormat_SetIntValue(formatCover, OH_MD_KEY_WIDTH, 1280);
+   OH_AVFormat_SetIntValue(formatCover, OH_MD_KEY_HEIGHT, 720);
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &coverTrackId, formatCover);
+   if (ret != AV_ERR_OK || coverTrackId < 0) {
+       // 添加封面失败
+   }
+   OH_AVFormat_Destroy(formatCover); // 销毁
+   ```
+   
+   **方法二：用OH_AVFormat_CreateVideoFormat创建format**
+
+   ``` c++
+   int coverTrackId = -1;
+   OH_AVFormat *formatCover = OH_AVFormat_CreateVideoFormat(OH_AVCODEC_MIMETYPE_IMAGE_JPG, 1280, 720);
+   
+   int ret = OH_AVMuxer_AddTrack(muxer, &coverTrackId, formatCover);
+   if (ret != AV_ERR_OK || coverTrackId < 0) {
+       // 添加封面失败
+   }
+   OH_AVFormat_Destroy(formatCover); // 销毁
+   ```
+
+6. 调用OH_AVMuxer_Start()开始封装。
+   
+   ``` c++
+   // 调用start，写封装文件头。start后，不能设置媒体参数、不能添加媒体轨
+   if (OH_AVMuxer_Start(muxer) != AV_ERR_OK) {
+       // 异常处理
+   }
+   ```
+
+7. 调用OH_AVMuxer_WriteSample()，写入封装数据。
+   
+   包括视频、音频、封面数据。
+
+   ``` c++
+   // start后，才能开始写入数据
+   int size = ...;
+   OH_AVMemory *sample = OH_AVMemory_Create(size); // 创建AVMemory
+   // 往sampleBuffer里写入数据参考OH_AVMemory的使用方法
+   // 封装封面，必须一次写完一张图片
+   
+   // 创建buffer info
+   OH_AVCodecBufferAttr info;
+   info.pts = ...; // 当前数据的开始播放的时间，单位微秒
+   info.size = size; // 当前数据的长度
+   info.offset = 0; // 偏移，一般为0
+   info.flags |= AVCODEC_BUFFER_FLAGS_SYNC_FRAME; // 当前数据的标志。具体参考OH_AVCodecBufferFlags
+   int trackId = audioTrackId; // 选择写的媒体轨
+   
+   int ret = OH_AVMuxer_WriteSample(muxer, trackId, sample, info);
+   if (ret != AV_ERR_OK) {
+       // 异常处理
+   }
+   ```
+
+8. 调用OH_AVMuxer_Stop()，停止封装。
+
+   ``` c++
+   // 调用stop，写封装文件尾。stop后不能写入媒体数据
+   if (OH_AVMuxer_Stop(muxer) != AV_ERR_OK) {
+       // 异常处理
+   }
+   ```
+
+9. 调用OH_AVMuxer_Destroy()销毁实例，释放资源。
+
+   ``` c++
+   if (OH_AVMuxer_Destroy(muxer) != AV_ERR_OK) {
+       // 异常处理
+   }
+   muxer = NULL;
+   close(fd); // 关闭文件描述符
+   ```
\ No newline at end of file

zh-cn/application-dev/media/obtain-supported-codecs.md

+# 获取支持的编解码能力
+
+不同设备支持的编解码能力存在差异，开发者在调用编解码或配置编解码器前，需要先查询当前系统支持的编解码器规格。
+
+开发者可以调用本模块的Native API接口，查询相关能力的支持情况。
+
+## 开发步骤
+
+详细的API说明请参考[API文档](../reference/native-apis/_a_v_capability.md)。
+
+1. 获得能力
+
+    ```c
+    // 根据mime type、是否编码器获得能力
+    OH_AVCapability *capability = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_VIDEO_AVC, false);
+
+    // 根据mime type、是否编码器以及软硬件类别获得能力
+    OH_AVCapability *capability = OH_AVCodec_GetCapabilityByCategory(OH_AVCODEC_MIMETYPE_VIDEO_AVC, false, SOFTWARE);
+    ```
+
+2. 查询参数
+    ```c
+    // 查询当前能力是否支持硬件
+    bool isHardware = OH_AVCapability_IsHardware(capability);
+
+    // 查询当前能力codec名称
+    const char *codecName = OH_AVCapability_GetName(capability);
+
+    // 查询当前能力中，最大支持的实例数
+    int32_t maxSupportedInstances = OH_AVCapability_GetMaxSupportedInstances(capability);
+
+    // 查询当前能力中，编码支持的码率范围
+    OH_AVRange bitrateRange;
+    int32_t ret = OH_AVCapability_GetEncoderBitrateRange(capability, &bitrateRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，码控模式是否支持
+    bool isEncoderBitrateModeSupported = OH_AVCapability_IsEncoderBitrateModeSupported(capability, &bitrateMode);
+
+    // 查询当前能力中，编码质量范围
+    OH_AVRange qualityRange;
+    int32_t ret = OH_AVCapability_GetEncoderQualityRange(capability, &qualityRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，编码复杂度范围
+    OH_AVRange complexityRange;
+    int32_t ret = OH_AVCapability_GetEncoderComplexityRange(capability, &complexityRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，支持的音频采样率
+    const int32_t *sampleRates;
+    uint32_t sampleRateNum = 0;
+    int32_t ret = OH_AVCapability_GetAudioSupportedSampleRates(capability, &sampleRates, &sampleRateNum);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，支持的音频通道数范围
+    OH_AVRange channelCountRange;
+    int32_t ret = OH_AVCapability_GetAudioChannelCountRange(capability, &channelCountRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，宽的对齐值
+    int32_t widthAlignment;
+    int32_t ret = OH_AVCapability_GetVideoWidthAlignment(capability, &widthAlignment);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，高的对齐值
+    int32_t heightAlignment;
+    int32_t ret = OH_AVCapability_GetVideoHeightAlignment(capability, &heightAlignment);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，高为1080时，宽的范围
+    OH_AVRange widthRange;
+    int32_t ret = OH_AVCapability_GetVideoWidthRangeForHeight(capability, 1080, &widthRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，宽为1920时，高的范围
+    OH_AVRange heightRange;
+    int32_t ret = OH_AVCapability_GetVideoHeightRangeForWidth(capability, 1920, &heightRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，宽的范围
+    OH_AVRange widthRange;
+    int32_t ret = OH_AVCapability_GetVideoWidthRange(capability, &widthRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，高的范围
+    OH_AVRange heightRange;
+    int32_t ret = OH_AVCapability_GetVideoWidthRange(capability, &heightRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 校验当前能力是否支持分辨率1080p
+    bool isVideoSizeSupported = OH_AVCapability_IsVideoSizeSupported(capability, 1920, 1080);
+
+    // 查询当前能力中，视频帧率范围
+    OH_AVRange frameRateRange;
+    int32_t ret = OH_AVCapability_GetVideoFrameRateRange(capability, &frameRateRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，分辨率为1920x1080时视频帧率范围
+    OH_AVRange frameRateRange;
+    int32_t ret =  OH_AVCapability_GetVideoFrameRateRangeForSize(capability, 1920, 1080, &frameRateRange);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 校验当前能力是否支持分辨率1080p、帧率30的场景
+    bool areVideoSizeAndFrameRateSupported = OH_AVCapability_AreVideoSizeAndFrameRateSupported(capability, 1920, 1080, 30);
+
+    // 查询当前能力中，支持的颜色格式以及个数
+    const int32_t *pixFormats;
+    uint32_t pixFormatNum = 0;
+    int32_t ret = OH_AVCapability_GetVideoSupportedPixelFormats(capability, &pixFormats, &pixFormatNum);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，支持的模板
+    const int32_t *profiles;
+    uint32_t profileNum = 0;
+    int32_t ret =  OH_AVCapability_GetSupportedProfiles(capability, &profiles, &profileNum);
+    if (ret != AV_ERR_OK) {
+        // 处理异常
+    }
+
+    // 查询当前能力中，特定模板情况下的等级范围
+    const int32_t *levels;
+    uint32_t levelNum = 0;
+    int32_t ret = OH_AVCapability_GetSupportedLevelsForProfile(capability, 0, &levels, &levelNum);
+
+    // 校验当前能力是否支持分辨率1080p、帧率30的场景
+    bool areVideoSizeAndFrameRateSupported = OH_AVCapability_AreVideoSizeAndFrameRateSupported(capability, 1920, 1080, 30);
+    ```
\ No newline at end of file

zh-cn/application-dev/media/video-decoding.md

+# 视频解码
+
+开发者可以调用本模块的Native API接口，完成视频解码，即将媒体数据解码成YUV文件或送显。
+
+当前支持的解码能力如下：
+
+| 容器规格 | 视频硬解类型       | 视频软解类型   |
+| -------- | --------------------- | ---------------- |
+| mp4      | AVC(H.264)、HEVC(H.265) |AVC(H.264) |
+
+
+视频解码软/硬件解码存在差异，基于MimeType创建解码器时，软解当前仅支持 H264 ("video/avc")，硬解则支持 H264 ("video/avc") 和 H265 ("video/hevc")。
+
+## 开发步骤
+
+详细的API说明请参考[API文档](../reference/native-apis/_video_decoder.md)。
+
+1. 创建编解码器实例对象。
+   
+   应用可以通过名称或媒体类型创建解码器。
+
+   ``` c++
+    // 通过 codecname 创建解码器
+    OH_AVCapability *capability = OH_AVCodec_GetCapability(OH_AVCODEC_MIMETYPE_VIDEO_AVC, false);
+    const char *name = OH_AVCapability_GetName(capability);
+    OH_AVCodec *videoDec = OH_AudioDecoder_CreateByName(name); // name:"OH.Media.Codec.Decoder.Video.AVC"
+   ```
+   ```c++
+    // 通过 mimetype 创建解码器
+    // 软/硬解: 创建 H264 解码器
+    OH_AVCodec *videoDec = OH_VideoDecoder_CreateByMime(OH_AVCODEC_MIMETYPE_VIDEO_AVC);
+    // 通过 mimetype 创建解码器
+    // 硬解: 创建 H265 解码器
+    OH_AVCodec *videoDec = OH_VideoDecoder_CreateByMime(OH_AVCODEC_MIMETYPE_VIDEO_HEVC);
+   ```
+   ``` c++
+   // 初始化队列
+   class VDecSignal {
+   public:
+       std::mutex inMutex_;
+       std::mutex outMutex_;
+       std::condition_variable inCond_;
+       std::condition_variable outCond_;
+       std::queue<uint32_t> inQueue_;
+       std::queue<uint32_t> outQueue_;
+       std::queue<OH_AVMemory *> inBufferQueue_;
+       std::queue<OH_AVMemory *> outBufferQueue_;
+       std::queue<OH_AVCodecBufferAttr> attrQueue_;
+   };
+   VDecSignal *signal_;
+   ```
+
+2. 调用OH_VideoDecoder_SetCallback()设置回调函数。
+
+   注册回调函数指针集合OH_AVCodecAsyncCallback，包括：
+
+   - 解码器运行错误
+   - 码流信息变化，如码流宽、高变化。
+   - 运行过程中需要新的输入数据，即解码器已准备好，可以输入数据。
+   - 运行过程中产生了新的输出数据，即解码完成。(注：Surface模式data参数为空)
+
+   开发者可以通过处理该回调报告的信息，确保解码器正常运转。
+
+   ``` c++
+    // 解码异常回调
+    static void OnError(OH_AVCodec *codec, int32_t errorCode, void *userData)
+    {
+        (void)codec;
+        (void)errorCode;
+        (void)userData;
+    }
+    // 解码码流变化回调
+    static void OnOutputFormatChanged(OH_AVCodec *codec, OH_AVFormat *format, void *userData)
+    {
+        (void)codec;
+        (void)format;
+        (void)userData;
+    }
+    // 解码输入回调获取输入帧信息
+    static void OnInputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory *data, void *userData)
+    {
+        (void)codec;
+        VDecSignal *signal_ = static_cast<VDecSignal *>(userData);
+        unique_lock<mutex> lock(signal_->inMutex_);
+        // 解码输入帧id送入 inQueue_
+        signal_->inQueue_.push(index);
+        // 解码输入帧数据送入 inBufferQueue_
+        signal_->inBufferQueue_.push(data);
+        signal_->inCond_.notify_all();
+    }
+    // 解码输出回调获取输出帧信息
+    static void OnOutputBufferAvailable(OH_AVCodec *codec, uint32_t index, OH_AVMemory *data, OH_AVCodecBufferAttr *attr,
+                                        void *userData)
+    {
+        (void)codec;
+        VDecSignal *signal_ = static_cast<VDecSignal *>(userData);
+        unique_lock<mutex> lock(signal_->outMutex_);
+        // 将对应输出 buffer 的 index 送入 outQueue_
+        signal_->outQueue_.push(index);
+        // 将对应解码完成的数据 data 送入 outBufferQueue_ (注： Surface模式下data为空)
+        signal_->outBufferQueue_.push(data);
+        signal_->attrQueue_.push(*attr);
+        signal_->outCond_.notify_all();
+    }
+    OH_AVCodecAsyncCallback cb = {&OnError, &OnOutputFormatChanged, &OnInputBufferAvailable, &OnOutputBufferAvailable};
+    // 配置异步回调
+    int32_t ret = OH_VideoDecoder_SetCallback(videoDec, cb, signal_);
+   ```
+
+3. 调用OH_VideoDecoder_Configure()配置解码器。
+
+   配置必选项：视频帧宽度、视频帧高度、视频颜色格式。
+
+   ``` c++
+    // 配置视频帧宽度（必须）
+    constexpr uint32_t DEFAULT_WIDTH = 320; 
+    // 配置视频帧高度（必须）
+    constexpr uint32_t DEFAULT_HEIGHT = 240;
+    OH_AVFormat *format = OH_AVFormat_Create();
+    // 写入 format
+    OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, DEFAULT_WIDTH);
+    OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, DEFAULT_HEIGHT);
+    OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, AV_PIXEL_FORMAT_NV21);
+    // 配置解码器
+    int32_t ret = OH_VideoDecoder_Configure(videoDec, format);
+    OH_AVFormat_Destroy(format);
+   ```
+
+4. （如需使用Surface送显，必须设置）设置Surface。
+   
+   ``` c++
+    // 配置送显窗口参数
+    sptr<Rosen::Window> window = nullptr;
+    sptr<Rosen::WindowOption> option = new Rosen::WindowOption();
+    option->SetWindowRect({0, 0, DEFAULT_WIDTH, DEFAULT_HEIGHT});
+    option->SetWindowType(Rosen::WindowType::WINDOW_TYPE_APP_LAUNCHING);
+    option->SetWindowMode(Rosen::WindowMode::WINDOW_MODE_FLOATING);
+    window = Rosen::Window::Create("video-decoding", option);
+    window->Show();
+    sptr<Surface> ps = window->GetSurfaceNode()->GetSurface();
+    OHNativeWindow *nativeWindow = CreateNativeWindowFromSurface(&ps);
+    int32_t ret = OH_VideoDecoder_SetSurface(videoDec, window);
+    bool isSurfaceMode = true;
+   ```  
+
+5. （仅使用Surface时可配置）配置解码器surface参数。
+   
+   ``` c++
+    OH_AVFormat *format = OH_AVFormat_Create();
+    // 配置显示旋转角度
+    OH_AVFormat_SetIntValue(format, OH_MD_KEY_ROTATION, 90);
+    // 配置视频与显示屏匹配模式(缩放与显示窗口适配, 裁剪与显示窗口适配)
+    OH_AVFormat_SetIntValue(format, OH_MD_KEY_SCALING_MODE, SCALING_MODE_SCALE_CROP);
+    int32_t ret = OH_VideoDecoder_SetParameter(videoDec, format);
+    OH_AVFormat_Destroy(format);
+   ``` 
+
+6. 调用OH_VideoDecoder_Start()启动解码器。
+
+   ``` c++
+    string_view outputFilePath = "/*yourpath*.yuv";
+    std::unique_ptr<std::ifstream> inputFile = std::make_unique<std::ifstream>();
+    // 打开待解码二进制文件路径
+    inputFile->open(inputFilePath.data(), std::ios::in | std::ios::binary); 
+    // buffer 模式下需要配置
+    if(!isSurfaceMode) {
+        // buffer 模式: 配置解码文件输出路径
+        std::unique_ptr<std::ofstream> outFile = std::make_unique<std::ofstream>();
+        outFile->open(outputFilePath.data(), std::ios::out | std::ios::binary);
+    }
+    // 开始解码
+    int32_t ret = OH_VideoDecoder_Start(videoDec);
+   ```
+
+7. 调用OH_VideoDecoder_PushInputData()，写入解码码流。
+
+   ``` c++
+    // 配置 buffer info 信息
+    OH_AVCodecBufferAttr info;
+    // 调用 Ffmpeg 接口 av_packet_alloc 进行初始化并返回一个容器 pkt
+    AVPacket pkt = av_packet_alloc();
+    // 配置 info 的输入尺寸、偏移量、时间戳等字段信息
+    info.size = pkt->size;
+    info.offset = 0;
+    info.pts = pkt->pts;
+    info.flags = AVCODEC_BUFFER_FLAGS_NONE;
+    // 送入解码输入队列进行解码, index 为对应队列下标
+    int32_t ret = OH_VideoDecoder_PushInputData(videoDec, index, info);
+   ```
+
+8. 调用OH_VideoDecoder_FreeOutputData()，输出解码帧。
+
+   ``` c++
+    int32_t ret;
+    // 将解码完成数据 data 写入到对应输出文件中
+    outFile->write(reinterpret_cast<char *>(OH_AVMemory_GetAddr(data)), data.size);
+    // buffer 模式, 释放已完成写入的数据, index 为对应 surface/buffer 队列下标
+    if (isSurfaceMode) {
+        ret = OH_VideoDecoder_RenderOutputData(videoDec, index);
+    } else {
+        ret = OH_VideoDecoder_FreeOutputData(videoDec, index);
+    }
+    if (ret != AV_ERR_OK) {
+        // 异常处理
+    }
+   ```
+
+9. （可选）调用OH_VideoDecoder_Flush()刷新解码器。
+   
+   调用OH_VideoDecoder_Flush()后，解码器仍处于运行态，但会将当前队列清空，将已解码的数据释放。
+    
+   此时需要调用OH_VideoDecoder_Start()重新开始解码。
+
+   ``` c++
+    int32_t ret;
+    // 刷新解码器 videoDec
+    ret = OH_VideoDecoder_Flush(videoDec);
+    if (ret != AV_ERR_OK) {
+        // 异常处理
+    }
+    // 重新开始解码
+    ret = OH_VideoDecoder_Start(videoDec);
+   ```
+
+10. （可选）调用OH_VideoDecoder_Reset()重置解码器。
+    
+    调用OH_VideoDecoder_Reset()后，解码器回到初始化的状态，需要调用OH_VideoDecoder_Configure()重新配置。
+
+    ``` c++
+     int32_t ret;
+     // 重置解码器 videoDec
+     ret = OH_VideoDecoder_Reset(videoDec);
+     if (ret != AV_ERR_OK) {
+         // 异常处理
+     }
+     // 重新配置解码器参数
+     ret = OH_VideoDecoder_Configure(videoDec, format);
+    ```
+
+11. 调用OH_VideoDecoder_Stop()停止解码器。
+    
+    ``` c++
+     int32_t ret;
+     // 终止解码器 videoDec
+     ret = OH_VideoDecoder_Stop(videoDec);
+     if (ret != AV_ERR_OK) {
+         // 异常处理
+     }
+     return AV_ERR_OK;
+    ```
+
+12. 调用OH_VideoDecoder_Destroy()销毁解码器实例，释放资源。
+
+    ``` c++
+     int32_t ret;
+     // 调用 OH_VideoDecoder_Destroy, 注销解码器
+     ret = OH_VideoDecoder_Destroy(videoDec);
+     if (ret != AV_ERR_OK) {
+         // 异常处理
+     }
+     return AV_ERR_OK;
+    ```
+