#include <CUAudioSample.h>

Inheritance diagram for cugl::AudioSample:

Public Types
enum	Type : int { Type::UNKNOWN = -1, Type::WAV_FILE = 0, Type::MP3_FILE = 1, Type::OGG_FILE = 2, Type::FLAC_FILE = 3, Type::IN_MEMORY = 4 }

Public Member Functions
	AudioSample ()

	~AudioSample ()

bool	init (const std::string file, bool stream=false)

bool	init (Uint8 channels, Uint32 rate, Uint32 frames)

bool	initWithData (const std::shared_ptr< JsonValue > &data)

virtual void	dispose () override

bool	isStreamed () const

Type	getType () const

virtual Sint64	getLength () const override

virtual double	getDuration () const override

float *	getBuffer ()

std::shared_ptr< audio::AudioDecoder >	getDecoder ()

virtual std::shared_ptr< audio::AudioNode >	createNode () override

Public Member Functions inherited from cugl::Sound
	Sound ()

	~Sound ()

Uint32	getRate () const

Uint32	getChannels () const

const std::string	getFile () const

const std::string	getSuffix () const

float	getVolume () const

void	setVolume (float volume)

Static Public Member Functions
static Type	guessType (const char *file)

static Type	guessType (const std::string &file)

static std::shared_ptr< AudioSample >	alloc (const std::string file, bool stream=false)

static std::shared_ptr< AudioSample >	alloc (Uint8 channels, Uint32 rate, Uint32 frames)

static std::shared_ptr< AudioSample >	allocWithData (const std::shared_ptr< JsonValue > &data)

Protected Attributes
Uint64	_frames

Type	_type

bool	_stream

float *	_buffer

Protected Attributes inherited from cugl::Sound
Uint8	_channels

Uint32	_rate

std::string	_file

float	_volume

Detailed Description

This class represents a sample that can be played by a audio::AudioPlayer.

This class provides support for both in-memory audio samples and streaming audio. The former is ideal for sound effects, but not long-playing music. The latter introduces some latency and is only ideal for long-playing music.

The choice of buffered or streaming is independent of the file type.
Currently, we support four file types: WAV (including ADPCM encodings), MP3, Ogg (Vorbis), and Flac. As a general rule, we prefer WAV for sound effects and Ogg for music.

All audio samples consist of float-formated PCM data. We assume channels are interleaved. We support up to 32 channels, though it is unlikely for that many channels to be encoded in a sound file. SDL itself only supports 8 channels for (7.1 surround) playback.

Member Enumeration Documentation

◆ Type

enum cugl::AudioSample::Type : int

strong

This enum represents the possible audio sample sources.

Right, we only support file types that are easy to stream into a Linear PCM format. We recommend that you use OGG for music and WAV for sound effects.

Enumerator
UNKNOWN	An unknown audio file source
WAV_FILE	A (Windows-style) WAV file
MP3_FILE	A simple MP3 without VBR encoding
OGG_FILE	An ogg vorbis file
FLAC_FILE	A FLAC file
IN_MEMORY	An in-memory sound source (generator)

Constructor & Destructor Documentation

◆ AudioSample()

cugl::AudioSample::AudioSample ( )

Creates a degenerate audio sample with no buffer.

NEVER USE A CONSTRUCTOR WITH NEW. If you want to allocate an asset on the heap, use one of the static constructors instead.

◆ ~AudioSample()

cugl::AudioSample::~AudioSample ( )

inline

Deletes this audio sample, disposing of all resources.

Member Function Documentation

◆ alloc() [1/2]

static std::shared_ptr<AudioSample> cugl::AudioSample::alloc	(	const std::string	file,
		bool	stream = `false`
	)

inlinestatic

Returns a newly allocated audio sample for the given file.

The choice of buffered or streaming is independent of the file type. If the file is streamed, it will not be loaded into memory. Otherwise, this initializer will allocate memory to read the asset into memory.

Parameters

file	The source file for the audio sample
stream	Wether to stream the audio from the file.

Returns: a newly allocated audio sample for the given file.

◆ alloc() [2/2]

static std::shared_ptr<AudioSample> cugl::AudioSample::alloc	(	Uint8	channels,
		Uint32	rate,
		Uint32	frames
	)

inlinestatic

Returns an empty audio sample of the given size.

The audio sample will be in-memory (not streamed). The contents of the buffer will all be 0s. Use the getBuffer() method to write data to this buffer.

Parameters

channels	the number of audio channels
rate	the sampling rate of this source
frames	the number of frames in this source

Returns: an empty audio sample of the given size.

◆ allocWithData()

static std::shared_ptr<AudioSample> cugl::AudioSample::allocWithData ( const std::shared_ptr< JsonValue > & data )

inlinestatic

Returns a newly allocated audio sample with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports the following attribute values:

 "file":     The path to the source, relative to the asset directory
 "stream":   A boolean, indicating whether to stream the sample
 "volume":   A float, representing the volume

All attributes are optional. There are no required attributes. By default, audio samples are not streamed, meaning they are fully loaded into memory. This is recommended for sound effects, but not for music.

Parameters

data	The JSON object specifying the audio sample

Returns: a newly allocated audio sample with the given JSON specification.

◆ createNode()

virtual std::shared_ptr<audio::AudioNode> cugl::AudioSample::createNode ( )

overridevirtual

Returns a playble audio node for this asset.

This audio node may be attached to an audio::AudioOutput for immediate playback. Nodes are distinct. Each call to this method allocates a new audio node.

Returns: a playble audio node for this asset.

Reimplemented from cugl::Sound.

◆ dispose()

virtual void cugl::AudioSample::dispose ( )

overridevirtual

Deletes the sample resources and resets all attributes.

This will delete the file reference and any allocated buffers. You must reinitialize the sound data to use the object.

Reimplemented from cugl::Sound.

◆ getBuffer()

float* cugl::AudioSample::getBuffer ( )

inline

Returns the underlying PCM data buffer.

This pointer will be null if the sample is streamed. Otherwise, the the buffer will contain channels * frames many elements. It is okay to write data to the buffer, but it cannot be resized or reassigned.

Returns: the underlying PCM data buffer.

◆ getDecoder()

std::shared_ptr<audio::AudioDecoder> cugl::AudioSample::getDecoder ( )

Returns a new decoder for this audio sample

A decoder is used to extract the sound data into a PCM buffer. It should not be accessed directly. Instead it is used by the audio graph to acquire playback data.

Returns: a new decoder for this audio sample

◆ getDuration()

virtual double cugl::AudioSample::getDuration ( ) const

inlineoverridevirtual

Returns the length of this audio sample in seconds.

The accuracy of this method depends on the specific implementation.

Returns: the length of this audio sample in seconds.

Reimplemented from cugl::Sound.

◆ getLength()

virtual Sint64 cugl::AudioSample::getLength ( ) const

inlineoverridevirtual

Returns the frame length of this audio sample.

The frame length is the duration times the sample rate.

Returns: the frame length of this audio sample.

Reimplemented from cugl::Sound.

◆ getType()

Type cugl::AudioSample::getType ( ) const

inline

Returns the encoding type for this audio sample

The type should be one of WAV, MP3, OGG, or FLAC.

Returns: the encoding type for this audio sample

◆ guessType() [1/2]

static Type cugl::AudioSample::guessType ( const char * file )

static

Returns the type suggested by the given file name

The type will be determined from the file extension (e.g. .wav, .mp3, .ogg, etc).

Parameters

file	The file name

Returns: the type suggested by the given file name

◆ guessType() [2/2]

static Type cugl::AudioSample::guessType ( const std::string & file )

inlinestatic

Returns the type suggested by the given file name

The type will be determined from the file extension (e.g. .wav, .mp3, .ogg, etc).

Parameters

file	The file name

Returns: the type suggested by the given file name

◆ init() [1/2]

bool cugl::AudioSample::init	(	const std::string	file,
		bool	stream = `false`
	)

Initializes a new audio sample for the given file.

The choice of buffered or streaming is independent of the file type. If the file is streamed, it will not be loaded into memory. Otherwise, this initializer will allocate memory to read the asset into memory.

Parameters

file	The source file for the audio sample
stream	Wether to stream the audio from the file.

Returns: true if the sound source was initialized successfully

◆ init() [2/2]

bool cugl::AudioSample::init	(	Uint8	channels,
		Uint32	rate,
		Uint32	frames
	)

Initializes an empty audio sample of the given size.

The audio sample will be in-memory (not streamed). The contents of the buffer will all be 0s. Use the getBuffer() method to write data to this buffer.

Parameters

channels	the number of audio channels
rate	the sampling rate of this source
frames	the number of frames in this source

Returns: true if the audio sample was initialized successfully

◆ initWithData()

bool cugl::AudioSample::initWithData ( const std::shared_ptr< JsonValue > & data )

Initializes an audio sample with the given JSON specificaton.

This initializer is designed to receive the "data" object from the JSON passed to Scene2Loader. This JSON format supports the following attribute values:

 "file":     The path to the source, relative to the asset directory
 "stream":   A boolean, indicating whether to stream the sample
 "volume":   A float, representing the volume

All attributes are optional. There are no required attributes. By default, audio samples are not streamed, meaning they are fully loaded into memory. This is recommended for sound effects, but not for music.

Parameters

data	The JSON object specifying the audio sample

Returns: true if the audio sample was initialized successfully

◆ isStreamed()

bool cugl::AudioSample::isStreamed ( ) const

inline

Returns true if this is an streaming audio asset.

This method is to prevent the overhead of run-time typing.

Returns: true if this is an streaming audio asset.

Member Data Documentation

◆ _buffer

float* cugl::AudioSample::_buffer

protected

The in-memory sound buffer for this sound source (OPTIONAL)

◆ _frames

Uint64 cugl::AudioSample::_frames

protected

The number of frames in this audio sample

◆ _stream

bool cugl::AudioSample::_stream

protected

Whether or not this sample is streamed or in-memory

◆ _type

Type cugl::AudioSample::_type

protected

The encoding type (WAV, MP3, OGG, FLAC) of this source

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

include/cugl/audio/CUAudioSample.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ AudioSample()

◆ ~AudioSample()

Member Function Documentation

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ allocWithData()

◆ createNode()

◆ dispose()

◆ getBuffer()

◆ getDecoder()

◆ getDuration()

◆ getLength()

◆ getType()

◆ guessType() [1/2]

◆ guessType() [2/2]

◆ init() [1/2]

◆ init() [2/2]

◆ initWithData()

◆ isStreamed()

Member Data Documentation

◆ _buffer

◆ _frames

◆ _stream

◆ _type