class EE::Audio::InputSoundFile¶

Overview¶

Provide read access to sound files. More…

#include <inputsoundfile.hpp>

class InputSoundFile: private EE::NonCopyable {
public:
    // construction

    ~InputSoundFile();

    // methods

    bool openFromFile(const std::string& filename);
    bool openFromMemory(const void* data, std::size_t sizeInBytes);
    bool openFromStream(IOStream& stream);
    Uint64 getSampleCount() const;
    unsigned int getChannelCount() const;
    unsigned int getSampleRate() const;
    Time getDuration() const;
    Time getTimeOffset() const;
    Uint64 getSampleOffset() const;
    void seek(Uint64 sampleOffset);
    void seek(Time timeOffset);
    Uint64 read(Int16* samples, Uint64 maxCount);
};

Detailed Documentation¶

Provide read access to sound files.

This class decodes audio samples from a sound file. It is used internally by higher-level classes such as SoundBuffer and Music, but can also be useful if you want to process or analyze audio files without playing them, or if you want to implement your own version of Music with more specific features.

Usage example:

// Open a sound file
InputSoundFile file;
if (!file.openFromFile("music.ogg"))
 /* error */;

// Print the sound attributes
std::cout << "duration: " << file.getDuration().asSeconds() << std::endl;
std::cout << "channels: " << file.getChannelCount() << std::endl;
std::cout << "sample rate: " << file.getSampleRate() << std::endl;
std::cout << "sample count: " << file.getSampleCount() << std::endl;

// Read and process batches of samples until the end of file is reached
Int16 samples[1024];
Uint64 count;
do
{
 count = file.read(samples, 1024);

 // process, analyze, play, convert, or whatever
 // you want to do with the samples...
}
while (count > 0);

Methods¶

bool openFromFile(const std::string& filename)

Open a sound file from the disk for reading.

The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit.

Parameters:

filename

Path of the sound file to load

Returns:

True if the file was successfully opened

bool openFromMemory(const void* data, std::size_t sizeInBytes)

Open a sound file in memory for reading.

The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit.

Parameters:

data	Pointer to the file data in memory
sizeInBytes	Size of the data to load, in bytes

Returns:

True if the file was successfully opened

bool openFromStream(IOStream& stream)

Open a sound file from a custom stream for reading.

The supported audio formats are: WAV (PCM only), OGG/Vorbis, FLAC. The supported sample sizes for FLAC and WAV are 8, 16, 24 and 32 bit.

Parameters:

stream

Source stream to read from

Returns:

True if the file was successfully opened

Uint64 getSampleCount() const

Get the total number of audio samples in the file.

Returns:

Number of samples

unsigned int getChannelCount() const

Get the number of channels used by the sound.

Returns:

Number of channels (1 = mono, 2 = stereo)

unsigned int getSampleRate() const

Get the sample rate of the sound.

Returns:

Sample rate, in samples per second

Time getDuration() const

Get the total duration of the sound file.

This function is provided for convenience, the duration is deduced from the other sound file attributes.

Returns:

Duration of the sound file

Time getTimeOffset() const

Get the read offset of the file in time.

Returns:

Time position

Uint64 getSampleOffset() const

Get the read offset of the file in samples.

Returns:

Sample position

void seek(Uint64 sampleOffset)

Change the current read position to the given sample offset.

This function takes a sample offset to provide maximum precision. If you need to jump to a given time, use the other overload.

The sample offset takes the channels into account. If you have a time offset instead, you can easily find the corresponding sample offset with the following formula: timeInSeconds * sampleRate * channelCount If the given offset exceeds to total number of samples, this function jumps to the end of the sound file.

Parameters:

sampleOffset

Index of the sample to jump to, relative to the beginning

void seek(Time timeOffset)

Change the current read position to the given time offset.

Using a time offset is handy but imprecise. If you need an accurate result, consider using the overload which takes a sample offset.

If the given time exceeds to total duration, this function jumps to the end of the sound file.

Parameters:

timeOffset

Time to jump to, relative to the beginning

Uint64 read(Int16* samples, Uint64 maxCount)

Read audio samples from the open file.

Parameters:

samples	Pointer to the sample array to fill
maxCount	Maximum number of samples to read

Returns:

Number of samples actually read (may be less than maxCount)