@codexo/exojs 0.6.12 → 0.7.12

package/dist/esm/audio/BeatDetector.d.ts

@@ -0,0 +1,142 @@
+import { Signal } from '@/core/Signal';
+import type { AudioBus } from '@/audio/AudioBus';
+import type { Sound } from '@/audio/Sound';
+import type { Music } from '@/audio/Music';
+export type BeatDetectorSource = AudioBus | Sound | Music | MediaStream | AudioNode | null;
+export interface BeatDetectorOptions {
+    /** Minimum detectable BPM. Default 50. */
+    minBpm?: number;
+    /** Maximum detectable BPM. Default 250. */
+    maxBpm?: number;
+    /** FFT size for onset detection. Default 2048. */
+    fftSize?: number;
+    /** Hop size in samples between successive FFTs. Default 512. */
+    hopSize?: number;
+    /** Sliding window duration for tempogram (seconds). Default 6. */
+    tempoWindowSec?: number;
+    /** Initial suppression period before beats are emitted (ms). Default 1500. */
+    settlingMs?: number;
+    /** Number of mel filterbank bands. Default 24. */
+    melBands?: number;
+    /**
+     * When true (default), the worklet runs parallel 3/4 and 4/4 posteriors and
+     * switches active time signature via hysteresis. Set false to lock to 4/4.
+     */
+    enableTimeSignatureDetection?: boolean;
+}
+export interface BeatInfo {
+    /** audioContext.currentTime when the beat occurred. */
+    audioTime: number;
+    /** BPM at this beat. */
+    tempo: number;
+    /** Confidence 0..1. */
+    confidence: number;
+    /** Phase within beat (0 = start). */
+    beatPhase: number;
+    /** Novelty/onset strength at the beat. */
+    energy: number;
+    /** Is this beat the first in a bar? */
+    isDownbeat: boolean;
+    /** Beat position within the bar (1..N). */
+    beatInBar: number;
+}
+export interface UpcomingBeat {
+    audioTime: number;
+    tempo: number;
+    isDownbeat: boolean;
+    beatInBar: number;
+}
+export interface BarInfo {
+    audioTime: number;
+    tempo: number;
+    confidence: number;
+    /** Monotonically increasing bar counter since detector start. */
+    barNumber: number;
+}
+export interface TimeSignature {
+    numerator: number;
+    denominator: number;
+}
+export interface TempoCandidate {
+    bpm: number;
+    /** Peak strength 0..1. */
+    score: number;
+}
+export interface BandEnergy {
+    low: number;
+    mid: number;
+    high: number;
+}
+/**
+ * Real-time tempo + beat tracker. Splits work between the audio-rendering
+ * thread (an AudioWorklet that runs onset detection, tempogram analysis,
+ * and parallel 3/4 and 4/4 posterior estimation) and the main thread (this
+ * class — receives beats, fires Signals, handles configuration and source
+ * routing).
+ *
+ * Accepts a wide range of {@link BeatDetectorSource}s — bus, individual
+ * sound/music, raw MediaStream, or any AudioNode — and exposes a Signal
+ * for each notable event:
+ * - {@link BeatDetector.onBeat} — every detected beat
+ * - {@link BeatDetector.onDownbeat} — first beat of each bar
+ * - {@link BeatDetector.onBarStart} — bar boundary
+ * - {@link BeatDetector.onTempoChange} — when the tracked BPM changes
+ * - {@link BeatDetector.onBeatPredicted} — look-ahead schedule notice
+ *
+ * Detection is delayed by `settlingMs` (default 1500 ms) after a new
+ * source is attached; this prevents spurious beats during the algorithm's
+ * warm-up. Time-signature detection (3/4 vs 4/4) is on by default; lock
+ * to 4/4 by setting `enableTimeSignatureDetection: false`.
+ */
+export declare class BeatDetector {
+    readonly onBeat: Signal<[BeatInfo]>;
+    readonly onTempoChange: Signal<[number, number]>;
+    readonly onDownbeat: Signal<[BeatInfo]>;
+    readonly onBarStart: Signal<[BarInfo]>;
+    readonly onBeatPredicted: Signal<[UpcomingBeat]>;
+    private readonly _options;
+    private _workletNode;
+    private _source;
+    private _tapSource;
+    private _streamSource;
+    private _ready;
+    private _tempo;
+    private _beatPhase;
+    private _nextBeatTime;
+    private _confidence;
+    private _gridStability;
+    private _tempoCandidates;
+    private _rms;
+    private _onsetStrength;
+    private _bandEnergy;
+    private _barPosition;
+    private _barLength;
+    private _timeSignature;
+    private _nextDownbeatTime;
+    private _lookahead;
+    constructor(options?: BeatDetectorOptions);
+    get source(): BeatDetectorSource;
+    set source(value: BeatDetectorSource);
+    get ready(): Promise<void>;
+    get tempo(): number;
+    get beatPhase(): number;
+    get nextBeatTime(): number;
+    get confidence(): number;
+    get gridStability(): number;
+    get rms(): number;
+    get onsetStrength(): number;
+    get bandEnergy(): BandEnergy;
+    get tempoCandidates(): ReadonlyArray<TempoCandidate>;
+    get barPosition(): number;
+    get barLength(): number;
+    get timeSignature(): TimeSignature;
+    get nextDownbeatTime(): number;
+    get lookahead(): ReadonlyArray<UpcomingBeat>;
+    destroy(): void;
+    private _setup;
+    private _onWorkletMessage;
+    private _connectSource;
+    private _resolveToAudioNode;
+    private _deferConnectionViaBus;
+    private _disconnectTap;
+}