这是一个专业的音频节奏分析和卡点制作工具，使用现代化的uv包管理器，能够精确检测音乐节拍并生成卡点时间戳。

• 🎵 自动BPM检测 - 精确计算每分钟节拍数
• 🥁 节拍定位 - 准确识别每个节拍的时间位置
• 🎯 智能卡点 - 基于强度分析筛选最佳卡点位置
• 📊 可视化分析 - 生成音频波形和节拍强度图表
• 💾 多格式导出 - 支持JSON、CSV、TXT格式
• 🖥️ 现代CLI - 友好的命令行界面和丰富的选项

• Python 3.9-3.12
• uv包管理器

# 克隆项目
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

{
  "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], ...]
}

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

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

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

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库实现专业音频分析：

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

• 建议使用高质量音频文件（比特率≥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上下文文件

• 视频卡点 - 为短视频、Vlog添加音乐节拍特效
• 音乐制作 - 辅助编曲和节奏设计
• 舞蹈编排 - 根据节拍设计舞蹈动作
• 游戏开发 - 音乐游戏节拍同步
• 体育训练 - 节奏训练和配速指导

欢迎提交Issue和Pull Request来改进这个工具！

MIT License - 详见LICENSE文件