AudioSource Class Reference

An object responsible for decoding an audio file. More...

#include <audio_source.hpp>

Collaboration diagram for AudioSource:

Public Types
enum	DecodeState : std::uint8_t { DecodeState::WAITING_FOR_FRAME, DecodeState::DECODING, DecodeState::END_OF_FILE }
	An enumeration of possible states the decoder can be in. More...
using	DecodeVector = std::vector< std::uint8_t >
	Type of decoded sample vectors.
using	DecodeResult = std::pair< DecodeState, DecodeVector >
	Type of the result of Decode().

Public Member Functions
	AudioSource (const std::string &path)
	Constructs an AudioSource. More...
virtual	~AudioSource ()=default
	Virtual, empty destructor for AudioSource.
virtual DecodeResult	Decode ()=0
	Performs a round of decoding. More...
virtual std::uint8_t	ChannelCount () const =0
	Returns the channel count. More...
virtual std::uint32_t	SampleRate () const =0
	Returns the sample rate. More...
virtual SampleFormat	OutputSampleFormat () const =0
	Returns the output sample format. More...
virtual std::uint64_t	Seek (std::uint64_t position)=0
	Seeks to the given position, in samples. More...
virtual size_t	BytesPerSample () const
	Returns the number of bytes for each sample this decoder outputs. More...
virtual const std::string &	Path () const
	Gets the file-path of this audio source's audio file. More...
virtual std::uint64_t	SamplesFromMicros (std::uint64_t micros) const
	Converts a position in microseconds to an elapsed sample count. More...
std::uint64_t	MicrosFromSamples (std::uint64_t samples) const
	Converts an elapsed sample count to a position in microseconds. More...

Protected Attributes
std::string	path
	The file-path of this AudioSource's audio file.

Detailed Description

An object responsible for decoding an audio file.

AudioSource is an abstract base class, implemented separately for each supported audio file format.

See also

Mp3AudioSource

SndfileAudioSource

Note

When we refer to 'samples' in this class, this usually refers to the smallest unit of data for all channels. Some audio decoders call the smallest unit of data for one channel a 'sample'–so that there are exactly ChannelCount() of their samples to one of ours. We usually call this a 'mono sample'.

Definition at line 35 of file audio_source.hpp.

Member Enumeration Documentation

DecodeState

enum AudioSource::DecodeState : std::uint8_t

strong

An enumeration of possible states the decoder can be in.

Enumerator
WAITING_FOR_FRAME	The decoder is currently trying to acquire a frame.
DECODING	The decoder is currently decoding a frame.
END_OF_FILE	The decoder has run out of things to decode.

Definition at line 39 of file audio_source.hpp.

                           : std::uint8_t {
        WAITING_FOR_FRAME,
        DECODING,
        END_OF_FILE
    };

Constructor & Destructor Documentation

AudioSource()

AudioSource::AudioSource

(

const std::string &

path

)

Constructs an AudioSource.

Parameters

path	The path to the file from which this AudioSource is decoding.

Definition at line 16 of file audio_source.cpp.

                                              : path(path)
{
}

Member Function Documentation

BytesPerSample()

size_t AudioSource::BytesPerSample ( ) const

virtual

Returns the number of bytes for each sample this decoder outputs.

As the decoder returns packed samples, this includes the channel count as a factor.

Returns

The number of bytes per sample.

Definition at line 20 of file audio_source.cpp.

References ChannelCount(), OutputSampleFormat(), and SAMPLE_FORMAT_BPS.

{
    auto sf = static_cast<uint8_t>(this->OutputSampleFormat());
    return SAMPLE_FORMAT_BPS[sf] * this->ChannelCount();
}

ChannelCount()

virtual std::uint8_t AudioSource::ChannelCount ( ) const

pure virtual

Returns the channel count.

Returns

The number of channels this AudioSource is decoding.

Referenced by BytesPerSample(), and SdlAudioSink::SdlAudioSink().

Decode()

virtual DecodeResult AudioSource::Decode ( )

pure virtual

Performs a round of decoding.

Returns

A pair of the decoder's state upon finishing the decoding round and the vector of bytes decoded. The vector may be empty, if the decoding round did not finish off a frame.

MicrosFromSamples()

std::uint64_t AudioSource::MicrosFromSamples

(

std::uint64_t

samples

)

const

Converts an elapsed sample count to a position in microseconds.

Parameters

samples

The number of elapsed samples.

Returns

The corresponding song position, in microseconds.

Definition at line 40 of file audio_source.cpp.

References SampleRate().

{
    // This is basically SamplesFromMicros but backwards.

    return (samples * 1000000) / this->SampleRate();
}

OutputSampleFormat()

virtual SampleFormat AudioSource::OutputSampleFormat ( ) const

pure virtual

Returns the output sample format.

Returns

The output sample format, as a SampleFormat.

Referenced by BytesPerSample(), and SdlAudioSink::SdlAudioSink().

Path()

const std::string & AudioSource::Path ( ) const

virtual

Gets the file-path of this audio source's audio file.

Returns

The audio file's path.

Definition at line 26 of file audio_source.cpp.

References path.

{
    return this->path;
}

SampleRate()

virtual std::uint32_t AudioSource::SampleRate ( ) const

pure virtual

Returns the sample rate.

Should fail if, for some peculiar reason, the sample rate is above ((2^31) - 1)Hz; this probably implies something is wrong anyway.

Returns

The output sample rate (Hz) as a 32-bit unsigned integer.

Referenced by MicrosFromSamples(), SamplesFromMicros(), and SdlAudioSink::SdlAudioSink().

SamplesFromMicros()

std::uint64_t AudioSource::SamplesFromMicros ( std::uint64_t  micros ) const

virtual

Converts a position in microseconds to an elapsed sample count.

Parameters

micros

The song position, in microseconds.

Returns

The corresponding number of elapsed samples.

Definition at line 31 of file audio_source.cpp.

References SampleRate().

{
    // The sample rate is expressed in terms of samples per second, so we
    // need to convert the position to seconds then multiply by the rate.
    // We do things in a slightly peculiar order to minimise rounding.

    return (micros * this->SampleRate()) / 1000000;
}

Seek()

virtual std::uint64_t AudioSource::Seek ( std::uint64_t  position )

pure virtual

Seeks to the given position, in samples.

For convenience, the new position (in terms of samples) is returned.

Parameters

position

The requested new position in the file, in samples.

Returns

The new position in the file, in samples.

---

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

• src/audio/audio_source.hpp
• src/audio/audio_source.cpp