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