1# 使用AudioSession管理应用音频焦点(C/C++)
2
3对于涉及多个音频流并发播放的场景，系统已预设了默认的[音频焦点策略](audio-playback-concurrency.md#音频焦点策略)，该策略将对所有音频流（包括播放和录制）实施统一的焦点管理。
4
5应用可利用音频会话管理（AudioSessionManager）提供的接口，通过AudioSession主动管理应用内音频流的焦点，自定义本应用音频流的焦点策略，调整本应用音频流释放音频焦点的时机，从而贴合应用特定的使用需求。
6
7本文档主要介绍AudioSession相关C API的使用方法和注意事项，更多音频焦点及音频会话的信息，可参考：[音频焦点和音频会话介绍](audio-playback-concurrency.md)。
8
9## 使用入门
10
11应用要使用OHAudio提供的音频会话管理（AudioSessionManager）能力，需要添加对应的头文件。
12
13### 在 CMake 脚本中链接动态库
14
15``` cmake
16target_link_libraries(sample PUBLIC libohaudio.so)
17```
18
19### 添加头文件
20
21应用通过引入[native_audio_session_manager.h](../../reference/apis-audio-kit/native__audio__session__manager_8h.md)头文件，使用音频播放相关API。
22
23```cpp
24#include <ohaudio/native_audio_session_manager.h>
25```
26
27## 获取音频会话管理器
28
29创建[OH_AudioSessionManager](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager)实例。在使用音频会话管理功能前，需要先通过[OH_AudioManager_GetAudioSessionManager](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiomanager_getaudiosessionmanager)创建音频会话管理实例。
30
31  ```cpp
32  OH_AudioSessionManager *audioSessionManager;
33  OH_AudioManager_GetAudioSessionManager(&audioSessionManager);
34  ```
35
36## 激活音频会话
37
38应用可以通过[OH_AudioSessionManager_ActivateAudioSession](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager_activateaudiosession)接口激活当前应用的音频会话。
39
40应用在[激活音频会话](#激活音频会话)时，需指定[音频会话策略（OH_AudioSession_Strategy）](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosession_strategy)，其中包含[音频并发模式（OH_AudioSession_ConcurrencyMode）](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosession_concurrencymode)参数，用于声明不同的音频并发策略。
41
42  ```cpp
43  OH_AudioSession_Strategy strategy = {CONCURRENCY_MIX_WITH_OTHERS};
44
45  OH_AudioSessionManager_ActivateAudioSession(audioSessionManager, &strategy);
46  ```
47
48## 查询音频会话是否已激活
49
50应用可以通过[OH_AudioSessionManager_IsAudioSessionActivated](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager_isaudiosessionactivated)接口检查当前应用的音频会话是否已激活。
51
52  ```cpp
53  bool isActivated = OH_AudioSessionManager_IsAudioSessionActivated(audioSessionManager);
54  ```
55
56## 停用音频会话
57
58应用可以通过[OH_AudioSessionManager_DeactivateAudioSession](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager_deactivateaudiosession)接口停用当前应用的音频会话。
59
60  ```cpp
61  OH_AudioSessionManager_DeactivateAudioSession(audioSessionManager);
62  ```
63
64## 监听音频会话停用事件
65
66在使用AudioSession功能的过程中，推荐应用监听[音频会话停用事件（OH_AudioSession_DeactivatedEvent）](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosession_deactivatedevent)。
67
68当AudioSession被停用（非主动停用）时，应用会收到[音频会话停用事件（OH_AudioSession_DeactivatedEvent）](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosession_deactivatedevent)，其中包含[音频会话停用原因（OH_AudioSession_DeactivatedReason）](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosession_deactivatedreason)。
69
70在收到AudioSessionDeactivatedEvent时，应用可根据自身业务需求，做相应的处理，例如释放相应资源、重新激活AudioSession等。
71
72### 定义回调函数
73
74  ```cpp
75  int32_t MyAudioSessionDeactivatedCallback(OH_AudioSession_DeactivatedEvent event)
76  {
77    switch(event.reason) {
78      case DEACTIVATED_LOWER_PRIORITY:
79        // 应用焦点被抢占
80        return 0;
81      case DEACTIVATED_TIMEOUT:
82        // 超时
83        return 0;
84    }
85  }
86  ```
87
88### 注册音频会话停用事件回调
89
90应用可以通过[OH_AudioSessionManager_RegisterSessionDeactivatedCallback](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager_registersessiondeactivatedcallback)接口监听音频会话停用事件。
91
92```cpp
93OH_AudioSessionManager_RegisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
94```
95
96### 取消注册音频会话停用事件回调
97
98应用可以通过[OH_AudioSessionManager_UnregisterSessionDeactivatedCallback](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiosessionmanager_unregistersessiondeactivatedcallback)接口取消监听音频会话停用事件。
99
100```cpp
101OH_AudioSessionManager_UnregisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
102```
103
104## 完整示例
105
106参考以下示例，完成音频会话从创建到激活并监听的过程。
107
108  ```cpp
109  #include <cstdint>
110  #include "ohaudio/native_audio_session_manager.h"
111
112  int32_t MyAudioSessionDeactivatedCallback(OH_AudioSession_DeactivatedEvent event)
113  {
114    switch(event.reason) {
115      case DEACTIVATED_LOWER_PRIORITY:
116        // 应用焦点被抢占
117        return 0;
118      case DEACTIVATED_TIMEOUT:
119        // 超时
120        return 0;
121    }
122  }
123
124  OH_AudioSessionManager *audioSessionManager;
125
126  // 创建音频会话管理器
127  OH_AudioCommon_Result resultManager = OH_AudioManager_GetAudioSessionManager(&audioSessionManager);
128
129  OH_AudioSession_Strategy strategy = {CONCURRENCY_MIX_WITH_OTHERS};
130
131  // 设置音频并发模式并激活音频会话
132  OH_AudioCommon_Result resultActivate = OH_AudioSessionManager_ActivateAudioSession(audioSessionManager, &strategy);
133
134  // 查询音频会话是否已激活。
135  bool isActivated = OH_AudioSessionManager_IsAudioSessionActivated(audioSessionManager);
136
137  // 监听音频会话停用事件
138  OH_AudioCommon_Result resultRegister = OH_AudioSessionManager_RegisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
139
140  // 音频会话激活后应用在此处正常执行音频播放、暂停、停止、释放等操作即可。
141
142  // 取消监听音频会话停用事件
143  OH_AudioCommon_Result resultUnregister = OH_AudioSessionManager_UnregisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
144
145  // 停用音频会话
146  OH_AudioCommon_Result resultDeactivate = OH_AudioSessionManager_DeactivateAudioSession(audioSessionManager);
147  ```
148