1# Extended Audio Concurrency Strategy (C/C++)
2
3The audio system offers a default concurrency strategy based on the audio stream type. If the default concurrency strategy cannot meet your service requirements, you can use an audio session to customize a strategy. The audio session is an extension of the default audio concurrency strategy. Example scenarios are as follows:
4
5- When an application that continuously plays a short sound does not want to be paused when running in the background, it can obtain an audio session to ensure a seamless integration of the entire playback process.
6
7- If the default concurrency strategy does not meet service requirements, an application can request an audio session and specify a strategy.
8
9The following figure shows the audio session process.
10
11![AudioSession status change](figures/audiosession-status-change.png)
12
13## Prerequisites
14
15To use the audio session management capability provided by OHAudio, add the corresponding header file.
16
17### Linking the Dynamic Link Library in the CMake Script
18
19``` cmake
20target_link_libraries(sample PUBLIC libohaudio.so)
21```
22
23### Adding Header Files
24
25Include the **native_audio_session_manager.h** header file so that the application can use the functions related to audio playback.
26
27```cpp
28#include <ohaudio/native_audio_session_manager.h>
29```
30
31## Audio Session Strategy
32
33In scenarios where multiple audio streams are active, an application can proactively establish an audio session strategy to manage how other applications handle audio streams once it has acquired audio focus.
34
35### Audio Concurrency Mode
36
37When the default concurrency strategy cannot meet service requirements, you can configure the audio concurrency mode.
38
39Four audio concurrency modes are provided. 
40
41- **CONCURRENCY_DEFAULT**: default concurrency strategy, which is used no audio session is used.
42
43- **CONCURRENCY_MIX_WITH_OTHERS**: mixes audio streams with other applications that are concurrently playing audio.
44
45  It is assumed that application A adopts **CONCURRENCY_MIX_WITH_OTHERS** and is playing audio streams, and application B applies to play audio streams at a later time. The relationship between applications A and B is described in the table below.
46
47  | Application Behavior Before Mode Configuration| Application Behavior After Mode Configuration|
48  | ------------ | ------------------ |
49  | Application A rejects the playback request of application B.| Application A mixes its audio playback with that of application B.|
50  | Application A pauses the playback of application B.| Application A mixes its audio playback with that of application B.|
51  | Application A lowers the volume of application B.| Application A mixes its audio playback with that of application B.|
52  | Application B lowers the volume of application A.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
53  | Application B pauses the playback of application A.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
54  | Application B stops the playback of application A.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
55
56  It is assumed that application A is playing audio streams, and application B adopts **CONCURRENCY_MIX_WITH_OTHERS** and applies to play audio streams at a later time. The relationship between applications A and B is described in the table below.
57
58  | Application Behavior Before Mode Configuration| Application Behavior After Mode Configuration|
59  | ------------ | ------------------ |
60  | Application A rejects the playback request of application B.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
61  | Application A pauses the playback of application B.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
62  | Application A lowers the volume of application B.| If applications and B have similar types, application A mixes its audio playback with that of application B.|
63  | Application B lowers the volume of application A.| Application A mixes its audio playback with that of application B.|
64  | Application B pauses the playback of application A.| Application A mixes its audio playback with that of application B.|
65  | Application B stops the playback of application A.| Application A mixes its audio playback with that of application B.|
66
67- **CONCURRENCY_DUCK_OTHERS**: lowers the volume of the application that is currently playing the audio.
68
69  It is assumed that application A is playing audio streams, and application B adopts **CONCURRENCY_DUCK_OTHERS** and applies to play audio streams at a later time. The relationship between applications A and B is described in the table below.
70
71  | Application Behavior Before Mode Configuration| Application Behavior After Mode Configuration|
72  | ------------ | ------------------ |
73  | Application B pauses the playback of application A.| Application B lowers the volume of application A.|
74  | Application B stops the playback of application A.| Application B lowers the volume of application A.|
75
76- **CONCURRENCY_PAUSE_OTHERS**: pauses the application that is currently playing the audio.
77
78  It is assumed that application A is playing audio streams, and application B that adopts **CONCURRENCY_PAUSE_OTHERS** applies to play audio streams at a later time. The relationship between applications A and B is described in the table below.
79
80  | Application Behavior Before Mode Configuration| Application Behavior After Mode Configuration|
81  | ------------ | ------------------ |
82  | Application B stops the playback of application A.| Application B pauses the playback of application A.|
83
84## Audio Session Deactivation Event
85
86It is recommended that an application listen for audio session deactivation events. When such an event occurs, the system performs corresponding operations on the related audio stream based on the reason of the deactivation.
87
88If the application wants to customize a concurrency strategy through the audio session again, it must activate the audio session first.
89
90### Reasons for Audio Session Deactivation
91
92Two audio session deactivation reasons are preset:
93
94- **DEACTIVATED_LOWER_PRIORITY**: The focus of the application that is playing audio streams is forcibly cleared.
95
96- **DEACTIVATED_TIME_OUT**: The default duration is reached after the application creates an audio session or stops audio playback. In this case, the volume of the application that was lowered in volume by this session will be restored to its original level, and the application that was paused by this session will receive a stop playback focus event.
97
98## Obtaining an Audio Session Manager
99
100Create an **OH_AudioSessionManager** instance. Before using audio session management, you must call **OH_AudioManager_GetAudioSessionManager** to create an **OH_AudioSessionManager** instance.
101
102  ```cpp
103  OH_AudioSessionManager *audioSessionManager;
104  OH_AudioManager_GetAudioSessionManager(&audioSessionManager);
105  ```
106
107## Activating an Audio Session
108
109Call **OH_AudioSessionManager_ActivateAudioSession** to activate an audio session.
110
111  ```cpp
112  OH_AudioSession_Strategy strategy = {CONCURRENCY_MIX_WITH_OTHERS};
113  
114  OH_AudioSessionManager_ActivateAudioSession(audioSessionManager, &strategy);
115  ```
116
117## Deactivating an Audio Session
118
119Call **OH_AudioSessionManager_DeactivateAudioSession** to deactivate an audio session when it is no longer needed.
120
121  ```cpp
122  OH_AudioSessionManager_DeactivateAudioSession(audioSessionManager);
123  ```
124
125## Checking Whether an Audio Session Is Activated
126
127Call **OH_AudioSessionManager_IsAudioSessionActivated** to check whether an audio session is activated.
128
129  ```cpp
130  bool isActivated = OH_AudioSessionManager_IsAudioSessionActivated(audioSessionManager);
131  ```
132
133## Registering and Unregistering the Audio Session Deactivation Event Callback
134
135### Defining a Callback
136
137  ```cpp
138  int32_t MyAudioSessionDeactivatedCallback(OH_AudioSession_DeactivatedEvent event)
139  {
140    switch(event.reason) {
141      case DEACTIVATED_LOWER_PRIORITY:
142        // The application focus is preempted.
143        return 0;
144      case DEACTIVATED_TIMEOUT:
145        // A timeout error occurs.
146        return 0;
147    }
148  }
149  ```
150
151### Registering a Callback to Listen for Audio Session Deactivation Events
152Call **OH_AudioSessionManager_RegisterSessionDeactivatedCallback** to register a callback to listen for audio session deactivation events.
153
154  ```cpp
155  OH_AudioSessionManager_RegisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
156  ```
157
158### Unregistering the Callback Used to Listen for Audio Session Deactivation Events
159
160Call **OH_AudioSessionManager_UnregisterSessionDeactivatedCallback** to unregister the callback used to listen for audio session deactivation events.
161
162  ```cpp
163  OH_AudioSessionManager_UnregisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
164  ```
165
166## Sample Code
167
168Refer to the sample code below to complete the process of creating, activating, and listening of an audio session.
169
170  ```cpp
171  #include <cstdint>
172  #include "ohaudio/native_audio_session_manager.h"
173  
174  int32_t MyAudioSessionDeactivatedCallback(OH_AudioSession_DeactivatedEvent event)
175  {
176    switch(event.reason) {
177      case DEACTIVATED_LOWER_PRIORITY:
178        // The application focus is preempted.
179        return 0;
180      case DEACTIVATED_TIMEOUT:
181        // A timeout error occurs.
182        return 0;
183    }
184  }
185  
186  OH_AudioSessionManager *audioSessionManager;
187
188  // Create an OH_AudioSessionManager instance.
189  OH_AudioCommon_Result resultManager = OH_AudioManager_GetAudioSessionManager(&audioSessionManager);
190  
191  OH_AudioSession_Strategy strategy = {CONCURRENCY_MIX_WITH_OTHERS};
192
193  // Set an audio concurrency mode and activate an audio session.
194  OH_AudioCommon_Result resultActivate = OH_AudioSessionManager_ActivateAudioSession(audioSessionManager, &strategy);
195  
196  // Check whether the audio session is activated.
197  bool isActivated = OH_AudioSessionManager_IsAudioSessionActivated(audioSessionManager);
198  
199  // Listen for audio session deactivation events.
200  OH_AudioCommon_Result resultRegister = OH_AudioSessionManager_RegisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
201
202  // After the audio session is activated, the application can perform operations such as playing, pausing, stopping, and releasing audio streams.
203  
204  // Cancel listening for audio session deactivation events.
205  OH_AudioCommon_Result resultUnregister = OH_AudioSessionManager_UnregisterSessionDeactivatedCallback(audioSessionManager, MyAudioSessionDeactivatedCallback);
206  
207  // Deactivate the audio session.
208  OH_AudioCommon_Result resultDeactivate = OH_AudioSessionManager_DeactivateAudioSession(audioSessionManager);
209  ```
210