Sound Packs

sensory-ui includes 9 distinct sound packs, each with a unique character. Swap between them by changing the theme value in sensory.config.js. All built-in packs generate audio programmatically via the Web Audio API. No audio files, no base64 blobs, no network requests.

Architecture: Tunes + Instruments + EffectsCopy Anchor Link

sensory-ui uses an instrument-based architecture that separates concerns:

Tunes (sounds/core/tunes.ts)Copy Anchor Link

Define the musical content:

• Frequencies, durations, pitch contours
• Note sequences for arpeggios
• Filter settings for noise-based sounds
• Volume levels and decay times

Instruments (sounds/core/instruments.ts)Copy Anchor Link

Define the synthesis technique:

• Waveform type (sine, square, sawtooth, triangle)
• Noise characteristics (white, pink, brown)
• Filter settings and resonance
• Envelope shapes (attack/decay curves)
• Harmonic content and detuning
• Effects chain (reverb, delay, chorus, distortion)

Effects (sounds/core/effects.ts)Copy Anchor Link

Spatial/timbral processing:

• Reverb via generated impulse responses (no external files)
• Feedback delay with filter
• Chorus via modulated delay
• Waveshaper distortion
• Chains of effects daisy-chained automatically

Factory (sounds/core/factory.ts)Copy Anchor Link

Combines tunes with instruments:

• Takes a tune definition and an instrument config
• If the instrument has effects, routes output through the chain
• Produces a SoundSynthesizer function

This separation allows the same tunes to be played by different instruments, creating distinct sound pack characters with minimal code duplication.

Effects SystemCopy Anchor Link

Each InstrumentConfig can include an optional effects array. When present, the factory routes every sound through the effects chain before reaching ctx.destination.

interface InstrumentConfig {
  filterFreq: number;
  q: number;
  oscType: OscillatorWaveform;
  decayMult: number;
  gainMult: number;
  pitchMult: number;
  effects?: EffectDefinition[];  // optional effects chain
}

Available EffectsCopy Anchor Link

All effects support a mix parameter (0–1) for wet/dry balance.

Pack Effects MappingCopy Anchor Link

Built-in Sound Packs (9 total)Copy Anchor Link

Tune TypesCopy Anchor Link

Instrument PropertiesCopy Anchor Link

interface InstrumentConfig {
  filterFreq: number; // Filter cutoff frequency (1500–6000 Hz)
  q: number;          // Filter resonance (1–12)
  oscType: OscillatorType; // "sine" | "square" | "sawtooth" | "triangle"
  decayMult: number;  // Decay time multiplier (0.5–1.5)
  gainMult: number;   // Volume multiplier (0.4–1.0)
  pitchMult: number;  // Pitch multiplier (0.7–1.8)
  effects?: EffectDefinition[]; // Optional effects chain
}

Example Instrument SettingsCopy Anchor Link

Switching PacksCopy Anchor Link

Via Config FileCopy Anchor Link

// sensory.config.js
module.exports = {
  theme: "organic", // soft, aero, arcade, organic, glass, industrial, minimal, retro, crisp
};

Via Provider PropsCopy Anchor Link

<SensoryUIProvider config={{ theme: "organic" }}>
  {children}
</SensoryUIProvider>

Creating a Custom PackCopy Anchor Link

Option 1: Define a New InstrumentCopy Anchor Link

// sounds/core/instruments.ts
const MY_CUSTOM_INSTRUMENT: InstrumentConfig = {
  filterFreq: 4000,
  q: 5,
  oscType: "triangle",
  decayMult: 1.0,
  gainMult: 0.85,
  pitchMult: 1.1,
  effects: [
    { type: "reverb", options: { duration: 1.0, decay: 2.0, mix: 0.2 } },
  ],
};

Then generate the pack:

import { generateSoundPack } from "./core/factory";
import { INSTRUMENTS } from "./core/instruments";

// Add to INSTRUMENTS map, then:
export const myPack = generateSoundPack(MY_CUSTOM_INSTRUMENT);
// myPack covers all 17 roles

Option 2: Modify Existing PackCopy Anchor Link

import { INSTRUMENTS } from "./core/instruments";
import { generateSoundPack } from "./core/factory";

const myInstrument = {
  ...INSTRUMENTS.glass,
  gainMult: 0.6,    // quieter
  pitchMult: 2.0,   // higher pitched
  effects: [
    { type: "reverb", options: { duration: 2.0, mix: 0.4 } },
  ],
};

export const myPack = generateSoundPack(myInstrument);

Reference LinksCopy Anchor Link

• Web Audio API (MDN)
• OscillatorNode (MDN)
• BiquadFilterNode (MDN)
• Generating Sounds with AI
• @web-kits/audio