1.01 - Audio

You can play musics and sound effects through sol.audio.

Functions of sol.audio

sol.audio.play_sound(sound_id)

Plays a sound effect.

Generates a Lua error if the sound does not exist.

Several sounds can be played in parallel. In the current version, a sound cannot be interrupted after you start playing it.

Unlike musics, sounds files are entirely read before being played. A file access is made only the first time you play each sound. You can use sol.audio.preload_sounds() if you want to also avoid this initial file access.

sol.audio.preload_sounds()

Loads all sounds effects into memory for faster future access.

If you don't call this function, you can still play sound effects, but the first access to each sound effect will require a file access that might be perceptible on slow machines. It is recommended to call this function at the beginning of the program (typically from sol.main:on_started()).

The list of sound files to load is read from the quest database file.

This function does nothing if you already called it before.

sol.audio.play_music(music_id, [action])

Plays a music.

If the music does not exist, a Lua error is generated.

Only one music can be played at a time. If the same music was already playing, it continues normally and does not restart. If a different music was already playing, it is stopped and replaced by the new one.

When the music reaches the end, the action parameter indicates what to do next. The default behavior is to loop from the beginning.

However, some music files already have their own loop internal loop information. Such musics are able to loop to a specific point rather than to the beginning. Since they already loop forever internally, they don't have an end and the action parameter has no effect on them. See Music loop settings to know how Solarus supports internal loop information for each format.

sol.audio.get_music()

Returns the name of the music currently playing.

sol.audio.stop_music()

Stops playing music.

This function has no effect if no music was playing.

Remarks
This is equivalent to sol.audio.play_music("none").

sol.audio.get_sound_volume()

Returns the current volume of sound effects.

This volume applies to all sounds played by sol.audio.play_sound() and by the engine.

sol.audio.set_sound_volume(volume)

Sets the volume of sound effects.

This volume applies to all sounds played by sol.audio.play_sound() and by the engine.

Remarks
When the quest is run from the Solarus GUI, the user can also change the volume from the menus of the GUI.

sol.audio.get_music_volume()

Returns the current volume of musics.

This volume applies to all musics played by sol.audio.play_music(music_id, [action]). "sol.audio.play_music()"

Remarks
When the quest is run from the Solarus GUI, the user can also change the volume from the menus of the GUI.

sol.audio.set_music_volume(volume)

Sets the volume of musics.

This volume applies to all musics played by sol.audio.play_music(music_id, [action]). "sol.audio.play_music()"

sol.audio.get_music_format()

Returns the format of the music currently playing.

sol.audio.get_music_num_channels()

Returns the number of channels of the current .it music.

This function is only supported for .it musics.

sol.audio.get_music_channel_volume(channel)

Returns the volume of notes of a channel for the current .it music.

This function is only supported for .it musics.

Remarks
The channel should have the same volume for all its notes. Otherwise, calling this function does not make much sense.

sol.audio.set_music_channel_volume(channel, volume)

Sets the volume of all notes of a channel for the current .it music.

This function has no effect for musics other than .it.

sol.audio.get_tempo()

Returns the tempo of the current .it music.

This function is only supported for .it musics.

sol.audio.set_tempo(tempo)

Sets the tempo of the current .it music.

This function is only supported for .it musics.