媒体数据解析
======

开发者可以调用本模块的Native API接口，完成媒体数据的解封装相关操作，即从比特流数据中取出音频、视频、字幕等媒体sample，获得DRM相关信息。

当前支持的数据输入类型有：远程连接(http协议)和文件描述符(fd)。

当前支持的解封装格式请参考[AVCodec支持的格式](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/avcodec-support-formats#媒体数据解析)。

**适用场景**：

*   播放
    
    播放媒体文件时，需要先对媒体流进行解封装，然后使用解封装获取的sample进行解码和播放。
    
*   音视频编辑
    
    编辑媒体文件时，需要先对媒体流进行解封装，获取到指定sample进行编辑。
    
*   媒体文件格式转换（转封装）
    
    媒体文件格式转换时，需要先对媒体流进行解封装，然后按需将媒体流封装至新的格式文件内。
    

#### 开发指导

详细的API说明参考[AVDemuxer](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-avdemuxer)和[AVSource](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-avsource)

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/e/v3/Yg9CskpkQ4SshgH0UL57Ww/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132518Z&HW-CC-Expire=86400&HW-CC-Sign=F90F6F5A1C2191F79E4454B439B7A4094BE8C846DBF375EC45C03B7246A96DEF)

*   调用解封装能力解析网络播放路径，需要[声明权限](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/declare-permissions)：ohos.permission.INTERNET。
*   调用解封装能力解析本地文件，需要[向用户申请授权](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/request-user-authorization)：ohos.permission.READ\_MEDIA。
*   如果使用ResourceManager.getRawFd打开HAP资源文件描述符，使用方法请参考[getRawFd](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/js-apis-resource-manager#getrawfd9)。

#### \[h2\]在 CMake 脚本中链接动态库

target\_link\_libraries(sample PUBLIC libnative\_media\_codecbase.so)
target\_link\_libraries(sample PUBLIC libnative\_media\_avdemuxer.so)
target\_link\_libraries(sample PUBLIC libnative\_media\_avsource.so)
target\_link\_libraries(sample PUBLIC libnative\_media\_core.so)

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/20/v3/8U2R8fS0TvKWpvx31zp_Vg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132518Z&HW-CC-Expire=86400&HW-CC-Sign=1DF9699C7A134E5C44516B2DAC13CD4F620E738655C075CFD3D728E33D50421C)

上述'sample'字样仅为示例，此处由开发者根据实际工程目录自定义。

#### \[h2\]开发步骤

1.  添加头文件。
    
    #include <multimedia/player\_framework/native\_avdemuxer.h>
    #include <multimedia/player\_framework/native\_avsource.h>
    #include <multimedia/player\_framework/native\_avcodec\_base.h>
    #include <multimedia/player\_framework/native\_avformat.h>
    #include <multimedia/player\_framework/native\_avbuffer.h>
    #include <fcntl.h>
    #include <sys/stat.h>
    #include <string>
    
2.  创建资源管理实例。
    
    开发者HAP中使用open获取fd时，filepath需要转换为[沙箱路径](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/app-sandbox-directory#应用沙箱路径和真实物理路径的对应关系)，才能获取沙盒资源。
    
    // 创建文件操作符 fd，打开时对文件实例必须有读权限（filePath 为待解封装文件路径，需预置文件，保证路径指向的文件存在）。
    std::string filePath = "test.mp4";
    int32\_t fd = open(filePath.c\_str(), O\_RDONLY);
    struct stat fileStatus {};
    int64\_t fileSize = 0;
    if (stat(filePath.c\_str(), &fileStatus) == 0) {
       fileSize = static\_cast<int64\_t>(fileStatus.st\_size);
    } else {
       printf("get stat failed");
       return;
    }
    // 注意：offset（文件起始偏移）、fileSize（文件大小）需与待解析文件匹配。
    // fd 指向单个资源文件时，offset为0、fileSize为资源文件大小。
    // fd 指向多个连续拼接的资源文件时（如多个mp3二进制拼接）：offset、fileSize 按待解析文件实际偏移和大小设置。
    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);
    
    // 为自定义数据源创建 source 资源实例（可选）。使用该方式前，需要先实现AVSourceReadAt接口函数实现。
    // 当使用OH\_AVSource\_CreateWithDataSource时需要补充g\_filePath。
    // g\_filePath = filePath ;
    // OH\_AVDataSource dataSource = {fileSize, AVSourceReadAt};
    // OH\_AVSource \*source = OH\_AVSource\_CreateWithDataSource(&dataSource);
    
    AVSourceReadAt接口函数，需要放在创建资源管理实例前实现：
    
    // 添加头文件。
    #include <fstream>
    
    static std::string g\_filePath;
    
    enum MediaDataSourceError : int32\_t {
       SOURCE\_ERROR\_IO = -2,
       SOURCE\_ERROR\_EOF = -1
    };
    
    int32\_t AVSourceReadAt(OH\_AVBuffer \*data, int32\_t length, int64\_t pos)
    {
       if (data == nullptr) {
          printf("AVSourceReadAt : data is nullptr!\\n");
          return MediaDataSourceError::SOURCE\_ERROR\_IO;
       }
    
       std::ifstream infile(g\_filePath, std::ofstream::binary);
       if (!infile.is\_open()) {
          printf("AVSourceReadAt : open file failed! file:%s\\n", g\_filePath.c\_str());
          return MediaDataSourceError::SOURCE\_ERROR\_IO;  // 打开文件失败。
       }
    
       infile.seekg(0, std::ios::end);
       int64\_t fileSize = infile.tellg();
       if (pos >= fileSize) {
          printf("AVSourceReadAt : pos over or equals file size!\\n");
          return MediaDataSourceError::SOURCE\_ERROR\_EOF;  // pos已经是文件末尾位置，无法读取。
       }
    
       if (pos + length > fileSize) {
          length = fileSize - pos;    // pos+length长度超过文件大小时，读取从pos到文件末尾的数据。
       }
    
       infile.seekg(pos, std::ios::beg);
       if (length <= 0) {
          printf("AVSourceReadAt : read length less than zero!\\n");
          return MediaDataSourceError::SOURCE\_ERROR\_IO;
       }
       char\* buffer = new char\[length\];
       infile.read(buffer, length);
       infile.close();
    
       memcpy(reinterpret\_cast<char \*>(OH\_AVBuffer\_GetAddr(data)),
          buffer, length);
       delete\[\] buffer;
    
       return length;
    }
    
3.  创建解封装器实例。
    
    // 为资源实例创建对应的解封装器。
    OH\_AVDemuxer \*demuxer = OH\_AVDemuxer\_CreateWithSource(source);
    if (demuxer == nullptr) {
       printf("create demuxer failed");
       return;
    }
    
4.  注册DRM信息监听函数，接口参考[Demuxer\_MediaKeySystemInfoCallback()](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-native-avdemuxer-h#demuxer_mediakeysysteminfocallback)（可选）。如果不是DRM码流或已获得DRM信息，可跳过此步骤。DRM信息内容参考[DRM\_MediaKeySystemInfo](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-drm-drm-mediakeysysteminfo)。
    
    设置DRM信息监听的接口，回调函数支持返回解封装器实例，适用于多个解封装器场景。
    
    // DRM信息监听回调OnDrmInfoChangedWithObj实现。
    static void OnDrmInfoChangedWithObj(OH\_AVDemuxer \*demuxer, DRM\_MediaKeySystemInfo \*drmInfo)
    {
       // 解析DRM信息，包括数量、DRM类型及对应pssh。
    }
    
    Demuxer\_MediaKeySystemInfoCallback callback = &OnDrmInfoChangedWithObj;
    Drm\_ErrCode ret = OH\_AVDemuxer\_SetDemuxerMediaKeySystemInfoCallback(demuxer, callback);
    
    在监听到DRM信息后，也可主动调用获取DRM信息(uuid及对应pssh)接口。
    
    DRM\_MediaKeySystemInfo mediaKeySystemInfo;
    OH\_AVDemuxer\_GetMediaKeySystemInfo(demuxer, &mediaKeySystemInfo);
    
    在获取、解析DRM信息后，需创建对应DRM解决方案的[MediaKeySystem、MediaKeySession](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/drm-c-dev-guide)，获取DRM许可证等。并根据需要设置音频解密配置(详见[音频解码开发指南开发步骤](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/audio-decoding#开发步骤)第4步)、设置视频解密配置（详见[视频解码开发指南开发步骤Surface模式](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/video-decoding#surface模式)第5步或[Buffer模式](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/video-decoding#buffer模式)第4步），实现DRM内容解密。
    
5.  获取文件信息。
    
    // 获取文件用户自定义属性（可选，若用户无需获取自定义属性，可跳过此步）。
    // 从文件 source 获取用户自定义属性信息。
    OH\_AVFormat \*customMetadataFormat = OH\_AVSource\_GetCustomMetadataFormat(source);
    if (customMetadataFormat == nullptr) {
       // 需释放前置流程资源，参考第10步。
       printf("get custom metadata format failed");
       return;
    }
    // 注意事项：
    // 1. customKey需与封装时写入的key完全一致（含完整命名层级），
    // 示例key仅为演示，实际应替换为用户自定义的字符串。
    // 例：封装时写入key为"com.openharmony.custom.meta.abc.efg"，
    // 获取时必须使用完整key，截断使用"com.openharmony.custom.meta.abc"会失败。
    // 2. value类型需与封装时数据类型匹配，示例为string类型。其余类型需调用对应接口，支持int/float类型；API version 20起，支持buffer类型。
    const char \*customKey = "com.openharmony.custom.meta.string"; // 替换为实际封装时使用的完整key。
    const char \*customValue;
    if (!OH\_AVFormat\_GetStringValue(customMetadataFormat, customKey, &customValue)) {
       printf("get custom metadata from custom metadata format failed");
    }
    OH\_AVFormat\_Destroy(customMetadataFormat);
    customMetadataFormat = nullptr;
    
    // 获取文件轨道数（可选，若用户已知轨道信息，可跳过此步）。
    // 从文件 source 信息获取文件轨道数，用户可通过该接口获取文件级别属性，具体支持信息参考附表 1。
    OH\_AVFormat \*sourceFormat = OH\_AVSource\_GetSourceFormat(source);
    if (sourceFormat == nullptr) {
       // 需释放前置流程资源，参考第10步。
       printf("get source format failed");
       return;
    }
    int32\_t trackCount = 0;
    if (!OH\_AVFormat\_GetIntValue(sourceFormat, OH\_MD\_KEY\_TRACK\_COUNT, &trackCount)) {
       printf("get track count from source format failed");
    }
    if (trackCount == 0) {
       // 文件中无轨道，需根据业务做其他处理。
       printf("no track");
    }
    OH\_AVFormat\_Destroy(sourceFormat);
    sourceFormat = nullptr;
    
6.  获取轨道index及信息（可选，若用户已知轨道信息，可跳过此步）。
    
    uint32\_t audioTrackIndex = 0;
    uint32\_t videoTrackIndex = 0;
    int32\_t w = 0;
    int32\_t h = 0;
    int64\_t bitRate = 0; // 配置比特率，单位为bps。
    double frameRate = 0.0;
    const char\* mimetype = nullptr;
    uint8\_t \*codecConfig = nullptr;
    size\_t bufferSize = 0;
    int32\_t trackType = -1;
    for (uint32\_t index = 0; index < (static\_cast<uint32\_t>(trackCount)); index++) {
       // 获取轨道信息，用户可通过该接口获取对应轨道级别属性，具体支持信息参考附表 2。
       OH\_AVFormat \*trackFormat = OH\_AVSource\_GetTrackFormat(source, index);
       if (trackFormat == nullptr) {
          printf("get track format failed");
          return;
       }
       // 获取轨道类型, 不支持的类型不会修改trackType的值。
       // 注意trackType初始值建议设为非有效值（如-1），避免误用。
       if (!OH\_AVFormat\_GetIntValue(trackFormat, OH\_MD\_KEY\_TRACK\_TYPE, &trackType)) {
          printf("get track type from track format failed");
          return;
       }
       if (trackType == OH\_MediaType::MEDIA\_TYPE\_AUXILIARY) {
          const char \*referenceType;
          if (!OH\_AVFormat\_GetStringValue(trackFormat, OH\_MD\_KEY\_TRACK\_REFERENCE\_TYPE, &referenceType)) {
             printf("get reference type from auxiliary track failed");
          }
          int32\_t\* referenceIds;
          size\_t referenceIdsCount;
          if (!OH\_AVFormat\_GetIntBuffer(trackFormat, OH\_MD\_KEY\_REFERENCE\_TRACK\_IDS, &referenceIds, &referenceIdsCount)) {
             printf("get reference track ids from auxiliary track failed");
          }
          // 根据辅助轨类型处理轨道参考关系。
       }
       static\_cast<OH\_MediaType>(trackType) == OH\_MediaType::MEDIA\_TYPE\_AUD ? audioTrackIndex = index : videoTrackIndex = index;
       // 获取视频轨宽高。
       if (trackType == OH\_MediaType::MEDIA\_TYPE\_VID) {
          if (!OH\_AVFormat\_GetIntValue(trackFormat, OH\_MD\_KEY\_WIDTH, &w)) {
             printf("get track width from track format failed");
             return;
          }
          if (!OH\_AVFormat\_GetIntValue(trackFormat, OH\_MD\_KEY\_HEIGHT, &h)) {
             printf("get track height from track format failed");
             return;
          }
          if (!OH\_AVFormat\_GetLongValue(trackFormat, OH\_MD\_KEY\_BITRATE, &bitRate)) {
             printf("get track bitRate from track format failed");
             return;
          }
          if (!OH\_AVFormat\_GetDoubleValue(trackFormat, OH\_MD\_KEY\_FRAME\_RATE, &frameRate)) {
             printf("get track frameRate from track format failed");
             return;
          }
          if (!OH\_AVFormat\_GetStringValue(trackFormat, OH\_MD\_KEY\_CODEC\_MIME, &mimetype)) {
             printf("get track mimetype from track format failed");
             return;
          }
          if (!OH\_AVFormat\_GetBuffer(trackFormat, OH\_MD\_KEY\_CODEC\_CONFIG, &codecConfig, &bufferSize)) {
             printf("get track codecConfig from track format failed");
             return;
          }
          printf(" track width%d, track height：%d, track bitRate：%ld, track frameRate：%f, track mimetype：%s\\n", w, h, bitRate, frameRate, mimetype);
       }
       OH\_AVFormat\_Destroy(trackFormat);
       trackFormat = nullptr;
    }
    
7.  添加解封装轨道。
    
    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);
    
8.  调整轨道到指定时间点（可选）。
    
    // 调整轨道到指定时间点，后续从该时间点进行解封装。
    // 注意：
    // 1. mpegts、mpg 格式文件使用OH\_AVDemuxer\_SeekToTime功能时，跳转到的位置可能为非关键帧。可在跳转后调用OH\_AVDemuxer\_ReadSampleBuffer，通过获取到的OH\_AVCodecBufferAttr判断当前帧是否为关键帧。若非关键帧影响应用侧显示等功能，可在跳转后循环读取，获取到后续第一帧关键帧后，再进行解码等处理。
    // 2. ogg格式文件使用OH\_AVDemuxer\_SeekToTime功能时，会跳转到传入时间millisecond所在时间间隔(秒)的起始处，可能会导致一定数量的帧误差。
    // 3. demuxer的seek处理只针对解码行为一致的码流进行处理，如果seek后需要解码器重新配置参数，或者需要重新送入参数集的数据才可以正确解码的码流，seek后可能会出现花屏、解码卡死等问题。
    OH\_AVDemuxer\_SeekToTime(demuxer, 0, OH\_AVSeekMode::SEEK\_MODE\_CLOSEST\_SYNC);
    
9.  开始解封装，循环获取sample（以含音频、视频两轨的文件为例）。
    
    BufferAttr包含的属性：
    
    *   size：sample尺寸；
    *   offset：数据在AVBuffer中的偏移，一般为0；
    *   pts：文件封装的显示时间戳；
    *   flags：sample属性。
    
    | flag | 描述 |
    | :-- | :-- |
    | AVCODEC\_BUFFER\_FLAGS\_NONE | 默认。 |
    | AVCODEC\_BUFFER\_FLAGS\_EOS | 结尾sample，数据为空。 |
    | AVCODEC\_BUFFER\_FLAGS\_SYNC\_FRAME | IDR帧或I帧。 |
    | AVCODEC\_BUFFER\_FLAGS\_INCOMPLETE\_FRAME | 非完整的sample，一般由于buffer过小，无法拷贝完整的sample。 |
    | AVCODEC\_BUFFER\_FLAGS\_CODEC\_DATA | 含参数集信息的帧。 |
    | AVCODEC\_BUFFER\_FLAGS\_DISCARD | 可丢弃的帧。 |
    
    OH\_AVDemuxer\_ReadSampleBuffer接口本身可能存在耗时久，取决于文件IO，建议以异步方式进行调用。
    
    // 为每个线程定义处理函数。
    void ReadTrackSamples(OH\_AVDemuxer \*demuxer, uint32\_t trackIndex, int32\_t buffer\_size,
                          std::atomic<bool>& isEnd, std::atomic<bool>& threadFinished)
    {
       // 创建缓冲区。
       OH\_AVBuffer \*buffer = OH\_AVBuffer\_Create(buffer\_size);
       if (buffer == nullptr) {
          printf("Create buffer failed for track %d\\n", trackIndex);
          threadFinished.store(true);
          return;
       }
       OH\_AVCodecBufferAttr info;
       int32\_t ret;
    
       while (!isEnd.load()) {
          // 在调用OH\_AVDemuxer\_ReadSampleBuffer接口获取数据前，需要先调用OH\_AVDemuxer\_SelectTrackByID选中需要获取数据的轨道。
          // 注意：
          // 在avi、mpg、wmv格式下，由于容器标准不支持封装时间戳信息，所以demuxer解出的帧中不含pts信息，需要调用方根据帧率及解码出帧后的显示顺序自行计算显示时间戳信息。
          ret = OH\_AVDemuxer\_ReadSampleBuffer(demuxer, trackIndex, buffer);
          if (ret == AV\_ERR\_OK) {
                OH\_AVBuffer\_GetBufferAttr(buffer, &info);
                printf("Track %d sample size: %d\\n", trackIndex, info.size);
                // 检查EOS标志。
                if (info.flags == OH\_AVCodecBufferFlags::AVCODEC\_BUFFER\_FLAGS\_EOS) {
                   isEnd.store(true);
                }
                // 处理缓冲区数据（这里可以根据需要实现解码逻辑）。
          } else {
                printf("Read sample failed for track %d\\n", trackIndex);
                break;
          }
       }
       // 销毁缓冲区。
       OH\_AVBuffer\_Destroy(buffer);
       buffer = nullptr;
       threadFinished.store(true);
    }
    
    // 根据需求计算合适的缓冲区大小。
    int32\_t audioBufferSize = 4096;  // 典型音频缓冲区大小。
    int32\_t videoBufferSize = w \* h \* 3 >> 1;  // 原始视频缓冲区大小。
    
    // 创建原子变量用于线程通信。
    std::atomic<bool> audioIsEnd{false}, videoIsEnd{false}; // 表示流是否结束。
    std::atomic<bool> audioThreadFinished{false}, videoThreadFinished{false}; // 表示线程是否暂停。
    
    // 创建线程。
    std::thread audioThread(ReadTrackSamples, demuxer, audioTrackIndex, audioBufferSize,
                            std::ref(audioIsEnd), std::ref(audioThreadFinished));
    std::thread videoThread(ReadTrackSamples, demuxer, videoTrackIndex, videoBufferSize,
                            std::ref(videoIsEnd), std::ref(videoThreadFinished));
    audioThread.join();
    videoThread.join();
    
10.  销毁解封装实例。
     
     // 需要用户调用 OH\_AVSource\_Destroy 接口成功后，手动将实例置为nullptr，对同一实例重复调用 OH\_AVSource\_Destroy 会导致程序错误。
     if (OH\_AVSource\_Destroy(source) != AV\_ERR\_OK) {
        printf("destroy source pointer error");
     }
     source = nullptr;
     // 需要用户调用 OH\_AVDemuxer\_Destroy 接口成功后，手动将实例置为nullptr，对同一实例重复调用 OH\_AVDemuxer\_Destroy 会导致程序错误。
     if (OH\_AVDemuxer\_Destroy(demuxer) != AV\_ERR\_OK) {
        printf("destroy demuxer pointer error");
     }
     demuxer = nullptr;
     close(fd);
     

#### 附表

#### \[h2\]文件级别属性支持范围

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/bb/v3/uifxpoVSQG-DMY_S7BVcsg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132518Z&HW-CC-Expire=86400&HW-CC-Sign=294B8A056C46B23B08F9415A9EC494DDC5AB3C507ED50420A967B2AB9A66CEDF)

*   正常解析时才可以获取对应属性数据，如果文件信息错误或缺失，将导致解析异常，无法获取数据。
*   当前GBK格式字符集数据会转换为UTF8提供，其他类型字符集如果需要转换为UTF8格式使用，需要调用方自行转换，参考[icu4c](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/icu4c)。
*   从API version 23开始，部分OGG格式资源，如OH\_MD\_KEY\_TITLE、OH\_MD\_KEY\_ARTIST和OH\_MD\_KEY\_ALBUM存在于轨道属性中，可从轨道级别属性中获取。
*   数据类型及详细取值范围参考[媒体数据键值对](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-codecbase#媒体数据键值对)。

**表1** 文件级别属性支持范围

| 名称 | 描述 |
| :-- | :-- |
| OH\_MD\_KEY\_TITLE | 文件标题的键 |
| OH\_MD\_KEY\_ARTIST | 文件艺术家的键 |
| OH\_MD\_KEY\_ALBUM | 文件专辑的键 |
| OH\_MD\_KEY\_ALBUM\_ARTIST | 文件专辑艺术家的键 |
| OH\_MD\_KEY\_DATE | 文件日期的键 |
| OH\_MD\_KEY\_COMMENT | 文件注释的键 |
| OH\_MD\_KEY\_GENRE | 文件流派的键 |
| OH\_MD\_KEY\_COPYRIGHT | 文件版权的键 |
| OH\_MD\_KEY\_LANGUAGE | 文件语言的键 |
| OH\_MD\_KEY\_DESCRIPTION | 文件描述的键 |
| OH\_MD\_KEY\_LYRICS | 文件歌词的键 |
| OH\_MD\_KEY\_TRACK\_COUNT | 文件轨道数量的键 |
| OH\_MD\_KEY\_DURATION | 文件时长的键 |
| OH\_MD\_KEY\_START\_TIME | 文件起始时间的键 |

#### \[h2\]轨道级别属性支持范围

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/0b/v3/w-VV2BjKT8qTS0sDxWgjzg/note_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260709T132518Z&HW-CC-Expire=86400&HW-CC-Sign=BA1C0A2BED280B8846428D7BAEB3FCBD8CE302F6730392D62F15044C22B50CFD)

正常解析时才可以获取对应属性数据；如果文件信息错误或缺失，将导致解析异常，无法获取数据。

辅助轨属性范围与实际媒体类型（音频、视频）保持一致。

数据类型及详细取值范围参考[媒体数据键值对](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/capi-codecbase#媒体数据键值对)。

**表2** 轨道级别属性支持范围

| 名称 | 描述 | 视频轨支持 | 音频轨支持 | 字幕轨支持 | 辅助轨支持 |
| :-- | :-- | :-- | :-- | :-- | :-- |
| OH\_MD\_KEY\_CODEC\_MIME | 码流编解码器类型的键。 | √ | √ | √ | √ |
| OH\_MD\_KEY\_TRACK\_TYPE | 码流媒体类型的键。 | √ | √ | √ | √ |
| OH\_MD\_KEY\_TRACK\_START\_TIME | 码流起始时间的键。 | √ | √ | √ | √ |
| OH\_MD\_KEY\_BITRATE | 码流比特率的键。 | √ | √ | \- | √ |
| OH\_MD\_KEY\_LANGUAGE | 码流语言类型的键。 | √ | √ | \- | √ |
| OH\_MD\_KEY\_CODEC\_CONFIG | 编解码器特定数据的键，视频中表示传递参数集，音频中表示传递解码器的参数配置信息。 | √ | √ | \- | √ |
| OH\_MD\_KEY\_WIDTH | 视频流宽度的键。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_HEIGHT | 视频流高度的键。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_FRAME\_RATE | 视频流帧率的键。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_ROTATION | 视频流旋转角度的键。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_VIDEO\_SAR | 视频流样本长宽比的键。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_PROFILE | 视频流编码档次，只针对h265码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_RANGE\_FLAG | 视频流视频YUV值域标志的键，只针对h265码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_COLOR\_PRIMARIES | 视频流视频色域的键，只针对h265码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_TRANSFER\_CHARACTERISTICS | 视频流视频传递函数的键，只针对h265码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_MATRIX\_COEFFICIENTS | 视频矩阵系数的键，只针对h265码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_VIDEO\_IS\_HDR\_VIVID | 视频流标记是否为HDR Vivid的键，只针对HDR Vivid码流使用。 | √ | \- | \- | √ |
| OH\_MD\_KEY\_AUD\_SAMPLE\_RATE | 音频流采样率的键。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_AUD\_CHANNEL\_COUNT | 音频流通道数的键。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_CHANNEL\_LAYOUT | 音频流所需编码通道布局的键。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_AUDIO\_SAMPLE\_FORMAT | 音频流样本格式的键。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_AAC\_IS\_ADTS | aac格式的键，只针对aac码流使用。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_BITS\_PER\_CODED\_SAMPLE | 音频流每个编码样本位数的键。 | \- | √ | \- | √ |
| OH\_MD\_KEY\_REFERENCE\_TRACK\_IDS | 媒体文件轨道间参考、被参考关系。 | √ | √ | √ | √ |
| OH\_MD\_KEY\_TRACK\_REFERENCE\_TYPE | 媒体文件辅助轨类型。 | \- | \- | \- | √ |
| OH\_MD\_KEY\_TRACK\_DESCRIPTION | 媒体文件辅助轨描述信息。 | \- | \- | \- | √ |