【鸿蒙实战开发】HarmonyOS音频播放开发（二）

播放音量管理

播放音量的管理主要包括对系统音量的管理和对音频流音量的管理。系统音量与音频流音量分别是指HarmonyOS系统的总音量和指定音频流的音量，其中音频流音量的大小受制于系统音量，管理两者的接口不同。

系统音量

管理系统音量的接口是AudioVolumeManager，在使用之前，需要使用getVolumeManager()获取AudioVolumeManager实例。

通过AudioVolumeManager只能获取音量信息及监听音量变化，不能主动调节系统音量。如果应用需要调节系统音量，可以使用音量面板调节系统音量。

import { audio } from '@kit.AudioKit';

let audioManager = audio.getAudioManager();
let audioVolumeManager = audioManager.getVolumeManager();

监听系统音量变化

通过设置监听事件，可以监听系统音量的变化：

import { audio } from '@kit.AudioKit';

audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => {
  console.info(`VolumeType of stream: ${volumeEvent.volumeType} `);
  console.info(`Volume level: ${volumeEvent.volume} `);
  console.info(`Whether to updateUI: ${volumeEvent.updateUi} `);
});

使用音量面板调节系统音量

应用无法直接调节系统音量，可以通过系统音量面板，让用户通过界面操作来调节音量。当用户通过应用内音量面板调节音量时，系统会展示音量提示界面，显性地提示用户系统音量发生改变。

系统提供了ArkTS组件AVVolumePanel（音量面板），应用可以创建该组件，具样例和介绍请查看AVVolumePanel参考文档。

音频流音量

管理音频流音量的接口是AVPlayer或AudioRenderer的setVolume()方法，使用AVPlayer设置音频流音量的示例代码如下：

let volume = 1.0  // 指定的音量大小，取值范围为[0.00-1.00]，1表示最大音量
avPlayer.setVolume(volume);

使用AudioRenderer设置音频流音量的示例代码如下：

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

audioRenderer.setVolume(0.5).then(() => {  // 音量范围为[0.0-1.0]
  console.info('Invoke setVolume succeeded.');
}).catch((err: BusinessError) => {  
  console.error(`Invoke setVolume failed, code is ${err.code}, message is ${err.message}`);
});

音效管理

音效管理主要包括播放实例音效管理和全局音效查询两部分，播放实例音效管理主要包括查询和设置当前音频播放流的音效模式，全局音效查询支持查询StreamUsage对应场景支持的音效模式。

播放实例音效管理

主要包括查询和设置当前音频播放流的音效模式，音效模式包括EFFECT_NONE关闭音效模式和EFFECT_DEFAULT默认音效模式。默认音效模式会根据创建音频流的StreamUsage自动加载对应场景的音效。

获取播放实例

管理播放实例音效的接口是getAudioEffectMode()查询当前音频播放流的音效模式和setAudioEffectMode(mode: AudioEffectMode)设置当前音频播放流的音效模式，在使用之前，需要使用createAudioRenderer(options: AudioRendererOptions)先创建音频播放流AudioRenderer实例。

1. 导入音频接口。

import { audio } from '@kit.AudioKit';

2. 配置音频渲染参数并创建AudioRenderer实例，音频渲染参数的详细信息可以查看AudioRendererOptions，创建AudioRenderer实例时会默认挂载EFFECT_DEFAULT模式音效。

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

let audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100,
  channels: audio.AudioChannel.CHANNEL_1,
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
};

let audioRendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION,
  rendererFlags: 0
};

let audioRendererOptions: audio.AudioRendererOptions = {
  streamInfo: audioStreamInfo,
  rendererInfo: audioRendererInfo
};
let audioRenderer: audio.AudioRenderer | undefined = undefined;

audio.createAudioRenderer(audioRendererOptions, (err: BusinessError, data: audio.AudioRenderer) => {
  if (err) {
    console.error(`Invoke createAudioRenderer failed, code is ${err.code}, message is ${err.message}`);
    return;
  } else {
    console.info('Invoke createAudioRenderer succeeded.');
    audioRenderer = data;
  }
});

查询当前播放实例的音效模式

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

audioRenderer.getAudioEffectMode((err: BusinessError, effectMode: audio.AudioEffectMode) => {
  if (err) {
    console.error(`Failed to get params, code is ${err.code}, message is ${err.message}`);
    return;    
  } else {
    console.info(`getAudioEffectMode: ${effectMode}`);
  }
});

设置当前播放实例的音效模式

关闭系统音效：

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_NONE, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set params, code is ${err.code}, message is ${err.message}`);
    return;
  } else {
    console.info('Callback invoked to indicate a successful audio effect mode setting.');
  }
});

开启系统音效默认模式：

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set params, code is ${err.code}, message is ${err.message}`);
    return;
  } else {
    console.info('Callback invoked to indicate a successful audio effect mode setting.');
  }
});

全局查询音效模式

主要包括全局音效查询相应StreamUsage对应场景的音效模式。

对于播放音频类的应用，开发者需要关注该应用的音频流使用什么音效模式并做出相应的操作，比如音乐App播放时，应选择音乐场景下的模式。在使用查询接口前，开发者需要使用getStreamManager()创建一个AudioStreamManager音频流管理实例。

获取音频流管理接口

创建AudioStreamManager实例。在使用AudioStreamManager的API前，需要使用getStreamManager()创建一个AudioStreamManager实例。

import { audio } from '@kit.AudioKit';

let audioManager = audio.getAudioManager();
let audioStreamManager = audioManager.getStreamManager();

查询对应场景的音效模式

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC, async (err: BusinessError, audioEffectInfoArray: audio.AudioEffectInfoArray) => {
  if (err) {
    console.error('Failed to get effect info array');
    return;    
  } else {
    console.info(`getAudioEffectInfoArray: ${audioEffectInfoArray}`);
  }
});

音频播放流管理

对于播放音频类的应用，开发者需要关注该应用的音频流的状态以做出相应的操作，比如监听到状态为播放中/暂停时，及时改变播放按钮的UI显示。

读取或监听应用内音频流状态变化

参考使用AudioRenderer开发音频播放功能或audio.createAudioRenderer，完成AudioRenderer的创建，然后可以通过以下两种方式查看音频流状态的变化：

• 方法1：直接查看AudioRenderer的state：

import { audio } from '@kit.AudioKit';

let audioRendererState: audio.AudioState = audioRenderer.state;
console.info(`Current state is: ${audioRendererState }`)

• 方法2：注册stateChange监听AudioRenderer的状态变化：

import { audio } from '@kit.AudioKit';

audioRenderer.on('stateChange', (rendererState: audio.AudioState) => {
  console.info(`State change to: ${rendererState}`)
});

获取state后可对照AudioState来进行相应的操作，比如更改暂停播放按钮的显示等。

读取或监听所有音频流的变化

如果部分应用需要查询获取所有音频流的变化信息，可以通过AudioStreamManager读取或监听所有音频流的变化。

如下为音频流管理调用关系图：

在进行应用开发的过程中，开发者需要使用getStreamManager()创建一个AudioStreamManager实例，进而通过该实例管理音频流。开发者可通过调用on(‘audioRendererChange’)监听音频流的变化，在音频流状态变化、设备变化时获得通知。同时可通过off(‘audioRendererChange’)取消相关事件的监听。另外，开发者可以主动调用getCurrentAudioRendererInfoArray()来查询播放流的唯一ID、播放流客户端的UID、音频流状态等信息。

详细API含义可参考音频管理API文档AudioStreamManager。

开发步骤及注意事项

1. 创建AudioStreamManager实例。

   在使用AudioStreamManager的API前，需要使用getStreamManager()创建一个AudioStreamManager实例。

import { audio } from '@kit.AudioKit';

let audioManager = audio.getAudioManager();
let audioStreamManager = audioManager.getStreamManager();

2. 使用on(‘audioRendererChange’)监听音频播放流的变化。 如果音频流监听应用需要在音频播放流状态变化、设备变化时获取通知，可以订阅该事件。

import { audio } from '@kit.AudioKit';

audioStreamManager.on('audioRendererChange',  (AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => {
  for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) {
    let AudioRendererChangeInfo = AudioRendererChangeInfoArray[i];
    console.info(`## RendererChange on is called for ${i} ##`);
    console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`);
    console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`);
    console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`);
    console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 
    for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) {
      console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`);
      console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`);
      console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`);
      console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`);
      console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`);
      console.info(`SampleRates: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`);
      console.info(`ChannelCount ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`);
      console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks}`);
    }
  }
});

3. （可选）使用off(‘audioRendererChange’)取消监听音频播放流变化。

audioStreamManager.off('audioRendererChange');
console.info('RendererChange Off is called ');

4. （可选）使用getCurrentAudioRendererInfoArray()获取所有音频播放流的信息。

   该接口可获取音频播放流唯一ID、音频播放客户端的UID、音频状态以及音频播放器的其他信息。

   说明

   对所有音频流状态进行监听的应用需要声明权限ohos.permission.USE_BLUETOOTH，否则无法获得实际的设备名称和设备地址信息，查询到的设备名称和设备地址（蓝牙设备的相关属性）将为空字符串。

   import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

async function getCurrentAudioRendererInfoArray(): Promise<void> {
  await audioStreamManager.getCurrentAudioRendererInfoArray().then((AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => {
    console.info(`getCurrentAudioRendererInfoArray  Get Promise is called `);
    if (AudioRendererChangeInfoArray != null) {
      for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) {
        let AudioRendererChangeInfo = AudioRendererChangeInfoArray[i];
        console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`);
        console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`);
        console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`);
        console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`);  
        for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) {
          console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`);
          console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`);
          console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`);
          console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`);
          console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`);
          console.info(`SampleRates: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`);
          console.info(`ChannelCount ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`);
          console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks}`);
        }
      }
    }
  }).catch((err: BusinessError ) => {
    console.error(`Invoke getCurrentAudioRendererInfoArray failed, code is ${err.code}, message is ${err.message}`);
  });
}

音频输出设备管理

有时设备同时连接多个音频输出设备，需要指定音频输出设备进行音频播放，此时需要使用AudioRoutingManager接口进行输出设备的管理，API说明可以参考AudioRoutingManager API文档。

创建AudioRoutingManager实例

在使用AudioRoutingManager管理音频设备前，需要先导入模块并创建实例。

import { audio } from '@kit.AudioKit';  // 导入audio模块

let audioManager = audio.getAudioManager();  // 需要先创建AudioManager实例

let audioRoutingManager = audioManager.getRoutingManager();  // 再调用AudioManager的方法创建AudioRoutingManager实例

支持的音频输出设备类型

目前支持的音频输出设备见下表：

名称	值	说明
EARPIECE	1	听筒。
SPEAKER	2	扬声器。
WIRED_HEADSET	3	有线耳机，带麦克风。
WIRED_HEADPHONES	4	有线耳机，无麦克风。
BLUETOOTH_SCO	7	蓝牙设备SCO（Synchronous Connection Oriented）连接。
BLUETOOTH_A2DP	8	蓝牙设备A2DP（Advanced Audio Distribution Profile）连接。
USB_HEADSET	22	USB耳机，带麦克风。

获取输出设备信息

使用getDevices()方法可以获取当前所有输出设备的信息。

import { audio } from '@kit.AudioKit';

audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => {
  console.info('Promise returned to indicate that the device list is obtained.');
});

监听设备连接状态变化

可以设置监听事件来监听设备连接状态的变化，当有设备连接或断开时触发回调：

import { audio } from '@kit.AudioKit';

// 监听音频设备状态变化
audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => {
  console.info(`device change type : ${deviceChanged.type}`);  // 设备连接状态变化，0为连接，1为断开连接
  console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length}`);
  console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole}`);  // 设备角色
  console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType}`);  // 设备类型
});

// 取消监听音频设备状态变化
audioRoutingManager.off('deviceChange');

获取最高优先级输出设备信息

使用getPreferOutputDeviceForRendererInfo()方法, 可以获取当前最高优先级的输出设备。

说明

最高优先级输出设备表示声音将在此设备输出的设备。

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

let rendererInfo: audio.AudioRendererInfo = {
    usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags : 0
}

async function getPreferOutputDeviceForRendererInfo() {
  audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => {
    console.info(`device descriptor: ${desc}`);
  }).catch((err: BusinessError) => {
    console.error(`Result ERROR: ${err}`);
  })
}

监听最高优先级输出设备变化

import { audio } from '@kit.AudioKit';

let rendererInfo: audio.AudioRendererInfo = {
    usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
    rendererFlags : 0
}

// 监听最高优先级输出设备变化
audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => {
    console.info(`device change descriptor : ${desc[0].deviceRole}`);  // 设备角色
    console.info(`device change descriptor : ${desc[0].deviceType}`);  // 设备类型
});

// 取消监听最高优先级输出设备变化
audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo');

写在最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）文档用来跟着学习是非常有必要的。

希望这一份鸿蒙学习文档能够给大家带来帮助，有需要的小伙伴自行领取，限时开源，先到先得~无套路领取！！

如果你是一名有经验的资深Android移动开发、Java开发、前端开发、对鸿蒙感兴趣以及转行人员，可以直接领取这份资料

请点击→纯血版全套鸿蒙HarmonyOS学习文档

鸿蒙（HarmonyOS NEXT）5.0最新学习路线

路线图适合人群：

IT开发人员：想要拓展职业边界
零基础小白：鸿蒙爱好者，希望从0到1学习，增加一项技能。
技术提升/进阶跳槽：发展瓶颈期，提升职场竞争力，快速掌握鸿蒙技术

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习文档

《鸿蒙 (HarmonyOS)开发入门教学视频》

《鸿蒙生态应用开发V3.0白皮书》

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

《鸿蒙开发基础》

●ArkTS语言
●安装DevEco Studio
●运用你的第一个ArkTS应用
●ArkUI声明式UI开发
.……

《鸿蒙开发进阶》

●Stage模型入门
●网络管理
●数据管理
●电话服务
●分布式应用开发
●通知与窗口管理
●多媒体技术
●安全技能
●任务管理
●WebGL
●国际化开发
●应用测试
●DFX面向未来设计
●鸿蒙系统移植和裁剪定制
……

《鸿蒙进阶实战》

●ArkTS实践
●UIAbility应用
●网络案例
……

获取以上完整鸿蒙HarmonyOS学习文档，请点击→纯血版全套鸿蒙HarmonyOS学习文档