Skip to content

Search

Documentation

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…

このページの内容

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