1# AVDemuxer
2
3
4## 概述
5
6AVDemuxer模块提供从媒体文件码流中提取[sample](../../media/avcodec/audio-video-demuxer.md)的接口。
7
8对应的开发指南及样例可参考[媒体数据解析](../../media/avcodec/audio-video-demuxer.md)。
9
10**系统能力：** SystemCapability.Multimedia.Media.Spliter
11
12**起始版本：** 10
13
14
15## 汇总
16
17
18### 文件
19
20| 名称 | 描述 |
21| -------- | -------- |
22| [native_avdemuxer.h](native__avdemuxer_8h.md) | 声明用于音视频媒体数据解析的接口。 |
23
24### 类型定义
25
26| 名称 | 描述 |
27| -------- | -------- |
28| typedef void(* [DRM_MediaKeySystemInfoCallback](#drm_mediakeysysteminfocallback)) (DRM_MediaKeySystemInfo *mediaKeySystemInfo) | [DRM_MediaKeySystemInfo](../apis-drm-kit/_d_r_m___media_key_system_info.md)回调函数指针类型，不返回解封装器实例，适用于单个解封装器实例场景。需要使用[OH_AVDemuxer_SetMediaKeySystemInfoCallback](#oh_avdemuxer_setmediakeysysteminfocallback)接口将其设置为回调。（API14废弃）  |
29| typedef void(* [Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback)) (OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo)| [DRM_MediaKeySystemInfo](../apis-drm-kit/_d_r_m___media_key_system_info.md)回调函数指针类型，返回解封装器实例，适用于多个解封装器实例场景。需要使用[OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback)接口将其设置为回调，推荐使用。  |
30
31
32### 函数
33
34| 名称 | 描述 |
35| -------- | -------- |
36| OH_AVDemuxer \* [OH_AVDemuxer_CreateWithSource](#oh_avdemuxer_createwithsource) ([OH_AVSource](_a_v_source.md#oh_avsource) \*source) | 通过source实例创建OH_AVDemuxer实例。 |
37| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_Destroy](#oh_avdemuxer_destroy) (OH_AVDemuxer \*demuxer) | 销毁OH_AVDemuxer实例并清理内部资源。 |
38| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_SelectTrackByID](#oh_avdemuxer_selecttrackbyid) (OH_AVDemuxer \*demuxer, uint32_t trackIndex) | 指定读取sample的轨道，解封装器将会从该轨道中读取数据，未指定的轨道不会读取。 |
39| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_UnselectTrackByID](#oh_avdemuxer_unselecttrackbyid) (OH_AVDemuxer \*demuxer, uint32_t trackIndex) | 移除读取sample的轨道，未选中的轨道的数据不会被解封装器读取。 |
40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_ReadSample](#oh_avdemuxer_readsample) (OH_AVDemuxer \*demuxer, uint32_t trackIndex, [OH_AVMemory](_core.md#oh_avmemory) \*sample, [OH_AVCodecBufferAttr](_o_h___a_v_codec_buffer_attr.md) \*info) | 获取指定轨道的sample及相关信息（API11废弃）。  |
41| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_ReadSampleBuffer](#oh_avdemuxer_readsamplebuffer) (OH_AVDemuxer \*demuxer, uint32_t trackIndex, [OH_AVBuffer](_core.md#oh_avbuffer) \*sample) | 获取指定轨道的sample。 |
42| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_SeekToTime](#oh_avdemuxer_seektotime) (OH_AVDemuxer \*demuxer, int64_t millisecond, [OH_AVSeekMode](_codec_base.md#oh_avseekmode) mode) | 根据设定的[跳转模式](_codec_base.md#oh_avseekmode-1)，将所有选中的轨道到指定时间附近。  |
43| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_SetMediaKeySystemInfoCallback](#oh_avdemuxer_setmediakeysysteminfocallback) (OH_AVDemuxer \*demuxer, DRM_MediaKeySystemInfoCallback callback) | 设置异步DRM信息回调函数。（API14废弃）  |
44| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback) (OH_AVDemuxer \*demuxer, Demuxer_MediaKeySystemInfoCallback callback) | 设置异步DRM信息回调函数。  |
45| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVDemuxer_GetMediaKeySystemInfo](#oh_avdemuxer_getmediakeysysteminfo) (OH_AVDemuxer \*demuxer, DRM_MediaKeySystemInfo \*mediaKeySystemInfo) | 获取DRM信息。  |
46
47
48## 类型定义说明
49
50### Demuxer_MediaKeySystemInfoCallback
51
52```
53typedef void(* Demuxer_MediaKeySystemInfoCallback) (OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo)
54```
55
56**描述**
57媒体密钥系统信息回调函数指针类型。
58
59**系统能力：** SystemCapability.Multimedia.Media.Spliter
60
61**起始版本：** 12
62
63
64### DRM_MediaKeySystemInfoCallback
65
66```
67typedef void(* DRM_MediaKeySystemInfoCallback) (DRM_MediaKeySystemInfo *mediaKeySystemInfo)
68```
69
70**描述**
71媒体密钥系统信息回调函数指针类型。
72
73**系统能力：** SystemCapability.Multimedia.Media.Spliter
74
75**起始版本：** 11
76
77**废弃版本：** 14
78
79**替代接口：**[Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback)
80
81
82## 函数说明
83
84
85### OH_AVDemuxer_CreateWithSource()
86
87```
88OH_AVDemuxer* OH_AVDemuxer_CreateWithSource (OH_AVSource *source)
89```
90**描述**
91通过source实例创建OH_AVDemuxer实例。
92
93source的创建、销毁及使用，详情请参考[OH_AVSource](_a_v_source.md)。
94
95**系统能力：** SystemCapability.Multimedia.Media.Spliter
96
97**起始版本：** 10
98
99**参数:**
100
101| 名称 | 描述 |
102| -------- | -------- |
103| source | 指向OH_AVSource实例的指针。  |
104
105**返回：**
106
107返回一个指向OH_AVDemuxer实例的指针。
108
109如果执行成功，则返回指向OH_AVDemuxer实例的指针，否则返回NULL。
110
111可能的失败原因：
1121. source无效，即空指针；
1132. 非OH_AVSource实例。
114
115
116### OH_AVDemuxer_Destroy()
117
118```
119OH_AVErrCode OH_AVDemuxer_Destroy (OH_AVDemuxer *demuxer)
120```
121**描述**
122销毁OH_AVDemuxer实例并清理内部资源。同一实例只能被销毁一次。注意，销毁的实例在被重新创建之前不能再被使用。建议实例销毁成功后将指针置为NULL。
123
124**系统能力：** SystemCapability.Multimedia.Media.Spliter
125
126**起始版本：** 10
127
128**参数:**
129
130| 名称 | 描述 |
131| -------- | -------- |
132| demuxer | 指向OH_AVDemuxer实例的指针。  |
133
134**返回：**
135
136返回函数结果：
137
138AV_ERR_OK：执行成功。
139
140AV_ERR_INVALID_VAL：输入的demuxer指针为空或为非解封装器实例。
141
142
143### OH_AVDemuxer_GetMediaKeySystemInfo()
144
145```
146OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo (OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo)
147```
148**描述**
149获取DRM信息。在[Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback)或[DRM_MediaKeySystemInfoCallback](#drm_mediakeysysteminfocallback)成功回调以后，调用此接口才能获取到DRM信息。
150
151**系统能力：** SystemCapability.Multimedia.Media.Spliter
152
153**起始版本：** 11
154
155**参数:**
156
157| 名称 | 描述 |
158| -------- | -------- |
159| demuxer | 指向OH_AVDemuxer实例的指针。  |
160| mediaKeySystemInfo | 指向DRM信息的指针，请参阅[DRM_MediaKeySystemInfo](../apis-drm-kit/_d_r_m___media_key_system_info.md)。  |
161
162**返回：**
163
164返回函数结果：
165
166AV_ERR_OK：执行成功。
167
168AV_ERR_INVALID_VAL：
169
170    1. 输入的demuxer指针为空或为非解封装器实例；
171    2. mediaKeySystemInfo为nullptr。
172
173
174### OH_AVDemuxer_ReadSample()
175
176```
177OH_AVErrCode OH_AVDemuxer_ReadSample (OH_AVDemuxer *demuxer, uint32_t trackIndex, OH_AVMemory *sample, OH_AVCodecBufferAttr *info)
178```
179**描述**
180获取指定轨道的sample及相关信息。
181
182注意，读取轨道sample前，轨道必须被选中。调用接口后解封装器将自动前进到下一帧。
183
184**系统能力：** SystemCapability.Multimedia.Media.Spliter
185
186**起始版本：** 10
187
188**废弃版本：** 11
189
190**替代接口：**[OH_AVDemuxer_ReadSampleBuffer](#oh_avdemuxer_readsamplebuffer)
191
192**参数:**
193
194| 名称 | 描述 |
195| -------- | -------- |
196| demuxer | 指向OH_AVDemuxer实例的指针。  |
197| trackIndex | 本次读取压缩帧的轨道的索引。  |
198| sample | 指向OH_AVMemory实例的指针，用于储存压缩帧数据。  |
199| info | 指向OH_AVCodecBufferAttr实例的指针，用于储存压缩帧的相关信息。  |
200
201**返回：**
202
203返回函数结果：
204
205AV_ERR_OK：执行成功。
206
207AV_ERR_INVALID_VAL：
208
209    1. 输入的demuxer指针为空或为非解封装器实例；
210    2. 轨道的索引超出范围；
211    3. 不支持读取轨道；
212    4. 输入sample为空；
213    5. 输入info为空。
214
215AV_ERR_OPERATE_NOT_PERMIT：
216
217    1. 轨道的索引没有被选中；
218    2. demuxer没有正确的初始化。
219
220AV_ERR_NO_MEMORY：sample容量不足以存储所有帧数据。
221
222AV_ERR_UNKNOWN：无法从文件中读取或解析帧。
223
224
225### OH_AVDemuxer_ReadSampleBuffer()
226
227```
228OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer (OH_AVDemuxer *demuxer, uint32_t trackIndex, OH_AVBuffer *sample)
229```
230**描述**
231获取指定轨道的sample及相关信息。
232
233注意，读取轨道sample前，轨道必须被选中,可使用[OH_AVDemuxer_SelectTrackByID](#oh_avdemuxer_selecttrackbyid)。调用接口后解封装器将自动前进到下一帧。
234
235**系统能力：** SystemCapability.Multimedia.Media.Spliter
236
237**起始版本：** 11
238
239**参数:**
240
241| 名称 | 描述 |
242| -------- | -------- |
243| demuxer | 指向OH_AVDemuxer实例的指针。  |
244| trackIndex | 本次读取压缩帧的轨道的索引。  |
245| sample | 指向OH_AVBuffer实例的指针，用于储存压缩帧数据以及相关信息。  |
246
247**返回：**
248
249返回函数结果：
250
251AV_ERR_OK：执行成功。
252
253AV_ERR_INVALID_VAL：
254
255    1. 输入的demuxer指针为空或为非解封装器实例；
256    2. sample为空指针；
257    3. 轨道的索引超出范围；
258    4. 输入sample为空。
259
260AV_ERR_OPERATE_NOT_PERMIT：
261
262    1. 轨道的索引没有被选中；
263    2. demuxer没有正确的初始化。
264
265AV_ERR_NO_MEMORY：sample容量不足以存储所有帧数据。
266
267AV_ERR_UNKNOWN：无法从文件中读取或解析帧。
268
269
270### OH_AVDemuxer_SeekToTime()
271
272```
273OH_AVErrCode OH_AVDemuxer_SeekToTime (OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode)
274```
275**描述**
276根据设定的[跳转模式](_codec_base.md#oh_avseekmode-1)，将所有选中的轨道到指定时间附近。
277
278**系统能力：** SystemCapability.Multimedia.Media.Spliter
279
280**起始版本：** 10
281
282**参数:**
283
284| 名称 | 描述 |
285| -------- | -------- |
286| demuxer | 指向OH_AVDemuxer实例的指针。  |
287| millisecond | 期望跳转位置对应的时间，单位为毫秒，该时间戳是相对文件开始的位置。  |
288| mode | 跳转的模式，参考[OH_AVSeekMode](_codec_base.md#oh_avseekmode)。  |
289
290**返回：**
291
292返回函数结果：
293
294AV_ERR_OK：执行成功。
295
296AV_ERR_INVALID_VAL：
297
298    1. 输入的demuxer指针为空或为非解封装器实例；
299    2. 毫秒值超出范围。
300
301AV_ERR_OPERATE_NOT_PERMIT：
302
303    1. 轨道的索引没有被选中；
304    2. demuxer没有正确的初始化；
305    3. 资源无法seek。
306
307AV_ERR_UNKNOWN：
308
309    1. seek失败；
310    2. OH_AVSeekMode选择SEEK_MODE_NEXT_SYNC，并且时间点后无I帧，可能会跳转失败。
311
312
313### OH_AVDemuxer_SelectTrackByID()
314
315```
316OH_AVErrCode OH_AVDemuxer_SelectTrackByID (OH_AVDemuxer *demuxer, uint32_t trackIndex)
317```
318**描述**
319指定读取sample的轨道，解封装器将会从该轨道中读取数据，未指定的轨道不会读取。注意，通过多次调用接口并传入不同轨道的索引来选中多个轨道。 调用OH_AVDemuxer_ReadSample时只会读取被选中的轨道中数据，同一轨道被选择多次时，接口会返回AV_ERR_OK，并且只会生效一次。
320
321**系统能力：** SystemCapability.Multimedia.Media.Spliter
322
323**起始版本：** 10
324
325**参数:**
326
327| 名称 | 描述 |
328| -------- | -------- |
329| demuxer | 指向OH_AVDemuxer实例的指针。  |
330| trackIndex | 需选择的轨道的索引。  |
331
332**返回：**
333
334返回函数结果：
335
336AV_ERR_OK：执行成功。
337
338AV_ERR_OPERATE_NOT_PERMIT：demuxer没有正确的初始化。
339
340AV_ERR_INVALID_VAL：
341
342    1. 输入的demuxer指针为空或为非解封装器实例；
343    2. 轨道的索引超出范围；
344    3. 不支持读取轨道。
345
346
347### OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback()
348
349```
350OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback (OH_AVDemuxer *demuxer, Demuxer_MediaKeySystemInfoCallback callback)
351```
352**描述**
353设置DRM信息回调函数。
354
355**系统能力：** SystemCapability.Multimedia.Media.Spliter
356
357**起始版本：** 12
358
359**参数:**
360
361| 名称 | 描述 |
362| -------- | -------- |
363| demuxer | 指向OH_AVDemuxer实例的指针。  |
364| callback | 回调函数，详见[Demuxer_MediaKeySystemInfoCallback](#demuxer_mediakeysysteminfocallback)。  |
365
366**返回：**
367
368返回函数结果：
369
370AV_ERR_OK：执行成功。
371
372AV_ERR_OPERATE_NOT_PERMIT：demuxer没有正确的初始化。
373
374AV_ERR_INVALID_VAL：输入的demuxer指针为空或为非解封装器实例。
375
376
377### OH_AVDemuxer_SetMediaKeySystemInfoCallback()
378
379```
380OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback (OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfoCallback callback)
381```
382**描述**
383设置DRM信息回调函数。
384
385**系统能力：** SystemCapability.Multimedia.Media.Spliter
386
387**起始版本：** 11
388
389**废弃版本：** 14
390
391**替代接口：**[OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback](#oh_avdemuxer_setdemuxermediakeysysteminfocallback)
392
393**参数:**
394
395| 名称 | 描述 |
396| -------- | -------- |
397| demuxer | 指向OH_AVDemuxer实例的指针。  |
398| callback | 回调函数，详见[DRM_MediaKeySystemInfoCallback](#drm_mediakeysysteminfocallback)。  |
399
400**返回：**
401
402返回函数结果：
403
404AV_ERR_OK：执行成功。
405
406AV_ERR_OPERATE_NOT_PERMIT：demuxer没有正确的初始化。
407
408AV_ERR_INVALID_VAL：输入的demuxer指针为空或为非解封装器实例。
409
410
411### OH_AVDemuxer_UnselectTrackByID()
412
413```
414OH_AVErrCode OH_AVDemuxer_UnselectTrackByID (OH_AVDemuxer *demuxer, uint32_t trackIndex)
415```
416**描述**
417移除读取sample的轨道，未选中的轨道的数据不会被解封装器读取。注意，通过多次调用接口并传入不同轨道的索引来取消对多个轨道的选择。 同一轨道被多次取消选择时，接口会返回AV_ERR_OK，并且只会生效一次。
418
419**系统能力：** SystemCapability.Multimedia.Media.Spliter
420
421**起始版本：** 10
422
423**参数:**
424
425| 名称 | 描述 |
426| -------- | -------- |
427| demuxer | 指向OH_AVDemuxer实例的指针。  |
428| trackIndex | 需取消选择的轨道的索引。  |
429
430**返回：**
431
432返回函数结果：
433
434AV_ERR_OK：执行成功。
435
436AV_ERR_OPERATE_NOT_PERMIT：demuxer没有正确的初始化。
437
438AV_ERR_INVALID_VAL：输入的demuxer指针为空或非解封装器实例。