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