@pepperhorn/sound-module 0.0.0-stage → 0.1.0

package/dist/types/input/breath.d.ts

@@ -0,0 +1,79 @@
+export type BreathCurve = 'linear' | 'exponential' | 'logarithmic';
+export interface BreathConfig {
+    /** CC number carrying breath. Odisei + EWI default to CC2. */
+    cc: number;
+    /** Below this (0..127) the gate is shut. */
+    gateThreshold: number;
+    /** Gain at the gate threshold. */
+    floor: number;
+    /** Gain at full breath. */
+    ceiling: number;
+    curve: BreathCurve;
+    /** setTargetAtTime time constant for continuous breath changes. */
+    smoothingMs: number;
+    /** 'fixed' lets breath own loudness; the Odisei velocity is breath-derived. */
+    velocityMode: 'fixed' | 'passthrough';
+    fixedVelocity: number;
+}
+export declare const WIND_BREATH_DEFAULTS: BreathConfig;
+/** Map a raw breath CC (0..127) to a 0..1 gain. Returns 0 when gated. */
+export declare function breathToGain(cc: number, config: BreathConfig): number;
+export interface BreathOutputs {
+    noteOn: (midi: number, velocity: number) => void;
+    noteOff: (midi: number) => void;
+    /** immediate = jump straight to level (gate opening, reset). */
+    setBreath: (level: number, smoothingMs: number, immediate: boolean) => void;
+}
+/**
+ * Note gate + breath router for one MIDI input stream.
+ *
+ * Inactive until the first breath CC arrives, so a plain keyboard never gets
+ * gated. Once active, note-ons only sound while breath is above the gate
+ * threshold; held keys resume when breath comes back.
+ */
+export declare class BreathController {
+    private active;
+    private open;
+    private level;
+    /** Keys the device currently holds down. */
+    private held;
+    /** Notes we've actually started on the engine. */
+    private sounding;
+    private lastWriteAt;
+    private pendingWrite;
+    /** Last raw breath value (0..127), so config changes can re-evaluate it. */
+    private lastRaw;
+    /** A breath CC has been seen at least once (even while disabled). */
+    private hasRaw;
+    private enabled;
+    private config;
+    private readonly outputs;
+    private readonly now;
+    constructor(outputs: BreathOutputs, config?: BreathConfig, now?: () => number, enabled?: boolean);
+    get isActive(): boolean;
+    get isEnabled(): boolean;
+    /**
+     * Apply a new breath config at runtime without dropping held notes.
+     *
+     * - Disabling while active drops held-but-gated keys without starting them
+     *   (no idle-note drone), keeps notes already sounding, returns the shared
+     *   gain to 1, and makes this input pure pass-through from then on.
+     * - Any other change re-evaluates the last breath value under the new config,
+     *   so a gate/curve/floor tweak is heard immediately. A CC change just
+     *   re-targets which controller is listened to; the gate keeps its state until
+     *   the new CC speaks.
+     */
+    setConfig(config: BreathConfig, enabled?: boolean): void;
+    noteOn(midi: number, velocity: number): void;
+    noteOff(midi: number): void;
+    /** Feed a Control Change. Returns true if it was the breath CC. */
+    controlChange(cc: number, value: number): boolean;
+    breath(value: number): void;
+    /** Panic: release and forget every note, keep the gate state. */
+    releaseAll(): void;
+    /** Breath source gone (device unplugged): release everything, un-gate. */
+    reset(): void;
+    private start;
+    private writeNow;
+    private writeThrottled;
+}

package/dist/types/input/midiAccess.d.ts

@@ -0,0 +1,14 @@
+export declare function isMidiSupported(): boolean;
+export declare function getMidiAccess(): MIDIAccess | null;
+/** Called with the MIDIAccess once granted (immediately if already held). */
+export declare function onMidiAccess(fn: (a: MIDIAccess) => void): () => void;
+/** Classify a requestMIDIAccess rejection. */
+export declare function classifyMidiError(err: unknown): 'denied' | 'error';
+/** Ask for MIDI access (shows Chrome's prompt the first time). Deduped. */
+export declare function requestMidi(): Promise<void>;
+/**
+ * On load, reconnect silently only when it cannot raise a prompt: the browser
+ * already reports `granted`, or the user enabled MIDI on a previous visit.
+ * A `denied` permission is reflected straight away so the UI can explain it.
+ */
+export declare function autoRequestMidi(): Promise<void>;

package/dist/types/input/midiMonitor.d.ts

@@ -0,0 +1,10 @@
+export declare const breathMonitor: {
+    /** Last value on the configured breath CC, or -1 if none has arrived. */
+    raw: number;
+    /** Last CC of any number, so "breath on the wrong CC" is visible. */
+    lastCc: number;
+    lastCcValue: number;
+    /** performance.now() of the last breath-CC message. */
+    at: number;
+};
+export declare function resetBreathMonitor(): void;

package/dist/types/input/midiProfile.d.ts

@@ -0,0 +1,77 @@
+import { type BreathConfig } from './breath';
+export declare const MIDI_PROFILE_KEY = "module:midi-map:v1";
+/** Set once MIDI access has been granted, so the next visit can reconnect silently. */
+export declare const MIDI_ENABLED_KEY = "module:midi-enabled:v1";
+export type MidiPresetId = 'travel-sax-2' | 'travel-clarinet' | 'ewi-usb' | 'keyboard';
+export interface MidiProfile {
+    /** The preset last applied. Tweaks keep it; the UI shows "modified". */
+    preset: MidiPresetId;
+    breath: BreathConfig;
+    /** Breath gating on/off. Off = every input is plain pass-through. */
+    enabled: boolean;
+}
+export interface MidiPreset {
+    id: MidiPresetId;
+    label: string;
+    short: string;
+    breath: BreathConfig;
+    enabled: boolean;
+}
+export declare const MIDI_PRESETS: Record<MidiPresetId, MidiPreset>;
+export declare const MIDI_PRESET_ORDER: MidiPresetId[];
+/**
+ * Travel Sax 2 by default. Breath only arms once a breath CC actually arrives,
+ * so a plain keyboard still plays straight through under this preset.
+ */
+export declare const DEFAULT_MIDI_PRESET: MidiPresetId;
+/** The Breath Channel choices the Odisei apps offer. Learn can set any CC. */
+export declare const BREATH_CC_CHOICES: readonly [2, 7, 11];
+export declare const BREATH_LIMITS: {
+    readonly gateThreshold: {
+        readonly min: 0;
+        readonly max: 127;
+    };
+    readonly floor: {
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly ceiling: {
+        readonly min: 0;
+        readonly max: 1;
+    };
+    readonly smoothingMs: {
+        readonly min: 1;
+        readonly max: 60;
+    };
+    readonly fixedVelocity: {
+        readonly min: 1;
+        readonly max: 127;
+    };
+};
+export declare function presetProfile(id: MidiPresetId): MidiProfile;
+/**
+ * Coerce anything (stored JSON, a hand-edited payload, a future version) into a
+ * valid profile. Numbers are clamped; an unknown curve / CC / velocity mode
+ * falls back to the profile's preset value. Never throws.
+ */
+export declare function normalizeMidiProfile(raw: unknown): MidiProfile;
+/** True when the profile still equals its preset (nothing tweaked). */
+export declare function profileMatchesPreset(p: MidiProfile): boolean;
+export declare function loadMidiProfile(): MidiProfile;
+export declare function saveMidiProfile(p: MidiProfile): void;
+export declare function loadMidiEnabledFlag(): boolean;
+export declare function saveMidiEnabledFlag(v: boolean): void;
+export interface LearnTrack {
+    min: number;
+    max: number;
+    count: number;
+}
+export type LearnState = Map<string, LearnTrack>;
+export declare const LEARN_MIN_SPAN = 40;
+export declare const LEARN_MIN_MESSAGES = 6;
+/**
+ * Feed one CC message into the learn tracker. Returns the CC number once some
+ * (input, cc) pair has swept at least `minSpan` values over at least
+ * `minMessages` messages, else null. Mutates `state` only.
+ */
+export declare function observeLearn(state: LearnState, inputId: string, cc: number, value: number, minSpan?: number, minMessages?: number): number | null;

package/dist/types/input/useComputerKeyboard.d.ts

@@ -0,0 +1,19 @@
+import { type RefObject } from 'react';
+export declare const KEY_TO_SEMITONE: Readonly<Record<string, number>>;
+/** The computer key that plays semitone `n` (0..17), upper-cased; null outside that range. */
+export declare function keyLabelForSemitone(n: number): string | null;
+interface KeyboardCallbacks {
+    noteOn: (midi: number, velocity: number) => void;
+    noteOff: (midi: number) => void;
+    panic: () => void;
+}
+export interface ComputerKeyboardOptions {
+    /** Focus-scoped mode: listen on this element only; keys play only while focus is inside it. */
+    target?: RefObject<HTMLElement | null>;
+}
+/** A modal dialog (MIDI sheet, save dialog...) owns the keyboard while open. */
+export declare function isModalOpen(scope?: ParentNode | null): boolean;
+export declare function useComputerKeyboard(callbacks: KeyboardCallbacks, options?: ComputerKeyboardOptions): {
+    armed: boolean;
+};
+export {};

package/dist/types/input/useWebMidi.d.ts

@@ -0,0 +1,10 @@
+import { type BreathOutputs } from './breath';
+type WebMidiCallbacks = BreathOutputs;
+/**
+ * Wires granted MIDI access to the note/breath path. Access itself is requested
+ * on demand (see midiAccess.ts); on mount we only reconnect silently when the
+ * browser already granted it. Returns a stable panic function that releases
+ * every MIDI-held note.
+ */
+export declare function useWebMidi(callbacks: WebMidiCallbacks): () => void;
+export {};

package/dist/types/patches/builtin.d.ts

@@ -0,0 +1,2 @@
+import type { PatchManifest } from './types';
+export declare function getBuiltinPatches(): PatchManifest[];

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

@@ -0,0 +1,3 @@
+import type { PatchManifest } from './types';
+export declare function getCatalog(): PatchManifest[];
+export declare function findPatch(id: string): PatchManifest | undefined;

package/dist/types/patches/types.d.ts

@@ -0,0 +1,51 @@
+export type VelocityTag = 'pp' | 'p' | 'mp' | 'mf' | 'f' | 'ff' | 'default';
+export type SampleEntry = string | string[] | Partial<Record<VelocityTag, string | string[]>>;
+export type SoundfontKit = 'MusyngKite' | 'FluidR3_GM';
+export type PatchSource = {
+    kind: 'soundfont';
+    instrument: string;
+    kit?: SoundfontKit;
+} | {
+    kind: 'piano';
+} | {
+    kind: 'electric-piano';
+    instrument: 'CP80' | 'PianetT' | 'WurlitzerEP200' | 'TX81Z';
+} | {
+    kind: 'mallet';
+    instrument: string;
+} | {
+    kind: 'mellotron';
+    instrument: string;
+} | {
+    kind: 'smolken';
+    instrument: 'Arco' | 'Pizzicato' | 'Switched';
+} | {
+    kind: 'sampler';
+    baseUrl: string;
+    samples: Record<string, SampleEntry>;
+};
+export type Bank = 'GM' | 'PNO' | 'EP' | 'MAL' | 'MEL' | 'BAS' | 'CST' | 'USR';
+export interface PatchManifest {
+    id: string;
+    name: string;
+    category: string;
+    bank: Bank;
+    color: PatchColor;
+    description?: string;
+    defaultOctave?: number;
+    source: PatchSource;
+}
+export type PatchColor = 'coral' | 'amber' | 'lime' | 'sky' | 'lavender' | 'peach' | 'mint' | 'rose';
+export declare const BANK_LABELS: Record<Bank, string>;
+export declare const BANK_ORDER: Bank[];
+export interface UserPatch {
+    id: string;
+    name: string;
+    basePatchId: string;
+    color: PatchColor;
+    fxEnabled: Record<string, boolean>;
+    fxParams: Record<string, Record<string, number>>;
+    /** Chain order at save time. Absent on presets saved before ordering existed. */
+    fxOrder?: string[];
+    createdAt: number;
+}

package/dist/types/state/activeNotes.d.ts

@@ -0,0 +1,4 @@
+export declare function addActiveNote(midi: number): void;
+export declare function removeActiveNote(midi: number): void;
+export declare function clearActiveNotes(): void;
+export declare function useActiveNotes(): ReadonlySet<number>;

package/dist/types/state/useFullCatalog.d.ts

@@ -0,0 +1,19 @@
+import type { PatchManifest, UserPatch } from '../patches/types';
+/**
+ * Present a user-saved preset as a normal patch manifest so the LCD, the
+ * picker, prev/next and the loading overlay can all treat it like any other
+ * entry. It reuses the base patch's audio source, which is what lets the
+ * engine's instrument cache serve both from one load.
+ *
+ * Returns null when the base patch no longer exists (e.g. a preset synced from
+ * a build that had a patch this one does not).
+ */
+export declare function toUserManifest(user: UserPatch): PatchManifest | null;
+/**
+ * The built-in catalog with user presets merged in as USR-bank entries.
+ *
+ * Every consumer must use this rather than the raw `catalog`: looking a
+ * selected id up in the raw catalog silently misses user presets, which is how
+ * picking one from the library used to do nothing at all.
+ */
+export declare function useFullCatalog(): PatchManifest[];

package/dist/types/state/useSoundEngine.d.ts

@@ -0,0 +1,41 @@
+import { type AudioEngine, type EngineOptions } from '../audio/AudioEngine';
+import type { Bank, PatchManifest } from '../patches/types';
+export type LatencyInfo = ReturnType<AudioEngine['latencyInfo']>;
+export interface SoundEngineOptions {
+    /** Default true. When false, loads never mark patches as cached for offline (embed). */
+    trackOffline?: boolean;
+    /** Forwarded to getEngine(); only takes effect when it creates the engine. */
+    engineOptions?: EngineOptions;
+    /**
+     * Default false. When true, unmount silences and suspends the engine, and a
+     * re-run after power-on resumes it.
+     */
+    suspendOnUnmount?: boolean;
+}
+export interface SoundEngineApi {
+    engine: AudioEngine;
+    fullCatalog: PatchManifest[];
+    displayPatch: PatchManifest | undefined;
+    displayIndex: number;
+    isLoading: boolean;
+    activeBank: Bank;
+    currentBankPatches: PatchManifest[];
+    needsGesture: boolean;
+    ensureAudio(): Promise<void>;
+    selectPatch(p: PatchManifest): void;
+    selectPatchId(id: string): void;
+    previewPatchById(id: string): void;
+    downloadPatchById(id: string): void;
+    handleStep(delta: number): void;
+    handleBankSelect(bank: Bank): void;
+    noteOn(midi: number, vel: number): void;
+    noteOff(midi: number): void;
+    uiNoteOn(midi: number, vel: number): void;
+    panic(): void;
+    getLatency(): LatencyInfo;
+}
+/**
+ * The engine, patch selection and note wiring shared by the standalone app and
+ * the embed. Owns the load callbacks, the power-on gesture and MIDI input.
+ */
+export declare function useSoundEngine(options?: SoundEngineOptions): SoundEngineApi;

package/dist/types/state/useStore.d.ts

@@ -0,0 +1,131 @@
+import type { EffectId } from '../audio/effects';
+import type { ChainEffectId } from '../audio/effects';
+import type { PatchSourceTag } from '../audio/AudioEngine';
+import type { PatchManifest, UserPatch } from '../patches/types';
+import { type MidiPresetId, type MidiProfile } from '../input/midiProfile';
+import type { BreathConfig } from '../input/breath';
+/**
+ * Web MIDI access, as three user-visible outcomes plus the pre-request states:
+ * - `unsupported`: no requestMIDIAccess (iOS, Firefox without the add-on…)
+ * - `idle`: supported, not requested yet (we ask on demand)
+ * - `pending`: prompt showing
+ * - `denied`: SecurityError — recoverable only via Chrome's site settings
+ * - `granted`: access held (devices may or may not be plugged in)
+ * - `error`: any other failure
+ */
+export type MidiAccessStatus = 'unsupported' | 'idle' | 'pending' | 'denied' | 'granted' | 'error';
+export interface MidiDeviceInfo {
+    id: string;
+    name: string;
+    manufacturer: string;
+}
+interface State {
+    catalog: PatchManifest[];
+    currentPatchId: string;
+    /**
+     * The patch the user last asked for. Set the instant a selection happens and
+     * cleared when the engine either commits it (currentPatchId) or fails, so the
+     * display never claims a patch that is not actually loaded.
+     */
+    pendingPatchId: string | null;
+    loadError: {
+        id: string;
+        name: string;
+    } | null;
+    loadingPatchId: string | null;
+    loadingProgress: {
+        loaded: number;
+        total: number;
+    } | null;
+    currentSource: PatchSourceTag | null;
+    octave: number;
+    velocity: number;
+    fxEnabled: Record<EffectId, boolean>;
+    fxParams: Record<EffectId, Record<string, number>>;
+    /** Order of the audio effects in the chain. Doublers are note-level, so absent. */
+    fxOrder: ChainEffectId[];
+    favourites: Set<string>;
+    downloaded: Set<string>;
+    downloadingPatchId: string | null;
+    warmProgress: {
+        done: number;
+        total: number;
+    } | null;
+    userPatches: UserPatch[];
+    saveDialogOpen: boolean;
+    pickerOpen: boolean;
+    midiConnected: boolean;
+    midiActivity: boolean;
+    midiStatus: MidiAccessStatus;
+    midiDevices: MidiDeviceInfo[];
+    midiProfile: MidiProfile;
+    midiPanelOpen: boolean;
+    /** Learn mode: the next swept CC on any input becomes the breath CC. */
+    midiLearning: boolean;
+    setMidiStatus: (s: MidiAccessStatus) => void;
+    setMidiDevices: (d: MidiDeviceInfo[]) => void;
+    setMidiProfile: (p: MidiProfile) => void;
+    applyMidiPreset: (id: MidiPresetId) => void;
+    updateBreath: (patch: Partial<BreathConfig>) => void;
+    setBreathEnabled: (v: boolean) => void;
+    setMidiPanelOpen: (open: boolean) => void;
+    setMidiLearning: (v: boolean) => void;
+    debugMode: boolean;
+    online: boolean;
+    keyboardMode: boolean;
+    fxVisible: boolean;
+    previewPatchId: string | null;
+    setPickerOpen: (open: boolean) => void;
+    setPendingPatchId: (id: string | null) => void;
+    setLoadError: (e: {
+        id: string;
+        name: string;
+    } | null) => void;
+    setKeyboardMode: (v: boolean) => void;
+    toggleKeyboardMode: () => void;
+    setFxVisible: (v: boolean) => void;
+    toggleFxVisible: () => void;
+    setPreviewPatchId: (id: string | null) => void;
+    setLoadingPatchId: (id: string | null) => void;
+    setLoadingProgress: (p: {
+        loaded: number;
+        total: number;
+    } | null) => void;
+    setCurrentSource: (s: PatchSourceTag | null) => void;
+    setCurrentPatchId: (id: string) => void;
+    markDownloaded: (id: string) => void;
+    unmarkDownloaded: (id: string) => void;
+    setDownloadingPatchId: (id: string | null) => void;
+    setWarmProgress: (p: {
+        done: number;
+        total: number;
+    } | null) => void;
+    setOctave: (n: number) => void;
+    shiftOctave: (delta: number) => void;
+    setVelocity: (n: number) => void;
+    shiftVelocity: (delta: number) => void;
+    toggleFxEnabled: (id: EffectId) => void;
+    setFxParam: (id: EffectId, paramId: string, value: number) => void;
+    setFxOrder: (order: ChainEffectId[]) => void;
+    moveFx: (id: ChainEffectId, delta: number) => void;
+    toggleFavourite: (id: string) => void;
+    setMidiConnected: (b: boolean) => void;
+    flashMidiActivity: () => void;
+    setSaveDialogOpen: (open: boolean) => void;
+    saveCurrentAsUserPatch: (name: string) => string | null;
+    deleteUserPatch: (id: string) => void;
+    setDebugMode: (v: boolean) => void;
+    toggleDebugMode: () => void;
+    setOnline: (v: boolean) => void;
+}
+export type PersistScope = 'app' | 'embed';
+/** 'embed' persists only patch, octave and velocity; 'app' (default) also persists fx state. */
+export declare function setPersistScope(scope: PersistScope): void;
+export declare const useStore: import("zustand").UseBoundStore<import("zustand").StoreApi<State>>;
+/**
+ * App-only startup: loads downloaded patches, user patches and debug mode from
+ * localStorage and installs online/offline listeners. Idempotent. Kept out of
+ * module load so the store can be imported by the embed without side effects.
+ */
+export declare function hydrateAppState(): void;
+export {};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@pepperhorn/sound-module",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Embeddable React sound module: a sampled-instrument rack with patch browser, on-screen piano, computer keyboard and Web MIDI input.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/embed/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/embed/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./dist/styles.css",
+    "./fonts.css": "./dist/fonts.css",
+    "./patches/*": "./dist/patches/*",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prepublishOnly": "node scripts/verify-dist.mjs"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@fontsource/chakra-petch": "^5.3.0",
+    "@fontsource/inter": "^5.1.0",
+    "@fontsource/jetbrains-mono": "^5.1.0",
+    "@fontsource/michroma": "^5.3.0",
+    "smplr": "^0.20.0",
+    "zustand": "^5.0.12"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}