audio

Sound playback, mixing, music, procedural sound effects and 3D spatial sound.

Import

import { SfxPreset, Wave, Sfx, SoundGroup, ... } from "audio";

Needs the "audio" permission in thicket.json.

SoundPlayOptions class

class SoundPlayOptions

Type only: the runtime hands you instances; you never construct it yourself.

Playback options for a SoundChannel.

SoundPlayOptions.volume

volume?: float64

Volume; 0 is silent, 1 is normal.

SoundPlayOptions.pitch

pitch?: float64

Speed multiplier; 1.0 is normal speed.

SoundPlayOptions.pan

pan?: float64

Stereo pan; -1 is left, 0 is center, 1 is right.

SoundPlayOptions.loop

loop?: boolean

Whether playback repeats when it reaches the end.

SoundPlayOptions.group

group?: int

Sound group identifier; see SoundGroup constants.

SoundChannel class

class SoundChannel

Type only: the runtime hands you instances; you never construct it yourself.

SoundChannel.volume

volume: float64

Playback volume; 0 is silent, 1 is normal.

SoundChannel.pitch

pitch: float64

Playback speed multiplier; 1.0 is normal speed.

SoundChannel.pan

pan: float64

Stereo pan; -1 is left, 0 is center, 1 is right.

SoundChannel.spatialized

spatialized: boolean

Whether this sound uses 3D spatial positioning.

SoundChannel.position

position: Vec3 | float64

3D position in world space or 2D distance fallback.

SoundChannel.velocity

velocity: Vec3

3D velocity in world space for Doppler effect.

SoundChannel.minDistance

minDistance: float64

Closest distance for spatial attenuation falloff in world units.

SoundChannel.maxDistance

maxDistance: float64

Farthest distance for spatial attenuation falloff in world units.

SoundChannel.rolloff

rolloff: float64

Exponent for distance attenuation curve; typically 0.0–2.0.

SoundChannel.attenuation

attenuation: int

Spatial attenuation model; see Attenuation constants.

SoundChannel.position2D

position2D: float64

2D stereo pan when spatialized is false; -1 to 1.

SoundChannel.isPlaying

readonly isPlaying: boolean

True if the sound is currently playing. Read-only.

SoundChannel.playbackPosition

readonly playbackPosition: float64

The voice's live decoder cursor in seconds. Zero after it ends or is stolen.

SoundChannel.stop

stop(): void

Stops playback immediately.

SoundChannel.pause

pause(): void

Pauses playback; call resume() to continue.

SoundChannel.resume

resume(): void

Resumes playback after pause().

SoundChannel.onComplete

onComplete(callback: () => void): void

Runs once on the main thread in the frame after natural playback completion.

Sound class

class Sound

Type only: the runtime hands you instances; you never construct it yourself.

Sound.duration

readonly duration: float64

The decoded source length in seconds.

Sound.play

play(options?: SoundPlayOptions): SoundChannel

Begins playback and returns a SoundChannel for real-time control.

Sound.unload

unload(): void

Frees decoded audio and invalidates all SoundChannels from this sound.

MusicTrack class

class MusicTrack

Type only: the runtime hands you instances; you never construct it yourself.

A streamed music asset returned by Audio.loadMusic(path).

MusicTrack.unload

unload(): void

Stops playback and frees resources.

SfxPreset static class

static class SfxPreset

Named procedural sound-effect recipes.

static readonly COIN: int
static readonly LASER: int
static readonly EXPLOSION: int
static readonly POWERUP: int
static readonly HIT: int
static readonly JUMP: int
static readonly BLIP: int
static readonly RANDOM: int

Wave static class

static class Wave

Oscillator wave shapes for Sfx.tone.

static readonly SINE: int
static readonly SQUARE: int
static readonly TRIANGLE: int
static readonly SAWTOOTH: int
static readonly NOISE: int

Sfx static class

static class Sfx

Static procedural sound-effect synthesizer.

Sfx.generate

static generate(preset: int, seed?: int): Sound

Generate a reusable Sound asset from a named preset and optional deterministic seed.

Parameters

• preset: A SfxPreset constant.
• seed: Optional deterministic seed; omitted or 0 for random variation.

Returns: A new Sound asset that can be played multiple times.

Sfx.play

static play(preset: int, seed?: int): void

Play a preset immediately as a one-shot effect.

Parameters

• preset: A SfxPreset constant.
• seed: Optional deterministic seed; omitted or 0 for random variation.

Sfx.tone

static tone(frequency: float64, durationMs: int, wave?: int): void

Play an oscillator tone for the given duration.

Parameters

• frequency: Frequency in Hz.
• durationMs: Duration in milliseconds.
• wave: Optional Wave constant; defaults to SINE.

AudioListener class

class AudioListener

Type only: the runtime hands you instances; you never construct it yourself.

position: Vec3
direction: Vec3

SoundGroup static class

static class SoundGroup

Top-level sound mix-group constants.

SoundGroup.Music

static readonly Music: int

Deprecated

Use MUSIC.

SoundGroup.Voice

static readonly Voice: int

Deprecated

Use VOICE.

SoundGroup.Ambient

static readonly Ambient: int

Deprecated

Use AMBIENT.

Other members of SoundGroup

static readonly SFX: int
static readonly MUSIC: int
static readonly VOICE: int
static readonly AMBIENT: int
static readonly UI: int

Attenuation static class

static class Attenuation

Top-level spatial attenuation constants.

Attenuation.None

static readonly None: int

Deprecated

Use NONE.

Attenuation.InverseDistance

static readonly InverseDistance: int

Deprecated

Use INVERSE.

Attenuation.LinearDistance

static readonly LinearDistance: int

Deprecated

Use LINEAR.

Attenuation.ExponentialDistance

static readonly ExponentialDistance: int

Deprecated

Use EXPONENTIAL.

Other members of Attenuation

static readonly NONE: int
static readonly INVERSE: int
static readonly LINEAR: int
static readonly EXPONENTIAL: int

Audio static class

static class Audio

Audio.SoundGroup

static readonly SoundGroup: any

Deprecated

Use top-level SoundGroup.

Audio.AttenuationModel

static readonly AttenuationModel: any

Deprecated

Use top-level Attenuation.

Audio.loadSound

static loadSound(path: string, group?: int): Promise<Sound>
static loadSound(buffer: Buffer, group?: int): Promise<Sound>

Loads a sound asset from a project or bundled path.

Parameters

• path: Project or bundled asset path.
• group: Optional sound group; see SoundGroup constants.

Returns: Promise that resolves to a loaded Sound.

Example

import { Audio, Sound } from "audio";
const click: Sound = await Audio.loadSound("assets/click.wav");
Audio.play(click);

Audio.play

static play(sound: Sound | int, options?: SoundPlayOptions | float64, pitch?: float64, loop?: boolean): SoundChannel | void

Begins playback of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.
• options: Optional SoundPlayOptions or volume (float64).
• pitch: Optional speed multiplier.
• loop: Optional boolean for looping playback.

Returns: SoundChannel if sound is a Sound object, void if a handle.

Audio.unloadSound

static unloadSound(sound: Sound | int): void

Stops playback and frees resources for the given sound.

Parameters

• sound: Sound object or numeric handle.

Audio.stop

static stop(sound: Sound | int): void

Stops playback of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.

Audio.setSoundVolume

static setSoundVolume(sound: Sound | int, volume: float64): void

Sets the volume of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.
• volume: Volume; 0 is silent, 1 is normal.

Audio.soundVolume

static soundVolume(sound: Sound | int): float64

Reads the current volume of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.

Returns: Current volume in range 0..1.

Audio.setSoundPitch

static setSoundPitch(sound: Sound | int, pitch: float64): void

Sets the pitch (speed) of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.
• pitch: Speed multiplier; 1.0 is normal speed.

Audio.soundPitch

static soundPitch(sound: Sound | int): float64

Reads the current pitch of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.

Returns: Current pitch multiplier.

Audio.setSoundPan

static setSoundPan(sound: Sound | int, pan: float64): void

Sets the pan (left/right balance) of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.
• pan: Stereo pan; -1 is left, 0 is center, 1 is right.

Audio.soundPan

static soundPan(sound: Sound | int): float64

Reads the current pan of a sound or sound channel.

Parameters

• sound: Sound object or numeric handle.

Returns: Current pan in range -1..1.

Audio.playPanned

static playPanned(sound: Sound | int, pan: float64, volume?: float64, pitch?: float64, loop?: boolean): void

Plays a sound with a specific pan and volume.

Parameters

• sound: Sound object or numeric handle.
• pan: Stereo pan; -1 is left, 0 is center, 1 is right.
• volume: Optional volume; 0 is silent, 1 is normal.
• pitch: Optional speed multiplier.
• loop: Optional boolean for looping playback.

Audio.loadMusic

static loadMusic(path: string): Promise<MusicTrack>

Streams a music asset from a project or bundled path.

Parameters

• path: Project or bundled asset path.

Returns: Promise that resolves to a loaded MusicTrack.

Audio.unloadMusic

static unloadMusic(track: MusicTrack | int): void

Stops playback and frees resources for the given music track.

Parameters

• track: MusicTrack object or numeric handle.

Audio.playMusicHandle

static playMusicHandle(track: MusicTrack, volume?: float64, loop?: boolean, startSeconds?: float64): void
static playMusicHandle(id: int, volume?: float64, loop?: boolean, startSeconds?: float64): void

Begins playback of a music track.

Parameters

• track: MusicTrack object to play.
• volume: Optional volume; 0 is silent, 1 is normal.
• loop: Optional boolean for looping playback.
• startSeconds: Optional start point in seconds (default 0), e.g. a saved musicPosition().

Example

import { Audio, MusicTrack } from "audio";
const theme: MusicTrack = await Audio.loadMusic("assets/theme.ogg");
Audio.playMusicHandle(theme, 0.8, true);

Audio.crossfadeTo

static crossfadeTo(track: MusicTrack, durationMs: int, volume?: float64, loop?: boolean): void
static crossfadeTo(id: int, durationMs: int, volume?: float64, loop?: boolean): void

Crossfades to a new music track over a specified duration.

Parameters

• track: MusicTrack object to crossfade to.
• durationMs: Crossfade duration in milliseconds.
• volume: Optional target volume; 0 is silent, 1 is normal.
• loop: Optional boolean for looping playback.

Audio.stopMusic

static stopMusic(fadeMs?: int): void

Stops music playback with optional fade-out.

Parameters

• fadeMs: Optional fade-out duration in milliseconds.

Audio.pauseMusic

static pauseMusic(): void

Pauses music playback.

Audio.resumeMusic

static resumeMusic(): void

Resumes music playback after pauseMusic().

Audio.musicPlaying

static musicPlaying(): boolean

Returns true if music is currently playing.

Audio.activeMusic

static activeMusic(): int

Returns the numeric handle of the currently playing track, or 0 if none.

Audio.musicPosition

static musicPosition(): float64

Playback position of the active music track in seconds (playing or paused), or 0 if none.

Audio.masterVolume

static masterVolume: float64

Master mixer gain, clamped to 0..1.

Audio.sfxVolume

static sfxVolume: float64

Sound-effects mix-group gain, clamped to 0..1.

Audio.musicVolume

static musicVolume: float64

Music mix-group gain, clamped to 0..1.

Audio.listener

static readonly listener: AudioListener

The 3D listener's position and orientation for spatial audio. Read-only.

Audio.setMasterVolume

static setMasterVolume(volume: float64): void

Deprecated

Assign masterVolume.

Audio.setSfxVolume

static setSfxVolume(volume: float64): void

Deprecated

Assign sfxVolume.

Audio.setMusicVolume

static setMusicVolume(volume: float64): void

Deprecated

Assign musicVolume.

Audio.setGroupVolume

static setGroupVolume(group: int, volume: float64): void

Sets the volume for a sound group.

Parameters

• group: A SoundGroup constant.
• volume: Volume; 0 is silent, 1 is normal.

Audio.groupVolume

static groupVolume(group: int): float64

Reads the volume for a sound group.

Parameters

• group: A SoundGroup constant.

Returns: Current volume in range 0..1.

Audio.setListenerPosition

static setListenerPosition(x: float64, y: float64, z: float64): void

Sets the 3D listener position for spatial audio.

Parameters

• x: World x coordinate.
• y: World y coordinate.
• z: World z coordinate.

Audio.setListenerDirection

static setListenerDirection(fx: float64, fy: float64, fz: float64, ux?: float64, uy?: float64, uz?: float64): void

Sets the 3D listener orientation for spatial audio.

Parameters

• fx: Forward vector x component.
• fy: Forward vector y component.
• fz: Forward vector z component.
• ux: Optional up vector x; defaults to 0.
• uy: Optional up vector y; defaults to 1.
• uz: Optional up vector z; defaults to 0.

Audio.listenerPosition

static listenerPosition(): Vec3

Reads the 3D listener position.

Returns: Current listener position as Vec3.

Audio.setSoundPosition

static setSoundPosition(sound: Sound | int, x: float64, y: float64, z: float64): void

Sets the 3D world position of a sound.

Parameters

• sound: Sound object or numeric handle.
• x: World x coordinate.
• y: World y coordinate.
• z: World z coordinate.

Audio.setSoundSpatialized

static setSoundSpatialized(sound: Sound | int, enabled: boolean): void

Enables or disables 3D spatial positioning for a sound.

Parameters

• sound: Sound object or numeric handle.
• enabled: True to use 3D positioning, false for 2D panning only.

Audio.setSoundDistanceRange

static setSoundDistanceRange(sound: Sound | int, minDist: float64, maxDist: float64): void

Sets the distance range for spatial attenuation.

Parameters

• sound: Sound object or numeric handle.
• minDist: Minimum distance in world units; no attenuation closer than this.
• maxDist: Maximum distance in world units; silent beyond this.

Audio.setSoundRolloff

static setSoundRolloff(sound: Sound | int, rolloff: float64): void

Sets the rolloff factor for distance attenuation.

Parameters

• sound: Sound object or numeric handle.
• rolloff: Rolloff exponent; typical range 0.0–2.0.

Audio.soundRolloff

static soundRolloff(sound: Sound | int): float64

Reads the rolloff factor of a sound.

Parameters

• sound: Sound object or numeric handle.

Returns: Current rolloff exponent.

Audio.setSoundDopplerFactor

static setSoundDopplerFactor(sound: Sound | int, factor: float64): void

Sets the Doppler effect factor for a sound.

Parameters

• sound: Sound object or numeric handle.
• factor: Doppler factor; 1.0 is realistic, 0.0 disables the effect.

Audio.soundDopplerFactor

static soundDopplerFactor(sound: Sound | int): float64

Reads the Doppler effect factor of a sound.

Parameters

• sound: Sound object or numeric handle.

Returns: Current Doppler factor.

Audio.setSoundVelocity

static setSoundVelocity(sound: Sound | int, x: float64, y: float64, z: float64): void

Sets the 3D velocity of a sound for Doppler effects.

Parameters

• sound: Sound object or numeric handle.
• x: Velocity x component.
• y: Velocity y component.
• z: Velocity z component.

Audio.setSoundAttenuationModel

static setSoundAttenuationModel(sound: Sound | int, model: int): void

Sets the spatial attenuation model for a sound.

Parameters

• sound: Sound object or numeric handle.
• model: An Attenuation constant.

Audio.soundAttenuationModel

static soundAttenuationModel(sound: Sound | int): int

Reads the spatial attenuation model of a sound.

Parameters

• sound: Sound object or numeric handle.

Returns: Current Attenuation constant.

Audio.playSpatial

static playSpatial(sound: Sound | int, x: float64, y: float64, z: float64, minDist?: float64, maxDist?: float64, volume?: float64, pitch?: float64, loop?: boolean): void

Plays a sound at a 3D position with optional attenuation.

Parameters

• sound: Sound object or numeric handle.
• x: World x coordinate.
• y: World y coordinate.
• z: World z coordinate.
• minDist: Optional minimum distance for attenuation.
• maxDist: Optional maximum distance for attenuation.
• volume: Optional volume; 0 is silent, 1 is normal.
• pitch: Optional speed multiplier.
• loop: Optional boolean for looping playback.

Music static class

static class Music

Global background-music playback. Audio's music methods remain aliases.

Music.volume

static volume: float64

Music volume; 0 is silent, 1 is normal.

Music.isPlaying

static readonly isPlaying: boolean

True if music is currently playing. Read-only.

Music.current

static readonly current: int

Numeric handle of the currently playing track, or 0 if none. Read-only.

Music.play

static play(track: int | MusicTrack): void

Begins playback of a music track.

Parameters

• track: MusicTrack object or numeric handle.

Music.crossfade

static crossfade(track: int | MusicTrack, ms: int): void

Crossfades to a new music track over a specified duration.

Parameters

• track: MusicTrack object or numeric handle to crossfade to.
• ms: Crossfade duration in milliseconds.

Music.pause

static pause(): void

Pauses music playback.

Music.resume

static resume(): void

Resumes music playback after pause().

Music.stop

static stop(fadeMs?: int): void

Stops music playback with optional fade-out.

Parameters

• fadeMs: Optional fade-out duration in milliseconds.

audio const

const audio: any

Deprecated

Use Audio.

---

Generated from lang/types/audio.d.tks in the ThicketScript repository.