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_audiostream_base.h
30  *
31  * @brief Declare the underlying data structure.
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_BASE_H
41 #define NATIVE_AUDIOSTREAM_BASE_H
42 
43 #include <stdint.h>
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48 
49 /**
50  * @brief Define the result of the function execution.
51  *
52  * @since 10
53  */
54 typedef enum {
55     /**
56      * @error The call was successful.
57      *
58      * @since 10
59      */
60     AUDIOSTREAM_SUCCESS = 0,
61 
62     /**
63      * @error This means that the function was executed with an invalid input parameter.
64      *
65      * @since 10
66      */
67     AUDIOSTREAM_ERROR_INVALID_PARAM = 1,
68 
69     /**
70      * @error Execution status exception.
71      *
72      * @since 10
73      */
74     AUDIOSTREAM_ERROR_ILLEGAL_STATE = 2,
75 
76     /**
77      * @error An system error has occurred.
78      *
79      * @since 10
80      */
81     AUDIOSTREAM_ERROR_SYSTEM = 3
82 } OH_AudioStream_Result;
83 
84 /**
85  * @brief Define the audio stream type.
86  *
87  * @since 10
88  */
89 typedef enum {
90     /**
91      * The type for audio stream is renderer.
92      *
93      * @since 10
94      */
95     AUDIOSTREAM_TYPE_RENDERER = 1,
96 
97     /**
98      * The type for audio stream is capturer.
99      *
100      * @since 10
101      */
102     AUDIOSTREAM_TYPE_CAPTURER = 2
103 } OH_AudioStream_Type;
104 
105 /**
106  * @brief Define the audio stream sample format.
107  *
108  * @since 10
109  */
110 typedef enum {
111     /**
112      * Unsigned 8 format.
113      *
114      * @since 10
115      */
116     AUDIOSTREAM_SAMPLE_U8 = 0,
117     /**
118      * Signed 16 bit integer, little endian.
119      *
120      * @since 10
121      */
122     AUDIOSTREAM_SAMPLE_S16LE = 1,
123     /**
124      * Signed 24 bit integer, little endian.
125      *
126      * @since 10
127      */
128     AUDIOSTREAM_SAMPLE_S24LE = 2,
129     /**
130      * Signed 32 bit integer, little endian.
131      *
132      * @since 10
133      */
134     AUDIOSTREAM_SAMPLE_S32LE = 3,
135 } OH_AudioStream_SampleFormat;
136 
137 /**
138  * @brief Define the audio encoding type.
139  *
140  * @since 10
141  */
142 typedef enum {
143     /**
144      * PCM encoding type.
145      *
146      * @since 10
147      */
148     AUDIOSTREAM_ENCODING_TYPE_RAW = 0,
149     /**
150      * AudioVivid encoding type.
151      *
152      * @since 12
153      */
154     AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID = 1,
155 } OH_AudioStream_EncodingType;
156 
157 /**
158  * @brief Define the audio stream usage.
159  * Audio stream usage is used to describe what work scenario
160  * the current stream is used for.
161  *
162  * @since 10
163  */
164 typedef enum {
165     /**
166      * Unknown usage.
167      *
168      * @since 10
169      */
170     AUDIOSTREAM_USAGE_UNKNOWN = 0,
171     /**
172      * Music usage.
173      *
174      * @since 10
175      */
176     AUDIOSTREAM_USAGE_MUSIC = 1,
177     /**
178      * Voice communication usage.
179      *
180      * @since 10
181      */
182     AUDIOSTREAM_USAGE_VOICE_COMMUNICATION = 2,
183     /**
184      * Voice assistant usage.
185      *
186      * @since 10
187      */
188     AUDIOSTREAM_USAGE_VOICE_ASSISTANT = 3,
189     /**
190      * Alarm usage.
191      *
192      * @since 10
193      */
194     AUDIOSTREAM_USAGE_ALARM = 4,
195     /**
196      * Voice message usage.
197      *
198      * @since 10
199      */
200     AUDIOSTREAM_USAGE_VOICE_MESSAGE = 5,
201     /**
202      * Ringtone usage.
203      *
204      * @since 10
205      */
206     AUDIOSTREAM_USAGE_RINGTONE = 6,
207     /**
208      * Notification usage.
209      *
210      * @since 10
211      */
212     AUDIOSTREAM_USAGE_NOTIFICATION = 7,
213     /**
214      * Accessibility usage, such as screen reader.
215      *
216      * @since 10
217      */
218     AUDIOSTREAM_USAGE_ACCESSIBILITY = 8,
219     /**
220      * Movie or video usage.
221      *
222      * @since 10
223      */
224     AUDIOSTREAM_USAGE_MOVIE = 10,
225     /**
226      * Game sound effect usage.
227      *
228      * @since 10
229      */
230     AUDIOSTREAM_USAGE_GAME = 11,
231     /**
232      * Audiobook usage.
233      *
234      * @since 10
235      */
236     AUDIOSTREAM_USAGE_AUDIOBOOK = 12,
237     /**
238      * Navigation usage.
239      *
240      * @since 10
241      */
242     AUDIOSTREAM_USAGE_NAVIGATION = 13,
243      /**
244      * Video call usage.
245      *
246      * @since 12
247      */
248     AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION = 17,
249 } OH_AudioStream_Usage;
250 
251 /**
252  * @brief Define the audio latency mode.
253  *
254  * @since 10
255  */
256 typedef enum {
257     /**
258      * This is a normal audio scene.
259      *
260      * @since 10
261      */
262     AUDIOSTREAM_LATENCY_MODE_NORMAL = 0,
263     /**
264      * This is a low latency audio scene.
265      *
266      * @since 10
267      */
268     AUDIOSTREAM_LATENCY_MODE_FAST = 1
269 } OH_AudioStream_LatencyMode;
270 
271 /**
272  * @brief Define the audio event.
273  *
274  * @since 10
275  */
276 typedef enum {
277     /**
278      * The routing of the audio has changed.
279      *
280      * @since 10
281      */
282     AUDIOSTREAM_EVENT_ROUTING_CHANGED = 0
283 } OH_AudioStream_Event;
284 
285 /**
286  * @brief The audio stream states
287  *
288  * @since 10
289  */
290 typedef enum {
291     /**
292      * The invalid state.
293      *
294      * @since 10
295      */
296     AUDIOSTREAM_STATE_INVALID = -1,
297     /**
298      * Create new instance state.
299      *
300      * @since 10
301      */
302     AUDIOSTREAM_STATE_NEW = 0,
303     /**
304      * The prepared state.
305      *
306      * @since 10
307      */
308     AUDIOSTREAM_STATE_PREPARED = 1,
309     /**
310      * The stream is running.
311      *
312      * @since 10
313      */
314     AUDIOSTREAM_STATE_RUNNING = 2,
315     /**
316      * The stream is stopped.
317      *
318      * @since 10
319      */
320     AUDIOSTREAM_STATE_STOPPED = 3,
321     /**
322      * The stream is released.
323      *
324      * @since 10
325      */
326     AUDIOSTREAM_STATE_RELEASED = 4,
327     /**
328      * The stream is paused.
329      *
330      * @since 10
331      */
332     AUDIOSTREAM_STATE_PAUSED = 5,
333 } OH_AudioStream_State;
334 
335 /**
336  * @brief Defines the audio interrupt type.
337  *
338  * @since 10
339  */
340 typedef enum {
341     /**
342      * Force type, system change audio state.
343      *
344      * @since 10
345      */
346     AUDIOSTREAM_INTERRUPT_FORCE = 0,
347     /**
348      * Share type, application change audio state.
349      *
350      * @since 10
351      */
352     AUDIOSTREAM_INTERRUPT_SHARE = 1
353 } OH_AudioInterrupt_ForceType;
354 
355 /**
356  * @brief Defines the audio interrupt hint type.
357  *
358  * @since 10
359  */
360 typedef enum {
361     /**
362      * None.
363      *
364      * @since 10
365      */
366     AUDIOSTREAM_INTERRUPT_HINT_NONE = 0,
367     /**
368      * Resume the stream.
369      *
370      * @since 10
371      */
372     AUDIOSTREAM_INTERRUPT_HINT_RESUME = 1,
373     /**
374      * Pause the stream.
375      *
376      * @since 10
377      */
378     AUDIOSTREAM_INTERRUPT_HINT_PAUSE = 2,
379     /**
380      * Stop the stream.
381      *
382      * @since 10
383      */
384     AUDIOSTREAM_INTERRUPT_HINT_STOP = 3,
385     /**
386      * Ducked the stream.
387      *
388      * @since 10
389      */
390     AUDIOSTREAM_INTERRUPT_HINT_DUCK = 4,
391     /**
392      * Unducked the stream.
393      *
394      * @since 10
395      */
396     AUDIOSTREAM_INTERRUPT_HINT_UNDUCK = 5
397 } OH_AudioInterrupt_Hint;
398 
399 /**
400  * @brief Defines the audio source type.
401  *
402  * @since 10
403  */
404 typedef enum {
405     /**
406      * Invalid type.
407      *
408      * @since 10
409      */
410     AUDIOSTREAM_SOURCE_TYPE_INVALID = -1,
411     /**
412      * Mic source type.
413      *
414      * @since 10
415      */
416     AUDIOSTREAM_SOURCE_TYPE_MIC = 0,
417     /**
418      * Voice recognition source type.
419      *
420      * @since 10
421      */
422     AUDIOSTREAM_SOURCE_TYPE_VOICE_RECOGNITION = 1,
423     /**
424      * Playback capture source type.
425      *
426      * @deprecated since 12
427      * @useinstead OH_AVScreenCapture in native interface.
428      * @since 10
429      */
430     AUDIOSTREAM_SOURCE_TYPE_PLAYBACK_CAPTURE = 2,
431     /**
432      * Voice call source type.
433      *
434      * @permission ohos.permission.RECORD_VOICE_CALL
435      * @systemapi
436      * @since 11
437      */
438     AUDIOSTREAM_SOURCE_TYPE_VOICE_CALL = 4,
439     /**
440      * Voice communication source type.
441      *
442      * @since 10
443      */
444     AUDIOSTREAM_SOURCE_TYPE_VOICE_COMMUNICATION = 7,
445     /**
446      * Voice message source type.
447      *
448      * @since 12
449      */
450     AUDIOSTREAM_SOURCE_TYPE_VOICE_MESSAGE = 10,
451     /**
452      * Unprocessed source type.
453      *
454      * @since 15
455      */
456     AUDIOSTREAM_SOURCE_TYPE_UNPROCESSED = 14
457 } OH_AudioStream_SourceType;
458 
459 /**
460  * @brief Defines the audio interrupt mode.
461  *
462  * @since 12
463  */
464 typedef enum {
465     /**
466      * Share mode
467      */
468     AUDIOSTREAM_INTERRUPT_MODE_SHARE = 0,
469     /**
470      * Independent mode
471      */
472     AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT = 1
473 } OH_AudioInterrupt_Mode;
474 
475 /**
476  * @brief Defines the audio effect mode.
477  *
478  * @since 12
479  */
480 typedef enum {
481     /**
482      * Audio Effect Mode effect none.
483      *
484      * @since 12
485      */
486     EFFECT_NONE = 0,
487     /**
488      * Audio Effect Mode effect default.
489      *
490      * @since 12
491      */
492     EFFECT_DEFAULT = 1,
493 } OH_AudioStream_AudioEffectMode;
494 
495 /**
496  * @brief Declaring the audio stream builder.
497  * The instance of builder is used for creating audio stream.
498  *
499  * @since 10
500  */
501 typedef struct OH_AudioStreamBuilderStruct OH_AudioStreamBuilder;
502 
503 /**
504  * @brief Declaring the audio renderer stream.
505  * The instance of renderer stream is used for playing audio data.
506  *
507  * @since 10
508  */
509 typedef struct OH_AudioRendererStruct OH_AudioRenderer;
510 
511 /**
512  * @brief Declaring the audio capturer stream.
513  * The instance of renderer stream is used for capturing audio data.
514  *
515  * @since 10
516  */
517 typedef struct OH_AudioCapturerStruct OH_AudioCapturer;
518 
519 /**
520  * @brief Declaring the callback struct for renderer stream.
521  *
522  * @since 10
523  */
524 typedef struct OH_AudioRenderer_Callbacks_Struct {
525     /**
526      * This function pointer will point to the callback function that
527      * is used to write audio data
528      *
529      * @since 10
530      */
531     int32_t (*OH_AudioRenderer_OnWriteData)(
532             OH_AudioRenderer* renderer,
533             void* userData,
534             void* buffer,
535             int32_t length);
536 
537     /**
538      * This function pointer will point to the callback function that
539      * is used to handle audio renderer stream events.
540      *
541      * @since 10
542      */
543     int32_t (*OH_AudioRenderer_OnStreamEvent)(
544             OH_AudioRenderer* renderer,
545             void* userData,
546             OH_AudioStream_Event event);
547 
548     /**
549      * This function pointer will point to the callback function that
550      * is used to handle audio interrupt events.
551      *
552      * @since 10
553      */
554     int32_t (*OH_AudioRenderer_OnInterruptEvent)(
555             OH_AudioRenderer* renderer,
556             void* userData,
557             OH_AudioInterrupt_ForceType type,
558             OH_AudioInterrupt_Hint hint);
559 
560     /**
561      * This function pointer will point to the callback function that
562      * is used to handle audio error result.
563      *
564      * @since 10
565      */
566     int32_t (*OH_AudioRenderer_OnError)(
567             OH_AudioRenderer* renderer,
568             void* userData,
569             OH_AudioStream_Result error);
570 } OH_AudioRenderer_Callbacks;
571 
572 /**
573  * @brief Declaring the callback struct for capturer stream.
574  *
575  * @since 10
576  */
577 typedef struct OH_AudioCapturer_Callbacks_Struct {
578     /**
579      * This function pointer will point to the callback function that
580      * is used to read audio data.
581      *
582      * @since 10
583      */
584     int32_t (*OH_AudioCapturer_OnReadData)(
585             OH_AudioCapturer* capturer,
586             void* userData,
587             void* buffer,
588             int32_t length);
589 
590     /**
591      * This function pointer will point to the callback function that
592      * is used to handle audio capturer stream events.
593      *
594      * @since 10
595      */
596     int32_t (*OH_AudioCapturer_OnStreamEvent)(
597             OH_AudioCapturer* capturer,
598             void* userData,
599             OH_AudioStream_Event event);
600 
601     /**
602      * This function pointer will point to the callback function that
603      * is used to handle audio interrupt events.
604      *
605      * @since 10
606      */
607     int32_t (*OH_AudioCapturer_OnInterruptEvent)(
608             OH_AudioCapturer* capturer,
609             void* userData,
610             OH_AudioInterrupt_ForceType type,
611             OH_AudioInterrupt_Hint hint);
612 
613     /**
614      * This function pointer will point to the callback function that
615      * is used to handle audio error result.
616      *
617      * @since 10
618      */
619     int32_t (*OH_AudioCapturer_OnError)(
620             OH_AudioCapturer* capturer,
621             void* userData,
622             OH_AudioStream_Result error);
623 } OH_AudioCapturer_Callbacks;
624 
625 /**
626  * @brief Defines reason for device changes of one audio stream.
627  *
628  * @since 11
629  */
630 typedef enum {
631     /* Unknown. */
632     REASON_UNKNOWN = 0,
633     /* New Device available. */
634     REASON_NEW_DEVICE_AVAILABLE = 1,
635     /* Old Device unavailable. Applications should consider to pause the audio playback when this reason is
636     reported. */
637     REASON_OLD_DEVICE_UNAVAILABLE = 2,
638     /* Device is overrode by user or system. */
639     REASON_OVERRODE = 3,
640 } OH_AudioStream_DeviceChangeReason;
641 
642 /**
643  * @brief Callback when the output device of an audio renderer changed.
644  *
645  * @param renderer AudioRenderer where this event occurs.
646  * @param userData User data which is passed by user.
647  * @param reason Indicates that why does the output device changes.
648  * @since 11
649  */
650 typedef void (*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData,
651     OH_AudioStream_DeviceChangeReason reason);
652 
653 /**
654  * @brief Callback when the mark position reached.
655  *
656  * @param renderer AudioRenderer where this event occurs.
657  * @param samplePos Mark position in samples.
658  * @param userData User data which is passed by user.
659  * @since 12
660  */
661 typedef void (*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData);
662 
663 /**
664  * @brief This function pointer will point to the callback function that
665  * is used to write audio data with metadata
666  *
667  * @param renderer AudioRenderer where this event occurs.
668  * @param userData User data which is passed by user.
669  * @param audioData Audio data which is written by user.
670  * @param audioDataSize Audio data size which is the size of audio data written by user.
671  * @param metadata Metadata which is written by user.
672  * @param metadataSize Metadata size which is the size of metadata written by user.
673  * @return Error code of the callback function returned by user.
674  * @since 12
675  */
676 typedef int32_t (*OH_AudioRenderer_WriteDataWithMetadataCallback)(OH_AudioRenderer* renderer,
677     void* userData, void* audioData, int32_t audioDataSize, void* metadata, int32_t metadataSize);
678 
679 /**
680  * @brief Defines Enumeration of audio stream privacy type for playback capture.
681  *
682  * @since 12
683  */
684 typedef enum {
685     /** Privacy type that stream can be captured by third party applications.
686      * @since 12
687      */
688     AUDIO_STREAM_PRIVACY_TYPE_PUBLIC = 0,
689     /** Privacy type that stream can not be captured.
690      * @since 12
691      */
692     AUDIO_STREAM_PRIVACY_TYPE_PRIVATE = 1,
693 } OH_AudioStream_PrivacyType;
694 
695 /**
696  * @brief Defines enumeration of audio data callback result.
697  *
698  * @since 12
699  */
700 typedef enum {
701     /** Result of audio data callback is invalid. */
702     AUDIO_DATA_CALLBACK_RESULT_INVALID = -1,
703     /** Result of audio data callback is valid. */
704     AUDIO_DATA_CALLBACK_RESULT_VALID = 0,
705 } OH_AudioData_Callback_Result;
706 
707 /**
708  * @brief Callback function of  write data.
709  *
710  * This function is similar with OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData instead of the return
711  * value. The return result of this function indicates whether the data filled in the buffer is valid or invalid. If
712  * result is invalid, the data filled by user will not be played.
713  *
714  * @param renderer AudioRenderer where this callback occurs.
715  * @param userData User data which is passed by user.
716  * @param audioData Audio data pointer, where user should fill in audio data.
717  * @param audioDataSize Size of audio data that user should fill in.
718  * @return Audio Data callback result.
719  * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData
720  * @since 12
721  */
722 typedef OH_AudioData_Callback_Result (*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData,
723     void* audioData, int32_t audioDataSize);
724 #ifdef __cplusplus
725 }
726 #endif
727 
728 #endif // NATIVE_AUDIOSTREAM_BASE_H
729