文章标题：从概念到代码实战：AI练琴助手核心原理与极简实现（2026）

def traditional_practice(player, piece):
    while not mastered(piece):
        performance = player.play(piece)
         关键：缺少自动评估模块
        feedback = player.self_assess(performance)
        player.adjust(feedback)
    return "mastered"

┌─────────────────────────────────────────────────────────┐
│                    AI音乐教学（上位概念）                   │
│        利用AI技术进行音乐教学，提供个性化教学方案             │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│              AI练琴助手（通用概念）                        │
│      实时反馈 | 错误检测 | 个性化指导 | 多乐器支持          │
└─────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────┐
│             智能陪练系统（钢琴场景落地）                    │
│   错音识别 | 节奏校准 | 动态计划 | 多维度评分 | 曲谱库     │
└─────────────────────────────────────────────────────────┘

pip install aubio numpy sounddevice

import aubio
import numpy as np
import sounddevice as sd

class PitchDetector:
    """
    实时音高检测器
    将音频输入转换为MIDI音符编号，用于判断弹奏的音符是否正确
    """
    
    def __init__(self, sample_rate=44100, hop_size=512):
        self.sample_rate = sample_rate
        self.hop_size = hop_size
        
         初始化aubio的音高检测对象，使用YIN算法（鲁棒性较好）
         YIN算法是一种自相关音高检测算法，对钢琴音色有良好的识别效果
        self.pitch_o = aubio.pitch("yin", hop_size, hop_size, sample_rate)
        self.pitch_o.set_unit("midi")   输出单位设为MIDI音符编号
        self.pitch_o.set_silence(-40)    静音阈值（dB）
    
    def audio_to_midi(self, audio_chunk):
        """
        将音频块转换为MIDI音符编号
        
        参数:
            audio_chunk: numpy数组，形状为(hop_size,)，音频采样数据
        返回:
            midi_note: int，检测到的MIDI音符编号；返回0表示检测无效
        """
         aubio要求输入为float32类型
        audio_f32 = audio_chunk.astype(np.float32)
        midi_note = self.pitch_o(audio_f32)[0]
        return int(round(midi_note)) if midi_note > 0 else 0

 测试代码：从麦克风读取音频并进行音高检测
def test_pitch_detection(duration=3, sample_rate=44100):
    """
    从麦克风读取指定时长的音频，实时打印检测到的MIDI音符
    """
    detector = PitchDetector(sample_rate=sample_rate)
    hop_size = 512   与检测器保持一致
    frames_per_hop = hop_size / sample_rate   每hop的时间间隔
    
    def audio_callback(indata, frames, time, status):
        if status:
            print(f"音频状态异常: {status}")
         处理单通道音频
        audio_chunk = indata[:, 0] if indata.shape[1] > 1 else indata.flatten()
        midi_note = detector.audio_to_midi(audio_chunk)
        if midi_note > 0:
            print(f"检测到音符: MIDI {midi_note} -> 音名: {midi_to_note_name(midi_note)}")
    
    print("开始录音检测（请在钢琴上弹奏几个音）...")
    stream = sd.InputStream(callback=audio_callback, channels=1, 
                           samplerate=sample_rate, blocksize=hop_size)
    with stream:
        sd.sleep(int(duration  1000))

def midi_to_note_name(midi_num):
    """将MIDI编号转换为可读的音名，如 60 -> C4（中央C）"""
    notes = ['C', 'C', 'D', 'D', 'E', 'F', 'F', 'G', 'G', 'A', 'A', 'B']
    octave = (midi_num // 12) - 1
    note = notes[midi_num % 12]
    return f"{note}{octave}"

class RhythmAnalyzer:
    """
    节奏分析与节拍检测器
    检测演奏的节拍位置，用于评估节奏准确性
    """
    
    def __init__(self, sample_rate=44100, hop_size=512):
        self.sample_rate = sample_rate
        self.hop_size = hop_size
        
         初始化节拍检测器
        self.beat_o = aubio.beat(samplerate=sample_rate, hop_size=hop_size)
        self.detected_beats = []   存储检测到的节拍时间戳
    
    def process_audio_stream(self, audio_stream_callback):
        """
        处理音频流，实时记录节拍位置
        
        在真实的AI练琴助手中，此模块会将检测到的节拍与乐谱中的预期节拍
        进行比对，计算节奏准确率并标记节奏偏移位置
        """
        pass
    
    def calculate_tempo_stability(self, beat_timestamps):
        """
        基于节拍时间戳计算节奏稳定性
        
        参数:
            beat_timestamps: list，检测到的节拍时间戳列表（单位：秒）
        返回:
            stability: float，节奏稳定性评分（0-1，越高越稳定）
            avg_bpm: float，平均每分钟节拍数
        """
        if len(beat_timestamps) < 2:
            return 0.0, 0.0
        
         计算相邻节拍的时间间隔
        intervals = np.diff(beat_timestamps)
        
         节奏稳定性 = 1 - 间隔的标准差/均值（归一化）
        mean_interval = np.mean(intervals)
        std_interval = np.std(intervals)
        stability = max(0.0, 1.0 - (std_interval / mean_interval))
        
         计算平均BPM
        avg_bpm = 60.0 / mean_interval if mean_interval > 0 else 0.0
        
        return stability, avg_bpm

class SimpleAIPracticeAssistant:
    """
    极简AI练琴助手示例
    整合音高检测与节奏检测，实现错误音符检测
    """
    
    def __init__(self, target_score=None):
        """
        参数:
            target_score: list of dict，目标乐谱，格式如
                [{"midi": 60, "duration": 1.0}, {"midi": 62, "duration": 0.5}, ...]
        """
        self.pitch_detector = PitchDetector()
        self.rhythm_analyzer = RhythmAnalyzer()
        self.target_score = target_score or []
    
    def detect_errors(self, actual_midi_notes, expected_midi_notes):
        """
        将实际弹奏的音符序列与目标乐谱比对，标记错误
        
        返回:
            errors: dict，包含错音位置、错误类型等信息
        """
        errors = {
            "wrong_pitch": [],    音高错误的音符位置
            "missed_notes": [],   漏弹的音符
            "extra_notes": []     多弹的音符
        }
        
        min_len = min(len(actual_midi_notes), len(expected_midi_notes))
        for i in range(min_len):
            if actual_midi_notes[i] != expected_midi_notes[i]:
                errors["wrong_pitch"].append({
                    "position": i,
                    "expected": expected_midi_notes[i],
                    "actual": actual_midi_notes[i],
                    "expected_name": midi_to_note_name(expected_midi_notes[i]),
                    "actual_name": midi_to_note_name(actual_midi_notes[i])
                })
        
        if len(actual_midi_notes) > len(expected_midi_notes):
            errors["extra_notes"] = actual_midi_notes[len(expected_midi_notes):]
        elif len(actual_midi_notes) < len(expected_midi_notes):
            errors["missed_notes"] = expected_midi_notes[len(actual_midi_notes):]
        
        return errors
    
    def generate_feedback(self, errors):
        """
        根据错误检测结果生成面向用户的反馈文本
        """
        if not any(errors.values()):
            return "演奏正确！继续加油！"
        
        feedback = []
        if errors["wrong_pitch"]:
            for err in errors["wrong_pitch"][:3]:   最多展示3个错误
                feedback.append(f"位置{err['position']+1}：应弹{err['expected_name']}，实际弹了{err['actual_name']}")
        
        if errors["missed_notes"]:
            feedback.append(f"漏弹了{len(errors['missed_notes'])}个音符")
        
        if errors["extra_notes"]:
            feedback.append(f"多弹了{len(errors['extra_notes'])}个音符")
        
        return "发现以下问题：" + "；".join(feedback)

 使用示例
if __name__ == "__main__":
     模拟一段C大调音阶作为目标乐谱（C4, D4, E4, F4, G4, A4, B4, C5）
    c_major_scale = [60, 62, 64, 65, 67, 69, 71, 72]
    
    assistant = SimpleAIPracticeAssistant()
    
     模拟一段包含错误的演奏（假设第二个音弹成了D4）
    actual_performance = [60, 63, 64, 65, 67, 69, 71, 72]
    
    errors = assistant.detect_errors(actual_performance, c_major_scale)
    feedback = assistant.generate_feedback(errors)
    
    print("AI练琴助手反馈：")
    print(feedback)

AI练琴助手反馈：
发现以下问题：位置2：应弹D4，实际弹了D4