sa2kit 1.4.2 → 1.5.1

package/dist/audioDetection/index.d.mts

@@ -0,0 +1,449 @@
+import React__default from 'react';
+
+/**
+ * 音频检测模块类型定义
+ * Audio Detection Module Type Definitions
+ */
+/**
+ * 音符信息
+ * Note Information
+ */
+interface NoteInfo {
+    /** 音符名称 (例如: "C4", "A#3") */
+    name: string;
+    /** 频率 (Hz) */
+    frequency: number;
+    /** 音高类别 (不含八度，例如: "C", "A#") */
+    noteName: string;
+    /** 八度 */
+    octave: number;
+    /** 音符的MIDI编号 */
+    midi: number;
+    /** 音量/强度 (0-1) */
+    volume: number;
+    /** 音符检测的置信度 (0-1) */
+    confidence: number;
+}
+/**
+ * 和弦信息
+ * Chord Information
+ */
+interface ChordInfo {
+    /** 和弦名称 (例如: "Cmaj", "Am7") */
+    name: string;
+    /** 根音 */
+    root: string;
+    /** 和弦类型 (例如: "major", "minor", "diminished") */
+    type: string;
+    /** 组成音符 */
+    notes: NoteInfo[];
+    /** 和弦检测的置信度 (0-1) */
+    confidence: number;
+}
+/**
+ * 音频检测结果
+ * Audio Detection Result
+ */
+interface AudioDetectionResult {
+    /** 检测到的所有音符 */
+    notes: NoteInfo[];
+    /** 检测到的和弦（如果有） */
+    chord?: ChordInfo;
+    /** 检测时间戳 */
+    timestamp: number;
+    /** 是否正在检测到声音 */
+    isDetecting: boolean;
+}
+/**
+ * 音频输入配置
+ * Audio Input Configuration
+ */
+interface AudioInputConfig {
+    /** 采样率 (默认: 44100) */
+    sampleRate?: number;
+    /** FFT大小 (默认: 4096) */
+    fftSize?: number;
+    /** 最小音量阈值 (0-1, 默认: 0.01) */
+    minVolume?: number;
+    /** 最小检测置信度 (0-1, 默认: 0.7) */
+    minConfidence?: number;
+    /** 平滑系数 (0-1, 默认: 0.8) */
+    smoothing?: number;
+    /** 检测频率范围 */
+    frequencyRange?: {
+        min: number;
+        max: number;
+    };
+}
+/**
+ * 音频输入状态
+ * Audio Input State
+ */
+type AudioInputState = 'idle' | 'initializing' | 'active' | 'error' | 'stopped';
+/**
+ * 音频检测器事件
+ * Audio Detector Events
+ */
+interface AudioDetectorEvents {
+    /** 检测到新的音频结果 */
+    onDetection?: (result: AudioDetectionResult) => void;
+    /** 状态变化 */
+    onStateChange?: (state: AudioInputState) => void;
+    /** 错误发生 */
+    onError?: (error: Error) => void;
+}
+/**
+ * 频率到音符的映射
+ * Frequency to Note Mapping
+ */
+interface FrequencyToNoteMap {
+    [frequency: number]: NoteInfo;
+}
+
+/**
+ * 音频输入服务
+ * Audio Input Service
+ *
+ * 负责管理麦克风输入和音频流处理
+ * Manages microphone input and audio stream processing
+ */
+
+declare class AudioInputService {
+    private audioContext;
+    private mediaStream;
+    private sourceNode;
+    private analyserNode;
+    private state;
+    private config;
+    constructor(config?: AudioInputConfig);
+    /**
+     * 初始化音频输入
+     * Initialize audio input
+     */
+    initialize(): Promise<void>;
+    /**
+     * 获取时域数据
+     * Get time domain data
+     */
+    getTimeDomainData(): Float32Array;
+    /**
+     * 获取频域数据
+     * Get frequency domain data
+     */
+    getFrequencyData(): Float32Array;
+    /**
+     * 获取当前音量
+     * Get current volume
+     */
+    getCurrentVolume(): number;
+    /**
+     * 停止音频输入
+     * Stop audio input
+     */
+    stop(): void;
+    /**
+     * 获取当前状态
+     * Get current state
+     */
+    getState(): AudioInputState;
+    /**
+     * 获取配置
+     * Get configuration
+     */
+    getConfig(): Required<AudioInputConfig>;
+    /**
+     * 获取音频上下文
+     * Get audio context
+     */
+    getAudioContext(): AudioContext | null;
+    /**
+     * 获取分析器节点
+     * Get analyser node
+     */
+    getAnalyserNode(): AnalyserNode | null;
+    /**
+     * 设置状态
+     * Set state
+     */
+    private setState;
+    /**
+     * 检查是否正在运行
+     * Check if running
+     */
+    isRunning(): boolean;
+}
+
+/**
+ * 音高检测器
+ * Pitch Detector
+ *
+ * 使用自相关算法检测音频中的音高
+ * Uses autocorrelation algorithm to detect pitch in audio
+ */
+
+declare class PitchDetector {
+    private sampleRate;
+    private minFrequency;
+    private maxFrequency;
+    private static readonly NOTE_NAMES;
+    constructor(sampleRate?: number, minFrequency?: number, maxFrequency?: number);
+    /**
+     * 检测音高
+     * Detect pitch using autocorrelation
+     */
+    detectPitch(audioBuffer: Float32Array, minVolume?: number): number | null;
+    /**
+     * 自相关算法
+     * Autocorrelation algorithm
+     */
+    private autoCorrelate;
+    /**
+     * 计算RMS音量
+     * Calculate RMS volume
+     */
+    private calculateRMS;
+    /**
+     * 将频率转换为音符信息
+     * Convert frequency to note information
+     */
+    frequencyToNote(frequency: number, volume?: number): NoteInfo | null;
+    /**
+     * 使用FFT检测主频率
+     * Detect dominant frequency using FFT
+     */
+    detectDominantFrequency(frequencyData: Float32Array, minVolume?: number): number | null;
+    /**
+     * 抛物线插值
+     * Parabolic interpolation for better frequency estimation
+     */
+    private parabolicInterpolation;
+    /**
+     * 检测多个音高（和弦）
+     * Detect multiple pitches (chords)
+     */
+    detectMultiplePitches(frequencyData: Float32Array, minVolume?: number): NoteInfo[];
+}
+
+/**
+ * 和弦识别器
+ * Chord Recognizer
+ *
+ * 根据检测到的音符识别和弦
+ * Recognizes chords based on detected notes
+ */
+
+declare class ChordRecognizer {
+    private static readonly CHORD_PATTERNS;
+    private static readonly NOTE_NAMES;
+    /**
+     * 识别和弦
+     * Recognize chord from notes
+     */
+    recognizeChord(notes: NoteInfo[]): ChordInfo | null;
+    /**
+     * 获取唯一的音符类别（不考虑八度）
+     * Get unique note classes (ignoring octave)
+     */
+    private getUniqueNoteClasses;
+    /**
+     * 计算音程
+     * Calculate intervals from root
+     */
+    private calculateIntervals;
+    /**
+     * 匹配和弦模式
+     * Match chord pattern
+     */
+    private matchPattern;
+    /**
+     * 获取和弦后缀
+     * Get chord suffix for display
+     */
+    private getChordSuffix;
+    /**
+     * 识别八度内的音程（用于简单的音程识别）
+     * Recognize interval within an octave
+     */
+    recognizeInterval(note1: NoteInfo, note2: NoteInfo): string;
+    /**
+     * 分析和弦质量
+     * Analyze chord quality
+     */
+    analyzeChordQuality(chord: ChordInfo): string;
+}
+
+/**
+ * 音频检测器 - 主控制器
+ * Audio Detector - Main Controller
+ *
+ * 整合音频输入、音高检测和和弦识别
+ * Integrates audio input, pitch detection, and chord recognition
+ */
+
+declare class AudioDetector {
+    private audioInput;
+    private pitchDetector;
+    private chordRecognizer;
+    private isDetecting;
+    private animationFrameId;
+    private events;
+    private lastResult;
+    constructor(config?: AudioInputConfig, events?: AudioDetectorEvents);
+    /**
+     * 启动音频检测
+     * Start audio detection
+     */
+    start(): Promise<void>;
+    /**
+     * 停止音频检测
+     * Stop audio detection
+     */
+    stop(): void;
+    /**
+     * 检测循环
+     * Detection loop
+     */
+    private detectLoop;
+    /**
+     * 执行一次检测
+     * Perform single detection
+     */
+    private detect;
+    /**
+     * 获取当前状态
+     * Get current state
+     */
+    getState(): AudioInputState;
+    /**
+     * 获取最后的检测结果
+     * Get last detection result
+     */
+    getLastResult(): AudioDetectionResult | null;
+    /**
+     * 检查是否正在运行
+     * Check if running
+     */
+    isRunning(): boolean;
+    /**
+     * 获取音频输入服务
+     * Get audio input service
+     */
+    getAudioInput(): AudioInputService;
+}
+
+/**
+ * 音频检测调试工具
+ * Audio Detection Debug Tool
+ */
+
+declare class AudioDetectorDebugger {
+    private detector;
+    private debugInterval;
+    constructor(config?: AudioInputConfig);
+    start(): Promise<void>;
+    stop(): void;
+    getDetector(): AudioDetector;
+    /**
+     * 测试麦克风是否正常工作
+     */
+    testMicrophone(): Promise<{
+        hasPermission: boolean;
+        isReceivingAudio: boolean;
+        averageVolume: number;
+        peakVolume: number;
+    }>;
+}
+declare function debugAudioDetection(config?: AudioInputConfig): Promise<AudioDetectorDebugger>;
+declare function testMicrophone(): Promise<void>;
+
+/**
+ * 音频检测 React Hook
+ * Audio Detection React Hook
+ */
+
+interface UseAudioDetectionOptions extends AudioInputConfig {
+    /** 是否自动开始检测 */
+    autoStart?: boolean;
+    /** 检测结果更新间隔（毫秒） */
+    updateInterval?: number;
+}
+interface UseAudioDetectionReturn {
+    /** 当前检测结果 */
+    result: AudioDetectionResult | null;
+    /** 音频输入状态 */
+    state: AudioInputState;
+    /** 是否正在检测 */
+    isDetecting: boolean;
+    /** 错误信息 */
+    error: Error | null;
+    /** 启动检测 */
+    start: () => Promise<void>;
+    /** 停止检测 */
+    stop: () => void;
+    /** 获取检测器实例 */
+    getDetector: () => AudioDetector | null;
+}
+/**
+ * 使用音频检测的 Hook
+ * Hook for using audio detection
+ */
+declare function useAudioDetection(options?: UseAudioDetectionOptions): UseAudioDetectionReturn;
+
+/**
+ * 音频检测组件
+ * Audio Detection Component
+ *
+ * 显示实时音频检测结果的React组件
+ * React component for displaying real-time audio detection results
+ */
+
+interface AudioDetectionDisplayProps extends UseAudioDetectionOptions {
+    /** 自定义类名 */
+    className?: string;
+    /** 是否显示调试信息 */
+    showDebugInfo?: boolean;
+    /** 自定义渲染音符 */
+    renderNote?: (note: NoteInfo) => React__default.ReactNode;
+    /** 自定义渲染和弦 */
+    renderChord?: (chord: ChordInfo) => React__default.ReactNode;
+    /** 开始按钮文本 */
+    startButtonText?: string;
+    /** 停止按钮文本 */
+    stopButtonText?: string;
+}
+/**
+ * 音频检测显示组件
+ */
+declare const AudioDetectionDisplay: React__default.FC<AudioDetectionDisplayProps>;
+/**
+ * 默认样式（可以通过CSS覆盖）
+ */
+declare const audioDetectionStyles = "\n.audio-detection-display {\n  padding: 20px;\n  border: 1px solid #ddd;\n  border-radius: 8px;\n  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;\n}\n\n.audio-detection-controls {\n  display: flex;\n  gap: 12px;\n  align-items: center;\n  margin-bottom: 20px;\n}\n\n.audio-detection-button {\n  padding: 10px 20px;\n  font-size: 16px;\n  border: none;\n  border-radius: 6px;\n  background-color: #007bff;\n  color: white;\n  cursor: pointer;\n  transition: background-color 0.3s;\n}\n\n.audio-detection-button:hover {\n  background-color: #0056b3;\n}\n\n.audio-detection-button:disabled {\n  background-color: #ccc;\n  cursor: not-allowed;\n}\n\n.audio-detection-button.active {\n  background-color: #dc3545;\n}\n\n.audio-detection-button.active:hover {\n  background-color: #c82333;\n}\n\n.audio-detection-status {\n  padding: 8px 16px;\n  border-radius: 4px;\n  font-size: 14px;\n}\n\n.status-idle { background-color: #e7f3ff; color: #004085; }\n.status-initializing { background-color: #fff3cd; color: #856404; }\n.status-active { background-color: #d4edda; color: #155724; }\n.status-error { background-color: #f8d7da; color: #721c24; }\n.status-stopped { background-color: #e2e3e5; color: #383d41; }\n\n.audio-detection-error {\n  padding: 12px;\n  background-color: #f8d7da;\n  border: 1px solid #f5c6cb;\n  border-radius: 4px;\n  color: #721c24;\n  margin-bottom: 16px;\n}\n\n.audio-detection-result {\n  margin-top: 20px;\n}\n\n.audio-detection-notes h3,\n.audio-detection-chord h3 {\n  margin-bottom: 12px;\n  font-size: 18px;\n}\n\n.notes-grid {\n  display: grid;\n  grid-template-columns: repeat(auto-fill, minmax(150px, 1fr));\n  gap: 12px;\n}\n\n.note-item {\n  padding: 12px;\n  border: 2px solid #007bff;\n  border-radius: 6px;\n  background-color: #f8f9fa;\n}\n\n.default-note-display {\n  text-align: center;\n}\n\n.note-name {\n  font-size: 24px;\n  font-weight: bold;\n  color: #007bff;\n  margin-bottom: 4px;\n}\n\n.note-frequency {\n  font-size: 14px;\n  color: #666;\n  margin-bottom: 4px;\n}\n\n.note-confidence {\n  font-size: 12px;\n  color: #999;\n}\n\n.audio-detection-chord {\n  margin-top: 20px;\n  padding: 16px;\n  border: 2px solid #28a745;\n  border-radius: 8px;\n  background-color: #f8f9fa;\n}\n\n.default-chord-display {\n  text-align: center;\n}\n\n.chord-name {\n  font-size: 32px;\n  font-weight: bold;\n  color: #28a745;\n  margin-bottom: 8px;\n}\n\n.chord-type,\n.chord-notes,\n.chord-confidence {\n  margin-bottom: 4px;\n  color: #666;\n}\n\n.audio-detection-waiting {\n  text-align: center;\n  padding: 40px;\n  color: #666;\n  font-size: 18px;\n}\n\n.audio-detection-debug {\n  margin-top: 20px;\n  padding: 12px;\n  background-color: #f4f4f4;\n  border-radius: 4px;\n}\n\n.audio-detection-debug pre {\n  margin: 8px 0 0 0;\n  font-size: 12px;\n  overflow-x: auto;\n}\n";
+
+/**
+ * 钢琴键盘可视化组件
+ * Piano Keyboard Visualization Component
+ */
+
+interface PianoKeyboardProps {
+    /** 当前激活的音符 */
+    activeNotes?: NoteInfo[];
+    /** 起始八度 (默认: 2) */
+    startOctave?: number;
+    /** 结束八度 (默认: 6) */
+    endOctave?: number;
+    /** 自定义类名 */
+    className?: string;
+    /** 是否显示音符名称 */
+    showNoteNames?: boolean;
+}
+/**
+ * 钢琴键盘可视化
+ */
+declare const PianoKeyboard: React__default.FC<PianoKeyboardProps>;
+/**
+ * 钢琴键盘样式
+ */
+declare const pianoKeyboardStyles = "\n.piano-keyboard {\n  width: 100%;\n  padding: 20px;\n  background-color: #2c3e50;\n  border-radius: 8px;\n  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.3);\n}\n\n.piano-keys-container {\n  position: relative;\n  width: 100%;\n  height: 200px;\n}\n\n.white-keys {\n  display: flex;\n  height: 100%;\n  gap: 2px;\n}\n\n.piano-key {\n  position: relative;\n  border: 1px solid #000;\n  cursor: pointer;\n  transition: all 0.15s ease;\n}\n\n.white-key {\n  flex: 1;\n  background: linear-gradient(to bottom, #ffffff 0%, #f0f0f0 100%);\n  border-radius: 0 0 4px 4px;\n  display: flex;\n  align-items: flex-end;\n  justify-content: center;\n  padding-bottom: 8px;\n}\n\n.white-key:hover {\n  background: linear-gradient(to bottom, #f8f8f8 0%, #e8e8e8 100%);\n}\n\n.white-key.active {\n  background: linear-gradient(to bottom, #4CAF50 0%, #45a049 100%) !important;\n  box-shadow: 0 0 20px rgba(76, 175, 80, 0.8);\n}\n\n.black-keys {\n  position: absolute;\n  top: 0;\n  left: 0;\n  width: 100%;\n  height: 60%;\n  pointer-events: none;\n}\n\n.black-key {\n  position: absolute;\n  width: calc(100% / 52 * 0.6); /* \u5047\u8BBE\u670952\u4E2A\u767D\u952E\u7684\u5BBD\u5EA6 */\n  height: 100%;\n  background: linear-gradient(to bottom, #2c3e50 0%, #1a252f 100%);\n  border-radius: 0 0 3px 3px;\n  pointer-events: all;\n  transform: translateX(-50%);\n  display: flex;\n  align-items: flex-end;\n  justify-content: center;\n  padding-bottom: 6px;\n  z-index: 10;\n}\n\n.black-key:hover {\n  background: linear-gradient(to bottom, #34495e 0%, #2c3e50 100%);\n}\n\n.black-key.active {\n  background: linear-gradient(to bottom, #4CAF50 0%, #388E3C 100%) !important;\n  box-shadow: 0 0 20px rgba(76, 175, 80, 0.8);\n}\n\n.key-label {\n  font-size: 11px;\n  font-weight: bold;\n  user-select: none;\n}\n\n.white-key .key-label {\n  color: #666;\n}\n\n.white-key.active .key-label {\n  color: white;\n}\n\n.black-key .key-label {\n  color: #ddd;\n}\n\n.black-key.active .key-label {\n  color: white;\n}\n";
+
+export { AudioDetectionDisplay, type AudioDetectionDisplayProps, type AudioDetectionResult, AudioDetector, AudioDetectorDebugger, type AudioDetectorEvents, type AudioInputConfig, AudioInputService, type AudioInputState, type ChordInfo, ChordRecognizer, type FrequencyToNoteMap, type NoteInfo, PianoKeyboard, type PianoKeyboardProps, PitchDetector, type UseAudioDetectionOptions, type UseAudioDetectionReturn, audioDetectionStyles, debugAudioDetection, pianoKeyboardStyles, testMicrophone, useAudioDetection };