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
46extern "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 */
61OH_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 */
76OH_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 */
91OH_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 */
106OH_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 */
119OH_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 */
133OH_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 */
147OH_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 */
161OH_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 */
177OH_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 */
193OH_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 */
210OH_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 */
227OH_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 */
243OH_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 */
260OH_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 */
277OH_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 */
294OH_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 */
311OH_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 */
328OH_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 */
345OH_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 */
362OH_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