audio module

Sound playback: play starts a node's sound component and returns a handle that stop_playback, set_volume_linear, set_pitch_scale and is_playing take…

Di halaman ini

Functions
Constants

Sound playback: play starts a node's sound component and returns a handle that stop_playback, set_volume_linear, set_pitch_scale and is_playing take; seek and skip move it. play_cue plays a sound named in audio/cues.toml, from a position heard from the listener when given one. A node's sound announces finished (EVENT_FINISHED) with the handle when it plays out. devices lists the outputs [audio] device can name.

23 functions, 1 constant. Scripts reach it as audio::.

Acts on sound: those functions are also methods on the component's handle, without the node argument.

Functions

Argument kinds are the script values a call passes: node is a node handle, any a table or value of any kind, fn a callback.

function	acts on	what it does
`bus_limit(string) -> any`	—	One bus's limiter as `[audio.buses]` declares it: `limit`, `limit_threshold_db`, `limit_knee_db`, `limit_attack_time` and `limit_release_time`. Nil for a bus with none.
`bus_volume_linear(string) -> float`	—	One bus's own gain, without its parents'.
`buses() -> any`	—	Every audio bus, declared in `[audio.buses]` or made by setting a volume, in name order.
`cues() -> any`	—	Every sound named in `audio/cues.toml`, in name order.
`device_ready() -> bool`	—	Whether an output device is open. False on a page until the first gesture, and false for good with no sound card; playing before then hands out handles that make no sound.
`devices() -> any`	—	Every output device's name, as `[audio] device` takes it. Empty when the platform lists none.
`distance_gain(int) -> any`	—	The gain the distance to the listener is costing a positional handle right now: 1 up close, 0 out of range.
`emitter_position(int) -> any`	—	Where a handle played with a `position` is; nil for a flat or unknown one.
`is_playing(int) -> bool`	—	Whether a handle's sound is still going: false once it plays out or is stopped, on the same tick with or without an output device.
`listener_position() -> any`	—	Where the ears are: the current `listener` node's world position, or what `set_listener_position` last put there.
`pan(int) -> any`	—	Where a positional handle sits between the speakers: -1 hard left, 0 centred, 1 hard right.
`play(node) -> int`	`sound`	Start the node's own `sound` from the top, replacing what it had going, and return the new handle.
`play_cue(string, any?) -> any`	—	Play a named sound: the next of its variations in turn, at its own volume and pitch, through its own bus. A `position` in the options table places it. Nil for a name nothing declared.
`seek(node, float)`	`sound`	Jump the node's sound to `seconds` into the file it is playing; `playback_time` reads it back. A node with nothing playing is left alone.
`set_bus_volume_linear(string, float)`	—	Set one bus's gain and re-apply it to everything already playing on it: which is what a volume slider is.
`set_emitter_position(int, any, any?, any?)`	—	Move what a handle plays from, so a sound follows something the script is driving; the frame takes its doppler from how far it moved.
`set_listener_position(any, any?, any?)`	—	Put the ears at a point by hand, for a game whose view is not a node; a `listener` node in the scene takes it back on the next frame.
`set_pitch_scale(int, float)`	—	Set a playing handle's speed multiplier, which carries its pitch with it.
`set_volume_linear(int, float)`	—	Set a playing handle's linear gain, where 1 is the file's own level.
`skip(node)`	`sound`	Move the node's sound on to the next file in its `queue`. Past the last one it has played out, and the node announces `finished`.
`stop(node)`	`sound`	Silence what the node's `sound` started, over its `fade_out_time`; a node carrying none is left alone.
`stop_all()`	—	Silence everything at once and clear the playback every `sound` component was holding.
`stop_playback(int)`	—	Silence the sound a handle names, over the `fade_out_time` its `sound` had; a finished, stopped or unknown handle is left alone.

Constants

name	value
`EVENT_FINISHED`	`finished`