内容
# midifier
将一首歌曲转换成多轨 General MIDI 文件。它可以识别演奏的乐器，转录每个乐器，并命名和分配轨道，以便在 [kinesthesia](https://github.com/h4ks-com/kinesthesia) 中进行练习。
可作为 REST API 和 MCP 工具使用。
## 运行它
```bash
uv sync --extra dev
uv run python -m midifier # API 在 :8000 上，文档在 /docs
uv run python -m midifier mcp # MCP 服务器
```
启动时无需配置，结果写入 `./data`。
## 使用它
```bash
# 启动转录
curl -F 'file=@song.mp3' http://localhost:8000/v1/jobs
# {"id":"...","state":"queued"}
# 轮询它
curl http://localhost:8000/v1/jobs/<id>
```
一次只能运行一个任务，每个任务大约需要歌曲长度的三倍时间，因此任务采用轮询方式而不是等待。在任务等待时，`GET /v1/jobs/<id>` 会报告 `queue_ahead` 和 `eta_seconds`，而 `GET /v1/queue` 会报告服务的繁忙程度。估计值是根据已完成的任务而不是配置项来衡量的，因此它反映了运行该服务的硬件。
OpenAPI 模式在 `/openapi.json` 中。
## 保护它
服务仅持有 API 密钥的哈希值，因此读取部署的密钥不会让任何人调用它。生成一对密钥：
```bash
uv run python -m midifier keygen
```
将哈希值部署为 `MIDIFIER_API_KEY_HASH`，并将密钥提供给调用者。 如果没有配置哈希值，服务是开放的，这适合本地使用。
调用者可以通过以下三种方式之一提供密钥，具体取决于客户端的便捷性：
| 调用者 | 方式 |
|---|---|
| REST | `X-API-Key: <key>` |
| MCP over HTTP | `X-API-Key: <key>` 或 `Authorization: Bearer <key>` |
| MCP over stdio | `api_key` 工具参数 |
MCP 服务器从同一应用程序的 `/mcp` 提供，因此一个 URL 和一个密钥涵盖了两个接口，并且通过 MCP 启动的作业在 REST 上可见。
## 配置它
每个设置都是一个环境变量，前缀为 `MIDIFIER_`。请参阅 [`.env.example`](.env.example) 获取完整列表。重要的设置：
| 变量 | 默认值 | 说明 |
|---|---|---|
| `MIDIFIER_API_KEY_HASH` | 未设置 | 设置后，调用者必须提供密钥 |
| `MIDIFIER_STORAGE_BACKEND` | `local` | `local` 或 `s3` |
| `MIDIFIER_MINIO_BUCKET` | — | 配合其他 `MINIO_*` 值，用于 `s3` |
| `MIDIFIER_MODEL_SIZE` | `medium` | `small`、`medium` 或 `large` |
| `MIDIFIER_HF_TOKEN` | — | 下载转录权重所需 |
| `MIDIFIER_MAX_DURATION_SECONDS` | `360` | 接受的最长歌曲 |
| `MIDIFIER_MAX_CONCURRENT_JOBS` | `1` | 同时运行的转录 |
## 开发它
```bash
uv run pre-commit run --all-files # 所有文件 CI 运行
uv run pytest --cov # 测试，80% 门控
```
约定和管道背后的原因在 [AGENTS.md](AGENTS.md) 中。
## 许可证
MIT。 它下载的转录权重单独许可，不在此处重新分发。
