#include <CUAudioDecoder.h>

Public Member Functions
	AudioDecoder ()

	~AudioDecoder ()

bool	init (const std::string file)

bool	init (const std::string file, AudioType type)

void	dispose ()

double	getDuration () const

Uint32	getSampleRate () const

Uint64	getLength () const

Uint32	getChannels () const

std::string	getFile () const

Uint32	getPageSize () const

bool	ready ()

Sint32	pagein (float *buffer)

Uint32	getPage () const

void	setPage (Uint32 page)

Uint32	getPageCount () const

void	rewind ()

Sint64	decode (float *buffer)

Static Public Member Functions
static std::shared_ptr< AudioDecoder >	alloc (const std::string file)

static std::shared_ptr< AudioDecoder >	alloc (const std::string file, AudioType type)

Protected Attributes
std::string	_file

AudioType	_type

Uint8	_channels

Uint32	_rate

Uint64	_frames

Uint32	_pagesize

Uint32	_currpage

Uint32	_lastpage

CODEC_Source *	_source

Detailed Description

This class represents an audio file decoder.

An audio file decoder takes an audio file and converts into a linear-PCM stream. This stream is used by the classes AudioSample (to read the audio data into memory) and audio::AudioPlayer (to play an audio stream directly from the file).

This decoder supports all the file types in AudioType, with the exception of AudioType#IN_MEMORY. The restrictions for the various file types are described in the enumeration for that type.

This class ensures that all memory pages are uniform in size. When the page size is variable, this decoder tries to balance memory requirements paging efficiency.

The decoder always interleaves the audio channels. MP3 and WAV ADPCM only support mono or stereo. But all other formats can support more channels. SDL supports up to 8 channels (7.1 stereo) in general. Note that the channel layout for OGG data is nonstandard (e.g. channels > 3 are not stereo compatible), so this decoder standardizes the channel layout to agree with FLAC and other data encodings.

A decoder is NOT thread safe. If a decoder is used by an audio thread, then it should not be accessed directly in the main thread, and vice versa.

Constructor & Destructor Documentation

◆ AudioDecoder()

cugl::AudioDecoder::AudioDecoder ( )

Creates an initialized audio decoder

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

◆ ~AudioDecoder()

cugl::AudioDecoder::~AudioDecoder ( )

inline

Deletes this decoder, disposing of all resources.

Member Function Documentation

◆ alloc() [1/2]

static std::shared_ptr< AudioDecoder > cugl::AudioDecoder::alloc ( const std::string file )

inlinestatic

Creates a newly allocated decoder for the given file.

The AudioType of the file will be inferred from the file suffix. If this audio type is not correct, this allocator will fail and return nullptr.

Parameters

file	the source file for the decoder

Returns: a newly allocated decoder for the given file.

◆ alloc() [2/2]

static std::shared_ptr< AudioDecoder > cugl::AudioDecoder::alloc	(	const std::string	file,
		AudioType	type
	)

inlinestatic

Creates a newly allocated decoder for the given file.

If the audio type is not correct for this file, this allocator will fail and return nullptr.

Parameters

file	the source file for the decoder
type	the codec type for this file

Returns: a newly allocated decoder for the given file.

◆ decode()

Sint64 cugl::AudioDecoder::decode ( float * buffer )

Decodes the entire audio file, storing its value in buffer.

The buffer should be able to hold channels * frames many elements. The data is interpretted as floats and channels are all interleaved. If the method returns -1, then an error occurred during reading.

Parameters

buffer The buffer to store the audio data

Returns: the number of frames actually read (-1 on error).

◆ dispose()

void cugl::AudioDecoder::dispose ( )

Deletes the decoder resources and resets all attributes.

This will close the associated file. You must reinitialize the decoder to use it.

◆ getChannels()

Uint32 cugl::AudioDecoder::getChannels ( ) const

inline

Returns the number of channels used by this sound source

A value of 1 means mono, while 2 means stereo. Depending on the file format, other channels are possible. For example, 6 channels means support for 5.1 surround sound.

We support up to 32 possible channels.

Returns: the number of channels used by this sound asset

◆ getDuration()

double cugl::AudioDecoder::getDuration ( ) const

inline

Returns the length of this sound source in seconds.

The accuracy of this method depends on the specific implementation.

Returns: the length of this sound source in seconds.

◆ getFile()

std::string cugl::AudioDecoder::getFile ( ) const

inline

Returns the file for this audio source

This value is the empty string if there was no source file.

Returns: the file for this audio source

◆ getLength()

Uint64 cugl::AudioDecoder::getLength ( ) const

inline

Returns the frame length of this sound source.

The frame length is the duration times the sample rate.

Returns: the frame length of this sound source.

◆ getPage()

Uint32 cugl::AudioDecoder::getPage ( ) const

inline

Returns the current page of this decoder

This value is the next page to be read in with the pagein() command.

Returns: the current page of this decoder

◆ getPageCount()

Uint32 cugl::AudioDecoder::getPageCount ( ) const

inline

Returns the total number of pages in this decoder

This value is the maximum value for the setPage command.

Returns: total number of pages in this decoder

◆ getPageSize()

Uint32 cugl::AudioDecoder::getPageSize ( ) const

inline

Returns the number of frames in a single page of data

When multiplied by the number of channels, this gives the number of samples read per page

Returns: the number of frames in a single page of data

◆ getSampleRate()

Uint32 cugl::AudioDecoder::getSampleRate ( ) const

inline

Returns the sample rate of this sound source.

Returns: the sample rate of this sound source.

◆ init() [1/2]

bool cugl::AudioDecoder::init ( const std::string file )

Initializes a new decoder for the given file.

The AudioType of the file will be inferred from the file suffix. If this audio type is not correct, this initializer will fail and return false.

Parameters

file	the source file for the decoder

Returns: true if the decoder was initialized successfully

◆ init() [2/2]

bool cugl::AudioDecoder::init	(	const std::string	file,
		AudioType	type
	)

Initializes a new decoder for the given file and type.

If the audio type is not correct for this file, this initializer will fail and return false.

Parameters

file	the source file for the decoder
type	the codec type for this file

Returns: true if the decoder was initialized successfully

◆ pagein()

Sint32 cugl::AudioDecoder::pagein ( float * buffer )

Reads a page of data into the provided buffer.

The buffer should be able to hold channels * page size many elements. The data is interpretted as floats and channels are all interleaved. If a full page is read, this method should return the page size. If it reads less, it will return the number of frames read. It will return -1 on a processing error.

Parameters

buffer The buffer to store the audio data

Returns: the number of frames actually read (-1 on error).

◆ ready()

bool cugl::AudioDecoder::ready ( )

inline

Returns true if there are still data to be read by the decoder

This value will return false if the decoder is at the end of the file

Returns: true if there are still data to be read by the decoder

◆ rewind()

void cugl::AudioDecoder::rewind ( )

inline

Rewinds this decoder back the beginning of the stream

◆ setPage()

void cugl::AudioDecoder::setPage ( Uint32 page )

Sets the current page of this decoder

This value is the next page to be read in with the pagein() command. If the page is greater than the total number of pages, it will be set just beyond the last page.

Parameters

page	The new page of this decoder

Member Data Documentation

◆ _channels

Uint8 cugl::AudioDecoder::_channels

protected

The number of channels in this sound source (max 32)

◆ _currpage

Uint32 cugl::AudioDecoder::_currpage

protected

The current page in the stream

◆ _file

std::string cugl::AudioDecoder::_file

protected

The source for this decoder

◆ _frames

Uint64 cugl::AudioDecoder::_frames

protected

The number of frames in this sounds source

◆ _lastpage

Uint32 cugl::AudioDecoder::_lastpage

protected

The final page in the stream

◆ _pagesize

Uint32 cugl::AudioDecoder::_pagesize

protected

The size of a decoder chunk

◆ _rate

Uint32 cugl::AudioDecoder::_rate

protected

The sampling rate (frequency) of this sound source

◆ _source

CODEC_Source* cugl::AudioDecoder::_source

protected

The underlying decoder from SDL_codec

◆ _type

AudioType cugl::AudioDecoder::_type

protected

The codec type for the audio file

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

cugl/include/cugl/audio/CUAudioDecoder.h

Public Member Functions

Static Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ AudioDecoder()

◆ ~AudioDecoder()

Member Function Documentation

◆ alloc() [1/2]

◆ alloc() [2/2]

◆ decode()

◆ dispose()

◆ getChannels()

◆ getDuration()

◆ getFile()

◆ getLength()

◆ getPage()

◆ getPageCount()

◆ getPageSize()

◆ getSampleRate()

◆ init() [1/2]

◆ init() [2/2]

◆ pagein()

◆ ready()

◆ rewind()

◆ setPage()

Member Data Documentation

◆ _channels

◆ _currpage

◆ _file

◆ _frames

◆ _lastpage

◆ _pagesize

◆ _rate

◆ _source

◆ _type