Recipes
The data format every sound is built from, exported from @bloxwap/sfx/recipes.
Every sound is plain data. You can inspect it from the @bloxwap/sfx/recipes entry point, for example to draw a visualization or document your sound design:
import { recipes, sourceEnd, echoTail, type Recipe } from '@bloxwap/sfx/recipes';
recipes.payout.layers.length; // 16Recipe
interface Recipe {
level: number; // output level for the summed layers
layers: readonly Layer[];
echo?: Echo; // optional darkening feedback delay
}
interface Echo {
delay: number; // seconds between repeats
feedback: number; // 0–1, level of each repeat relative to the previous one
wet: number; // level of the echo relative to the dry sound
lowpass: number; // Hz, applied on every repeat
}Layers
Each layer starts at seconds after the trigger. Its envelope rises exponentially to peak over attack, stays there for hold seconds (zero by default), then falls exponentially over decay. Set pan to place the layer in the stereo field. A layer is centered by default.
interface ToneLayer {
wave: 'sine' | 'triangle' | 'sawtooth' | 'square';
freq: number; // Hz
to?: number; // Hz: glide exponentially to this pitch
glide?: number; // glide duration in seconds (default attack + hold + decay)
detune?: number; // cents
at: number; attack: number; hold?: number; decay: number; peak: number; pan?: number;
}
interface NoiseLayer {
noise: 'lowpass' | 'bandpass' | 'highpass'; // white noise through this filter
freq: number; // filter frequency, Hz
q?: number; // filter Q (default 1)
at: number; attack: number; hold?: number; decay: number; peak: number; pan?: number;
}Example: chime
{
level: 1.75,
echo: { delay: 0.12, feedback: 0.25, wet: 0.18, lowpass: 4000 },
layers: [
{ wave: 'sine', freq: 1046.5, at: 0, attack: 0.006, decay: 0.22, peak: 0.09 },
{ wave: 'sine', freq: 1568, at: 0.09, attack: 0.006, decay: 0.26, peak: 0.08 },
],
}Timing helpers
sourceEnd(recipe)returns the seconds until the last layer's envelope ends.echoTail(recipe)returns the seconds of echo after that, until the repeats fall below -60 dB.duration(name)from the main entry returns the sum of the two.
Define your own sounds
import { define, play, preload, type Recipe } from '@bloxwap/sfx';
const coin = {
level: 0.6,
layers: [{ wave: 'sine', freq: 880, at: 0, attack: 0.006, decay: 0.15, peak: 0.2 }],
} satisfies Recipe;
define('coin', coin);
await preload(['coin']);
play('coin');Use data-sound-press="coin" after defining it. SoundName accepts custom strings;
isSound() checks whether a name has actually been registered. sounds and recipes
remain the built-in catalog; getRecipe(name) from the recipes entry resolves either kind.
preload() without arguments warms the built-ins; pass custom names to warm your own.
define() copies and freezes the data. Invalid timing, frequencies, filters, echo parameters,
reserved names and attempts to replace built-ins throw RangeError. Defining a custom name
again replaces its recipe and clears its old render cache. Sounds already playing finish.
Definitions survive dispose(); that function releases audio resources.
Build a sound
import { define, play } from '@bloxwap/sfx';
define('coin', {
"level": 0.6,
"layers": [
{
"wave": "sine",
"freq": 440,
"at": 0,
"attack": 0.006,
"decay": 0.15,
"peak": 0.2
}
]
});
play('coin');Custom recipes are limited to 64 layers and 10 seconds including echo. Up to 128 custom names may be registered; replacing a name does not consume another slot. Built-in recipes are deeply frozen. All registration paths invalidate cached renders. Offline renders are limited to 32 MiB each, 64 MiB concurrently, and 64 MiB retained in the playback cache. Requests exceeding those render budgets return null/false rather than allocating an oversized buffer.