• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Interface (AVTranscoder)
2<!--Kit: Media Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @wang-haizhou6-->
5<!--Designer: @HmQQQ-->
6<!--Tester: @xchaosioda-->
7<!--Adviser: @zengyawen-->
8
9> **说明：**
10>
11> - 本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
12> - 本Interface首批接口从API version 12开始支持。
13
14视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过[createAVTranscoder()](arkts-apis-media-f.md#mediacreateavtranscoder12)构建一个AVTranscoder实例。
15
16视频转码demo可参考：[视频转码开发指导](../../media/media/using-avtranscoder-for-transcodering.md)
17
18## 导入模块
19
20```ts
21import { media } from '@kit.MediaKit';
22```
23
24## 属性
25
26**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
27
28| 名称    | 类型                                 | 只读 | 可选 | 说明               |
29| ------- | ------------------------------------ | ---- | ---- | ------------------ |
30| fdSrc<sup>12+</sup>                                  | [AVFileDescriptor](arkts-apis-media-i.md#avfiledescriptor9)                       |  否  | 否   | 源媒体文件描述，通过该属性设置数据源。<br/> **使用示例**：<br/>假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 |
31| fdDst<sup>12+</sup>                               | number                 |  否  | 否   | 目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。<br>**说明：** <br> - 将资源句柄（fd）传递给 AVTranscoder 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。 |
32
33## prepare<sup>12+</sup>
34
35prepare(config: AVTranscoderConfig): Promise\<void>
36
37异步方式进行视频转码的参数设置。通过Promise获取返回值。
38
39**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
40
41**参数：**
42
43| 参数名 | 类型                                   | 必填 | 说明                       |
44| ------ | -------------------------------------- | ---- | -------------------------- |
45| config | [AVTranscoderConfig](arkts-apis-media-i.md#avtranscoderconfig12) | 是   | 配置视频转码的相关参数。 <!--RP1--><!--RP1End-->|
46
47**返回值：**
48
49| 类型           | 说明                                       |
50| -------------- | ------------------------------------------ |
51| Promise\<void> | 异步视频转码prepare方法的Promise返回值。 |
52
53**错误码：**
54
55以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。
56
57| 错误码ID | 错误信息                               |
58| -------- | -------------------------------------- |
59| 401  | The parameter check failed. Return by promise. |
60| 5400102  | Operation not allowed. Return by promise. |
61| 5400103  | IO error. Return by promise.              |
62| 5400105  | Service died. Return by promise.       |
63| 5400106  | Unsupported format. Returned by promise.  |
64
65**示例：**
66
67```ts
68import { BusinessError } from '@kit.BasicServicesKit';
69import { media } from '@kit.MediaKit';
70
71async function test() {
72  // 创建转码实例。
73  let avTranscoder = await media.createAVTranscoder();
74  // 配置参数以实际硬件设备支持的范围为准。
75  let avTranscoderConfig: media.AVTranscoderConfig = {
76    audioBitrate : 200000,
77    audioCodec : media.CodecMimeType.AUDIO_AAC,
78    fileFormat : media.ContainerFormatType.CFT_MPEG_4,
79    videoBitrate : 3000000,
80    videoCodec : media.CodecMimeType.VIDEO_AVC,
81  };
82
83  avTranscoder.prepare(avTranscoderConfig).then(() => {
84    console.info('prepare success');
85  }).catch((err: BusinessError) => {
86    console.error('prepare failed and catch error is ' + err.message);
87  });
88}
89```
90
91## start<sup>12+</sup>
92
93start(): Promise\<void>
94
95异步方式开始视频转码。通过Promise获取返回值。
96
97需要[prepare()](#prepare12)事件成功触发后，才能调用start方法。
98
99**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
100
101**返回值：**
102
103| 类型           | 说明                                  |
104| -------------- | ------------------------------------- |
105| Promise\<void> | 异步开始视频转码方法的Promise返回值。 |
106
107**错误码：**
108
109以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
110
111| 错误码ID | 错误信息                               |
112| -------- | -------------------------------------- |
113| 5400102  | Operation not allowed. Return by promise. |
114| 5400103  | IO error. Return by promise.           |
115| 5400105  | Service died. Return by promise.       |
116
117**示例：**
118
119```ts
120import { BusinessError } from '@kit.BasicServicesKit';
121import { media } from '@kit.MediaKit';
122
123async function test() {
124  // 创建转码实例。
125  let avTranscoder = await media.createAVTranscoder();
126  avTranscoder.start().then(() => {
127    console.info('start AVTranscoder success');
128  }).catch((err: BusinessError) => {
129    console.error('start AVTranscoder failed and catch error is ' + err.message);
130  });
131}
132```
133
134## pause<sup>12+</sup>
135
136pause(): Promise\<void>
137
138异步方式暂停视频转码。通过Promise获取返回值。
139
140需要[start()](#start12)事件成功触发后，才能调用pause方法，可以通过调用[resume()](#resume12)接口来恢复转码。
141
142**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
143
144**返回值：**
145
146| 类型           | 说明                                  |
147| -------------- | ------------------------------------- |
148| Promise\<void> | 异步暂停视频转码方法的Promise返回值。 |
149
150**错误码：**
151
152以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
153
154| 错误码ID | 错误信息                               |
155| -------- | -------------------------------------- |
156| 5400102  | Operation not allowed. Return by promise. |
157| 5400103  | IO error. Return by promise.           |
158| 5400105  | Service died. Return by promise.       |
159
160**示例：**
161
162```ts
163import { BusinessError } from '@kit.BasicServicesKit';
164import { media } from '@kit.MediaKit';
165
166async function test() {
167  // 创建转码实例。
168  let avTranscoder = await media.createAVTranscoder();
169  avTranscoder.pause().then(() => {
170    console.info('pause AVTranscoder success');
171  }).catch((err: BusinessError) => {
172    console.error('pause AVTranscoder failed and catch error is ' + err.message);
173  });
174}
175```
176
177## resume<sup>12+</sup>
178
179resume(): Promise\<void>
180
181异步方式恢复视频转码。通过Promise获取返回值。
182
183需要在[pause()](#pause12)事件成功触发后，才能调用resume方法。
184
185**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
186
187**返回值：**
188
189| 类型           | 说明                                  |
190| -------------- | ------------------------------------- |
191| Promise\<void> | 异步恢复视频转码方法的Promise返回值。 |
192
193**错误码：**
194
195以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
196
197| 错误码ID | 错误信息                               |
198| -------- | -------------------------------------- |
199| 5400102  | Operation not allowed. Return by promise. |
200| 5400103  | IO error. Return by promise.           |
201| 5400105  | Service died. Return by promise.       |
202
203**示例：**
204
205```ts
206import { BusinessError } from '@kit.BasicServicesKit';
207import { media } from '@kit.MediaKit';
208
209async function test() {
210  // 创建转码实例。
211  let avTranscoder = await media.createAVTranscoder();
212  avTranscoder.resume().then(() => {
213    console.info('resume AVTranscoder success');
214  }).catch((err: BusinessError) => {
215    console.error('resume AVTranscoder failed and catch error is ' + err.message);
216  });
217}
218```
219
220## cancel<sup>12+</sup>
221
222cancel(): Promise\<void>
223
224异步方式取消视频转码。通过Promise获取返回值。
225
226需要在[prepare()](#prepare12)、[start()](#start12)、[pause()](#pause12)或[resume()](#resume12)事件成功触发后，才能调用cancel方法。
227
228**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
229
230**返回值：**
231
232| 类型           | 说明                                  |
233| -------------- | ------------------------------------- |
234| Promise\<void> | 异步取消视频转码方法的Promise返回值。 |
235
236**错误码：**
237
238以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
239
240| 错误码ID | 错误信息                               |
241| -------- | -------------------------------------- |
242| 5400102  | Operation not allowed. Return by promise. |
243| 5400103  | IO error. Return by promise.           |
244| 5400105  | Service died. Return by promise.       |
245
246**示例：**
247
248```ts
249import { BusinessError } from '@kit.BasicServicesKit';
250import { media } from '@kit.MediaKit';
251
252async function test() {
253  // 创建转码实例。
254  let avTranscoder = await media.createAVTranscoder();
255  avTranscoder.cancel().then(() => {
256    console.info('cancel AVTranscoder success');
257  }).catch((err: BusinessError) => {
258    console.error('cancel AVTranscoder failed and catch error is ' + err.message);
259  });
260}
261```
262
263## release<sup>12+</sup>
264
265release(): Promise\<void>
266
267异步方式释放视频转码资源。通过Promise获取返回值。
268
269释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。
270
271**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
272
273**返回值：**
274
275| 类型           | 说明                                        |
276| -------------- | ------------------------------------------- |
277| Promise\<void> | 异步释放视频转码资源方法的Promise返回值。 |
278
279**错误码：**
280
281以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md)。
282
283| 错误码ID | 错误信息                          |
284| -------- | --------------------------------- |
285| 5400102  | Operation not allowed. Return by promise. |
286| 5400105  | Service died. Return by promise. |
287
288**示例：**
289
290```ts
291import { BusinessError } from '@kit.BasicServicesKit';
292import { media } from '@kit.MediaKit';
293
294async function test() {
295  // 创建转码实例。
296  let avTranscoder = await media.createAVTranscoder();
297  avTranscoder.release().then(() => {
298    console.info('release AVTranscoder success');
299  }).catch((err: BusinessError) => {
300    console.error('release AVTranscoder failed and catch error is ' + err.message);
301  });
302}
303```
304
305## on('progressUpdate')<sup>12+</sup>
306
307on(type: 'progressUpdate', callback: Callback\<number>): void
308
309注册转码进度更新事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。
310
311**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
312
313**参数：**
314
315| 参数名   | 类型     | 必填 | 说明                                                         |
316| -------- | -------- | ---- | ------------------------------------------------------------ |
317| type     | string   | 是   | 进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。 |
318| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 是   | 进度更新事件回调方法，progress: number，表示当前转码进度。 |
319
320**示例：**
321
322```ts
323import { media } from '@kit.MediaKit';
324
325async function test() {
326  // 创建转码实例。
327  let avTranscoder = await media.createAVTranscoder();
328  avTranscoder.on('progressUpdate', (progress: number) => {
329    console.info('avTranscoder progressUpdate = ' + progress);
330  });
331}
332```
333
334## off('progressUpdate')<sup>12+</sup>
335
336off(type:'progressUpdate', callback?: Callback\<number>): void
337
338取消注册转码进度更新事件。
339
340**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
341
342**参数：**
343
344| 参数名 | 类型   | 必填 | 说明                                                         |
345| ------ | ------ | ---- | ------------------------------------------------------------ |
346| type   | string | 是   | 进度更新事件回调类型，支持的事件：'progressUpdate'。 |
347| callback | [Callback\<number>](../apis-basic-services-kit/js-apis-base.md#callback) | 否   | 已注册的进度更新事件回调。由于当前回调注册时，仅会保留最后一次注册的回调，建议此参数缺省。 |
348
349**示例：**
350
351```ts
352import { media } from '@kit.MediaKit';
353
354async function test() {
355  // 创建转码实例。
356  let avTranscoder = await media.createAVTranscoder();
357  avTranscoder.off('progressUpdate');
358}
359```
360
361## on('error')<sup>12+</sup>
362
363on(type: 'error', callback: ErrorCallback): void
364
365注册AVtranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，开发者需要通过[release()](#release12)退出转码操作。
366
367开发者只能订阅一个错误事件的回调方法，当开发者重复订阅时，以最后一次订阅的回调接口为准。
368
369**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
370
371**参数：**
372
373| 参数名   | 类型          | 必填 | 说明                                                         |
374| -------- | ------------- | ---- | ------------------------------------------------------------ |
375| type     | string        | 是   | 转码错误事件回调类型'error'。 <br>- 'error'：录制过程中发生错误，触发该事件。 |
376| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 是   | 转码错误事件回调方法。                                       |
377
378**错误码：**
379
380以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。
381
382| 错误码ID | 错误信息                                   |
383| -------- | ------------------------------------------ |
384| 401      | The parameter check failed. |
385| 801      | Capability not supported. |
386| 5400101  | No memory.            |
387| 5400102  | Operation not allowed. |
388| 5400103  | I/O error.              |
389| 5400104  | Time out.            |
390| 5400105  | Service died.           |
391| 5400106  | Unsupported format.      |
392
393**示例：**
394
395```ts
396import { BusinessError } from '@kit.BasicServicesKit';
397import { media } from '@kit.MediaKit';
398
399async function test() {
400  // 创建转码实例。
401  let avTranscoder = await media.createAVTranscoder();
402  avTranscoder.on('error', (err: BusinessError) => {
403    console.info('case avTranscoder.on(error) called, errMessage is ' + err.message);
404  });
405}
406```
407
408## off('error')<sup>12+</sup>
409
410off(type:'error', callback?: ErrorCallback): void
411
412取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。
413
414**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
415
416**参数：**
417
418| 参数名 | 类型   | 必填 | 说明                                                         |
419| ------ | ------ | ---- | ------------------------------------------------------------ |
420| type   | string | 是   | 转码错误事件回调类型'error'。 <br>- 'error'：转码过程中发生错误，触发该事件。 |
421| callback | [ErrorCallback](../apis-basic-services-kit/js-apis-base.md#errorcallback) | 否   | 错误事件回调方法。 |
422
423**示例：**
424
425```ts
426import { media } from '@kit.MediaKit';
427
428async function test() {
429  // 创建转码实例。
430  let avTranscoder = await media.createAVTranscoder();
431  avTranscoder.off('error');
432}
433```
434
435## on('complete')<sup>12+</sup>
436
437on(type: 'complete', callback: Callback\<void>): void
438
439注册转码完成事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。
440
441当AVTranscoder上报complete事件时，当前转码操作已完成，开发者需要通过[release()](#release12)退出转码操作。
442
443**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
444
445**参数：**
446
447| 参数名   | 类型     | 必填 | 说明                                                         |
448| -------- | -------- | ---- | ------------------------------------------------------------ |
449| type     | string   | 是   | 完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。 |
450| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 是   | 完成事件回调方法。 |
451
452**示例：**
453
454```ts
455import { media } from '@kit.MediaKit';
456
457async function test() {
458  let avTranscoder: media.AVTranscoder | undefined = undefined;
459  // 创建转码实例。
460  avTranscoder = await media.createAVTranscoder();
461  avTranscoder.on('complete', async () => {
462    console.info('avTranscoder complete');
463    if (avTranscoder != undefined) {
464      // 开发者须在此监听转码完成事件。
465      // 须等待avTranscoder.release()释放转码实例之后，再对转码后的文件进行转发、上传、转存等处理。
466      await avTranscoder.release();
467      avTranscoder = undefined;
468    }
469  });
470}
471```
472
473## off('complete')<sup>12+</sup>
474
475off(type:'complete', callback?: Callback\<void>): void
476
477取消注册转码完成事件。
478
479**系统能力：** SystemCapability.Multimedia.Media.AVTranscoder
480
481**参数：**
482
483| 参数名 | 类型   | 必填 | 说明                                                         |
484| ------ | ------ | ---- | ------------------------------------------------------------ |
485| type   | string | 是   | 转码完成事件回调类型，支持的事件：'complete'。 |
486| callback | [Callback\<void>](../apis-basic-services-kit/js-apis-base.md#callback) | 否   | 完成事件回调方法。 |
487
488**示例：**
489
490```ts
491import { media } from '@kit.MediaKit';
492
493async function test() {
494  // 创建转码实例。
495  let avTranscoder = await media.createAVTranscoder();
496  avTranscoder.off('complete');
497}
498```
499