1# 使用OHAudio开发音频播放功能(C/C++) 2 3OHAudio是系统在API version 10中引入的一套C API，此API在设计上实现归一，同时支持普通音频通路和低时延通路。仅支持PCM格式，适用于依赖Native层实现音频输出功能的场景。 4 5OHAudio音频播放状态变化示意图： 6 7 8## 使用入门 9 10开发者要使用OHAudio提供的播放能力，需要添加对应的头文件。 11 12### 在 CMake 脚本中链接动态库 13 14``` cmake 15target_link_libraries(sample PUBLIC libohaudio.so) 16``` 17 18### 添加头文件 19 20开发者通过引入<[native_audiostreambuilder.h](../../reference/apis-audio-kit/native__audiostreambuilder_8h.md)>和<[native_audiorenderer.h](../../reference/apis-audio-kit/native__audiorenderer_8h.md)>头文件，使用音频播放相关API。 21 22```cpp 23#include <ohaudio/native_audiorenderer.h> 24#include <ohaudio/native_audiostreambuilder.h> 25``` 26 27## 音频流构造器 28 29OHAudio提供OH_AudioStreamBuilder接口，遵循构造器设计模式，用于构建音频流。开发者需要根据业务场景，指定对应的[OH_AudioStream_Type](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_type) 。 30 31`OH_AudioStream_Type`包含两种类型： 32 33- AUDIOSTREAM_TYPE_RENDERER 34- AUDIOSTREAM_TYPE_CAPTURER 35 36使用[OH_AudioStreamBuilder_Create](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_create)创建构造器示例： 37 38```cpp 39OH_AudioStreamBuilder* builder; 40OH_AudioStreamBuilder_Create(&builder, streamType); 41``` 42 43在音频业务结束之后，开发者应该执行[OH_AudioStreamBuilder_Destroy](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_destroy)接口来销毁构造器。 44 45```cpp 46OH_AudioStreamBuilder_Destroy(builder); 47``` 48 49## 开发步骤及注意事项 50 51详细的API说明请参考[OHAudio API参考](../../reference/apis-audio-kit/_o_h_audio.md)。 52 53开发者可以通过以下几个步骤来实现一个简单的播放功能。 54 551. 创建构造器 56 57 ```cpp 58 OH_AudioStreamBuilder* builder; 59 OH_AudioStreamBuilder_Create(&builder, AUDIOSTREAM_TYPE_RENDERER); 60 ``` 61 622. 配置音频流参数 63 64 创建音频播放构造器后，可以设置音频流所需要的参数，可以参考下面的案例。 65 66 ```cpp 67 // 设置音频采样率 68 OH_AudioStreamBuilder_SetSamplingRate(builder, 48000); 69 // 设置音频声道 70 OH_AudioStreamBuilder_SetChannelCount(builder, 2); 71 // 设置音频采样格式 72 OH_AudioStreamBuilder_SetSampleFormat(builder, AUDIOSTREAM_SAMPLE_S16LE); 73 // 设置音频流的编码类型 74 OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_RAW); 75 // 设置输出音频流的工作场景 76 OH_AudioStreamBuilder_SetRendererInfo(builder, AUDIOSTREAM_USAGE_MUSIC); 77 ``` 78 79 注意，播放的音频数据要通过回调接口写入，开发者要实现回调接口，使用`OH_AudioStreamBuilder_SetRendererCallback`设置回调函数。回调函数的声明请查看[OH_AudioRenderer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_callbacks) 。 80 813. 设置音频回调函数 82 83 多音频并发处理可参考文档[处理音频焦点事件](audio-playback-concurrency.md)，仅接口语言差异。 84 85 在设置音频回调函数时API version 12新增回调函数[OH_AudioRenderer_OnWriteDataCallback](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_onwritedatacallback)用于写入音频数据。 86 87 - API version 12开始**推荐**使用[OH_AudioRenderer_OnWriteDataCallback](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_onwritedatacallback)代替[OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData](../../reference/apis-audio-kit/_o_h___audio_renderer___callbacks___struct.md#oh_audiorenderer_onwritedata)用于写入音频数据。 88 89 > **注意：** 90 > 91 > - 能填满回调所需长度数据的情况下，返回AUDIO_DATA_CALLBACK_RESULT_VALID，系统会取用完整长度的数据缓冲进行播放。请不要在未填满数据的情况下返回AUDIO_DATA_CALLBACK_RESULT_VALID，否则会导致杂音、卡顿等现象。 92 > 93 > - 在无法填满回调所需长度数据的情况下，建议开发者返回AUDIO_DATA_CALLBACK_RESULT_INVALID，系统不会处理该段音频数据，然后会再次向应用请求数据，确认数据填满后返回AUDIO_DATA_CALLBACK_RESULT_VALID。 94 > 95 > - 回调函数结束后，音频服务会把缓冲中数据放入队列里等待播放，因此请勿在回调外再次更改缓冲中的数据。对于最后一帧，如果数据不够填满缓冲长度，开发者需要使用剩余数据拼接空数据的方式，将缓冲填满，避免缓冲内的历史脏数据对播放效果产生不良的影响。 96 97 从API version 12开始可通过[OH_AudioStreamBuilder_SetFrameSizeInCallback](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setframesizeincallback)设置audioDataSize的大小。 98 99 ```cpp 100 // 自定义写入数据函数 101 static OH_AudioData_Callback_Result NewAudioRendererOnWriteData( 102 OH_AudioRenderer* renderer, 103 void* userData, 104 void* audioData, 105 int32_t audioDataSize) 106 { 107 // 将待播放的数据，按audioDataSize长度写入audioData 108 // 如果开发者不希望播放某段audioData，返回AUDIO_DATA_CALLBACK_RESULT_INVALID即可 109 return AUDIO_DATA_CALLBACK_RESULT_VALID; 110 } 111 // 自定义音频流事件函数 112 int32_t MyOnStreamEvent( 113 OH_AudioRenderer* renderer, 114 void* userData, 115 OH_AudioStream_Event event) 116 { 117 // 根据event表示的音频流事件信息，更新播放器状态和界面 118 return 0; 119 } 120 // 自定义音频中断事件函数 121 int32_t MyOnInterruptEvent( 122 OH_AudioRenderer* renderer, 123 void* userData, 124 OH_AudioInterrupt_ForceType type, 125 OH_AudioInterrupt_Hint hint) 126 { 127 // 根据type和hint表示的音频中断信息，更新播放器状态和界面 128 return 0; 129 } 130 // 自定义异常回调函数 131 int32_t MyOnError( 132 OH_AudioRenderer* renderer, 133 void* userData, 134 OH_AudioStream_Result error) 135 { 136 // 根据error表示的音频异常信息，做出相应的处理 137 return 0; 138 } 139 140 OH_AudioRenderer_Callbacks callbacks; 141 142 // 配置回调函数 143 callbacks.OH_AudioRenderer_OnStreamEvent = MyOnStreamEvent; 144 callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent; 145 callbacks.OH_AudioRenderer_OnError = MyOnError; 146 callbacks.OH_AudioRenderer_OnWriteData = nullptr; 147 148 // 设置输出音频流的回调 149 OH_AudioStreamBuilder_SetRendererCallback(builder, callbacks, nullptr); 150 151 // 配置写入音频数据回调函数 152 OH_AudioRenderer_OnWriteDataCallback writeDataCb = NewAudioRendererOnWriteData; 153 OH_AudioStreamBuilder_SetRendererWriteDataCallback(builder, writeDataCb, nullptr); 154 ``` 155 156 - API version 11使用回调函数[OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData](../../reference/apis-audio-kit/_o_h___audio_renderer___callbacks___struct.md#oh_audiorenderer_onwritedata)用于写入音频数据。 157 158 > **注意：** 159 > 160 > - 该函数不支持返回回调结果，系统默认回调中的数据均为有效数据。请确保填满回调所需长度数据，否则会导致杂音、卡顿等现象。 161 > 162 > - 在无法填满回调所需长度数据的情况下，建议开发者选择暂时停止写入数据（不暂停音频流），阻塞回调函数，等待数据充足时，再继续写入数据，确保数据填满。在阻塞回调函数后，如需调用AudioRenderer相关接口，需先解阻塞。 163 > 164 > - 开发者如果不希望播放本次回调中的音频数据，可以主动将回调中的数据块置空（置空后，也会被系统统计到已写入的数据，播放静音帧）。 165 > 166 > - 回调函数结束后，音频服务会把缓冲中数据放入队列里等待播放，因此请勿在回调外再次更改缓冲中的数据。对于最后一帧，如果数据不够填满缓冲长度，开发者需要使用剩余数据拼接空数据的方式，将缓冲填满，避免缓冲内的历史脏数据对播放效果产生不良的影响。 167 168 ```cpp 169 // 自定义写入数据函数 170 int32_t MyOnWriteData( 171 OH_AudioRenderer* renderer, 172 void* userData, 173 void* buffer, 174 int32_t length) 175 { 176 // 将待播放的数据，按length长度写入buffer 177 // 如果开发者不希望播放某段buffer，可在此处对buffer进行置空处理。 178 return 0; 179 } 180 // 自定义音频流事件函数 181 int32_t MyOnStreamEvent( 182 OH_AudioRenderer* renderer, 183 void* userData, 184 OH_AudioStream_Event event) 185 { 186 // 根据event表示的音频流事件信息，更新播放器状态和界面 187 return 0; 188 } 189 // 自定义音频中断事件函数 190 int32_t MyOnInterruptEvent( 191 OH_AudioRenderer* renderer, 192 void* userData, 193 OH_AudioInterrupt_ForceType type, 194 OH_AudioInterrupt_Hint hint) 195 { 196 // 根据type和hint表示的音频中断信息，更新播放器状态和界面 197 return 0; 198 } 199 // 自定义异常回调函数 200 int32_t MyOnError( 201 OH_AudioRenderer* renderer, 202 void* userData, 203 OH_AudioStream_Result error) 204 { 205 // 根据error表示的音频异常信息，做出相应的处理 206 return 0; 207 } 208 209 OH_AudioRenderer_Callbacks callbacks; 210 211 // 配置回调函数 212 callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData; 213 callbacks.OH_AudioRenderer_OnStreamEvent = MyOnStreamEvent; 214 callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent; 215 callbacks.OH_AudioRenderer_OnError = MyOnError; 216 217 // 设置输出音频流的回调 218 OH_AudioStreamBuilder_SetRendererCallback(builder, callbacks, nullptr); 219 ``` 220 221 为了避免不可预期的行为，在设置音频回调函数时，可以通过下面两种方式中的任意一种来设置音频回调函数： 222 223 - 请确保[OH_AudioRenderer_Callbacks](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_callbacks)的每一个回调都被**自定义的回调方法**或**空指针**初始化。 224 225 ```cpp 226 // 自定义写入数据函数 227 int32_t MyOnWriteData( 228 OH_AudioRenderer* renderer, 229 void* userData, 230 void* buffer, 231 int32_t length) 232 { 233 // 将待播放的数据，按length长度写入buffer 234 return 0; 235 } 236 // 自定义音频中断事件函数 237 int32_t MyOnInterruptEvent( 238 OH_AudioRenderer* renderer, 239 void* userData, 240 OH_AudioInterrupt_ForceType type, 241 OH_AudioInterrupt_Hint hint) 242 { 243 // 根据type和hint表示的音频中断信息，更新播放器状态和界面 244 return 0; 245 } 246 247 OH_AudioRenderer_Callbacks callbacks; 248 249 // 配置回调函数，如果需要监听，则赋值 250 callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData; 251 callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent; 252 253 // （必选）如果不需要监听，使用空指针初始化 254 callbacks.OH_AudioRenderer_OnStreamEvent = nullptr; 255 callbacks.OH_AudioRenderer_OnError = nullptr; 256 ``` 257 258 - 使用前，初始化并清零结构体。 259 260 ```cpp 261 // 自定义写入数据函数 262 int32_t MyOnWriteData( 263 OH_AudioRenderer* renderer, 264 void* userData, 265 void* buffer, 266 int32_t length) 267 { 268 // 将待播放的数据，按length长度写入buffer 269 return 0; 270 } 271 // 自定义音频中断事件函数 272 int32_t MyOnInterruptEvent( 273 OH_AudioRenderer* renderer, 274 void* userData, 275 OH_AudioInterrupt_ForceType type, 276 OH_AudioInterrupt_Hint hint) 277 { 278 // 根据type和hint表示的音频中断信息，更新播放器状态和界面 279 return 0; 280 } 281 OH_AudioRenderer_Callbacks callbacks; 282 283 // 使用前，初始化并清零结构体 284 memset(&callbacks, 0, sizeof(OH_AudioRenderer_Callbacks)); 285 286 // 配置需要的回调函数 287 callbacks.OH_AudioRenderer_OnWriteData = MyOnWriteData; 288 callbacks.OH_AudioRenderer_OnInterruptEvent = MyOnInterruptEvent; 289 ``` 290 2914. 构造播放音频流 292 293 ```cpp 294 OH_AudioRenderer* audioRenderer; 295 OH_AudioStreamBuilder_GenerateRenderer(builder, &audioRenderer); 296 ``` 297 2985. 使用音频流 299 300 音频流包含下面接口，用来实现对音频流的控制。 301 302 | 接口 | 说明 | 303 | ------------------------------------------------------------ | ------------ | 304 | OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer) | 开始播放 | 305 | OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer) | 暂停播放 | 306 | OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer) | 停止播放 | 307 | OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer) | 释放缓存数据 | 308 | OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer) | 释放播放实例 | 309 3106. 释放构造器 311 312 构造器不再使用时，需要释放相关资源。 313 314 ```cpp 315 OH_AudioStreamBuilder_Destroy(builder); 316 ``` 317 318## 设置音频流音量 319 320开发者可使用[OH_AudioRenderer_SetVolume](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiorenderer_setvolume)接口设置当前音频流音量值。 321 322开发示例 323 324```cpp 325// 要设置的音量值，音量值的范围是[0.0, 1.0] 326float volume = 0.5f; 327 328// 设置当前音频流音量值 329OH_AudioStream_Result OH_AudioRenderer_SetVolume(audioRenderer, volume); 330``` 331 332## 设置低时延模式 333 334当设备支持低时延通路时，开发者可以使用低时延模式创建播放器，获得更高质量的音频体验。 335 336开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetLatencyMode()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setlatencymode)设置低时延模式。 337 338> **注意：** 339> 当音频录制场景[OH_AudioStream_Usage](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostream_usage)为`AUDIOSTREAM_USAGE_VOICE_COMMUNICATION`和`AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION`时，不支持主动设置低时延模式，系统会根据设备的能力，决策输出的音频通路。 340 341开发示例 342 343```cpp 344OH_AudioStreamBuilder_SetLatencyMode(builder, AUDIOSTREAM_LATENCY_MODE_FAST); 345``` 346 347## 设置音频声道布局 348 349播放音频文件时，可以通过设置音频的声道布局信息，指定渲染或播放时的扬声器摆位，使得渲染和播放效果更佳，获得更高质量的音频体验。 350 351开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetChannelLayout()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setchannellayout)设置声道布局信息。 352 353当声道布局与声道数不匹配时，创建音频流会失败。建议在设置声道布局时，确认下发的声道布局信息是正确的。 354 355如果不知道准确的声道布局信息，或者开发者需要使用默认声道布局，可以不调用设置声道布局接口，或者下发CH_LAYOUT_UNKNOWN，以使用基于声道数的默认声道布局。 356 357对于HOA格式的音频，想要获得正确的渲染和播放效果，必须指定声道布局信息。 358 359开发示例 360 361```cpp 362OH_AudioStreamBuilder_SetChannelLayout(builder, CH_LAYOUT_STEREO); 363``` 364 365## 播放AudioVivid格式音源 366 367播放AudioVivid格式音频文件时，需要使用与普通播放不同的数据写入回调函数，该回调可以同时写入PCM数据与元数据。 368 369开发流程与普通播放场景一致，仅需要在创建音频流构造器时，调用[OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setwritedatawithmetadatacallback)设置PCM数据与元数据同时写入的回调函数，同时调用[OH_AudioStreamBuilder_SetEncodingType()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setencodingtype)设置编码类型为AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID。 370 371在播放AudioVivid时，帧长是固定的，不可通过[OH_AudioStreamBuilder_SetFrameSizeInCallback()](../../reference/apis-audio-kit/_o_h_audio.md#oh_audiostreambuilder_setframesizeincallback)设置回调帧长。同时，在设置播放声道数和声道布局时，需要将写入音源的声床数和对象数相加后进行设置。 372 373开发示例 374 375```cpp 376// 自定义同时写入PCM数据和元数据函数 377int32_t MyOnWriteDataWithMetadata( 378 OH_AudioRenderer* renderer, 379 void* userData, 380 void* audioData, 381 int32_t audioDataSize, 382 void* metadata, 383 int32_t metadataSize) 384{ 385 // 将待播放的PCM数据和元数据，分别按audioDataSize和metadataSize写入buffer 386 return 0; 387} 388 389// 设置编码类型 390OH_AudioStreamBuilder_SetEncodingType(builder, AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID); 391// 配置回调函数 392OH_AudioRenderer_WriteDataWithMetadataCallback metadataCallback = MyOnWriteDataWithMetadata; 393// 设置同时写入PCM数据和元数据的回调 394OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(builder, metadataCallback, nullptr); 395``` 396 397## 相关实例 398 399针对OHAudio开发音频播放，有以下相关实例可供参考： 400 401- [OHAudio录制和播放](https://gitee.com/openharmony/applications_app_samples/tree/master/code/DocsSample/Media/Audio/OHAudio) 402 403<!--RP1--> 404<!--RP1End-->
