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 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * Create a stremBuilder can be used to open a renderer or capturer client. 49 * 50 * OH_AudioStreamBuilder_Destroy() must be called when you are done using the builder. 51 * 52 * @since 10 53 * 54 * @param builder The builder reference to the created result. 55 * @param type The stream type to be created. {@link #AUDIOSTREAM_TYPE_RENDERER} or {@link #AUDIOSTREAM_TYPE_CAPTURER} 56 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 57 */ 58 OH_AudioStream_Result OH_AudioStreamBuilder_Create(OH_AudioStreamBuilder** builder, OH_AudioStream_Type type); 59 60 /** 61 * Destroy a streamBulder. 62 * 63 * This function must be called when you are done using the builder. 64 * 65 * @since 10 66 * 67 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 68 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 69 */ 70 OH_AudioStream_Result OH_AudioStreamBuilder_Destroy(OH_AudioStreamBuilder* builder); 71 72 /* 73 * Set the channel count of the capturer client 74 * 75 * @since 10 76 * 77 * @param capturer Reference created by OH_AudioStreamBuilder 78 * @param channelCount Pointer to a variable that will be set for the channel count. 79 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 80 */ 81 OH_AudioStream_Result OH_AudioStreamBuilder_SetSamplingRate(OH_AudioStreamBuilder* builder, int32_t rate); 82 83 /* 84 * Set the channel count of the stream client 85 * 86 * @since 10 87 * 88 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 89 * @param channelCount The channel count. 90 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 91 */ 92 OH_AudioStream_Result OH_AudioStreamBuilder_SetChannelCount(OH_AudioStreamBuilder* builder, int32_t channelCount); 93 94 /* 95 * Set the sample format of the stream client 96 * 97 * @since 10 98 * 99 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 100 * @param format Sample data format. 101 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 102 */ 103 OH_AudioStream_Result OH_AudioStreamBuilder_SetSampleFormat(OH_AudioStreamBuilder* builder, 104 OH_AudioStream_SampleFormat format); 105 106 /* 107 * Set the encoding type of the stream client 108 * 109 * @since 10 110 * 111 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 112 * @param encodingType Encoding type for the stream client, {@link #AUDIOSTREAM_ENCODING_PCM} 113 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 114 */ 115 OH_AudioStream_Result OH_AudioStreamBuilder_SetEncodingType(OH_AudioStreamBuilder* builder, 116 OH_AudioStream_EncodingType encodingType); 117 118 /* 119 * Set the latency mode of the stream client 120 * 121 * @since 10 122 * 123 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 124 * @param latencyMode Latency mode for the stream client. 125 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 126 */ 127 OH_AudioStream_Result OH_AudioStreamBuilder_SetLatencyMode(OH_AudioStreamBuilder* builder, 128 OH_AudioStream_LatencyMode latencyMode); 129 130 /** 131 * @brief Set the channel layout to the stream client 132 * 133 * @since 12 134 * 135 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 136 * @param channelLayout is the layout of the speaker. 137 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 138 */ 139 OH_AudioStream_Result OH_AudioStreamBuilder_SetChannelLayout(OH_AudioStreamBuilder* builder, 140 OH_AudioChannelLayout channelLayout); 141 142 /* 143 * Set the renderer information of the stream client 144 * 145 * @since 10 146 * 147 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 148 * @param usage Set the stream usage for the renderer client. 149 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 150 */ 151 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInfo(OH_AudioStreamBuilder* builder, 152 OH_AudioStream_Usage usage); 153 154 /* 155 * Set the renderer mode of the stream client 156 * 157 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 158 * @param volumeMode Set the stream volume mode for the renderer client. 159 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 160 */ 161 OH_AudioStream_Result OH_AudioStreamBuilder_SetVolumeMode(OH_AudioStreamBuilder* builder, 162 OH_AudioStream_VolumeMode volumeMode); 163 164 /* 165 * Set the capturer information of the stream client 166 * 167 * @since 10 168 * 169 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 170 * @param sourceType Set the source type for the capturer client. 171 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 172 */ 173 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerInfo(OH_AudioStreamBuilder* builder, 174 OH_AudioStream_SourceType sourceType); 175 176 /* 177 * Set the callbacks for the renderer client 178 * 179 * @since 10 180 * 181 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 182 * @param callbacks Callbacks to the functions that will process renderer stream. 183 * @param userData Pointer to an application data structure that will be passed to the callback functions. 184 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 185 */ 186 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererCallback(OH_AudioStreamBuilder* builder, 187 OH_AudioRenderer_Callbacks callbacks, void* userData); 188 189 /** 190 * @brief Set the callback when the output device of an audio renderer changed. 191 * 192 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 193 * @param callback Callback to the function that will process this device change event. 194 * @param userData Pointer to an application data structure that will be passed to the callback functions. 195 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 196 * @since 11 197 */ 198 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererOutputDeviceChangeCallback(OH_AudioStreamBuilder* builder, 199 OH_AudioRenderer_OutputDeviceChangeCallback callback, void* userData); 200 201 202 /* 203 * Set the callbacks for the capturer client 204 * 205 * @since 10 206 * 207 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 208 * @param callbacks Callbacks to the functions that will process capturer stream. 209 * @param userData Pointer to an application data structure that will be passed to the callback functions. 210 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 211 */ 212 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerCallback(OH_AudioStreamBuilder* builder, 213 OH_AudioCapturer_Callbacks callbacks, void* userData); 214 215 /* 216 * Create the audio renderer client. 217 * 218 * @since 10 219 * 220 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 221 * @param audioRenderer Pointer to a viriable to receive the stream client. 222 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 223 */ 224 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateRenderer(OH_AudioStreamBuilder* builder, 225 OH_AudioRenderer** audioRenderer); 226 /* 227 * Create the audio capturer client. 228 * 229 * @since 10 230 * 231 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 232 * @param audioCapturer Pointer to a viriable to receive the stream client. 233 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 234 */ 235 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateCapturer(OH_AudioStreamBuilder* builder, 236 OH_AudioCapturer** audioCapturer); 237 238 OH_AudioStream_Result OH_AudioStreamBuilder_SetFrameSizeInCallback(OH_AudioStreamBuilder* builder, 239 int32_t frameSize); 240 241 /* 242 * Set stream privacy type for plabck capture. 243 * 244 * @since 12 245 * 246 * @param builder Reference provided by OH_AudioStreamBuilder_Create(). 247 * @param privacy The privacy type to be set.{@link #AUDIO_STREAM_PRIVACY_TYPE_PUBLIC} or 248 * {@link #AUDIO_STREAM_PRIVACY_TYPE_PRIVATE}. 249 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 250 */ 251 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererPrivacy(OH_AudioStreamBuilder* builder, 252 OH_AudioStream_PrivacyType privacy); 253 254 /* 255 * Set the interrupt mode of the stream client 256 * 257 * @since 12 258 * 259 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 260 * @param mode The audio interrupt mode 261 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 262 */ 263 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInterruptMode(OH_AudioStreamBuilder* builder, 264 OH_AudioInterrupt_Mode mode); 265 266 /** 267 * @brief Set the callback of writing metadata to the renderer client 268 * 269 * @since 12 270 * 271 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 272 * @param callback Callback to the functions that will write audio data with metadata to the renderer. 273 * @param userData Pointer to an application data structure that will be passed to the callback functions. 274 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 275 */ 276 OH_AudioStream_Result OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(OH_AudioStreamBuilder* builder, 277 OH_AudioRenderer_WriteDataWithMetadataCallback callback, void* userData); 278 279 /** 280 * @brief Set the callback of writing data to renderer client. 281 * 282 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 283 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 284 * 285 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 286 * @param callback Callback to functions that will write audio data to renderer client. 287 * @param userData Pointer to an application data structure that will be passed to the callback functions. 288 * @return Result code. 289 * {@link AUDIOSTREAM_SUCCESS} Success. 290 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 291 * @since 12 292 */ 293 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererWriteDataCallback(OH_AudioStreamBuilder* builder, 294 OH_AudioRenderer_OnWriteDataCallback callback, void* userData); 295 296 /** 297 * @brief Set the callback of interrupt event to renderer client. 298 * 299 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 300 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 301 * 302 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 303 * @param callback Callback to functions that will inte to renderer client. 304 * @param userData Pointer to an application data structure that will be passed to the callback functions. 305 * @return Result code. 306 * {@link AUDIOSTREAM_SUCCESS} Success. 307 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 308 * @since 18 309 */ 310 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInterruptCallback(OH_AudioStreamBuilder* builder, 311 OH_AudioRenderer_OnInterruptCallback callback, void* userData); 312 313 /** 314 * @brief Set the callback of error code to renderer client. 315 * 316 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 317 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 318 * 319 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 320 * @param callback Callback to functions that will inte to renderer client. 321 * @param userData Pointer to an application data structure that will be passed to the callback functions. 322 * @return Result code. 323 * {@link AUDIOSTREAM_SUCCESS} Success. 324 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 325 * @since 18 326 */ 327 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererErrorCallback(OH_AudioStreamBuilder* builder, 328 OH_AudioRenderer_OnErrorCallback callback, void* userData); 329 330 /** 331 * @brief Set the callback of reading data to capturer client. 332 * 333 * This function is similar with {@link OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 334 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 335 * 336 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 337 * @param callback Callback to functions that will read audio data to capturer client. 338 * @param userData Pointer to an application data structure that will eb passed to the callback functions. 339 * @return Result code. 340 * {@link AUDIOSTREAM_SUCCESS} Success. 341 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 342 * @since 18 343 */ 344 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerReadDataCallback(OH_AudioStreamBuilder* builder, 345 OH_AudioCapturer_OnReadDataCallback callback, void* userData); 346 347 /** 348 * @brief Set the callback of stream event to capturer client. 349 * 350 * This function is similar with {@link OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 351 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 352 * 353 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 354 * @param callback Callback to functions that will handle audio capturer stream events to capturer client. 355 * @param userData Pointer to an application data structure that will eb passed to the callback functions. 356 * @return Result code. 357 * {@link AUDIOSTREAM_SUCCESS} Success. 358 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 359 * @since 18 360 */ 361 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerDeviceChangeCallback(OH_AudioStreamBuilder* builder, 362 OH_AudioCapturer_OnDeviceChangeCallback callback, void* userData); 363 364 /** 365 * @brief Callback function of interrupt event. 366 * 367 * This function is similar with {@OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 368 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 369 * 370 * @param builder builder provided by OH_AudioStreamBuilder_Create(). 371 * @param callback Callback to Function that will int to capturer client. 372 * @param userData User data which is passed by user. 373 * @return result code. 374 * @since 18 375 */ 376 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerInterruptCallback(OH_AudioStreamBuilder* builder, 377 OH_AudioCapturer_OnInterruptCallback callback, void* userData); 378 379 /** 380 * @brief Callback function of error event. 381 * 382 * This function is similar with {@OH_AudioStreamBuilder_SetCapturerCallback}. Only the last callback set by 383 * OH_AudioStreamBuilder_SetCapturerCallback or this function will become effective. 384 * 385 * @param builder builder provided by OH_AudioStreamBuilder_Create(). 386 * @param callback Callback to Function that will int to capturer client. 387 * @param userData User data which is passed by user. 388 * @return result code. 389 * @since 18 390 */ 391 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerErrorCallback(OH_AudioStreamBuilder* builder, 392 OH_AudioCapturer_OnErrorCallback callback, void* userData); 393 #ifdef __cplusplus 394 } 395 #endif 396 397 #endif // NATIVE_AUDIOSTREAM_BUILDER_H 398