大网数据广告活动
OpenHarmony 设备与应用开发

查询和监听音频输出设备

· 52CE 我爱测

应用可通过以下两种方式管理全局音频输出设备: - 通常情况下,可以通过AudioRoutingManager查询和监听音频输出设备。 - 从API version 20开始,AudioSessionManager提供了部分输出设备管理的接口,支持通过AudioSession查询和监听音频输出设备,方便在使用AudioSession管理音频焦点的同时管理音频输出。

查询和监听音频输出设备

应用可通过以下两种方式管理全局音频输出设备:

以下各步骤示例为片段代码,可通过示例代码右下方链接获取完整示例。

通过AudioRoutingManager查询和监听音频输出设备

本模块提供音频输出设备管理能力,包括查询设备信息和监听连接状态变化。具体API说明请参考文档AudioRoutingManager。

创建AudioRoutingManager实例

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

// ...
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耳机,带麦克风。
NEARLINK 31 星闪设备。

获取输出设备信息

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

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

监听设备连接状态变化

设置监听事件以监控设备连接状态的变化,设备连接或断开时触发回调。

说明:

监听设备连接状态变化可以监听到全部的设备连接状态变化,不建议作为应用处理自动暂停的依据。应用如需处理自动暂停相关业务,可参考音频流输出设备变更原因。

// ...
  // 监听音频设备状态变化。
  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');

选择音频输出设备(仅对系统应用开放)

选择音频输出设备,当前只能选择一个输出设备,以设备ID作为唯一标识。AudioDeviceDescriptors的具体信息可以参考AudioDeviceDescriptors。

说明:

用户可以选择连接一组音频设备(如一对蓝牙耳机),但系统侧只感知为一个设备,该组设备共用一个设备ID。


let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{
    deviceRole : audio.DeviceRole.OUTPUT_DEVICE,
    deviceType : audio.DeviceType.SPEAKER,
    id : 1,
    name : "",
    address : "",
    sampleRates : [44100],
    channelCounts : [2],
    channelMasks : [0],
    networkId : audio.LOCAL_NETWORK_ID,
    interruptGroupId : 1,
    volumeGroupId : 1,
    displayName : ""
}];

async function selectOutputDevice() {
  audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => {
    console.info('Invoke selectOutputDevice succeeded.');
  }).catch((err: BusinessError) => {
    console.error(`Invoke selectOutputDevice failed, code is ${err.code}, message is ${err.message}`);
  });
}

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

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

说明:

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

// ...
let rendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,// 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。
  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}`);
    // ...
  });
  // ...
}

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

// ...
let rendererInfo: audio.AudioRendererInfo = {
  usage: audio.StreamUsage.STREAM_USAGE_MUSIC,// 音频流使用类型:音乐。根据业务场景配置,参考StreamUsage。
  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');

通过AudioSession查询和监听音频输出设备

应用使用播放器的SDK播放音频流,不持有AudioRenderer对象,因此无法灵活控制播放设备的选择和状态监听。从API version 20开始,AudioSession不仅增加了焦点管理功能,还提供了音频输出设备管理功能,包括设置默认输出设备和监听设备变化。请参考以下文档获取更多信息:

创建AudioSession实例

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

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

let audioSessionManager = audioManager.getSessionManager();  // 再调用AudioManager的方法创建AudioSessionManager实例。

设置本机默认音频输出设备

setDefaultOutputDevice可以用于设置本机默认输出设备。

说明:

  • 由于AudioSession是应用级设置,调用本接口设置默认音频输出设备会覆盖AudioRenderer的setDefaultOutputDevice接口设置的音频输出设备信息。
  • 调用setDefaultOutputDevice设置音频输出设备后,如需取消,可将参数设为audio.DeviceType.DEFAULT,将音频设备选择权交还给系统。否则,每次调用activateAudioSession时,应用选择的默认输出设备将生效。
// ...
  // 设置默认输出设备为本机扬声器。
  audioSessionManager.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => {
    console.info('setDefaultOutputDevice Success!');
    // ...
  }).catch((err: BusinessError) => {
    console.error(`setDefaultOutputDevice Fail: ${err}`);
    // ...
  });
  // ...
  // 设置默认输出设备为默认设备,即取消应用设置的默认设备,交由系统选择设备。
  audioSessionManager.setDefaultOutputDevice(audio.DeviceType.DEFAULT).then(() => {
    console.info('setDefaultOutputDevice Success!');
    // ...
  }).catch((err: BusinessError) => {
    console.error(`setDefaultOutputDevice Fail: ${err}`);
    // [Exclude setting_DefaultOutputDevice]

    console.error(`Failed to set default output device. Code: ${err.code}, message: ${err.message}`);
    // ...
  });

查询本机默认音频输出设备

应用可以通过getDefaultOutputDevice查询本机默认输出设备类型。

说明:

本接口用于查询通过setDefaultOutputDevice接口设置的输出设备。

let deviceType = audioSessionManager.getDefaultOutputDevice();
console.info(`getDefaultOutputDevice Success, deviceType: ${deviceType}`);

监听输出设备变化

应用可以通过注册CurrentOutputDeviceChangedEvent监听输出设备的连接状态变化。

说明:

currentOutputDeviceChangedCallback包含设备变更的原因及推荐的后续操作。应用应根据不同的变更原因进行处理,并按系统推荐的操作继续或停止当前播放。

// ...
// 同一监听事件中,on方法和off方法传入callback参数一致,off方法取消对应on方法订阅的监听。
let currentOutputDeviceChangedCallback = (currentOutputDeviceChangedEvent: audio.CurrentOutputDeviceChangedEvent) => {
  console.info(`reason of audioSessionStateChanged: ${currentOutputDeviceChangedEvent.changeReason} `);

  // 为UI收集信息
  let callbackMsg = `reason of audioSessionStateChanged: ${currentOutputDeviceChangedEvent.changeReason} `;
  if (globalCallbackUpdate) {
    globalCallbackUpdate(callbackMsg);
  }

  switch (currentOutputDeviceChangedEvent.changeReason) {
    case audio.AudioStreamDeviceChangeReason.REASON_OLD_DEVICE_UNAVAILABLE:
      // 响应设备不可用事件,如果应用处于播放状态,应暂停播放,更新UX界面。
      break;
    case audio.AudioStreamDeviceChangeReason.REASON_NEW_DEVICE_AVAILABLE:
      // 应用根据业务情况响应设备可用事件。
      break;
    case audio.AudioStreamDeviceChangeReason.REASON_OVERRODE:
      // 应用根据业务情况响应设备强选事件。
      break;
    case audio.AudioStreamDeviceChangeReason.REASON_SESSION_ACTIVATED:
      // 应用根据业务情况响应audio session激活时的输出设备信息。
      break;
    case audio.AudioStreamDeviceChangeReason.REASON_STREAM_PRIORITY_CHANGED:
      // 应用根据业务情况响应其它更高优先级的音频流触发的设备变更事件。
      break;
    case audio.AudioStreamDeviceChangeReason.REASON_UNKNOWN:
      // 应用根据业务情况响应未知原因事件。
      break;
  }
};
// ...
  audioSessionManager.on('currentOutputDeviceChanged', currentOutputDeviceChangedCallback);
  // ...
  audioSessionManager.off('currentOutputDeviceChanged', currentOutputDeviceChangedCallback);
  // ...
  // 取消该事件的所有监听。
  audioSessionManager.off('currentOutputDeviceChanged');

获取活跃输出设备信息(仅对系统应用开放)

从API版本26.0.0开始,使用getActiveOutputDeviceDescriptors方法,可以获取当前音频设备场景下的活跃输出设备描述符。

说明:

该接口返回的活跃设备跟系统的音频设备选择策略AudioStreamDeviceChangeReason有关。


async function getActiveOutputDeviceDescriptors() {
  audioRoutingManager.getActiveOutputDeviceDescriptors().then((audioDeviceDescriptors: audio.AudioDeviceDescriptors) => {
    console.info(`Succeeded in getting active output device descriptors, AudioDeviceDescriptors: ${JSON.stringify(audioDeviceDescriptors)}.`);
    for (let i = 0; i < audioDeviceDescriptors.length; i++) {
      console.info(`Active Device ${i} - id: ${audioDeviceDescriptors[i].id}`);
      console.info(`Active Device ${i} - name: ${audioDeviceDescriptors[i].name}`);
      console.info(`Active Device ${i} - type: ${audioDeviceDescriptors[i].deviceType}`);
      console.info(`Active Device ${i} - role: ${audioDeviceDescriptors[i].deviceRole}`);
      console.info(`Active Device ${i} - address: ${audioDeviceDescriptors[i].address}`);
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get active output device descriptors. Code: ${err.code}, message: ${err.message}`);
  });
}

本文来自 OpenHarmony 文档贡献者,按 CC BY 4.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
OpenHarmony 文档贡献者
适用范围
master 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
CC BY 4.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。