xbmc/addons/interfaces/AudioEngine.h

   1 /*
   2  *  Copyright (C) 2005-2018 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 #pragma once
  10
  11 #include "addons/kodi-dev-kit/include/kodi/AudioEngine.h"
  12 #include "cores/AudioEngine/Utils/AEChannelData.h"
  13
  14 extern "C"
  15 {
  16 namespace ADDON
  17 {
  18
  19 struct Interface_AudioEngine
  20 {
  21   static void Init(AddonGlobalInterface* addonInterface);
  22   static void DeInit(AddonGlobalInterface* addonInterface);
  23
  24   /**
  25    * @brief Translation functions to separate Kodi and addons
  26    *
  27    * This thought to make it more safe for cases as something changed inside
  28    * Kodi, addons overseen and breaks API, further to have on addons a better
  29    * documentation about this parts.
  30    */
  31   //@{
  32   static AEChannel TranslateAEChannelToKodi(AudioEngineChannel channel);
  33   static AudioEngineChannel TranslateAEChannelToAddon(AEChannel channel);
  34   static AEDataFormat TranslateAEFormatToKodi(AudioEngineDataFormat format);
  35   static AudioEngineDataFormat TranslateAEFormatToAddon(AEDataFormat format);
  36   //@}
  37
  38   /**
  39    * Creates and returns a new handle to an IAEStream in the format specified, this function should never fail
  40    * @param[in] streamFormat Format to use for stream
  41    * @param[in] options A bit field of stream options (see: enum AEStreamOptions)
  42    * @return a new Handle to an IAEStream that will accept data in the requested format
  43    */
  44   static AEStreamHandle* audioengine_make_stream(void* kodiBase,
  45                                                  AUDIO_ENGINE_FORMAT* streamFormat,
  46                                                  unsigned int options);
  47
  48   /**
  49    * This method will remove the specified stream from the engine.
  50    * For OSX/IOS this is essential to reconfigure the audio output.
  51    * @param[in] streamHandle The stream to be altered
  52    */
  53   static void audioengine_free_stream(void* kodiBase, AEStreamHandle* streamHandle);
  54
  55   /**
  56    * Get the current sink data format
  57    *
  58    * @param[in] sinkFormat sink data format. For more details see AUDIO_ENGINE_FORMAT.
  59    * @return Returns true on success, else false.
  60    */
  61   static bool get_current_sink_format(void* kodiBase, AUDIO_ENGINE_FORMAT* sinkFormat);
  62
  63   /**
  64    * Returns the amount of space available in the stream
  65    * @return The number of bytes AddData will consume
  66    */
  67   static unsigned int aestream_get_space(void* kodiBase, AEStreamHandle* streamHandle);
  68
  69   /**
  70    * Add planar or interleaved PCM data to the stream
  71    * @param[in] data array of pointers to the planes
  72    * @param[in] offset to frame in frames
  73    * @param[in] frames number of frames
  74    * @return The number of frames consumed
  75    */
  76   static unsigned int aestream_add_data(void* kodiBase,
  77                                         AEStreamHandle* streamHandle,
  78                                         uint8_t* const* data,
  79                                         unsigned int offset,
  80                                         unsigned int frames,
  81                                         double pts,
  82                                         bool hasDownmix,
  83                                         double centerMixLevel);
  84
  85   /**
  86    * Returns the time in seconds that it will take
  87    * for the next added packet to be heard from the speakers.
  88    * @return seconds
  89    */
  90   static double aestream_get_delay(void* kodiBase, AEStreamHandle* streamHandle);
  91
  92   /**
  93    * Returns if the stream is buffering
  94    * @return True if the stream is buffering
  95    */
  96   static bool aestream_is_buffering(void* kodiBase, AEStreamHandle* streamHandle);
  97
  98   /**
  99    * Returns the time in seconds that it will take
 100    * to underrun the cache if no sample is added.
 101    * @return seconds
 102    */
 103   static double aestream_get_cache_time(void* kodiBase, AEStreamHandle* streamHandle);
 104
 105   /**
 106    * Returns the total time in seconds of the cache
 107    * @return seconds
 108    */
 109   static double aestream_get_cache_total(void* kodiBase, AEStreamHandle* streamHandle);
 110
 111   /**
 112    * Pauses the stream playback
 113    */
 114   static void aestream_pause(void* kodiBase, AEStreamHandle* streamHandle);
 115
 116   /**
 117    * Resumes the stream after pausing
 118    */
 119   static void aestream_resume(void* kodiBase, AEStreamHandle* streamHandle);
 120
 121   /**
 122    * Start draining the stream
 123    * @note Once called AddData will not consume more data.
 124    */
 125   static void aestream_drain(void* kodiBase, AEStreamHandle* streamHandle, bool wait);
 126
 127   /**
 128    * Returns true if the is stream draining
 129    */
 130   static bool aestream_is_draining(void* kodiBase, AEStreamHandle* streamHandle);
 131
 132   /**
 133    * Returns true if the is stream has finished draining
 134    */
 135   static bool aestream_is_drained(void* kodiBase, AEStreamHandle* streamHandle);
 136
 137   /**
 138    * Flush all buffers dropping the audio data
 139    */
 140   static void aestream_flush(void* kodiBase, AEStreamHandle* streamHandle);
 141
 142   /**
 143    * Return the stream's current volume level
 144    * @return The volume level between 0.0 and 1.0
 145    */
 146   static float aestream_get_volume(void* kodiBase, AEStreamHandle* streamHandle);
 147
 148   /**
 149    * Set the stream's volume level
 150    * @param volume The new volume level between 0.0 and 1.0
 151    */
 152   static void aestream_set_volume(void* kodiBase, AEStreamHandle* streamHandle, float volume);
 153
 154   /**
 155    * Gets the stream's volume amplification in linear units.
 156    * @return The volume amplification factor between 1.0 and 1000.0
 157    */
 158   static float aestream_get_amplification(void* kodiBase, AEStreamHandle* streamHandle);
 159
 160   /**
 161    * Sets the stream's volume amplification in linear units.
 162    * @param amplify The volume amplification factor between 1.0 and 1000.0
 163    */
 164   static void aestream_set_amplification(void* kodiBase,
 165                                          AEStreamHandle* streamHandle,
 166                                          float amplify);
 167
 168   /**
 169    * Returns the size of one audio frame in bytes (channelCount * resolution)
 170    * @return The size in bytes of one frame
 171    */
 172   static unsigned int aestream_get_frame_size(void* kodiBase, AEStreamHandle* streamHandle);
 173
 174   /**
 175    * Returns the number of channels the stream is configured to accept
 176    * @return The channel count
 177    */
 178   static unsigned int aestream_get_channel_count(void* kodiBase, AEStreamHandle* streamHandle);
 179
 180   /**
 181    * Returns the stream's sample rate, if the stream is using a dynamic sample
 182    * rate, this value will NOT reflect any changes made by calls to SetResampleRatio()
 183    * @return The stream's sample rate (eg, 48000)
 184    */
 185   static unsigned int aestream_get_sample_rate(void* kodiBase, AEStreamHandle* streamHandle);
 186
 187   /**
 188    * Return the data format the stream has been configured with
 189    * @return The stream's data format (eg, AE_FMT_S16LE)
 190    */
 191   static AudioEngineDataFormat aestream_get_data_format(void* kodiBase,
 192                                                         AEStreamHandle* streamHandle);
 193
 194   /**
 195    * Return the resample ratio
 196    * @note This will return an undefined value if the stream is not resampling
 197    * @return the current resample ratio or undefined if the stream is not resampling
 198    */
 199   static double aestream_get_resample_ratio(void* kodiBase, AEStreamHandle* streamHandle);
 200
 201   /**
 202    * Sets the resample ratio
 203    * @note This function may return false if the stream is not resampling, if you wish to use this be sure to set the AESTREAM_FORCE_RESAMPLE option
 204    * @param[in] ratio the new sample rate ratio, calculated by ((double)desiredRate / (double)GetSampleRate())
 205    */
 206   static void aestream_set_resample_ratio(void* kodiBase,
 207                                           AEStreamHandle* streamHandle,
 208                                           double ratio);
 209 };
 210
 211 } /* namespace ADDON */
 212 } /* extern "C" */