1 /*
2  *  Copyright (C) 2005-2019 Team Kodi
3  *  This file is part of Kodi - https://kodi.tv
4  *
5  *  SPDX-License-Identifier: GPL-2.0-or-later
6  *  See LICENSES/README.md for more information.
7  */
8 
9 #ifndef C_API_AUDIO_ENGINE_H
10 #define C_API_AUDIO_ENGINE_H
11 
12 #include <stdbool.h>
13 #include <stdint.h>
14 
15 #ifdef __cplusplus
16 extern "C"
17 {
18 #endif /* __cplusplus */
19 
20   //¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
21   // "C" Definitions, structures and enumerators of audio engine
22   //{{{
23 
24   //============================================================================
25   /// @defgroup cpp_kodi_audioengine_Defs_AudioEngineStreamOptions enum AudioEngineStreamOptions
26   /// @ingroup cpp_kodi_audioengine_Defs
27   /// @brief **Bit options to pass to CAEStream**\n
28   /// A bit field of stream options.
29   ///
30   ///
31   /// ------------------------------------------------------------------------
32   ///
33   /// **Usage example:**
34   /// ~~~~~~~~~~~~~{.cpp}
35   /// // Here only as minimal, "format" must be set to wanted types
36   /// kodi::audioengine::AudioEngineFormat format;
37   /// m_audioengine = new kodi::audioengine::CAEStream(format, AUDIO_STREAM_FORCE_RESAMPLE | AUDIO_STREAM_AUTOSTART);
38   /// ~~~~~~~~~~~~~
39   ///
40   ///@{
41   typedef enum AudioEngineStreamOptions
42   {
43     /// force resample even if rates match
44     AUDIO_STREAM_FORCE_RESAMPLE = 1 << 0,
45     /// create the stream paused
46     AUDIO_STREAM_PAUSED = 1 << 1,
47     /// autostart the stream when enough data is buffered
48     AUDIO_STREAM_AUTOSTART = 1 << 2,
49   } AudioEngineStreamOptions;
50   ///@}
51   //----------------------------------------------------------------------------
52 
53   //============================================================================
54   /// @defgroup cpp_kodi_audioengine_Defs_AudioEngineChannel enum AudioEngineChannel
55   /// @ingroup cpp_kodi_audioengine_Defs
56   /// @brief **The possible channels**\n
57   /// Used to set available or used channels on stream.
58   ///
59   ///
60   /// ------------------------------------------------------------------------
61   ///
62   /// **Usage example:**
63   /// ~~~~~~~~~~~~~{.cpp}
64   /// kodi::audioengine::AudioEngineFormat format;
65   /// format.SetChannelLayout(std::vector<AudioEngineChannel>(AUDIOENGINE_CH_FL, AUDIOENGINE_CH_FR));
66   /// ~~~~~~~~~~~~~
67   ///
68   ///@{
69   enum AudioEngineChannel
70   {
71     /// Used inside to indicate the end of a list and not for addon use directly.
72     AUDIOENGINE_CH_NULL = -1,
73     /// RAW Audio format
74     AUDIOENGINE_CH_RAW,
75     /// Front left
76     AUDIOENGINE_CH_FL,
77     /// Front right
78     AUDIOENGINE_CH_FR,
79     /// Front center
80     AUDIOENGINE_CH_FC,
81     /// LFE / Subwoofer
82     AUDIOENGINE_CH_LFE,
83     /// Back left
84     AUDIOENGINE_CH_BL,
85     /// Back right
86     AUDIOENGINE_CH_BR,
87     /// Front left over center
88     AUDIOENGINE_CH_FLOC,
89     /// Front right over center
90     AUDIOENGINE_CH_FROC,
91     /// Back center
92     AUDIOENGINE_CH_BC,
93     /// Side left
94     AUDIOENGINE_CH_SL,
95     /// Side right
96     AUDIOENGINE_CH_SR,
97     /// Top front left
98     AUDIOENGINE_CH_TFL,
99     /// Top front right
100     AUDIOENGINE_CH_TFR,
101     /// Top front center
102     AUDIOENGINE_CH_TFC,
103     /// Top center
104     AUDIOENGINE_CH_TC,
105     /// Top back left
106     AUDIOENGINE_CH_TBL,
107     /// Top back right
108     AUDIOENGINE_CH_TBR,
109     /// Top back center
110     AUDIOENGINE_CH_TBC,
111     /// Back left over center
112     AUDIOENGINE_CH_BLOC,
113     /// Back right over center
114     AUDIOENGINE_CH_BROC,
115     /// Maximum possible value, to use e.g. as size inside list
116     AUDIOENGINE_CH_MAX
117   };
118   ///@}
119   //----------------------------------------------------------------------------
120 
121   //============================================================================
122   /// @defgroup cpp_kodi_audioengine_Defs_AudioEngineDataFormat enum AudioEngineDataFormat
123   /// @ingroup cpp_kodi_audioengine_Defs
124   /// @brief **Audio sample formats**\n
125   /// The bit layout of the audio data.
126   ///
127   /// LE = Little Endian, BE = Big Endian, NE = Native Endian
128   ///
129   /// For planar sample formats, each audio channel is in a separate data plane,
130   /// and linesize is the buffer size, in bytes, for a single plane. All data
131   /// planes must be the same size. For packed sample formats, only the first
132   /// data plane is used, and samples for each channel are interleaved. In this
133   /// case, linesize is the buffer size, in bytes, for the 1 plane.
134   ///
135   /// @note This is ordered from the worst to best preferred formats
136   ///
137   ///
138   /// ------------------------------------------------------------------------
139   ///
140   /// **Usage example:**
141   /// ~~~~~~~~~~~~~{.cpp}
142   /// kodi::audioengine::AudioEngineFormat format;
143   /// format.SetDataFormat(AUDIOENGINE_FMT_FLOATP);
144   /// ~~~~~~~~~~~~~
145   ///
146   ///@{
147   enum AudioEngineDataFormat
148   {
149     /// To define format as invalid
150     AUDIOENGINE_FMT_INVALID = -1,
151 
152     /// Unsigned integer 8 bit
153     AUDIOENGINE_FMT_U8,
154 
155     /// Big Endian signed integer 16 bit
156     AUDIOENGINE_FMT_S16BE,
157     /// Little Endian signed integer 16 bit
158     AUDIOENGINE_FMT_S16LE,
159     /// Native Endian signed integer 16 bit
160     AUDIOENGINE_FMT_S16NE,
161 
162     /// Big Endian signed integer 32 bit
163     AUDIOENGINE_FMT_S32BE,
164     /// Little Endian signed integer 32 bit
165     AUDIOENGINE_FMT_S32LE,
166     /// Native Endian signed integer 32 bit
167     AUDIOENGINE_FMT_S32NE,
168 
169     /// Big Endian signed integer 24 bit (in 4 bytes)
170     AUDIOENGINE_FMT_S24BE4,
171     /// Little Endian signed integer 24 bit (in 4 bytes)
172     AUDIOENGINE_FMT_S24LE4,
173     /// Native Endian signed integer 24 bit (in 4 bytes)
174     AUDIOENGINE_FMT_S24NE4,
175     /// S32 with bits_per_sample < 32
176     AUDIOENGINE_FMT_S24NE4MSB,
177 
178     /// Big Endian signed integer 24 bit (3 bytes)
179     AUDIOENGINE_FMT_S24BE3,
180     /// Little Endian signed integer 24 bit (3 bytes)
181     AUDIOENGINE_FMT_S24LE3,
182      /// Native Endian signed integer 24 bit (3 bytes)
183     AUDIOENGINE_FMT_S24NE3,
184 
185     /// Double floating point
186     AUDIOENGINE_FMT_DOUBLE,
187     /// Floating point
188     AUDIOENGINE_FMT_FLOAT,
189 
190     /// **Bitstream**\n
191     /// RAW Audio format
192     AUDIOENGINE_FMT_RAW,
193 
194     /// **Planar format**\n
195     /// Unsigned byte
196     AUDIOENGINE_FMT_U8P,
197     /// **Planar format**\n
198     /// Native Endian signed 16 bit
199     AUDIOENGINE_FMT_S16NEP,
200     /// **Planar format**\n
201     /// Native Endian signed 32 bit
202     AUDIOENGINE_FMT_S32NEP,
203     /// **Planar format**\n
204     /// Native Endian signed integer 24 bit (in 4 bytes)
205     AUDIOENGINE_FMT_S24NE4P,
206     /// **Planar format**\n
207     /// S32 with bits_per_sample < 32
208     AUDIOENGINE_FMT_S24NE4MSBP,
209     /// **Planar format**\n
210     /// Native Endian signed integer 24 bit (in 3 bytes)
211     AUDIOENGINE_FMT_S24NE3P,
212     /// **Planar format**\n
213     /// Double floating point
214     AUDIOENGINE_FMT_DOUBLEP,
215     /// **Planar format**\n
216     /// Floating point
217     AUDIOENGINE_FMT_FLOATP,
218 
219     /// Amount of sample formats.
220     AUDIOENGINE_FMT_MAX
221   };
222   ///@}
223   //----------------------------------------------------------------------------
224 
225   /*!
226    * @brief Internal API structure which are used for data exchange between
227    * Kodi and addon.
228    */
229   struct AUDIO_ENGINE_FORMAT
230   {
231     /*! The stream's data format (eg, AUDIOENGINE_FMT_S16LE) */
232     enum AudioEngineDataFormat m_dataFormat;
233 
234     /*! The stream's sample rate (eg, 48000) */
235     unsigned int m_sampleRate;
236 
237     /*! The encoded streams sample rate if a bitstream, otherwise undefined */
238     unsigned int m_encodedRate;
239 
240     /*! The amount of used speaker channels */
241     unsigned int m_channelCount;
242 
243     /*! The stream's channel layout */
244     enum AudioEngineChannel m_channels[AUDIOENGINE_CH_MAX];
245 
246     /*! The number of frames per period */
247     unsigned int m_frames;
248 
249     /*! The size of one frame in bytes */
250     unsigned int m_frameSize;
251   };
252 
253   /* A stream handle pointer, which is only used internally by the addon stream handle */
254   typedef void AEStreamHandle;
255 
256   //}}}
257 
258   //¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
259   // "C" Internal interface tables for intercommunications between addon and kodi
260   //{{{
261 
262   /*
263    * Function address structure, not need to visible on dev kit doxygen
264    * documentation
265    */
266   typedef struct AddonToKodiFuncTable_kodi_audioengine
267   {
268     AEStreamHandle* (*make_stream)(void* kodiBase,
269                                    struct AUDIO_ENGINE_FORMAT* format,
270                                    unsigned int options);
271     void (*free_stream)(void* kodiBase, AEStreamHandle* stream);
272     bool (*get_current_sink_format)(void* kodiBase, struct AUDIO_ENGINE_FORMAT* sink_format);
273 
274     // Audio Engine Stream definitions
275     unsigned int (*aestream_get_space)(void* kodiBase, AEStreamHandle* handle);
276     unsigned int (*aestream_add_data)(void* kodiBase,
277                                       AEStreamHandle* handle,
278                                       uint8_t* const* data,
279                                       unsigned int offset,
280                                       unsigned int frames,
281                                       double pts,
282                                       bool hasDownmix,
283                                       double centerMixLevel);
284     double (*aestream_get_delay)(void* kodiBase, AEStreamHandle* handle);
285     bool (*aestream_is_buffering)(void* kodiBase, AEStreamHandle* handle);
286     double (*aestream_get_cache_time)(void* kodiBase, AEStreamHandle* handle);
287     double (*aestream_get_cache_total)(void* kodiBase, AEStreamHandle* handle);
288     void (*aestream_pause)(void* kodiBase, AEStreamHandle* handle);
289     void (*aestream_resume)(void* kodiBase, AEStreamHandle* handle);
290     void (*aestream_drain)(void* kodiBase, AEStreamHandle* handle, bool wait);
291     bool (*aestream_is_draining)(void* kodiBase, AEStreamHandle* handle);
292     bool (*aestream_is_drained)(void* kodiBase, AEStreamHandle* handle);
293     void (*aestream_flush)(void* kodiBase, AEStreamHandle* handle);
294     float (*aestream_get_volume)(void* kodiBase, AEStreamHandle* handle);
295     void (*aestream_set_volume)(void* kodiBase, AEStreamHandle* handle, float volume);
296     float (*aestream_get_amplification)(void* kodiBase, AEStreamHandle* handle);
297     void (*aestream_set_amplification)(void* kodiBase, AEStreamHandle* handle, float amplify);
298     unsigned int (*aestream_get_frame_size)(void* kodiBase, AEStreamHandle* handle);
299     unsigned int (*aestream_get_channel_count)(void* kodiBase, AEStreamHandle* handle);
300     unsigned int (*aestream_get_sample_rate)(void* kodiBase, AEStreamHandle* handle);
301     enum AudioEngineDataFormat (*aestream_get_data_format)(void* kodiBase, AEStreamHandle* handle);
302     double (*aestream_get_resample_ratio)(void* kodiBase, AEStreamHandle* handle);
303     void (*aestream_set_resample_ratio)(void* kodiBase, AEStreamHandle* handle, double ratio);
304   } AddonToKodiFuncTable_kodi_audioengine;
305 
306   //}}}
307 
308 #ifdef __cplusplus
309 }
310 #endif /* __cplusplus */
311 
312 #endif /* !C_API_AUDIO_ENGINE_H */
313