Difference between revisions of "LuaAPI/wesnoth/audio"
(Document the wesnoth.audio module) |
|||
| (2 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
The audio module is only available in the game. It contains functions for playing music and sound effects. | The audio module is only available in the game. It contains functions for playing music and sound effects. | ||
| + | |||
| + | == Functions == | ||
=== wesnoth.audio.play === | === wesnoth.audio.play === | ||
| − | * '''wesnoth.audio.play'''(''sound'', [''repeats'']) | + | * {{LuaGameOnly}} '''wesnoth.audio.play'''(''sound'', [''repeats'']) |
Play a sound effect. The optional argument allows it to be repeated multiple times in succession. | Play a sound effect. The optional argument allows it to be repeated multiple times in succession. | ||
| Line 10: | Line 12: | ||
=== wesnoth.audio.volume === | === wesnoth.audio.volume === | ||
| − | * '''wesnoth.audio.volume''' ↔ ''volume'' | + | * {{LuaGameOnly}} '''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. | 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. | ||
| Line 16: | Line 18: | ||
=== wesnoth.audio.sources === | === wesnoth.audio.sources === | ||
| − | * '''wesnoth.audio.sources'''[''id''] ↔ ''sound source'' | + | * {{LuaGameOnly}} '''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: | 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: | ||
| Line 68: | Line 70: | ||
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. | 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'' | + | * {{LuaGameOnly}} #'''wesnoth.audio.music_list''' → ''number of songs'' |
Returns the number of songs in the current playlist. | Returns the number of songs in the current playlist. | ||
| − | * '''wesnoth.audio.music_list'''[''index''] ↔ ''music track'' | + | * {{LuaGameOnly}} '''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. | 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. | ||
| Line 106: | Line 108: | ||
=== wesnoth.audio.music_list.current === | === wesnoth.audio.music_list.current === | ||
| − | * '''wesnoth.audio.music_list.current''' → ''music track'' | + | * {{LuaGameOnly}} '''wesnoth.audio.music_list.current''' → ''music track'' |
| − | * '''wesnoth.audio.music_list.current_i''' ↔ ''index of the track'' | + | * {{LuaGameOnly}} '''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. | 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. | ||
| Line 113: | Line 115: | ||
=== wesnoth.audio.music_list.previous === | === wesnoth.audio.music_list.previous === | ||
| − | * '''wesnoth.audio.music_list.previous''' → ''music track'' | + | * {{LuaGameOnly}} '''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. | 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. | ||
| Line 121: | Line 123: | ||
=== wesnoth.audio.music_list.volume === | === wesnoth.audio.music_list.volume === | ||
| − | * '''wesnoth.audio.music_list.volume''' ↔ ''volume'' | + | * {{LuaGameOnly}} '''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. | 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. | ||
| Line 127: | Line 129: | ||
=== wesnoth.audio.music_list.all === | === wesnoth.audio.music_list.all === | ||
| − | * '''wesnoth.audio.music_list.all''' → ''array'' | + | * {{LuaGameOnly}} '''wesnoth.audio.music_list.all''' → ''array'' |
Returns a copy of the entire playlist as an array of WML tables. | Returns a copy of the entire playlist as an array of WML tables. | ||
| Line 133: | Line 135: | ||
=== wesnoth.audio.music_list.add === | === wesnoth.audio.music_list.add === | ||
| − | * '''wesnoth.audio.music_list.add'''(''track_name'', [''immediate'',] [''ms_before'', [''ms_after'']]) | + | * {{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. | Appends a track to the playlist. If true is passed for ''immediate'', also start playing the new track. | ||
| Line 139: | Line 141: | ||
=== wesnoth.audio.music_list.remove === | === wesnoth.audio.music_list.remove === | ||
| − | * '''wesnoth.audio.music_list.remove'''(''n1'', ...) | + | * {{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. | 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. | ||
| Line 145: | Line 147: | ||
=== wesnoth.audio.music_list.clear === | === wesnoth.audio.music_list.clear === | ||
| − | * '''wesnoth.audio.music_list.clear'''() | + | * {{LuaGameOnly}} '''wesnoth.audio.music_list.clear'''() |
Clears the playlist. The currently-playing track continues to play. | Clears the playlist. The currently-playing track continues to play. | ||
| Line 151: | Line 153: | ||
=== wesnoth.audio.music_list.next === | === wesnoth.audio.music_list.next === | ||
| − | * '''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. | Stop playing the current track and move on to the next one. This honours the shuffle settings. | ||
| Line 157: | Line 159: | ||
=== wesnoth.audio.music_list.play === | === wesnoth.audio.music_list.play === | ||
| − | * '''wesnoth.audio.music_list.play'''(''track_name'') | + | * {{LuaGameOnly}} '''wesnoth.audio.music_list.play'''(''track_name'') |
Start playing a track without appending it to the playlist. | Start playing a track without appending it to the playlist. | ||
| + | |||
| + | [[Category:Lua Reference]] | ||
Latest revision as of 17:53, 18 April 2024
The audio module is only available in the game. It contains functions for playing music and sound effects.
Contents
- 1 Functions
- 1.1 wesnoth.audio.play
- 1.2 wesnoth.audio.volume
- 1.3 wesnoth.audio.sources
- 1.4 wesnoth.audio.music_list
- 1.5 wesnoth.audio.music_list.current
- 1.6 wesnoth.audio.music_list.previous
- 1.7 wesnoth.audio.music_list.volume
- 1.8 wesnoth.audio.music_list.all
- 1.9 wesnoth.audio.music_list.add
- 1.10 wesnoth.audio.music_list.remove
- 1.11 wesnoth.audio.music_list.clear
- 1.12 wesnoth.audio.music_list.next
- 1.13 wesnoth.audio.music_list.play
Functions
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.