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 capturer information of the stream client 156 * 157 * @since 10 158 * 159 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 160 * @param sourceType Set the source type for the capturer client. 161 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 162 */ 163 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerInfo(OH_AudioStreamBuilder* builder, 164 OH_AudioStream_SourceType sourceType); 165 166 /* 167 * Set the callbacks for the renderer client 168 * 169 * @since 10 170 * 171 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 172 * @param callbacks Callbacks to the functions that will process renderer stream. 173 * @param userData Pointer to an application data structure that will be passed to the callback functions. 174 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 175 */ 176 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererCallback(OH_AudioStreamBuilder* builder, 177 OH_AudioRenderer_Callbacks callbacks, void* userData); 178 179 /** 180 * @brief Set the callback when the output device of an audio renderer changed. 181 * 182 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 183 * @param callback Callback to the function that will process this device change event. 184 * @param userData Pointer to an application data structure that will be passed to the callback functions. 185 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 186 * @since 11 187 */ 188 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererOutputDeviceChangeCallback(OH_AudioStreamBuilder* builder, 189 OH_AudioRenderer_OutputDeviceChangeCallback callback, void* userData); 190 191 192 /* 193 * Set the callbacks for the capturer client 194 * 195 * @since 10 196 * 197 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 198 * @param callbacks Callbacks to the functions that will process capturer stream. 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 */ 202 OH_AudioStream_Result OH_AudioStreamBuilder_SetCapturerCallback(OH_AudioStreamBuilder* builder, 203 OH_AudioCapturer_Callbacks callbacks, void* userData); 204 205 /* 206 * Create the audio renderer client. 207 * 208 * @since 10 209 * 210 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 211 * @param audioRenderer Pointer to a viriable to receive the stream client. 212 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 213 */ 214 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateRenderer(OH_AudioStreamBuilder* builder, 215 OH_AudioRenderer** audioRenderer); 216 /* 217 * Create the audio capturer client. 218 * 219 * @since 10 220 * 221 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 222 * @param audioCapturer Pointer to a viriable to receive the stream client. 223 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 224 */ 225 OH_AudioStream_Result OH_AudioStreamBuilder_GenerateCapturer(OH_AudioStreamBuilder* builder, 226 OH_AudioCapturer** audioCapturer); 227 228 OH_AudioStream_Result OH_AudioStreamBuilder_SetFrameSizeInCallback(OH_AudioStreamBuilder* builder, 229 int32_t frameSize); 230 231 /* 232 * Set stream privacy type for plabck capture. 233 * 234 * @since 12 235 * 236 * @param builder Reference provided by OH_AudioStreamBuilder_Create(). 237 * @param privacy The privacy type to be set.{@link #AUDIO_STREAM_PRIVACY_TYPE_PUBLIC} or 238 * {@link #AUDIO_STREAM_PRIVACY_TYPE_PRIVATE}. 239 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 240 */ 241 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererPrivacy(OH_AudioStreamBuilder* builder, 242 OH_AudioStream_PrivacyType privacy); 243 244 /* 245 * Set the interrupt mode of the stream client 246 * 247 * @since 12 248 * 249 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 250 * @param mode The audio interrupt mode 251 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 252 */ 253 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererInterruptMode(OH_AudioStreamBuilder* builder, 254 OH_AudioInterrupt_Mode mode); 255 256 /** 257 * @brief Set the callback of writing metadata to the renderer client 258 * 259 * @since 12 260 * 261 * @param builder Reference provided by OH_AudioStreamBuilder_Create() 262 * @param callback Callback to the functions that will write audio data with metadata to the renderer. 263 * @param userData Pointer to an application data structure that will be passed to the callback functions. 264 * @return {@link #AUDIOSTREAM_SUCCESS} or an undesired error. 265 */ 266 OH_AudioStream_Result OH_AudioStreamBuilder_SetWriteDataWithMetadataCallback(OH_AudioStreamBuilder* builder, 267 OH_AudioRenderer_WriteDataWithMetadataCallback callback, void* userData); 268 269 /** 270 * @brief Set the callback of writing data to renderer client. 271 * 272 * This function is similar with {@link OH_AudioStreamBuilder_SetRendererCallback}. Only the last callback set by 273 * OH_AudioStreamBuilder_SetRendererCallback or this function will become effective. 274 * 275 * @param builder Builder provided by OH_AudioStreamBuilder_Create() 276 * @param callback Callback to functions that will write audio data to renderer client. 277 * @param userData Pointer to an application data structure that will be passed to the callback functions. 278 * @return Result code. 279 * {@link AUDIOSTREAM_SUCCESS} Success. 280 * {@link AUDIOSTREAM_ERROR_INVALID_PARAM} Parameter is invalid, e.g. builder is nullptr, e.t.c. 281 * @since 12 282 */ 283 OH_AudioStream_Result OH_AudioStreamBuilder_SetRendererWriteDataCallback(OH_AudioStreamBuilder* builder, 284 OH_AudioRenderer_OnWriteDataCallback callback, void* userData); 285 #ifdef __cplusplus 286 } 287 #endif 288 289 #endif // NATIVE_AUDIOSTREAM_BUILDER_H 290