Metadata-Version: 2.4
Name: music-beat-detector
Version: 0.1.0
Summary: Music beat and structure detection CLI tool
Home-page: https://github.com/morganliu/music-beat-detector
Author: morganliu
Author-email: morganliu@me.com
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: librosa>=0.10.0
Requires-Dist: pydub>=0.25.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Music Beat Detector

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

## 功能

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

## 安装

```bash
pip install music-beat-detector
```

## 使用

### CLI 命令行

```bash
# 基本用法（输出到 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

```python
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")
```

## 输出格式

```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 框架

## 开发

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

# 运行测试
pytest

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

## 许可证

MIT License
