Module MusicAddon
Class interfacing the AVAudioPlayer to play music files.
You can also play multiple musics at the same time using different instances of this class. See MusicAddonExample.lua for an example.
Functions
| MusicAddon:init (in_filename) | MusicAddon constructor. |
| MusicAddon:load (in_filename) | Load a different file. |
| MusicAddon:unload () | Unload the currently loaded file. |
| MusicAddon:getURL () | Get the name of the loaded file. |
| MusicAddon:enableRate () | Enable controlling the play rate of the music. |
| MusicAddon:enableMetering () | Enable metering of the music. |
| MusicAddon:prepareToPlay () | Prepare the music for play. |
| MusicAddon:getLoops () | Get the number of times the music will loop. |
| MusicAddon:setLoops (in_loops) | Set the number of times the music will loop. |
| MusicAddon:getPan () | Get the pan value of the music. |
| MusicAddon:setPan (in_pan) | Set the pan value of the music. |
| MusicAddon:getRate () | Get the play rate of the music. |
| MusicAddon:setRate (in_rate) | Set the play rate of the music. |
| MusicAddon:play () | Start playing the loaded music. |
| MusicAddon:playAfterDelay (in_delay) | Start playing the music after a certain delay. |
| MusicAddon:pause () | Pause the music. |
| MusicAddon:stop () | Stop the music. |
| MusicAddon:isPlaying () | Check if the music is currently playing. |
| MusicAddon:getCurrentTime () | Get the current play position of the music. |
| MusicAddon:setCurrentTime (in_time) | Set the current play position of the music. |
| MusicAddon:getDuration () | Get the total duration of the music. |
| MusicAddon:getNumberOfChannels () | Get the number of channels in the music. |
| MusicAddon:getVolume () | Get the current volume of the music player. |
| MusicAddon:setVolume (in_volume) | Set the volume of the music player. |
| MusicAddon:getAveragePowerForChannel (in_channel) | Returns the average power for a given channel, in decibels, for the sound being played. |
| MusicAddon:getPeakPowerForChannel (in_channel) | Returns the peak power for a given channel, in decibels, for the sound being played. |
Functions
- MusicAddon:init (in_filename)
-
MusicAddon constructor.
Parameters:
- in_filename string Name of the file to load
See also:
Usage:
music = MusicAddon("GameMusic.mp3) - MusicAddon:load (in_filename)
-
Load a different file.
Parameters:
- in_filename string Name of the file to load
- MusicAddon:unload ()
- Unload the currently loaded file.
- MusicAddon:getURL ()
-
Get the name of the loaded file.
Returns:
-
string
Name of the file currently loaded.
- MusicAddon:enableRate ()
- Enable controlling the play rate of the music. To control the play rate, this function must be called before play or prepareForPlay.
- MusicAddon:enableMetering ()
-
Enable metering of the music.
See also:
- MusicAddon:prepareToPlay ()
- Prepare the music for play. Starts buffering the music so there is no delay when you start playing it.
- MusicAddon:getLoops ()
-
Get the number of times the music will loop.
Returns:
-
integer
Number of times the music will loop. A negative value means it will keep looping.
- MusicAddon:setLoops (in_loops)
-
Set the number of times the music will loop.
Parameters:
- in_loops integer Number of times to loop the music. A negative value means it will keep looping.
- MusicAddon:getPan ()
-
Get the pan value of the music.
Returns:
-
number
A value between -1 (left) and +1 (right).
- MusicAddon:setPan (in_pan)
-
Set the pan value of the music.
Parameters:
- in_pan number Pan value between -1 (left) and +1 (right).
- MusicAddon:getRate ()
-
Get the play rate of the music.
Returns:
-
number
Current play rate between 0.5 (half-speed) and 2.0 (double speed).
- MusicAddon:setRate (in_rate)
-
Set the play rate of the music.
Parameters:
- in_rate number Play rate between 0.5 (half-speed) and 2.0 (double speed).
- MusicAddon:play ()
- Start playing the loaded music.
- MusicAddon:playAfterDelay (in_delay)
-
Start playing the music after a certain delay.
This can be used to start two musics at precisely the same time.
Parameters:
- in_delay number Delay in seconds before the music starts playing.
- MusicAddon:pause ()
- Pause the music.
- MusicAddon:stop ()
- Stop the music. This does not rewind the music. Use MusicAddon:setCurrentTime to do so. If you want to resume the music where it was stopped, used MusicAddon:pause instead to avoid buffering glitches.
- MusicAddon:isPlaying ()
-
Check if the music is currently playing.
Returns:
-
bool
True if the music is currently playing, False otherwise.
- MusicAddon:getCurrentTime ()
-
Get the current play position of the music.
If the sound is playing, currentTime is the offset of the current playback position, measured in seconds from the start of the sound. If the sound is not playing, currentTime is the offset of where playing starts upon calling the play method, measured in seconds from the start of the sound.
Returns:
-
number
The playback point, in seconds, within the timeline of the sound associated with the audio player.
- MusicAddon:setCurrentTime (in_time)
-
Set the current play position of the music.
By setting this, you can seek to a specific point in a sound file or implement audio fast-forward and rewind functions.
Parameters:
- in_time number The playback point, in seconds, within the timeline of the sound associated with the audio player.
- MusicAddon:getDuration ()
-
Get the total duration of the music.
Returns:
-
number
Total duration, in seconds, of the sound associated with the audio player.
- MusicAddon:getNumberOfChannels ()
-
Get the number of channels in the music.
Returns:
-
integer
The number of audio channels in the sound associated with the audio player.
- MusicAddon:getVolume ()
-
Get the current volume of the music player.
Returns:
-
number
The playback gain for the audio player, ranging from 0.0 through 1.0.
- MusicAddon:setVolume (in_volume)
-
Set the volume of the music player.
Parameters:
- in_volume number The playback gain for the audio player, ranging from 0.0 through 1.0.
- MusicAddon:getAveragePowerForChannel (in_channel)
-
Returns the average power for a given channel, in decibels, for the sound being played.
Parameters:
- in_channel integer The audio channel whose average power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
Returns:
-
number
A floating-point representation, in decibels, of a given audio channel’s current average power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence). If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).
See also:
- MusicAddon:getPeakPowerForChannel (in_channel)
-
Returns the peak power for a given channel, in decibels, for the sound being played.
Parameters:
- in_channel integer The audio channel whose peak power value you want to obtain. Channel numbers are zero-indexed. A monaural signal, or the left channel of a stereo signal, has channel number 0.
Returns:
-
number
A floating-point representation, in decibels, of a given audio channel’s current peak power. A return value of 0 dB indicates full scale, or maximum power; a return value of -160 dB indicates minimum power (that is, near silence). If the signal provided to the audio player exceeds ±full scale, then the return value may exceed 0 (that is, it may enter the positive range).
See also: