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

#include <CUAudioSample.h>

Inheritance diagram for cugl::AudioSample:
cugl::Sound

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::AudioDecodergetDecoder ()
 
virtual std::shared_ptr< audio::AudioNodecreateNode () 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< AudioSamplealloc (const std::string file, bool stream=false)
 
static std::shared_ptr< AudioSamplealloc (Uint8 channels, Uint32 rate, Uint32 frames)
 
static std::shared_ptr< AudioSampleallocWithData (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
fileThe source file for the audio sample
streamWether 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
channelsthe number of audio channels
ratethe sampling rate of this source
framesthe 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
dataThe 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
fileThe 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
fileThe 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
fileThe source file for the audio sample
streamWether 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
channelsthe number of audio channels
ratethe sampling rate of this source
framesthe 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
dataThe 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: