LuaAPI/wesnoth/audio - Revision history

Laela at 17:53, 18 April 2024

2024-04-18T17:53:44Z

← Older revision		Revision as of 17:53, 18 April 2024
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 ===

Celtic Minstrel: Add context specifiers to each entry; it's redundant but it's useful redundancy

2021-07-04T23:38:19Z

Add context specifiers to each entry; it's redundant but it's useful redundancy

Celtic Minstrel: Categorize

2021-06-30T02:32:04Z

Categorize

← Older revision		Revision as of 02:32, 30 June 2021
Line 160:		Line 160:

	Start playing a track without appending it to the playlist.		Start playing a track without appending it to the playlist.

			[[Category:Lua Reference]]

Celtic Minstrel: Document the wesnoth.audio module

2021-05-16T05:15:04Z

Document the wesnoth.audio module

New page

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.

← Older revision		Revision as of 23:38, 4 July 2021
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]]