OSDL::Audio::Music Class Reference

Music is continuous audible content, as opposed to sound. More...

#include <OSDLMusic.h>

Inheritance diagram for OSDL::Audio::Music:

[legend]

Collaboration diagram for OSDL::Audio::Music:

[legend]

List of all members.

Public Member Functions
	Music (const std::string &musicFilename, bool preload=true)
	Creates a new music instance from specified file.
virtual	~Music () throw ()
	Virtual destructor.
virtual bool	load ()
	Loads the music from file.
virtual bool	unload ()
	Unloads the music that may be held by this instance.
virtual Volume	getVolume () const
	Returns the volume associated to this music instance.
virtual void	setVolume (Volume newVolume)
	Sets the volume associated to this music instance.
virtual MusicType	getType () const
	Returns the type of this music (ex: OggVorbis).
virtual void	play (PlaybackCount playCount=1)
	Plays this music instance at once.
virtual void	playWithFadeIn (Ceylan::System::Millisecond fadeInMaxDuration, PlaybackCount playCount=1)
	Plays this music instance at once.
virtual void	playWithFadeInFromPosition (Ceylan::System::Millisecond fadeInMaxDuration, MusicPosition position, PlaybackCount playCount=1)
	Plays this music instance at once from specified position.
virtual bool	isPlaying ()
	Tells whether this music is being played.
virtual void	pause ()
	Pauses the music playback.
virtual void	unpause ()
	Unpauses the music.
virtual void	rewind ()
	Rewinds the music to the start.
virtual void	setPosition (MusicPosition newPosition)
	Sets the position of the currently playing music.
virtual void	stop ()
	Halts playback of music.
virtual void	fadeIn (Ceylan::System::Millisecond fadeInMaxDuration)
	Gradually fades in the music over specified duration, starting from now.
virtual void	fadeOut (Ceylan::System::Millisecond fadeOutMaxDuration)
	Gradually fades out the music over specified duration, starting from now.
virtual const std::string	toString (Ceylan::VerbosityLevels level=Ceylan::high) const
	Returns an user-friendly description of the state of this object.
virtual bool	isConvertedToOutputFormat () const
	Tells whether the internal samples of this audible have already been converted to the sample format used for audio output.
Static Public Member Functions
static void	ManageCurrentMusic ()
	Manages the current music, including regarding the refilling of buffers.
static MusicType	GetTypeOf (const Music *music)
	Returns the type of the specified music (if parameter is not null), or the one of the currently played music (if null).
static std::string	DescribeMusicType (MusicType type)
	Returns a textual description of the specified music type.
static std::string	DescribeBitrateType (BitrateType type)
	Returns a textual description of the specified bitrate type.
static std::string	FindAudiblePath (const std::string &audibleFilename)
	Helper method to find the audible specified by its filename, using audio locators.
Protected Member Functions
virtual void	onPlaybackEnded ()
	Callback automatically called whenever the playback of this music is over.
virtual void	managePlaybackEnded ()
	Manages the notification of a playback end, notably regarding play count.
virtual void	onNoMoreCurrent ()
	Callback automatically called whenever this music was the current one, but it is not anymore.
virtual void	manageNoMoreCurrent ()
	Manages the notification that a music is not current anymore.
virtual void	manageBufferRefill ()
	Triggers any buffer refill, if necessary.
void	fillFirstBuffer ()
	Fills the first half of the double buffer with encoded data read from the music file.
void	fillSecondBuffer ()
	Fills the second half of the double buffer with encoded data read from the music file.
virtual void	setAsCurrent ()
	Sets this music as the current one.
virtual void	requestFillOfFirstBuffer ()
	Sets a corresponding flag in this music instance to notify the main loop the first buffer should be refilled.
virtual void	requestFillOfSecondBuffer ()
	Sets a corresponding flag in this music instance to notify the main loop the second buffer should be refilled.
Static Protected Member Functions
static int	GetLoopsForPlayCount (PlaybackCount playCount)
	Helper method to factorize conversion of play counts into a number of loops.
Protected Attributes
OSDL::Utils::DataStream *	_dataStream
	The internal low level music is defined through the template.
bool	_isPlaying
	Tells whether this music is being played.
bool	_convertedToOutputFormat
	Tells whether the internal samples have been converted already to the sample format used for audio output.
Static Protected Attributes
static Music *	_CurrentMusic = 0
	The music currently being played (if any).
Private Member Functions
	Music (const Music &source)
	The internal low level music is defined through the Ceylan::LoadableWithContent<LowLevelMusic> template.
Music &	operator= (const Music &source)
	Assignment operator made private to ensure that it will be never called.

Detailed Description

Music is continuous audible content, as opposed to sound.

Both are Audible instances.

They are also objects containing a low level sample (here a music), which can be loaded, unloaded, reloaded from file at will. Therefore a Music is (indirectly) a Loadable instance (mother class of the LoadableWithContent template).

Several music instances can exist, but at any given time up to one can be active.

Methods for playing musics are non-blocking: they trigger the playing and return immediately, the execution continues while the playback goes on, unless specified otherwise.

On the PC platform, musics must be OggVorbis (MikMod could be added quite easily).

In the embedded case (Nintendo DS platform), musics can be either RAW with OSDL header, or MP3.

Musics, as opposed to sounds, are streamed chunk after chunk from the media, not read once for all, as a whole, in memory.

See also:: Sound.

Definition at line 351 of file OSDLMusic.h.

Constructor & Destructor Documentation

Music::Music	(	const std::string &	musicFilename,
		bool	preload = `true`
	)			`[explicit]`

Creates a new music instance from specified file.

Parameters:

	musicFilename	the name of the file containing the targeted music. On all PC-like platforms (including Windows and most UNIX), the supported formats are WAVE, MOD, MIDI, OGG, and MP3. OGG and, to a lesser extent, WAVE, are recommended for musics.
	preload	the music will be loaded directly by this constructor iff true, otherwise only its path will be stored to allow for later loading. Anyway only up to the first chunk can be read initially, as it is streamed.

Note:: On some platforms, like the Nintendo DS, too few RAM is available to load a full music in it. Thus the music will always be streamed, and the preload flag will be ignored.

Exceptions:

MusicException

if the operation failed or is not supported.

Definition at line 183 of file OSDLMusic.cc.

References OSDL::Audio::AudioModule::IsAudioInitialized(), and load().

Music::~Music ( ) throw () [virtual]

Virtual destructor.

Definition at line 223 of file OSDLMusic.cc.

References _CurrentMusic, manageNoMoreCurrent(), and unload().

OSDL::Audio::Music::Music ( const Music & source ) [explicit, private]

The internal low level music is defined through the Ceylan::LoadableWithContent<LowLevelMusic> template.

Copy constructor made private to ensure that it will be never called.

The compiler should complain whenever this undefined constructor is called, implicitly or not.

Member Function Documentation

string Music::DescribeBitrateType ( BitrateType type ) [static]

Returns a textual description of the specified bitrate type.

Exceptions:

AudioException

if the operation failed or is not supported.

Definition at line 1358 of file OSDLMusic.cc.

References OSDL::Audio::CBR, and OSDL::Audio::VBR.

string Music::DescribeMusicType ( MusicType type ) [static]

Returns a textual description of the specified music type.

Exceptions:

AudioException

if the operation failed or is not supported.

Definition at line 1312 of file OSDLMusic.cc.

References OSDL::Audio::CommandBased, OSDL::Audio::MIDI, OSDL::Audio::MOD, OSDL::Audio::MP3, OSDL::Audio::NoMusic, OSDL::Audio::OggVorbis, and OSDL::Audio::Wave.

Referenced by toString().

void Music::fadeIn ( Ceylan::System::Millisecond fadeInMaxDuration ) [virtual]

Gradually fades in the music over specified duration, starting from now.

Does nothing if not playing or already fading.

Parameters:

fadeInMaxDuration

duration in milliseconds that the fade-in effect should take to go to full volume from silence, starting now.

Exceptions:

MusicException

if the operation failed, including if not supported.

Definition at line 1046 of file OSDLMusic.cc.

void Music::fadeOut ( Ceylan::System::Millisecond fadeOutMaxDuration ) [virtual]

Gradually fades out the music over specified duration, starting from now.

Does nothing if not playing or already fading. The music will be halted after the fade out is completed.

Parameters:

fadeOutMaxDuration

duration in milliseconds that the fade-out effect should take to go to silence, starting now, and from current volume.

Note:: The onPlaybackEnded method will be automatically called when the current music stops.

Exceptions:

MusicException

if the operation failed, including if not supported.

Definition at line 1077 of file OSDLMusic.cc.

void Music::fillFirstBuffer ( ) [protected]

Fills the first half of the double buffer with encoded data read from the music file.

Updates the corresponding size available for reading.

Exceptions:

AudioException

if the filling failed.

Definition at line 1497 of file OSDLMusic.cc.

References LOG_DEBUG_AUDIO, LOG_TRACE_AUDIO, OSDL::Data::music, and OSDL::Video::Pixels::toString().

Referenced by load(), and manageBufferRefill().

void Music::fillSecondBuffer ( ) [protected]

Fills the second half of the double buffer with encoded data read from the music file.

Updates the corresponding size available for reading.

Exceptions:

AudioException

if the filling failed.

Definition at line 1593 of file OSDLMusic.cc.

References LOG_DEBUG_AUDIO, LOG_TRACE_AUDIO, OSDL::Data::music, and OSDL::Video::Pixels::toString().

Referenced by manageBufferRefill().

string Audible::FindAudiblePath ( const std::string & audibleFilename ) [static, inherited]

Helper method to find the audible specified by its filename, using audio locators.

Note:: Starts by searching the current directory, before using the locator paths.

Parameters:

audibleFilename

the filename of the file where the audible is stored.

Exceptions:

AudibleException

if the operation failed, including if the file could not be found despite audio path locator.

Definition at line 130 of file OSDLAudible.cc.

References OSDL::Audio::AudioModule::AudioFileLocator, OSDL::Audio::AudioModule::AudioPathEnvironmentVariable, and OSDL::Audio::Audible::toString().

int Audible::GetLoopsForPlayCount ( PlaybackCount playCount ) [static, protected, inherited]

Helper method to factorize conversion of play counts into a number of loops.

Exceptions:

AudibleException

if the play count is out of bounds (must be either -1 for infinite looping or strictly superior to zero).

Definition at line 186 of file OSDLAudible.cc.

References OSDL::Audio::Loop, and OSDL::Video::Pixels::toString().

Referenced by OSDL::Audio::Sound::play(), play(), OSDL::Audio::Sound::playForAtMost(), OSDL::Audio::Sound::playForAtMostReturnChannel(), OSDL::Audio::Sound::playReturnChannel(), OSDL::Audio::Sound::playWithFadeIn(), playWithFadeIn(), OSDL::Audio::Sound::playWithFadeInForAtMost(), OSDL::Audio::Sound::playWithFadeInForAtMostReturnChannel(), playWithFadeInFromPosition(), and OSDL::Audio::Sound::playWithFadeInReturnChannel().

MusicType Music::getType ( ) const [virtual]

Returns the type of this music (ex: OggVorbis).

Exceptions:

AudioException

if the operation failed or is not supported.

Definition at line 634 of file OSDLMusic.cc.

References GetTypeOf().

Referenced by toString().

MusicType Music::GetTypeOf ( const Music * music ) [static]

Returns the type of the specified music (if parameter is not null), or the one of the currently played music (if null).

Exceptions:

AudioException

if the operation failed or is not supported.

Note:: Used to avoid code duplication with Audio module, prefer using directly the getType method.

Definition at line 1239 of file OSDLMusic.cc.

References OSDL::Audio::CommandBased, OSDL::Audio::MIDI, OSDL::Audio::MOD, OSDL::Audio::MP3, OSDL::Audio::NoMusic, OSDL::Audio::OggVorbis, OSDL::Audio::Unknown, and OSDL::Audio::Wave.

Referenced by getType(), and OSDL::Audio::AudioModule::getTypeOfCurrentMusic().

Volume Music::getVolume ( ) const [virtual]

Returns the volume associated to this music instance.

Ranges from MinVolume to MaxVolume.

Exceptions:

MusicException

if the operation failed, including if not supported or if no previously loaded music is available.

Implements OSDL::Audio::Audible.

Definition at line 546 of file OSDLMusic.cc.

Referenced by toString().

bool Audible::isConvertedToOutputFormat ( ) const [virtual, inherited]

Tells whether the internal samples of this audible have already been converted to the sample format used for audio output.

Returns:: true iff the samples are already converted.

Definition at line 105 of file OSDLAudible.cc.

References OSDL::Audio::Audible::_convertedToOutputFormat.

bool Music::isPlaying ( ) [virtual]

Tells whether this music is being played.

Note:: A paused music is deemed playing.

Definition at line 833 of file OSDLMusic.cc.

References _isPlaying.

bool Music::load ( ) [virtual]

Loads the music from file.

Returns:: true iff the music had to be actually loaded (otherwise it was already loaded and nothing was done).

Exceptions:

Ceylan::LoadableException

whenever the loading fails.

Definition at line 274 of file OSDLMusic.cc.

References OSDL::Audio::Audible::_convertedToOutputFormat, _dataStream, OSDL::Utils::createDataStreamFrom(), OSDL::DescribeFileTag(), fillFirstBuffer(), LOG_DEBUG_AUDIO, OSDL::Data::music, OSDL::MusicTag, and OSDL::Video::Pixels::toString().

Referenced by Music(), play(), and playWithFadeIn().

void Music::manageBufferRefill ( ) [protected, virtual]

Triggers any buffer refill, if necessary.

Helper method to be used by the main loop.

Exceptions:

AudioException

if a refill failed.

Definition at line 1480 of file OSDLMusic.cc.

References fillFirstBuffer(), and fillSecondBuffer().

Referenced by ManageCurrentMusic().

void Music::ManageCurrentMusic ( ) [static]

Manages the current music, including regarding the refilling of buffers.

To be called from the main loop.

Exceptions:

AudioException

if the operation failed.

Definition at line 1224 of file OSDLMusic.cc.

References _CurrentMusic, and manageBufferRefill().

void Music::manageNoMoreCurrent ( ) [protected, virtual]

Manages the notification that a music is not current anymore.

Called by the Command Manager. Calls the possibly user-overriden onNoMoreCurrent.

Exceptions:

AudioException

if the operation failed.

Definition at line 1439 of file OSDLMusic.cc.

References _CurrentMusic, _isPlaying, LOG_TRACE_AUDIO, and onNoMoreCurrent().

Referenced by managePlaybackEnded(), setAsCurrent(), and ~Music().

void Music::managePlaybackEnded ( ) [protected, virtual]

Manages the notification of a playback end, notably regarding play count.

Called by the Command Manager. Calls the possibly user-overriden onPlaybackEnded.

Definition at line 1393 of file OSDLMusic.cc.

References _isPlaying, generate_master_palette::count, LOG_DEBUG_AUDIO, manageNoMoreCurrent(), onPlaybackEnded(), play(), OSDL::Video::Pixels::toString(), and unload().

void Music::onNoMoreCurrent ( ) [protected, virtual]

Callback automatically called whenever this music was the current one, but it is not anymore.

When playing a music more than once, it always remains current during the whole playback (current status not toggled when stopping and restarting).

Note:: Made to be overriden, this default implementation does nothing except logging the call.

Exceptions:

AudioException

if the operation failed.

See also:: setAsCurrent

Definition at line 1429 of file OSDLMusic.cc.

References LOG_WARNING_AUDIO, and toString().

Referenced by manageNoMoreCurrent().

void Music::onPlaybackEnded ( ) [protected, virtual]

Callback automatically called whenever the playback of this music is over.

Note:: Will be called each time the music ends, including if multiple playbacks in a row were requested. Ex: called 3 times if requested play count is 3.; Made to be overriden, this default implementation does nothing except logging the call.

Exceptions:

AudioException

if the operation failed.

Definition at line 1383 of file OSDLMusic.cc.

References LOG_TRACE_AUDIO.

Referenced by managePlaybackEnded().

Music& OSDL::Audio::Music::operator= ( const Music & source ) [private]

Assignment operator made private to ensure that it will be never called.

The compiler should complain whenever this undefined operator is called, implicitly or not.

void Music::pause ( ) [virtual]

Pauses the music playback.

Paused music can be halted. Music can only be paused if it is actively playing.

Exceptions:

MusicException

if the operation failed, including if not supported.

Definition at line 842 of file OSDLMusic.cc.

void Music::play ( PlaybackCount playCount = 1 ) [virtual]

Plays this music instance at once.

Returns immediately, the playback taking place on the background.

The previous music will be halted, or, if fading out, this music waits (blocking) for the previous to finish.

Parameters:

playCount

the number of times this music should be played from start to finish, unless stopped. The previous music will be halted, or, if fading out, this method waits (blocking) for that to finish. A count of -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

On the Nintendo DS, a command manager is expected to be already available before playback.

Exceptions:

AudibleException

if the operation failed, including if not supported .

Implements OSDL::Audio::Audible.

Definition at line 661 of file OSDLMusic.cc.

References _isPlaying, OSDL::Audio::Audible::GetLoopsForPlayCount(), load(), OSDL::Audio::Loop, and unload().

Referenced by managePlaybackEnded(), and OSDL::Audio::MusicPlaybackSetting::startPlayback().

void Music::playWithFadeIn	(	Ceylan::System::Millisecond	fadeInMaxDuration,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this music instance at once.

Returns immediately, the playback taking place on the background.

The previous music will be halted, or, if fading out, this music waits (blocking) for the previous to finish.

Parameters:

	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume. The fade in effect only applies to the first loop.
	playCount	the number of times this music should be played from start to finish, unless stopped. The previous music will be halted, or, if fading out, this method waits (blocking) for that to finish. A count of -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported.

Note:: On the Nintendo DS, the fade-in duration cannot be set.

Implements OSDL::Audio::Audible.

Definition at line 733 of file OSDLMusic.cc.

References _isPlaying, OSDL::Audio::Audible::GetLoopsForPlayCount(), load(), OSDL::Audio::Loop, and unload().

Referenced by OSDL::Audio::MusicPlaybackSetting::startPlayback().

void Music::playWithFadeInFromPosition	(	Ceylan::System::Millisecond	fadeInMaxDuration,
		MusicPosition	position,
		PlaybackCount	playCount = `1`
	)			`[virtual]`

Plays this music instance at once from specified position.

The previous music will be halted, or, if fading out, this music waits (blocking) for the previous to finish.

Returns immediately, the playback taking place on the background.

Parameters:

	fadeInMaxDuration	duration in milliseconds during which the fade-in effect should take to go from silence to full volume.
	position	the position to play from, expressed in seconds.
	playCount	the number of times this music should be played, unless stopped by halt, fade out, expiration time or audio module stop. -1 means forever. Otherwise it must be strictly positive (exception thrown if zero or below -1).

Exceptions:

AudibleException

if the operation failed, including if not supported.

See also:: Position for its meaning, which depends on the type of the music stream.

Note:: Cannot be inherited from Audible as they have no concept of a position.; Works only for OggVorbis-encoded musics.

Definition at line 804 of file OSDLMusic.cc.

References _isPlaying, and OSDL::Audio::Audible::GetLoopsForPlayCount().

void Music::requestFillOfFirstBuffer ( ) [protected, virtual]

Sets a corresponding flag in this music instance to notify the main loop the first buffer should be refilled.

Called by the CommandManager from an IRQ.

Note:: Used by the Command Manager thanks to the friend declaration.

Definition at line 1139 of file OSDLMusic.cc.

void Music::requestFillOfSecondBuffer ( ) [protected, virtual]

Sets a corresponding flag in this music instance to notify the main loop the second buffer should be refilled.

Called by the CommandManager from an IRQ.

Note:: Used by the Command Manager thanks to the friend declaration.

Definition at line 1152 of file OSDLMusic.cc.

void Music::rewind ( ) [virtual]

Rewinds the music to the start.

This is safe to use on halted, paused, and already playing music. It is not useful to rewind the music immediately after starting playback, because it starts at the beginning by default.

This methods works only for these streams: MOD, OGG, MP3, Native MIDI.

Exceptions:

MusicException

if the operation failed, including if not supported.

Definition at line 946 of file OSDLMusic.cc.

void Music::setAsCurrent ( ) [protected, virtual]

Sets this music as the current one.

Any already current music will be replaced immediately, and be notified of it.

See also:: onNoMoreCurrent

Note:: Used by the Command Manager thanks to the friend declaration.

Exceptions:

AudioException

if the setting failed.

Definition at line 1118 of file OSDLMusic.cc.

References _CurrentMusic, LOG_DEBUG_AUDIO, manageNoMoreCurrent(), and toString().

void Music::setPosition ( MusicPosition newPosition ) [virtual]

Sets the position of the currently playing music.

Parameters:

newPosition

the position to play from.

Exceptions:

MusicException

if the operation failed, including if not supported by OSDL, by the back-end or the underlying codec.

See also:: MusicPosition for its meaning, which depends on the type of the music stream.

Definition at line 965 of file OSDLMusic.cc.

void Music::setVolume ( Volume newVolume ) [virtual]

Sets the volume associated to this music instance.

Setting the volume during a fade will do nothing.

Parameters:

newVolume

the new volume to be set, must range from MinVolume to MaxVolume.

Exceptions:

MusicException

if the operation failed, including if not supported or if no previously loaded music is available.

Implements OSDL::Audio::Audible.

Definition at line 579 of file OSDLMusic.cc.

void Music::stop ( ) [virtual]

Halts playback of music.

This interrupts music fader effects.

Note:: Audio::onMusicPlaybackFinished will be automatically called when the current music (be it this one or another) stops.

Exceptions:

MusicException

if the operation failed, including if not supported.

Definition at line 986 of file OSDLMusic.cc.

Referenced by OSDL::Audio::MusicPlaybackSetting::stopPlayback().

const string Music::toString ( Ceylan::VerbosityLevels level = Ceylan::high ) const [virtual]

Returns an user-friendly description of the state of this object.

Parameters:

level

the requested verbosity level.

Note:: Text output format is determined from overall settings.

See also:: Ceylan::TextDisplayable

Reimplemented from OSDL::Audio::Audible.

Definition at line 1165 of file OSDLMusic.cc.

References _isPlaying, DescribeMusicType(), getType(), getVolume(), OSDL::Audio::AudioModule::MaxVolume, and OSDL::Audio::AudioModule::MinVolume.

Referenced by onNoMoreCurrent(), setAsCurrent(), and OSDL::Audio::MusicPlaybackSetting::toString().

bool Music::unload ( ) [virtual]

Unloads the music that may be held by this instance.

If the music is available (loaded) and if it is playing, it will be halted. If the music is fading out, then this method will wait (blocking) until the fade out is complete.