# 克隆项目
git clone <repository-url>
cd music-rhythm-analysis

# 安装依赖
uv sync

# 基本分析
uv run rhythm-analyzer analyze your_audio.mp3

# 生成可视化图表
uv run rhythm-analyzer analyze your_audio.mp3 --visualize

# 查找最佳卡点
uv run rhythm-analyzer find-best-beats your_audio.mp3 --threshold 0.6

📋 命令详解

基本分析命令

uv run rhythm-analyzer analyze [OPTIONS] AUDIO_FILE

选项说明：

--output, -o - 输出文件路径（默认：beat_data.json）
--format, -f - 输出格式：json/csv/txt（默认：json）
--visualize, -v - 生成可视化图表
--viz-path - 可视化图表保存路径（默认：beat_analysis.png）
--time-format - 时间戳格式：seconds/mm:ss/frames（默认：seconds）
--show-beats - 显示前N个节拍（0=全部）

最佳卡点查找

uv run rhythm-analyzer find-best-beats [OPTIONS] AUDIO_FILE

选项说明：

--threshold, -t - 节拍强度阈值 0.0-1.0（默认：0.5）
--min-interval, -i - 最小节拍间隔秒数（默认：0.1）

🎯 使用示例

基础用法

# 分析音频并生成JSON数据
uv run rhythm-analyzer analyze song.mp3

# 导出CSV格式数据
uv run rhythm-analyzer analyze song.mp3 --format csv --output beats.csv

# 生成可视化图表
uv run rhythm-analyzer analyze song.mp3 --visualize --viz-path song_beats.png

高级用法

# 使用分秒时间格式显示前20个节拍
uv run rhythm-analyzer analyze song.mp3 --time-format mm:ss --show-beats 20

# 高强度阈值筛选最佳卡点
uv run rhythm-analyzer find-best-beats song.mp3 --threshold 0.7 --min-interval 0.15

# 分析结果导出为文本格式
uv run rhythm-analyzer analyze song.mp3 --format txt --output beat_report.txt

📊 输出格式

JSON格式

{
  "audio_file": "song.mp3",
  "bpm": 128.5,
  "total_beats": 320,
  "beat_times": [0.5, 1.0, 1.5, ...],
  "beat_timestamps": ["0.500s", "1.000s", "1.500s", ...],
  "downbeats": [0.5, 2.5, 4.5, ...],
  "beat_strengths": [[0.5, 31.76], [1.0, 28.12], ...]
}

CSV格式

Beat	Time (seconds)	Timestamp	Strength
1	0.500	0.500s	31.760
2	1.000	1.000s	28.120

TXT格式

音频文件: song.mp3
BPM: 128.50
总节拍数: 320

节拍时间戳:
  拍 1: 0.500s
  拍 2: 1.000s
  ...

🔧 API使用

from rhythm_analyzer import AudioRhythmAnalyzer

# 创建分析器
analyzer = AudioRhythmAnalyzer("your_audio.mp3")

# 加载和分析
analyzer.load_audio()
bpm = analyzer.detect_tempo()

# 获取节拍时间戳
timestamps = analyzer.get_beat_timestamps("seconds")
downbeats = analyzer.get_downbeats()

# 分析节拍强度
beat_strengths = analyzer.analyze_beat_strength()

# 导出数据
analyzer.export_beats("output.json", "json")

# 生成可视化
analyzer.visualize_beats("analysis.png")

🎵 支持的音频格式

MP3 - 最常用的音频格式
WAV - 无损音频格式
FLAC - 无损压缩格式
OGG - 开源音频格式
M4A - Apple音频格式

🔬 技术原理

本工具基于librosa库实现专业音频分析：

音频预处理 - 使用librosa加载和重采样音频
onset检测 - 检测音频中的瞬态事件
节奏跟踪 - 通过自相关算法计算BPM
节拍对齐 - 使用动态规划优化节拍位置
强度分析 - 计算每个节拍位置的音频能量
智能筛选 - 基于强度和间隔筛选最佳卡点

⚠️ 注意事项

音频质量

建议使用高质量音频文件（比特率≥128kbps）
避免严重压缩或失真的音频
单声道音频效果最佳

算法限制

复杂节奏音乐可能遗漏部分节拍
变拍子音乐检测准确性可能降低
即兴演奏或自由节奏音乐效果有限

参数调优

对于快节奏音乐，可降低--threshold值
对于慢节奏音乐，可增加--min-interval值
可视化功能需要matplotlib支持

🛠️ 开发环境

# 安装开发依赖
uv sync --group dev

# 代码格式化
uv run black .
uv run ruff check .

# 运行测试
uv run pytest

📁 项目结构

music-rhythm-analysis/
├── pyproject.toml      # uv项目配置和依赖管理
├── cli_uv.py          # 命令行界面（uv版本）
├── rhythm_analyzer.py # 核心分析引擎
├── demo.py            # 使用示例和演示
├── requirements.txt   # pip依赖文件（兼容性）
├── .gitignore         # Git忽略文件
├── README.md          # 项目文档
└── IFLOW.md           # iFlow上下文文件