LuaAPI/wesnoth/audio

The audio module is only available in the game. It contains functions for playing music and sound effects.

wesnoth.audio.play

• ♟ wesnoth.audio.play(sound, [repeats])

Play a sound effect. The optional argument allows it to be repeated multiple times in succession.

wesnoth.audio.volume

• ♟ wesnoth.audio.volume ↔ volume

Get or set the current sound effect volume. Volume is a number from 1 to 100, and is taken as a percentage of the volume set by the user in preferences.

wesnoth.audio.sources

• ♟ wesnoth.audio.sources[id] ↔ sound source

Add, remove, or modify a sound source. Each value in this table is a sound source metadata. When assigning, you can assign nil, another sound source, or a WML table describing a sound source. Sound sources can be compared using the Lua equality operators. Each sound source contains the following fields:

• source.id → source ID

The ID of the sound source. This is the same as the key to which it is assigned in wesnoth.audio.sources.

• source.sounds ↔ list of sounds

A list of sound files to play. A file will be randomly chosen from this list. When assigning, a comma-separated string will automatically be split to produce a list.

• source.delay ↔ milliseconds

The minimum delay between instances of the sound. After the sound plays once, it won't be considered ready to play until this delay has passed (or until it scrolls offscreen and back onscreen).

• source.chance ↔ percentage

The percentage chance per tick to play this sound once it becomes ready to play.

• source.loop ↔ count

Specifies how much the sound source should loop while it stays visible. If set to -1, it will loop forever.

• source.range ↔ hexes

Distance within which the sound plays at full volume, measured in hexes from to the screen centre.

• source.fade_range ↔ hexes

Additional distance within which the sound remains audible, relative to the screen centre. This specifies the number of hexes between the edge of the range and the point where the sound fades out entirely.

• source.check_fogged ↔ boolean

Specifies whether the sound should play if it comes from a location under fog. If true, it won't play.

• source.check_shrouded ↔ boolean

Specifies whether the sound should play if it comes from a location under shroud. If true, it won't play.

• source.locations ↔ list of locations

Specifies the list of locations the sound source emanates from. When assigning, you can assign a single location instead of a list of them.

• source.__cfg → wml table

Converts the sound source specification to a WML table.

wesnoth.audio.music_list

This is a table giving access to the current music playlist. It can be accessed as a normal array, including the Lua length operator. If you assign a music config to an entry, the track is replaced. It is not a normal array however and cannot be manipulated with the table library. It also contains several fields and functions.

• ♟ #wesnoth.audio.music_list → number of songs

Returns the number of songs in the current playlist.

• ♟ wesnoth.audio.music_list[index] ↔ music track

Query or manipulate the music playlist. Each element of this list is a music track userdata, and when mutating the list, you can assign either a music track userdata or a WML table describing a music track. Assigning nil is also allowed.

Some things that can be done with this include swapping the order of two songs, removing a song from the playlist, adding a song to the playlist, replacing one song on the playlist with another, or adjusting the timing parameters of a song on the playlist.

Music tracks can be compared with the Lua equality operators. Each music track contains the following fields:

• track.once ↔ boolean

Whether the track is set to play only once. Generally only true for wesnoth.music_list.current.

• track.ms_before ↔ milliseconds

The fade time before the track plays.

• track.ms_after ↔ milliseconds

The fade time after the track plays.

• track.name → string

The unresolved filename of the track.

• track.title → string

The user-friendly track title, if available. The game attempts to load this from metadata in the music file if no title was specified in the track config when it was added.

• track.__cfg → wml table

Converts the track back to a WML table.

wesnoth.audio.music_list.current

• ♟ wesnoth.audio.music_list.current → music track
• ♟ wesnoth.audio.music_list.current_i ↔ index of the track

Returns the currently-playing music track. This may be a track that's not on the playlist, as "play once" tracks are not added to the playlist. In this event, current_i will return nil.

wesnoth.audio.music_list.previous

• ♟ wesnoth.audio.music_list.previous → music track

Returns the last track that played before the current one. This may sometimes be a track that's not on the playlist, as "play once" tracks are not placed on the playlist.

Note: This does not work correctly if checked after replacing the entire playlist.

wesnoth.audio.music_list.volume

• ♟ wesnoth.audio.music_list.volume ↔ volume

Get or set the current music volume. Volume is a number from 1 to 100, and is taken as a percentage of the volume set by the user in preferences.

wesnoth.audio.music_list.all

• ♟ wesnoth.audio.music_list.all → array

Returns a copy of the entire playlist as an array of WML tables.

wesnoth.audio.music_list.add

• ♟ wesnoth.audio.music_list.add(track_name, [immediate,] [ms_before, [ms_after]])

Appends a track to the playlist. If true is passed for immediate, also start playing the new track.

wesnoth.audio.music_list.remove

• ♟ wesnoth.audio.music_list.remove(n1, ...)

Removes one or more tracks by their index. You can pass as many indices as you wish. If one of the removed tracks is currently playing, it continues to play.

wesnoth.audio.music_list.clear

• ♟ wesnoth.audio.music_list.clear()

Clears the playlist. The currently-playing track continues to play.

wesnoth.audio.music_list.next

• ♟ wesnoth.audio.music_list.next()

Stop playing the current track and move on to the next one. This honours the shuffle settings.

wesnoth.audio.music_list.play

• ♟ wesnoth.audio.music_list.play(track_name)

Start playing a track without appending it to the playlist.