CUGL 2.1
Cornell University Game Library
Public Member Functions | Static Public Member Functions | Static Public Attributes | List of all members
cugl::AudioDevices Class Reference

#include <CUAudioDevices.h>

Public Member Functions

Uint32 getReadSize () const
 
Uint32 getWriteSize () const
 
bool isActive ()
 
void activate ()
 
void deactivate ()
 
void reset ()
 
std::shared_ptr< audio::AudioOutputopenOutput ()
 
std::shared_ptr< audio::AudioOutputopenOutput (Uint8 channels, Uint32 rate)
 
std::shared_ptr< audio::AudioOutputopenOutput (const char *device)
 
std::shared_ptr< audio::AudioOutputopenOutput (const std::string &device)
 
std::shared_ptr< audio::AudioOutputopenOutput (const char *device, Uint8 channels, Uint32 rate)
 
std::shared_ptr< audio::AudioOutputopenOutput (const std::string &device, Uint8 channels, Uint32 rate)
 
bool closeOutput (const std::shared_ptr< audio::AudioOutput > &device)
 
std::shared_ptr< audio::AudioInputopenInput ()
 
std::shared_ptr< audio::AudioInputopenInput (Uint8 channels, Uint32 rate, Uint32 delay)
 
std::shared_ptr< audio::AudioInputopenInput (const char *device)
 
std::shared_ptr< audio::AudioInputopenInput (const std::string &device)
 
std::shared_ptr< audio::AudioInputopenInput (const char *device, Uint8 channels, Uint32 rate, Uint32 delay)
 
std::shared_ptr< audio::AudioInputopenInput (const std::string &device, Uint8 channels, Uint32 rate, Uint32 delay)
 
bool closeInput (const std::shared_ptr< audio::AudioInput > &device)
 

Static Public Member Functions

static AudioDevicesget ()
 
static void start ()
 
static void start (Uint32 frames)
 
static void start (Uint32 output, Uint32 input)
 
static void stop ()
 
static std::vector< std::string > devices (bool output)
 
static std::vector< std::string > occupied (bool output)
 

Static Public Attributes

static const Uint32 DEFAULT_OUTPUT_BUFFER
 
static const Uint32 DEFAULT_INPUT_BUFFER
 

Detailed Description

Class providing a singleton audio device manager

This class is provides the most basic support for a modern audio engine. It has a factory for managing multiple input and output devices. However, it is up to the developer to connect these together to form audio graphs. Therefore, a developer should only use this class when direct access to the audio graph is necessary. Most developers can use AudioEngine instead. As that class is built on top of this one, the developer should only ever use one of the two classes.

You cannot create new instances of this class. Instead, you should access the singleton through the three static methods: start(), stop(), and get().

IMPORTANT: Like the OpenGL context, this class is not thread-safe. It is only safe to access this class in the main application thread. This means it should never be called in a call-back function as those are typically executed in the host thread. If you need to access the AudioManager in a callback function, you should use the Application#schedule method to delay until the main thread is next available.

Member Function Documentation

◆ activate()

void cugl::AudioDevices::activate ( )

Activates the audio device manager.

This method is used to resume audio behavior after a call to the method deactivate(). This provides a uniform way of renabling audio devices (such as after an application switch).

This method is not the same as start(). It does not allocate any new resources.

◆ closeInput()

bool cugl::AudioDevices::closeInput ( const std::shared_ptr< audio::AudioInput > &  device)

Closes the output device and disposes all resources.

Once this method is called, the audio::AudioOutput is invalidated and is no longer safe to use.

Parameters
deviceThe output device to close
Returns
whether the device was successfully closed.

◆ closeOutput()

bool cugl::AudioDevices::closeOutput ( const std::shared_ptr< audio::AudioOutput > &  device)

Closes the output device and disposes all resources.

Once this method is called, the audio::AudioOutput is invalidated and is no longer safe to use.

Parameters
deviceThe output device to close
Returns
whether the device was successfully closed.

◆ deactivate()

void cugl::AudioDevices::deactivate ( )

Deactivates the audio device manager.

This method is used to pause all output nodes and release all input nodes from recording. This is important during an application switch, such as when the game goes into the background. All of the devices may be resumed with a call to deactivate().

This method is not the same as stop(). It does not release any resources and no audio graphs are invalidated.

◆ devices()

static std::vector<std::string> cugl::AudioDevices::devices ( bool  output)
static

Returns the list of all the audio devices

This value may change and should be polled regularly to provide an up-to-date list. The provided argument determines whether this is for output or input devices.

Parameters
outputWhether to list output (instead of input) devices
Returns
the list of all the audio devices

◆ get()

static AudioDevices* cugl::AudioDevices::get ( )
inlinestatic

Returns the singleton instance of the device manager.

If the audio manager has not been started, then this method will return nullptr.

Returns
the singleton instance of the audio manager.

◆ getReadSize()

Uint32 cugl::AudioDevices::getReadSize ( ) const
inline

Returns the size of the read buffer (in frames) for output nodes.

While output devices do not need to have uniform buffer sizes, we require this to ensure that audio graph nodes are all interchangeable. Therefore, a suitable buffer size (that works for all relevant devices) should be set at activation.

Note that the value is in frames. Therefore, output devices with different numbers of channels will have a different raw buffer size.

Returns
the size of the read buffer (in frames) for output nodes.

◆ getWriteSize()

Uint32 cugl::AudioDevices::getWriteSize ( ) const
inline

Returns the size of the write buffer (in frames) for input nodes.

While input devices do not need to have uniform buffer sizes, we require this to ensure that audio graph nodes are all interchangeable. Therefore, a suitable buffer size (that works for all relevant devices) should be set at activation.

Note that the value is in frames. Therefore, input devices with different numbers of channels will have a different raw buffer size.

Returns
the size of the write buffer (in frames) for input nodes.

◆ isActive()

bool cugl::AudioDevices::isActive ( )

Returns true if the audio device manager is active.

An active audio manager will regularly poll data from any unpaused output node, and regular write data to any unreleased input node.

Returns
true if the audio manager is active.

◆ occupied()

static std::vector<std::string> cugl::AudioDevices::occupied ( bool  output)
static

Returns the list of devices with attached audio nodes.

If there is an audio node on the default device, this will include the current default. The provided argument determines whether this is for output or input devices.

Parameters
outputWhether to list output (instead of input) devices
Returns
the list of devices with attached audio nodes.

◆ openInput() [1/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( )

Returns the default input device with 2 channels at 48000 Hz.

The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This node is always logically attached to the default input device. That means it will switch devices whenever the default input changes. This method may fail if the default device is in use.

Returns
the default input device with 2 channels at 48000 Hz.

◆ openInput() [2/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( const char *  device)

Returns the given input device with 2 channels at 48000 Hz.

The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
Returns
the given input device with 2 channels at 48000 Hz.

◆ openInput() [3/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( const char *  device,
Uint8  channels,
Uint32  rate,
Uint32  delay 
)

Returns the given output device with the given channels and sample rate.

The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
delayThe playback delay between recording and reading
Returns
the given output device with the given channels and sample rate.

◆ openInput() [4/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( const std::string &  device)

Returns the given input device with 2 channels at 48000 Hz.

The input delay will be equal to the value getWriteSize(). This means that playback is only available after two calls to audio::AudioInput#record(). This is the minimal value for smooth real-time playback of recorded audio.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
Returns
the given input device with 2 channels at 48000 Hz.

◆ openInput() [5/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( const std::string &  device,
Uint8  channels,
Uint32  rate,
Uint32  delay 
)

Returns the given output device with the given channels and sample rate.

The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
delayThe playback delay between recording and reading
Returns
the given output device with the given channels and sample rate.

◆ openInput() [6/6]

std::shared_ptr<audio::AudioInput> cugl::AudioDevices::openInput ( Uint8  channels,
Uint32  rate,
Uint32  delay 
)

Returns the default input device with the given channels and sample rate.

The delay value is the number of frames that must be recorded before a single frame. This determines the playback latency. While it is possible to have a delay of 0, this is unlikely to provide smooth real-time playback of recorded audio. That is because there are no guarantees about the thread interleaving of input and output devices. A delay of at least getWriteSize(), and maybe even more, is recommended.

An input device is initialized with both active as false and record as true. That means it will start recording as soon as the AudioManager is activated. In addition, it is also unpaused, meaning that playback will start as soon as it is attached to an audio graph.

This node is always logically attached to the default input device. That means it will switch devices whenever the default input changes. This method may fail if the default input device is in use.

Parameters
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
delayThe playback delay between recording and reading
Returns
the default input device with the given channels and sample rate.

◆ openOutput() [1/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( )

Returns the default output device with 2 channels at 48000 Hz.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This node is always logically attached to the default output device. That means it will switch devices whenever the default output changes. This method may fail if the default device is in use.

Returns
the default output device with 2 channels at 48000 Hz.

◆ openOutput() [2/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( const char *  device)

Returns the given output device with 2 channels at 48000 Hz.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
Returns
the given output device with 2 channels at 48000 Hz.

◆ openOutput() [3/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( const char *  device,
Uint8  channels,
Uint32  rate 
)

Returns the output device with the given channels and sample rate.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
Returns
the output device with the given channels and sample rate.

◆ openOutput() [4/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( const std::string &  device)

Returns the given output device with 2 channels at 48000 Hz.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
Returns
the given output device with 2 channels at 48000 Hz.

◆ openOutput() [5/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( const std::string &  device,
Uint8  channels,
Uint32  rate 
)

Returns the output device with the given channels and sample rate.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This method may fail if the given device is in use.

Parameters
deviceThe name of the output device
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
Returns
the output device with the given channels and sample rate.

◆ openOutput() [6/6]

std::shared_ptr<audio::AudioOutput> cugl::AudioDevices::openOutput ( Uint8  channels,
Uint32  rate 
)

Returns the default output device with the given channels and sample rate.

An output device is initialized with both active and paused as false. That means it will begin playback as soon as the audio manager is activated.

This node is always logically attached to the default output device. That means it will switch devices whenever the default output changes. This method may fail if the default output device is in use.

Parameters
channelsThe number of audio channels
rateThe sample rate (frequency) in Hz
Returns
the default output device with the given channels and sample rate.

◆ reset()

void cugl::AudioDevices::reset ( )

Resets any stopped or failed audio devices.

This method will also roll over the default output (not input) device if it changes.

This method is necessary for when an audio device is unplugged. While SDL often does this automatically, this method is provided for platforms (e.g. CoreAudio on MacOS) where this must be done explicitly.

◆ start() [1/3]

static void cugl::AudioDevices::start ( )
static

Starts the singleton audio device manager.

Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect. In addition, an audio manager will start off as inactive, and must be activated.

Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.

This method will create a manager where the input and output buffer sizes are the default values.

◆ start() [2/3]

static void cugl::AudioDevices::start ( Uint32  frames)
static

Starts the singleton audio device manager.

Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect. In addition, an audio manager will start off as inactive, and must be activated.

Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.

This method will create a manager where the output and input buffer share the same size.

Parameters
framesThe output and input buffer size in frames.

◆ start() [3/3]

static void cugl::AudioDevices::start ( Uint32  output,
Uint32  input 
)
static

Starts the singleton audio device manager.

Once this method is called, the method get() will no longer return nullptr. Calling the method multiple times (without calling stop) will have no effect. In addition, an audio manager will start off as inactive, and must be activated.

Instances of audio::AudioNode (and its subclasses) cannot be initialized until this manager is activated. That is because audio nodes need a uniform buffer size (set by this method) in order to coordinate with one another.

This method will create a manager where the output and input buffer have the specified sizes. It is not necessary for the buffer value of an input device match the buffer value of an output device. Indeed, on many systems, an input buffer size of less than 1024 samples is not supported, while output devices can process much faster than that. What is important is ensuring enough delay so that the audio graph does not outrun the input device. Therefore, an input delay of less than the input buffer size is not recommended for real-time audio processing.

Parameters
outputThe size of the output buffer in frames.
inputThe size of the input buffer in frames.

◆ stop()

static void cugl::AudioDevices::stop ( )
static

Stops the singleton device manager, releasing all resources.

Once this method is called, the method get() will return nullptr. Calling the method multiple times (without calling stop) will have no effect. In addition, the audio manager will no longer be active.

Once this method is called, all instances of audio::AudioNode become invalid. In addition, no future instances of audio::AudioNode may be created. This method should only be called at application shutdown.

Member Data Documentation

◆ DEFAULT_INPUT_BUFFER

const Uint32 cugl::AudioDevices::DEFAULT_INPUT_BUFFER
static

The default input buffer size for each audio node

◆ DEFAULT_OUTPUT_BUFFER

const Uint32 cugl::AudioDevices::DEFAULT_OUTPUT_BUFFER
static

The default input buffer size for each audio node


The documentation for this class was generated from the following file: