@react-synth/synth 0.0.6-alpha

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+import { AudioContext as AudioContext_2 } from 'node-web-audio-api';
+import { Context } from 'react';
+import { ReactNode } from 'react';
+
+declare type Accidental = "" | "#" | "b" | "##" | "bb";
+
+export declare const ADSR_DEFAULTS: {
+    readonly attack: 0;
+    readonly attack_level: 1;
+    readonly decay: 0;
+    readonly sustain: 0;
+    readonly sustain_level: 1;
+    readonly release: 1;
+};
+
+export declare type ADSRProps = {
+    /** Attack time in beats - time from silence to attack_level (default: 0) */
+    attack?: number;
+    /** Peak amplitude at end of attack, multiplied by amp (default: 1) */
+    attack_level?: number;
+    /** Decay time in beats - time from attack_level to decay_level (default: 0) */
+    decay?: number;
+    /** Amplitude at end of decay, multiplied by amp (default: sustain_level) */
+    decay_level?: number;
+    /** Sustain time in beats - time at sustain_level (default: 0) */
+    sustain?: number;
+    /** Sustained amplitude level, multiplied by amp (default: 1) */
+    sustain_level?: number;
+    /** Release time in beats - time from sustain_level to silence (default: 1) */
+    release?: number;
+};
+
+export declare function applyADSREnvelope(gainNode: GainNode, audioTime: number, props: ADSRProps, amp: number, beatsToSeconds: (beats: number) => number): number;
+
+/**
+ * Chord component - plays multiple notes simultaneously using Web Audio oscillators
+ *
+ * When used inside a Loop or Sequence, the chord will be scheduled
+ * with sample-accurate timing via the scheduler.
+ *
+ * The chord duration is determined by the ADSR envelope:
+ * total duration = attack + decay + sustain + release
+ *
+ * @example
+ * // Using chord names (powered by Tonal)
+ * <Chord notes="Cmaj7" amp={0.5} />
+ * <Chord notes="Am:4" oscillator="sawtooth" />  // A minor in octave 4
+ * <Chord notes="Dm7/F" release={2} />           // D minor 7 with F bass
+ *
+ * // Using note arrays
+ * <Chord notes={["a3", "c4", "e4"]} amp={0.5} attack={0.1} sustain={2} release={0.5} />
+ * <Chord notes={[440, 550, 660]} oscillator="sawtooth" decay={0.2} sustain_level={0.7} />
+ *
+ * // With filter and voice overrides
+ * <Chord notes="Em7" filter={{ cutoff: 1000, resonance: 4 }} />
+ * <Chord notes="Cmaj" voices={{ count: 2, detune: 8 }} />
+ */
+export declare function Chord({ notes, amp, oscillator, filter, voices, attack, attack_level, decay, decay_level, sustain, sustain_level, release, __stepIndex, }: ChordProps): ReactNode;
+
+declare type ChordProps = ADSRProps & SynthOverrides & {
+    /**
+     * Chord specification - can be:
+     * - A chord name string (e.g., "Cmaj7", "Am", "F#m7", "Dm/F")
+     * - An array of note names (e.g., ["A4", "C#3", "E4"])
+     * - An array of frequencies in Hz (e.g., [440, 550, 660])
+     *
+     * When using chord names, specify the octave with a colon (e.g., "Cmaj7:4" for octave 4)
+     * Default octave is 3 if not specified.
+     */
+    notes: string | (NoteName | number)[];
+    /** Amplitude 0-1 (default: 0.3) */
+    amp?: number;
+    /** Step index when inside a Sequence (injected by Sequence) */
+    __stepIndex?: number;
+};
+
+/**
+ * Cutoff value that can be either a static number or a dynamic line pattern
+ */
+export declare type CutoffType = number | {
+    /** Starting value (MIDI note number) */
+    from: number;
+    /** Ending value (MIDI note number) */
+    to: number;
+    /** Number of interpolation steps */
+    steps: number;
+    /** Whether to mirror the values (up then down) */
+    mirror?: boolean;
+    /**
+     * Manual step index override.
+     * Use this when you need a global step counter across nested sequences.
+     * If omitted, uses __stepIndex from the parent Sequence.
+     */
+    step?: number;
+};
+
+export declare const DEFAULT_SYNTH_CONFIG: SynthConfig;
+
+/**
+ * Configuration for the synthesizer's filter
+ */
+export declare type FilterConfig = {
+    /** Filter type */
+    type: FilterType;
+    /** Cutoff type */
+    cutoff: CutoffType;
+    /** Resonance/Q factor */
+    resonance: number;
+};
+
+export declare type FilterType = "lowpass" | "highpass" | "bandpass" | "lowshelf" | "highshelf" | "peaking" | "notch" | "allpass";
+
+export declare function getScheduler(bpm: number): Scheduler;
+
+export declare function getSynthPreset(type: SynthType): SynthConfig;
+
+declare type Letter = "A" | "B" | "C" | "D" | "E" | "F" | "G";
+
+/** Generate an array of linearly interpolated values */
+export declare function line(start: number, end: number, steps: number): number[];
+
+/**
+ * Loop component - plays its children repeatedly at the specified interval
+ *
+ * Children should use the useLoop() hook to register their audio callbacks,
+ * which will be called with precise timing by the scheduler.
+ *
+ * @example
+ * <Loop id="kick" interval={1}>
+ *   <Note note="C2" />
+ * </Loop>
+ */
+export declare function Loop({ id, interval, children, }: LoopProps): ReactNode;
+
+declare type LoopProps = {
+    /** Unique identifier for this loop */
+    id: string;
+    /** Interval in beats between each loop iteration */
+    interval: number;
+    /** Content to play on each loop */
+    children: ReactNode;
+};
+
+export declare function midiToFrequency(midi: number): number;
+
+/** Mirror an array: [1,2,3] → [1,2,3,3,2,1] */
+export declare function mirror(values: number[]): number[];
+
+/**
+ * Note component - plays a note using Web Audio oscillator with ADSR envelope
+ *
+ * When used inside a Loop or Sequence, the note will be scheduled
+ * with sample-accurate timing via the scheduler.
+ *
+ * The note duration is determined by the ADSR envelope:
+ * total duration = attack + decay + sustain + release
+ *
+ * @example
+ * <Note note="A4" amp={0.5} attack={0.1} sustain={0.5} release={0.2} />
+ * <Note note={440} oscillator="sawtooth" attack={0.05} decay={0.1} sustain_level={0.7} />
+ * <Note note="C4" filter={{ cutoff: 800, resonance: 5 }} />
+ * <Note note="E4" voices={{ count: 3, detune: 10, spread: 0.5 }} />
+ */
+export declare function Note({ note, amp, oscillator, filter, voices, attack, attack_level, decay, decay_level, sustain, sustain_level, release, __stepIndex, }: NoteProps): ReactNode;
+
+export declare type NoteInput = NoteName | number;
+
+export declare type NoteName = `${Letter}${Accidental}${Octave}`;
+
+declare type NoteProps = ADSRProps & SynthOverrides & {
+    /** Note name (e.g., "A4", "C#3") or frequency in Hz */
+    note: NoteName | number;
+    /** Amplitude 0-1 (default: 0.3) */
+    amp?: number;
+    /** Step index when inside a Sequence (injected by Sequence) */
+    __stepIndex?: number;
+};
+
+export declare function noteToFrequency(note: NoteName | string): number;
+
+declare type Octave = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+
+declare type OscillatorType_2 = "sine" | "square" | "sawtooth" | "triangle";
+export { OscillatorType_2 as OscillatorType }
+
+export declare type PitchClass = `${Letter}${Accidental}`;
+
+export declare function resetScheduler(bpm: number): Scheduler;
+
+export declare function resolveChordNotes(notes: string | (string | number)[]): (string | number)[];
+
+export declare function resolveCutoff(cutoff: CutoffType, stepIndex: number): number;
+
+/**
+ * Sample component - plays an audio sample file with optional effects
+ *
+ * @example
+ * <Sample name="bd_haus" amp={2} cutoff={100} />
+ * <Sample name="drum_cymbal_closed" amp={0.5} rate={1.5} pan={0.1} />
+ */
+export declare function Sample({ name, amp, cutoff, rate, pan, __stepIndex, }: SampleProps): ReactNode;
+
+export declare type SampleName = "bd_haus" | "drum_cymbal_closed";
+
+declare type SampleProps = {
+    /** Sample name (without extension, e.g., "bd_haus") */
+    name: SampleName;
+    /** Amplitude/volume (default: 1) */
+    amp?: number;
+    /**
+     * Filter cutoff as MIDI note number or Line pattern (Sonic Pi compatible)
+     *
+     * Common values:
+     * - 60  => ~262 Hz (C4)
+     * - 80  => ~831 Hz
+     * - 100 => ~2637 Hz
+     * - 110 => ~4699 Hz
+     * - 130 => ~20kHz (essentially no filtering)
+     *
+     * Can also be a Line pattern: { from: 60, to: 120, steps: 8 }
+     */
+    cutoff?: CutoffType;
+    /** Playback rate multiplier (default: 1) */
+    rate?: number;
+    /** Stereo pan position from -1 (left) to 1 (right) (default: 0) */
+    pan?: number;
+    /** Step index when inside a Sequence (injected by Sequence) */
+    __stepIndex?: number;
+};
+
+export declare type ScheduleCallback = (audioTime: number, beatTime: number) => void;
+
+export declare const ScheduleNoteContext: Context<ScheduleNoteContextValue | null>;
+
+export declare type ScheduleNoteContextValue = {
+    /**
+     * Schedule a note to be played.
+     * @param id - Unique identifier for this note callback
+     * @param callback - The audio callback to invoke at the scheduled time
+     * @param stepIndex - Optional step index when inside a Sequence
+     */
+    scheduleNote: (id: string, callback: ScheduleCallback, stepIndex?: number) => void;
+    /**
+     * Unschedule a previously scheduled note.
+     * @param id - The identifier used when scheduling
+     */
+    unscheduleNote: (id: string) => void;
+};
+
+export declare class Scheduler {
+    private context;
+    private _bpm;
+    private startTime;
+    private events;
+    private timerID;
+    private running;
+    private readonly lookahead;
+    private readonly scheduleInterval;
+    /** Grace period before actually removing a loop - allows React HMR to re-add it */
+    private readonly removalGracePeriod;
+    constructor(bpm: number);
+    get audioContext(): AudioContext_2;
+    get bpm(): number;
+    set bpm(value: number);
+    start(): void;
+    stop(): void;
+    clear(): void;
+    addLoop(id: string, intervalBeats: number, callback: ScheduleCallback, startBeat?: number): void;
+    remove(id: string): void;
+    beatsToSeconds(beats: number): number;
+    private secondsToBeats;
+    private getCurrentBeat;
+    private beatToAudioTime;
+    private schedule;
+}
+
+/**
+ * Sequence component - plays children one after another with precise timing
+ *
+ * @example
+ * <Sequence interval={0.25}>
+ *   <Note note="C4" />
+ *   <Note note="E4" />
+ *   <Note note="G4" />
+ * </Sequence>
+ */
+export declare function Sequence({ interval, children, __stepIndex, }: SequenceProps): ReactNode;
+
+declare type SequenceProps = {
+    /** Time interval between each child in beats */
+    interval: number;
+    /** Children to play in sequence */
+    children: ReactNode;
+    /** Step index when nested inside another Sequence (injected by parent Sequence) */
+    __stepIndex?: number;
+};
+
+/**
+ * Synth component - defines the synthesizer for child Note/Chord components
+ *
+ * @example
+ * // Using a preset synth type
+ * <Synth type="prophet">
+ *   <Note note="C4" />
+ * </Synth>
+ *
+ * @example
+ * // Overriding preset parameters with nested structure
+ * <Synth type="prophet" filter={{ cutoff: 2000, resonance: 6 }}>
+ *   <Chord notes="Am7" />
+ * </Synth>
+ *
+ * @example
+ * // Creating thick unison sound
+ * <Synth type="saw" voices={{ count: 4, detune: 15, spread: 0.8 }}>
+ *   <Sequence interval={0.25}>
+ *     <Note note="A3" />
+ *     <Note note="C4" />
+ *   </Sequence>
+ * </Synth>
+ */
+export declare function Synth({ type, oscillator, filter, voices, children, }: SynthProps): ReactNode;
+
+export declare const SYNTH_PRESETS: Record<SynthType, SynthConfig>;
+
+export declare type SynthConfig = {
+    /** Oscillator waveform type */
+    oscillator: OscillatorType_2;
+    /** Filter configuration */
+    filter: FilterConfig;
+    /** Voice/unison configuration */
+    voices: VoiceConfig;
+};
+
+export declare type SynthOverrides = {
+    oscillator?: OscillatorType_2;
+    filter?: Partial<FilterConfig>;
+    voices?: Partial<VoiceConfig>;
+};
+
+declare type SynthProps = SynthOverrides & {
+    type: SynthType;
+    children: React.ReactNode;
+};
+
+export declare type SynthType = "sine" | "saw" | "square" | "tri" | "prophet" | "hollow" | "dark_ambience" | "bass" | "pluck";
+
+/**
+ * Track component - wraps your song and provides timing context
+ *
+ * @example
+ * <Track bpm={120}>
+ *   <Loop id="drums" interval={1}>
+ *     <Note note="C4" />
+ *   </Loop>
+ * </Track>
+ */
+export declare function Track({ bpm, children }: TrackProps): ReactNode;
+
+declare type TrackContextValue = {
+    audioContext: AudioContext_2;
+    scheduler: Scheduler;
+};
+
+declare type TrackProps = {
+    bpm: number;
+    children: ReactNode;
+};
+
+export declare function useScheduleNote(): ScheduleNoteContextValue;
+
+export declare function useSynth(): SynthConfig;
+
+export declare function useTrack(): TrackContextValue;
+
+/**
+ * Configuration for oscillator voices (for unison/detune effects)
+ */
+export declare type VoiceConfig = {
+    /** Number of oscillator voices */
+    count: number;
+    /** Detune spread in cents between voices */
+    detune: number;
+    /** Stereo spread for voices 0-1 */
+    spread: number;
+};
+
+export { }