LunaLua global Sound and Music functions

There is a hardcoded API based on the SDL Mixer audio library used in LunaLua. It provides flexible SFX and Music functions to take more advanced usage of the audio sub-system.

Music common functions

There are common music functions that providing dynamic usage of music playback with the ability to play any custom music in one section. Also, Fade-IN/Fade-OUT effects are available for usage. List of supported formats.

Music common functions [Audio namespace]
Function	Return values	Description
Audio.MusicChange(int section, string fileName, int fadeInDelayMs = -1)	nil	Changes custom music of given section and sets it to play when player is in given section. File path is relative to episode folder (where level file is placed). The fadeInDelayMs argument receiving a millisecond delay of fade in effect. When it equal to zero or it's less, playing of song will be started normally. Note: Some music formats are supports extra arguments (for example, track number in the music file, or synthesizer flags, more detail info and how to use here) (LunaLua-master ≥ 2018-09-13)
Audio.MusicChange(int section, int musicId, int fadeInDelayMs = -1)	nil	Changes current music given section and sets it to play when player is in given section. The fadeInDelayMs argument receiving a millisecond delay of fade in effect. When it equal to zero or it's less, playing of song will be started normally. (LunaLua-master ≥ 2018-09-13)
Audio.MusicFadeOut(int section, int fadeOutDelayMs)	nil	Stops the music of given section with fade out effect (when player is in given section), and sets the section music to silence. (LunaLua-master ≥ 2018-09-13)
Audio.MusicTitle()	string	Returns music title from ID3/VorbisComment tag (if title tag is empty, filename will be returned) [works for OGG, FLAC, MP3, MIDI, and tracker musics like MOD, IT, XM, S3M, etc.] (LunaLua ≥ v0.7.1)
Audio.MusicTitleTag()	string	Returns music title from ID3/VorbisComment tag (if title tag is empty, returns empty string) [works for OGG, FLAC, MP3, MIDI, and tracker musics like MOD, IT, XM, S3M, etc.] (LunaLua ≥ v0.7.1)
Audio.MusicArtistTag()	string	Returns music artist from ID3/VorbisComment tag (if title tag is empty, returns empty string) [works for OGG, FLAC, MP3, MIDI, and tracker musics like MOD, IT, XM, S3M, etc.] (LunaLua ≥ v0.7.2.1)
Audio.MusicAlbumTag()	string	Returns music album from ID3/VorbisComment tag (if title tag is empty, returns empty string) [works for OGG, FLAC, MP3, MIDI, and tracker musics like MOD, IT, XM, S3M, etc.] (LunaLua ≥ v0.7.2.1)
Audio.MusicCopyrightTag()	string	Returns music copyright from ID3/VorbisComment tag (if title tag is empty, returns empty string) [works for OGG, FLAC, MP3, MIDI, and tracker musics like MOD, IT, XM, S3M, etc.] (LunaLua ≥ v0.7.2.1)
Audio.MusicClock()	double	Returns the time starts from begin of the current music track playback (in seconds). The time resets to 0 when music track was changed.
Audio.AudioClock()	double	Returns the total time of played music starts from SMBX game launching (in seconds).
Audio.MusicIsPlaying()	bool	Returns true if any music is currently playing
Audio.MusicIsPaused()	bool	Returns true if any music was paused
Audio.MusicIsFading()	bool	Returns true if any music is currently fading
Audio.MusicVolume(int volume)	nil	Sets the music volume level (from 0 to 128)

Music advanced functions

There are advanced music functions are giving an ability to work with SDL Mixer X library's music API directly: open any song, start/pause/resume it as you want.

Important note: To use these functions, you must seize the section stream! Otherwise, SMBX Engine will override your playing music by that which is set as music of section or World Map.

Music advanced functions [Audio namespace]
Function	Return values	Description
Audio.MusicOpen(string fileName)	nil	Loads a music file into stream. File path is relative to custom music section. Note: Some music formats are supported extra arguments (for example, track number in the music file, or synthesizer flags, more detail info and how to use here)
Audio.MusicPlay()	nil	Starts playback of the music file which currently loaded into stream
Audio.MusicPlayFadeIn(int milliseconds)	nil	Starts playback of the music file which currently loaded into stream with Fade-IN effect in milliseconds
Audio.MusicStop()	nil	Stops the current music playback
Audio.MusicStopFadeOut(int milliseconds)	nil	Stops the current music playback with Fade-OUT effect in milliseconds
Audio.MusicPause()	nil	Pauses the current music playback
Audio.MusicResume()	nil	Continues paused music

Music special functions

There are special functions that giving able to seize the music stream control from SMBX Engine. Seizing of music stream giving able to play any kinds of music with LUA code. By using music stream control seizing you can correctly use the music stream with no bugs. The target section should have any switched default music ID to take the ability to pause/resume music when you switching from SMBX into another application.

Music special functions [Audio namespace]
Function	Return values	Description
Audio.SeizeStream(int sectionID)	nil	Seizing control of music stream from SMBX Engine for specific section ID (from 0 to 20. If -1, then will be seized music stream for all sections) or World Map.
Audio.ReleaseStream(int sectionID)	nil	Returns control of music stream back to SMBX Engine for specific section ID (from 0 to 20. If -1, then will be seized music stream for all sections). SMBX Engine will can play it's musics in stream.
Audio.resetMciSections()	nil	Releases stream for all seized sections

Sound effects common functions

There are functions to work with sound effects and mixing channels. List of supported formats.

Sound Effects functions [Audio namespace]
Function	Return values	Description
Audio.clearSFXBuffer()	nil	Removes all custom sound effects from buffer and stops all currently playing sounds and loops. WARNING: Don't call this function if you have working loops with using of Mix_Chunk pointers!

Sound Effects functions [SFX namespace]
Function	Return values	Description
SFX.open(string path)	nil	Load a sound effect object
SFX.play(number / string / Mix_Chunk sound[, volume, loops, delay])	nil	Plays a SMBX Sound by either the SMBX Sound ID, or specific file, with optional volume, a specific amount of loops (0 = Infinite), and delay.

Sound Effects global variables [Audio namespace]
Function	Return values	Description
Audio.sounds[*]	SoundOverride	Accesses an overrideable sound. With this you can override SMBX sounds at runtime. * is the id of the sound. See more: SoundOverride class

SFX Object sound functions

This is the user-friendly hardcoded overlay that allows you an easier managing of playing SFX.

Tip: At SMBX2 Beta4+ the SFX class is available which gives you a more flexible way on how to play and manipulate sound effects. Use this API in only a condition you want to have the simple but controllable sound playing. Otherwise, use the SFX class instead of this.

SFX Play object sound functions [Audio namespace]
Function	Return values	Description
Audio.SfxPlayObj(Mix_Chunk sfxFile, int loops)	PlayingSfxInstance	Plays sound file by chunk pointer. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops (Use SFX.play)
Audio.SfxPlayObjVol(Mix_Chunk sfxFile, int loops, int volume)	PlayingSfxInstance	Plays sound file by chunk pointer with giving of initial volume value. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops (LunaLua-master ≥ 2018-11-19) (Use SFX.play)
Audio.SfxPlayObjTimed(Mix_Chunk sfxFile, int loops, int ticks)	PlayingSfxInstance	Plays sound file by chunk pointer with time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel.. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops
Audio.SfxPlayObjTimedVol(Mix_Chunk sfxFile, int loops, int ticks, int volume)	PlayingSfxInstance	Plays sound file by chunk pointer with giving of initial volume value and with time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel.. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops (LunaLua-master ≥ 2018-11-19)

Low-level sound functions

This is the lowest SFX API which has the direct binding into the C API SDL Mixer X.

Notice: Suggested to not use this API if you are not sure how to use it properly. You may use this when you develop your own sound overlay modules or libraries when you want to have complete functionality of the audio library.

Low-level sound functions [Audio namespace]
Function	Return values	Description
Audio.newMix_Chunk()	Mix_Chunk	Constructs the null Mix_Chunk pointer which pointing to specific sound file - chunk. Use this function always when you wish to create global variable for sound chunkcs.
Audio.SfxOpen(string fileName)	Mix_Chunk	Loads sound effect file into buffer and returns pointer to them which you can use later to play it with using of loops and effects (Use SFX.open)
Audio.SfxFadeInObj(Mix_Chunk sfxFile, int loops, int fade_ms)	PlayingSfxInstance	Plays sound file by chunk pointer with fade-in effect. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops
Audio.SfxFadeInObjVol(Mix_Chunk sfxFile, int loops, int fade_ms, int volume)	PlayingSfxInstance	Plays sound file by chunk pointer with giving initial volume value and with fade-in effect. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops (LunaLua-master ≥ 2018-11-19)
Audio.SfxFadeInObjTimed(Mix_Chunk sfxFile, int loops, int fade_ms, int ticks)	PlayingSfxInstance	Plays sound file by chunk pointer with fade-in effect and time limit (ticks in milliseconds, -1 is forever). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops
Audio.SfxFadeInObjTimedVol(Mix_Chunk sfxFile, int loops, int fade_ms, int ticks, int volume)	PlayingSfxInstance	Plays sound file by chunk pointer with fade-in effect and giving initial volume value and time limit (ticks in milliseconds, -1 is forever). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns an object that can be used to control the sound clip as it plays/loops (LunaLua-master ≥ 2018-11-19)
Audio.SfxPlayCh(int Channel, Mix_Chunk sfxFile, int loops )	int	Plays sound file by chunk pointer in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns the number of channel where sound is playing/looping
Audio.SfxPlayChVol(int Channel, Mix_Chunk sfxFile, int loops, int volume )	int	Plays sound file by chunk pointer with giving initial volume value in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns the number of channel where sound is playing/looping (LunaLua-master ≥ 2018-11-19)
Audio.SfxPlayChTimed(int Channel, Mix_Chunk sfxFile, int loops, int ticks)	int	Plays sound file by chunk pointer with time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns the number of channel where sound is playing/looping
Audio.SfxPlayChTimedVol(int Channel, Mix_Chunk sfxFile, int loops, int ticks, int volume)	int	Plays sound file by chunk pointer with giving initial volume value and with time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns the number of channel where sound is playing/looping (LunaLua-master ≥ 2018-11-19)
Audio.SfxFadeInCh(int Channel, Mix_Chunk sfxFile, int loops, int fade_ms)	int	Plays sound file by chunk pointer with fade-in effect in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns: the channel the sample is played on. On any errors, -1 is returned.
Audio.SfxFadeInChVol(int Channel, Mix_Chunk sfxFile, int loops, int fade_ms, int volume)	int	Plays sound file by chunk pointer with fade-in effect in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]) and with giving initial volume value. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns: the channel the sample is played on. On any errors, -1 is returned. (LunaLua-master ≥ 2018-11-19)
Audio.SfxFadeInChTimed(int Channel, Mix_Chunk sfxFile, int loops, int fade_ms, int ticks)	int	Plays sound file by chunk pointer with fade-in effect and time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]). Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns: the channel the sample is played on. On any errors, -1 is returned.
Audio.SfxFadeInChTimedVol(int Channel, Mix_Chunk sfxFile, int loops, int fade_ms, int ticks, int volume)	int	Plays sound file by chunk pointer with fade-in effect and time limit (ticks in milliseconds, -1 is forever) in the specific channel (if -1 then will be used any free channel. You can use any channels from 1 to 18 [total 32 but is not recommends to use more than 18 channels]) and with giving initial volume value. Sound will be played with defined number of loops (If 0 then once, if -1 then forever, else 1 play twice or 2 play thrice, etc.). Returns: the channel the sample is played on. On any errors, -1 is returned. (LunaLua-master ≥ 2018-11-19)
Audio.SfxPause(int Channel)	nil	Pauses sound or sound loop in the specific channel. If -1 then pause sounds in the all channels
Audio.SfxResume(int Channel)	nil	Resume paused sound or sound loop in the specific channel. If -1 then resume sounds in the all channels
Audio.SfxStop(int Channel)	int	Stops sound or sound loop in the specific channel. If -1 then stops sounds in the all channels. Returns always 0
Audio.SfxExpire(int Channel, int ticks)	int	Change the timed stoppage of a channel
Audio.SfxFadeOut(int Channel, int fade_ms)	int	Fading out and stops playing sound or sound loop in specific channel with fade in lenght in milliseconds. Returns: The number of channels set to fade out.
Audio.SfxIsPlaying(int Channel)	int	Tells you if channel is playing, or not. Returns: Zero if the channel is not playing. Otherwise if you passed in -1, the number of channels playing is returned. If you passed in a specific channel, then 1 is returned if it is playing.
Audio.SfxIsPaused(int Channel)	int	Tells you if channel is paused, or not. Returns: Zero if the channel is not paused. Otherwise if you passed in -1, the number of paused channels is returned. If you passed in a specific channel, then 1 is returned if it is paused.
Audio.SfxIsFading(int Channel)	int	Tells you if which channel is fading in, out, or not. Does not tell you if the channel is playing anything, or paused, so you'd need to test that separately. Returns: the fading status. Never returns an error.
Audio.SfxVolume(int Channel, int volume)	int	Sets volume (from 0 to 128) to the specific channel. Returns: current volume of the channel. If channel is -1, the average volume is returned.
Audio.SfxSetPanning(int Channel, int left, int right)	int	Panning stereo effects. This effect will only work on stereo audio. Meaning you called Mix_OpenAudio with 2 channels. The easiest way to do true panning is to call SfxSetPanning(channel, left, 254 - left); so that the total volume is correct, if you consider the maximum volume to be 127 per channel for center, or 254 max for left, this works, but about halves the effective volume. This Function registers the effect for you, so don't try to Mix_RegisterEffect it yourself. Notes: Setting both left and right to 255 will unregister the effect from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. Using this function on a mono audio device will not register the effect, nor will it return an error status. Returns: Zero on errors, such as bad channel, or if Mix_RegisterEffect failed.
Audio.SfxSetDistance(int Channel, int distance)	int	This effect simulates a simple attenuation of volume due to distance. The volume never quite reaches silence, even at max distance. Note: Using a distance of 0 will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.
Audio.SfxSet3DPosition(int Channel, int angle, int distance)	int	This effect emulates a simple 3D audio effect. It's not all that realistic, but it can help improve some level of realism. By giving it the angle and distance from the camera's point of view, the effect pans and attenuates volumes. If you are looking for better positional audio, using OpenAL is suggested. Note: Using angle and distance of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.
Audio.SfxReverseStereo(int Channel, int flip)	int	Simple reverse stereo, swaps left and right channel sound. Note: Using a flip of 0, will cause the effect to unregister itself from channel. You cannot unregister it any other way, unless you use Mix_UnregisterAllEffects on the channel. Returns: Zero on errors, such as an invalid channel, or if Mix_RegisterEffect failed.

Deprecated

Global Music and Sounds functions
Function	Return values	Description
playSFX(int index)	nil	Plays a SMBX Sound by the SMBX Sound ID (Deprecated: Use SFX.play)
playSFX(string filename)	nil	Plays a Soundfile (supports WAV only) (Deprecated: Use SFX.play)
playSFXSDL(string filename)	nil	Plays a Soundfile via SDL2_mixer (supports WAV, OGG, FLAC, AIFF, VOC) (Deprecated: Use SFX.play)
clearSFXBuffer()	nil	Clear SFX buffer and stop all custom sounds which playing via SDL2_mixer (Deprecated: Use Audio.clearSFXBuffer)
Audio.playSFX(int index)	nil	Plays a SMBX Sound by the SMBX Sound ID (Deprecated: Use SFX.play)
Audio.playSFX(string fileName)	nil	Once plays the sound effect file. Path to file is relative to level custom directory. (Deprecated: Use SFX.play)
playMusic(int section)	nil	Plays the music, which is set by the given section id (Use Audio.MusicChange)
MusicOpen(string filename)	nil	Loads the custom music file into stream of SDL2_mixer. Current music playback will be halted. Note: to get playback of custom music file in current section, default music should be switched into any non-custom and you must to apply the stream seizing in this section! (Deprecated: Use Audio.MusicOpen or Audio.MusicChange)
MusicPlay()	nil	Plays current file in the music stream of SDL2_mixer. Important note: Don't forget open custom track with MusicOpen() function! (Deprecated: Use Audio.MusicPlay or Audio.MusicChange)
MusicPlayFadeIn(int milliseconds)	nil	Plays current file in the music stream with fade-IN effect via SDL2_mixer with length in milliseconds (Deprecated: Use Audio.MusicPlayFadeIn)
MusicStop()	nil	Stops playback of current music stream of SDL2_mixer. (Deprecated: Use Audio.MusicStop)
MusicStopFadeOut(int milliseconds)	nil	Stops playback of current music stream of SDL2_mixer with fade-out effect with length in milliseconds. (Deprecated: Use Audio.MusicStopFadeOut)
MusicVolume(int volume)	nil	Sets current volume level (from 0 to 128) for music stream of SDL2_mixer (Deprecated: Use Audio.MusicVolume)