Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

juce_AudioIODevice.h 15KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352
  1. /*
  2. ==============================================================================
  3. This file is part of the JUCE library.
  4. Copyright (c) 2022 - Raw Material Software Limited
  5. JUCE is an open source library subject to commercial or open-source
  6. licensing.
  7. The code included in this file is provided under the terms of the ISC license
  8. http://www.isc.org/downloads/software-support-policy/isc-license. Permission
  9. To use, copy, modify, and/or distribute this software for any purpose with or
  10. without fee is hereby granted provided that the above copyright notice and
  11. this permission notice appear in all copies.
  12. JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  13. EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  14. DISCLAIMED.
  15. ==============================================================================
  16. */
  17. namespace juce
  18. {
  19. class AudioIODevice;
  20. /** Additional information that may be passed to the AudioIODeviceCallback. */
  21. struct AudioIODeviceCallbackContext
  22. {
  23. /** If the host provides this information, this field will be set to point to
  24. an integer holding the current value; otherwise, this will be nullptr.
  25. */
  26. const uint64_t* hostTimeNs = nullptr;
  27. };
  28. //==============================================================================
  29. /**
  30. One of these is passed to an AudioIODevice object to stream the audio data
  31. in and out.
  32. The AudioIODevice will repeatedly call this class's audioDeviceIOCallback()
  33. method on its own high-priority audio thread, when it needs to send or receive
  34. the next block of data.
  35. @see AudioIODevice, AudioDeviceManager
  36. @tags{Audio}
  37. */
  38. class JUCE_API AudioIODeviceCallback
  39. {
  40. public:
  41. /** Destructor. */
  42. virtual ~AudioIODeviceCallback() = default;
  43. /** Processes a block of incoming and outgoing audio data.
  44. The subclass's implementation should use the incoming audio for whatever
  45. purposes it needs to, and must fill all the output channels with the next
  46. block of output data before returning.
  47. The channel data is arranged with the same array indices as the channel name
  48. array returned by AudioIODevice::getOutputChannelNames(), but those channels
  49. that aren't specified in AudioIODevice::open() will have a null pointer for their
  50. associated channel, so remember to check for this.
  51. @param inputChannelData a set of arrays containing the audio data for each
  52. incoming channel - this data is valid until the function
  53. returns. There will be one channel of data for each input
  54. channel that was enabled when the audio device was opened
  55. (see AudioIODevice::open())
  56. @param numInputChannels the number of pointers to channel data in the
  57. inputChannelData array.
  58. @param outputChannelData a set of arrays which need to be filled with the data
  59. that should be sent to each outgoing channel of the device.
  60. There will be one channel of data for each output channel
  61. that was enabled when the audio device was opened (see
  62. AudioIODevice::open())
  63. The initial contents of the array is undefined, so the
  64. callback function must fill all the channels with zeros if
  65. its output is silence. Failing to do this could cause quite
  66. an unpleasant noise!
  67. @param numOutputChannels the number of pointers to channel data in the
  68. outputChannelData array.
  69. @param numSamples the number of samples in each channel of the input and
  70. output arrays. The number of samples will depend on the
  71. audio device's buffer size and will usually remain constant,
  72. although this isn't guaranteed. For example, on Android,
  73. on devices which support it, Android will chop up your audio
  74. processing into several smaller callbacks to ensure higher audio
  75. performance. So make sure your code can cope with reasonable
  76. changes in the buffer size from one callback to the next.
  77. */
  78. virtual void audioDeviceIOCallback (const float** inputChannelData,
  79. int numInputChannels,
  80. float** outputChannelData,
  81. int numOutputChannels,
  82. int numSamples)
  83. {
  84. ignoreUnused (inputChannelData, numInputChannels, outputChannelData, numOutputChannels, numSamples);
  85. }
  86. /** The same as audioDeviceIOCallback(), but with an additional context argument.
  87. The default implementation of this function will call audioDeviceIOCallback(),
  88. but you can override this function if you need to make use of the context information.
  89. */
  90. virtual void audioDeviceIOCallbackWithContext (const float** inputChannelData,
  91. int numInputChannels,
  92. float** outputChannelData,
  93. int numOutputChannels,
  94. int numSamples,
  95. const AudioIODeviceCallbackContext& context)
  96. {
  97. audioDeviceIOCallback (inputChannelData, numInputChannels, outputChannelData, numOutputChannels, numSamples);
  98. ignoreUnused (context);
  99. }
  100. /** Called to indicate that the device is about to start calling back.
  101. This will be called just before the audio callbacks begin, either when this
  102. callback has just been added to an audio device, or after the device has been
  103. restarted because of a sample-rate or block-size change.
  104. You can use this opportunity to find out the sample rate and block size
  105. that the device is going to use by calling the AudioIODevice::getCurrentSampleRate()
  106. and AudioIODevice::getCurrentBufferSizeSamples() on the supplied pointer.
  107. @param device the audio IO device that will be used to drive the callback.
  108. Note that if you're going to store this this pointer, it is
  109. only valid until the next time that audioDeviceStopped is called.
  110. */
  111. virtual void audioDeviceAboutToStart (AudioIODevice* device) = 0;
  112. /** Called to indicate that the device has stopped. */
  113. virtual void audioDeviceStopped() = 0;
  114. /** This can be overridden to be told if the device generates an error while operating.
  115. Be aware that this could be called by any thread! And not all devices perform
  116. this callback.
  117. */
  118. virtual void audioDeviceError (const String& errorMessage);
  119. };
  120. //==============================================================================
  121. /**
  122. Base class for an audio device with synchronised input and output channels.
  123. Subclasses of this are used to implement different protocols such as DirectSound,
  124. ASIO, CoreAudio, etc.
  125. To create one of these, you'll need to use the AudioIODeviceType class - see the
  126. documentation for that class for more info.
  127. For an easier way of managing audio devices and their settings, have a look at the
  128. AudioDeviceManager class.
  129. @see AudioIODeviceType, AudioDeviceManager
  130. @tags{Audio}
  131. */
  132. class JUCE_API AudioIODevice
  133. {
  134. public:
  135. /** Destructor. */
  136. virtual ~AudioIODevice();
  137. //==============================================================================
  138. /** Returns the device's name, (as set in the constructor). */
  139. const String& getName() const noexcept { return name; }
  140. /** Returns the type of the device.
  141. E.g. "CoreAudio", "ASIO", etc. - this comes from the AudioIODeviceType that created it.
  142. */
  143. const String& getTypeName() const noexcept { return typeName; }
  144. //==============================================================================
  145. /** Returns the names of all the available output channels on this device.
  146. To find out which of these are currently in use, call getActiveOutputChannels().
  147. */
  148. virtual StringArray getOutputChannelNames() = 0;
  149. /** Returns the names of all the available input channels on this device.
  150. To find out which of these are currently in use, call getActiveInputChannels().
  151. */
  152. virtual StringArray getInputChannelNames() = 0;
  153. //==============================================================================
  154. /** Returns the set of sample-rates this device supports.
  155. @see getCurrentSampleRate
  156. */
  157. virtual Array<double> getAvailableSampleRates() = 0;
  158. /** Returns the set of buffer sizes that are available.
  159. @see getCurrentBufferSizeSamples, getDefaultBufferSize
  160. */
  161. virtual Array<int> getAvailableBufferSizes() = 0;
  162. /** Returns the default buffer-size to use.
  163. @returns a number of samples
  164. @see getAvailableBufferSizes
  165. */
  166. virtual int getDefaultBufferSize() = 0;
  167. //==============================================================================
  168. /** Tries to open the device ready to play.
  169. @param inputChannels a BigInteger in which a set bit indicates that the corresponding
  170. input channel should be enabled
  171. @param outputChannels a BigInteger in which a set bit indicates that the corresponding
  172. output channel should be enabled
  173. @param sampleRate the sample rate to try to use - to find out which rates are
  174. available, see getAvailableSampleRates()
  175. @param bufferSizeSamples the size of i/o buffer to use - to find out the available buffer
  176. sizes, see getAvailableBufferSizes()
  177. @returns an error description if there's a problem, or an empty string if it succeeds in
  178. opening the device
  179. @see close
  180. */
  181. virtual String open (const BigInteger& inputChannels,
  182. const BigInteger& outputChannels,
  183. double sampleRate,
  184. int bufferSizeSamples) = 0;
  185. /** Closes and releases the device if it's open. */
  186. virtual void close() = 0;
  187. /** Returns true if the device is still open.
  188. A device might spontaneously close itself if something goes wrong, so this checks if
  189. it's still open.
  190. */
  191. virtual bool isOpen() = 0;
  192. /** Starts the device actually playing.
  193. This must be called after the device has been opened.
  194. @param callback the callback to use for streaming the data.
  195. @see AudioIODeviceCallback, open
  196. */
  197. virtual void start (AudioIODeviceCallback* callback) = 0;
  198. /** Stops the device playing.
  199. Once a device has been started, this will stop it. Any pending calls to the
  200. callback class will be flushed before this method returns.
  201. */
  202. virtual void stop() = 0;
  203. /** Returns true if the device is still calling back.
  204. The device might mysteriously stop, so this checks whether it's
  205. still playing.
  206. */
  207. virtual bool isPlaying() = 0;
  208. /** Returns the last error that happened if anything went wrong. */
  209. virtual String getLastError() = 0;
  210. //==============================================================================
  211. /** Returns the buffer size that the device is currently using.
  212. If the device isn't actually open, this value doesn't really mean much.
  213. */
  214. virtual int getCurrentBufferSizeSamples() = 0;
  215. /** Returns the sample rate that the device is currently using.
  216. If the device isn't actually open, this value doesn't really mean much.
  217. */
  218. virtual double getCurrentSampleRate() = 0;
  219. /** Returns the device's current physical bit-depth.
  220. If the device isn't actually open, this value doesn't really mean much.
  221. */
  222. virtual int getCurrentBitDepth() = 0;
  223. /** Returns a mask showing which of the available output channels are currently
  224. enabled.
  225. @see getOutputChannelNames
  226. */
  227. virtual BigInteger getActiveOutputChannels() const = 0;
  228. /** Returns a mask showing which of the available input channels are currently
  229. enabled.
  230. @see getInputChannelNames
  231. */
  232. virtual BigInteger getActiveInputChannels() const = 0;
  233. /** Returns the device's output latency.
  234. This is the delay in samples between a callback getting a block of data, and
  235. that data actually getting played.
  236. */
  237. virtual int getOutputLatencyInSamples() = 0;
  238. /** Returns the device's input latency.
  239. This is the delay in samples between some audio actually arriving at the soundcard,
  240. and the callback getting passed this block of data.
  241. */
  242. virtual int getInputLatencyInSamples() = 0;
  243. //==============================================================================
  244. /** True if this device can show a pop-up control panel for editing its settings.
  245. This is generally just true of ASIO devices. If true, you can call showControlPanel()
  246. to display it.
  247. */
  248. virtual bool hasControlPanel() const;
  249. /** Shows a device-specific control panel if there is one.
  250. This should only be called for devices which return true from hasControlPanel().
  251. */
  252. virtual bool showControlPanel();
  253. /** On devices which support it, this allows automatic gain control or other
  254. mic processing to be disabled.
  255. If the device doesn't support this operation, it'll return false.
  256. */
  257. virtual bool setAudioPreprocessingEnabled (bool shouldBeEnabled);
  258. //==============================================================================
  259. /** Returns the number of under- or over runs reported by the OS since
  260. playback/recording has started.
  261. This number may be different than determining the Xrun count manually (by
  262. measuring the time spent in the audio callback) as the OS may be doing
  263. some buffering internally - especially on mobile devices.
  264. Returns -1 if playback/recording has not started yet or if getting the underrun
  265. count is not supported for this device (Android SDK 23 and lower).
  266. */
  267. virtual int getXRunCount() const noexcept;
  268. //==============================================================================
  269. protected:
  270. /** Creates a device, setting its name and type member variables. */
  271. AudioIODevice (const String& deviceName,
  272. const String& typeName);
  273. /** @internal */
  274. String name, typeName;
  275. };
  276. } // namespace juce