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