LunaLua global Sound and Music functions

From PGE Wiki
Jump to: navigation, search

This is a new Audio Engine based on the SDL Mixer library. It provides flexible SFX and Music functions to take more advanced usage of audio system.

Music common functions

There are common music functions which providing dynamic usage of music playback with ability to play any custom musics 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.MusicOpen(string fileName) nil Loads a music file into stream. File path is relative to custom music section.
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)
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
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)
Audio.MusicTitle() string Returns music title from ID3/VorbisComment tag (if title tag is empty, filename will be returned) [works for OGG, FLAC, MP3, 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, 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, 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, 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, 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).

Music special functions

There are a special functions which giving able to seize music stream from SMBX Engine. Seizing of music stream giving able to play any musics with LUA code. With using of stream seizing you can correctly use the music stream with no bugs. Target section should have any switched default music ID to take ability pause/resume music when you switching from SMBX into another applications. (Level only)

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).
Audio.ReleaseStream(int sectionID) nil Returns control of music stream to 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.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.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!
Audio.playSFX(int index) nil Plays a SMBX Sound by the SMBX Sound ID
Audio.playSFX(string fileName) nil Once plays the sound effect file. Path to file is relative to level custom directory.
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
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
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.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.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.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.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.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.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.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.
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

(Level only) (LunaLua ≥ v0.7.3)

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 Audio.playSFX)
playSFX(string filename) nil Plays a Soundfile (supports WAV only) (Deprecated: Use Audio.playSFX)
playSFXSDL(string filename) nil Plays a Soundfile via SDL2_mixer (supports WAV, OGG, FLAC, AIFF, VOC) (Deprecated: Use Audio.playSFX)
clearSFXBuffer() nil Clear SFX buffer and stop all custom sounds which playing via SDL2_mixer (Deprecated: Use Audio.clearSFXBuffer)
playMusic(int section) nil Plays the music, which is set by the given section id
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)
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)
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)