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