raga（राग，印度古典音乐里的“旋律框架”）是一个小而完整的音乐信息检索与符号生成工具 箱，聚焦四件事：
- 音高与旋律 —— 自相关 / YIN 基频估计、F0→音符量化、单声部旋律切分。
- 节拍与速度 —— 谱通量起始点、自相关测速、动态规划节拍跟踪。
- 和声分析 —— 色度图、Krumhansl 调性估计、模板匹配和弦识别。
- 符号生成 —— 受调式约束的随机游走旋律、马尔可夫模型、功能和声进行，以及零依赖的 标准 MIDI 文件读写。
它只依赖 NumPy / SciPy，不引入音频库或深度学习框架，因此离线、可复现、易读——适合 作为歌声/音乐研究的“音乐一侧”前端与教学参考实现。
⚠️ 早期研究阶段：API 仍可能调整，欢迎在 issue 中讨论。
pip install -e . # 从源码安装
pip install -e ".[dev]" # 连同开发/测试依赖要求 Python ≥ 3.9。
import raga
signal, sr = raga.read_wav("solo.wav")
# 1) 音高与旋律
f0 = raga.estimate_f0(signal, sr, method="yin") # (帧数,)，无基音为 0
notes = raga.extract_melody(signal, sr) # 旋律音符事件
# 2) 节拍与速度
beats, tempo = raga.track_beats(signal, sr) # 节拍时间（秒）+ BPM
# 3) 和声
key = raga.estimate_key(signal, sr) # 例如 "C major"
chords = raga.recognize_chords(signal, sr) # 和弦段列表
# 4) 生成并写成 MIDI（给定种子即可复现）
score = raga.random_walk_melody(tonic=0, scale="major", n_notes=16, seed=0)
raga.write_midi(score, "tune.mid")安装后提供 raga 命令：
raga pitch solo.wav -o f0.csv --method yin
raga chords solo.wav
raga key solo.wav
raga tempo solo.wav --show-beats
raga gen -o tune.mid --tonic A --scale pentatonic_minor --notes 24 --seed 7| 模块 | 内容 |
|---|---|
raga.io |
WAV 读写 |
raga.framing |
分帧、加窗 |
raga.spectral |
STFT、功率/幅度谱 |
raga.notes |
音名 / 音级与频率换算 |
raga.pitch |
自相关 / YIN 基频估计 |
raga.chroma |
色度图与归一化 |
raga.onset |
谱通量起始点检测 |
raga.tempo |
测速与动态规划节拍跟踪 |
raga.key |
Krumhansl 调性估计 |
raga.chords |
模板匹配和弦识别 |
raga.melody |
F0 → 旋律音符切分 |
raga.score / raga.midi |
乐谱容器与标准 MIDI 读写 |
raga.generate |
随机游走 / 马尔可夫旋律、和弦进行 |
MIT © Rong Shengxue