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
27namespace juce
28{
29
30class 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{
48public:
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{
142public:
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 */
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 */
166
167 //==============================================================================
168 /** Returns the set of sample-rates this device supports.
169 @see getCurrentSampleRate
170 */
172
173 /** Returns the set of buffer sizes that are available.
174 @see getCurrentBufferSizeSamples, getDefaultBufferSize
175 */
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 */
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 */
264
265 /** Returns a mask showing which of the available input channels are currently
266 enabled.
267 @see getInputChannelNames
268 */
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 //==============================================================================
320protected:
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/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
One of these is passed to an AudioIODevice object to stream the audio data in and out.
virtual void audioDeviceIOCallback(const float **inputChannelData, int numInputChannels, float **outputChannelData, int numOutputChannels, int numSamples)=0
Processes a block of incoming and outgoing audio data.
virtual ~AudioIODeviceCallback()=default
Destructor.
virtual void audioDeviceAboutToStart(AudioIODevice *device)=0
Called to indicate that the device is about to start calling back.
virtual void audioDeviceStopped()=0
Called to indicate that the device has stopped.
Base class for an audio device with synchronised input and output channels.
virtual double getCurrentSampleRate()=0
Returns the sample rate that the device is currently using.
virtual int getCurrentBitDepth()=0
Returns the device's current physical bit-depth.
virtual void close()=0
Closes and releases the device if it's open.
virtual bool isPlaying()=0
Returns true if the device is still calling back.
const String & getTypeName() const noexcept
Returns the type of the device.
virtual StringArray getOutputChannelNames()=0
Returns the names of all the available output channels on this device.
virtual StringArray getInputChannelNames()=0
Returns the names of all the available input channels on this device.
virtual Array< int > getAvailableBufferSizes()=0
Returns the set of buffer sizes that are available.
virtual BigInteger getActiveInputChannels() const =0
Returns a mask showing which of the available input channels are currently enabled.
virtual void stop()=0
Stops the device playing.
virtual BigInteger getActiveOutputChannels() const =0
Returns a mask showing which of the available output channels are currently enabled.
virtual Array< double > getAvailableSampleRates()=0
Returns the set of sample-rates this device supports.
virtual int getInputLatencyInSamples()=0
Returns the device's input latency.
virtual int getCurrentBufferSizeSamples()=0
Returns the buffer size that the device is currently using.
const String & getName() const noexcept
Returns the device's name, (as set in the constructor).
virtual int getDefaultBufferSize()=0
Returns the default buffer-size to use.
virtual void start(AudioIODeviceCallback *callback)=0
Starts the device actually playing.
virtual String getLastError()=0
Returns the last error that happened if anything went wrong.
virtual String open(const BigInteger &inputChannels, const BigInteger &outputChannels, double sampleRate, int bufferSizeSamples)=0
Tries to open the device ready to play.
virtual int getOutputLatencyInSamples()=0
Returns the device's output latency.
virtual bool isOpen()=0
Returns true if the device is still open.
An arbitrarily large integer class.
A special array for holding a list of strings.
The JUCE String class!
Definition juce_String.h:43
#define JUCE_API
This macro is added to all JUCE public class declarations.