diff --git a/zh-cn/application-dev/media/Readme-CN.md b/zh-cn/application-dev/media/Readme-CN.md index f4c1c506f20fc22be84dc8822ab63b20a9f3d4b2..d2048aef8c448de17af254e2a027403355b2d6eb 100755 --- a/zh-cn/application-dev/media/Readme-CN.md +++ b/zh-cn/application-dev/media/Readme-CN.md @@ -5,4 +5,6 @@ - [音频播放开发指导](audio-playback.md) - [音频管理开发指导](audio-management.md) - [音频录制开发指导](audio-recorder.md) + - [音频解码开发指导](audio-decoder.md) + - [音频编码开发指导](audio-encoder.md) diff --git a/zh-cn/application-dev/media/audio-decoder.md b/zh-cn/application-dev/media/audio-decoder.md new file mode 100644 index 0000000000000000000000000000000000000000..af0a8a3ac9b2fcdb787d3eec0e8600aa6f33bd1f --- /dev/null +++ b/zh-cn/application-dev/media/audio-decoder.md @@ -0,0 +1,232 @@ +# 音频解码开发指导 + +## 场景介绍 + +音频解码的主要工作是将编码后的数据解码为原始数据，同时对音频解码任务进行管理。 + +**图1** 音频解码状态机 + +![zh-ch_image_image_audio_decoder_machine](figures/zh-ch_image_image_audio_decoder_machine.png) + +## 音频解码零层图 + +**图2** 音频解码零层图 + +![zh-ch_image_image_audio_decoder](figures/zh-ch_image_image_audio_decoder.png) + +## 音频解码开发步骤 + +详细API含义可参考：[js-apis-media.md](../reference/apis/js-apis-media.md) + +### 全流程场景 + +包含流程：创建音频解码实例、设置监听事件、配置解码音频的媒体信息、准备音频解码、开始音频解码、获取音频媒体信息、清空缓存、停止解码、重置音频解码、销毁音频解码器资源 + +```js +/* 用于打印音频媒体信息 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioDecoder key is ' + item); + console.info('audioDecoder value is ' + property); + } +} + +/* 设置订阅事件回调函数 */ +function SetCallback() { + audioDecoder.on('needInputData', (inBuffer) => { // 订阅音频解码的输入音频帧内存事件 + console.info('audioDecoder needInputData success'); + /* 将要解码的音频帧数据写入inBuffer后，再将其推入队列中 */ + audioDecoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder pushInputData success'); + } else { + console.info(`audioDecoder pushInputData fail, errMessage:${error.message}`); + } + }); + }); + audioDecoder.on('newOutputData', (outBuffer) => { // 订阅音频解码的输出解码后内存事件 + console.info('audioDecoder newOutputData success'); + /* 获取outBuffer中的时间戳和index信息后，将其从队列中释放 */ + audioDecoder.freeOutputBuffer(outBuffer, true, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder freeOutputBuffer success'); + } else { + console.info(`audioDecoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); + }); + audioDecoder.on('error', (error) => { // 订阅音频解码错误事件，若出现报错，则需销毁资源，重新开始 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 + }); + audioDecoder.on('streamChanged', (format) => { // 订阅音频解码媒体信息变化事件 + if (typeof(format) != 'undefined') { + printfDescription(format); + } + }); +} + +/* 函数调用发生错误时用于上报错误信息 */ +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} + +/* 函数调用发生异常时用于上报错误信息 */ +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +let audioDecoder = undefined; +let mediaDescription = { + "channel_count": 2, + "sample_rate": 44100, + "audio_sample_format": 1, +} + +/* 1.创建音频解码实例 */ +await media.createAudioDecoderByMime('audio/mp4a-latm').then((decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByMime success'); + } else { + console.info('audioDecoder createAudioDecoderByMime fail'); + } +}, failureCallback).catch(catchCallback); + +/* 2.设置监听事件 */ +SetCallback(); + +/* 3.配置解码音频的媒体信息 */ +await audioDecoder.configure(mediaDescription).then(() => { + console.log('audioDecoder configure success'); +}, failureCallback).catch(catchCallback); + +/* 4.准备音频解码 */ +await audioDecoder.prepare().then(() => { + console.log('audioDecoder prepare success'); +}, failureCallback).catch(catchCallback); + +/* 5.开始音频解码 */ +await audioDecoder.start().then(() => { + console.log('audioDecoder start success'); +}, failureCallback).catch(catchCallback); + +/* 触发'needInputData'和'newOutputData'订阅事件 */ + +/* 6.获取音频媒体信息 */ +await audioDecoder.getOutputMediaDescription().then((mediaDescription) => { + console.log('audioDecoder getOutputMediaDescription success'); + printfDescription(mediaDescription); +}, failureCallback).catch(catchCallback); + +/* 7.获取音频解码能力 */ +await audioDecoder.getaudioDecoderCaps().then((audioCaps) => { + console.log('audioDecoder getaudioDecoderCaps success'); +}, failureCallback).catch(catchCallback); + +/* 8.清空缓存 */ +await audioDecoder.flush().then(() => { + console.log('audioDecoder flush success'); +}, failureCallback).catch(catchCallback); + +/* 9.停止解码 */ +await audioDecoder.stop().then(() => { + console.log('audioDecoder stop success'); +}, failureCallback).catch(catchCallback); + +/* 10.重置音频解码 */ +await audioDecoder.reset().then(() => { + console.log('audioDecoder reset success'); +}, failureCallback).catch(catchCallback); + +/* 11.销毁音频解码器资源 */ +await audioDecoder.release().then(() => { + console.log('audioDecoder release success'); +}, failureCallback).catch(catchCallback); +audioDecoder = undefined; // 将音频解码器置空 +``` + +### 正常解码场景 + +```js +/* 设置订阅事件回调函数 */ +function SetCallback() { + audioDecoder.on('needInputData', (inBuffer) => { // 订阅音频解码的输入音频帧内存事件 + console.info('audioDecoder needInputData success'); + /* 将要解码的音频帧数据写入inBuffer后，再将其推入队列中 */ + audioDecoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder pushInputData success'); + } else { + console.info(`audioDecoder pushInputData fail, errMessage:${error.message}`); + } + }); + }); + audioDecoder.on('newOutputData', (outBuffer) => { // 订阅音频解码的输出解码后内存事件 + console.info('audioDecoder newOutputData success'); + if (outBuffer.flags == media.FrameFlags.EOS_FRAME) { // 读到EOS帧 + await audioDecoder.release().then(() => { // 销毁音频解码器资源 + console.log('audioDecoder release success'); + }, failureCallback).catch(catchCallback); + audioDecoder = undefined; // 将音频解码器置空 + return; + } + /* 获取outBuffer中的时间戳和index信息后，将其从队列中释放 */ + audioDecoder.freeOutputBuffer(outBuffer, true, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder freeOutputBuffer success'); + } else { + console.info(`audioDecoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); + }); + audioDecoder.on('error', (error) => { // 订阅音频解码错误事件，若出现报错，则需销毁资源，重新开始 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 + }); +} + +let audioDecoder = undefined; +let mediaDescription = { + "channel_count": 2, + "sample_rate": 44100, + "audio_sample_format": 1, +} + +/* 1.创建音频解码实例 */ +await media.createAudioDecoderByMime('audio/mp4a-latm').then((decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByMime success'); + } else { + console.info('audioDecoder createAudioDecoderByMime fail'); + } +}, failureCallback).catch(catchCallback); + +/* 2.设置监听事件 */ +SetCallback(); + +/* 3.配置解码音频的媒体信息 */ +await audioDecoder.configure(mediaDescription).then(() => { + console.log('audioDecoder configure success'); +}, failureCallback).catch(catchCallback); + +/* 4.准备音频解码 */ +await audioDecoder.prepare().then(() => { + console.log('audioDecoder prepare success'); +}, failureCallback).catch(catchCallback); + +/* 5.开始音频解码 */ +await audioDecoder.start().then(() => { + console.log('audioDecoder start success'); +}, failureCallback).catch(catchCallback); + +/* + * 触发'needInputData'和'newOutputData'订阅事件 + * 应用将需要解码的音频帧传入'needInputData'事件 + * 再将'newOutputData'事件解码后的音频帧数据播放 + */ +``` \ No newline at end of file diff --git a/zh-cn/application-dev/media/audio-encoder.md b/zh-cn/application-dev/media/audio-encoder.md new file mode 100644 index 0000000000000000000000000000000000000000..18c75b5ba60d25212ab4c7065af5fa63403b053b --- /dev/null +++ b/zh-cn/application-dev/media/audio-encoder.md @@ -0,0 +1,232 @@ +# 音频编码开发指导 + +## 场景介绍 + +音频编码的主要工作是将音频原始数据编码为压缩数据，同时对音频编码任务进行管理。 + +**图1** 音频编码状态机 + +![zh-ch_image_image_audio_Encoder_machine](figures/zh-ch_image_image_audio_encoder_machine.png) + +## 音频编码零层图 + +**图2** 音频编码零层图 + +![zh-ch_image_image_audio_Encoder](figures/zh-ch_image_image_audio_encoder.png) + +## 音频编码开发步骤 + +详细API含义可参考：[js-apis-media.md](../reference/apis/js-apis-media.md) + +### 全流程场景 + +包含流程：创建音频编码实例、设置监听事件、配置编码音频的媒体信息、准备音频编码、开始音频编码、获取音频媒体信息、清空缓存、停止编码、重置音频编码、销毁音频编码器资源 + +```js +/* 用于打印音频媒体信息 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioEncoder key is ' + item); + console.info('audioEncoder value is ' + property); + } +} + +/* 设置订阅事件回调函数 */ +function SetCallback() { + audioEncoder.on('needInputData', (inBuffer) => { // 订阅音频编码的输入音频帧内存事件 + console.info('audioEncoder needInputData success'); + /* 将要编码的音频帧数据写入inBuffer后，再将其推入队列中 */ + audioEncoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder pushInputData success'); + } else { + console.info(`audioEncoder pushInputData fail, errMessage:${error.message}`); + } + }); + }); + audioEncoder.on('newOutputData', (outBuffer) => { // 订阅音频编码的输出编码后内存事件 + console.info('audioEncoder newOutputData success'); + /* 获取outBuffer中的时间戳和index信息后，将其从队列中释放 */ + audioEncoder.freeOutputBuffer(outBuffer, true, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder freeOutputBuffer success'); + } else { + console.info(`audioEncoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); + }); + audioEncoder.on('error', (error) => { // 订阅音频编码错误事件，若出现报错，则需销毁资源，重新开始 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 + }); + audioEncoder.on('streamChanged', (format) => { // 订阅音频编码媒体信息变化事件 + if (typeof(format) != 'undefined') { + printfDescription(format); + } + }); +} + +/* 函数调用发生错误时用于上报错误信息 */ +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} + +/* 函数调用发生异常时用于上报错误信息 */ +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +let audioEncoder = undefined; +let mediaDescription = { + "channel_count": 1, + "sample_rate": 48000, + "audio_sample_format": 3, +} + +/* 1.创建音频编码实例 */ +await media.createAudioEncoderByMime('audio/mp4a-latm').then((Encoder) => { + if (typeof(Encoder) != 'undefined') { + audioEncoder = Encoder; + console.info('audioEncoder createAudioEncoderByMime success'); + } else { + console.info('audioEncoder createAudioEncoderByMime fail'); + } +}, failureCallback).catch(catchCallback); + +/* 2.设置监听事件 */ +SetCallback(); + +/* 3.配置编码音频的媒体信息 */ +await audioEncoder.configure(mediaDescription).then(() => { + console.log('audioEncoder configure success'); +}, failureCallback).catch(catchCallback); + +/* 4.准备音频编码 */ +await audioEncoder.prepare().then(() => { + console.log('audioEncoder prepare success'); +}, failureCallback).catch(catchCallback); + +/* 5.开始音频编码 */ +await audioEncoder.start().then(() => { + console.log('audioEncoder start success'); +}, failureCallback).catch(catchCallback); + +/* 触发'needInputData'和'newOutputData'订阅事件 */ + +/* 6.获取音频媒体信息 */ +await audioEncoder.getOutputMediaDescription().then((mediaDescription) => { + console.log('audioEncoder getOutputMediaDescription success'); + printfDescription(mediaDescription); +}, failureCallback).catch(catchCallback); + +/* 7.获取音频编码能力 */ +await audioEncoder.getaudioEncoderCaps().then((audioCaps) => { + console.log('audioEncoder getaudioEncoderCaps success'); +}, failureCallback).catch(catchCallback); + +/* 8.清空缓存 */ +await audioEncoder.flush().then(() => { + console.log('audioEncoder flush success'); +}, failureCallback).catch(catchCallback); + +/* 9.停止编码 */ +await audioEncoder.stop().then(() => { + console.log('audioEncoder stop success'); +}, failureCallback).catch(catchCallback); + +/* 10.重置音频编码 */ +await audioEncoder.reset().then(() => { + console.log('audioEncoder reset success'); +}, failureCallback).catch(catchCallback); + +/* 11.销毁音频编码器资源 */ +await audioEncoder.release().then(() => { + console.log('audioEncoder release success'); +}, failureCallback).catch(catchCallback); +audioEncoder = undefined; // 将音频编码器置空 +``` + +### 正常编码场景 + +```js +/* 设置订阅事件回调函数 */ +function SetCallback() { + audioEncoder.on('needInputData', (inBuffer) => { // 订阅音频编码的输入音频帧内存事件 + console.info('audioEncoder needInputData success'); + /* 将要编码的音频帧数据写入inBuffer后，再将其推入队列中 */ + audioEncoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder pushInputData success'); + } else { + console.info(`audioEncoder pushInputData fail, errMessage:${error.message}`); + } + }); + }); + audioEncoder.on('newOutputData', (outBuffer) => { // 订阅音频编码的输出编码后内存事件 + console.info('audioEncoder newOutputData success'); + if (outBuffer.flags == media.FrameFlags.EOS_FRAME) { // 读到EOS帧 + await audioEncoder.release().then(() => { // 销毁音频编码器资源 + console.log('audioEncoder release success'); + }, failureCallback).catch(catchCallback); + audioEncoder = undefined; // 将音频编码器置空 + return; + } + /* 获取outBuffer中的时间戳和index信息后，将其从队列中释放 */ + audioEncoder.freeOutputBuffer(outBuffer, true, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder freeOutputBuffer success'); + } else { + console.info(`audioEncoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); + }); + audioEncoder.on('error', (error) => { // 订阅音频编码错误事件，若出现报错，则需销毁资源，重新开始 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 + }); +} + +let audioEncoder = undefined; +let mediaDescription = { + "channel_count": 1, + "sample_rate": 48000, + "audio_sample_format": 3, +} + +/* 1.创建音频编码实例 */ +await media.createAudioEncoderByMime('audio/mp4a-latm').then((Encoder) => { + if (typeof(Encoder) != 'undefined') { + audioEncoder = Encoder; + console.info('audioEncoder createAudioEncoderByMime success'); + } else { + console.info('audioEncoder createAudioEncoderByMime fail'); + } +}, failureCallback).catch(catchCallback); + +/* 2.设置监听事件 */ +SetCallback(); + +/* 3.配置编码音频的媒体信息 */ +await audioEncoder.configure(mediaDescription).then(() => { + console.log('audioEncoder configure success'); +}, failureCallback).catch(catchCallback); + +/* 4.准备音频编码 */ +await audioEncoder.prepare().then(() => { + console.log('audioEncoder prepare success'); +}, failureCallback).catch(catchCallback); + +/* 5.开始音频编码 */ +await audioEncoder.start().then(() => { + console.log('audioEncoder start success'); +}, failureCallback).catch(catchCallback); + +/* + * 触发'needInputData'和'newOutputData'订阅事件 + * 应用将需要编码的音频帧传入'needInputData'事件 + * 再将'newOutputData'事件编码后的音频帧数据储存 + */ +``` \ No newline at end of file diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder.png b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder.png new file mode 100644 index 0000000000000000000000000000000000000000..c4c59dd681ad11d842d541fb403b2f87fe8a7b3f Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder_machine.png b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder_machine.png new file mode 100644 index 0000000000000000000000000000000000000000..e619498b79125aa7bb3cefcb427e55d1ff31937d Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_decoder_machine.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder.png b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder.png new file mode 100644 index 0000000000000000000000000000000000000000..d7deb0796b4c7d108da9704c087ae52a8e177853 Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder.png differ diff --git a/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder_machine.png b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder_machine.png new file mode 100644 index 0000000000000000000000000000000000000000..e619498b79125aa7bb3cefcb427e55d1ff31937d Binary files /dev/null and b/zh-cn/application-dev/media/figures/zh-ch_image_image_audio_encoder_machine.png differ diff --git a/zh-cn/application-dev/reference/apis/js-apis-media.md b/zh-cn/application-dev/reference/apis/js-apis-media.md index 21af291759b0e9c973a051ce31c2b5e660311e67..4f28d7cbc335fde7ef452b4c1c77693bf416a0f5 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-media.md +++ b/zh-cn/application-dev/reference/apis/js-apis-media.md @@ -6,6 +6,8 @@ - 音频播放（[AudioPlayer](#audioplayer)） - 音频录制（[AudioRecorder](#audiorecorder)） +- 音频解码（[AudioDecodeProcessor](#audiodecodeprocessor8)） +- 音频编码（[AudioEncodeProcessor](#audioencodeprocessor8)） 后续将提供以下功能：视频播放、视频录制、DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。 @@ -37,7 +39,7 @@ var audioPlayer = media.createAudioPlayer(); createAudioPlayerAsync(callback: AsyncCallback\<[AudioPlayer](#audioplayer)>): void -异步方式创建音频播放实例。通过注册回调函数获取返回值。 +异步创建音频播放实例。通过注册回调函数获取返回值。 **参数：** @@ -62,7 +64,7 @@ media.createAudioPlayerAsync((error, audio) => { createAudioPlayerAsync: Promise<[AudioPlayer](#audioplayer)> -异步方式创建音频播放实例。通过Promise获取返回值。 +异步创建音频播放实例。通过Promise获取返回值。 **返回值：** @@ -107,6 +109,286 @@ createAudioRecorder(): AudioRecorder var audiorecorder = media.createAudioRecorder(); ``` +## media.createAudioDecoderByName8+ + +createAudioDecoderByName(name: string, callback: AsyncCallback<[AudioDecodeProcessor](#audiodecodeprocessor8)>):void + +通过解码器名称异步创建音频解码实例。通过注册回调函数获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------ | +| name | string | 是 | 指定解码器名称。 | +| callback | AsyncCallback<[AudioDecodeProcessor](#audiodecodeprocessor8)>) | 是 | 异步创建音频解码实例回调方法。 | + +**示例：** + +``` +media.createAudioDecoderByName('avdec_mp3', (error, decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByName success'); + } else { + console.info(`audioDecoder createAudioDecoderByName fail, error:${error.message}`); + } +}); +``` + +## media.createAudioDecoderByName8+ + +createAudioDecoderByName(name: string): Promise<[AudioDecodeProcessor](#audiodecodeprocessor8)> + +通过解码器名称异步创建音频解码实例。通过Promise获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| name | string | 是 | 指定解码器名称。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | --------------------------------- | +| Promise<[AudioDecodeProcessor](#audiodecodeprocessor8)> | 异步创建音解码实例Promise返回值。 | + +**示例：** + +``` +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await media.createAudioDecoderByName('avdec_mp3').then((decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByName success'); + } else { + console.info('audioDecoder createAudioDecoderByName fail'); + } +}, failureCallback).catch(catchCallback); + +``` + +## media.createAudioDecoderByMime8+ + +createAudioDecoderByMime(codecMime: string, callback: AsyncCallback<[AudioDecodeProcessor](#audiodecodeprocessor8)>):void + +通过CodecMimeType类型异步创建音频解码实例。通过注册回调函数获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| codecMime | string | 是 | codecMime类型，具体可参考[CodecMimeType](#codecmimetype8)。 | +| callback | AsyncCallback<[AudioDecodeProcessor](#audiodecodeprocessor8)> | 是 | 异步创建音频解码实例回调方法。 | + +**返回值:** + +| 类型 | 说明 | +| --------------------------------------------- | ------------------------------------------------ | +| [AudioDecodeProcessor](#audiodecodeprocessor8) | 返回AudioDecodeProcessor类实例，失败时返回null。 | + +**示例：** + +``` +media.createAudioDecoderByMime('audio/mpeg', (error, decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByMime success'); + } else { + console.info(`audioDecoder createAudioDecoderByMime fail, error:${error.message}`); + } +}); +``` + +## media.createAudioDecoderByMime8+ + +createAudioDecoderByMime(codecMime: string): Promise<[AudioDecodeProcessor](#audiodecodeprocessor8)> + +通过CodecMimeType类型异步创建音频解码实例。通过Promise获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | ----------------------------------------------------------- | +| codecMime | string | 是 | codecMime类型，具体可参考[CodecMimeType](#codecmimetype8)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | ----------------------------------- | +| Promise<[AudioDecodeProcessor](#audiodecodeprocessor8)> | 异步创建音频解码实例Promise返回值。 | + +**示例：** + +``` +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await media.createAudioDecoderByMime('audio/mpeg').then((decoder) => { + if (typeof(decoder) != 'undefined') { + audioDecoder = decoder; + console.info('audioDecoder createAudioDecoderByMime success'); + } else { + console.info('audioDecoder createAudioDecoderByMime fail'); + } +}, failureCallback).catch(catchCallback); +``` + +## media.createAudioEncoderByName8+ + +createAudioEncoderByName(name: string, callback: AsyncCallback<[AudioEncodeProcessor](#audioencodeprocessor8)>):void + +通过编码器名称异步创建音频编码实例。通过注册回调函数获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------------------ | ---- | ------------------------------ | +| name | string | 是 | 指定编码器名称。 | +| callback | AsyncCallback<[AudioEncodeProcessor](#audioencodeprocessor8)> | 是 | 异步创建音频编码实例回调方法。 | + +**示例：** + +``` +media.createAudioEncoderByName('avenc_aac', (error, encoder) => { + if (typeof(encoder) != 'undefined') { + audioEncoder = encoder; + console.info('audioEncoder createAudioEncoderByName success'); + } else { + console.info(`audioEncoder createAudioEncoderByName fail, error:${error.message}`); + } +}); +``` + +## media.createAudioEncoderByName8+ + +createAudioEncoderByName(name: string): Promise<[AudioEncodeProcessor](#audioencodeprocessor8)> + +通过编码器名称异步创建音频编码实例。通过Promise获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ------ | ---- | ---------------- | +| name | string | 是 | 指定编码器名称。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | ----------------------------------- | +| Promise<[AudioEncodeProcessor](#audioencodeprocessor8)> | 异步创建音频编码实例Promise返回值。 | + +**示例：** + +``` +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await media.createAudioEncoderByName('avenc_aac').then((encoder) => { + if (typeof(encoder) != 'undefined') { + audioEncoder = encoder; + console.info('audioEncoder createAudioEncoderByName success'); + } else { + console.info('audioEncoder createAudioEncoderByName fail'); + } +}, failureCallback).catch(catchCallback); +``` + + + +## media.createAudioEncoderByMime8+ + +createAudioEncoderByMime(codecMime: string, callback: AsyncCallback<[AudioEncodeProcessor](#audioencodeprocessor8)>):void +通过CodecMimeType类型异步创建音频编码实例。通过注册回调函数获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------------- | +| codecMime | string | 是 | codecMime类型，具体可参考[CodecMimeType](#codecmimetype8)。 | +| callback | AsyncCallback<[AudioEncodeProcessor](#audioencodeprocessor8)> | 是 | 异步创建音频编码实例回调方法。 | + +**示例：** + +``` +media.createAudioEncoderByMime('audio/mp4a-latm', (error, encoder) => { + if (typeof(encoder) != 'undefined') { + audioEncoder = encoder; + console.info('audioEncoder createAudioEncoderByMime success'); + } else { + console.info(`audioEncoder createAudioEncoderByMime fail, error:${error.message}`); + } +}); +``` + +## media.createAudioEncoderByMime8+ + +createAudioEncoderByMime(codecMime: string): Promise<[AudioEncodeProcessor](#audioencodeprocessor8)> + +通过CodecMimeType类型异步创建音频编码实例。 通过Promise获取返回值。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| --------- | ------ | ---- | ----------------------------------------------------------- | +| codecMime | string | 是 | codecMime类型，具体可参考[CodecMimeType](#codecmimetype8)。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------------------------------------------ | ----------------------------------- | +| Promise<[AudioEncodeProcessor](#audioencodeprocessor8)> | 异步创建音频解码实例Promise返回值。 | + +**示例：** + +``` +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await media.createAudioDecoderByMime('audio/mp4a-latm').then((encoder) => { + if (typeof(encoder) != 'undefined') { + audioEncoder = encoder; + console.info('audioEncoder createAudioEncoderByMime success'); + } else { + console.info('audioEncoder createAudioEncoderByMime fail'); + } +}, failureCallback).catch(catchCallback); +``` + ## MediaErrorCode8+ 媒体服务错误类型枚举 @@ -709,4 +991,1799 @@ on(type: 'error', callback: ErrorCallback): void | 名称 | 默认值 | 说明 | | -------- | ------ | ------------------------------------------------------------ | | MPEG_4 | 2 | 封装为MPEG-4格式。 | -| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | \ No newline at end of file +| AAC_ADTS | 6 | 封装为ADTS（Audio Data Transport Stream）格式，是AAC音频的传输流格式。 | + +## AudioDecodeProcessor8+ + +音频解码管理类，用于解码音频媒体。在调用AudioDecodeProcessor的方法前，需要先通过[createAudioDecoderByName()](#media.createaudiodecoderbyname8)或[createAudioDecoderByMime()](#media.createaudiodecoderbymime8)构建一个[AudioDecodeProcessor](#audiodecodeprocessor8)实例。 + +音频解码demo可参考：[音频解码开发指导](../../media/audio-decoder.md) + +### configure + +configure(desc: [MediaDescription](#mediadescription8), callback: AsyncCallback): void + +配置解码音频的媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 设置媒体配置信息。媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。
必须设置的音频解码媒体信息：MD_KEY_AUD_CHANNEL_COUNT、MD_KEY_AUD_SAMPLE_RATE、MD_KEY_AUDIO_SAMPLE_FORMAT。 | +| callback | AsyncCallback | 是 | 配置媒体信息事件回调函数。 | + +**示例：** + +```js +let mediaDescription = { + "channel_count" : 2, + "sample_rate" : 44100, + "audio_sample_format": 1, +} +audioDecoder.configure(mediaDescription, (error) => { // 配置媒体信息 + if (typeof(error) != 'undefined') { + console.log('audioDecoder configure success'); + } else { + console.info(`audioDecoder configure fail, errMessage:${error.message}`); + } +}); +``` + + +### configure + +configure(desc: [MediaDescription](#mediadescription8)): Promise + +配置解码音频的媒体信息。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 设置媒体配置信息。媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。
必须设置的音频解码媒体信息：MD_KEY_AUD_CHANNEL_COUNT、MD_KEY_AUD_SAMPLE_RATE、MD_KEY_AUDIO_SAMPLE_FORMAT。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 配置媒体信息Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +let mediaDescription = { + "channel_count" : 2, + "sample_rate" : 44100, + "audio_sample_format": 1, +} +await audioDecoder.configure(mediaDescription).then(() => { // 配置媒体信息 + console.log('audioDecoder configure success'); +}, failureCallback).catch(catchCallback); +``` + +### prepare + +prepare(callback: AsyncCallback): void + +准备音频解码，通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 准备音频解码事件回调函数。 | + +**示例：** + +```js +audioDecoder.prepare((error) => { // 准备音频解码 + if (typeof(error) != 'undefined') { + console.log('audioDecoder prepare success'); + } else { + console.info(`audioDecoder prepare fail, errMessage:${error.message}`); + } +}); +``` + +### prepare + +prepare(): Promise + +准备音频解码，通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 准备音频解码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.prepare().then(() => { // 准备音频解码 + console.log('audioDecoder prepare success'); +}, failureCallback).catch(catchCallback); +``` + +### start + +start(callback: AsyncCallback): void + +开始音频解码器，通过注册回调函数获取执行结果。在start()方法调用前需完成[needInputData](#onneedinputdata)和[newOutputData](#onnewoutputdata)两个事件注册。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 开始音频解码事件回调函数。 | + +**示例：** + +```js +audioDecoder.start((error) => { // 开始音频解码 + if (typeof(error) != 'undefined') { + console.log('audioDecoder start success'); + } else { + console.info(`audioDecoder start fail, errMessage:${error.message}`); + } +}); +``` + +### start + +start(): Promise + +开始音频解码，通过Promise获取执行结果。在start()方法调用前需完成[needInputData](#onneedinputdata)和[newOutputData](#onnewoutputdata)两个事件注册。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 开始音频解码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.start().then(() => { // 开始音频解码 + console.log('audioDecoder start success'); +}, failureCallback).catch(catchCallback); + +``` + +### stop + +stop(callback: AsyncCallback): void + +停止音频解码，通过注册回调函数获取执行结果。stop()后可直接调用[start()](#audiodecodeprocessor_start1)继续进行解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 停止音频解码事件回调函数。 | + +**示例：** + +```js +audioDecoder.stop((error) => { // 停止音频解码 + if (typeof(error) != 'undefined') { + console.log('audioDecoder stop success'); + } else { + console.info(`audioDecoder stop fail, errMessage:${error.message}`); + } +}); +``` + +### stop + +stop(): Promise + +停止音频解码。通过Promise获取执行结果。stop()后可直接调用[start()](#audiodecodeprocessor_start2)继续进行解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 停止音频解码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.stop().then(() => { // 停止音频解码 + console.log('audioDecoder stop success'); +}, failureCallback).catch(catchCallback); +``` + +### flush + +flush(callback: AsyncCallback): void + +清空缓存中未完成解码的内存。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | ---------------------- | +| callback | AsyncCallback | 是 | 清空缓存事件回调函数。 | + +**示例：** + +```js +audioDecoder.flush((error) => { // 刷新缓存 + if (typeof(error) != 'undefined') { + console.log('audioDecoder flush success'); + } else { + console.info(`audioDecoder flush fail, errMessage:${error.message}`); + } +}); +``` + +### flush + +flush(): Promise + +清空缓存中未完成解码的内存。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | ----------------------- | +| Promise | 清空缓存Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.flush().then(() => { // 清空缓存 + console.log('audioDecoder flush success'); +}, failureCallback).catch(catchCallback); +``` + +### reset + +reset(callback: AsyncCallback): void + +重置音频解码。通过注册回调函数获取执行结果。重置后需要重新[configure()](#audiodecodeprocessor_configure1)和[prepare()](#audiodecodeprocessor_prepare1)才可进行音频解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | ------------------------ | +| callback | AsyncCallback | 是 | 重置音解码事件回调函数。 | + +**示例：** + +```js +audioDecoder.reset((error) => { // 重置音频解码 + if (typeof(error) != 'undefined') { + console.log('audioDecoder reset success'); + } else { + console.info(`audioDecoder reset fail, errMessage:${error.message}`); + } +}); +``` + +### reset + +reset(): Promise + +重置音频解码。通过Promise获取执行结果。重置后需要重新[configure()](#audiodecodeprocessor_configure2)和[prepare()](#audiodecodeprocessor_prepare2)才可进行音频解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 重置音频解码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.reset().then(() => { // 重置音频解码 + console.log('audioDecoder reset success'); +}, failureCallback).catch(catchCallback); +``` + +### release + +release(callback: AsyncCallback): void + +销毁音频解码器资源。通过注册回调函数获取执行结果。应用需手动release，不能依赖内存回收机制。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------------- | +| callback | AsyncCallback | 是 | 销毁音频解码器资源事件回调函数。 | + +**示例：** + +```js +audioDecoder.release((error) => { // 销毁音频解码器资源 + if (typeof(error) != 'undefined') { + console.log('audioDecoder release success'); + audioDecoder = undefined; // 将音频解码器置空 + } else { + console.info(`audioDecoder release fail, errMessage:${error.message}`); + } +}); +``` + +### release + +release(): Promise + +销毁音解码器资源。通过Promise获取执行结果。应用需手动release，不能依赖内存回收机制。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------- | +| Promise | 销毁音频解码器资源Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.release().then(() => { // 销毁音频解码器资源 + console.log('audioDecoder release success'); +}, failureCallback).catch(catchCallback); +audioDecoder = undefined; // 将音频解码器置空 +``` + + +### pushInputData + +pushInputData(buffer: [CodecBuffer](#codecbuffer8), callback: AsyncCallback): void + +将解码音频帧内存数据输入队列。通过注册回调函数获取执行结果。需在[start()](#audiodecodeprocessor_start1)之后才可调用此接口。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | -------------------------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 音频解码原始帧数据。 | +| callback | AsyncCallback | 是 | 输入解码音频帧数据进队列事件回调函数。 | + +**示例：** + +```js +audioDecoder.on('needInputData', (inputBuffer) => { // 订阅needInputData事件 + /* 将需要解码的数据传入inputBuffer中，此处需仅做示例，解码时，需按实际情况将每帧的数据进行赋值 */ + inputBuffer.index = 0; + inputBuffer.timeMs = 0; + inputBuffer.offset = 0; + inputBuffer.length = 100; + inputBuffer.flags = 1; + inputBuffer.data; // 使用零拷贝策略，将数据直接写入data中 + /* 将需要解码的数据推入队列中 */ + audioDecoder.pushInputData(inputBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder pushInputData success'); + } else { + console.info(`audioDecoder pushInputData fail, errMessage:${error.message}`); + } + }); +}); +``` + +### pushInputData + +pushInputData(buffer: [CodecBuffer](#codecbuffer8)): Promise + +将解码音频帧内存数据输入队列。 通过Promise获取执行结果 。需在[start()](#audiodecodeprocessor_start2)之后才可调用此接口。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------------- | ---- | -------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 音频解码原始帧数据。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------------- | +| Promise | 将解码音频帧数据输入队列Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +audioDecoder.on('needInputData', (inputBuffer) => { // 订阅needInputData事件 + /* 将需要解码的数据传入inputBuffer中，此处仅做示例，解码时，需按实际情况将每帧的数据进行赋值 */ + inputBuffer.index = 0; + inputBuffer.timeMs = 0; + inputBuffer.offset = 0; + inputBuffer.length = 100; + inputBuffer.flags = 1; + inputBuffer.data; // 使用零拷贝策略，将数据直接写入data中 + /* 将需要解码的数据推入队列中 */ + await audioDecoder.pushInputData(inputBuffer).then(() => { + console.log('audioDecoder pushInputData success'); + }, failureCallback).catch(catchCallback); +}); +``` + +### freeOutputBuffer + +freeOutputBuffer(buffer: [CodecBuffer](#codecbuffer8), callback: AsyncCallback): void + +释放解码输出的音频帧内存。 通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | -------------------------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 解码完成的音频帧数据。 | +| callback | AsyncCallback | 是 | 释放解码输出的音频帧内存事件回调函数。 | + +**示例：** + +```js +audioDecoder.on('newOutputData', (outputBuffer) => { // 订阅newOutputData事件 + /* 将newOutputData数据读取后，再将其释放 */ + audioDecoder.freeOutputBuffer(outputBuffer, (error) => { // 释放解码输出的音频帧内存 + if (typeof(error) != 'undefined') { + console.log('audioDecoder freeOutputBuffer success'); + } else { + console.info(`audioDecoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); +}); +``` + +### freeOutputBuffer + +freeOutputBuffer(buffer: [CodecBuffer](#codecbuffer8)): Promise + +释放解码输出的音频帧内存。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------------- | ---- | ---------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 解码完成的音频帧数据。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------------- | +| Promise | 释放解码输出的音频帧内存Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +audioDecoder.on('newOutputData', (outputBuffer) => { // 订阅newOutputData事件 + /* 将outputBuffer数据读取后，再将其释放 */ + await audioDecoder.freeOutputBuffer(outputBuffer, false).then(() => { // 释放解码输出的音频帧内存 + console.log('audioDecoder freeOutputBuffer success'); + }, failureCallback).catch(catchCallback); +}); +``` + +### setParameter + +setParameter(desc: [MediaDescription](#mediadescription8), callback: AsyncCallback): void; + +动态设置解码音频的媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。 | +| callback | AsyncCallback | 是 | 动态设置解码音频的媒体信息事件回调函数。 | + +**示例：** + +```js +let mediaDescription = { // 此处mediaDescription仅做为示例 + "channel_count" : 2, + "sample_rate" : 44100, + "audio_sample_format": 1, +} + +audioDecoder.setParameter(mediaDescription, (error) => { // 动态设置解码音频的媒体信息 + if (typeof(error) != 'undefined') { + console.log('audioDecoder setParameter success'); + } else { + console.info(`audioDecoder setParameter fail, errMessage:${error.message}`); + } +}); +``` + +### setParameter + +setParameter(desc: [MediaDescription](#mediadescription8)): Promise + +设置音频解码器的配置参数，通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------------------------------------- | ---- | ------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 设置媒体配置信息。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------------------- | +| Promise | 音频解码器参数设置完成时，返回的Promise实例。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +let mediaDescription = { // 此处mediaDescription仅做为示例 + "channel_count" : 2, + "sample_rate" : 44100, + "audio_sample_format": 1, +} + +await audioDecoder.setParameter(mediaDescription).then(() => { // 动态设置解码音频的媒体信息 + console.log('audioDecoder setParameter success'); +}, failureCallback).catch(catchCallback); +``` + +### getOutputMediaDescription + +getOutputMediaDescription(callback: AsyncCallback<[MediaDescription](#mediadescription8)>): void + +获取解码音频的当前媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | ---------------------------------------- | +| callback | AsyncCallback<[MediaDescription](#mediadescription8)> | 是 | 获取解码音频的当前媒体信息事件回调函数。 | + +**示例：** + +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioDecoder key is ' + item); + console.info('audioDecoder value is ' + property); + } +} + +audioDecoder.getOutputMediaDescription((error, mediaDescription) => { + if (typeof(mediaDescription) != 'undefined') { + console.log('audioDecoder getOutputMediaDescription success'); + printfDescription(mediaDescription); + } else { + console.log('audioDecoder getOutputMediaDescription fail'); + } +}); +``` + +### getOutputMediaDescription + +getOutputMediaDescription(): Promise<[MediaDescription](#mediadescription8)> + +获取解码音频的当前媒体信息。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------------------- | ------------------------------------------- | +| Promise<[MediaDescription](#mediadescription8)> | 获取解码音频的当前媒体信息的Promise返回值。 | + +**示例：** + +```js +/* 将format中的所有内容显示 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioDecoder key is ' + item); + console.info('audioDecoder value is ' + property); + } +} +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.getOutputMediaDescription().then((mediaDescription) => { + console.log('audioDecoder getOutputMediaDescription success'); + printfDescription(mediaDescription); +}, failureCallback).catch(catchCallback); +``` + +### on('error') + +on(type: 'error', callback: ErrorCallback<[CodecError](#codecerror8)>): void + +订阅音频解码错误事件。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频解码错误事件回调类型，支持的事件包括：'error'。
- 'error'：音频解码中发生错误，触发该事件。 | +| callback | ErrorCallback<[CodecError](#codecerror8)> | 是 | 音频解码错误事件回调方法。 | + +**示例：** + +```js +audioDecoder.on('error', (error) => { // 设置'error'事件回调 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 +}); +/* 系统内存不足或状态切换异常时，触发error事件回调 */ +``` + + +### on('streamChanged') + +on(type: 'streamChanged', callback: Callback<[MediaDescription](#mediadescription8)>): void + +监听音频解码器输出格式更改或第一帧解码格式事件。 新的输出信息将通过回调方式返回。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | 是 | 解码音频第一帧或媒体信息发生变化事件回调类型，支持的事件包括：'streamChanged'。
- 'streamChanged'：解码音频第一帧解码完成或媒体信息发生变化时，触发该事件。 | +| callback | Callback<[MediaDescription](#mediadescription8)> | 是 | 解码音频第一帧或媒体信息发生变化事件回调方法。 | + +**示例：** + +```js +/* 将format中的所有内容显示 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioDecoder key is ' + item); + console.info('audioDecoder value is ' + property); + } +} + +audioEncoder.on('streamChanged', (format) => { // 设置解码音频第一帧或媒体信息发生变化事件回调 + if (typeof(format) != 'undefined') { + printfDescription(format); + } +}); +/* 解码音频的媒体信息发生变化时，触发事件 */ +``` + +### on('needInputData') + +on(type: 'needInputData', callback: Callback<[CodecBuffer](#codecbuffer8)>): void + +订阅音频解码输入音频帧内存事件。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频解码输入音频帧内存事件回调类型，支持的事件包括：'needInputData'。
- 'needInputData'：[start()](#audiodecodeprocessor_start1)调用之后，触发该事件。 | +| callback | Callback<[CodecBuffer](#codecbuffer8)> | 是 | 音频解码输入音频帧内存事件回调方法。 - 用户需将要解码的音频帧内容填入[CodecBuffer](#codecbuffer8)，再调用[pushInputData()](#audiodecodeprocessor_pushinputdata1)方法将[CodecBuffer](#codecbuffer8)推入队列中。 | + +**示例：** + +```js +audioDecoder.on('needInputData', (inBuffer) => { + console.info('audioDecoder needInputData'); + /* 将音频帧内容填入inBuffer后，调用pushInputData方法将其推入队列 */ + audioDecoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder pushInputData success'); + } else { + console.info(`audioDecoder pushInputData fail, errMessage:${error.message}`); + } + }); +}); +``` + +### on('newOutputData') + +on(type: 'newOutputData', callback: Callback<[CodecBuffer](#codecbuffer8)>): void + +订阅音频解码输出音频帧解码后内存事件。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频解码输出音频帧解码后内存事件回调类型，支持的事件包括：'newOutputData'。
\- 'newOutputData'：[pushInputData()](#audiodecodeprocessor_pushinputdata1)调用之后，触发该事件。 | +| callback | Callback<[CodecBuffer](#codecbuffer8)> | 是 | 音频解码输出音频帧解码后内存事件。
\- 媒体服务将音频帧解码后的内容通过[CodecBuffer](#codecbuffer8)返回给用户，用户读取内存后，需调用[freeOutputBuffer()](#audiodecodeprocessor_freeoutputbuffer1)方法将该内存从队列中移除。 | + +**示例：** + +```js +audioDecoder.on('newOutputData', (outBuffer) => { + console.info('audioDecoder newOutputData'); + /* 获取outBuffer中音频帧解码后的时间戳和index后，调用freeOutputBuffer方法将该帧送显，并将该内存从队列中移除 */ + audioEncoder.freeOutputBuffer(outBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioDecoder freeOutputBuffer success'); + } else { + console.info(`audioDecoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); +}); +``` + +### getAudioDecoderCaps + +getAudioDecoderCaps(callback: AsyncCallback<[AudioCaps](#audiocaps8)>): void + +获取音频解码能力。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback<[AudioCaps](#audiocaps8)> | 是 | 获取音频解码能力事件回调函数。 | + +**示例：** + +```js +audioDecoder.getAudioDecoderCaps((error, audioCaps) => { + if (typeof(audioCaps) != 'undefined') { + console.log('audioDecoder getAudioDecoderCaps success'); + printfDescription(mediaDescription); + } else { + console.log('audioDecoder getAudioDecoderCaps fail'); + } +}); +``` + +### getAudioDecoderCaps + +getAudioDecoderCaps(): Promise<[AudioCaps](#audiocaps8)> +获取音频解码能力。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioDecoder + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | --------------------------------- | +| Promise<[AudioCaps](#audiocaps8)> | 获取音频解码能力的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioDecoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioDecoder catchCallback, error:${error.message}`); +} + +await audioDecoder.getAudioDecoderCaps().then((videoCaps) => { + console.log('audioDecoder getAudioDecoderCaps success'); +}, failureCallback).catch(catchCallback); +``` + +## AudioEncodeProcessor8+ + +音频编码管理类，用于编码音频媒体。在调用AudioEncodeProcessor的方法前，需要先通过[createAudioEncoderByName()](#media.createaudioencoderbyname)或[createAudioEncoderByMime()](#media.createaudioencoderbymime)构建一个[AudioEncodeProcessor](#audioencodeprocessor8)实例。 + +音频编码demo可参考：[音频编码开发指导](../../media/audio-encoder.md) + +### configure + +configure(desc: [MediaDescription](#mediadescription8), callback: AsyncCallback): void + +配置编码音频的媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 设置媒体配置信息。媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。
必须设置的音频编码媒体信息：MD_KEY_AUD_CHANNEL_COUNT、MD_KEY_AUD_SAMPLE_RATE、MD_KEY_AUDIO_SAMPLE_FORMAT。 | +| callback | AsyncCallback | 是 | 配置媒体信息事件回调函数。 | + +**示例：** + +```js +let mediaDescription = { + "channel_count" : 1, + "sample_rate" : 48000, + "audio_sample_format": 3, +} +audioEncoder.configure(mediaDescription, (error) => { // 配置媒体信息 + if (typeof(error) != 'undefined') { + console.log('audioEncoder configure success'); + } else { + console.info(`audioEncoder configure fail, errMessage:${error.message}`); + } +}); +``` + + +### configure + +configure(desc: [MediaDescription](#mediadescription8)): Promise + +通过Promise方式使用 [MediaDescription](#mediadescription8)配置音频编码器。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 设置媒体配置信息。媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。
必须设置的音频编码媒体信息：MD_KEY_AUD_CHANNEL_COUNT、MD_KEY_AUD_SAMPLE_RATE、MD_KEY_AUDIO_SAMPLE_FORMAT。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 配置媒体信息Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +let mediaDescription = { + "channel_count" : 1, + "sample_rate" : 48000, + "audio_sample_format": 3, +} +await audioEncoder.configure(mediaDescription).then(() => { // 配置媒体信息 + console.log('audioEncoder configure success'); +}, failureCallback).catch(catchCallback); +``` + +### prepare + +prepare(callback: AsyncCallback): void + +准备音频编码，通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 准备音频编码事件回调函数。 | + +**示例：** + +```js +audioEncoder.prepare((error) => { // 准备音频编码 + if (typeof(error) != 'undefined') { + console.log('audioEncoder prepare success'); + } else { + console.info(`audioEncoder prepare fail, errMessage:${error.message}`); + } +}); +``` + +### prepare + +prepare(): Promise + +准备音频编码，通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 准备音频编码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.prepare().then(() => { // 准备音频编码 + console.log('audioEncoder prepare success'); +}, failureCallback).catch(catchCallback); +``` + +### start + +start(callback: AsyncCallback): void + +开始音频编码，通过注册回调函数获取执行结果。在start()方法调用前需完成[needInputData](#onneedinputdata-1)和[newOutputData](#onnewoutputdata-1)两个事件注册。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 开始音频编码事件回调函数。 | + +**示例：** + +```js +audioEncoder.stop((error) => { // 停止音频编码 + if (typeof(error) != 'undefined') { + console.log('audioEncoder stop success'); + } else { + console.info(`audioEncoder stop fail, errMessage:${error.message}`); + } +}); +``` + +### start + +start(): Promise + +启动音频编码，通过Promise获取执行结果。在start()方法调用前需完成[needInputData](#onneedinputdata-1)和[newOutputData](#onnewoutputdata-1)两个事件注册。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 开始音频编码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.start().then(() => { // 开始音频编码 + console.log('audioEncoder start success'); +}, failureCallback).catch(catchCallback); +``` + +### stop + +stop(callback: AsyncCallback): void + +停止音频解码，通过注册回调函数获取执行结果。stop()后可直接调用[start()](#audioencodeprocessor_start1)继续进行解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 停止音频编码事件回调函数。 | + +**示例：** + +```js +audioDecoder.stop((error) => { // 停止音频解码 + if (typeof(error) != 'undefined') { + console.log('audioDecoder stop success'); + } else { + console.info(`audioDecoder stop fail, errMessage:${error.message}`); + } +}); +``` + +### stop + +stop(): Promise + +停止音频编码。通过Promise获取执行结果。stop()后可直接调用[start()](#audioencodeprocessor_start2)继续进行解码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 停止音频编码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.stop().then(() => { // 停止音频编码 + console.log('audioEncoder stop success'); +}, failureCallback).catch(catchCallback); +``` + +### flush + +flush(callback: AsyncCallback): void + +清空缓存中未完成编码的内存。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | ---------------------- | +| callback | AsyncCallback | 是 | 清空缓存事件回调函数。 | + +**示例：** + +```js +audioEncoder.flush((error) => { // 刷新缓存 + if (typeof(error) != 'undefined') { + console.log('audioEncoder flush success'); + } else { + console.info(`audioEncoder flush fail, errMessage:${error.message}`); + } +}); +``` + +### flush + +flush(): Promise + +清空缓存中未完成编码的内存。 通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | ----------------------- | +| Promise | 清空缓存Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.flush().then(() => { // 清空缓存 + console.log('audioEncoder flush success'); +}, failureCallback).catch(catchCallback); +``` + +### reset + +reset(callback: AsyncCallback): void + +重置音频编码。通过注册回调函数获取执行结果。重置后需要重新[configure()](#audioencodeprocessor_configure1)和[prepare()](#audioencodeprocessor_prepare1)才可进行音频编码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------- | +| callback | AsyncCallback | 是 | 重置音频编码事件回调函数。 | + +**示例：** + +```js +audioEncoder.reset((error) => { // 重置音频编码 + if (typeof(error) != 'undefined') { + console.log('audioEncoder reset success'); + } else { + console.info(`audioEncoder reset fail, errMessage:${error.message}`); + } +}); +``` + +### reset + +reset(): Promise + +重置音频编码。 通过Promise获取执行结果 。重置后需要重新[configure()](#audioencodeprocessor_configure2)和[prepare()](#audioencodeprocessor_prepare2)才可进行音频编码。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------- | +| Promise | 重置音频编码Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.reset().then(() => { // 重置音频编码 + console.log('audioEncoder reset success'); +}, failureCallback).catch(catchCallback); +``` + +### release + +release(callback: AsyncCallback): void + +销毁音频编码器资源。通过注册回调函数获取执行结果。应用需手动release，不能依赖内存回收机制。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------- | ---- | -------------------------------- | +| callback | AsyncCallback | 是 | 销毁音频编码器资源事件回调函数。 | + +**示例：** + +```js +audioEncoder.release((error) => { // 销毁音频编码器资源 + if (typeof(error) != 'undefined') { + console.log('audioEncoder release success'); + audioEncoder = undefined; // 将音频编码器置空 + } else { + console.info(`audioEncoder release fail, errMessage:${error.message}`); + } +}); +``` + +### release + +release(): Promise + +销毁音频编码器资源。通过Promise获取执行结果。应用需手动release，不能依赖内存回收机制。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------- | +| Promise | 销毁音频编码器资源Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.release().then(() => { // 销毁音频编码器资源 + console.log('audioEncoder release success'); +}, failureCallback).catch(catchCallback); +audioEncoder = undefined; // 将音频编码器置空 +``` + + +### pushInputData + +pushInputData(buffer: [CodecBuffer](#codecbuffer8) , callback: AsyncCallback): void + +将编码音频帧内存数据输入队列。通过注册回调函数获取执行结果。需在[start()](#audioencodeprocessor_start1)之后才可调用此接口。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | -------------------------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 音频编码原始帧数据。 | +| callback | AsyncCallback | 是 | 输入编码音频帧数据进队列事件回调函数。 | + +**示例：** + +```js +audioEncoder.on('newInputData', (inputBuffer) => { // 订阅newInputData事件 + /* 将需要解码的数据传入inputBuffer中，此处需仅做示例，编码时，需按实际情况将每帧的数据进行赋值 */ + inputBuffer.index = 0; + inputBuffer.timeMs = 0; + inputBuffer.offset = 0; + inputBuffer.length = 100; + inputBuffer.flags = 1; + inputBuffer.data; // 使用零拷贝策略，将数据直接写入data中 + /* 将需要解码的数据推入队列中 */ + audioEncoder.pushInputData(inputBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder pushInputData success'); + } else { + console.info(`audioEncoder pushInputData fail, errMessage:${error.message}`); + } + }); +}); +``` + +### pushInputData + +pushInputData(buffer: [CodecBuffer](#codecbuffer8)): Promise + +将编码音频帧内存数据输入队列。 通过Promise获取执行结果 。需在[start()](#audioencodeprocessor_start2)之后才可调用此接口。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------------- | ---- | -------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 音频编码原始帧数据。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------------- | +| Promise | 将编码音频帧数据输入队列Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +audioEncoder.on('newInputData', (inputBuffer) => { // 订阅needInputData事件 + /* 将需要解码的数据传入inputBuffer中，此处仅做示例，解码时，需按实际情况将每帧的数据进行赋值 */ + inputBuffer.index = 0; + inputBuffer.timeMs = 0; + inputBuffer.offset = 0; + inputBuffer.length = 100; + inputBuffer.flags = 1; + inputBuffer.data; // 使用零拷贝策略，将数据直接写入data中 + /* 将需要解码的数据推入队列中 */ + await audioEncoder.pushInputData(inputBuffer).then(() => { + console.log('audioEncoder pushInputData success'); + }, failureCallback).catch(catchCallback); +}); +``` + +### freeOutputBuffer + +freeOutputBuffer(buffer: [CodecBuffer](#codecbuffer8) , callback: AsyncCallback): void + +释放编码输出的音频帧内存。 通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------- | ---- | -------------------------------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 编码完成的音频帧数据。 | +| callback | AsyncCallback | 是 | 释放编码输出的音频帧内存事件回调函数。 | + +**示例：** + +```js +audioEncoder.on('newOutputData', (outputBuffer) => { // 订阅newOutputData事件 + /* 将newOutputData数据读取后，再将其释放 */ + audioEncoder.freeOutputBuffer(outputBuffer, (error) => { // 释放编码输出的音频帧内存 + if (typeof(error) != 'undefined') { + console.log('audioEncoder freeOutputBuffer success'); + } else { + console.info(`audioEncoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); +}); +``` + +### freeOutputBuffer + +freeOutputBuffer(buffer: [CodecBuffer](#codecbuffer8)): Promise + +释放音频编码器的输出buffer，通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------------- | ---- | ---------------- | +| buffer | [CodecBuffer](#codecbuffer8) | 是 | 音频输出buffer。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | --------------------------------------- | +| Promise | 释放解码输出的音频帧内存Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +audioEncoder.on('newOutputData', (outputBuffer) => { // 订阅newOutputData事件 + /* 将outputBuffer数据读取后，再将其释放 */ + await audioEncoder.freeOutputBuffer(outputBuffer, false).then(() => { // 释放编码输出的音频帧内存 + console.log('audioEncoder freeOutputBuffer success'); + }, failureCallback).catch(catchCallback); +}); +``` + +### setParameter + +setParameter(desc: [MediaDescription](#mediadescription8), callback: AsyncCallback): void; + +动态设置编码音频的媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。 | +| callback | AsyncCallback | 是 | 动态设置编码音频的媒体信息事件回调函数。 | + +**示例：** + +```js +let mediaDescription = { // 此处mediaDescription仅做为示例 + "channel_count" : 1, + "sample_rate" : 48000, + "audio_sample_format": 3, +} + +audioDecoder.setParameter(mediaDescription, (error) => { // 动态设置解码音频的媒体信息 + if (typeof(error) != 'undefined') { + console.log('audioDecoder setParameter success'); + } else { + console.info(`audioDecoder setParameter fail, errMessage:${error.message}`); + } +}); + +``` + +### setParameter + +setParameter(desc: [MediaDescription](#mediadescription8)): Promise + +动态设置编码音频的媒体信息。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | -------------------------------------- | ---- | ------------------------------------------------------------ | +| desc | [MediaDescription](#mediadescription8) | 是 | 媒体信息键值对，key值的范围可参考[MediaDescriptionKey](#mediadescriptionkey8)。 | + +**返回值：** + +| 类型 | 说明 | +| ------------- | ------------------------------------------- | +| Promise | 动态设置编码音频的媒体信息的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +let mediaDescription = { // 此处mediaDescription仅做为示例 + "channel_count" : 1, + "sample_rate" : 48000, + "audio_sample_format": 3, +} + +await audioEncoder.setParameter(mediaDescription).then(() => { // 动态设置编码音频的媒体信息 + console.log('audioEncoder setParameter success'); +}, failureCallback).catch(catchCallback); +``` + +### getOutputMediaDescription + +getOutputMediaDescription(callback: AsyncCallback<[MediaDescription](#mediadescription8)>): void + +获取编码音频的当前媒体信息。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------------------- | ---- | ---------------------------------------- | +| callback | AsyncCallback<[MediaDescription](#mediadescription8)> | 是 | 获取编码音频的当前媒体信息事件回调函数。 | + +**示例：** + +```js +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioEncoder key is ' + item); + console.info('audioEncoder value is ' + property); + } +} + +audioEncoder.getOutputMediaDescription((error, mediaDescription) => { + if (typeof(mediaDescription) != 'undefined') { + console.log('audioEncoder getOutputMediaDescription success'); + printfDescription(mediaDescription); + } else { + console.log('audioEncoder getOutputMediaDescription fail'); + } +}); +``` + +### getOutputMediaDescription + +getOutputMediaDescription(): Promise<[MediaDescription](#mediadescription8)> + +获取编码音频的当前媒体信息。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------------------- | ------------------------------------------- | +| Promise<[MediaDescription](#mediadescription8)> | 获取编码音频的当前媒体信息的Promise返回值。 | + +**示例：** + +```js +/* 将format中的所有内容显示 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioEncoder key is ' + item); + console.info('audioEncoder value is ' + property); + } +} +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.getOutputMediaDescription().then((mediaDescription) => { + console.log('audioEncoder getOutputMediaDescription success'); + printfDescription(mediaDescription); +}, failureCallback).catch(catchCallback); +``` + +### on('error') + +on(type: 'error', callback: ErrorCallback<[CodecError](#codecerror8)>): void + +订阅音频编码错误事件。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频编码错误事件回调类型，支持的事件包括：'error'。
- 'error'：音频编码中发生错误，触发该事件。 | +| callback | ErrorCallback<[CodecError](#codecerror8)> | 是 | 音频编码错误事件回调方法。 | + +**示例：** + +```js +audioEncoder.on('error', (error) => { // 设置'error'事件回调 + console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称 + console.info(`audio error called, errCode is ${error.code}`); // 打印错误码 + console.info(`audio error called, errMessage is ${error.message}`);// 打印错误类型详细描述 +}); +/* 系统内存不足或状态切换异常时，触发error事件回调 */ +``` + + +### on('streamChanged') + +on(type: 'streamChanged', callback: Callback<[MediaDescription](#mediadescription8)>): void + +订阅编码音频第一帧或媒体信息发生变化事件。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------------ | +| type | string | 是 | 编码音频第一帧或媒体信息发生变化事件回调类型，支持的事件包括：'streamChanged'。
- 'streamChanged'：音频编码中发生错误，触发该事件。 | +| callback | Callback<[MediaDescription](#mediadescription8)> | 是 | 编码音频第一帧或媒体信息发生变化事件回调方法。 | + +**示例：** + +```js +/* 将format中的所有内容显示 */ +function printfDescription(obj) { + for (let item in obj) { + let property = obj[item]; + console.info('audioEncoder key is ' + item); + console.info('audioEncoder value is ' + property); + } +} + +audioEncoder.on('streamChanged', (format) => { // 设置编码音频第一帧或媒体信息发生变化事件回调 + if (typeof(format) != 'undefined') { + printfDescription(format); + } +}); +/* 编码音频的媒体信息发生变化时，触发事件 */ +``` + +### on('needInputData') + +on(type: 'needInputData', callback: Callback<[CodecBuffer](#codecbuffer8)>): void + +监听音频编码器的输入buffer。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频编码输入音频帧内存事件回调类型，支持的事件包括：'needInputData'。
- 'needInputData'：[start()](#audioencodeprocessor_start1)调用之后，触发该事件。 | +| callback | Callback<[CodecBuffer](#codecbuffer8)> | 是 | 音频编码输入音频帧内存事件回调方法。 - 用户需将要编码的音频帧内容填入[CodecBuffer](#codecbuffer8)，再调用[pushInputData()](#audioencodeprocessor_pushinputdata1)方法将[CodecBuffer](#codecbuffer8)推入队列中。 | + +**示例：** + +```js +audioEncoder.on('needInputData', (inBuffer) => { + console.info('audioEncoder needInputData'); + /* 将音频帧内容填入inBuffer后，调用pushInputData方法将其推入队列 */ + audioEncoder.pushInputData(inBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder pushInputData success'); + } else { + console.info(`audioEncoder pushInputData fail, errMessage:${error.message}`); + } + }); +}); +``` + +### on('newOutputData') + +on(type: 'newOutputData', callback: Callback<[CodecBuffer](#codecbuffer8)>): void + +监听音频编码器的输出buffer。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | +| type | string | 是 | 音频编码输出音频帧编码后内存事件回调类型，支持的事件包括：'newOutputData'。
\- 'newOutputData'：[pushInputData()](#audioencodeprocessor_pushinputdata1)调用之后，触发该事件。 | +| callback | Callback<[CodecBuffer](#codecbuffer8)> | 是 | 音频编码输出音频帧编码后内存事件。
\- 媒体服务将音频帧编码后的内容通过[CodecBuffer](#codecbuffer8)返回给用户，用户读取内存后，需调用[freeOutputBuffer()](#audioencodeprocessor_freeoutputbuffer1)方法将该内存从队列中移除。 | + +**示例：** + +```js +audioEncoder.on('newOutputData', (outBuffer) => { + console.info('audioEncoder newOutputData'); + /* 获取outBuffer中音频帧编码后的时间戳和index后，调用freeOutputBuffer方法将该帧送显，并将该内存从队列中移除 */ + audioEncoder.freeOutputBuffer(outBuffer, (error) => { + if (typeof(error) != 'undefined') { + console.log('audioEncoder freeOutputBuffer success'); + } else { + console.info(`audioEncoder freeOutputBuffer fail, errMessage:${error.message}`); + } + }); +}); +``` + +### getAudioEncoderCaps + +getAudioEncoderCaps(callback: AsyncCallback<[AudioCaps](#audiocaps8)>): void + +获取音频编码能力。通过注册回调函数获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------- | ---- | ------------------------------ | +| callback | AsyncCallback<[AudioCaps](#audiocaps8)> | 是 | 获取音频编码能力事件回调函数。 | + +**示例：** + +```js +audioEncoder.getAudioEncoderCaps((error, audioCaps) => { + if (typeof(audioCaps) != 'undefined') { + console.log('audioEncoder getAudioEncoderCaps success'); + printfDescription(mediaDescription); + } else { + console.log('audioEncoder getAudioEncoderCaps fail'); + } +}); +``` + +### getAudioEncoderCaps + +getAudioEncoderCaps(): Promise<[AudioCaps](#audiocaps8)> +获取音频编码能力。通过Promise获取执行结果。 + +**系统能力：** SystemCapability.Multimedia.Media.AudioEncoder + +**返回值：** + +| 类型 | 说明 | +| --------------------------------- | --------------------------------- | +| Promise<[AudioCaps](#audiocaps8)> | 获取音频编码能力的Promise返回值。 | + +**示例：** + +```js +function failureCallback(error) { + console.info(`audioEncoder failureCallback, error:${error.message}`); +} +function catchCallback(error) { + console.info(`audioEncoder catchCallback, error:${error.message}`); +} + +await audioEncoder.getAudioEncoderCaps().then((videoCaps) => { + console.log('audioEncoder getAudioEncoderCaps success'); +}, failureCallback).catch(catchCallback); +``` + +## AudioCaps8+ + +音频编解码器能力类，用于表示音频编解码器能力范围。 + +**系统能力：** 以下各项对应的系统能力均为SystemCapability.Multimedia.Media.AudioCaps + +### 属性 + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| -------------------- | ------------------------------------------------------------ | ---- | ---- | ------------------------------------------------------------ | +| codecInfo | [AVCodecInfo](#avcodecinfo8) | 是 | 否 | 编解码器描述信息，包括编解码器名称、功能类型、MIME类型、是否支持硬件加速、是否只支持软件编解码、是否为厂商提供。 | +| supportedBitrate | [Range](#range8) | 是 | 否 | 音频编解码器支持的比特率范围。 | +| supportedChannel | [Range](#range8) | 是 | 否 | 音频编解码器支持的声道数范围。 | +| supportedFormats | Array<[AudioSampleFormat](./js-apis-audio.md#audiosampleformat8)> | 是 | 否 | 音频编解码器支持的RAW数据格式。 | +| supportedSampleRates | Array | 是 | 否 | 音频编解码器支持的采样率范围。 | +| supportedProfiles | Array | 是 | 否 | 音频编解码器支持的profile集合。 |