使用AudioRenderer开发音频播放功能(ArkTs)
AudioRenderer是音频渲染器,用于播放PCM(Pulse Code Modulation)音频数据,相比AVPlayer而言,可以在输入前添加数据预处理,更适合有音频开发经验的开发者,以实现更灵活的播放功能。
开发指导
使用AudioRenderer播放音频涉及到AudioRenderer实例的创建、音频渲染参数的配置、渲染的开始与停止、资源的释放等。本开发指导将以一次渲染音频数据的过程为例,向开发者讲解如何使用AudioRenderer进行音频渲染,建议搭配AudioRenderer的API说明阅读。
下图展示了AudioRenderer的状态变化,在创建实例后,调用对应的方法可以进入指定的状态实现对应的行为。需要注意的是在确定的状态执行不合适的方法可能导致AudioRenderer发生错误,建议开发者在调用状态转换的方法前进行状态检查,避免程序运行产生预期以外的结果。
为保证UI线程不被阻塞,大部分AudioRenderer调用都是异步的。对于每个API均提供了callback函数和Promise函数,以下示例均采用callback函数。
图1 AudioRenderer状态变化示意图
[图示请参阅官方原文]
在进行应用开发的过程中,建议开发者通过on('stateChange')方法订阅AudioRenderer的状态变更。因为针对AudioRenderer的某些操作,仅在音频播放器在固定状态时才能执行。如果应用在音频播放器处于错误状态时执行操作,系统可能会抛出异常或生成其他未定义的行为。
- prepared状态:通过调用audio.createAudioRenderer方法进入到该状态。
- running状态:正在进行音频数据播放,可以在prepared状态通过调用start方法进入此状态,也可以在paused状态和stopped状态通过调用start方法进入此状态。
- paused状态:在running状态可以通过调用pause方法暂停音频数据的播放并进入paused状态,暂停播放之后可以通过调用start方法继续音频数据播放。
- stopped状态:在paused/running状态可以通过stop方法停止音频数据的播放。
- released状态:在prepared、paused、stopped等状态,用户均可通过release方法释放掉所有占用的硬件和软件资源,并且不会再进入到其他的任何一种状态了。
当音频流处于工作状态(非released状态)时,需要占用系统的音频流资源。由于系统对音频流数量有限制,所以当客户端暂时不使用音频流时,调用release()回收音频资源,做好资源利用,避免后续创建音频流失败。
开发步骤及注意事项
以下各步骤示例为片段代码,可通过示例代码右下方链接获取完整示例。
-
配置音频渲染参数并创建AudioRenderer实例,音频渲染参数的详细信息可以查看AudioRendererOptions。
// ... // 从API版本26.0.0开始,参数samplingRate支持number类型。 // 音频渲染扩展支持8000Hz到384000Hz范围内以10Hz为步长的采样率值。具体设备支持的采样率规格会存在差异。 let audioStreamInfo: audio.AudioStreamInfo = { samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, // 采样率。 channels: audio.AudioChannel.CHANNEL_2, // 通道。 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // 采样格式。 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // 编码格式。 }; let audioRendererInfo: audio.AudioRendererInfo = { usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。 rendererFlags: 0 // 音频渲染器标志。 }; let audioRendererOptions: audio.AudioRendererOptions = { streamInfo: audioStreamInfo, rendererInfo: audioRendererInfo }; // ... audio.createAudioRenderer(audioRendererOptions, (err, renderer) => { // 创建AudioRenderer实例。 if (!err) { console.info('Succeeded in creating audio renderer.'); // ... audioRenderer = renderer; if (audioRenderer !== undefined) { audioRenderer.on('writeData', writeDataCallback); // ... } } else { console.info(`Failed to create audio renderer. Code: ${err.code}, message: ${err.message}`); globalLogUpdate(`Failed to create audio renderer. Code: ${err.code}, message: ${err.message}`, false); } }); -
调用on('writeData')方法,订阅监听音频数据写入回调,推荐使用API version 12支持返回回调结果的方式。
-
API version 12开始该方法支持返回回调结果,系统可以根据开发者返回的值来决定此次回调中的数据是否播放。
注意:
- 能填满回调所需长度数据的情况下,返回audio.AudioDataCallbackResult.VALID,系统会取用完整长度的数据缓冲进行播放。请不要在未填满数据的情况下返回audio.AudioDataCallbackResult.VALID,否则会导致杂音、卡顿等现象。
- 在无法填满回调所需长度数据的情况下,建议开发者返回audio.AudioDataCallbackResult.INVALID,系统不会处理该段音频数据,然后会再次向应用请求数据,确认数据填满后返回audio.AudioDataCallbackResult.VALID。
- 回调函数结束后,音频服务会把缓冲中数据放入队列里等待播放,因此请勿在回调外再次更改缓冲中的数据。对于最后一帧,如果数据不够填满缓冲长度,开发者需要使用剩余数据拼接空数据的方式,将缓冲填满,避免缓冲内的历史脏数据对播放效果产生不良的影响。
// ... class Options { public offset?: number; public length?: number; } // ... let bufferSize: number = 0; let file = await context.resourceManager.getRawFd('S16LE_2_48000.pcm'); writeDataCallback = (buffer: ArrayBuffer) => { let options: Options = { offset: bufferSize + file.offset, length: buffer.byteLength }; if (bufferSize > file.length) { return audio.AudioDataCallbackResult.INVALID; } try { let bufferLength = fs.readSync(file.fd, buffer, options); bufferSize += buffer.byteLength; // 系统会判定buffer有效,正常播放。 // ... return audio.AudioDataCallbackResult.VALID; } catch (error) { console.error(`Failed to read file. Code: ${error.code}, message: ${error.message}`); // 系统会判定buffer无效,不播放。 // ... return audio.AudioDataCallbackResult.INVALID; } }; // ... audioRenderer.on('writeData', writeDataCallback); -
API version 11该方法不支持返回回调结果,系统默认回调中的数据均为有效数据。
注意:
- 开发者应避免在主线程中注册回调,以免被其他业务阻塞导致响应回调不及时造成卡顿。建议使用独立的异步线程池处理回调。
- 请确保填满回调所需长度数据,否则会导致杂音、卡顿等现象。
- 在无法填满回调所需长度数据的情况下,建议开发者选择暂时停止写入数据(不暂停音频流),阻塞回调函数,等待数据充足时,再继续写入数据,确保数据填满。在阻塞回调函数后,如需调用AudioRenderer相关接口,需先解阻塞。
- 开发者如果不希望播放本次回调中的音频数据,可以主动将回调中的数据块置空(置空后,也会被系统统计到已写入的数据,播放静音帧)。
- 回调函数结束后,音频服务会把缓冲中数据放入队列里等待播放,因此请勿在回调外再次更改缓冲中的数据。对于最后一帧,如果数据不够填满缓冲长度,开发者需要使用剩余数据拼接空数据的方式,将缓冲填满,避免缓冲内的历史脏数据对播放效果产生不良的影响。
- 在写数据回调中,避免与耗时业务耦合或等待其他业务操作,例如写数据时不要等待UI绘制。否则,可能会导致数据传输不及时,从而产生卡顿现象。
// ... class Options { public offset?: number; public length?: number; } // ... let bufferSize: number = 0; let file = await context.resourceManager.getRawFd('S16LE_2_48000.pcm'); writeDataCallback = (buffer: ArrayBuffer) => { let options: Options = { offset: bufferSize + file.offset, length: buffer.byteLength }; // ... audioRenderer.on('writeData', writeDataCallback);
-
-
调用start方法进入running状态,开始渲染音频。
// ... audioRenderer.start((err: BusinessError) => { if (err) { console.error(`Failed to start audio renderer. Code: ${err.code}, message: ${err.message}`); // ... } else { console.info('Succeeded in starting audio renderer.'); // ... } }); -
调用stop方法停止渲染。
// ... audioRenderer.stop((err: BusinessError) => { if (err) { console.error(`Failed to stop audio renderer. Code: ${err.code}, message: ${err.message}`); // ... } else { console.info('Succeeded in stopping audio renderer.'); // ... } }); -
调用release方法销毁实例,释放资源。
应用需根据实际业务需求合理使用AudioRenderer实例,按需创建并及时释放,避免占用过多音频资源导致异常。
// ... audioRenderer.release((err: BusinessError) => { if (err) { console.error(`Failed to release audio renderer. Code: ${err.code}, message: ${err.message}`); // ... } else { // 关闭沙箱文件。 console.info('Succeeded in releasing audio renderer.'); // ... } });
选择正确的StreamUsage
创建播放器时候,开发者需要根据应用场景指定播放器的StreamUsage,选择正确的StreamUsage可以避免用户遇到不符合预期的行为。
在音频API文档StreamUsage介绍中,列举了每一种类型推荐的应用场景。例如音乐场景推荐使用STREAM_USAGE_MUSIC,电影或者视频场景推荐使用STREAM_USAGE_MOVIE,游戏场景推荐使用STREAM_USAGE_GAME,等等。
如果开发者配置了不正确的StreamUsage,可能带来一些不符合预期的行为。例如以下场景。
- 游戏场景错误使用
STREAM_USAGE_MUSIC类型,游戏应用将无法和其他音乐应用并发播放,而游戏场景通常可以与其他音乐应用并发播放。 - 导航场景错误使用
STREAM_USAGE_MUSIC类型,导航应用播报时候会导致正在播放的音乐停止播放,而导航场景我们通常期望正在播放的音乐仅降低音量播放。
配置合适的音频采样率
采样率:指音频每秒单个声道样点数,单位为Hz。
重采样:根据输入输出音频采样率的差异,进行上采样(通过插值增加样点数)或下采样(通过抽取减少样点数)。
AudioRenderer支持枚举类型AudioSamplingRate中定义的所有采样率。
若通过AudioRenderer设置的输入音频采样率与设备输出采样率不一致,系统会将输入音频重采样为设备输出采样率。
若为减少重采样功耗,可使用采样率与输出设备采样率一致的输入音频。推荐使用48k采样率。
完整示例
下面展示了使用AudioRenderer渲染音频文件的示例代码。
// ...
class Options {
public offset?: number;
public length?: number;
}
// ...
let audioRenderer: audio.AudioRenderer | undefined = undefined;
// 从API版本26.0.0开始,参数samplingRate支持number类型。
// 音频渲染扩展支持8000Hz到384000Hz范围内以10Hz为步长的采样率值。具体设备支持的采样率规格会存在差异。
let audioStreamInfo: audio.AudioStreamInfo = {
samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, // 采样率。
channels: audio.AudioChannel.CHANNEL_2, // 通道。
sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // 采样格式。
encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // 编码格式。
};
let audioRendererInfo: audio.AudioRendererInfo = {
usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。
rendererFlags: 0 // 音频渲染器标志。
};
let audioRendererOptions: audio.AudioRendererOptions = {
streamInfo: audioStreamInfo,
rendererInfo: audioRendererInfo
};
let writeDataCallback: audio.AudioRendererWriteDataCallback;
async function initArguments(context: common.UIAbilityContext) {
let bufferSize: number = 0;
let file = await context.resourceManager.getRawFd('S16LE_2_48000.pcm');
writeDataCallback = (buffer: ArrayBuffer) => {
let options: Options = {
offset: bufferSize + file.offset,
length: buffer.byteLength
};
if (bufferSize > file.length) {
return audio.AudioDataCallbackResult.INVALID;
}
try {
let bufferLength = fs.readSync(file.fd, buffer, options);
bufferSize += buffer.byteLength;
// 系统会判定buffer有效,正常播放。
if (bufferSize > file.length) {
let view = new DataView(buffer);
for (let i = bufferSize - file.length; i < buffer.byteLength; i++) {
// 空白区域填充静音数据。当使用音频采样格式为SAMPLE_FORMAT_U8时0x7F为静音数据,使用其他采样格式时0为静音数据。
view.setUint8(i, 0);
}
}
// API version 11不支持返回回调结果,从API version 12开始支持返回回调结果。
// 如果开发者不希望播放某段buffer,返回audio.AudioDataCallbackResult.INVALID即可。
return audio.AudioDataCallbackResult.VALID;
} catch (error) {
console.error(`Failed to read file. Code: ${error.code}, message: ${error.message}`);
// ...
// API version 11不支持返回回调结果,从API version 12开始支持返回回调结果。
return audio.AudioDataCallbackResult.INVALID;
}
};
}
// 初始化,创建实例,设置监听事件。
async function init() {
audio.createAudioRenderer(audioRendererOptions, (err, renderer) => { // 创建AudioRenderer实例。
if (!err) {
console.info('Succeeded in creating audio renderer.');
// ...
audioRenderer = renderer;
if (audioRenderer !== undefined) {
audioRenderer.on('writeData', writeDataCallback);
// ...
}
} else {
console.info(`Failed to create audio renderer. Code: ${err.code}, message: ${err.message}`);
// ...
}
});
}
// 开始一次音频渲染。
async function start() {
if (audioRenderer !== undefined) {
let stateGroup = [audio.AudioState.STATE_PREPARED, audio.AudioState.STATE_PAUSED, audio.AudioState.STATE_STOPPED];
if (stateGroup.indexOf(audioRenderer.state.valueOf()) === -1) { // 当且仅当状态为prepared、paused和stopped之一时才能启动渲染。
console.error('Audio renderer state is invalid.');
// ...
return;
}
// 启动渲染。
audioRenderer.start((err: BusinessError) => {
if (err) {
console.error(`Failed to start audio renderer. Code: ${err.code}, message: ${err.message}`);
// ...
} else {
console.info('Succeeded in starting audio renderer.');
// ...
}
});
}
}
async function pause() {
// 暂停渲染。
if (audioRenderer !== undefined) {
// 只有渲染器状态为running的时候才能暂停。
if (audioRenderer.state.valueOf() !== audio.AudioState.STATE_RUNNING) {
console.info('Audio renderer state is not running.');
// ...
return;
}
// 暂停渲染。
audioRenderer.pause((err: BusinessError) => {
if (err) {
console.error(`Failed to pause audio renderer. Code: ${err.code}, message: ${err.message}`);
// ...
} else {
console.info('Succeeded in pausing audio renderer.');
// ...
}
});
}
}
// 停止渲染。
async function stop() {
if (audioRenderer !== undefined) {
// 只有渲染器状态为running或paused的时候才可以停止。
if (audioRenderer.state.valueOf() !== audio.AudioState.STATE_RUNNING &&
audioRenderer.state.valueOf() !== audio.AudioState.STATE_PAUSED) {
console.info('Audio renderer state is not running or paused.');
// ...
return;
}
// 停止渲染。
audioRenderer.stop((err: BusinessError) => {
if (err) {
console.error(`Failed to stop audio renderer. Code: ${err.code}, message: ${err.message}`);
// ...
} else {
console.info('Succeeded in stopping audio renderer.');
// ...
}
});
}
}
// 销毁实例,释放资源。
async function release() {
if (audioRenderer !== undefined) {
// 渲染器状态不是released状态,才能release。
if (audioRenderer.state.valueOf() === audio.AudioState.STATE_RELEASED) {
console.info('Audio renderer state is released.');
// ...
return;
}
// ...
// 释放资源。
audioRenderer.release((err: BusinessError) => {
if (err) {
console.error(`Failed to release audio renderer. Code: ${err.code}, message: ${err.message}`);
// ...
} else {
// 关闭沙箱文件。
console.info('Succeeded in releasing audio renderer.');
// ...
}
});
}
}
当同优先级或高优先级音频流要使用输出设备时,当前音频流会被中断,应用可以自行响应中断事件并做出处理。具体的音频并发处理方式可参考处理音频焦点事件。
本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。
