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 } OH_AudioStream_SourceType;
452 
453 /**
454  * Defines the audio interrupt mode.
455  *
456  * @since 12
457  */
458 typedef enum {
459     /**
460      * Share mode
461      */
462     AUDIOSTREAM_INTERRUPT_MODE_SHARE = 0,
463     /**
464      * Independent mode
465      */
466     AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT = 1
467 } OH_AudioInterrupt_Mode;
468 
469 /**
470  * @brief Defines the audio effect mode.
471  *
472  * @since 12
473  */
474 typedef enum {
475     /**
476      * Audio Effect Mode effect none.
477      *
478      * @since 12
479      */
480     EFFECT_NONE = 0,
481     /**
482      * Audio Effect Mode effect default.
483      *
484      * @since 12
485      */
486     EFFECT_DEFAULT = 1,
487 } OH_AudioStream_AudioEffectMode;
488 
489 /**
490  * @brief Declaring the audio stream builder.
491  * The instance of builder is used for creating audio stream.
492  *
493  * @since 10
494  */
495 typedef struct OH_AudioStreamBuilderStruct OH_AudioStreamBuilder;
496 
497 /**
498  * @brief Declaring the audio renderer stream.
499  * The instance of renderer stream is used for playing audio data.
500  *
501  * @since 10
502  */
503 typedef struct OH_AudioRendererStruct OH_AudioRenderer;
504 
505 /**
506  * @brief Declaring the audio capturer stream.
507  * The instance of renderer stream is used for capturing audio data.
508  *
509  * @since 10
510  */
511 typedef struct OH_AudioCapturerStruct OH_AudioCapturer;
512 
513 /**
514  * @brief Declaring the callback struct for renderer stream.
515  *
516  * @since 10
517  */
518 typedef struct OH_AudioRenderer_Callbacks_Struct {
519     /**
520      * This function pointer will point to the callback function that
521      * is used to write audio data
522      *
523      * @since 10
524      */
525     int32_t (*OH_AudioRenderer_OnWriteData)(
526             OH_AudioRenderer* renderer,
527             void* userData,
528             void* buffer,
529             int32_t length);
530 
531     /**
532      * This function pointer will point to the callback function that
533      * is used to handle audio renderer stream events.
534      *
535      * @since 10
536      */
537     int32_t (*OH_AudioRenderer_OnStreamEvent)(
538             OH_AudioRenderer* renderer,
539             void* userData,
540             OH_AudioStream_Event event);
541 
542     /**
543      * This function pointer will point to the callback function that
544      * is used to handle audio interrupt events.
545      *
546      * @since 10
547      */
548     int32_t (*OH_AudioRenderer_OnInterruptEvent)(
549             OH_AudioRenderer* renderer,
550             void* userData,
551             OH_AudioInterrupt_ForceType type,
552             OH_AudioInterrupt_Hint hint);
553 
554     /**
555      * This function pointer will point to the callback function that
556      * is used to handle audio error result.
557      *
558      * @since 10
559      */
560     int32_t (*OH_AudioRenderer_OnError)(
561             OH_AudioRenderer* renderer,
562             void* userData,
563             OH_AudioStream_Result error);
564 } OH_AudioRenderer_Callbacks;
565 
566 /**
567  * @brief Declaring the callback struct for capturer stream.
568  *
569  * @since 10
570  */
571 typedef struct OH_AudioCapturer_Callbacks_Struct {
572     /**
573      * This function pointer will point to the callback function that
574      * is used to read audio data.
575      *
576      * @since 10
577      */
578     int32_t (*OH_AudioCapturer_OnReadData)(
579             OH_AudioCapturer* capturer,
580             void* userData,
581             void* buffer,
582             int32_t length);
583 
584     /**
585      * This function pointer will point to the callback function that
586      * is used to handle audio capturer stream events.
587      *
588      * @since 10
589      */
590     int32_t (*OH_AudioCapturer_OnStreamEvent)(
591             OH_AudioCapturer* capturer,
592             void* userData,
593             OH_AudioStream_Event event);
594 
595     /**
596      * This function pointer will point to the callback function that
597      * is used to handle audio interrupt events.
598      *
599      * @since 10
600      */
601     int32_t (*OH_AudioCapturer_OnInterruptEvent)(
602             OH_AudioCapturer* capturer,
603             void* userData,
604             OH_AudioInterrupt_ForceType type,
605             OH_AudioInterrupt_Hint hint);
606 
607     /**
608      * This function pointer will point to the callback function that
609      * is used to handle audio error result.
610      *
611      * @since 10
612      */
613     int32_t (*OH_AudioCapturer_OnError)(
614             OH_AudioCapturer* capturer,
615             void* userData,
616             OH_AudioStream_Result error);
617 } OH_AudioCapturer_Callbacks;
618 
619 /**
620  * @brief Defines reason for device changes of one audio stream.
621  *
622  * @since 11
623  */
624 typedef enum {
625     /* Unknown. */
626     REASON_UNKNOWN = 0,
627     /* New Device available. */
628     REASON_NEW_DEVICE_AVAILABLE = 1,
629     /* Old Device unavailable. Applications should consider to pause the audio playback when this reason is
630     reported. */
631     REASON_OLD_DEVICE_UNAVAILABLE = 2,
632     /* Device is overrode by user or system. */
633     REASON_OVERRODE = 3,
634 } OH_AudioStream_DeviceChangeReason;
635 
636 /**
637  * @brief Callback when the output device of an audio renderer changed.
638  *
639  * @param renderer AudioRenderer where this event occurs.
640  * @param userData User data which is passed by user.
641  * @param reason Indicates that why does the output device changes.
642  * @since 11
643  */
644 typedef void (*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData,
645     OH_AudioStream_DeviceChangeReason reason);
646 
647 /**
648  * @brief Callback when the mark position reached.
649  *
650  * @param renderer AudioRenderer where this event occurs.
651  * @param samplePos Mark position in samples.
652  * @param userData User data which is passed by user.
653  * @since 12
654  */
655 typedef void (*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData);
656 
657 /**
658  * @brief This function pointer will point to the callback function that
659  * is used to write audio data with metadata
660  *
661  * @param renderer AudioRenderer where this event occurs.
662  * @param userData User data which is passed by user.
663  * @param audioData Audio data which is written by user.
664  * @param audioDataSize Audio data size which is the size of audio data written by user.
665  * @param metadata Metadata which is written by user.
666  * @param metadataSize Metadata size which is the size of metadata written by user.
667  * @return Error code of the callback function returned by user.
668  * @since 12
669  */
670 typedef int32_t (*OH_AudioRenderer_WriteDataWithMetadataCallback)(OH_AudioRenderer* renderer,
671     void* userData, void* audioData, int32_t audioDataSize, void* metadata, int32_t metadataSize);
672 
673 /**
674  * @brief Defines Enumeration of audio stream privacy type for playback capture.
675  *
676  * @since 12
677  */
678 typedef enum {
679     /** Privacy type that stream can be captured by third party applications.
680      * @since 12
681      */
682     AUDIO_STREAM_PRIVACY_TYPE_PUBLIC = 0,
683     /** Privacy type that stream can not be captured.
684      * @since 12
685      */
686     AUDIO_STREAM_PRIVACY_TYPE_PRIVATE = 1,
687 } OH_AudioStream_PrivacyType;
688 
689 /**
690  * @brief Defines enumeration of audio data callback result.
691  *
692  * @since 12
693  */
694 typedef enum {
695     /** Result of audio data callabck is invalid. */
696     AUDIO_DATA_CALLBACK_RESULT_INVALID = -1,
697     /** Result of audio data callabck is valid. */
698     AUDIO_DATA_CALLBACK_RESULT_VALID = 0,
699 } OH_AudioData_Callback_Result;
700 
701 /**
702  * @brief Callback function of  write data.
703  *
704  * This function is similar with OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData instead of the return
705  * value. The return result of this function indicates whether the data filled in the buffer is valid or invalid. If
706  * result is invalid, the data filled by user will not be played.
707  *
708  * @param renderer AudioRenderer where this callback occurs.
709  * @param userData User data which is passed by user.
710  * @param audioData Audio data pointer, where user should fill in audio data.
711  * @param audioDataSize Size of audio data that user should fill in.
712  * @return Audio Data callback result.
713  * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData
714  * @since 12
715  */
716 typedef OH_AudioData_Callback_Result (*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData,
717     void* audioData, int32_t audioDataSize);
718 #ifdef __cplusplus
719 }
720 #endif
721 
722 #endif // NATIVE_AUDIOSTREAM_BASE_H
723