Audio

Bus volume, mute, and the browser autoplay-unlock state. For the higher-level subsystem walkthrough (bus graph layout, locked vs. unlocked, and web autoplay constraints), see the Audio Guide.

The audio graph has three buses: 'sfx' and 'music' feed into 'main', which feeds the browser's audio destination. All three are independently controllable.

sfx    ─┐
music  ─┼─► main ─► destination

AudioBus is the type of a bus name:

declare const bus: AudioBus; // 'main' | 'music' | 'sfx'

Volume

BT.audioVolumeSet sets a bus's volume, optionally fading to it. BT.audioVolumeGet reads it back.

BT.audioVolumeSet('music', 0.5); // immediate change
BT.audioVolumeSet('sfx', 0, { fadeMs: 300 }); // linear fade to silence over 300 ms
BT.audioVolumeSet('main', 0.8, { fadeMs: 500, easing: 'ease-out' }); // eased fade

BT.audioVolumeGet('music'); // 0.5

options fields:

With no fadeMs, the bus gain changes immediately. With fadeMs, 'linear' easing schedules a linear ramp; any other easing curve is sampled into a value curve so the fade follows that curve rather than a straight line.

Mute

BT.audioMuteSet mutes or unmutes a bus without touching its configured volume. BT.isAudioMuted reports the current mute state.

BT.audioVolumeSet('music', 0.75);

BT.audioMuteSet('music', true); // silences the bus immediately (no fade)
BT.isAudioMuted('music'); // true
BT.audioVolumeGet('music'); // still 0.75 - muting never overwrites the configured level

BT.audioMuteSet('music', false); // restores audio at 0.75

BT.audioVolumeGet always returns the logical (pre-mute) volume, so reading it while muted still reports the level you configured, not 0.

Unlock state

Browsers block audio playback until a user gesture. BT.isAudioUnlocked is false until the first pointerdown, pointerup, touchend, or keydown on the canvas successfully resumes the audio context, and stays true for the rest of the session. On a touch screen that is the end of the first tap, since touchstart is not a user activation.

if (!BT.isAudioUnlocked) {
  // Show a "click or press a key to enable audio" prompt.
}

See Web audio constraints for what happens to volume/mute calls made before the gesture, and why no configure flag can skip this requirement.

A BT.renderAt seek suspends the context while the loop is stopped (a gesture that unlocks audio mid-seek stays suspended too) and drops BT.soundPlay calls made by stepped updates; BT.resume() brings it back. See Seeking a frame with renderAt.

Loading

AudioClip decodes an audio file into a reusable AudioBuffer, exposing the winning source URL, duration, and sample rate. Loading and decoding work even while the audio context is locked (suspended, pre-gesture) - only real-time playback needs an unlocked context. See Preloading audio clips.

import { AudioClip } from 'blit386';

// Load a single clip (cached by its resolved URL)
const theme = await AudioClip.load('audio/theme.mp3');

// Fallback list: tries each URL in order, resolving with the first that decodes
const hit = await AudioClip.load(['audio/hit.ogg', 'audio/hit.mp3']);

// Load multiple clips in parallel - each entry is a single URL or a fallback list
const clips = await AudioClip.loadAll(['audio/theme.mp3', ['audio/hit.ogg', 'audio/hit.mp3']]);

// Check cache before loading
if (AudioClip.isLoaded('audio/theme.mp3')) {
  // already cached
}

// Number of clip loads currently in flight
AudioClip.loadingCount;

For a single loading-screen signal that also covers sprite sheet images, see BT.loadingAssetsCount.

Pass onProgress to report phased load progress:

await AudioClip.load('audio/theme.mp3', {
  onProgress: (progress) => {
    console.log(progress.phase, progress.ratio);
  },
});

Release a clip's decoded buffer with unload() once you no longer need it:

theme.unload(); // releases the decoded buffer; safe to call more than once

• AudioClip.load() and loadAll() throw a beginner-friendly error covering network/CORS failures, HTTP status errors, unsupported container/codec decode failures, and loading before the engine has started.
• Prefer a fallback list (for example ['theme.ogg', 'theme.mp3']) for any clip whose primary format might not decode in every browser - see Audio formats.
• Playing a loaded clip back as SFX is covered in Playback (SFX) below; as looping, crossfading music in Playback (Music).

Under a Vite dev server with the blit386/vite plugin installed, editing an audio file under a watched asset directory (public/ by default) swaps the decoded buffer inside the same AudioClip instance - demo-held references stay valid. Any SFX voice still playing the old buffer is stopped; if the replaced clip is the currently playing music track, playback restarts immediately (fadeMs: 0, no crossfade). duration/sampleRate reflect the buffer decoded at initial load and are not updated by a hot reload. See Hot Reload for the full asset type matrix.

Synth

AudioClip.synth renders a clip procedurally from a SynthParams descriptor - no source file, no network request, and no OfflineAudioContext. Rendering runs entirely on the CPU and is deterministic: identical params (including seed) always produce identical sample data, so a SynthParams object can be stored and replayed as a preset. Unlike Loading, there is nothing to fetch or decode from the network - a synthesized clip is ready the instant synth() resolves, even before BT.isAudioUnlocked is true (see Unlock state above).

import { AudioClip } from 'blit386';

const laser = await AudioClip.synth({
  waveform: 'sawtooth',
  frequency: 880,
  duration: 0.3,
  pitchSweep: { toFrequency: 110 },
  seed: 1,
});

SynthParams fields:

SynthEnvelope fields (all optional, times in seconds):

The release phase always finishes exactly at duration, even on a very short clip where the attack, decay, and release phases overlap - a percussive hit is never cut off mid-fade.

SynthPitchSweep fields:

SynthVibrato fields (both optional):

import { AudioClip, BT } from 'blit386';

// A short, noisy boom: mostly noise, with a touch of low square tone, quick attack and decay.
const boom = await AudioClip.synth({
  waveform: 'square',
  frequency: 90,
  duration: 0.4,
  noiseMix: 0.8,
  envelope: { attack: 0, decay: 0.05, sustain: 0.3, release: 0.3 },
  seed: 42,
});

BT.soundPlay(boom, { volume: 0.7 });

Presets

BT.synthPreset bundles six ready-made SynthParams factories for common sound effects: jump, pickup, explosion, laser, hit, blip. Each takes an optional seed and applies small, bounded, deterministic jitter to a couple of hand-picked fields (frequency, duration, or noise mix) - the same seed always renders the exact same variant, so a preset stays reproducible even though it varies from call to call.

import { AudioClip, BT } from 'blit386';

// Same character every time - useful for a UI sound that should stay consistent.
const menuBlip = await AudioClip.synth(BT.synthPreset.blip());

// A different seed per pickup keeps repeated collects from sounding robotic, while staying
// reproducible - a wall-clock seed like Date.now() would defeat that, since it can never be
// replayed the same way twice.
let pickupCount = 0;
const coin = await AudioClip.synth(BT.synthPreset.pickup(pickupCount++));

BT.soundPlay(menuBlip);
BT.soundPlay(coin, { volume: 0.8 });

Omitting seed (or passing 0) always renders the same baseline variant - useful when you want a preset's default character rather than per-play variation. See Playback (SFX) below for playing the resulting clip through the SFX voice pool, and Design a sound in the Audio Guide for a walkthrough of tuning SynthParams by hand and storing presets as data.

Playback (SFX)

BT.soundPlay plays a loaded AudioClip through a fixed-size pool of SFX voices. Each call returns an opaque SoundRef handle - pass it to BT.soundStop and the per-sound volume, pitch, and pan controls.

import { AudioClip, BT } from 'blit386';

const hit = await AudioClip.load('audio/hit.mp3');

const ref = BT.soundPlay(hit, { volume: 0.8 });

BT.isSoundPlaying(ref); // true

BT.soundStop(ref, { fadeOutMs: 200 }); // fades out over 200 ms

options fields:

A common pattern - vary pitch slightly per play so a repeated sound (footsteps, hits) doesn't sound robotic, using the seedable BT.random:

import { AudioClip, BT } from 'blit386';

const footstep = await AudioClip.load('audio/footstep.mp3');

function playFootstep() {
  const pitch = BT.random.float(0.9, 1.1); // 0.9-1.1x

  BT.soundPlay(footstep, { pitch, volume: 0.6 });
}

Per-sound controls, all silent no-ops on a stale or invalid SoundRef (already stopped, stolen, or completed - never throws):

BT.soundVolumeSet(ref, 0.5, { fadeMs: 100 });
BT.soundVolumeGet(ref); // 0.5

BT.soundPitchSet(ref, 1.2);
BT.soundPitchGet(ref); // 1.2

BT.soundPanSet(ref, -0.3);
BT.soundPanGet(ref); // -0.3

BT.soundPlay also returns an inert SoundRef (no throw) when clip hasn't finished loading yet, or was already released with clip.unload().

Playback (Music)

BT.musicPlay plays a loaded AudioClip through a single looping music player, distinct from the SFX voice pool - there is no SoundRef to manage, and calling it again crossfades from whatever is currently playing into the new track rather than layering the two.

import { AudioClip, BT } from 'blit386';

const theme = await AudioClip.load('audio/theme.mp3');

BT.musicPlay(theme, { volume: 0.8 });

BT.isMusicPlaying; // true

BT.musicStop({ fadeMs: 500 }); // fades out over 500 ms

options fields:

Crossfading

fadeMs sets how long each side of a crossfade takes; overlap sets how the two sides line up in time:

import { AudioClip, BT } from 'blit386';

const calm = await AudioClip.load('audio/calm.mp3');
const battle = await AudioClip.load('audio/battle.mp3');

BT.musicPlay(calm);

// Later, when the fight starts:
BT.musicPlay(battle, { fadeMs: 800, overlap: 1 }); // calm fades out while battle fades in, at the same time
BT.musicPlay(battle, { fadeMs: 800, overlap: 0 }); // battle starts fading in exactly as calm finishes fading out
BT.musicPlay(battle, { fadeMs: 800, overlap: -1 }); // an 800 ms silence gap between the two

Calling BT.musicPlay again before a crossfade finishes immediately cuts the track that was already fading out - only one crossfade is ever in flight, so rapid calls (menu navigation, quick scene changes) never pile up.

Loop points

Loop the whole track (the default), a one-shot, or a specific region such as a bridge that repeats while an intro plays only once:

import { AudioClip, BT } from 'blit386';

const theme = await AudioClip.load('audio/theme.mp3');

BT.musicPlay(theme); // loops the whole track (default)
BT.musicPlay(theme, { loop: false }); // plays once and stops
BT.musicPlay(theme, { loopStart: 8, loopEnd: 32 }); // an 8s intro, then loops the 8-32s region forever

loopStart and loopEnd must be given together, with 0 <= loopStart < loopEnd <= duration - BT.musicPlay throws a beginner-friendly error otherwise, since a mismatched pair is always a programmer mistake rather than something that can happen from normal play.

BT.musicVolumeSet sets the current track's gain, optionally fading to it; BT.musicVolumeGet reads back the last requested target (not a mid-fade instantaneous value):

BT.musicVolumeSet(0.4, { fadeMs: 300 });
BT.musicVolumeGet(); // 0.4

BT.musicPlay silently does nothing (no throw) when clip hasn't finished loading yet, or was already released with clip.unload() - the same as BT.soundPlay.

See Playing music in the Audio Guide for a state-based music switching pattern and an intro-then-loop recipe.

Hardware settings

audioVoices (default 16) caps the number of simultaneous SFX voices - see Playback (SFX) for the allocation and stealing policy. Documented in Hardware settings.

API history

See also

Last updated on October 18, 2026