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

#include <Music.hpp>

Inheritance diagram for sf::Music:

Collaboration diagram for sf::Music:

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

Public Types
typedef Span< Time >	TimeSpan

Public Types inherited from sf::SoundSource
enum	Status { Stopped , Paused , Playing }
	Enumeration of the sound source states. More...

Public Member Functions
	Music ()
	Default constructor. More...

	~Music ()
	Destructor. More...

bool	openFromFile (const std::string &filename)
	Open a music from an audio file. More...

bool	openFromMemory (const void *data, std::size_t sizeInBytes)
	Open a music from an audio file in memory. More...

bool	openFromStream (InputStream &stream)
	Open a music from an audio file in a custom stream. More...

Time	getDuration () const
	Get the total duration of the music. More...

TimeSpan	getLoopPoints () const
	Get the positions of the of the sound's looping sequence. More...

void	setLoopPoints (TimeSpan timePoints)
	Sets the beginning and end of the sound's looping sequence using sf::Time. More...

Public Member Functions inherited from sf::SoundStream
virtual	~SoundStream ()
	Destructor. More...

void	play ()
	Start or resume playing the audio stream. More...

void	pause ()
	Pause the audio stream. More...

void	stop ()
	Stop playing the audio stream. More...

unsigned int	getChannelCount () const
	Return the number of channels of the stream. More...

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

Status	getStatus () const
	Get the current status of the stream (stopped, paused, playing) More...

void	setPlayingOffset (Time timeOffset)
	Change the current playing position of the stream. More...

Time	getPlayingOffset () const
	Get the current playing position of the stream. More...

void	setLoop (bool loop)
	Set whether or not the stream should loop after reaching the end. More...

bool	getLoop () const
	Tell whether or not the stream is in loop mode. More...

Public Member Functions inherited from sf::SoundSource
	SoundSource (const SoundSource &copy)
	Copy constructor. More...

virtual	~SoundSource ()
	Destructor. More...

void	setPitch (float pitch)
	Set the pitch of the sound. More...

void	setVolume (float volume)
	Set the volume of the sound. More...

void	setPosition (float x, float y, float z)
	Set the 3D position of the sound in the audio scene. More...

void	setPosition (const Vector3f &position)
	Set the 3D position of the sound in the audio scene. More...

void	setRelativeToListener (bool relative)
	Make the sound's position relative to the listener or absolute. More...

void	setMinDistance (float distance)
	Set the minimum distance of the sound. More...

void	setAttenuation (float attenuation)
	Set the attenuation factor of the sound. More...

float	getPitch () const
	Get the pitch of the sound. More...

float	getVolume () const
	Get the volume of the sound. More...

Vector3f	getPosition () const
	Get the 3D position of the sound in the audio scene. More...

bool	isRelativeToListener () const
	Tell whether the sound's position is relative to the listener or is absolute. More...

float	getMinDistance () const
	Get the minimum distance of the sound. More...

float	getAttenuation () const
	Get the attenuation factor of the sound. More...

SoundSource &	operator= (const SoundSource &right)
	Overload of assignment operator. More...

virtual void	play ()=0
	Start or resume playing the sound source. More...

virtual void	pause ()=0
	Pause the sound source. More...

virtual void	stop ()=0
	Stop playing the sound source. More...

virtual Status	getStatus () const
	Get the current status of the sound (stopped, paused, playing) More...

Protected Member Functions
virtual bool	onGetData (Chunk &data)
	Request a new chunk of audio samples from the stream source. More...

virtual void	onSeek (Time timeOffset)
	Change the current playing position in the stream source. More...

virtual Int64	onLoop ()
	Change the current playing position in the stream source to the loop offset. More...

Protected Member Functions inherited from sf::SoundStream
	SoundStream ()
	Default constructor. More...

void	initialize (unsigned int channelCount, unsigned int sampleRate)
	Define the audio stream parameters. More...

virtual bool	onGetData (Chunk &data)=0
	Request a new chunk of audio samples from the stream source. More...

virtual void	onSeek (Time timeOffset)=0
	Change the current playing position in the stream source. More...

virtual Int64	onLoop ()
	Change the current playing position in the stream source to the beginning of the loop. More...

Protected Member Functions inherited from sf::SoundSource
	SoundSource ()
	Default constructor. More...

Additional Inherited Members
Protected Types inherited from sf::SoundStream
enum	{ NoLoop = -1 }

Protected Attributes inherited from sf::SoundSource
unsigned int	m_source
	OpenAL source identifier. More...

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:

// Declare a new music
sf::Music music;
 
// Open it from an audio file
if (!music.openFromFile("music.ogg"))
{
    // error...
}
 
// 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.setLoop(true);         // make it loop
 
// Play it
music.play();

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

Definition at line 48 of file Music.hpp.

Member Typedef Documentation

◆ TimeSpan

typedef Span<Time> sf::Music::TimeSpan

Definition at line 87 of file Music.hpp.

Constructor & Destructor Documentation

◆ Music()

sf::Music::Music ( )

Default constructor.

◆ ~Music()

sf::Music::~Music ( )

Destructor.

Member Function Documentation

◆ getDuration()

Time sf::Music::getDuration ( ) const

Get the total duration of the music.

Returns: Music duration

◆ getLoopPoints()

TimeSpan sf::Music::getLoopPoints ( ) const

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()

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

protectedvirtual

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()

virtual Int64 sf::Music::onLoop ( )

protectedvirtual

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 -1 if there's no loop)

Reimplemented from sf::SoundStream.

◆ onSeek()

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

protectedvirtual

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::string & filename )

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

Here is the caller graph for this function:

◆ openFromMemory()

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

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 )

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

◆ setLoopPoints()

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

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

Loop points allow one to specify a pair of positions such that, when the music is enabled for looping, it will seamlessly seek to the beginning whenever it encounters the end. 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:

Music.hpp

Classes

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ TimeSpan

Constructor & Destructor Documentation

◆ Music()

◆ ~Music()

Member Function Documentation

◆ getDuration()

◆ getLoopPoints()

◆ onGetData()

◆ onLoop()

◆ onSeek()

◆ openFromFile()

◆ openFromMemory()

◆ openFromStream()

◆ setLoopPoints()