Zzhupengfeiupdate: 更新文件 arkts-apis-media-AVTranscoder.md

Interface (AVTranscoder)

视频转码管理类，用于视频转码。在调用AVTranscoder的方法前，需要先通过createAVTranscoder()构建一个AVTranscoder实例。

说明：

本模块首批接口从API version 6开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。

本Interface首批接口从API version 12开始支持。

导入模块

import { media } from '@kit.MediaKit';

属性

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

名称	类型	只读	可选	说明
fdSrc¹²⁺	AVFileDescriptor	否	否	源媒体文件描述，通过该属性设置数据源。使用示例：假设一个连续存储的媒体文件，地址偏移：0，字节长度：100。其文件描述为AVFileDescriptor{ fd = 资源句柄; offset = 0; length = 100; }。说明： - 将资源句柄（fd）传递给AVTranscoder实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个AVPlayer/AVMetadataExtractor/AVImageGenerator/AVTranscoder。 - 同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。
fdDst¹²⁺	number	否	否	目标媒体文件描述，通过该属性设置数据输出。在创建AVTranscoder实例后，必须设置fdSrc和fdDst属性。说明： - 将资源句柄（fd）传递给AVTranscoder实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个AVPlayer/AVMetadataExtractor/AVImageGenerator/AVTranscoder。 - 同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致视频转码数据获取异常。

addWatermark

addWatermark(watermark: image.PixelMap, configs: WatermarkConfiguration): Promise<number>

为视频转码添加水印。使用Promise异步回调。

说明：

应用最多可以添加5个水印。

此接口只能在prepared状态之前调用。

起始版本： 26.0.0

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
watermark	image.PixelMap	是	水印图像。
configs	WatermarkConfiguration	是	水印配置参数。

返回值：

类型	说明
Promise<number>	Promise对象，返回添加的水印ID。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.
5400108	The parameter check failed, parameter value out of range.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';
import { image } from '@kit.ImageKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  
  // 配置水印参数。
  let watermarkConfig: media.WatermarkConfiguration = {
      // 根据实际需求配置水印参数，单位为像素（px）。
      top : 40,
      left : 40,
      width: 200,
      height: 300,
  };

  avTranscoder.addWatermark(watermarkPixelMap, watermarkConfig).then((watermarkId: number) => {
    console.info('addWatermark success, watermarkId: ' + watermarkId);
  }).catch((err: BusinessError) => {
    console.error('addWatermark failed and catch error is ' + err.message);
  });
}

prepare¹²⁺

prepare(config: AVTranscoderConfig): Promise<void>

进行视频转码的参数设置。使用Promise异步回调。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
config	AVTranscoderConfig	是	配置视频转码的相关参数。

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档和Media错误码。

错误码ID	错误信息
401	The parameter check failed. Return by promise.
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.
5400106	Unsupported format. Returned by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  // 配置参数以实际硬件设备支持的范围为准。
  let avTranscoderConfig: media.AVTranscoderConfig = {
    audioBitrate : 200000,
    audioCodec : media.CodecMimeType.AUDIO_AAC,
    fileFormat : media.ContainerFormatType.CFT_MPEG_4,
    videoBitrate : 3000000,
    videoCodec : media.CodecMimeType.VIDEO_AVC,
  };

  avTranscoder.prepare(avTranscoderConfig).then(() => {
    console.info('prepare success');
  }).catch((err: BusinessError) => {
    console.error('prepare failed and catch error is ' + err.message);
  });
}

start¹²⁺

start(): Promise<void>

开始视频转码。使用Promise异步回调。

需要prepare()事件成功触发后，才能调用start方法。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.start().then(() => {
    console.info('start AVTranscoder success');
  }).catch((err: BusinessError) => {
    console.error('start AVTranscoder failed and catch error is ' + err.message);
  });
}

pause¹²⁺

pause(): Promise<void>

暂停视频转码。使用Promise异步回调。

需要start()事件成功触发后，才能调用pause方法，可以通过调用resume()接口来恢复转码。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.pause().then(() => {
    console.info('pause AVTranscoder success');
  }).catch((err: BusinessError) => {
    console.error('pause AVTranscoder failed and catch error is ' + err.message);
  });
}

resume¹²⁺

resume(): Promise<void>

恢复视频转码。使用Promise异步回调。

需要在pause()事件成功触发后，才能调用resume方法。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.resume().then(() => {
    console.info('resume AVTranscoder success');
  }).catch((err: BusinessError) => {
    console.error('resume AVTranscoder failed and catch error is ' + err.message);
  });
}

cancel¹²⁺

cancel(): Promise<void>

取消视频转码。使用Promise异步回调。

需要在prepare()、start()、pause()或resume()事件成功触发后，才能调用cancel方法。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400103	IO error. Return by promise.
5400105	Service died. Return by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.cancel().then(() => {
    console.info('cancel AVTranscoder success');
  }).catch((err: BusinessError) => {
    console.error('cancel AVTranscoder failed and catch error is ' + err.message);
  });
}

release¹²⁺

release(): Promise<void>

释放视频转码资源。使用Promise异步回调。

释放视频转码资源之后，该AVTranscoder实例不能再进行任何操作。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

返回值：

类型	说明
Promise<void>	Promise对象，无返回结果。

错误码：

以下错误码的详细介绍请参见Media错误码。

错误码ID	错误信息
5400102	Operation not allowed. Return by promise.
5400105	Service died. Return by promise.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.release().then(() => {
    console.info('release AVTranscoder success');
  }).catch((err: BusinessError) => {
    console.error('release AVTranscoder failed and catch error is ' + err.message);
  });
}

on('progressUpdate')¹²⁺

on(type:'progressUpdate', callback: Callback<number>):void

注册转码进度更新事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。使用callback异步回调。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	进度更新事件回调类型，支持的事件：'progressUpdate'，在转码过程中系统会自动触发此事件。
callback	Callback<number>	是	回调函数，返回进度更新事件，函数中的参数number，表示当前转码百分比进度。

示例：

import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.on('progressUpdate', (progress: number) => {
    console.info('avTranscoder progressUpdate = ' + progress);
  });
}

off('progressUpdate')¹²⁺

off(type:'progressUpdate', callback?: Callback<number>): void

取消注册转码进度更新事件。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	进度更新事件回调类型，支持的事件：'progressUpdate'。
callback	Callback<number>	否	已注册的进度更新事件回调。由于当前回调注册时，仅会保留最后一次注册的回调，建议此参数缺省。

示例：

import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.off('progressUpdate');
}

on('error')¹²⁺

on(type: 'error', callback: ErrorCallback): void

注册AVTranscoder的错误事件，该事件仅用于错误提示。如果AVTranscoder上报error事件，开发者需要通过release()退出转码操作。使用callback异步回调。

开发者只能订阅一个错误事件的回调方法，当开发者重复订阅时，以最后一次订阅的回调接口为准。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	转码错误事件回调类型'error'。 - 'error'：录制过程中发生错误，触发该事件。
callback	ErrorCallback	是	转码错误事件回调方法。

错误码：

以下错误码的详细介绍请参见通用错误码说明文档和Media错误码。

错误码ID	错误信息
401	The parameter check failed.
801	Capability not supported.
5400101	No memory.
5400102	Operation not allowed.
5400103	I/O error.
5400104	Time out.
5400105	Service died.
5400106	Unsupported format.

示例：

import { BusinessError } from '@kit.BasicServicesKit';
import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.on('error', (err: BusinessError) => {
    console.info('case avTranscoder.on(error) called, errMessage is ' + err.message);
  });
}

off('error')¹²⁺

off(type:'error', callback?: ErrorCallback): void

取消注册转码错误事件，取消后不再接收到AVTranscoder的错误事件。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	转码错误事件回调类型'error'。 - 'error'：转码过程中发生错误，触发该事件。
callback	ErrorCallback	否	错误事件回调方法。

示例：

import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.off('error');
}

on('complete')¹²⁺

on(type: 'complete', callback: Callback<void>): void

注册转码完成事件，并通过注册的回调方法通知开发者。开发者只能注册一个进度更新事件的回调方法，当开发者重复注册时，以最后一次注册的回调接口为准。使用callback异步回调。

当AVTranscoder上报complete事件时，当前转码操作已完成，开发者需要通过release()退出转码操作。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	完成事件回调类型，支持的事件：'complete'，在转码过程中系统会自动触发此事件。
callback	Callback<void>	是	回调函数，返回完成事件回调方法。

示例：

import { media } from '@kit.MediaKit';

async function test() {
  let avTranscoder: media.AVTranscoder | undefined = undefined;
  // 创建转码实例。
  avTranscoder = await media.createAVTranscoder();
  avTranscoder.on('complete', async () => {
    console.info('avTranscoder complete');
    if (avTranscoder != undefined) {
      // 开发者须在此监听转码完成事件。
      // 须等待avTranscoder.release()释放转码实例之后，再对转码后的文件进行转发、上传、转存等处理。
      await avTranscoder.release();
      avTranscoder = undefined;
    }
  });
}

off('complete')¹²⁺

off(type:'complete', callback?: Callback<void>): void

取消注册转码完成事件。

原子化服务API： 从API version 22开始，该接口支持在原子化服务中使用。

系统能力： SystemCapability.Multimedia.Media.AVTranscoder

参数：

参数名	类型	必填	说明
type	string	是	转码完成事件回调类型，支持的事件：'complete'。
callback	Callback<void>	否	完成事件回调方法。

示例：

import { media } from '@kit.MediaKit';

async function test() {
  // 创建转码实例。
  let avTranscoder = await media.createAVTranscoder();
  avTranscoder.off('complete');
}

Interface (AVTranscoder)

导入模块

属性

addWatermark

prepare12+

start12+

pause12+

resume12+

cancel12+

release12+

on('progressUpdate')12+

off('progressUpdate')12+

on('error')12+

off('error')12+

on('complete')12+

off('complete')12+

prepare¹²⁺

start¹²⁺

pause¹²⁺

resume¹²⁺

cancel¹²⁺

release¹²⁺

on('progressUpdate')¹²⁺

off('progressUpdate')¹²⁺

on('error')¹²⁺

off('error')¹²⁺

on('complete')¹²⁺

off('complete')¹²⁺