Offers a interface to play audio. More...

#include <AudioEngine.h>

Public Types
enum class	AudioState
	AudioState enum,all possible states of an audio instance.

Static Public Member Functions
static void	end ()
	Release objects relating to AudioEngine.
static AudioProfile *	getDefaultProfile ()
	Gets the default profile of audio instances.
static AUDIO_ID	play2d (std::string_view filePath, bool loop=false, float volume=1.0f, const AudioProfile *profile=nullptr)
	Play 2d sound.
static AUDIO_ID	play2d (std::string_view filePath, const AudioPlayerSettings &settings, const AudioProfile *profile=nullptr)
	Play 2d sound.
static AUDIO_ID	play3d (std::string_view filePath, const Vec3 &position, bool loop=false, float volume=1.0f, const AudioProfile *profile=nullptr)
	Play sound in 3d space.
static AUDIO_ID	play3d (std::string_view filePath, const AudioPlayerSettings &settings, const AudioProfile *profile=nullptr)
	Play sound in 3d space.
static void	setLoop (AUDIO_ID audioID, bool loop)
	Sets whether an audio instance loop or not.
static bool	isLoop (AUDIO_ID audioID)
	Checks whether an audio instance is loop.
static void	setVolume (AUDIO_ID audioID, float volume)
	Sets volume for an audio instance.
static float	getVolume (AUDIO_ID audioID)
	Gets the volume value of an audio instance.
static void	setPitch (AUDIO_ID audioID, float pitch)
	Sets pitch for an audio instance.
static float	getPitch (AUDIO_ID audioID)
	Gets the volume value of an audio instance.
static void	pause (AUDIO_ID audioID)
	Pause an audio instance.
static void	pauseAll ()
	Pause all playing audio instances.
static void	resume (AUDIO_ID audioID)
	Resume an audio instance.
static void	resumeAll ()
	Resume all suspended audio instances.
static void	stop (AUDIO_ID audioID)
	Stop an audio instance.
static void	stopAll ()
	Stop all audio instances.
static bool	setCurrentTime (AUDIO_ID audioID, float sec)
	Sets the current playback position of an audio instance.
static float	getCurrentTime (AUDIO_ID audioID)
	Gets the current playback position of an audio instance.
static float	getDuration (AUDIO_ID audioID)
	Gets the duration of an audio instance.
static AudioState	getState (AUDIO_ID audioID)
	Returns the state of an audio instance.
static void	setFinishCallback (AUDIO_ID audioID, const std::function< void(AUDIO_ID, std::string_view)> &callback)
	Register a callback to be invoked when an audio instance has completed playing.
static int	getMaxAudioInstance ()
	Gets the maximum number of simultaneous audio instance of AudioEngine.
static bool	setMaxAudioInstance (int maxInstances)
	Sets the maximum number of simultaneous audio instance for AudioEngine.
static void	uncache (std::string_view filePath)
	Uncache the audio data from internal buffer.
static void	uncacheAll ()
	Uncache all audio data from internal buffer.
static AudioProfile *	getProfile (AUDIO_ID audioID)
	Gets the audio profile by id of audio instance.
static AudioProfile *	getProfile (std::string_view profileName)
	Gets an audio profile by name.
static void	preload (std::string_view filePath)
	Preload audio file.
static void	preload (std::string_view filePath, std::function< void(bool isSuccess)> callback)
	Preload audio file.
static int	getPlayingAudioCount ()
	Gets playing audio count.
static void	setEnabled (bool isEnabled)
	Whether to enable playing audios.
static bool	isEnabled ()
	Check whether AudioEngine is enabled.
static void	setPan (AUDIO_ID audioId, float value, float distance=-0.5f)
	Sets the pan of an audio instance.
static float	getPan (AUDIO_ID audioId)
	Gets the pan of an audio instance.
static ax::Vec3	getSourcePosition (AUDIO_ID audioId)
	Gets the position of the audio source.
static void	setSourcePosition (AUDIO_ID audioId, const ax::Vec3 &position)
	Sets the position of the audio source.
static void	setListenerPosition (const ax::Vec3 &position)
	Sets the position of the listener.
static ax::Vec3	getListenerPosition ()
	Gets the position of the listener.
static void	setDistanceScale (float scale)
	Sets the distance scale.
static float	getDistanceScale ()
	Gets the distance scale.
static void	setReverbProperties (AUDIO_ID audioId, const ReverbProperties *reverbProperties)
	Sets and enables reverb for an audio track.

Detailed Description

Offers a interface to play audio.

Note: Make sure to call AudioEngine::end() when the audio engine is not needed anymore to release resources.

Member Function Documentation

◆ end()

void end ( )

static

Release objects relating to AudioEngine.

Warning: It must be called before the application exit. @lua endToLua

◆ getDefaultProfile()

AudioProfile * getDefaultProfile ( )

static

Gets the default profile of audio instances.

Returns: The default profile of audio instances.

◆ play2d() [1/2]

AUDIO_ID play2d	(	std::string_view	filePath,
		bool	loop = false,
		float	volume = 1.0f,
		const AudioProfile *	profile = nullptr )

static

Play 2d sound.

Parameters

filePath	The path of an audio file.
loop	Whether audio instance loop or not.
volume	Volume value (range from 0.0 to 1.0).
profile	A profile for audio instance. When profile is not specified, default profile will be used.

Returns: An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.

See also: AudioProfile

◆ play2d() [2/2]

AUDIO_ID play2d	(	std::string_view	filePath,
		const AudioPlayerSettings &	settings,
		const AudioProfile *	profile = nullptr )

static

Play 2d sound.

Parameters

filePath	The path of an audio file.
settings	The player settings for audio.
profile	A profile for audio instance. When profile is not specified, default profile will be used.

Returns: An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.

See also: AudioProfile, AudioPlayerSettings

◆ play3d() [1/2]

AUDIO_ID play3d	(	std::string_view	filePath,
		const Vec3 &	position,
		bool	loop = false,
		float	volume = 1.0f,
		const AudioProfile *	profile = nullptr )

static

Play sound in 3d space.

Parameters

filePath	The path of an audio file.
position	Position of audio source relative to listener
loop	Whether audio instance loop or not.
volume	Volume value (range from 0.0 to 1.0).
profile	A profile for audio instance. When profile is not specified, default profile will be used.

Returns: An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.

See also: AudioProfile

◆ play3d() [2/2]

AUDIO_ID play3d	(	std::string_view	filePath,
		const AudioPlayerSettings &	settings,
		const AudioProfile *	profile = nullptr )

static

Play sound in 3d space.

Parameters

filePath	The path of an audio file.
settings	The player settings for audio.
profile	A profile for audio instance. When profile is not specified, default profile will be used.

Returns: An audio ID. It allows you to dynamically change the behavior of an audio instance on the fly.

See also: AudioProfile, AudioPlayerSettings

◆ setLoop()

void setLoop	(	AUDIO_ID	audioID,
		bool	loop )

static

Sets whether an audio instance loop or not.

Parameters

audioID	An audioID returned by the play2d function.
loop	Whether audio instance loop or not.

◆ isLoop()

bool isLoop ( AUDIO_ID audioID )

static

Checks whether an audio instance is loop.

Parameters

audioID An audioID returned by the play2d function.

Returns: Whether or not an audio instance is loop.

◆ setVolume()

void setVolume	(	AUDIO_ID	audioID,
		float	volume )

static

Sets volume for an audio instance.

Parameters

audioID	An audioID returned by the play2d function.
volume	Volume value (range from 0.0 to 1.0).

◆ getVolume()

float getVolume ( AUDIO_ID audioID )

static

Gets the volume value of an audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: Volume value (range from 0.0 to 1.0).

◆ setPitch()

void setPitch	(	AUDIO_ID	audioID,
		float	pitch )

static

Sets pitch for an audio instance.

Parameters

audioID	An audioID returned by the play2d function.
pitch	Volume value (range from 0.5 to 2.0).

◆ getPitch()

float getPitch ( AUDIO_ID audioID )

static

Gets the volume value of an audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: pitch value (range from 0.5 to 2.0).

◆ pause()

void pause ( AUDIO_ID audioID )

static

Pause an audio instance.

Parameters

audioID An audioID returned by the play2d function.

◆ resume()

void resume ( AUDIO_ID audioID )

static

Resume an audio instance.

Parameters

audioID An audioID returned by the play2d function.

◆ stop()

void stop ( AUDIO_ID audioID )

static

Stop an audio instance.

Parameters

audioID An audioID returned by the play2d function.

◆ setCurrentTime()

bool setCurrentTime	(	AUDIO_ID	audioID,
		float	sec )

static

Sets the current playback position of an audio instance.

Parameters

audioID	An audioID returned by the play2d function.
sec	The offset in seconds from the start to seek to.

Returns

◆ getCurrentTime()

float getCurrentTime ( AUDIO_ID audioID )

static

Gets the current playback position of an audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: The current playback position of an audio instance.

◆ getDuration()

float getDuration ( AUDIO_ID audioID )

static

Gets the duration of an audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: The duration of an audio instance.

◆ getState()

AudioState getState ( AUDIO_ID audioID )

static

Returns the state of an audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: The status of an audio instance.

◆ setFinishCallback()

void setFinishCallback	(	AUDIO_ID	audioID,
		const std::function< void(AUDIO_ID, std::string_view)> &	callback )

static

Register a callback to be invoked when an audio instance has completed playing.

Parameters

audioID	An audioID returned by the play2d function.
callback

◆ setMaxAudioInstance()

bool setMaxAudioInstance ( int maxInstances )

static

Sets the maximum number of simultaneous audio instance for AudioEngine.

Parameters

maxInstances The maximum number of simultaneous audio instance.

◆ uncache()

void uncache ( std::string_view filePath )

static

Uncache the audio data from internal buffer.

AudioEngine cache audio data on ios,mac, and win32 platform.

Warning: This can lead to stop related audio first.

Parameters

filePath Audio file path.

◆ uncacheAll()

void uncacheAll ( )

static

Uncache all audio data from internal buffer.

Warning: All audio will be stopped first.

◆ getProfile() [1/2]

AudioProfile * getProfile ( AUDIO_ID audioID )

static

Gets the audio profile by id of audio instance.

Parameters

audioID An audioID returned by the play2d function.

Returns: The audio profile.

◆ getProfile() [2/2]

AudioProfile * getProfile ( std::string_view profileName )

static

Gets an audio profile by name.

Parameters

profileName A name of audio profile.

Returns: The audio profile.

◆ preload() [1/2]

void preload ( std::string_view filePath )

inlinestatic

Preload audio file.

Parameters

filePath The file path of an audio.

◆ preload() [2/2]

void preload	(	std::string_view	filePath,
		std::function< void(bool isSuccess)>	callback )

static

Preload audio file.

Parameters

filePath	The file path of an audio.
callback	A callback which will be called after loading is finished.

◆ setEnabled()

void setEnabled ( bool isEnabled )

static

Whether to enable playing audios.

Note: If it's disabled, current playing audios will be stopped and the later 'preload', 'play2d' methods will take no effects.

◆ setPan()

void setPan	(	AUDIO_ID	audioId,
		float	value,
		float	distance = -0.5f )

static

Sets the pan of an audio instance.

Parameters

audioId	An audioID returned by the play2d function.
value	Panning value, from -1.f to +1.f, representing -60 degrees to +60 degrees
distance	Distance from source, with -0.5f being the default

Returns

◆ getPan()

float getPan ( AUDIO_ID audioId )

static

Gets the pan of an audio instance.

Parameters

audioId An audioID returned by the play2d function.

Returns: pan value as a float between -1.0f to +1.0f

◆ getSourcePosition()

ax::Vec3 getSourcePosition ( AUDIO_ID audioId )

static

Gets the position of the audio source.

Parameters

audioId An audioID returned by the play2d function.

Returns: Vec3 position of source

◆ setSourcePosition()

void setSourcePosition	(	AUDIO_ID	audioId,
		const ax::Vec3 &	position )

static

Sets the position of the audio source.

Parameters

audioId	An audioID returned by the play2d function.
position	position of source

◆ setListenerPosition()

void setListenerPosition ( const ax::Vec3 & position )

static

Sets the position of the listener.

Parameters

position position of listener

◆ getListenerPosition()

ax::Vec3 getListenerPosition ( )

static

Gets the position of the listener.

Returns: Vec3 position of listener

◆ setDistanceScale()

void setDistanceScale ( float scale )

static

Sets the distance scale.

Parameters

scale used for 3D audio source to listener calculations. Default is 1.0f, and must be greater than 0.f.

◆ getDistanceScale()

float getDistanceScale ( )

static

Gets the distance scale.

Returns: float distance used for 3D audio source to listener calculations

◆ setReverbProperties()

void setReverbProperties	(	AUDIO_ID	audioId,
		const ReverbProperties *	reverbProperties )

static

Sets and enables reverb for an audio track.

Parameters

audioId	An audioID returned by the play2d function.
reverbProperties	The pointer to reverb effect settings. If this is nullptr, then reverb effect will be disabled.

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

AudioEngine.h

Public Types

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ end()

◆ getDefaultProfile()

◆ play2d() [1/2]

◆ play2d() [2/2]

◆ play3d() [1/2]

◆ play3d() [2/2]

◆ setLoop()

◆ isLoop()

◆ setVolume()

◆ getVolume()

◆ setPitch()

◆ getPitch()

◆ pause()

◆ resume()

◆ stop()

◆ setCurrentTime()

◆ getCurrentTime()

◆ getDuration()

◆ getState()

◆ setFinishCallback()

◆ setMaxAudioInstance()

◆ uncache()

◆ uncacheAll()

◆ getProfile() [1/2]

◆ getProfile() [2/2]

◆ preload() [1/2]

◆ preload() [2/2]

◆ setEnabled()

◆ setPan()

◆ getPan()

◆ getSourcePosition()

◆ setSourcePosition()

◆ setListenerPosition()

◆ getListenerPosition()

◆ setDistanceScale()

◆ getDistanceScale()

◆ setReverbProperties()