1# native_avdemuxer.h 2 3## Overview 4 5The file declares the APIs for parsing audio and video media data. 6 7**File to include**: <multimedia/player_framework/native_avdemuxer.h> 8 9**Library**: libnative_media_avdemuxer.so 10 11**System capability**: SystemCapability.Multimedia.Media.Spliter 12 13**Since**: 10 14 15**Related module**: [AVDemuxer](capi-avdemuxer.md) 16 17**Sample**: [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 18 19## Summary 20 21### Structs 22 23| Name| typedef Keyword| Description| 24| -- | -- | -- | 25| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) | OH_AVDemuxer | Describes a native object for the OH_AVDemuxer interface.| 26| [DRM_MediaKeySystemInfo](capi-avdemuxer-drm-mediakeysysteminfo.md) | DRM_MediaKeySystemInfo | Describes a native object for the DRM_MediaKeySystemInf interface.| 27 28### Functions 29 30| Name| typedef Keyword| Description| 31| -- | -- | -- | 32| [typedef void (\*DRM_MediaKeySystemInfoCallback)(DRM_MediaKeySystemInfo* mediaKeySystemInfo)](#drm_mediakeysysteminfocallback) | DRM_MediaKeySystemInfoCallback | Defines a pointer to the callback function for **DRM_MediaKeySystemInfo**. No demuxer instance is returned. This callback function applies to the scenario where a single demuxer instance is used. You need to call **OH_AVDemuxer_SetMediaKeySystemInfoCallback** to set the callback function as a callback.| 33| [typedef void (\*Demuxer_MediaKeySystemInfoCallback)(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo)](#demuxer_mediakeysysteminfocallback) | Demuxer_MediaKeySystemInfoCallback | Defines a pointer to the callback function for **DRM_MediaKeySystemInfo**. A demuxer instance is returned. This callback function applies to the scenario where multiple demuxer instances are used. You need to call **OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback** to set the callback function as a callback. This callback function is recommended.| 34| [OH_AVDemuxer *OH_AVDemuxer_CreateWithSource(OH_AVSource *source)](#oh_avdemuxer_createwithsource) | - | Creates an OH_AVDemuxer instance based on a source instance. For details about how to create, destroy, and use a source instance, see [OH_AVSource](_a_v_source.md).| 35| [OH_AVErrCode OH_AVDemuxer_Destroy(OH_AVDemuxer *demuxer)](#oh_avdemuxer_destroy) | - | Destroys an OH_AVDemuxer instance and clears internal resources. An instance can be destroyed only once. The destroyed instance cannot be used until it is re-created. You are advised to set the pointer to NULL after the instance is destroyed.| 36| [OH_AVErrCode OH_AVDemuxer_SelectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex)](#oh_avdemuxer_selecttrackbyid) | - | Selects a track from which the demuxer reads sample data. You can select multiple tracks by calling this API multiple times, with a different track index passed in each time. When **OH_AVDemuxer_ReadSample** is called, only the data in the selected track is read. If the same track is selected multiple times, **AV_ERR_OK** is returned and the API call takes effect only once.| 37| [OH_AVErrCode OH_AVDemuxer_UnselectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex)](#oh_avdemuxer_unselecttrackbyid) | - | Deselects a track. The demuxer no longer reads sample data from a track after it is deselected. You can deselect multiple tracks by calling this API multiple times, with a different track index passed in each time. If the same track is deselected multiple times, **AV_ERR_OK** is returned and the API call takes effect only once.| 38| [OH_AVErrCode OH_AVDemuxer_ReadSample(OH_AVDemuxer *demuxer, uint32_t trackIndex,OH_AVMemory *sample, OH_AVCodecBufferAttr *info)](#oh_avdemuxer_readsample) | - | Reads the sample and related information from the specified track. You must select a track before reading the sample. After this API is called, the demuxer automatically proceeds to the next frame.| 39| [OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer(OH_AVDemuxer *demuxer, uint32_t trackIndex,OH_AVBuffer *sample)](#oh_avdemuxer_readsamplebuffer) | - | Reads the sample and related information from the specified track. You must select a track before reading the sample. After this API is called, the demuxer automatically proceeds to the next frame.| 40| [OH_AVErrCode OH_AVDemuxer_SeekToTime(OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode)](#oh_avdemuxer_seektotime) | - | Seeks to the specified time for all the selected tracks based on a seek mode.| 41| [OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,DRM_MediaKeySystemInfoCallback callback)](#oh_avdemuxer_setmediakeysysteminfocallback) | - | Sets a callback for obtaining the media key system information.| 42| [OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,Demuxer_MediaKeySystemInfoCallback callback)](#oh_avdemuxer_setdemuxermediakeysysteminfocallback) | - | Sets an asynchronous callback for obtaining the media key system information.| 43| [OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo)](#oh_avdemuxer_getmediakeysysteminfo) | - | Obtains the media key system information. The media key system information can be obtained only after **Demuxer_MediaKeySystemInfoCallback** or **DRM_MediaKeySystemInfoCallback** is successfully invoked.| 44 45## Function Description 46 47### DRM_MediaKeySystemInfoCallback() 48 49``` 50typedef void (*DRM_MediaKeySystemInfoCallback)(DRM_MediaKeySystemInfo* mediaKeySystemInfo) 51``` 52 53**Description** 54 55Defines a pointer to the callback function for DRM_MediaKeySystemInfo. No demuxer instance is returned. This callback function applies to the scenario where a single demuxer instance is used. 56 57You need to call [OH_AVDemuxer_SetMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback) to set the callback function as a callback. 58 59**System capability**: SystemCapability.Multimedia.Media.Spliter 60 61**Since**: 11 62 63**Deprecated from**: 14 64 65**Substitute**: [Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback) 66 67### Demuxer_MediaKeySystemInfoCallback() 68 69``` 70typedef void (*Demuxer_MediaKeySystemInfoCallback)(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo) 71``` 72 73**Description** 74 75Defines a pointer to the callback function for **DRM_MediaKeySystemInfo**. A demuxer instance is returned. This callback function applies to the scenario where multiple demuxer instances are used. 76 77You need to call [OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback) to set the callback function as a callback. This callback function is recommended. 78 79**System capability**: SystemCapability.Multimedia.Media.Spliter 80 81**Since**: 12 82 83### OH_AVDemuxer_CreateWithSource() 84 85``` 86OH_AVDemuxer *OH_AVDemuxer_CreateWithSource(OH_AVSource *source) 87``` 88 89**Description** 90 91Creates an OH_AVDemuxer instance based on a source instance. 92 93For details about how to create, destroy, and use a source instance, see [OH_AVSource](_a_v_source.md). 94 95**System capability**: SystemCapability.Multimedia.Media.Spliter 96 97**Since**: 10 98 99 100**Parameters** 101 102| Name| Description| 103| -- | -- | 104| [OH_AVSource](_a_v_source.md#oh_avsource) *source | Pointer to an OH_AVSource instance.| 105 106**Returns** 107 108| Type| Description| 109| -- | -- | 110| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) * | Pointer to an OH_AVDemuxer instance.<br>If the operation fails, NULL is returned.<br>The possible causes of an operation failure are as follows:<br>1. The value of **source** is invalid, that is, nullptr.<br>2. The value of **source** does not point to an OH_AVSource instance. | 111 112### OH_AVDemuxer_Destroy() 113 114``` 115OH_AVErrCode OH_AVDemuxer_Destroy(OH_AVDemuxer *demuxer) 116``` 117 118**Description** 119 120Destroys an OH_AVDemuxer instance and clears internal resources. An instance can be destroyed only once. 121 122The destroyed instance cannot be used until it is re-created. You are advised to set the pointer to NULL after the instance is destroyed. 123 124**System capability**: SystemCapability.Multimedia.Media.Spliter 125 126**Since**: 10 127 128 129**Parameters** 130 131| Name| Description| 132| -- | -- | 133| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 134 135**Returns** 136 137| Type| Description| 138| -- | -- | 139| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **demuxer** is nullptr or does not point to a demuxer instance.| 140 141### OH_AVDemuxer_SelectTrackByID() 142 143``` 144OH_AVErrCode OH_AVDemuxer_SelectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex) 145``` 146 147**Description** 148 149Selects a track from which the demuxer reads sample data. 150 151You can select multiple tracks by calling this API multiple times, with a different track index passed in each time. 152 153When [OH_AVDemuxer_ReadSample](#oh_avdemuxer_readsample) is called, only the data in the selected track is read. If the same track is selected multiple times, **AV_ERR_OK** is returned and the API call takes effect only once. 154 155**System capability**: SystemCapability.Multimedia.Media.Spliter 156 157**Since**: 10 158 159 160**Parameters** 161 162| Name| Description| 163| -- | -- | 164| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 165| uint32_t trackIndex | Index of the track.| 166 167**Returns** 168 169| Type| Description| 170| -- | -- | 171| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **demuxer** is nullptr or does not point to a demuxer instance.<br>2. The track index is out of range.<br>3. Track reading is not supported.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The demuxer is not correctly initialized.| 172 173### OH_AVDemuxer_UnselectTrackByID() 174 175``` 176OH_AVErrCode OH_AVDemuxer_UnselectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex) 177``` 178 179**Description** 180 181Deselects a track. The demuxer no longer reads sample data from a track after it is deselected. 182 183You can deselect multiple tracks by calling this API multiple times, with a different track index passed in each time. 184 185If the same track is deselected multiple times, **AV_ERR_OK** is returned and the API call takes effect only once. 186 187**System capability**: SystemCapability.Multimedia.Media.Spliter 188 189**Since**: 10 190 191 192**Parameters** 193 194| Name| Description| 195| -- | -- | 196| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 197| uint32_t trackIndex | Index of the track.| 198 199**Returns** 200 201| Type| Description| 202| -- | -- | 203| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **demuxer** is nullptr or does not point to a demuxer instance.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The demuxer is not correctly initialized.| 204 205### OH_AVDemuxer_ReadSample() 206 207``` 208OH_AVErrCode OH_AVDemuxer_ReadSample(OH_AVDemuxer *demuxer, uint32_t trackIndex,OH_AVMemory *sample, OH_AVCodecBufferAttr *info) 209``` 210 211**Description** 212 213Reads the sample and related information from the specified track. 214 215You must select a track before reading the sample. After this API is called, the demuxer automatically proceeds to the next frame. 216 217**System capability**: SystemCapability.Multimedia.Media.Spliter 218 219**Since**: 10 220 221**Deprecated from**: 11 222 223**Substitute**: [OH_AVDemuxer_ReadSampleBuffer](#oh_avdemuxer_readsamplebuffer) 224 225 226**Parameters** 227 228| Name| Description| 229| -- | -- | 230| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 231| uint32_t trackIndex | Index of the track from which the compressed frame is to be read.| 232| [OH_AVMemory](_core.md#oh_avmemory) *sample | Pointer to the OH_AVMemory instance for storing the compressed frame data.| 233| [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) *info | Pointer to the OH_AVCodecBufferAttr instance for storing the compressed frame information.| 234 235**Returns** 236 237| Type| Description| 238| -- | -- | 239| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **demuxer** is nullptr or does not point to a demuxer instance.<br>2. The track index is out of range.<br>3. Track reading is not supported.<br>4. The value of **sample** is null.<br>5. The value of **info** is null.<br>**AV_ERR_OPERATE_NOT_PERMIT**:<br>1. The track with the specified index is not selected.<br>2. The demuxer is not correctly initialized.<br>**AV_ERR_NO_MEMORY**: The sample capacity is insufficient to store all frame data.<br>**AV_ERR_UNKNOWN**: Failed to read or parse the frame from the file.| 240 241### OH_AVDemuxer_ReadSampleBuffer() 242 243``` 244OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer(OH_AVDemuxer *demuxer, uint32_t trackIndex,OH_AVBuffer *sample) 245``` 246 247**Description** 248 249Reads the sample and related information from the specified track. 250 251You can use [OH_AVDemuxer_SelectTrackByID](#oh_avdemuxer_selecttrackbyid) to select a track before reading the sample. After this API is called, the demuxer automatically proceeds to the next frame. 252 253**System capability**: SystemCapability.Multimedia.Media.Spliter 254 255**Since**: 11 256 257 258**Parameters** 259 260| Name| Description| 261| -- | -- | 262| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 263| uint32_t trackIndex | Index of the track from which the compressed frame is to be read.. | 264| [OH_AVBuffer](_core.md#oh_avbuffer) *sample | Pointer to the OH_AVBuffer instance for storing the compressed frame data and related information.| 265 266**Returns** 267 268| Type| Description| 269| -- | -- | 270| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **demuxer** is nullptr or does not point to a demuxer instance.<br>2. The value of **sample** is nullptr.<br>3. The track index is out of range.<br>4. The value of **sample** is null.<br>**AV_ERR_OPERATE_NOT_PERMIT**:<br>1. The track with the specified index is not selected.<br>2. The demuxer is not correctly initialized.<br>**AV_ERR_NO_MEMORY**: The sample capacity is insufficient to store all frame data.<br>**AV_ERR_UNKNOWN**: Failed to read or parse the frame from the file.| 271 272### OH_AVDemuxer_SeekToTime() 273 274``` 275OH_AVErrCode OH_AVDemuxer_SeekToTime(OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode) 276``` 277 278**Description** 279 280Seeks to the specified time for all the selected tracks based on a [seek mode](capi-native-avcodec-base-h.md#oh_avseekmode). 281 282**System capability**: SystemCapability.Multimedia.Media.Spliter 283 284**Since**: 10 285 286 287**Parameters** 288 289| Name| Description| 290| -- | -- | 291| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 292| int64_t millisecond | Time to seek to, in milliseconds. The timestamp is relative to the start position of the file.| 293| [OH_AVSeekMode](capi-native-avcodec-base-h.md#oh_avseekmode) mode | Seek mode.| 294 295**Returns** 296 297| Type| Description| 298| -- | -- | 299| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **demuxer** is nullptr or does not point to a demuxer instance.<br>2. The value of **millisecond** is out of range.<br>**AV_ERR_OPERATE_NOT_PERMIT**:<br>1. The track with the specified index is not selected.<br>2. The demuxer is not correctly initialized.<br>3. The seek operation cannot be performed on the resource.<br>**AV_ERR_UNKNOWN**:<br>1. The seek operation fails.<br>2. **OH_AVSeekMode** is set to **SEEK_MODE_NEXT_SYNC** and there is no I-frame following the specified position.| 300 301### OH_AVDemuxer_SetMediaKeySystemInfoCallback() 302 303``` 304OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,DRM_MediaKeySystemInfoCallback callback) 305``` 306 307**Description** 308 309Sets a callback for obtaining the media key system information. 310 311**System capability**: SystemCapability.Multimedia.Media.Spliter 312 313**Since**: 11 314 315**Deprecated from**: 14 316 317**Substitute**: [OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback) 318 319 320**Parameters** 321 322| Name| Description| 323| -- | -- | 324| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 325| [DRM_MediaKeySystemInfoCallback](#drm_mediakeysysteminfocallback) callback | Callback function.| 326 327**Returns** 328 329| Type| Description| 330| -- | -- | 331| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The demuxer is not correctly initialized.<br>**AV_ERR_INVALID_VAL**: The value of **demuxer** is nullptr or does not point to a demuxer instance.| 332 333### OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback() 334 335``` 336OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer,Demuxer_MediaKeySystemInfoCallback callback) 337``` 338 339**Description** 340 341Sets a callback for obtaining the media key system information. 342 343**System capability**: SystemCapability.Multimedia.Media.Spliter 344 345**Since**: 12 346 347 348**Parameters** 349 350| Name| Description| 351| -- | -- | 352| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 353| [Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback) callback | Callback function.| 354 355**Returns** 356 357| Type| Description| 358| -- | -- | 359| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_OPERATE_NOT_PERMIT**: The demuxer is not correctly initialized.<br>**AV_ERR_INVALID_VAL**: The value of **demuxer** is nullptr or does not point to a demuxer instance.| 360 361### OH_AVDemuxer_GetMediaKeySystemInfo() 362 363``` 364OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo) 365``` 366 367**Description** 368 369Obtains the media key system information. The media key system information can be obtained only after [Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback) or [DRM_MediaKeySystemInfoCallback](#drm_mediakeysysteminfocallback) is successfully invoked. 370 371**System capability**: SystemCapability.Multimedia.Media.Spliter 372 373**Since**: 11 374 375 376**Parameters** 377 378| Name| Description| 379| -- | -- | 380| [OH_AVDemuxer](capi-avdemuxer-oh-avdemuxer.md) *demuxer | Pointer to an OH_AVDemuxer instance.| 381| [DRM_MediaKeySystemInfo](capi-avdemuxer-drm-mediakeysysteminfo.md) *mediaKeySystemInfo | Pointer to the media key system information.| 382 383**Returns** 384 385| Type| Description| 386| -- | -- | 387| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**:<br>1. The value of **demuxer** is nullptr or does not point to a demuxer instance.<br> 2. The value of **mediaKeySystemInfo** is nullptr.| 388