Skip to content

Search

Documentation

sound component

A sound on the node: file, volume_linear, pitch_scale and loop, with its layers mixed in and its queue played after it. autoplay starts it on load…

このページの内容

audio · 37 properties · Audio

A sound on the node: file, volume_linear, pitch_scale and loop, with its layers mixed in and its queue played after it. autoplay starts it on load, node.sound.play() triggers it, seek and skip move it, positional plays it from the node for the listener, and the node announces finished when it plays out. Filters, distortion, reverb and automatic gain control are rodio's.

In a scene, sound is the node key that applies it. A script reaches each property below as a field on node.sound: reading one asks the running component, and assigning one leaves the rest alone. The whole table is node.sound.get() and node.sound.set(table).

Properties

property type default description
attenuation enum inverse How a positional sound falls off past min_distance: inverse halves its gain at every doubling of distance, inverse_square quarters it One of inverse, inverse_square.
auto_gain bool false Even the level out with automatic gain control. Read when it starts; turning it off while playing bypasses it
auto_gain_attack_time float 4 Seconds it takes to answer the level rising Range 0–10.
auto_gain_floor float 0 The least gain it applies At least 0.
auto_gain_max float 7 The most gain it applies At least 0.
auto_gain_release_time float 0 Seconds it takes to answer the level falling Range 0–10.
auto_gain_target float 1 The level it holds the sound at; 1 is the file's own At least 0.
autoplay bool false Start playing when the node enters the scene
bus string — Audio bus this plays through; empty is master
crossfade_time float 0 Seconds a playing sound fades out over when file changes, while the new file, if autoplay starts it, fades in; 0 cuts At least 0.
delay float 0 Seconds of silence before the sound starts. Read when it starts At least 0.
distortion_gain float 1 Gain before the distortion's clip At least 0.
distortion_threshold float 0 Level samples are clipped at after distortion_gain; 0 is off Range 0–1.
doppler_level float 0 How much the closing speed bends the pitch; 0 is off, 1 physical At least 0.
end_time float 0 Seconds into file each play stops at, and a loop turns back at; 0 plays to the end. Read when it starts At least 0.
fade_in_time float 0 Seconds the sound rises from silence over when it starts At least 0.
fade_out_time float 0 Seconds the sound falls to silence over: the last ones before it plays out, and the first after audio.stop At least 0.
file string — Audio file, project-relative; required to play
high_pass_hz float 0 Cut what is below this frequency; 0 is off At least 0.
high_pass_q float 0.5 How sharply the high-pass turns at its cutoff; higher rings there At least 0.01.
layers list [] Files mixed with file for its whole length, each at its own import level. Read when it starts
loop bool false Restart the sound when it ends; with a queue, each file repeats until node.sound.skip() moves on
loop_offset float -1 Seconds into file every repeat after the first starts from; below 0 takes the file's own loop_offset import setting. Read when it starts At least -1.
low_pass_hz float 0 Cut what is above this frequency; 0 is off At least 0.
low_pass_q float 0.5 How sharply the low-pass turns at its cutoff; higher rings there At least 0.01.
max_distance float 50 Silent beyond this distance from the listener At least 0.001.
min_distance float 1 Full volume within this distance of the listener At least 0.001.
pan float 0 Balance of a sound that is not positional: -1 left, 0 both channels at full, 1 right. A positional sound is panned by where it is Range -1–1.
paused bool false Hold the sound where it is; playback_time and the count to finished hold with it
pitch_scale float 1 Playback speed multiplier At least 0.01.
playback_time float 0 Seconds into the file playing now, counted on the fixed step so a run with no output device reads the same; 0 when nothing plays Read-only: engine output the inspector shows but never writes.
positional bool false Place the sound where the node is, heard from the listener
queue list [] Files played after file, in order and without a gap; node.sound.skip() moves to the next. Read when it starts
reverb_level float 0 Gain of that echo At least 0.
reverb_time float 0 Seconds an echo of the sound trails it by; 0 is off. Read when it starts At least 0.
start_time float 0 Seconds into file each play starts from. Read when it starts At least 0.
volume_linear float 1 Linear gain; 1 is the file's own level At least 0.

Script functions

Methods of node.sound, the handle a node carrying this component exposes. Every handle also has get(), set(table), patch(table), has() and remove().

From audio:

method what it does
play() -> int Start the node's own sound from the top, replacing what it had going, and return the new handle.
seek(float) 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.
skip() 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() Silence what the node's sound started, over its fade_out_time; a node carrying none is left alone.