Provide read access to sound files. More...

#include <SFML/Audio/InputSoundFile.hpp>

Public Member Functions
	InputSoundFile ()=default
	Default constructor.

	InputSoundFile (const std::filesystem::path &filename)
	Construct a sound file from the disk for reading.

	InputSoundFile (const void *data, std::size_t sizeInBytes)
	Construct a sound file in memory for reading.

	InputSoundFile (InputStream &stream)
	Construct a sound file from a custom stream for reading.

bool	openFromFile (const std::filesystem::path &filename)
	Open a sound file from the disk for reading.

bool	openFromMemory (const void *data, std::size_t sizeInBytes)
	Open a sound file in memory for reading.

bool	openFromStream (InputStream &stream)
	Open a sound file from a custom stream for reading.

std::uint64_t	getSampleCount () const
	Get the total number of audio samples in the file.

unsigned int	getChannelCount () const
	Get the number of channels used by the sound.

unsigned int	getSampleRate () const
	Get the sample rate of the sound.

const std::vector< SoundChannel > &	getChannelMap () const
	Get the map of position in sample frame to sound channel.

Time	getDuration () const
	Get the total duration of the sound file.

Time	getTimeOffset () const
	Get the read offset of the file in time.

std::uint64_t	getSampleOffset () const
	Get the read offset of the file in samples.

void	seek (std::uint64_t sampleOffset)
	Change the current read position to the given sample offset.

void	seek (Time timeOffset)
	Change the current read position to the given time offset.

std::uint64_t	read (std::int16_t *samples, std::uint64_t maxCount)
	Read audio samples from the open file.

void	close ()
	Close the current file.

Detailed Description

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 sf::SoundBuffer and sf::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 sf::Music with more specific features.

Usage example:

// Open a sound file
sf::InputSoundFile file("music.ogg");
 
// Print the sound attributes
std::cout << "duration: " << file.getDuration().asSeconds() << '\n'
          << "channels: " << file.getChannelCount() << '\n'
          << "sample rate: " << file.getSampleRate() << '\n'
          << "sample count: " << file.getSampleCount() << std::endl;
 
// Read and process batches of samples until the end of file is reached
std::array<std::int16_t, 1024> samples;
std::uint64_t count;
do
{
    count = file.read(samples.data(), samples.size());
 
    // process, analyze, play, convert, or whatever
    // you want to do with the samples...
}
while (count > 0);

See also: sf::SoundFileReader, sf::OutputSoundFile

Definition at line 51 of file InputSoundFile.hpp.

Constructor & Destructor Documentation

◆ InputSoundFile() [1/4]

sf::InputSoundFile::InputSoundFile ( )

default

Default constructor.

Construct an input sound file that is not associated with a file to read.

◆ InputSoundFile() [2/4]

sf::InputSoundFile::InputSoundFile ( const std::filesystem::path & filename )

explicit

Construct a sound file from the disk for reading.

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

Because of minimp3_ex limitation, for MP3 files with big (>16kb) APEv2 tag, it may not be properly removed, tag data will be treated as MP3 data and there is a low chance of garbage decoded at the end of file. See also: https://github.com/lieff/minimp3

Parameters

filename Path of the sound file to load

Exceptions

`sf::Exception` if opening the file was unsuccessful

◆ InputSoundFile() [3/4]

sf::InputSoundFile::InputSoundFile	(	const void *	data,
		std::size_t	sizeInBytes )

Construct 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

Exceptions

`sf::Exception` if opening the file was unsuccessful

◆ InputSoundFile() [4/4]

sf::InputSoundFile::InputSoundFile ( InputStream & stream )

explicit

Construct 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

Exceptions

`sf::Exception` if opening the file was unsuccessful

Member Function Documentation

◆ close()

void sf::InputSoundFile::close ( )

Close the current file.

◆ getChannelCount()

unsigned int sf::InputSoundFile::getChannelCount ( ) const

nodiscard

Get the number of channels used by the sound.

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

◆ getChannelMap()

const std::vector< SoundChannel > & sf::InputSoundFile::getChannelMap ( ) const

nodiscard

Get the map of position in sample frame to sound channel.

This is used to map a sample in the sample stream to a position during spatialization.

Returns: Map of position in sample frame to sound channel

See also: getSampleRate, getChannelCount, getDuration

◆ getDuration()

Time sf::InputSoundFile::getDuration ( ) const

nodiscard

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

◆ getSampleCount()

std::uint64_t sf::InputSoundFile::getSampleCount ( ) const

nodiscard

Get the total number of audio samples in the file.

Returns: Number of samples

◆ getSampleOffset()

std::uint64_t sf::InputSoundFile::getSampleOffset ( ) const

nodiscard

Get the read offset of the file in samples.

Returns: Sample position

◆ getSampleRate()

unsigned int sf::InputSoundFile::getSampleRate ( ) const

nodiscard

Get the sample rate of the sound.

Returns: Sample rate, in samples per second

◆ getTimeOffset()

Time sf::InputSoundFile::getTimeOffset ( ) const

nodiscard

Get the read offset of the file in time.

Returns: Time position

◆ openFromFile()

bool sf::InputSoundFile::openFromFile ( const std::filesystem::path & filename )

nodiscard

Open a sound file from the disk for reading.

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

Because of minimp3_ex limitation, for MP3 files with big (>16kb) APEv2 tag, it may not be properly removed, tag data will be treated as MP3 data and there is a low chance of garbage decoded at the end of file. See also: https://github.com/lieff/minimp3

Parameters

filename Path of the sound file to load

Returns: true if the file was successfully opened

◆ openFromMemory()

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

nodiscard

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

◆ openFromStream()

bool sf::InputSoundFile::openFromStream ( InputStream & stream )

nodiscard

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

◆ read()

std::uint64_t sf::InputSoundFile::read	(	std::int16_t *	samples,
		std::uint64_t	maxCount )

nodiscard

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)

◆ seek() [1/2]

void sf::InputSoundFile::seek ( std::uint64_t 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

◆ seek() [2/2]

void sf::InputSoundFile::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

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

InputSoundFile.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ InputSoundFile() [1/4]

◆ InputSoundFile() [2/4]

◆ InputSoundFile() [3/4]

◆ InputSoundFile() [4/4]

Member Function Documentation

◆ close()

◆ getChannelCount()

◆ getChannelMap()

◆ getDuration()

◆ getSampleCount()

◆ getSampleOffset()

◆ getSampleRate()

◆ getTimeOffset()

◆ openFromFile()

◆ openFromMemory()

◆ openFromStream()

◆ read()

◆ seek() [1/2]

◆ seek() [2/2]