Difference between revisions of "LuaAPI/wesnoth/audio"

From The Battle for Wesnoth Wiki
(Categorize)
(Add context specifiers to each entry; it's redundant but it's useful redundancy)
Line 4: Line 4:
 
=== 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 10:
 
=== 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 16:
 
=== 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 68:
 
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 106:
 
=== 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 113:
 
=== 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 121:
 
=== 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 127:
 
=== 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 133:
 
=== 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 139:
 
=== 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 145:
 
=== 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 151:
 
=== 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 157:
 
=== 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]]
 
[[Category:Lua Reference]]

Revision as of 23:38, 4 July 2021

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.volumevolume

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.idsource ID

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

  • source.soundslist 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.delaymilliseconds

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.chancepercentage

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

  • source.loopcount

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

  • source.rangehexes

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

  • source.fade_rangehexes

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_foggedboolean

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

  • source.check_shroudedboolean

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

  • source.locationslist 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.__cfgwml 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_listnumber 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.onceboolean

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

  • track.ms_beforemilliseconds

The fade time before the track plays.

  • track.ms_aftermilliseconds

The fade time after the track plays.

  • track.namestring

The unresolved filename of the track.

  • track.titlestring

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.__cfgwml table

Converts the track back to a WML table.

wesnoth.audio.music_list.current

  • wesnoth.audio.music_list.currentmusic track
  • wesnoth.audio.music_list.current_iindex 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.previousmusic 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.volumevolume

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.allarray

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.