@pepperhorn/sound-module 0.0.0-stage → 0.1.2

package/dist/types/audio/AudioEngine.d.ts

@@ -0,0 +1,147 @@
+import type { PatchManifest } from '../patches/types';
+import type { ChainEffectId } from './effects';
+import type { EffectId } from './effects';
+import { type LoadProgress } from './loadPatch';
+import { type PatchSourceTag } from './loggedStorage';
+/** What a finished load tells the UI about the patch it just produced. */
+export interface LoadOutcome {
+    source: PatchSourceTag;
+    /** Every sample resolved — the patch is safe to mark as cached for offline. */
+    offlineReady: boolean;
+}
+export type { PatchSourceTag } from './loggedStorage';
+export type { LoadProgress } from './loadPatch';
+export declare function subscribeEngineLog(fn: (line: string) => void): () => void;
+export declare function resetDecodeCounters(): void;
+export declare function snapshotDecodeCounters(): {
+    failures: string[];
+    attempted: number;
+    succeeded: number;
+    failed: number;
+};
+export interface EngineOptions {
+    /** Patch console.warn to surface smplr decode failures. Default true. */
+    consoleShim?: boolean;
+    /**
+     * Default false. When true (embed), the engine log is silent unless the
+     * store's debug mode is on, so a host page's console isn't flooded.
+     */
+    quiet?: boolean;
+}
+export declare class AudioEngine {
+    readonly context: AudioContext;
+    private chain;
+    private current;
+    private currentId;
+    private loadSeq;
+    onLoaded?: (id: string, outcome: LoadOutcome) => void;
+    onLoading?: (id: string | null) => void;
+    onProgress?: (id: string, progress: LoadProgress) => void;
+    onError?: (id: string, err: unknown) => void;
+    onSinkChange?: (sinkId: string) => void;
+    private currentSource;
+    private currentSinkId;
+    private instrumentCache;
+    private previewBus;
+    private previewEntry;
+    private previewSeq;
+    private previewTimers;
+    onPreviewChange?: (id: string | null) => void;
+    private doublerState;
+    private activeDoubles;
+    constructor(options?: EngineOptions);
+    /** Silence everything and suspend the context. Chain and caches are kept so resume() plays again. */
+    suspend(): Promise<void>;
+    resume(): Promise<void>;
+    /** Play a short sine pop through the FX chain to confirm the audio path. */
+    testTone(seconds?: number, gain?: number): void;
+    /**
+     * Audio-path latency in ms. baseLatency is the Web Audio buffer; outputLatency
+     * adds the OS/device path (Bluetooth sinks typically add 150–250ms here).
+     */
+    latencyInfo(): {
+        baseLatencyMs: number;
+        outputLatencyMs: number | null;
+    };
+    loadPatch(patch: PatchManifest): Promise<void>;
+    private evictCacheIfNeeded;
+    /** Drop the in-memory instrument cache (used by purgeAndReload). */
+    private clearInstrumentCache;
+    get loadedPatchSource(): PatchSourceTag | null;
+    private noteOnCount;
+    noteOn(midi: number, velocity?: number): void;
+    /**
+     * Pre-load a patch into the persistent browser cache without making it the
+     * active instrument. Used by the picker's "download for offline" button.
+     * Returns true if the load completed (samples are now cached).
+     */
+    preloadPatch(patch: PatchManifest): Promise<{
+        ok: boolean;
+        fetched: number;
+        attempted: number;
+        failed: string[];
+    }>;
+    private ensurePreviewBus;
+    /** Silence and forget any audition in flight. Safe to call at any time. */
+    stopPreview(): void;
+    /**
+     * Audition a patch from the library without making it the active instrument:
+     * loads its samples (which fills the offline caches, so a later select is
+     * fast and works offline) and plays a C–G run into a dry bus.
+     */
+    previewPatch(patch: PatchManifest): Promise<{
+        ok: boolean;
+        offlineReady: boolean;
+    }>;
+    /** Trigger middle C through the current instrument — independent of touch input. */
+    testCurrentNote(): void;
+    /**
+     * Nuke every cached/stale layer for the given patch and re-fetch from
+     * scratch. Use when Firefox's HTTP cache, the Cache API, OR a stale
+     * smplr instance is suspected of holding bad state.
+     */
+    purgeAndReload(patch: PatchManifest): Promise<void>;
+    /**
+     * Diagnostic: walk a chromatic scale through the current instrument and
+     * log which notes return a non-null voice. Used to figure out why some
+     * notes silently produce no sound.
+     */
+    testScale(): Promise<void>;
+    /**
+     * Diagnostic: fetch a known vendored sample, decode, and play it directly
+     * through the FX chain via a raw AudioBufferSource — bypassing smplr's
+     * Channel/Voice/scheduler entirely. If THIS produces sound but live patch
+     * notes don't, the bug is inside smplr's voice path. If neither produces
+     * sound, the FX chain is broken.
+     */
+    testRawBuffer(): Promise<void>;
+    noteOff(midi: number): void;
+    panic(): void;
+    /** Breath/expression level 0..1 on the shared pre-FX gain stage. */
+    setBreath(level: number, smoothingMs?: number, immediate?: boolean): void;
+    /**
+     * Jump the shared breath gain to full, for notes that are not breath
+     * controlled (touch / computer keyboard). Immediate, so smoothing is moot.
+     */
+    liftBreath(): void;
+    setEffectParam(id: EffectId, paramId: string, value: number): void;
+    /** Rewire the audio chain into this order. Note-level effects are unaffected. */
+    setEffectOrder(order: ChainEffectId[]): void;
+    setEffectEnabled(id: EffectId, on: boolean): void;
+    get loadedPatchId(): string | null;
+    /** True on browsers where AudioContext.setSinkId is implemented. */
+    get sinkIdSupported(): boolean;
+    /** Current routing target: '' = system default. */
+    get sinkId(): string;
+    /**
+     * Route all audio output to the given deviceId (as returned by
+     * navigator.mediaDevices.enumerateDevices() { kind: 'audiooutput' }). Pass
+     * '' to route to the OS default output.
+     *
+     * USB audio interfaces — including class-compliant (UAC1/UAC2) devices —
+     * show up in enumerateDevices() as regular audiooutput entries once the
+     * OS has claimed the device, so this is the correct path for them.
+     */
+    setSinkId(deviceId: string): Promise<void>;
+}
+export declare function getEngine(options?: EngineOptions): AudioEngine;

package/dist/types/audio/customSampler.d.ts

@@ -0,0 +1,43 @@
+import type { SampleEntry } from '../patches/types';
+interface SamplerSource {
+    baseUrl: string;
+    samples: Record<string, SampleEntry>;
+}
+interface LoadProgressLike {
+    loaded: number;
+    total: number;
+}
+/** The subset of the shared storage cascade this sampler needs. */
+interface SampleStorage {
+    fetch(url: string): Promise<Response>;
+}
+export declare class CustomSampler {
+    readonly context: AudioContext;
+    readonly output: GainNode;
+    readonly load: Promise<this>;
+    private regions;
+    private byMidi;
+    private active;
+    private destination?;
+    private onLoadProgress?;
+    private storage?;
+    private totalSamples;
+    private loadedSamples;
+    constructor(context: AudioContext, options: {
+        source: SamplerSource;
+        destination?: AudioNode;
+        onLoadProgress?: (progress: LoadProgressLike) => void;
+        storage?: SampleStorage;
+    });
+    private loadSource;
+    private loadEntry;
+    private fetchBuffer;
+    start(event: {
+        note: number | string;
+        velocity?: number;
+    }): () => void;
+    stop(target?: number | string): void;
+    disconnect(): void;
+    private findNearestMidi;
+}
+export {};

package/dist/types/audio/effects.d.ts

@@ -0,0 +1,111 @@
+import type { PatchColor } from '../patches/types';
+export type EffectId = 'distortion' | 'doubler1' | 'doubler2' | 'chorus' | 'delay' | 'reverb';
+export interface EffectParamDef {
+    id: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+    default: number;
+    unit?: string;
+    labels?: string[];
+}
+export interface EffectDef {
+    id: EffectId;
+    name: string;
+    color: PatchColor;
+    params: EffectParamDef[];
+}
+/**
+ * The effects that actually exist as audio nodes, in their default order.
+ *
+ * The doublers are deliberately absent: they are note-level triggers fired in
+ * AudioEngine.noteOn, not nodes in the graph, so "where they sit in the chain"
+ * has no meaning and they cannot be reordered.
+ */
+export declare const CHAIN_EFFECT_IDS: readonly ["distortion", "chorus", "delay", "reverb"];
+export type ChainEffectId = (typeof CHAIN_EFFECT_IDS)[number];
+export declare function isChainEffectId(id: string): id is ChainEffectId;
+/**
+ * Coerce anything — persisted state, a saved preset from an older build — into
+ * a usable chain order: every effect exactly once. Unknown ids are dropped and
+ * missing ones appended in default order, so a stored order can never leave an
+ * effect silently unwired.
+ */
+export declare function normalizeFxOrder(input: unknown): ChainEffectId[];
+/** The order with `id` moved by `delta` places, clamped at the ends. */
+export declare function moveInOrder(order: ChainEffectId[], id: ChainEffectId, delta: number): ChainEffectId[];
+export declare const DOUBLER_SNAPS: readonly [{
+    readonly st: -12;
+    readonly label: "-OCT";
+}, {
+    readonly st: -11;
+    readonly label: "-M7";
+}, {
+    readonly st: -10;
+    readonly label: "-m7";
+}, {
+    readonly st: -7;
+    readonly label: "-5";
+}, {
+    readonly st: -5;
+    readonly label: "-4";
+}, {
+    readonly st: -4;
+    readonly label: "-M3";
+}, {
+    readonly st: -3;
+    readonly label: "-m3";
+}, {
+    readonly st: 0;
+    readonly label: "UNI";
+}, {
+    readonly st: 3;
+    readonly label: "m3";
+}, {
+    readonly st: 4;
+    readonly label: "M3";
+}, {
+    readonly st: 5;
+    readonly label: "4";
+}, {
+    readonly st: 7;
+    readonly label: "5";
+}, {
+    readonly st: 10;
+    readonly label: "m7";
+}, {
+    readonly st: 11;
+    readonly label: "M7";
+}, {
+    readonly st: 12;
+    readonly label: "+OCT";
+}];
+export declare const EFFECT_DEFS: EffectDef[];
+export declare function defaultParams(): Record<EffectId, Record<string, number>>;
+export interface EffectChain {
+    /**
+     * Where instruments connect. This node's identity never changes, including
+     * across a reorder — instruments are wired to it at construction and kept in
+     * the engine's LRU cache, so a chain whose input was the first effect would
+     * silence every cached instrument the moment the order changed.
+     */
+    inputNode: AudioNode;
+    master: GainNode;
+    setEnabled: (id: EffectId, on: boolean) => void;
+    setParam: (id: EffectId, paramId: string, value: number) => void;
+    /**
+     * Reorder the audio-graph effects in series. Non-chain ids (the note-level
+     * doublers) are ignored and missing ones appended — see normalizeFxOrder.
+     */
+    setOrder: (order: readonly EffectId[]) => void;
+    getOrder: () => ChainEffectId[];
+    /**
+     * Pre-FX breath/expression gain (0..1), applied on inputNode itself: ahead
+     * of the FX so reverb/delay tails ring out when breath stops, and untouched
+     * by setOrder (which only rewires inputNode's outputs).
+     */
+    setBreath: (level: number, smoothingMs: number, immediate?: boolean) => void;
+    dispose: () => void;
+}
+export declare function buildEffectChain(context: AudioContext): EffectChain;

package/dist/types/audio/fetchSlots.d.ts

@@ -0,0 +1,4 @@
+/** How many fetches hold a slot right now. Exposed for tests and diagnostics. */
+export declare function activeFetchCount(): number;
+export declare function maxConcurrentFetches(): number;
+export declare function withFetchSlot<T>(fn: () => Promise<T>): Promise<T>;

package/dist/types/audio/loadPatch.d.ts

@@ -0,0 +1,25 @@
+import type { PatchManifest } from '../patches/types';
+export interface LoadProgress {
+    loaded: number;
+    total: number;
+}
+export interface LoadedInstrument {
+    start(event: {
+        note: number | string;
+        velocity?: number;
+    }): () => void;
+    stop(target?: number | string): void;
+    disconnect(): void;
+    load: Promise<unknown>;
+}
+interface InstantiateOptions {
+    context: AudioContext;
+    destination: AudioNode;
+    patch: PatchManifest;
+    onLoadProgress?: (progress: LoadProgress) => void;
+    storage?: {
+        fetch: (url: string) => Promise<Response>;
+    };
+}
+export declare function instantiatePatch(opts: InstantiateOptions): LoadedInstrument;
+export {};

package/dist/types/audio/loggedStorage.d.ts

@@ -0,0 +1,46 @@
+export type SourceTier = 'local' | 'localAlt' | 'cache' | 'cdn';
+export interface LoggedStorageStats {
+    attempted: number;
+    succeeded: number;
+    failed: string[];
+    bySource: Record<SourceTier, number>;
+}
+export interface PatchSourceTag {
+    tier: 'local' | 'cache' | 'cdn' | 'mixed' | 'unknown';
+    local: number;
+    cache: number;
+    cdn: number;
+    total: number;
+}
+export declare function computeSourceTag(stats: LoggedStorageStats): PatchSourceTag;
+/**
+ * How much of a patch actually arrived.
+ *
+ * This matters because smplr's loader resolves whatever happens: a sample that
+ * 404s or fails to decode is dropped with a `console.warn` and the load
+ * promise still fulfils (see `loadAudioBuffer` in smplr, and its own comment
+ * "Failed samples are silently omitted"). So "the load resolved" says nothing
+ * about whether the instrument can make a sound — only these counts do.
+ */
+export type LoadCompleteness = 'complete' | 'degraded' | 'empty';
+export declare function classifyLoad(stats: LoggedStorageStats): LoadCompleteness;
+/**
+ * True when a completed load left the patch genuinely playable offline: every
+ * sample request was satisfied and at least one actually resolved. A load with
+ * missing samples still makes noise, but marking it "downloaded" would lie to
+ * the picker's offline greyout, so it does not count.
+ */
+export declare function isOfflineReady(stats: LoggedStorageStats): boolean;
+export type SampleSourceMode = 'app' | 'cdn';
+/** Choose between the app's local-first cascade and direct CDN fetching. */
+export declare function configureSampleSource(config: {
+    mode: SampleSourceMode;
+}): void;
+export declare function getSampleSourceMode(): SampleSourceMode;
+export interface LoggedStorage {
+    fetch: (url: string) => Promise<Response>;
+    reset(): void;
+    snapshot(): LoggedStorageStats;
+}
+export declare function clearCdnCache(): Promise<void>;
+export declare function createLoggedStorage(onEvent?: (line: string) => void): LoggedStorage;

package/dist/types/audio/preview.d.ts

@@ -0,0 +1,16 @@
+import type { PatchManifest } from '../patches/types';
+export interface PreviewEvent {
+    notes: number[];
+    /** Milliseconds after the audition starts. */
+    at: number;
+    /** Milliseconds to hold before releasing. */
+    hold: number;
+}
+/** A C–G run followed by a C major triad. */
+export declare function previewSequence(rootMidi: number): PreviewEvent[];
+export declare function previewDurationMs(events: PreviewEvent[]): number;
+/**
+ * C in the patch's own preferred octave, clamped to a range every sample set
+ * can reach — a bass patch auditioned at C4 would be out of its sampled range.
+ */
+export declare function previewRootMidi(patch: Pick<PatchManifest, 'defaultOctave'>): number;

package/dist/types/components/Knob.d.ts

@@ -0,0 +1,22 @@
+interface KnobProps {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    unit?: string;
+    color?: string;
+    size?: number;
+    /** Discrete position names (e.g. doubler intervals) shown instead of a number. */
+    labels?: string[];
+    defaultValue?: number;
+    disabled?: boolean;
+    onChange: (value: number) => void;
+}
+/**
+ * A skeuomorphic pot: coloured value arc, skirt collar and domed cap. Drag
+ * up/down or scroll to turn (shift = fine), arrow keys step it, double-click
+ * returns it to its default.
+ */
+export declare function Knob({ label, value, min, max, step, unit, color, size, labels, defaultValue, disabled, onChange, }: KnobProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/LiveTouchKeyboard.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The on-screen keyboard wired to the live active-note set. Kept as its own
+ * component so only the keyboard re-renders per note.
+ */
+export declare function LiveTouchKeyboard(props: {
+    noteOn: (midi: number, vel: number) => void;
+    noteOff: (midi: number) => void;
+    fill?: boolean;
+    keyLabels?: boolean;
+    octaves?: number;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/LoadErrorToast.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Surfaced when a patch load fails. Before this existed a failed load left the
+ * LCD showing a patch that was never actually loaded, with no clue why the keys
+ * were silent — the single most confusing failure mode of the loader.
+ */
+export declare function LoadErrorToast({ onRetry, inline, }: {
+    onRetry: (id: string) => void;
+    /**
+     * Sit in the layout instead of floating. Keyboard mode fills the viewport and
+     * ends in the touch controls, so a floating toast would cover panic and the
+     * octave buttons no matter which edge it was pinned to.
+     */
+    inline?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/LoadingOverlay.d.ts

@@ -0,0 +1,3 @@
+export declare function LoadingOverlay({ contained }: {
+    contained?: boolean;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/components/MidiPanel.d.ts

@@ -0,0 +1,17 @@
+export interface LatencyInfo {
+    baseLatencyMs: number;
+    outputLatencyMs: number | null;
+}
+interface MidiPanelProps {
+    /** Reads the AudioContext latency (engine.latencyInfo). Optional for tests. */
+    getLatency?: () => LatencyInfo;
+    /** Render absolutely inside the nearest positioned ancestor (embed). */
+    contained?: boolean;
+}
+/**
+ * MIDI & breath controls sheet, opened from the MIDI status pill. Shows the
+ * permission state first; once granted, devices, presets, the live breath
+ * meter and the breath shaping controls.
+ */
+export declare function MidiPanel({ getLatency, contained }: MidiPanelProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/components/MidiStatus.d.ts

@@ -0,0 +1,4 @@
+/** MIDI status pill; tapping it opens the MIDI / breath controls sheet. */
+export declare function MidiStatus({ className }?: {
+    className?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/PatchCard.d.ts

@@ -0,0 +1,20 @@
+import type { PatchManifest } from '../patches/types';
+interface PatchCardProps {
+    patch: PatchManifest;
+    active: boolean;
+    favourited: boolean;
+    downloaded: boolean;
+    downloading: boolean;
+    /** True when we're offline AND this patch isn't cached locally. */
+    unavailableOffline?: boolean;
+    /** This card's audition is loading or playing. */
+    previewing?: boolean;
+    onSelect: (id: string) => void;
+    onPreview: (id: string) => void;
+    onToggleFavourite: (id: string) => void;
+    onDownload?: (id: string) => void;
+    /** Render the offline download button. Off in the embed. */
+    showDownload?: boolean;
+}
+export declare function PatchCard({ patch, active, favourited, downloaded, downloading, unavailableOffline, previewing, onSelect, onPreview, onToggleFavourite, onDownload, showDownload, }: PatchCardProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/PatchPicker.d.ts

@@ -0,0 +1,13 @@
+interface PatchPickerProps {
+    onSelect: (id: string) => void;
+    /** Audition a patch without switching to it. */
+    onPreview: (id: string) => void;
+    /** Fetch a patch's samples into the offline caches. */
+    onDownload?: (id: string) => void;
+    /** Render absolutely inside the nearest positioned ancestor (embed). */
+    contained?: boolean;
+    /** Show download buttons and the offline pill. Off in the embed. */
+    offlineFeatures?: boolean;
+}
+export declare function PatchPicker({ onSelect, onPreview, onDownload, contained, offlineFeatures, }: PatchPickerProps): import("react/jsx-runtime").JSX.Element | null;
+export {};

package/dist/types/components/PatchStrip.d.ts

@@ -0,0 +1,17 @@
+import type { PatchManifest } from '../patches/types';
+import type { PatchSourceTag } from '../audio/AudioEngine';
+interface PatchStripProps {
+    patch: PatchManifest | undefined;
+    index: number;
+    total: number;
+    loading: boolean;
+    source: PatchSourceTag | null;
+    onStep: (delta: number) => void;
+    onBrowse: () => void;
+}
+/**
+ * The library readout for keyboard mode: everything you need to know about the
+ * loaded patch in one thin bar, so the rest of the screen belongs to the keys.
+ */
+export declare function PatchStrip({ patch, index, total, loading, source, onStep, onBrowse, }: PatchStripProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/PowerOnOverlay.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The "tap to power on" scrim browsers need before audio can start. `contained`
+ * pins it to the nearest positioned ancestor instead of the viewport (embed).
+ */
+export declare function PowerOnOverlay({ onPowerOn, contained, }: {
+    onPowerOn: () => void;
+    contained?: boolean;
+}): import("react/jsx-runtime").JSX.Element;

package/dist/types/components/TouchKeyboard.d.ts

@@ -0,0 +1,17 @@
+interface TouchKeyboardProps {
+    noteOn: (midi: number, velocity: number) => void;
+    noteOff: (midi: number) => void;
+    /** Notes currently sounding from ANY source (computer keyboard, MIDI, touch) —
+     *  used to light the on-screen keys. Touch also feeds this via App.noteOn. */
+    activeNotes?: ReadonlySet<number>;
+    octaves?: number;
+    /**
+     * Stretch to fill the parent instead of using the fixed rack height. Used by
+     * keyboard mode, where the keys take the lion's share of the viewport.
+     */
+    fill?: boolean;
+    /** Show the computer-keyboard letter that plays each key (follows the octave). */
+    keyLabels?: boolean;
+}
+export declare function TouchKeyboard({ noteOn, noteOff, activeNotes, octaves, fill, keyLabels, }: TouchKeyboardProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/types/components/overlayEscape.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether an overlay's Escape handler (bound on window) should act on `e`.
+ * Full-screen app overlays own the whole page, so any Escape counts. A
+ * contained (embed) overlay only answers Escape pressed inside the element it
+ * is drawn in — the module root — so Escape elsewhere on the host page is left
+ * to the host.
+ */
+export declare function escapeIsForOverlay(e: KeyboardEvent, overlay: HTMLElement | null, contained: boolean): boolean;

package/dist/types/embed/SoundModule.d.ts

@@ -0,0 +1,16 @@
+export interface SoundModuleProps {
+    /** Base URL that serves /patches/**. becreative passes "". Omitted → CST patches hidden. */
+    assetBaseUrl?: string;
+    /** Applied to the component root only. Default 'dark'. */
+    theme?: 'dark' | 'light';
+    /** On-screen piano octaves. Default 2 (25 keys). */
+    octaves?: number;
+    className?: string;
+}
+/**
+ * The embeddable sound module: patch strip, status row and a labelled
+ * on-screen piano, with every overlay drawn inside its own root. The computer
+ * keyboard plays only while focus is inside the module; MIDI and breath play
+ * regardless.
+ */
+export declare function SoundModule({ assetBaseUrl, theme, octaves, className }: SoundModuleProps): import("react/jsx-runtime").JSX.Element;

package/dist/types/embed/catalog.d.ts

@@ -0,0 +1,6 @@
+import type { PatchManifest } from '../patches/types';
+export declare function joinAssetUrl(base: string, path: string): string;
+export declare function embedCatalog(catalog: PatchManifest[], assetBaseUrl: string | undefined): PatchManifest[];
+export declare function configureEmbed(opts: {
+    assetBaseUrl?: string;
+}): void;

package/dist/types/embed/index.d.ts

@@ -0,0 +1,2 @@
+export { SoundModule } from './SoundModule';
+export type { SoundModuleProps } from './SoundModule';