Music Beat Detector

音乐自动打点命令行工具，支持节拍检测和结构检测。

功能

• 节拍检测: 检测 BPM 和每拍时间点
• 结构检测: 检测音乐段落（intro/verse/chorus/bridge/outro）
• 能量分析: 检测能量高峰点
• 静音检测: 检测静音区域
• 多格式支持: MP3, WAV, FLAC, OGG, M4A, AAC, WMA

安装

pip install music-beat-detector

使用

CLI 命令行

# 基本用法（输出到 stdout）
beat-detector ./music-output/jiang02.mp3

# 输出到文件
beat-detector ./music-output/jiang02.mp3 -o ./music-output/yanglin01.json

# 格式化输出
beat-detector ./music-output/jiang02.mp3 -o ./music-output/yanglin01.json --pretty

# 指定帧率
beat-detector ./music-output/jiang02.mp3 --fps 60 -o ./music-output/yanglin01.json

# 调整日志级别
beat-detector ./music-output/jiang02.mp3 --log-level debug

Python API

from beat_detector import analyze

# 基本调用
result = analyze("input.mp3")

# 带参数调用
result = analyze(
    "input.mp3",
    fps=30,                    # 帧率
    log_level="info",          # 日志级别
    on_progress=lambda p: print(f"{p}%")  # 进度回调
)

# 访问结果
print(f"BPM: {result.meta.bpm}")
print(f"Duration: {result.meta.duration_ms}ms")
print(f"Beats: {len(result.beats)}")

# 导出 JSON
json_str = result.to_json(pretty=True)
result.save("output.json")

输出格式

{
  "meta": {
    "file": "input.mp3",
    "duration_ms": 180000,
    "sample_rate": 44100,
    "bpm": 120,
    "time_signature": "4/4"
  },
  "beats": [
    {"time_ms": 500, "frame": 15, "beat_in_bar": 1},
    {"time_ms": 1000, "frame": 30, "beat_in_bar": 2}
  ],
  "structure": {
    "segments": [
      {
        "type": "intro",
        "start_ms": 0,
        "end_ms": 8000,
        "start_frame": 0,
        "end_frame": 240,
        "confidence": 0.85
      }
    ],
    "energy_peaks": [
      {"time_ms": 15000, "frame": 450, "intensity": 0.9}
    ],
    "silence_regions": []
  }
}

依赖

• librosa - 音频分析
• pydub - 音频格式支持
• numpy - 数值计算
• click - CLI 框架

开发

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=beat_detector --cov-report=html

许可证

MIT License