Detailed Description

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

Once the audio system is initialized using ConfigMgr::audioInit() or ConfigMgr::load(), using this manager you can load sound files from external files or from a CDC file and play them.
By default as a minimum value, there are 8 mixing channels, each of one can play a sound at the same time. It can be dinamically modified up to 128 mixing channels so 128 different sound can be played at the same time.
Actions that can be done on a sound object:

play, stop, pause and resume
fade out and fade in on a given time
effects: panning, distance and source emitting position

Supported sound formats:

	Raw streams: WAV and VOC
	Compressed streams: FLAC, Ogg and MP3

This is a sharing manager: it has the ability of sharing a sound 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 sound id, it will be effectively closed.

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

Note: The Sound 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::Sound
	Sound Object class. More...

class	CRM64Pro::SoundMgr
	Sound Manager class. More...

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

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

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

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

Sint32	CRM64Pro::Sound::play (Sint32 iChannel=-1, Sint32 iLoop=0)
	Play a sound.

Sint32	CRM64Pro::Sound::fadeIn (Sint32 iTime=1000, Sint32 iChannel=-1, Sint32 iLoop=0)
	Play a sound with a fade in effect.

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

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

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

Sint32	CRM64Pro::SoundMgr::info (Sint32 idSnd=0)
	Request Sound Manager information.

Sint32	CRM64Pro::SoundMgr::close (Sint32 idSnd=0)
	Close and destroy a sound.

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

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

Sound *	CRM64Pro::SoundMgr::get (Sint32 idSnd=0)
	Get a pointer to the sound using its handler.

Sint32	CRM64Pro::SoundMgr::stop (Sint32 iChannel)
	Stop sound playing in a channel.

Sint32	CRM64Pro::SoundMgr::pause (Sint32 iChannel)
	Pause sound playing in a channel.

Sint32	CRM64Pro::SoundMgr::resume (Sint32 iChannel)
	Resume sound playing in a channel.

Sint32	CRM64Pro::SoundMgr::status (Sint32 iChannel)
	Get the sound status on a given channel.

Sint32	CRM64Pro::SoundMgr::fadeOut (Sint32 iChannel, Sint32 iTime=1000)
	Sound fade out effect in a channel.

Sint32	CRM64Pro::SoundMgr::panning (Sint32 iChannel=-1, Uint8 iLeft=255, Uint8 iRight=255)
	Set the panning of a channel.

Sint32	CRM64Pro::SoundMgr::distance (Sint32 iChannel=-1, Uint8 iDistance=0)
	Set the distance of a channel.

Sint32	CRM64Pro::SoundMgr::position (Sint32 iChannel=-1, Sint16 iAngle=0, Uint8 iDistance=0)
	Set the position of a channel.

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

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

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

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

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

Function Documentation

◆ info() [1/3]

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

Request Sound 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::Sound::getName ( string & sName )

Get the name.

Parameters

sName a string containing the Sound object name.

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

◆ getID()

Uint32 CRM64Pro::Sound::getID ( )

Get the ID.

Returns: the object ID.

◆ info() [2/3]

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

Get Sound object information.

Parameters

sType	an string pointer filled in with sound type. 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::Sound::play	(	Sint32	iChannel = `-1`,
		Sint32	iLoop = `0`
	)

Play a sound.

Parameters

iChannel	Mixing channel used for the sound play. -1 will use the first free channel and it is set by default.
iLoop	number of sound playing loops. By default is set to 0. 0 plays the sound just once, 1 twice and -1 plays it forever.

Returns: greater than 0 on success(the channel used for playing it) or a negative error code on failure.

◆ fadeIn()

Sint32 CRM64Pro::Sound::fadeIn	(	Sint32	iTime = `1000`,
		Sint32	iChannel = `-1`,
		Sint32	iLoop = `0`
	)

Play a sound with a fade in effect.

Parameters

iTime	time for fading in the sound, in milliseconds. By default is set to 1000ms.
iChannel	Mixing channel used for the sound play. -1 will use the first free channel and it is set by default.
iLoop	number of sound playing loops. By default is set to 0. 0 plays the sound just once, 1 twice and -1 plays it forever.

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

◆ saveToFile()

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

Export the Sound 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::Sound::save ( const string & sFileCDC )

Save the Sound in to a CDC file.

If the Sound 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 Sound::save() with the CDC id.

◆ save() [2/2]

Sint32 CRM64Pro::Sound::save ( Sint32 idCDC )

Save the Sound in to a CDC file.

If the Sound 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::SoundMgr::info ( Sint32 iMode = 0 )

Request Sound 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.
idSnd for displaying Manager and given Sound id information.

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

◆ close()

Sint32 CRM64Pro::SoundMgr::close ( Sint32 idSnd = 0 )

Close and destroy a sound.

Parameters

idSnd 0 (default value) for closing all sound or the Sound id.
As the Sound Manager has the ability of sharing a Sound id, if the sound 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 sound, it will be automatically closed once the GDK is terminated.

◆ getNum()

Sint32 CRM64Pro::SoundMgr::getNum ( )

Get number of loaded objects.

Returns: the number of CDC files.

◆ setName()

Sint32 CRM64Pro::SoundMgr::setName	(	Sint32	idSnd,
		const string &	sName
	)

Change the object name.

Parameters

idSnd	Sound id.
sName	The name to give to the sound e.g. 'mySound'. 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()

Sound * CRM64Pro::SoundMgr::get ( Sint32 idSnd = 0 )

Get a pointer to the sound using its handler.

By default it returns the first sound loaded.

Parameters

idSnd Sound id.

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

◆ stop()

Sint32 CRM64Pro::SoundMgr::stop ( Sint32 iChannel )

Stop sound playing in a channel.

Parameters

iChannel Mixing channel where the sound is being played.
-1 will affect all channels.

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

◆ pause()

Sint32 CRM64Pro::SoundMgr::pause ( Sint32 iChannel )

Pause sound playing in a channel.

Parameters

iChannel Mixing channel where the sound is being played.
-1 will affect all channels.

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

◆ resume()

Sint32 CRM64Pro::SoundMgr::resume ( Sint32 iChannel )

Resume sound playing in a channel.

Parameters

iChannel Mixing channel where the sound is being played.
-1 will affect all channels.

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

◆ status()

Sint32 CRM64Pro::SoundMgr::status ( Sint32 iChannel )

Get the sound status on a given channel.

Parameters

iChannel Mixing channel where the sound is being played.
-1 will affect all channels.

Returns

C64_STATUS_DISABLED	channel is not playing any sound.
C64_STATUS_ENABLED	channel is playing a sound.
C64_STATUS_PAUSED	channel playing is paused.

◆ fadeOut()

Sint32 CRM64Pro::SoundMgr::fadeOut	(	Sint32	iChannel,
		Sint32	iTime = `1000`
	)

Sound fade out effect in a channel.

Parameters

iChannel	Mixing channel where the sound is being played. -1 will affect all channels.
iTime	time for fading out the sound, in milliseconds. By default is set to 1000ms.

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

◆ panning()

Sint32 CRM64Pro::SoundMgr::panning	(	Sint32	iChannel = `-1`,
		Uint8	iLeft = `255`,
		Uint8	iRight = `255`
	)

Set the panning of a channel.

Parameters

iChannel	Mixing channel where the sound is being played. -1 will affect all channels, even the reserved for music playback. By default, it is set to -1.
iLeft	left channel value ranging from 0 (quietest) to 255 (loudest). By default, it is set to 255.
iRight	right channel value ranging from 0 (quietest) to 255 (loudest). By default, it is set to 255.

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

Note: This effect does not work with 32bits floating point audio sampling and requires a mode different to Mono.

◆ distance()

Sint32 CRM64Pro::SoundMgr::distance	(	Sint32	iChannel = `-1`,
		Uint8	iDistance = `0`
	)

Set the distance of a channel.

Parameters

iChannel	Mixing channel where the sound is being played. -1 will affect all channels, even the reserved for music playback. By default, it is set to -1.
iDistance	an integer from 0 to 255 that specifies the location of the sound in relation to the listener. 0 is overlapping the listener and 255 is as far away as possible. A good step value is 8. By default, it is set to 0.

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

Note: This effect does not work with 32bits floating point audio sampling.

◆ position()

Sint32 CRM64Pro::SoundMgr::position	(	Sint32	iChannel = `-1`,
		Sint16	iAngle = `0`,
		Uint8	iDistance = `0`
	)

Set the position of a channel.

Parameters

iChannel	Mixing channel where the sound is being played. -1 will affect all channels, even the reserved for music playback. By default, it is set to -1.
iAngle	an integer from 0 to 360 that specifies the location of the sound in relation to the listener. 0 is due north and rotates clockwise as the value increases. By default, it is set to -1.
iDistance	an integer from 0 to 255 that specifies the location of the sound in relation to the listener. 0 is overlapping the listener and 255 is as far away as possible. A good step value is 8. By default, it is set to 0.

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

Note: This effect does not work with 32bits floating point audio sampling.

◆ loadFromFile()

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

Load a sound from an external file.

The Sound 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 (without extension) 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 Sound id) or a negative error code on failure.

◆ load() [1/2]

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

Load a sound stored in a CDC file.

The Sound 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 sound name (maximum size of 64 characters).

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

◆ load() [2/2]

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

Load a sound stored in a CDC file.

The Sound 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 sound name (maximum size of 64 characters).

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

◆ remove()

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

Remove a sound stored in a CDC file.

Parameters

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

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

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

◆ exist()

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

Check if a sound is stored in a CDC file.

Parameters

idCDC	CDC id.
sName	string with the sound 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 sound 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()

◆ fadeOut()

◆ panning()

◆ distance()

◆ position()

◆ loadFromFile()

◆ load() [1/2]

◆ load() [2/2]

◆ remove()

◆ exist()