From 8cfffe5946cbcce11ebf88c43de87278c05842f0 Mon Sep 17 00:00:00 2001 From: zhangkai Date: Wed, 2 Jul 2025 20:15:52 +0800 Subject: [PATCH] =?UTF-8?q?audio=E8=B5=84=E6=96=99=E4=BC=98=E5=8C=96?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: zhangkai --- .../media/audio/audio-playback-concurrency.md | 16 +++-- .../media/audio/volume-management.md | 69 ++++++++++++++++++- 2 files changed, 80 insertions(+), 5 deletions(-) diff --git a/zh-cn/application-dev/media/audio/audio-playback-concurrency.md b/zh-cn/application-dev/media/audio/audio-playback-concurrency.md index 0afb32f3c6a..2cd6b7e6cba 100644 --- a/zh-cn/application-dev/media/audio/audio-playback-concurrency.md +++ b/zh-cn/application-dev/media/audio/audio-playback-concurrency.md @@ -120,7 +120,7 @@ InterruptForceType参数提示应用该焦点变化是否已由系统强制操作： - - 强制打断类型（INTERRUPT_FORCE）：由系统进行操作，强制执行。应用需要做一些必要的处理，例如更新状态、更新界面显示等。 + - 强制打断类型（INTERRUPT_FORCE）：由系统进行操作，强制执行。应用收到打断提示后无需再调用系统相关接口，只需做一些必要的处理，例如更新状态、更新界面显示等。 - 共享打断类型（INTERRUPT_SHARE）：由应用进行操作，应用可以选择响应或忽略，系统不会干涉。 @@ -218,15 +218,23 @@ async function onAudioInterrupt(): Promise { 应用可以使用音频会话（AudioSession）的相关接口，自定义本应用音频流的焦点策略。在系统进行焦点管理时，只要条件允许，本应用的所有音频流将优先遵循这一策略。 +> **注意：** +> +> - 应用在申请音频焦点（开始音频播放或录制）之前需要确保AudioSession已经处于激活状态，否则AudioSession的自定义焦点策略不会影响此次焦点申请。若应用使用了异步接口，则需要格外注意异步操作执行的时序。 +> +> - [音频会话策略（AudioSessionStrategy）](#音频会话策略audiosessionstrategy)中的并发模式（CONCURRENCY_MIX_WITH_OTHERS）为双向生效，其他策略均为单向生效。 +> +> - 音频策略优先级为：STOP > PAUSE > DUCK > PLAYBOTH。当指定的[音频会话策略（AudioSessionStrategy）](#音频会话策略audiosessionstrategy)优先级高于默认策略时，指定的音频会话策略不会生效。 + 使用音频会话（AudioSession）相关接口，主要可以实现以下功能： - 应用激活音频会话（AudioSession）并指定[音频会话策略（AudioSessionStrategy）](#音频会话策略audiosessionstrategy)后，本应用的所有音频流在参与焦点管理时，会优先使用该策略。 - 典型场景：应用播放短视频时，会打断后台音乐，应用希望自身的音频流停止后，后台的音乐可以自动恢复。 + 典型场景：应用播放短视频时，会打断后台音乐，应用希望自身的音频流停止后，后台的音乐可以自动恢复（该场景需要应用在音频流启动前激活AudioSession，音频流停止后停用AudioSession）。 - 音频会话（AudioSession）处于激活状态下，本应用的音频流全部停止时，不会立刻释放音频焦点，系统会保持音频焦点，直到音频会话停用时再释放音频焦点，或是直到该应用有新的音频流申请焦点。 - 典型场景：应用连续播放多个音频时，在多个音频衔接的间隙，不希望后台被影响的其他音频自动恢复，希望整个播放过程保持音频焦点的连贯性。 + 典型场景：应用连续播放多个音频时，在多个音频衔接的间隙，不希望后台被影响的其他音频自动恢复，希望整个播放过程保持音频焦点的连贯性（该场景需要应用在整个播放过程开始前激活AudioSession，整个播放过程结束后停用AudioSession）。 ### 音频会话（AudioSession）使用流程 @@ -270,7 +278,7 @@ async function onAudioInterrupt(): Promise { - 默认模式（CONCURRENCY_DEFAULT）：即系统默认的[音频焦点策略](#音频焦点策略)。 -- 并发模式（CONCURRENCY_MIX_WITH_OTHERS）：和其它音频流并发。 +- 并发模式（CONCURRENCY_MIX_WITH_OTHERS）：和其他音频流并发。 - 降低音量模式（CONCURRENCY_DUCK_OTHERS）：和其他音频流并发，并且降低其他音频流的音量。 diff --git a/zh-cn/application-dev/media/audio/volume-management.md b/zh-cn/application-dev/media/audio/volume-management.md index 4af5c051eb2..20ff2695601 100644 --- a/zh-cn/application-dev/media/audio/volume-management.md +++ b/zh-cn/application-dev/media/audio/volume-management.md @@ -41,6 +41,61 @@ let audioManager = audio.getAudioManager(); let audioVolumeManager = audioManager.getVolumeManager(); ``` +### 获取音量信息 + +管理音频组音量的接口由AudioVolumeGroupManager提供，在使用之前，需要使用[getVolumeGroupManager()](../../reference/apis-audio-kit/arkts-apis-audio-AudioVolumeManager.md#getvolumegroupmanager9)获取AudioVolumeGroupManager实例。 + +```ts +import { audio } from '@kit.AudioKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; + +audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { + if (err) { + console.error(`Failed to obtain the volume group infos list. ${err}`); + return; + } + console.info('Callback invoked to indicate that the volume group infos list is obtained.'); +}); +``` + +使用[AudioVolumeGroupManager](../../reference/apis-audio-kit/arkts-apis-audio-AudioVolumeGroupManager.md)获取指定流的音量信息。 + +示例代码如下所示： + +```ts +import { audio } from '@kit.AudioKit'; +import { BusinessError } from '@kit.BasicServicesKit'; + +// 获取指定流的音量。 +audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { + if (err) { + console.error(`Failed to obtain the volume. ${err}`); + return; + } + console.info('Callback invoked to indicate that the volume is obtained.'); +}); + +// 获取指定流的最小音量。 +audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { + if (err) { + console.error(`Failed to obtain the minimum volume. ${err}`); + return; + } + console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); +}); + +// 获取指定流的最大音量。 +audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { + if (err) { + console.error(`Failed to obtain the maximum volume. ${err}`); + return; + } + console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); +}); +``` + ### 监听系统音量变化 通过设置监听事件，可以监听系统音量的变化： @@ -158,16 +213,28 @@ let volume = 1.0; // 指定的音量大小，取值范围为[0.00-1.00]，1表 avPlayer.setVolume(volume); ``` -使用[AudioRenderer](../../reference/apis-audio-kit/arkts-apis-audio-f.md#audiocreateaudiorenderer8)设置音频流音量的示例代码如下： +使用[AudioRenderer](../../reference/apis-audio-kit/arkts-apis-audio-f.md#audiocreateaudiorenderer8)的[setVolume](../../reference/apis-audio-kit/arkts-apis-audio-AudioRenderer.md#setvolume9)和[getVolume](../../reference/apis-audio-kit/arkts-apis-audio-AudioRenderer.md#getvolume12)接口分别完成音频流音量的设置和获取。 + +示例代码如下所示： ```ts 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}`); }); + +// 获取音频流音量。 +try { + let value: number = audioRenderer.getVolume(); + console.info(`Indicate that the volume is obtained ${value}.`); +} catch (err) { + let error = err as BusinessError; + console.error(`Failed to obtain the volume, error ${error}.`); +} ``` ### 监听活跃流变化 -- Gitee