Detailed Description

v2.00 (28 June 2023)
The Audio Music module includes the Music Manager and Music objects.

Once the audio system is initialized using ConfigMgr::audioInit() or ConfigMgr::load(), you can use this manager for loading music files from external files or from a CDC file and play them.
There is a dedicated channel for the music playback and only one music can be played at a given time although you can change to play other one at anytime.

Actions that can be done on a music object:

play, stop, pause and resume
fade out and fade in on a given time
modify music stream time position

Supported music formats:

	Raw streams: WAV and VOC
	Compressed streams: FLAC, Ogg and MP3
	Modules: 669, abc, amf, ams, dbm, dmf, dsm, far, gdm, it, mdl, med, mid, mod, mt2, mtm, okt, pat, psm, ptm, st3m, stm, ult and xm

This is a sharing manager: it has the ability of sharing a music id to a group of owners when they request to open an already opened object based on the name as the key. When the last one of them closes the music id, it will be effectively closed.

Only a single instance of the Music Manager exists which is created once Main is instantiated.
You can get a reference to this manager using Main::IMusicMgr() method.

Note: The Music Manager is automatically released when Main::Terminate() is called.
At this time, any resource still loaded, will be released avoding resource leaks.

Classes
class	CRM64Pro::Music
	Music Object class. More...

class	CRM64Pro::MusicMgr
	Music Manager class. More...

Functions
Sint32	CRM64Pro::Music::info (Sint32 iMode=0)
	Request Music object information.

Sint32	CRM64Pro::Music::getName (string &sName)
	Get the name.

Uint32	CRM64Pro::Music::getID ()
	Get the ID.

Sint32	CRM64Pro::Music::info (string sType, AudioInfo AI)
	Get Music object information.

Sint32	CRM64Pro::Music::play (Sint32 iLoop=0)
	Start playing music.

Sint32	CRM64Pro::Music::fadeIn (Sint32 iTime=1000, Sint32 iLoop=0)
	Start playing music with a fade in effect.

Sint32	CRM64Pro::Music::saveToFile (const string &sFile)
	Export the Music to an external file.

Sint32	CRM64Pro::Music::save (const string &sFileCDC)
	Save the Music in to a CDC file.

Sint32	CRM64Pro::Music::save (Sint32 idCDC)
	Save the Music in to a CDC file.

Sint32	CRM64Pro::MusicMgr::info (Sint32 idMus=0)
	Request Music Manager information.

Sint32	CRM64Pro::MusicMgr::close (Sint32 idMus=0)
	Close and destroy a music.

Sint32	CRM64Pro::MusicMgr::getNum ()
	Get number of loaded objects.

Sint32	CRM64Pro::MusicMgr::setName (Sint32 idMus, const string &sName)
	Change the object name.

Music *	CRM64Pro::MusicMgr::get (Sint32 idMus=0)
	Get a pointer to the music using its handler.

Sint32	CRM64Pro::MusicMgr::stop ()
	Stop music playing.

Sint32	CRM64Pro::MusicMgr::pause ()
	Pause music playing.

Sint32	CRM64Pro::MusicMgr::resume ()
	Resume music playing.

Sint32	CRM64Pro::MusicMgr::status ()
	Get the music status.

Sint32	CRM64Pro::MusicMgr::position (double dPosition)
	Set the current position in the music stream.

Sint32	CRM64Pro::MusicMgr::fadeOut (Sint32 iTime=1000)
	Music fade out effect.

Sint32	CRM64Pro::MusicMgr::loadFromFile (const string &sFile, const string &sName="")
	Load a music from an external file.

Sint32	CRM64Pro::MusicMgr::load (const string &sFileCDC, const string &sName)
	Load a music stored in a CDC file.

Sint32	CRM64Pro::MusicMgr::load (const Sint32 idCDC, const string &sName)
	Load a music stored in a CDC file.

Sint32	CRM64Pro::MusicMgr::remove (const Sint32 idCDC, const string &sName)
	Remove a music stored in a CDC file.

Sint32	CRM64Pro::MusicMgr::exist (Sint32 idCDC, const string &sName)
	Check if a music is stored in a CDC file.

Function Documentation

◆ info() [1/3]

Sint32 CRM64Pro::Music::info ( Sint32 iMode = 0 )

Request Music object information.

For displaying the information, it uses the default log.

Parameters

iMode unused for the time being.

Returns: 0 on success or a negative error code on failure.

◆ getName()

Sint32 CRM64Pro::Music::getName ( string & sName )

Get the name.

Parameters

sName a string containing the Music object name.

Returns: 0 on success or a negative error code on failure.

◆ getID()

Uint32 CRM64Pro::Music::getID ( )

Get the ID.

Returns: the object ID.

◆ info() [2/3]

Sint32 CRM64Pro::Music::info	(	string *	sType,
		AudioInfo *	AI
	)

Get Music object information.

Parameters

sType	an string pointer filled in with the input file music extension. If nullptr is passed, the method ignores the retrieving of this value.
AI	a pointer to an AudioInfo struct. If nullptr is passed, the method ignores the retrieving of this struct.

Returns: 0 on success or a negative error code on failure.

◆ play()

Sint32 CRM64Pro::Music::play ( Sint32 iLoop = 0 )

Start playing music.

Parameters

iLoop number of music playing loops.
By default is set to 0.
0 plays the music just once, 1 twice and -1 plays it forever.

Returns: 0 on success or a negative error code on failure.

◆ fadeIn()

Sint32 CRM64Pro::Music::fadeIn	(	Sint32	iTime = `1000`,
		Sint32	iLoop = `0`
	)

Start playing music with a fade in effect.

Parameters

iTime	time for fading in the music, in milliseconds. By default is set to 1000ms.
iLoop	number of music playing loops. By default is set to 0. 0 plays the music just once, 1 twice and -1 plays it forever.

Returns: 0 on success or a negative error code on failure.

◆ saveToFile()

Sint32 CRM64Pro::Music::saveToFile ( const string & sFile )

Export the Music to an external file.

Parameters

sFile string containing the [directory]+filename.
The extension, if present, is removed and the right extension is automatically added.
If the file already exists, it will be overwritten.
Directory separators '\' and '/' are supported.

Returns: 0 or greater on success or a negative error code on failure.

◆ save() [1/2]

Sint32 CRM64Pro::Music::save ( const string & sFileCDC )

Save the Music in to a CDC file.

If the Music already exists on the CDC, it will be overwritten.

Parameters

sFileCDC string containing the [directory]+filename+[extension].
Directory separators '\' and '/' are supported.

Returns: greater than 0 on success or a negative error code on failure.

Note: If the CDC file is secured, this call will fail. For these cases, open first the CDC using ArchiveMgr::open() and use Music::save() with the CDC id.

◆ save() [2/2]

Sint32 CRM64Pro::Music::save ( Sint32 idCDC )

Save the Music in to a CDC file.

If the Music already exists on the CDC, it will be overwritten.

Parameters

idCDC CDC id.

Returns: greater than 0 on success or a negative error code on failure.

◆ info() [3/3]

Sint32 CRM64Pro::MusicMgr::info ( Sint32 iMode = 0 )

Request Music Manager information.

For displaying the information, it uses the default log.

Parameters

iMode -1 for displaying only Manager information.
0 for displaying Manager and all Objects information. This is the default value.
idMus for displaying Manager and given Music id information.

Returns: 0 on success or a negative error code on failure.

◆ close()

Sint32 CRM64Pro::MusicMgr::close ( Sint32 idMus = 0 )

Close and destroy a music.

Parameters

idMus 0 (default value) for closing all music or the Music id.
As the Music Manager has the ability of sharing a Music id, if the music is shared, it will not be removed till the last owner call this method.

Returns: 0 on success or a negative error code on failure.

Note: If you forget to close a music, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::MusicMgr::getNum ( )

Get number of loaded objects.

Returns: the number of CDC files.

◆ setName()

Sint32 CRM64Pro::MusicMgr::setName	(	Sint32	idMus,
		const string &	sName
	)

Change the object name.

Parameters

idMus	Music id.
sName	The name to give to the music e.g. 'myMusic'. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns: 0 on success or a negative error code on failure.

◆ get()

Music * CRM64Pro::MusicMgr::get ( Sint32 idMus = 0 )

Get a pointer to the music using its handler.

By default it returns the first music loaded.

Parameters

idMus Music id.

Returns: nullptr the music was not found.; A pointer to the music object.

◆ stop()

Sint32 CRM64Pro::MusicMgr::stop ( )

Stop music playing.

Returns: 0 on success or a negative error code on failure.

◆ pause()

Sint32 CRM64Pro::MusicMgr::pause ( )

Pause music playing.

Returns: 0 on success or a negative error code on failure.

◆ resume()

Sint32 CRM64Pro::MusicMgr::resume ( )

Resume music playing.

Returns: 0 on success or a negative error code on failure.

◆ status()

Sint32 CRM64Pro::MusicMgr::status ( )

Get the music status.

Returns

C64_STATUS_DISABLED	music is not playing.
C64_STATUS_ENABLED	music is playing.
C64_STATUS_PAUSED	music playing is paused.

◆ position()

Sint32 CRM64Pro::MusicMgr::position ( double dPosition )

Set the current position in the music stream.

Parameters

dPosition jump to this time position (in seconds).

Returns: 0 on success or a negative error code on failure.

◆ fadeOut()

Sint32 CRM64Pro::MusicMgr::fadeOut ( Sint32 iTime = 1000 )

Music fade out effect.

Parameters

iTime time for fading out the music, in milliseconds.
By default is set to 1000ms.

Returns: 0 on success or a negative error code on failure.

◆ loadFromFile()

Sint32 CRM64Pro::MusicMgr::loadFromFile	(	const string &	sFile,
		const string &	sName = `""`
	)

Load a music from an external file.

The Music Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters

sFile	string containing the [directory]+filename+[extension]. Directory separators '\' and '/' are supported.
sName	the image object name. By default, it is set to empty to use the filename for setting the object name. The object name must be unique and with a maximum size of 64 characters or will be truncated.

Returns: greater than 0 on success(the Music id) or a negative error code on failure.

◆ load() [1/2]

Sint32 CRM64Pro::MusicMgr::load	(	const string &	sFileCDC,
		const string &	sName
	)

Load a music stored in a CDC file.

The Music Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters

sFileCDC	string containing the [directory]+filename. Directory separators '\' and '/' are supported.
sName	string with the music name (maximum size of 64 characters).

Returns: 0 or greater on success(the Music id) or a negative error code on failure.

◆ load() [2/2]

Sint32 CRM64Pro::MusicMgr::load	(	const Sint32	idCDC,
		const string &	sName
	)

Load a music stored in a CDC file.

The Music Manager has the ability of sharing ids based on the name as the key, so before trying to load a new one, it checks if it is already loaded for sharing it.

Parameters

idCDC	CDC id.
sName	string with the music name (maximum size of 64 characters).

Returns: 0 or greater on success(the Music id) or a negative error code on failure.

◆ remove()

Sint32 CRM64Pro::MusicMgr::remove	(	const Sint32	idCDC,
		const string &	sName
	)

Remove a music stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the music name (maximum size of 64 characters).

Returns: greater than 0 on success or a negative error code on failure.

Note: The music must be closed before trying to remove it from the CDC.

◆ exist()

Sint32 CRM64Pro::MusicMgr::exist	(	Sint32	idCDC,
		const string &	sName
	)

Check if a music is stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the music name (maximum size of 64 characters).

Returns: 0 on success(it exists) or a negative error code on failure (it does not exist).

Note: It is normally used for checking if a music is present without throwing any error.

Detailed Description

Classes

Functions

Function Documentation

◆ info() [1/3]

◆ getName()

◆ getID()

◆ info() [2/3]

◆ play()

◆ fadeIn()

◆ saveToFile()

◆ save() [1/2]

◆ save() [2/2]

◆ info() [3/3]

◆ close()

◆ getNum()

◆ setName()

◆ get()

◆ stop()

◆ pause()

◆ resume()

◆ status()

◆ position()

◆ fadeOut()

◆ loadFromFile()

◆ load() [1/2]

◆ load() [2/2]

◆ remove()

◆ exist()