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_audiorenderer.h
30  *
31  * @brief Declare audio stream related interfaces for output type.
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_AUDIORENDERER_H
41 #define NATIVE_AUDIORENDERER_H
42 
43 #include <stdbool.h>
44 #include <time.h>
45 #include "native_audiostream_base.h"
46 #include "native_audio_device_base.h"
47 #include "multimedia/native_audio_channel_layout.h"
48 #ifdef __cplusplus
49 extern "C" {
50 #endif
51 /*
52  * Request to release the renderer stream.
53  *
54  * @since 10
55  *
56  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
57  * @return Function result code:
58  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
59  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
60  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
61  */
62 OH_AudioStream_Result OH_AudioRenderer_Release(OH_AudioRenderer* renderer);
63 
64 /*
65  * Request to start the renderer stream.
66  *
67  * @since 10
68  *
69  * @param renderer reference created by OH_AudioStreamBuilder
70  * @return Function result code:
71  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
72  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
73  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
74  */
75 OH_AudioStream_Result OH_AudioRenderer_Start(OH_AudioRenderer* renderer);
76 
77 /*
78  * Request to pause the renderer stream.
79  *
80  * @since 10
81  *
82  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
83  * @return Function result code:
84  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
85  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
86  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
87  */
88 OH_AudioStream_Result OH_AudioRenderer_Pause(OH_AudioRenderer* renderer);
89 
90 /*
91  * Request to stop renderer stream.
92  *
93  * @since 10
94  *
95  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
96  * @return Function result code:
97  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
98  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
99  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
100  */
101 OH_AudioStream_Result OH_AudioRenderer_Stop(OH_AudioRenderer* renderer);
102 
103 /*
104  * Request to flush the renderer stream.
105  *
106  * @since 10
107  *
108  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
109  * @return Function result code:
110  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
111  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
112  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
113  */
114 OH_AudioStream_Result OH_AudioRenderer_Flush(OH_AudioRenderer* renderer);
115 
116 /*
117  * Query the current state of the renderer client.
118  *
119  * This function will return the renderer state without updating the state.
120  *
121  * @since 10
122  *
123  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
124  * @param state Pointer to a variable that will be set for the state value.
125  * @return Function result code:
126  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
127  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
128  */
129 OH_AudioStream_Result OH_AudioRenderer_GetCurrentState(OH_AudioRenderer* renderer,
130     OH_AudioStream_State* state);
131 
132 /*
133  * Query the sample rate value of the renderer client
134  *
135  * This function will return the renderer sample rate value without updating the state.
136  *
137  * @since 10
138  *
139  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
140  * @param rate The state value to be updated
141  * @return Function result code:
142  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
143  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
144  */
145 OH_AudioStream_Result OH_AudioRenderer_GetSamplingRate(OH_AudioRenderer* renderer, int32_t* rate);
146 
147 /*
148  * Query the stream id of the renderer client.
149  *
150  * @since 10
151  *
152  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
153  * @param stramId Pointer to a variable that will be set for the stream id.
154  * @return Function result code:
155  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
156  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
157  */
158 OH_AudioStream_Result OH_AudioRenderer_GetStreamId(OH_AudioRenderer* renderer, uint32_t* streamId);
159 
160 /*
161  * Query the channel count of the renderer client.
162  *
163  * @since 10
164  *
165  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
166  * @param channelCount Pointer to a variable that will be set for the channel count.
167  * @return Function result code:
168  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
169  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
170  */
171 OH_AudioStream_Result OH_AudioRenderer_GetChannelCount(OH_AudioRenderer* renderer, int32_t* channelCount);
172 
173 /*
174  * Query the sample format of the renderer client.
175  *
176  * @since 10
177  *
178  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
179  * @param sampleFormat Pointer to a variable that will be set for the sample format.
180  * @return Function result code:
181  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
182  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
183  */
184 OH_AudioStream_Result OH_AudioRenderer_GetSampleFormat(OH_AudioRenderer* renderer,
185     OH_AudioStream_SampleFormat* sampleFormat);
186 
187 /*
188  * Query the latency mode of the renderer client.
189  *
190  * @since 10
191  *
192  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
193  * @param latencyMode Pointer to a variable that will be set for the latency mode.
194  * @return Function result code:
195  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
196  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
197  */
198 OH_AudioStream_Result OH_AudioRenderer_GetLatencyMode(OH_AudioRenderer* renderer,
199     OH_AudioStream_LatencyMode* latencyMode);
200 /*
201  * Query the renderer info of the renderer client.
202  *
203  * The rendere info includes {@link OH_AudioStream_Usage} value.
204  *
205  * @since 10
206  *
207  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
208  * @param usage Pointer to a variable that will be set for the stream usage.
209  * @return Function result code:
210  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
211  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
212  */
213 OH_AudioStream_Result OH_AudioRenderer_GetRendererInfo(OH_AudioRenderer* renderer,
214     OH_AudioStream_Usage* usage);
215 
216 /*
217  * Query the encoding type of the renderer client.
218  *
219  * @since 10
220  *
221  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
222  * @param encodingType Pointer to a variable that will be set for the encoding type.
223  * @return Function result code:
224  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
225  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
226  */
227 OH_AudioStream_Result OH_AudioRenderer_GetEncodingType(OH_AudioRenderer* renderer,
228     OH_AudioStream_EncodingType* encodingType);
229 
230 /*
231  * Query the the number of frames that have been written since the stream was created.
232  *
233  * @since 10
234  *
235  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
236  * @param frames Pointer to a variable that will be set for the frame count number.
237  * @return Function result code:
238  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
239  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
240  */
241 OH_AudioStream_Result OH_AudioRenderer_GetFramesWritten(OH_AudioRenderer* renderer, int64_t* frames);
242 
243 /*
244  * Query the the time at which a particular frame was presented.
245  *
246  * @since 10
247  *
248  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
249  * @param clockId {@link #CLOCK_MONOTONIC}
250  * @param framePosition Pointer to a variable to receive the position
251  * @param timestamp Pointer to a variable to receive the timestamp
252  * @return Function result code:
253  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
254  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
255  *                                                 1.The param of renderer is nullptr;
256  *                                                 2.The param of clockId invalid.
257  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
258  */
259 OH_AudioStream_Result OH_AudioRenderer_GetTimestamp(OH_AudioRenderer* renderer,
260     clockid_t clockId, int64_t* framePosition, int64_t* timestamp);
261 
262 /*
263  * Query the frame size in callback, it is a fixed length that the stream want to be filled for each callback.
264  *
265  * @since 10
266  *
267  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
268  * @param frameSize Pointer to a variable that will be set for the frame size.
269  * @return Function result code:
270  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
271  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
272  */
273 OH_AudioStream_Result OH_AudioRenderer_GetFrameSizeInCallback(OH_AudioRenderer* renderer, int32_t* frameSize);
274 
275 /*
276  * Query the playback speed of the stream client
277  *
278  * @since 11
279  *
280  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
281  * @param speed Pointer to a variable to receive the playback speed.
282  * @return Function result code:
283  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
284  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
285  */
286 OH_AudioStream_Result OH_AudioRenderer_GetSpeed(OH_AudioRenderer* renderer, float* speed);
287 
288 
289 /*
290  * Set the playback speed of the stream client
291  *
292  * @since 11
293  *
294  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
295  * @param speed The playback speed, form 0.25 to 4.0.
296  * @return Function result code:
297  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
298  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
299  */
300 OH_AudioStream_Result OH_AudioRenderer_SetSpeed(OH_AudioRenderer* renderer, float speed);
301 
302 /**
303  * Set volume of current renderer.
304  *
305  * @since 12
306  *
307  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
308  * @param volume Volume to set which changes from 0.0 to 1.0.
309  * @return Function result code:
310  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
311  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
312  *                                                 1.The param of renderer is nullptr;
313  *                                                 2.The param of volume invalid.
314  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
315  *         {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred.
316  */
317 OH_AudioStream_Result OH_AudioRenderer_SetVolume(OH_AudioRenderer* renderer, float volume);
318 
319 /**
320  * Changes the volume with ramp for a duration.
321  *
322  * @since 12
323  *
324  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
325  * @param volume Volume to set which changes from 0.0 to 1.0.
326  * @param durationMs Duration for volume ramp, in millisecond.
327  * @return Function result code:
328  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
329  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
330  *                                                 1.The param of renderer is nullptr;
331  *                                                 2.The param of volume invalid.
332  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
333  *         {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred.
334  */
335 OH_AudioStream_Result OH_AudioRenderer_SetVolumeWithRamp(OH_AudioRenderer* renderer, float volume, int32_t durationMs);
336 
337 /**
338  * Get Volume of current renderer.
339  *
340  * @since 12
341  *
342  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
343  * @param volume Pointer to a variable to receive the volume.
344  * @return Function result code:
345  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
346  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
347  *                                                 1.The param of renderer is nullptr;
348  *                                                 2.The param of volume is nullptr.
349  */
350 OH_AudioStream_Result OH_AudioRenderer_GetVolume(OH_AudioRenderer* renderer, float* volume);
351 
352 /**
353  * @brief Set mark position on current renderer. Calling this function will overwrite the mark postion which has already
354  * set.
355  *
356  * @since 12
357  *
358  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
359  * @param samplePos Mark position in samples.
360  * @param callback Callback used when the samplePos has reached.
361  * @param userData User data which is passed by user.
362  * @return Function result code:
363  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
364  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
365  *                                                 1.The param of renderer is nullptr;
366  *                                                 2.The param of samplePos invalid.
367  *         {@link AUDIOSTREAM_ERROR_ILLEGAL_STATE} Execution status exception.
368  *         {@link AUDIOSTREAM_ERROR_SYSTEM} An system error has occurred.
369  */
370 OH_AudioStream_Result OH_AudioRenderer_SetMarkPosition(OH_AudioRenderer* renderer, uint32_t samplePos,
371     OH_AudioRenderer_OnMarkReachedCallback callback, void* userData);
372 
373 /**
374  * @brief Cancel mark which has set by {@link #OH_AudioRenderer_SetMarkPosition}.
375  *
376  * @since 12
377  *
378  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
379  * @return Function result code:
380  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
381  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
382  */
383 OH_AudioStream_Result OH_AudioRenderer_CancelMark(OH_AudioRenderer* renderer);
384 
385 /**
386  * @brief Gets the underflow count on this stream.
387  *
388  * @since 12
389  *
390  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
391  * @param count Pointer to a variable to receive the underflow count number.
392  * @return Function result code:
393  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
394  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM}:
395  *                                                 1.The param of renderer is nullptr;
396  *                                                 2.The param of count is nullptr.
397  */
398 OH_AudioStream_Result OH_AudioRenderer_GetUnderflowCount(OH_AudioRenderer* renderer, uint32_t* count);
399 
400 /**
401  * @brief Query the channel layout of the renderer client.
402  *
403  * @since 12
404  *
405  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
406  * @param channelLayout Pointer to a variable to receive the channel layout
407  * @return Function result code:
408  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
409  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
410  */
411 OH_AudioStream_Result OH_AudioRenderer_GetChannelLayout(OH_AudioRenderer* renderer,
412     OH_AudioChannelLayout* channelLayout);
413 
414 /**
415  * @brief Query current audio effect mode.
416  *
417  * @since 12
418  *
419  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
420  * @param effectMode Pointer to a variable to receive current audio effect mode
421  * @return Function result code:
422  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
423  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
424  */
425 OH_AudioStream_Result OH_AudioRenderer_GetEffectMode(OH_AudioRenderer* renderer,
426     OH_AudioStream_AudioEffectMode* effectMode);
427 
428 /**
429  * @brief Set current audio effect mode.
430  *
431  * @since 12
432  *
433  * @param renderer Reference created by OH_AudioStreamBuilder_GenerateRenderer()
434  * @param effectMode Audio effect mode that will be set for the stream
435  * @return Function result code:
436  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
437  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
438  */
439 OH_AudioStream_Result OH_AudioRenderer_SetEffectMode(OH_AudioRenderer* renderer,
440     OH_AudioStream_AudioEffectMode effectMode);
441 
442 /**
443  * @brief Get the privacy of this stream.
444  *
445  * @since 12
446  *
447  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
448  * @param privacy Pointer to a variable which receives the results.
449  * @return Function result code:
450  *         {@link AUDIOSTREAM_SUCCESS} If the execution is successful.
451  *         {@link AUDIOSTREAM_ERROR_INVALID_PARAM} The param of renderer is nullptr.
452  */
453 OH_AudioStream_Result OH_AudioRenderer_GetRendererPrivacy(OH_AudioRenderer* renderer,
454     OH_AudioStream_PrivacyType* privacy);
455 
456 /**
457  * @brief Set silent and mix with other streams for this stream.
458  *
459  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
460  * @param on The silent and mix with other streams mode.
461  *     true: set the slient mode and mix with other streams.
462  *     false: unset the slient mode, current stream will trigger the audio focus internally.
463  * @return result code for this function.
464  *     {@link #AUDIOSTREAM_SUCCESS} succeed in setting to the silent and mix with other streams.
465  *     {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} this stream is not allowed to set/unset the silent mode.
466  * @since 12
467  */
468 OH_AudioStream_Result OH_AudioRenderer_SetSilentModeAndMixWithOthers(
469     OH_AudioRenderer* renderer, bool on);
470 
471 /**
472  * @brief Query silent and mix with other streams status for this stream.
473  *
474  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
475  * @param on Pointer to the silent and mix with other streams status.
476  * @return result code for this function.
477  *     {@link #AUDIOSTREAM_SUCCESS} succeed in getting silent and mix with other streams status
478  *     {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function.
479  * @since 12
480  */
481 OH_AudioStream_Result OH_AudioRenderer_GetSilentModeAndMixWithOthers(
482     OH_AudioRenderer* renderer, bool* on);
483 
484 /**
485  * @brief Temporarily changes the current audio device
486  *        This function applys on audiorenderers whose StreamUsage are
487  *        STREAM_USAGE_VOICE_COMMUNICATIN/STREAM_USAGE_VIDEO_COMMUNICATION/STREAM_USAGE_VOICE_MESSAGE.
488  *        Setting the device will only takes effect if no other accessory such as headphones are in use.
489  *
490  * @param renderer Renderer generated by OH_AudioStreamBuilder_GenerateRenderer()
491  * @param deviceType The target device. The available deviceTypes are:
492  *                                             EARPIECE: Built-in earpiece
493  *                                             SPEAKER: Built-in speaker
494  *                                             DEFAULT: System default output device
495  * @return result code for this function.
496  *         {@link #AUDIOSTREAM_SUCCESS} succeed in setting the default output device
497  *         {@link #AUDIOSTREAM_ERROR_INVALID_PARAM}:
498  *                                                 1.The param of renderer is nullptr;
499  *                                                 2.The param of deviceType is not valid
500  *         {@link #AUDIOSTREAM_ERROR_ILLEGAL_STATE} This audiorenderer can not reset the output device
501  *         {@link #AUDIOSTREAM_ERROR_SYSTEM} system error when calling this function.
502  * @since 12
503  */
504 OH_AudioStream_Result OH_AudioRenderer_SetDefaultOutputDevice(
505     OH_AudioRenderer* renderer, OH_AudioDevice_Type deviceType);
506 
507 #ifdef __cplusplus
508 }
509 #endif
510 #endif // NATIVE_AUDIORENDERER_H
511