View source for LuaAPI/wesnoth/audio


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

== Functions ==

=== wesnoth.audio.play ===

* {{LuaGameOnly}} '''wesnoth.audio.play'''(''sound'', [''repeats''])

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

=== wesnoth.audio.volume ===

* {{LuaGameOnly}} '''wesnoth.audio.volume''' &harr; ''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.sources'''[''id''] &harr; ''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''' &rarr; ''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''' &harr; ''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''' &harr; ''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''' &harr; ''percentage''

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

* ''source''.'''loop''' &harr; ''count''

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

* ''source''.'''range''' &harr; ''hexes''

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

* ''source''.'''fade_range''' &harr; ''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''' &harr; ''boolean''

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

* ''source''.'''check_shrouded''' &harr; ''boolean''

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

* ''source''.'''locations''' &harr; ''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''' &rarr; ''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.

* {{LuaGameOnly}} #'''wesnoth.audio.music_list''' &rarr; ''number of songs''

Returns the number of songs in the current playlist.

* {{LuaGameOnly}} '''wesnoth.audio.music_list'''[''index''] &harr; ''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''' &harr; ''boolean''

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

* ''track''.'''ms_before''' &harr; ''milliseconds''

The fade time before the track plays.

* ''track''.'''ms_after''' &harr; ''milliseconds''

The fade time after the track plays.

* ''track''.'''name''' &rarr; ''string''

The unresolved filename of the track.

* ''track''.'''title''' &rarr; ''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'' &rarr; ''wml table''

Converts the track back to a WML table.

=== wesnoth.audio.music_list.current ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.current''' &rarr; ''music track''
* {{LuaGameOnly}} '''wesnoth.audio.music_list.current_i''' &harr; ''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.previous''' &rarr; ''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.volume''' &harr; ''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.all''' &rarr; ''array''

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

=== wesnoth.audio.music_list.add ===

* {{LuaGameOnly}} '''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 ===

* {{LuaGameOnly}} '''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.clear'''()

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

=== wesnoth.audio.music_list.next ===

* {{LuaGameOnly}} '''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 ===

* {{LuaGameOnly}} '''wesnoth.audio.music_list.play'''(''track_name'')

Start playing a track without appending it to the playlist.

[[Category:Lua Reference]]