Streamed music played from an audio file. More...

#include <Music.hpp>

Inheritance diagram for sf::Music:

Classes
struct	Span
	Structure defining a time range using the template type. More...

Public Types
using	TimeSpan = Span<Time>
Public Types inherited from sf::SoundSource
enum class	Status { Stopped , Paused , Playing }
	Enumeration of the sound source states. More...
using	EffectProcessor
	Callable that is provided with sound data for processing.

Public Member Functions
	Music ()
	Default constructor.
	Music (const std::filesystem::path &filename)
	Construct a music from an audio file.
	Music (const void *data, std::size_t sizeInBytes)
	Construct a music from an audio file in memory.
	Music (InputStream &stream)
	Construct a music from an audio file in a custom stream.
	~Music () override
	Destructor.
	Music (Music &&) noexcept
	Move constructor.
Music &	operator= (Music &&) noexcept
	Move assignment.
bool	openFromFile (const std::filesystem::path &filename)
	Open a music from an audio file.
bool	openFromMemory (const void *data, std::size_t sizeInBytes)
	Open a music from an audio file in memory.
bool	openFromStream (InputStream &stream)
	Open a music from an audio file in a custom stream.
Time	getDuration () const
	Get the total duration of the music.
TimeSpan	getLoopPoints () const
	Get the positions of the of the sound's looping sequence.
void	setLoopPoints (TimeSpan timePoints)
	Sets the beginning and duration of the sound's looping sequence using sf::Time.
Public Member Functions inherited from sf::SoundStream
	~SoundStream () override
	Destructor.
	SoundStream (SoundStream &&) noexcept
	Move constructor.
SoundStream &	operator= (SoundStream &&) noexcept
	Move assignment.
void	play () override
	Start or resume playing the audio stream.
void	pause () override
	Pause the audio stream.
void	stop () override
	Stop playing the audio stream.
unsigned int	getChannelCount () const
	Return the number of channels of the stream.
unsigned int	getSampleRate () const
	Get the stream sample rate of the stream.
std::vector< SoundChannel >	getChannelMap () const
	Get the map of position in sample frame to sound channel.
Status	getStatus () const override
	Get the current status of the stream (stopped, paused, playing).
void	setPlayingOffset (Time timeOffset)
	Change the current playing position of the stream.
Time	getPlayingOffset () const
	Get the current playing position of the stream.
void	setLooping (bool loop)
	Set whether or not the stream should loop after reaching the end.
bool	isLooping () const
	Tell whether or not the stream is in loop mode.
void	setEffectProcessor (EffectProcessor effectProcessor) override
	Set the effect processor to be applied to the sound.
Public Member Functions inherited from sf::SoundSource
	SoundSource (const SoundSource &)=default
	Copy constructor.
	SoundSource (SoundSource &&) noexcept=default
	Move constructor.
SoundSource &	operator= (SoundSource &&) noexcept=default
	Move assignment.
virtual	~SoundSource ()=default
	Destructor.
void	setPitch (float pitch)
	Set the pitch of the sound.
void	setPan (float pan)
	Set the pan of the sound.
void	setVolume (float volume)
	Set the volume of the sound.
void	setSpatializationEnabled (bool enabled)
	Set whether spatialization of the sound is enabled.
void	setPosition (const Vector3f &position)
	Set the 3D position of the sound in the audio scene.
void	setDirection (const Vector3f &direction)
	Set the 3D direction of the sound in the audio scene.
void	setCone (const Cone &cone)
	Set the cone properties of the sound in the audio scene.
void	setVelocity (const Vector3f &velocity)
	Set the 3D velocity of the sound in the audio scene.
void	setDopplerFactor (float factor)
	Set the doppler factor of the sound.
void	setDirectionalAttenuationFactor (float factor)
	Set the directional attenuation factor of the sound.
void	setRelativeToListener (bool relative)
	Make the sound's position relative to the listener or absolute.
void	setMinDistance (float distance)
	Set the minimum distance of the sound.
void	setMaxDistance (float distance)
	Set the maximum distance of the sound.
void	setMinGain (float gain)
	Set the minimum gain of the sound.
void	setMaxGain (float gain)
	Set the maximum gain of the sound.
void	setAttenuation (float attenuation)
	Set the attenuation factor of the sound.
float	getPitch () const
	Get the pitch of the sound.
float	getPan () const
	Get the pan of the sound.
float	getVolume () const
	Get the volume of the sound.
bool	isSpatializationEnabled () const
	Tell whether spatialization of the sound is enabled.
Vector3f	getPosition () const
	Get the 3D position of the sound in the audio scene.
Vector3f	getDirection () const
	Get the 3D direction of the sound in the audio scene.
Cone	getCone () const
	Get the cone properties of the sound in the audio scene.
Vector3f	getVelocity () const
	Get the 3D velocity of the sound in the audio scene.
float	getDopplerFactor () const
	Get the doppler factor of the sound.
float	getDirectionalAttenuationFactor () const
	Get the directional attenuation factor of the sound.
bool	isRelativeToListener () const
	Tell whether the sound's position is relative to the listener or is absolute.
float	getMinDistance () const
	Get the minimum distance of the sound.
float	getMaxDistance () const
	Get the maximum distance of the sound.
float	getMinGain () const
	Get the minimum gain of the sound.
float	getMaxGain () const
	Get the maximum gain of the sound.
float	getAttenuation () const
	Get the attenuation factor of the sound.
SoundSource &	operator= (const SoundSource &right)
	Overload of assignment operator.

Protected Member Functions
bool	onGetData (Chunk &data) override
	Request a new chunk of audio samples from the stream source.
void	onSeek (Time timeOffset) override
	Change the current playing position in the stream source.
std::optional< std::uint64_t >	onLoop () override
	Change the current playing position in the stream source to the loop offset.
Protected Member Functions inherited from sf::SoundStream
	SoundStream ()
	Default constructor.
void	initialize (unsigned int channelCount, unsigned int sampleRate, const std::vector< SoundChannel > &channelMap)
	Define the audio stream parameters.
Protected Member Functions inherited from sf::SoundSource
	SoundSource ()=default
	Default constructor.
Protected Member Functions inherited from sf::AudioResource
	AudioResource ()
	Default constructor.
	AudioResource (const AudioResource &)=default
	Copy constructor.
AudioResource &	operator= (const AudioResource &)=default
	Copy assignment.
	AudioResource (AudioResource &&) noexcept=default
	Move constructor.
AudioResource &	operator= (AudioResource &&) noexcept=default
	Move assignment.

Detailed Description

Streamed music played from an audio file.

Musics are sounds that are streamed rather than completely loaded in memory. This is especially useful for compressed musics that usually take hundreds of MB when they are uncompressed: by streaming it instead of loading it entirely, you avoid saturating the memory and have almost no loading delay. This implies that the underlying resource (file, stream or memory buffer) must remain valid for the lifetime of the sf::Music object.

Apart from that, a sf::Music has almost the same features as the sf::SoundBuffer / sf::Sound pair: you can play/pause/stop it, request its parameters (channels, sample rate), change the way it is played (pitch, volume, 3D position, ...), etc.

As a sound stream, a music is played in its own thread in order not to block the rest of the program. This means that you can leave the music alone after calling play(), it will manage itself very well.

Usage example:

// Open a music from an audio file
sf::Music music("music.ogg");
 
// Change some parameters
music.setPosition({0, 1, 10}); // change its 3D position
music.setPitch(2);             // increase the pitch
music.setVolume(50);           // reduce the volume
music.setLooping(true);        // make it loop
 
// Play it
music.play();

See also: sf::Sound, sf::SoundStream

Member Typedef Documentation

◆ TimeSpan

using sf::Music::TimeSpan = Span<Time>

Constructor & Destructor Documentation

◆ Music() [1/5]

sf::Music::Music ( )

Default constructor.

Construct an empty music that does not contain any data.

◆ Music() [2/5]

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

Construct a music from an audio file.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the file must remain accessible until the sf::Music object loads a new music or is destroyed.

Parameters

filename Path of the music file to open

Exceptions

`sf::Exception` if loading was unsuccessful

See also: openFromMemory, openFromStream

◆ Music() [3/5]

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

Construct a music from an audio file in memory.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the data buffer must remain accessible until the sf::Music object loads a new music or is destroyed. That is, you can't deallocate the buffer right after calling this function.

Parameters

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

Exceptions

`sf::Exception` if loading was unsuccessful

See also: openFromFile, openFromStream

◆ Music() [4/5]

sf::Music::Music ( InputStream & stream )

Construct a music from an audio file in a custom stream.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the stream must remain accessible until the sf::Music object loads a new music or is destroyed.

Parameters

stream Source stream to read from

Exceptions

`sf::Exception` if loading was unsuccessful

See also: openFromFile, openFromMemory

◆ ~Music()

sf::Music::~Music ( )

override

Destructor.

◆ Music() [5/5]

sf::Music::Music ( Music && )

noexcept

Move constructor.

Member Function Documentation

◆ getDuration()

Time sf::Music::getDuration ( ) const

nodiscard

Get the total duration of the music.

Returns: Music duration

◆ getLoopPoints()

TimeSpan sf::Music::getLoopPoints ( ) const

nodiscard

Get the positions of the of the sound's looping sequence.

Returns: Loop Time position class.

Warning: Since setLoopPoints() performs some adjustments on the provided values and rounds them to internal samples, a call to getLoopPoints() is not guaranteed to return the same times passed into a previous call to setLoopPoints(). However, it is guaranteed to return times that will map to the valid internal samples of this Music if they are later passed to setLoopPoints().

See also: setLoopPoints

◆ onGetData()

bool sf::Music::onGetData ( Chunk & data )

nodiscardoverrideprotectedvirtual

Request a new chunk of audio samples from the stream source.

This function fills the chunk from the next samples to read from the audio file.

Parameters

data	Chunk of data to fill

Returns: True to continue playback, false to stop

Implements sf::SoundStream.

◆ onLoop()

std::optional< std::uint64_t > sf::Music::onLoop ( )

overrideprotectedvirtual

Change the current playing position in the stream source to the loop offset.

This is called by the underlying SoundStream whenever it needs us to reset the seek position for a loop. We then determine whether we are looping on a loop point or the end-of-file, perform the seek, and return the new position.

Returns: The seek position after looping (or std::nullopt if there's no loop)

Reimplemented from sf::SoundStream.

◆ onSeek()

void sf::Music::onSeek ( Time timeOffset )

overrideprotectedvirtual

Change the current playing position in the stream source.

Parameters

timeOffset New playing position, from the beginning of the music

Implements sf::SoundStream.

◆ openFromFile()

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

nodiscard

Open a music from an audio file.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the file must remain accessible until the sf::Music object loads a new music or is destroyed.

Parameters

filename Path of the music file to open

Returns: True if loading succeeded, false if it failed

See also: openFromMemory, openFromStream

◆ openFromMemory()

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

nodiscard

Open a music from an audio file in memory.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the data buffer must remain accessible until the sf::Music object loads a new music or is destroyed. That is, you can't deallocate the buffer right after calling this function.

Parameters

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

Returns: True if loading succeeded, false if it failed

See also: openFromFile, openFromStream

◆ openFromStream()

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

nodiscard

Open a music from an audio file in a custom stream.

This function doesn't start playing the music (call play() to do so). See the documentation of sf::InputSoundFile for the list of supported formats.

Warning: Since the music is not loaded at once but rather streamed continuously, the stream must remain accessible until the sf::Music object loads a new music or is destroyed.

Parameters

stream Source stream to read from

Returns: True if loading succeeded, false if it failed

See also: openFromFile, openFromMemory

◆ operator=()

Music & sf::Music::operator= ( Music && )

noexcept

Move assignment.

◆ setLoopPoints()

void sf::Music::setLoopPoints ( TimeSpan timePoints )

Sets the beginning and duration of the sound's looping sequence using sf::Time.

setLoopPoints() allows for specifying the beginning offset and the duration of the loop such that, when the music is enabled for looping, it will seamlessly seek to the beginning whenever it encounters the end of the duration. Valid ranges for timePoints.offset and timePoints.length are [0, Dur) and (0, Dur-offset] respectively, where Dur is the value returned by getDuration(). Note that the EOF "loop point" from the end to the beginning of the stream is still honored, in case the caller seeks to a point after the end of the loop range. This function can be safely called at any point after a stream is opened, and will be applied to a playing sound without affecting the current playing offset.

Warning: Setting the loop points while the stream's status is Paused will set its status to Stopped. The playing offset will be unaffected.

Parameters

timePoints The definition of the loop. Can be any time points within the sound's length

See also: getLoopPoints

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

SFML/Audio/Music.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ TimeSpan

Constructor & Destructor Documentation

◆ Music() [1/5]

◆ Music() [2/5]

◆ Music() [3/5]

◆ Music() [4/5]

◆ ~Music()

◆ Music() [5/5]

Member Function Documentation

◆ getDuration()

◆ getLoopPoints()

◆ onGetData()

◆ onLoop()

◆ onSeek()

◆ openFromFile()

◆ openFromMemory()

◆ openFromStream()

◆ operator=()

◆ setLoopPoints()