1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audiostreambuilder.h 30 * 31 * @brief Declare audio stream builder related interfaces. 32 * 33 * @syscap SystemCapability.Multimedia.Audio.Core 34 * @since 10 35 * @version 1.0 36 */ 37 38 #ifndef NATIVE_AUDIOSTREAM_BUILDER_H 39 #define NATIVE_AUDIOSTREAM_BUILDER_H 40 41 #include "native_audiostream_base.h" 42 #include "native_audiorenderer.h" 43 #include "native_audiocapturer.h" 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * Create a stremBuilder can be used to open a renderer or capturer client. 50 * 51 * OH_AudioStreamBuilder_Destroy() must be called when you are done using the builder. 52 * 53 * @since 10 54 * 55 * @param builder The builder reference to the created result. 56 * @param type The stream type to be created. {@link #AUDIOSTREAM_TYPE_RENDERER} or {@link #AUDIOSTREAM_TYPE_CAPTURER} 57 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 58 */ 59 OH_AudioStream_Result OH_AudioStreamBuilder_Create(OH_AudioStreamBuilder** builder, OH_AudioStream_Type type); 60 61 /** 62 * Destroy a streamBulder. 63 * 64 * This function must be called when you are done using the builder. 65 * 66 * @since 10 67 * 68 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 69 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 70 */ 71 OH_AudioStream_Result OH_AudioStreamBuilder_Destroy(OH_AudioStreamBuilder* builder); 72 73 /* 74 * Set the channel count of the capturer client 75 * 76 * @since 10 77 * 78 * @param capturer Reference created by OH_AudioStreamBuilder 79 * @param channelCount Pointer to a variable that will be set for the channel count. 80 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 81 */ 82 OH_AudioStream_Result OH_AudioStreamBuilder_SetSamplingRate(OH_AudioStreamBuilder* builder, int32_t rate); 83 84 /* 85 * Set the channel count of the stream client 86 * 87 * @since 10 88 * 89 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 90 * @param channelCount The channel count. 91 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 92 */ 93 OH_AudioStream_Result OH_AudioStreamBuilder_SetChannelCount(OH_AudioStreamBuilder* builder, int32_t channelCount); 94 95 /* 96 * Set the sample format of the stream client 97 * 98 * @since 10 99 * 100 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 101 * @param format Sample data format. 102 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 103 */ 104 OH_AudioStream_Result OH_AudioStreamBuilder_SetSampleFormat(OH_AudioStreamBuilder* builder, 105 OH_AudioStream_SampleFormat format); 106 107 /* 108 * Set the encoding type of the stream client 109 * 110 * @since 10 111 * 112 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 113 * @param encodingType Encoding type for the stream client, {@link #AUDIOSTREAM_ENCODING_PCM} 114 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 115 */ 116 OH_AudioStream_Result OH_AudioStreamBuilder_SetEncodingType(OH_AudioStreamBuilder* builder, 117 OH_AudioStream_EncodingType encodingType); 118 119 /* 120 * Set the latency mode of the stream client 121 * 122 * @since 10 123 * 124 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 125 * @param latencyMode Latency mode for the stream client. 126 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 127 */ 128 OH_AudioStream_Result OH_AudioStreamBuilder_SetLatencyMode(OH_AudioStreamBuilder* builder, 129 OH_AudioStream_LatencyMode latencyMode); 130 131 /** 132 * @brief Set the channel layout to the stream client 133 * 134 * @since 12 135 * 136 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 137 * @param channelLayout is the layout of the speaker. 138 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 139 */ 140 OH_AudioStream_Result OH_AudioStreamBuilder_SetChannelLayout(OH_AudioStreamBuilder* builder, 141 OH_AudioChannelLayout channelLayout); 142 143 /* 144 * Set the renderer information of the stream client 145 * 146 * @since 10 147 * 148 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 149 * @param usage Set the stream usage for the renderer client. 150 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 151 */ 152 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInfo(OH_AudioStreamBuilder* builder, 153 OH_AudioStream_Usage usage); 154 155 /* 156 * Set the renderer mode of the stream client 157 * 158 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 159 * @param volumeMode Set the stream volume mode for the renderer client. 160 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 161 */ 162 OH_AudioStream_Result OH_AudioStreamBuilder_SetVolumeMode(OH_AudioStreamBuilder* builder, 163 OH_AudioStream_VolumeMode volumeMode); 164 165 /* 166 * Set the capturer information of the stream client 167 * 168 * @since 10 169 * 170 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 171 * @param sourceType Set the source type for the capturer client. 172 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 173 */ 174 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerInfo(OH_AudioStreamBuilder* builder, 175 OH_AudioStream_SourceType sourceType); 176 177 /* 178 * Set the callbacks for the renderer client 179 * 180 * @deprecated since 18 181 * @useinstead Set the callback functions separately using OH_AudioStreamBuilder_SetRendererWriteDataCallback, 182 * OH_AudioStreamBuilder_SetRendererInterruptCallback, OH_AudioStreamBuilder_SetRendererOutputDeviceChangeCallback 183 * and OH_AudioStreamBuilder_SetRendererErrorCallback. 184 * @since 10 185 * 186 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 187 * @param callbacks Callbacks to the functions that will process renderer stream. 188 * @param userData Pointer to an application data structure that will be passed to the callback functions. 189 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 190 */ 191 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererCallback(OH_AudioStreamBuilder* builder, 192 OH_AudioRenderer_Callbacks callbacks, void* userData); 193 194 /** 195 * @brief Set the callback when the output device of an audio renderer changed. 196 * 197 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 198 * @param callback Callback to the function that will process this device change event. 199 * @param userData Pointer to an application data structure that will be passed to the callback functions. 200 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 201 * @since 11 202 */ 203 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererOutputDeviceChangeCallback(OH_AudioStreamBuilder* builder, 204 OH_AudioRenderer_OutputDeviceChangeCallback callback, void* userData); 205 206 207 /* 208 * Set the callbacks for the capturer client 209 * 210 * @deprecated since 18 211 * @useinstead Set the callback functions separately using OH_AudioStreamBuilder_SetCapturerReadDataCallback, 212 * OH_AudioStreamBuilder_SetCapturerDeviceChangeCallback, OH_AudioStreamBuilder_SetCapturerInterruptCallback 213 * and OH_AudioStreamBuilder_SetCapturerErrorCallback. 214 * @since 10 215 * 216 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 217 * @param callbacks Callbacks to the functions that will process capturer stream. 218 * @param userData Pointer to an application data structure that will be passed to the callback functions. 219 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 220 */ 221 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerCallback(OH_AudioStreamBuilder* builder, 222 OH_AudioCapturer_Callbacks callbacks, void* userData); 223 224 /* 225 * Create the audio renderer client. 226 * 227 * @since 10 228 * 229 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 230 * @param audioRenderer Pointer to a viriable to receive the stream client. 231 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 232 */ 233 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateRenderer(OH_AudioStreamBuilder* builder, 234 OH_AudioRenderer** audioRenderer); 235 /* 236 * Create the audio capturer client. 237 * 238 * @since 10 239 * 240 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 241 * @param audioCapturer Pointer to a viriable to receive the stream client. 242 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 243 */ 244 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateCapturer(OH_AudioStreamBuilder* builder, 245 OH_AudioCapturer** audioCapturer); 246 247 OH_AudioStream_Result OH_AudioStreamBuilder_SetFrameSizeInCallback(OH_AudioStreamBuilder* builder, 248 int32_t frameSize); 249 250 /* 251 * Set stream privacy type for plabck capture. 252 * 253 * @since 12 254 * 255 * @param builder Reference provided by OH_AudioStreamBuilder_Create(). 256 * @param privacy The privacy type to be set.{@link #AUDIO_STREAM_PRIVACY_TYPE_PUBLIC} or 257 * {@link #AUDIO_STREAM_PRIVACY_TYPE_PRIVATE}. 258 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 259 */ 260 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererPrivacy(OH_AudioStreamBuilder* builder, 261 OH_AudioStream_PrivacyType privacy); 262 263 /* 264 * Set the interrupt mode of the stream client 265 * 266 * @since 12 267 * 268 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 269 * @param mode The audio interrupt mode 270 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 271 */ 272 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInterruptMode(OH_AudioStreamBuilder* builder, 273 OH_AudioInterrupt_Mode mode); 274 275 /** 276 * @brief Set the callback of writing metadata to the renderer client 277 * 278 * @since 12 279 * 280 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 281 * @param callback Callback to the functions that will write audio data with metadata to the renderer. 282 * @param userData Pointer to an application data structure that will be passed to the callback functions. 283 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 284 */ 285 OH_AudioStream_Result OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(OH_AudioStreamBuilder* builder, 286 OH_AudioRenderer_WriteDataWithMetadataCallback callback, void* userData); 287 288 /** 289 * @brief Set the callback of writing data to renderer client. 290 * 291 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 292 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 293 * 294 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 295 * @param callback Callback to functions that will write audio data to renderer client. 296 * @param userData Pointer to an application data structure that will be passed to the callback functions. 297 * @return Result code. 298 * {@link AUDIOSTREAM_SUCCESS} Success. 299 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 300 * @since 12 301 */ 302 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererWriteDataCallback(OH_AudioStreamBuilder* builder, 303 OH_AudioRenderer_OnWriteDataCallback callback, void* userData); 304 305 /** 306 * @brief Set the callback of writing data to renderer client. 307 * 308 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererWriteDataCallback}. Only the last callback set 309 * by OH_AudioStreamBuilder_SetRendererWriteDataCallback or this function will become effective. Different with 310 * OH_AudioStreamBuilder_SetRendererWriteDataCallback, the callback in this function can return audio data of any 311 * length. 312 * 313 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 314 * @param callback Callback to functions that will write audio data to renderer client. 315 * @param userData Pointer to an application data structure that will be passed to the callback functions. 316 * @return Result code. 317 * {@link AUDIOSTREAM_SUCCESS} Success. 318 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 319 * @since 20 320 */ 321 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererWriteDataCallbackAdvanced(OH_AudioStreamBuilder* builder, 322 OH_AudioRenderer_OnWriteDataCallbackAdvanced callback, void* userData); 323 324 /** 325 * @brief Set the callback of interrupt event to renderer client. 326 * 327 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 328 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 329 * 330 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 331 * @param callback Callback to functions that will inte to renderer client. 332 * @param userData Pointer to an application data structure that will be passed to the callback functions. 333 * @return Result code. 334 * {@link AUDIOSTREAM_SUCCESS} Success. 335 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 336 * @since 18 337 */ 338 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInterruptCallback(OH_AudioStreamBuilder* builder, 339 OH_AudioRenderer_OnInterruptCallback callback, void* userData); 340 341 /** 342 * @brief Set the callback of error code to renderer client. 343 * 344 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 345 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 346 * 347 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 348 * @param callback Callback to functions that will inte to renderer client. 349 * @param userData Pointer to an application data structure that will be passed to the callback functions. 350 * @return Result code. 351 * {@link AUDIOSTREAM_SUCCESS} Success. 352 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 353 * @since 18 354 */ 355 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererErrorCallback(OH_AudioStreamBuilder* builder, 356 OH_AudioRenderer_OnErrorCallback callback, void* userData); 357 358 /** 359 * @brief Set the callback of reading data to capturer client. 360 * 361 * This function is similar with {@link OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 362 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 363 * 364 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 365 * @param callback Callback to functions that will read audio data to capturer client. 366 * @param userData Pointer to an application data structure that will eb passed to the callback functions. 367 * @return Result code. 368 * {@link AUDIOSTREAM_SUCCESS} Success. 369 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 370 * @since 18 371 */ 372 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerReadDataCallback(OH_AudioStreamBuilder* builder, 373 OH_AudioCapturer_OnReadDataCallback callback, void* userData); 374 375 /** 376 * @brief Set the callback of stream event to capturer client. 377 * 378 * This function is similar with {@link OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 379 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 380 * 381 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 382 * @param callback Callback to functions that will handle audio capturer stream events to capturer client. 383 * @param userData Pointer to an application data structure that will eb passed to the callback functions. 384 * @return Result code. 385 * {@link AUDIOSTREAM_SUCCESS} Success. 386 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 387 * @since 18 388 */ 389 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerDeviceChangeCallback(OH_AudioStreamBuilder* builder, 390 OH_AudioCapturer_OnDeviceChangeCallback callback, void* userData); 391 392 /** 393 * @brief Callback function of interrupt event. 394 * 395 * This function is similar with {@OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 396 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 397 * 398 * @param builder builder provided by OH_AudioStreamBuilder_Create(). 399 * @param callback Callback to Function that will int to capturer client. 400 * @param userData User data which is passed by user. 401 * @return result code. 402 * @since 18 403 */ 404 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerInterruptCallback(OH_AudioStreamBuilder* builder, 405 OH_AudioCapturer_OnInterruptCallback callback, void* userData); 406 407 /** 408 * @brief Callback function of error event. 409 * 410 * This function is similar with {@OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 411 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 412 * 413 * @param builder builder provided by OH_AudioStreamBuilder_Create(). 414 * @param callback Callback to Function that will int to capturer client. 415 * @param userData User data which is passed by user. 416 * @return result code. 417 * @since 18 418 */ 419 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerErrorCallback(OH_AudioStreamBuilder* builder, 420 OH_AudioCapturer_OnErrorCallback callback, void* userData); 421 422 /** 423 * @brief Set audio capturer configuration, if app want its recorder only to be muted instead of interrupted. 424 * 425 * @param builder reference provided by OH_AudioStreamBuilder_Create() 426 * @param muteWhenInterrupted use {@code true} if application want to be muted instead of interrupted. 427 * @return function result code: 428 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 429 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of builder is nullptr. 430 * @since 20 431 */ 432 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerWillMuteWhenInterrupted(OH_AudioStreamBuilder* builder, 433 bool muteWhenInterrupted); 434 435 /** 436 * @brief Set the callback of fast status change event for audio renderer. 437 * 438 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 439 * @param callback Callback function that will recevie the fast status change event. 440 * @param userData Pointer to an application data structure that will be passed to the callback functions. 441 * @return 442 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 443 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of builder or callback is nullptr. 444 * @since 20 445 */ 446 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererFastStatusChangeCallback(OH_AudioStreamBuilder* builder, 447 OH_AudioRenderer_OnFastStatusChange callback, void* userData); 448 449 /** 450 * @brief Set the callback of fast status change event for audio capturer. 451 * 452 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 453 * @param callback Callback function that will recevie the fast status change event. 454 * @param userData Pointer to an application data structure that will be passed to the callback functions. 455 * @return 456 * {@link AUDIOSTREAM_SUCCESS} if the execution is successful. 457 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} the param of builder or callback is nullptr. 458 * @since 20 459 */ 460 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerFastStatusChangeCallback(OH_AudioStreamBuilder* builder, 461 OH_AudioCapturer_OnFastStatusChange callback, void* userData); 462 463 #ifdef __cplusplus 464 } 465 #endif 466 467 #endif // NATIVE_AUDIOSTREAM_BUILDER_H 468