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