summaryrefslogtreecommitdiffstats
path: root/xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h
diff options
context:
space:
mode:
Diffstat (limited to 'xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h')
-rw-r--r--xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h597
1 files changed, 0 insertions, 597 deletions
diff --git a/xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h b/xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h
deleted file mode 100644
index 02faf86..0000000
--- a/xbmc/addons/kodi-addon-dev-kit/include/kodi/AudioEngine.h
+++ /dev/null
@@ -1,597 +0,0 @@
1#pragma once
2/*
3 * Copyright (C) 2005-2017 Team KODI
4 * http://kodi.tv
5 *
6 * This Program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2, or (at your option)
9 * any later version.
10 *
11 * This Program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with Kodi; see the file COPYING. If not, see
18 * <http://www.gnu.org/licenses/>.
19 *
20 */
21
22#include "AddonBase.h"
23
24#ifdef BUILD_KODI_ADDON
25#include "AEChannelData.h"
26#else
27#include "cores/AudioEngine/Utils/AEChannelData.h"
28#endif
29
30//==============================================================================
31///
32/// \defgroup cpp_kodi_audioengine Interface - kodi::audioengine
33/// \ingroup cpp
34/// @brief **Audio engine functions**
35///
36///
37/// It has the header \ref AudioEngine.h "#include <kodi/AudioEngine.h>" be included
38/// to enjoy it.
39///
40//------------------------------------------------------------------------------
41
42//==============================================================================
43///
44/// \defgroup cpp_kodi_audioengine_Defs Definitions, structures and enumerators
45/// \ingroup cpp_kodi_audioengine
46/// @brief **Library definition values**
47///
48//------------------------------------------------------------------------------
49
50extern "C"
51{
52
53 //============================================================================
54 /// \ingroup cpp_kodi_audioengine_Defs
55 /// @brief Bit options to pass to CAddonAEStream
56 ///
57 typedef enum AudioEngineStreamOptions
58 {
59 /// force resample even if rates match
60 AUDIO_STREAM_FORCE_RESAMPLE = 1 << 0,
61 /// create the stream paused
62 AUDIO_STREAM_PAUSED = 1 << 1,
63 /// autostart the stream when enough data is buffered
64 AUDIO_STREAM_AUTOSTART = 1 << 2,
65 /// if this option is set the ADSP-System is bypassed and the raw stream
66 /// will be passed through IAESink
67 AUDIO_STREAM_BYPASS_ADSP = 1 << 3
68 } AudioEngineStreamOptions;
69 //----------------------------------------------------------------------------
70
71 //============================================================================
72 /// \defgroup cpp_kodi_audioengine_Defs_AudioEngineFormat struct AudioEngineFormat
73 /// \ingroup cpp_kodi_audioengine_Defs
74 /// @brief The audio format structure that fully defines a stream's audio
75 /// information
76 ///
77 //@{
78 struct AudioEngineFormat
79 {
80 /// The stream's data format (eg, AE_FMT_S16LE)
81 enum AEDataFormat m_dataFormat;
82
83 /// The stream's sample rate (eg, 48000)
84 unsigned int m_sampleRate;
85
86 /// The encoded streams sample rate if a bitstream, otherwise undefined
87 unsigned int m_encodedRate;
88
89 /// The amount of used speaker channels
90 unsigned int m_channelCount;
91
92 /// The stream's channel layout
93 enum AEChannel m_channels[AE_CH_MAX];
94
95 /// The number of frames per period
96 unsigned int m_frames;
97
98 /// The size of one frame in bytes
99 unsigned int m_frameSize;
100
101 AudioEngineFormat()
102 {
103 m_dataFormat = AE_FMT_INVALID;
104 m_sampleRate = 0;
105 m_encodedRate = 0;
106 m_frames = 0;
107 m_frameSize = 0;
108 m_channelCount = 0;
109
110 for (unsigned int ch = 0; ch < AE_CH_MAX; ++ch)
111 {
112 m_channels[ch] = AE_CH_MAX;
113 }
114 }
115
116 /// Function to compare the format structure with another
117 bool compareFormat(const AudioEngineFormat *fmt)
118 {
119 if (!fmt)
120 {
121 return false;
122 }
123
124 if (m_dataFormat != fmt->m_dataFormat ||
125 m_sampleRate != fmt->m_sampleRate ||
126 m_encodedRate != fmt->m_encodedRate ||
127 m_frames != fmt->m_frames ||
128 m_frameSize != fmt->m_frameSize ||
129 m_channelCount != fmt->m_channelCount)
130 {
131 return false;
132 }
133
134 for (unsigned int ch = 0; ch < AE_CH_MAX; ++ch)
135 {
136 if (fmt->m_channels[ch] != m_channels[ch])
137 {
138 return false;
139 }
140 }
141
142 return true;
143 }
144 };
145 //@}
146 //----------------------------------------------------------------------------
147
148 /* A stream handle pointer, which is only used internally by the addon stream handle */
149 typedef void AEStreamHandle;
150
151 /*
152 * Function address structure, not need to visible on dev kit doxygen
153 * documentation
154 */
155 typedef struct AddonToKodiFuncTable_kodi_audioengine
156 {
157 AEStreamHandle* (*make_stream)(void *kodiBase, AudioEngineFormat* format, unsigned int options);
158 void (*free_stream)(void *kodiBase, AEStreamHandle *stream);
159 bool (*get_current_sink_format)(void *kodiBase, AudioEngineFormat* sink_format);
160
161 // Audio Engine Stream definitions
162 unsigned int (*aestream_get_space)(void *kodiBase, AEStreamHandle *handle);
163 unsigned int (*aestream_add_data)(void *kodiBase, AEStreamHandle *handle, uint8_t* const *data,
164 unsigned int offset, unsigned int frames, double pts);
165 double (*aestream_get_delay)(void *kodiBase, AEStreamHandle *handle);
166 bool (*aestream_is_buffering)(void *kodiBase, AEStreamHandle *handle);
167 double (*aestream_get_cache_time)(void *kodiBase, AEStreamHandle *handle);
168 double (*aestream_get_cache_total)(void *kodiBase, AEStreamHandle *handle);
169 void (*aestream_pause)(void *kodiBase, AEStreamHandle *handle);
170 void (*aestream_resume)(void *kodiBase, AEStreamHandle *handle);
171 void (*aestream_drain)(void *kodiBase, AEStreamHandle *handle, bool wait);
172 bool (*aestream_is_draining)(void *kodiBase, AEStreamHandle *handle);
173 bool (*aestream_is_drained)(void *kodiBase, AEStreamHandle *handle);
174 void (*aestream_flush)(void *kodiBase, AEStreamHandle *handle);
175 float (*aestream_get_volume)(void *kodiBase, AEStreamHandle *handle);
176 void (*aestream_set_volume)(void *kodiBase, AEStreamHandle *handle, float volume);
177 float (*aestream_get_amplification)(void *kodiBase, AEStreamHandle *handle);
178 void (*aestream_set_amplification)(void *kodiBase, AEStreamHandle *handle, float amplify);
179 unsigned int (*aestream_get_frame_size)(void *kodiBase, AEStreamHandle *handle);
180 unsigned int (*aestream_get_channel_count)(void *kodiBase, AEStreamHandle *handle);
181 unsigned int (*aestream_get_sample_rate)(void *kodiBase, AEStreamHandle *handle);
182 AEDataFormat (*aestream_get_data_format)(void *kodiBase, AEStreamHandle *handle);
183 double (*aestream_get_resample_ratio)(void *kodiBase, AEStreamHandle *handle);
184 void (*aestream_set_resample_ratio)(void *kodiBase, AEStreamHandle *handle, double ratio);
185 } AddonToKodiFuncTable_kodi_audioengine;
186
187} /* extern "C" */
188
189namespace kodi
190{
191namespace audioengine
192{
193
194 //============================================================================
195 ///
196 /// \defgroup cpp_kodi_audioengine_CAddonAEStream class CAddonAEStream
197 /// \ingroup cpp_kodi_audioengine
198 /// @brief **Audio Engine Stream Class**
199 ///
200 ///
201 /// It has the header \ref AudioEngine.h "#include <kodi/AudioEngine.h>" be
202 /// included to enjoy it.
203 ///
204 //----------------------------------------------------------------------------
205 class CAddonAEStream
206 {
207 public:
208 //==========================================================================
209 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
210 /// @brief Contructs new class to an Kodi IAEStream in the format specified.
211 ///
212 /// @param[in] format The data format the incoming audio will be in
213 /// (e.g. \ref AE_FMT_S16LE)
214 /// @param[in] options [opt] A bit field of stream options (see: enum \ref AudioEngineStreamOptions)
215 ///
216 ///
217 /// ------------------------------------------------------------------------
218 ///
219 /// **Audio engine format information:**
220 /// @code
221 /// /*
222 /// * Audio engine format information
223 /// *
224 /// * Only as example shown here! See always the original structure on related header.
225 /// */
226 /// typedef struct AudioEngineFormat
227 /// {
228 /// enum AEDataFormat m_dataFormat; /* The stream's data format (eg, AE_FMT_S16LE) */
229 /// unsigned int m_sampleRate; /* The stream's sample rate (eg, 48000) */
230 /// unsigned int m_encodedRate; /* The encoded streams sample rate if a bitstream, otherwise undefined */
231 /// unsigned int m_channelCount; /* The amount of used speaker channels */
232 /// enum AEChannel m_channels[AE_CH_MAX]; /* The stream's channel layout */
233 /// unsigned int m_frames; /* The number of frames per period */
234 /// unsigned int m_frameSamples; /* The number of samples in one frame */
235 /// unsigned int m_frameSize; /* The size of one frame in bytes */
236 ///
237 /// /* Function to compare the format structure with another */
238 /// bool compareFormat(const AudioEngineFormat *fmt);
239 /// } AudioEngineFormat;
240 /// @endcode
241 ///
242 /// ------------------------------------------------------------------------
243 ///
244 /// **Bit options to pass to CAELib_Stream (on Kodi by <c>IAE::MakeStream</c>)**
245 ///
246 /// | enum AEStreamOptions | Value: | Description:
247 /// |----------------------------:|:------:|:-----------------------------------
248 /// | AUDIO_STREAM_FORCE_RESAMPLE | 1 << 0 | Force resample even if rates match
249 /// | AUDIO_STREAM_PAUSED | 1 << 1 | Create the stream paused
250 /// | AUDIO_STREAM_AUTOSTART | 1 << 2 | Autostart the stream when enough data is buffered
251 /// | AUDIO_STREAM_BYPASS_ADSP | 1 << 3 | if this option is set the ADSP-System is bypassed and the raw stream will be passed through IAESink.
252 ///
253 ///
254 /// ------------------------------------------------------------------------
255 ///
256 /// **Example:**
257 /// ~~~~~~~~~~~~~{.cpp}
258 ///
259 /// #include <kodi/AudioEngine.h>
260 ///
261 /// using namespace kodi::audioengine;
262 ///
263 /// ...
264 ///
265 /// AudioEngineFormat format;
266 /// format.m_dataFormat = AE_FMT_FLOAT;
267 /// format.m_channelCount = 2;
268 /// format.m_channels[0] = AE_CH_FL;
269 /// format.m_channels[1] = AE_CH_FR;
270 /// format.m_channels[2] = AE_CH_NULL;
271 /// format.m_sampleRate = 48000;
272 /// format.m_frameSize = sizeof(float)*format.m_channelCount;
273 /// format.m_frames = 512;
274 /// CAddonAEStream* stream = new CAddonAEStream(format, AE_STREAM_AUTOSTART | AE_STREAM_BYPASS_ADSP);
275 ///
276 /// ~~~~~~~~~~~~~
277 ///
278 CAddonAEStream(AudioEngineFormat format, unsigned int options = 0)
279 : m_kodiBase(::kodi::addon::CAddonBase::m_interface->toKodi->kodiBase),
280 m_cb(::kodi::addon::CAddonBase::m_interface->toKodi->kodi_audioengine)
281 {
282 m_StreamHandle = m_cb->make_stream(m_kodiBase, &format, options);
283 if (m_StreamHandle == nullptr)
284 {
285 kodi::Log(ADDON_LOG_FATAL, "CAddonAEStream: make_stream failed!");
286 }
287 }
288 //--------------------------------------------------------------------------
289
290 //==========================================================================
291 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
292 /// @brief Class destructor
293 ///
294 ~CAddonAEStream()
295 {
296 if (m_StreamHandle)
297 {
298 m_cb->free_stream(m_kodiBase, m_StreamHandle);
299 m_StreamHandle = nullptr;
300 }
301 }
302 //--------------------------------------------------------------------------
303
304 //==========================================================================
305 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
306 /// @brief Returns the amount of space available in the stream
307 ///
308 /// @return The number of bytes AddData will consume
309 ///
310 unsigned int GetSpace()
311 {
312 return m_cb->aestream_get_space(m_kodiBase, m_StreamHandle);
313 }
314 //--------------------------------------------------------------------------
315
316 //==========================================================================
317 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
318 /// @brief Add planar or interleaved PCM data to the stream
319 ///
320 /// @param[in] data array of pointers to the planes
321 /// @param[in] offset to frame in frames
322 /// @param[in] frames number of frames
323 /// @param[in] pts presentation timestamp
324 /// @return The number of frames consumed
325 ///
326 unsigned int AddData(uint8_t* const *data, unsigned int offset, unsigned int frames, double pts = 0.0)
327 {
328 return m_cb->aestream_add_data(m_kodiBase, m_StreamHandle, data, offset, frames, pts);
329 }
330 //--------------------------------------------------------------------------
331
332 //==========================================================================
333 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
334 /// @brief Returns the time in seconds that it will take for the next added
335 /// packet to be heard from the speakers.
336 ///
337 /// @return seconds
338 ///
339 double GetDelay()
340 {
341 return m_cb->aestream_get_delay(m_kodiBase, m_StreamHandle);
342 }
343 //--------------------------------------------------------------------------
344
345 //==========================================================================
346 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
347 /// @brief Returns if the stream is buffering
348 ///
349 /// @return True if the stream is buffering
350 ///
351 bool IsBuffering()
352 {
353 return m_cb->aestream_is_buffering(m_kodiBase, m_StreamHandle);
354 }
355 //--------------------------------------------------------------------------
356
357 //==========================================================================
358 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
359 /// @brief Returns the time in seconds of the stream's cached audio samples.
360 /// Engine buffers excluded.
361 ///
362 /// @return seconds
363 ///
364 double GetCacheTime()
365 {
366 return m_cb->aestream_get_cache_time(m_kodiBase, m_StreamHandle);
367 }
368 //--------------------------------------------------------------------------
369
370 //==========================================================================
371 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
372 /// @brief Returns the total time in seconds of the cache
373 ///
374 /// @return seconds
375 ///
376 double GetCacheTotal()
377 {
378 return m_cb->aestream_get_cache_total(m_kodiBase, m_StreamHandle);
379 }
380 //--------------------------------------------------------------------------
381
382 //==========================================================================
383 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
384 /// @brief Pauses the stream playback
385 ///
386 void Pause()
387 {
388 return m_cb->aestream_pause(m_kodiBase, m_StreamHandle);
389 }
390 //--------------------------------------------------------------------------
391
392 //==========================================================================
393 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
394 /// @brief Resumes the stream after pausing
395 ///
396 void Resume()
397 {
398 return m_cb->aestream_resume(m_kodiBase, m_StreamHandle);
399 }
400 //--------------------------------------------------------------------------
401
402 //==========================================================================
403 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
404 /// @brief Start draining the stream
405 ///
406 /// @param[in] wait [opt] Wait until drain is finished if set to
407 /// true, otherwise it returns direct
408 ///
409 /// @note Once called AddData will not consume more data.
410 ///
411 void Drain(bool wait = true)
412 {
413 return m_cb->aestream_drain(m_kodiBase, m_StreamHandle, wait);
414 }
415 //--------------------------------------------------------------------------
416
417 //==========================================================================
418 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
419 /// @brief Returns true if the is stream draining
420 ///
421 bool IsDraining()
422 {
423 return m_cb->aestream_is_draining(m_kodiBase, m_StreamHandle);
424 }
425 //--------------------------------------------------------------------------
426
427 //==========================================================================
428 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
429 /// @brief Returns true if the is stream has finished draining
430 ///
431 bool IsDrained()
432 {
433 return m_cb->aestream_is_drained(m_kodiBase, m_StreamHandle);
434 }
435 //--------------------------------------------------------------------------
436
437 //==========================================================================
438 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
439 /// @brief Flush all buffers dropping the audio data
440 ///
441 void Flush()
442 {
443 return m_cb->aestream_flush(m_kodiBase, m_StreamHandle);
444 }
445 //--------------------------------------------------------------------------
446
447 //==========================================================================
448 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
449 /// @brief Return the stream's current volume level
450 ///
451 /// @return The volume level between 0.0 and 1.0
452 ///
453 float GetVolume()
454 {
455 return m_cb->aestream_get_volume(m_kodiBase, m_StreamHandle);
456 }
457 //--------------------------------------------------------------------------
458
459 //==========================================================================
460 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
461 /// @brief Set the stream's volume level
462 ///
463 /// @param[in] volume The new volume level between 0.0 and 1.0
464 ///
465 void SetVolume(float volume)
466 {
467 return m_cb->aestream_set_volume(m_kodiBase, m_StreamHandle, volume);
468 }
469 //--------------------------------------------------------------------------
470
471 //==========================================================================
472 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
473 /// @brief Gets the stream's volume amplification in linear units.
474 ///
475 /// @return The volume amplification factor between 1.0 and 1000.0
476 ///
477 float GetAmplification()
478 {
479 return m_cb->aestream_get_amplification(m_kodiBase, m_StreamHandle);
480 }
481 //--------------------------------------------------------------------------
482
483 //==========================================================================
484 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
485 /// @brief Sets the stream's volume amplification in linear units.
486 ///
487 /// @param[in] amplify The volume amplification factor between
488 /// 1.0 and 1000.0
489 ///
490 void SetAmplification(float amplify)
491 {
492 return m_cb->aestream_set_amplification(m_kodiBase, m_StreamHandle, amplify);
493 }
494 //--------------------------------------------------------------------------
495
496 //==========================================================================
497 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
498 /// @brief Returns the size of one audio frame in bytes (channelCount * resolution)
499 ///
500 /// @return The size in bytes of one frame
501 ///
502 unsigned int GetFrameSize() const
503 {
504 return m_cb->aestream_get_frame_size(m_kodiBase, m_StreamHandle);
505 }
506 //--------------------------------------------------------------------------
507
508 //==========================================================================
509 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
510 /// @brief Returns the number of channels the stream is configured to accept
511 ///
512 /// @return The channel count
513 ///
514 unsigned int GetChannelCount() const
515 {
516 return m_cb->aestream_get_channel_count(m_kodiBase, m_StreamHandle);
517 }
518 //--------------------------------------------------------------------------
519
520 //==========================================================================
521 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
522 /// @brief Returns the stream's sample rate, if the stream is using a dynamic
523 /// sample rate, this value will NOT reflect any changes made by calls to
524 /// SetResampleRatio()
525 ///
526 /// @return The stream's sample rate (eg, 48000)
527 ///
528 unsigned int GetSampleRate() const
529 {
530 return m_cb->aestream_get_sample_rate(m_kodiBase, m_StreamHandle);
531 }
532 //--------------------------------------------------------------------------
533
534 //==========================================================================
535 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
536 /// @brief Return the data format the stream has been configured with
537 ///
538 /// @return The stream's data format (eg, AUDIOENGINE_FMT_S16LE)
539 ///
540 AEDataFormat GetDataFormat() const
541 {
542 return m_cb->aestream_get_data_format(m_kodiBase, m_StreamHandle);
543 }
544 //--------------------------------------------------------------------------
545
546 //==========================================================================
547 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
548 /// @brief Return the resample ratio
549 ///
550 /// @note This will return an undefined value if the stream is not resampling
551 ///
552 /// @return the current resample ratio or undefined if the stream is not resampling
553 ///
554 double GetResampleRatio()
555 {
556 return m_cb->aestream_get_resample_ratio(m_kodiBase, m_StreamHandle);
557 }
558 //--------------------------------------------------------------------------
559
560 //==========================================================================
561 /// @ingroup cpp_kodi_audioengine_CAddonAEStream
562 /// @brief Sets the resample ratio
563 ///
564 /// @note This function may return false if the stream is not resampling, if
565 /// you wish to use this be sure to set the AESTREAM_FORCE_RESAMPLE option
566 ///
567 /// @param[in] ratio the new sample rate ratio, calculated by
568 /// ((double)desiredRate / (double)GetSampleRate())
569 ///
570 void SetResampleRatio(double ratio)
571 {
572 m_cb->aestream_set_resample_ratio(m_kodiBase, m_StreamHandle, ratio);
573 }
574 //--------------------------------------------------------------------------
575
576 private:
577 void* m_kodiBase;
578 AddonToKodiFuncTable_kodi_audioengine* m_cb;
579 AEStreamHandle *m_StreamHandle;
580 };
581
582 //============================================================================
583 /// @ingroup cpp_kodi_audioengine
584 /// @brief Get the current sink data format
585 ///
586 /// @param[in] format Current sink data format. For more details see AudioEngineFormat.
587 /// @return Returns true on success, else false.
588 ///
589 inline bool GetCurrentSinkFormat(AudioEngineFormat &format)
590 {
591 using namespace kodi::addon;
592 return CAddonBase::m_interface->toKodi->kodi_audioengine->get_current_sink_format(CAddonBase::m_interface->toKodi->kodiBase, &format);
593 }
594 //----------------------------------------------------------------------------
595
596} /* audioengine */
597} /* kodi */
generated by cgit v1.2.3 (git 2.25.1) at 2026-01-11 16:00:27 +0000