mcpField
A
Audiolla

Audiolla

本地服务
github.com/psyb0t媒体与设计51 周前更新
代码仓库

关于 Audiolla

Audiolla 是面向音频工程师、创作者和 Agent 工作流的可自托管音频处理 API。它在一个 Docker 容器中整合分析、编辑、修复、语音处理和 MIDI 工具，并支持异步任务与 Webhook。

主要功能

  1. 01音轨分离与母带处理
  2. 02BPM、调性、响度和结构分析
  3. 03音频修复与语音处理
  4. 04音频转 MIDI 及 MIDI 工具
  5. 05效果器、变换与批处理工作流
  6. 06异步任务与 Webhook 回调

适用场景

  1. 01分离音轨并处理母带
  2. 02分析 BPM、调性和响度以准备 DJ 曲目
  3. 03清理语音并识别说话者
  4. 04将音频转为 MIDI 并处理 MIDI 文件

MCP 相关

Audiolla 通过 MCP 端点向 LLM Agent 提供音频处理能力。生成音频的 MCP 工具使用暂存文件路径或输出 URL，而不是以 base64 返回音频。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "psyb0t-audiolla": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "docker.io/psyb0t/audiolla:v1.1.7"
      ]
    }
  }
}
启动命令docker run -i --rm docker.io/psyb0t/audiolla:v1.1.7

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
ocidocker.io/psyb0t/audiolla:v1.1.7

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

audiolla

CI version license Docker Pulls

三十种音频引擎。一个端口。零云端服务。即发即忘的异步任务。支持 Webhook。

你需要用 Demucs 分离音轨。接着用 librosa 分析 BPM 和调性。再用 basic-pitch 转录 MIDI。然后用 pyannote 进行说话人分离。再用 DeepFilterNet 增强语音。之后，你花了三天调试 Python 版本冲突，现在什么都不想干了。

audiolla 就是你不再这么折腾后得到的结果。

所有值得使用的音频处理工具，都封装在一个 HTTP API 中，运行于一个 Docker 容器。POST 一个文件，就能获得音频、JSON 或 MIDI。你可以通过 curl、shell 脚本、Python 笔记本、Makefile 使用它，也可以让大模型 Agent 连接 MCP 端点，尽情发挥。

无需账号，无需订阅，无需按分钟计费，也不会被供应商锁定。运行 docker run，就搞定了。

包含什么

🎛️ 音轨分离Demucs — htdemucs、微调版、6 音轨、MDX 变体
🎚️ 母带处理参考母带处理（matchering）+ 自定义效果器链
📊 分析BPM · 调性 · LUFS · 节拍 · 起音 · 旋律 · 结构片段
🎹 和弦 + 调性和弦检测 + Krumhansl-Schmuckler 调性估算
🎵 音频 → MIDI通过 Spotify 的 basic-pitch 进行复音转录（ONNX，无 TF）
🧹 修复通过 UVR BS-Roformer + MelBand Roformer 去混响 · 去回声 · 降噪
🗣️ 语音增强（DeepFilterNet）· VAD（silero-vad）· 说话人分离（pyannote）
🖼️ 可视化频谱图 + 波形 PNG + 8 种模式的动画 MP4/WebM
🔍 指纹Chromaprint 声学指纹（兼容 AcoustID）
✂️ 静音检测间隔 · 修剪边缘 · 删除所有静音
🎼 MIDI 工作流从 JSON 编曲 · 检查 · 转换 · 通过 fluidsynth 渲染
🎸 效果23 种效果的效果器链 — Compressor、Reverb、PitchShift、滤波器……
🔧 转换Sox DSP — 音高、速度、EQ、混响、增益
📢 响度测量 LUFS · 归一化至目标值
🥁 HPSS通过 librosa 中值滤波进行谐波/打击乐声源分离
🔇 降噪通过 noisereduce 进行频谱降噪 — 固定模式 + 自适应模式
⏩ 时间拉伸通过 librosa 相位声码器独立调整速度系数 + 移调
🏷️ 音频标记通过 Audio Spectrogram Transformer 获取 AudioSet 前 K 个类别标签
🔗 音频嵌入通过 LAION CLAP 生成 512 维语义嵌入 + 可选文本相似度
🏷️ 零样本分类通过 CLAP 余弦相似度与任意自由文本标签比对 — 流派、情绪、乐器
📋 音频信息ffprobe 元数据 — 时长、采样率、声道、编解码器、位深
✂️ 剪辑按起始/结束秒数剪切片段 — 支持任意格式输入和输出
🎚️ 混音合并 N 条分阶段音轨，并为每条音轨设置 gain_db — 纯 ffmpeg，无模型
🔗 拼接按顺序首尾拼接 N 个音频文件
⏩ 速度通过 ffmpeg atempo 更改播放速度而不移调（0.1× – 10×）
🔄 转换重新编码：一次调用即可设置格式、采样率、声道数
🔍 相似度通过 CLAP 嵌入计算两个音频文件之间的余弦相似度
🎹 MIDI 量化将 MIDI 音符时间对齐到节奏网格（16 分音符、8 分音符、四分音符……）
🌅 淡化淡入和/或淡出，提供 13 种曲线形状
⏪ 反转反向播放音频
🔁 循环将音频重复 N 次
🎯 BPM 匹配自动检测 BPM，然后拉伸至目标值 — 无需手动计算
📈 响度曲线随时间变化的 RMS 包络 — 带时间戳的 dB 数值，用于增益自动化
🎤 音高校正自动调音至最近的半音 — 可配置校正强度
🔧 修复去削波 + 去嗡声 — 修复削波峰值并移除电源线嗡声
🔁 循环点查找最佳无缝循环边界 — 评分、小节数、候选列表
🥁 鼓机步进音序器规格 → GM 鼓 MIDI — 16 步模式、摇摆、速度
🎼 和弦转 MIDI和弦进行 → MIDI 文件 — 每个片段采用根音+三音+五音配置
↔️ 立体声宽度通过 M/S 处理拓宽或收缩立体声像
✂️ 分割分割为 N 个等长部分或按静音分割 — 返回包含片段的 ZIP
🔊 声像将音频定位于立体声场中（-1 左 → 0 中 → 1 右）
🎚️ EQ参数均衡器 — 包含 freq/gain_db/width_hz 频段的 JSON 数组
🎵 调性匹配检测源调性，然后移调至目标调性
🎙️ 侧链闪避触发音轨（人声）音量较大时降低音乐音量
🏷️ 元数据通过 mutagen 读取和写入 ID3/Vorbis/FLAC/WAV 音频标签
🔴 削波检测检测数字削波 — 计数、比率、峰值 dBFS
↔️ 中/侧将 L/R 编码为 Mid+Side，或将 Mid+Side 解码为 L/R
✂️ 节拍切片在检测到的节拍位置切片音频 — 返回包含片段的 ZIP
🏟️ 卷积混响通过脉冲响应实现卷积混响 — 可控制 wet_mix
🥁 瞬态塑形器双压缩器，分别控制起音/延音 — 增强鼓声冲击力，削减房间混响尾音
🎚️ 多频段压缩带零相位 LR4 分频器的 N 频段压缩器 — 母带级动态处理
🎛️ DJ 准备一次调用：BPM + 调性 + Camelot 轮盘位置 + 综合 LUFS
📦 批处理依次对暂存文件运行 trim/convert/fade/reverse/speed/eq
🧩 预设 + 管线精选 YAML 工作流（master-for-spotify、podcast-cleanup 等）+ 服务端临时串联操作
🗂️ 目录GET /v1/catalog — 按类别分组、供发现使用的机器可读端点列表
⚡ 异步任务每个端点都支持 async_job=true — 即发即忘 + Webhook 回调

目录

运行

# no GPU
docker run --rm -it \
  -v $HOME/.audiolla-data:/data \
  -p 8000:8000 \
  psyb0t/audiolla:latest

# GPU
docker run --rm -it --gpus all \
  -v $HOME/.audiolla-data:/data \
  -e AUDIOLLA_DEVICE=cuda \
  -p 8000:8000 \
  psyb0t/audiolla:latest-cuda

容器启动时会预先下载 Demucs 权重（针对启用的变体），并缓存到 /data/torch_cache/。首次启动会下载；下次使用相同的 -v 挂载时，权重已就绪。其他引擎（matchering、pedalboard、librosa、sox、fx、midi）无需权重，/healthz 显示正常后即可使用。

从 v0.23.x 迁移至 v1.0.0

**v1.0.0 是一次会破坏兼容性的 API 发布。**所有现有客户端都会失效。新的接口形式如下：

  • 所有音频端点都接收 JSON 请求体（除 /v1/files 外，不再使用 multipart/form-data）
  • 输入使用 file_path（相对于 FILES_DIR 的路径）或 file_url（由服务端获取），二者必须且只能选其一。请先通过 PUT /v1/files/{path} 预先上传文件。
  • 输出必须使用 output_path 或 output_url，二者必须且只能选其一。响应中不再返回原始音频字节。
  • 异步路径：如果未提供任何输出参数，async_job=true 会自动将文件暂存到 jobs/{id}.{ext}。
  • 可生成音频的 MCP 工具不再提供 audio_base64（以及 midi_base64 / image_base64 / video_base64）。同样必须提供 output_path 或 output_url，且只能选其一。
  • openapi.yaml 现在是 API 契约，Pydantic 模型通过 make generate 从中重新生成。切勿手动编辑 src/audiolla/schema/_generated.py。
- curl -X POST http://localhost:8000/v1/audio/normalize \
-     -F "[email protected]" -F "target_lufs=-14" -o normalized.wav

+ # 1) stage the file (multipart only lives here now)
+ curl -X PUT --data-binary @track.wav \
+     -H 'Content-Type: application/octet-stream' \
+     http://localhost:8000/v1/files/uploads/track.wav

+ # 2) process via JSON body — response is JSON, not bytes
+ curl -X POST http://localhost:8000/v1/audio/normalize \
+     -H 'Content-Type: application/json' \
+     -d '{"file_path":"uploads/track.wav","target_lufs":-14,"output_path":"out/normalized.wav"}'

+ # 3) retrieve the result
+ curl -o normalized.wav http://localhost:8000/v1/files/out/normalized.wav

原因请参阅 v1.0.0 更新日志条目，了解完整说明。

快速开始

容器启动后，只需六条命令即可完成完整的音频处理流程（现在每个音频端点都使用 JSON 请求体；请先将输入文件暂存到 /v1/files/...）：

# stage your input file
curl -X PUT --data-binary @song.wav \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/song.wav

# rip the vocals out of a track
curl -X POST http://localhost:8000/v1/audio/separate \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/song.wav","engine":"htdemucs","stems":["vocals"],"output_path":"out/vocals.wav"}'
# → {"path":"out/vocals.wav","size":...,"output_format":"wav"}
curl -o vocals.wav http://localhost:8000/v1/files/out/vocals.wav

# what key is it in? what are the chords?
curl -X POST http://localhost:8000/v1/audio/chords \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/song.wav"}'
# → {"key":"F# minor","key_confidence":0.91,"chords":[{"chord":"F#m","start_sec":0.0,...},...]}

# transcribe that vocal melody to MIDI
curl -X PUT --data-binary @out/vocals.wav -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/vocals.wav  # only if not already staged
curl -X POST http://localhost:8000/v1/audio/to_midi/basic-pitch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocals.wav","output_path":"out/melody.mid"}'

# render the MIDI back to audio through a SoundFont
curl -X POST http://localhost:8000/v1/midi/render \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"out/melody.mid","output_path":"out/rendered.wav"}'

# strip background noise from a voice recording
curl -X POST http://localhost:8000/v1/audio/noise-reduce/uvr-denoise \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/interview.wav","output_path":"out/clean.wav"}'

# who's speaking and when?
curl -X POST http://localhost:8000/v1/audio/diarize/pyannote \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/interview.wav"}'
# → {"num_speakers":2,"segments":[{"speaker":"SPEAKER_00","start_sec":0.5,"end_sec":8.2},...]}

输入音频。输出 MIDI。检测和弦。识别说话人。降噪。重新合成。无需配置 Python 环境。无需 API 密钥。无需账号。只需 HTTP。

功能介绍

默认输出格式为 wav。在 JSON 请求体中添加 "output_format":"mp3" 即可改为输出 mp3（也支持 flac、opus、aac、pcm）。

每个音频端点都接收 application/json 请求体。仍使用 multipart 的唯一接口是 PUT /v1/files/{path}（用于暂存输入文件的原始字节）。

输入 — 每个音频端点都必须且只能提供以下其中一项：

  • file_path — /v1/files 暂存区内的路径（请先通过 PUT /v1/files/{path} 暂存文件）
  • file_url — 由服务端获取的远程 URL（默认禁用 — 请参阅远程 URL）

输出 — 可生成音频的端点必须且只能提供以下其中一项：

  • output_path — 服务端写入 /v1/files/<path>，并返回 JSON {"path":..., "size":..., ...}
  • output_url — 服务端通过 PUT 请求写入预签名 URL，并返回 JSON {"url":..., "size":..., ...}

仅用于分析的端点（返回 JSON 数据的端点，例如 /v1/audio/analyze、/v1/audio/loudness、/v1/audio/info）无需 output_path / output_url — 响应即为分析结果。

分离音轨
# stage input
curl -X PUT --data-binary @track.wav \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/track.wav

# vocals only
curl -X POST http://localhost:8000/v1/audio/separate \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","engine":"htdemucs","stems":["vocals"],"output_path":"out/vocals.wav"}'
curl -o vocals.wav http://localhost:8000/v1/files/out/vocals.wav

# all 4 stems as a ZIP
curl -X POST http://localhost:8000/v1/audio/separate \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","engine":"htdemucs","output_path":"out/stems.zip"}'
curl -o stems.zip http://localhost:8000/v1/files/out/stems.zip
母带处理
# stage track + reference
curl -X PUT --data-binary @track.wav -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/track.wav
curl -X PUT --data-binary @ref.wav -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/ref.wav

# match EQ + loudness to a reference track
curl -X POST http://localhost:8000/v1/audio/master \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","mode":"reference","reference_path":"uploads/ref.wav","output_path":"out/mastered.wav"}'
curl -o mastered.wav http://localhost:8000/v1/files/out/mastered.wav

# run a built-in pedalboard chain (presets: transparent, loud)
curl -X POST http://localhost:8000/v1/audio/master \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","mode":"chain","preset":"loud","output_path":"out/mastered.wav"}'
curl -o mastered.wav http://localhost:8000/v1/files/out/mastered.wav
分析
# returns JSON. features: bpm, key, loudness, duration,
# spectral_centroid, rms, zcr. Omit features to get them all.
curl -X POST http://localhost:8000/v1/audio/analyze \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","features":["bpm","key","loudness"]}'
节拍、起音、旋律和片段
# beat grid — returns bpm + beat timestamps
curl -X POST http://localhost:8000/v1/audio/beats \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'

# onset timestamps — note attacks, transients
curl -X POST http://localhost:8000/v1/audio/onsets \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'

# dominant melody contour — pitch in Hz per frame
curl -X POST http://localhost:8000/v1/audio/melody \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'

# structural segmentation — labels recurring sections A, B, C...
curl -X POST http://localhost:8000/v1/audio/segments \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","num_segments":6}'

启用 click_track=true 后，节拍检测还会生成节拍轨文件（设置 output_path 即可接收文件）——方便将混音与网格对齐。若已大致了解速度，可传入 start_bpm=140 作为跟踪器的初始值（速度更快、准确度更高）。设置 as_midi=true 和 output_path，即可将旋律导出为单轨 MIDI 文件。

静音检测与裁剪
# find silent gaps in a recording (no trim_mode → JSON only)
curl -X POST http://localhost:8000/v1/audio/silence \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","threshold_db":-30,"min_duration_sec":1.0}'

# trim all silence and stage the result
curl -X POST http://localhost:8000/v1/audio/silence \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","threshold_db":-30,"min_duration_sec":0.5,"trim_mode":"all","output_path":"out/trimmed.wav"}'
curl -o trimmed.wav http://localhost:8000/v1/files/out/trimmed.wav

# trim only leading/trailing silence
curl -X POST http://localhost:8000/v1/audio/silence \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","threshold_db":-40,"min_duration_sec":0.3,"trim_mode":"edges","output_path":"processed/trimmed.wav"}'

trim_mode=edges — 仅裁掉开头和结尾的静音。trim_mode=all — 移除检测到的所有间隔（压缩谈话录音、缩短循环片段）。若不设置 trim_mode，响应仅包含 JSON：silent_ranges、non_silent_ranges、duration — 无需提供 output_path / output_url。

可视化（频谱图、波形、视频）

可视化输出按输出类型分为两个子命名空间：

# Static PNG spectrogram (color + scale params)
curl -X POST http://localhost:8000/v1/audio/visualize/image/spectrogram \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","width":1280,"height":720,"output_path":"out/spec.png"}'
curl -o spec.png http://localhost:8000/v1/files/out/spec.png

# Static PNG waveform (color param)
curl -X POST http://localhost:8000/v1/audio/visualize/image/waveform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","width":1280,"height":240,"output_path":"out/wave.png"}'
curl -o wave.png http://localhost:8000/v1/files/out/wave.png

# Animated MP4 spectrum analyser (fps + container params)
curl -X POST http://localhost:8000/v1/audio/visualize/video/spectrum \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","width":1280,"height":720,"fps":30,"container":"mp4","output_path":"out/viz.mp4"}'
curl -o viz.mp4 http://localhost:8000/v1/files/out/viz.mp4

/image/spectrogram：生成 PNG（通过 output_path 暂存，或 PUT 到 output_url）。参数：width、height、color（默认为 intensity）、scale（log/lin）。

/image/waveform：生成 PNG。参数：width、height、color（默认为 lime）。

/video/{mode}：spectrum（滚动 FFT）、waves（示波器）、cqt（恒 Q 变换）、freqs（柱状图分析器）、volume（VU 表）、vectorscope（立体声 X/Y 示波器）、phasemeter、histogram。参数：width、height、fps、container（默认为 mp4，也可为 webm）。

声学指纹
# Chromaprint fingerprint — identifies a recording regardless of encoding
curl -X POST http://localhost:8000/v1/audio/fingerprint \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'
# → {"duration": 215.34, "fingerprint": "AQADtEqRRIuQ..."}

# include the raw integer array (for custom similarity scoring)
curl -X POST http://localhost:8000/v1/audio/fingerprint \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","return_raw":true}'

Base64 指纹字符串兼容 AcoustID 查询服务。

去混响、去回声、去噪

通过 UVR 生态系统模型进行 AI 音频修复——BS-Roformer 和 MelBand Roformer。这三种功能统一使用 POST /v1/audio/restore/{engine}。

# Remove room reverb (BS-Roformer, SDR 19+)
curl -X POST http://localhost:8000/v1/audio/restore/uvr-dereverb \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"out/dry.wav"}'

# Remove echo — normal mode
curl -X POST http://localhost:8000/v1/audio/restore/uvr-deecho \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"out/noecho.wav"}'

# Remove echo — aggressive mode (same engine, harder suppression)
curl -X POST http://localhost:8000/v1/audio/restore/uvr-deecho \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","aggressive":true,"output_path":"out/noecho.wav"}'

# Remove broadband background noise — ML (MelBand Roformer, SDR 28)
curl -X POST http://localhost:8000/v1/audio/restore/uvr-denoise \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"out/clean.wav"}'

均支持 output_format、output_path、output_url。如需基于 DSP 的降噪（无需 GPU），请使用 noise-reduce/noise-reduce。

UVR 引擎也可通过 /v1/audio/separate 使用——uvr-vocal-bsr（BS-Roformer，SDR 13）和 uvr-karaoke 会像 Demucs 一样返回人声和伴奏音轨，但音质通常更好。

音频转 MIDI 转录

通过 Spotify 的 basic-pitch（ONNX 后端，无需 TensorFlow）将复调音频转换为 MIDI。弹奏吉他、哼唱旋律、录制钢琴乐句——即可获得包含所有音符的 MIDI 文件。

# Any audio → MIDI file (staged)
curl -X POST http://localhost:8000/v1/audio/to_midi/basic-pitch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/guitar_riff.wav","output_path":"out/riff.mid"}'
curl -o riff.mid http://localhost:8000/v1/files/out/riff.mid

# Tune the detection thresholds
curl -X POST http://localhost:8000/v1/audio/to_midi/basic-pitch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/piano.wav","onset_threshold":0.6,"frame_threshold":0.3,"minimum_note_length_ms":80,"output_path":"out/piano.mid"}'

# Write directly to a different staging path
curl -X POST http://localhost:8000/v1/audio/to_midi/basic-pitch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"recordings/bass.wav","output_path":"midi/bass_notes.mid"}'
# → {"path":"midi/bass_notes.mid","size":...,"engine":"basic-pitch","output_format":"mid"}

可选参数：onset_threshold（0–1，默认值为 0.5）、frame_threshold（0–1，默认值为 0.3）、minimum_note_length_ms（默认值为 58）、minimum_frequency / maximum_frequency（Hz，默认不限制）、multiple_pitch_bends（布尔值，默认值为 false）、melodia_trick（布尔值，默认值为 true——有助于处理旋律内容）。默认引擎：basic-pitch。

MIDI 文件可直接传入 /v1/midi/inspect 或 /v1/midi/render——音频 → MIDI → 音频，实现完整往返转换。

神经网络语音和人声增强

DeepFilterNet DF3——一种基于深度学习的降噪技术，使用语音数据训练。对于语音录音，它比宽带降噪效果更好；专门处理人声时，它比 UVR 的降噪更加精准。

# Enhance a vocal recording
curl -X POST http://localhost:8000/v1/audio/enhance/deepfilter \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal_recording.wav","output_path":"out/enhanced.wav"}'
curl -o enhanced.wav http://localhost:8000/v1/files/out/enhanced.wav

# Stage the output as mp3
curl -X POST http://localhost:8000/v1/audio/enhance/deepfilter \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"vocals/raw.wav","output_format":"mp3","output_path":"vocals/enhanced.mp3"}'

支持 output_format、output_path、output_url。

生成音乐 + 音效

通过 POST /v1/audio/generate/{engine} 进行文本转音频生成。v1.0.0 提供 五种引擎，涵盖音乐和音效，各自具有不同的许可、VRAM 和声音特征——且均仅支持 CUDA。

# Stable Audio Open 1.0 — 47s cap, no vocals, great for loops + SFX
curl -X POST http://localhost:8000/v1/audio/generate/stable-audio-open \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"130 bpm tech house drum loop, punchy kick, crisp hats, no vocals","duration_sec":10,"seed":42,"output_path":"out/loop.wav"}'
curl -o loop.wav http://localhost:8000/v1/files/out/loop.wav

# MusicGen 300M — 30s cap, instrumental, CC-BY-NC (opt-in required)
curl -X POST http://localhost:8000/v1/audio/generate/musicgen-small \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"lo-fi hip-hop beat with vinyl crackle, 90 bpm","duration_sec":15,"output_path":"out/beat.wav"}'

# Riffusion — spectrogram-to-audio via Griffin-Lim, ~5s, lo-fi character
curl -X POST http://localhost:8000/v1/audio/generate/riffusion \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"ambient drone with metallic resonance","output_path":"out/drone.wav"}'

# AudioLDM 2 — general SFX (no opt-in gate, CC-BY 4.0 commercial-OK)
curl -X POST http://localhost:8000/v1/audio/generate/audioldm2 \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"heavy rain on a metal roof with distant thunder","duration_sec":10,"num_inference_steps":50,"output_path":"out/rain.wav"}'

引擎详情：

引擎许可最长时长VRAM（fp16）输出
stable-audio-openStability Community Licence（低于收入门槛时可用于商业用途）硬性上限为 47 s~12 GB44.1 kHz 立体声。循环、音效、氛围纹理——仅限器乐
musicgen-smallCC-BY-NC 4.0（仅限非商业用途——通过 AUDIOLLA_ENABLE_NONCOMMERCIAL=1 选择启用）硬性上限为 30 s~3 GB32 kHz 单声道。Meta MusicGen 300M，器乐
musicgen-mediumCC-BY-NC 4.0（需进行相同的选择启用）硬性上限为 30 s~6-8 GB32 kHz 单声道。质量高于 -small
riffusionCreativeML OpenRAIL-M（遵守许可中的使用限制时可用于商业用途）每次处理约 5 s~3 GB22.05 kHz 单声道。SD 风格的频谱图、Griffin-Lim 重建——具有 lo-fi / 循环感的特征
audioldm2CC-BY 4.0（可用于商业用途——无需选择启用）硬性上限为 30 s~8-10 GB（CPU 卸载）16 kHz 单声道。通用音效：氛围、拟音、动物、机械、撞击声。速度较慢（默认使用 200 步 DDIM；传入 num_inference_steps=50 可提速约 4 倍）

所有引擎均支持 async_job=true、webhook_url、output_path、output_url 和 seed，以便复现结果。stable-audio-open 和 audioldm2 还接受 num_inference_steps（以质量换取速度）。模型权重会在首次调用时下载到 HF_HOME（容器内默认为 /data/hf——五种引擎合计约 7 GB）。后续调用仅执行推理。五种引擎均标记为 cuda_only——非 CUDA 主机将收到 HTTP 400。

MusicGen 许可选择启用。 MusicGen 权重采用 CC-BY-NC 4.0 许可。引擎代码随镜像提供，但除非操作者在服务的环境中明确设置 AUDIOLLA_ENABLE_NONCOMMERCIAL=1，否则不会加载模型。matchering 也遵循相同模式（GPL v3）——镜像中包含受许可约束的代码，但只有在主动选择启用后才能实际使用。选择启用前，请阅读 MusicGen 权重许可。AudioLDM 2 采用 CC-BY 4.0 许可（允许商业用途，无需选择启用）——这是这组引擎中唯一无需切换任何标志即可安全用于商业用途的生成器。

延后至未来版本（已调研，但未在 v1.0.0 中提供）：

  • ACE-Step v1（3.5B，Apache 2.0，支持生成带人声的完整歌曲，最长 4 min）——需要来自 diffusers>=0.38 的 AceStepPipeline，而它本身又需要预发布版 safetensors。无法通过项目的哈希锁定供应链门槛。待 safetensors 0.8.x 发布稳定版后重新评估，或直接将 ACE-Step 的流水线纳入项目。
  • DiffRhythm full v1.2（Apache 2.0）——未打包的研究仓库（没有 setup.py / PyPI 发布）。待上游发布软件包，或将其纳入 thirdparty/ 后重新评估。
  • Stable Audio Open Small（Stability Community Licence，专用于音效，时长 11 s）——需要 stable-audio-tools，而它要求 python >=3.10, <3.11；audiolla 使用 Python 3.12，存在硬性不兼容。待 stable-audio-tools 放宽 Python 版本约束，或 diffusers 为其扩展出流水线后重新评估。
  • TangoFlux（ICLR 2026，44.1 kHz，30 s，速度快）——仅支持通过 git 安装（没有 PyPI 软件包）。可以在哈希锁定的供应链中固定 SHA；目前暂缓，以保持重型依赖栈仅使用 PyPI。
  • AudioGen（Meta，CC-BY-NC）——audiocraft==1.3.0 将 transformers<=4.31.0 固定为依赖，与 audiolla 的 4.51.3 存在硬性冲突。需要使用隔离的子进程 / sidecar 容器。
  • YuE 7B（Apache 2.0，支持生成带人声的完整歌曲）——fp16 需要 16-24 GB VRAM，不借助 int4 量化工具无法在 12 GB GPU 上运行。
和弦与调性检测

通过 librosa 实现 Krumhansl-Schmuckler 调性估算和基于色度模板的和弦分段。除 librosa 依赖栈外无需额外依赖。

curl -X POST http://localhost:8000/v1/audio/chords \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'
# → {
#     "key": "C major",
#     "key_confidence": 0.87,
#     "duration": 183.4,
#     "chords": [
#       {"chord": "C", "start_sec": 0.0, "end_sec": 2.3, "confidence": 0.91},
#       {"chord": "Am", "start_sec": 2.3, "end_sec": 4.6, "confidence": 0.85},
#       ...
#     ]
#   }

# Tune the hop length (lower = finer time resolution)
curl -X POST http://localhost:8000/v1/audio/chords \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","hop_length":256}'

可选参数：hop_length（默认值为 512）、segment_min_duration_sec（默认值为 0.5，用于合并非常短的和弦片段）。

语音活动检测

silero-vad——基于 ONNX 的 VAD，可快速、准确地检测语音和音乐。返回带时间戳的语音和非语音片段。

curl -X POST http://localhost:8000/v1/audio/vad \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/interview.wav"}'
# → {
#     "speech_ratio": 0.73,
#     "duration": 120.0,
#     "threshold": 0.5,
#     "speech_segments": [
#       {"start_sec": 1.2, "end_sec": 8.4},
#       ...
#     ],
#     "non_speech_segments": [
#       {"start_sec": 0.0, "end_sec": 1.2},
#       ...
#     ]
#   }

# Tighter detection
curl -X POST http://localhost:8000/v1/audio/vad \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/podcast.wav","threshold":0.7,"min_speech_duration_ms":300,"min_silence_duration_ms":200}'

可选参数：threshold（0–1，默认值为 0.5）、min_speech_duration_ms（默认值为 250）、min_silence_duration_ms（默认值为 100）。

说话人分离

pyannote/speaker-diarization-3.1——来自 HuggingFace Hub 的先进说话人分离方案。返回各说话人对应的带时间戳片段及说话人数。

**注意：**此引擎需要 HuggingFace 账户。你必须在 https://huggingface.co/pyannote/speaker-diarization-3.1 接受模型条款，然后在启动容器时设置 HF_TOKEN（或较早使用的别名 HUGGINGFACE_TOKEN——入口点会双向同步它们）。具有模型访问权限的只读令牌即可。接受 huggingface.co 上相应的许可协议后，同一令牌也可解锁受限的文本转音频引擎（stable-audio-open、musicgen-small、musicgen-medium）。

docker run ... \
  -e HF_TOKEN=hf_your_token_here \
  psyb0t/audiolla:latest

curl -X POST http://localhost:8000/v1/audio/diarize/pyannote \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/interview.wav"}'
# → {
#     "num_speakers": 2,
#     "speakers": ["SPEAKER_00", "SPEAKER_01"],
#     "duration": 120.0,
#     "segments": [
#       {"speaker": "SPEAKER_00", "start_sec": 0.5, "end_sec": 8.2, "duration_sec": 7.7},
#       {"speaker": "SPEAKER_01", "start_sec": 8.5, "end_sec": 14.1, "duration_sec": 5.6},
#       ...
#     ]
#   }

# Hint the expected speaker count
curl -X POST http://localhost:8000/v1/audio/diarize/pyannote \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/roundtable.wav","num_speakers":4}'

# Or constrain the range
curl -X POST http://localhost:8000/v1/audio/diarize/pyannote \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/panel.wav","min_speakers":2,"max_speakers":6}'

可选参数：num_speakers（说话人的精确数量提示）、min_speakers、max_speakers。

变换
# pitch shift up 2 semitones + add reverb, export mp3.
# operations is a JSON array — ops: gain, equalizer, compand, reverb,
# pitch, tempo, rate, channels, trim, pad.
curl -X POST http://localhost:8000/v1/audio/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","operations":[{"op":"pitch","params":{"n_semitones":2}},{"op":"reverb","params":{"reverberance":50}}],"output_format":"mp3","output_path":"out/out.mp3"}'
curl -o out.mp3 http://localhost:8000/v1/files/out/out.mp3
响度测量
# Measure integrated LUFS — returns JSON, no audio output
curl -X POST http://localhost:8000/v1/audio/loudness \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'
# → {"loudness_lufs": -18.4}
响度曲线

随时间变化的 RMS 包络——返回 {time_sec, rms_db} 点列表。可用于生成增益自动化曲线、查找响亮和安静的片段，或在母带处理前可视化动态范围。

# Default hop (512 samples) — fine-grained envelope
curl -X POST http://localhost:8000/v1/audio/loudness/curve \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}' | jq '.curve[:5]'
# → [
#     {"time_sec": 0.0,   "rms_db": -18.4},
#     {"time_sec": 0.012, "rms_db": -17.9},
#     ...
#   ]

# Coarser envelope (2048-sample hop)
curl -X POST http://localhost:8000/v1/audio/loudness/curve \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","hop_length":2048}' | jq '{duration, sample_rate, points}'

响应字段：curve（由 {time_sec, rms_db} 组成的数组）、duration（秒）、sample_rate、points（曲线总长度）。可选参数：hop_length（默认值为 512）。

响度归一化
# Normalize to -14 LUFS (streaming platform standard)
curl -X POST http://localhost:8000/v1/audio/normalize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","target_lufs":-14,"output_path":"out/normalized.wav"}'
curl -o normalized.wav http://localhost:8000/v1/files/out/normalized.wav

# Write to a different staging path
curl -X POST http://localhost:8000/v1/audio/normalize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","target_lufs":-23,"output_path":"mastered/norm.wav"}'

必须提供 target_lufs。响应 JSON 中的 loudness_lufs 为归一化前测得的响度，此外还包含 path / url / size。

HPSS（谐波/打击乐分离）

通过 librosa 使用中值滤波进行谐波/打击乐源分离。谐波 = 音调内容（有音高的乐器、铺底音）；打击乐 = 瞬态（鼓、打击乐器）。不使用 ML——纯 DSP，速度快，无需 GPU。

# Get both stems in a ZIP
curl -X POST http://localhost:8000/v1/audio/separate/hpss \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"out/stems.zip"}'
curl -o stems.zip http://localhost:8000/v1/files/out/stems.zip
# → stems.zip contains harmonic.wav + percussive.wav

# Wider margin = harder separation (more aggressive)
curl -X POST http://localhost:8000/v1/audio/separate/hpss \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","margin":3.0,"output_path":"out/stems.zip"}'

# Output to a different staging path
curl -X POST http://localhost:8000/v1/audio/separate/hpss \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"hpss/stems.zip"}'

参数：margin（默认值为 1.0——≥1.0，数值越大分离越强）、kernel_size（默认值为 31——奇数整数，中值滤波器宽度）、output_format（默认值为 wav）。

频谱降噪

同一端点提供两种引擎选项进行降噪——选择 DSP 可实现无需 GPU 的快速清理，选择 ML 可获得更高质量的降噪效果。

# DSP (noisereduce) — no GPU, pure spectral subtraction + Wiener filtering
curl -X POST http://localhost:8000/v1/audio/noise-reduce/noise-reduce \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","output_path":"out/clean.wav"}'

# Stationary mode — constant hum, hiss, fan noise
curl -X POST http://localhost:8000/v1/audio/noise-reduce/noise-reduce \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","stationary":true,"output_path":"out/clean.wav"}'

# Partial reduction — subtle noise floor cleanup
curl -X POST http://localhost:8000/v1/audio/noise-reduce/noise-reduce \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","prop_decrease":0.5,"output_path":"out/clean.wav"}'

# ML (UVR MelBand Roformer, SDR 28) — higher quality, GPU-accelerated
curl -X POST http://localhost:8000/v1/audio/noise-reduce/uvr-denoise \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","output_path":"out/clean.wav"}'

DSP 参数（仅适用于 noise-reduce 引擎）：stationary（布尔值，默认值为 false）、prop_decrease（0–1，默认值为 1.0）。两种引擎均接受 output_format、output_path、output_url。

时长拉伸与音高变换

通过 librosa 相位声码器独立调整速度因子和半音偏移。放慢曲目以便学习；将人声提高 3 个半音以变换调性；先将 MIDI 旋律移调到不同音区，再进行渲染。

# Slow down to 80% speed, no pitch change
curl -X POST http://localhost:8000/v1/audio/stretch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","tempo_factor":0.8,"output_path":"out/slow.wav"}'

# Shift up 3 semitones, no tempo change
curl -X POST http://localhost:8000/v1/audio/stretch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","pitch_semitones":3,"output_path":"out/pitched.wav"}'

# Both — pitch-corrected time stretch (traditional chipmunk effect)
curl -X POST http://localhost:8000/v1/audio/stretch \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","tempo_factor":0.5,"pitch_semitones":6,"output_format":"mp3","output_path":"out/stretched.mp3"}'

参数：tempo_factor（默认值为 1.0——0.5 = 半速）、pitch_semitones（默认值为 0.0——±半音）、output_format、output_path。

音高校正

使用 librosa 的相位声码器，将音频自动调至最近的半音。strength=1.0 会将音高强制对齐；较低的值则会混合校正后的信号与原始信号。

# Hard auto-tune — snap every note to the nearest semitone
curl -X POST http://localhost:8000/v1/audio/pitch-correct \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","output_path":"out/tuned.wav"}'

# Subtle correction — 50% blend
curl -X POST http://localhost:8000/v1/audio/pitch-correct \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","strength":0.5,"output_format":"mp3","output_path":"out/tuned.mp3"}'

# Async for long files, staged output
curl -X POST http://localhost:8000/v1/audio/pitch-correct \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"sessions/take1.wav","strength":1.0,"async_job":true,"output_path":"sessions/take1_tuned.wav"}'

参数：strength（0.0–1.0，默认值为 1.0）、output_format、output_path、async_job、webhook_url。需要 librosa-analyze 引擎。

修复

修复削波峰值和／或去除电源线嗡声。去削波使用三次插值重建被削平的波形顶部和底部。去嗡声会在 hum_freq（及其谐波）处应用陷波滤波器。

# Declip only (default)
curl -X POST http://localhost:8000/v1/audio/repair \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/overdriven.wav","output_path":"out/repaired.wav"}'

# Remove 60 Hz hum (North American power grid)
curl -X POST http://localhost:8000/v1/audio/repair \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","declip":false,"dehum":true,"hum_freq":60.0,"output_path":"out/clean.wav"}'

# Both — declip a 50 Hz humming mic recording
curl -X POST http://localhost:8000/v1/audio/repair \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/problem_track.wav","declip":true,"dehum":true,"hum_freq":50.0,"output_format":"flac","output_path":"out/repaired.flac"}'

参数：declip（布尔值，默认 true）、dehum（布尔值，默认 false）、hum_freq（Hz，默认 50.0）、output_format、output_path、async_job、webhook_url。

音频标注

通过 Audio Spectrogram Transformer（MIT/ast-finetuned-audioset-10-10-0.4593）对 AudioSet 类别标签进行 Top-K 分类。识别录音中的内容——音乐、语音、特定乐器、环境声音等。

curl -X POST http://localhost:8000/v1/audio/tag \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav"}'
# → {
#     "tags": [
#       {"label": "Music", "score": 0.94},
#       {"label": "Drum", "score": 0.87},
#       {"label": "Guitar", "score": 0.71},
#       ...
#     ],
#     "duration": 5.2
#   }

# Get top 20 results instead of the default 10
curl -X POST http://localhost:8000/v1/audio/tag \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/soundscape.wav","top_k":20}'

需要 HF 模型缓存。首次运行时会将权重下载到 /data/hf/。可选参数：top_k（默认 10）。

镜像默认设置为 HF_HUB_OFFLINE=0，因此首次调用时会延迟下载权重到 /data/hf/。对于网络访问受限的部署（无法向外连接），请先使用 huggingface-cli download <model> 将模型预下载到挂载的 /data/hf 卷，然后使用 -e HF_HUB_OFFLINE=1 启动容器。

音频嵌入

通过 LAION CLAP（laion/larger_clap_music_and_speech）生成 512 维 L2 归一化音频嵌入。适用于语义音频搜索、相似度评分和聚类。

# Get the embedding vector
curl -X POST http://localhost:8000/v1/audio/embed \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'
# → {"embedding": [0.032, -0.11, ...], "dim": 512, "norm": 1.0}

# Semantic similarity — how well does the audio match a text description?
curl -X POST http://localhost:8000/v1/audio/embed \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","query_text":"energetic rock guitar riff"}'
# → {"embedding": [...], "dim": 512, "norm": 1.0,
#    "query_text": "energetic rock guitar riff", "similarity": 0.73}

similarity 是 [-1, 1] 范围内的余弦相似度。需要 HF 模型缓存——与音频标注相同，首次运行时需要下载。

零样本分类

给定音频和一组自由文本标签，使用现有的 CLAP 模型返回每个标签的余弦相似度分数。无需下载额外模型——使用相同的 clap-embed 引擎。适用于流派、情绪、乐器、声音描述等 CLAP 能理解的任何内容。

# Genre detection
curl -X POST http://localhost:8000/v1/audio/classify \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","labels":["jazz","hip-hop","classical","electronic","rock"]}'
# → {"results": [
#     {"label": "hip-hop", "score": 0.42},
#     {"label": "electronic", "score": 0.38},
#     ...
#   ]}

# Mood / energy
curl -X POST http://localhost:8000/v1/audio/classify \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","labels":["energetic","calm","melancholic","aggressive","uplifting"]}'

# Speaker gender
curl -X POST http://localhost:8000/v1/audio/classify \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/interview.wav","labels":["male voice","female voice","child voice","multiple speakers"]}'

结果按分数降序排列。分数为 [-1, 1] 范围内的余弦相似度——分数越高，相似度越高。需要 clap-embed 模型缓存。

音频信息

使用 ffprobe 检查任意音频文件的元数据，无需将其加载到内存中进行处理。支持任何格式。

curl -X POST http://localhost:8000/v1/audio/info \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}'
# → {
#     "size_bytes": 52428800,
#     "duration_sec": 297.241,
#     "sample_rate": 44100,
#     "channels": 2,
#     "codec": "pcm_s16le",
#     "sample_fmt": "s16",
#     "format": "wav",
#     "bit_depth": 16,
#     "bit_rate": 1411200
#   }

# Works on any staged file
curl -X POST http://localhost:8000/v1/audio/info \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"recordings/interview.mp3"}'
# → {"codec": "mp3", "bit_rate": 192000, ...}
裁剪

从任意音频文件中精确截取指定时间范围。常见用途：提取副歌、剪辑采样片段，或按小节边界切分分轨。

# Extract seconds 30–90 from a track
curl -X POST http://localhost:8000/v1/audio/trim \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","start_sec":30.0,"end_sec":90.0,"output_path":"out/chorus.wav"}'

# Clip a specific beat range, export as mp3
curl -X POST http://localhost:8000/v1/audio/trim \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/stem.wav","start_sec":0.0,"end_sec":8.0,"output_format":"mp3","output_path":"out/loop.mp3"}'

# From staged file, write to a different staging path
curl -X POST http://localhost:8000/v1/audio/trim \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"sessions/full.wav","start_sec":120.5,"end_sec":180.0,"output_path":"clips/verse.wav"}'

start_sec 默认为 0。必须指定 end_sec，且其值必须大于 start_sec。支持所有标准的 output_format 值。

混音

将多个已暂存或可通过 URL 访问的音轨合并为一个。每条音轨的 gain_db 可用于在混音前平衡音量。适用于以自定义音量将分离的分轨重新混合、叠加合成器声部，或合并节拍器音轨与音乐。

# Mix drums and bass at equal levels
curl -X POST http://localhost:8000/v1/audio/mix \
  -H 'Content-Type: application/json' \
  -d '{"tracks":[{"file_path":"stems/drums.wav"},{"file_path":"stems/bass.wav"}],"output_path":"out/rhythm.wav"}'

# Stems at custom levels (drums -3 dB, bass 0 dB, vocals +2 dB)
curl -X POST http://localhost:8000/v1/audio/mix \
  -H 'Content-Type: application/json' \
  -d '{"tracks":[
    {"file_path":"stems/drums.wav","gain_db":-3},
    {"file_path":"stems/bass.wav","gain_db":0},
    {"file_path":"stems/vocals.wav","gain_db":2}
  ],"output_format":"wav","output_path":"out/custom_mix.wav"}'

# Write to a different staging path
curl -X POST http://localhost:8000/v1/audio/mix \
  -H 'Content-Type: application/json' \
  -d '{"tracks":[{"file_path":"stems/harmonic.wav"},{"file_path":"stems/percussive.wav","gain_db":-6}],"output_path":"mixed/recombined.wav"}'

tracks 是必需的 JSON 数组。每个条目都需要 file_path 或 file_url，并可选填 gain_db（默认 0.0）。至少需要 2 条音轨。较短的音轨会以静音补齐至最长音轨的时长。

拼接

按顺序拼接 N 个音频文件。自动处理不同的采样率和声道数（ffmpeg 会即时重采样）。

curl -X POST http://localhost:8000/v1/audio/concat \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"file_path":"intro.wav"},{"file_path":"verse.wav"},{"file_path":"outro.wav"}],"output_path":"out/full_track.wav"}'

# output_format change + different staging path
curl -X POST http://localhost:8000/v1/audio/concat \
  -H 'Content-Type: application/json' \
  -d '{"files":[{"file_path":"a.wav"},{"file_path":"b.wav"}],"output_format":"mp3","output_path":"concat/result.mp3"}'

files 是必需的 {file_path?, file_url?} 对象 JSON 数组。至少需要 2 个条目。

速度

改变播放速度而不改变音高——适用于以半速／双倍速试听，或制作慢动作效果。使用 ffmpeg atempo 滤镜链处理极端倍数。

# Half speed
curl -X POST http://localhost:8000/v1/audio/speed \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","speed":0.5,"output_path":"out/slow.wav"}'

# Double speed
curl -X POST http://localhost:8000/v1/audio/speed \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","speed":2.0,"output_path":"out/fast.wav"}'

# 4× speed (chains two atempo=2.0 filters internally)
curl -X POST http://localhost:8000/v1/audio/speed \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","speed":4.0,"output_format":"mp3","output_path":"out/fast.mp3"}'

必须指定 speed。范围：0.1–10.0。注意：这会改变时长，但不会改变音高。若要在保持音高的同时改变速度，请使用 /v1/audio/stretch。

转换

通过一次调用将音频重新编码为其他格式、采样率或声道数。

# WAV → 16 kHz mono FLAC (for speech models)
curl -X POST http://localhost:8000/v1/audio/convert \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","output_format":"flac","sample_rate":16000,"channels":1,"output_path":"out/prepared.flac"}'

# Stereo → mono WAV
curl -X POST http://localhost:8000/v1/audio/convert \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stereo.wav","channels":1,"output_path":"out/mono.wav"}'

# Any format → Opus at 48 kHz
curl -X POST http://localhost:8000/v1/audio/convert \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/audio.mp3","output_format":"opus","sample_rate":48000,"output_path":"out/out.opus"}'

output_format 默认为 wav。sample_rate 和 channels 为可选参数；如果省略，则保留源文件的值。

相似度

使用 CLAP 嵌入计算两个音频文件之间的余弦相似度。返回 [-1, 1] 范围内的分数——1 = 声音相同，0 = 不相关，负值 = 声学上相反。适用于重复文件检测、翻唱匹配，或在音频库中查找最相似的采样。

curl -X POST http://localhost:8000/v1/audio/similar \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/original.wav","reference_file_path":"uploads/remix.wav"}'
# → {"similarity": 0.847, "dim": 512}

# Different staged paths
curl -X POST http://localhost:8000/v1/audio/similar \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stems/vocals.wav","reference_file_path":"stems/vocals_ref.wav"}'

主文件：file_path / file_url。参考文件：reference_file_path / reference_file_url。需要 clap-embed 引擎。

MIDI 量化

将 MIDI 文件中的所有音符时间吸附到最近的节奏网格。相比 /v1/midi/transform 的 quantize_grid_beats 参数，这是一个更简洁的专用端点。

# Quantize to 16th notes (0.25 beats)
curl -X POST http://localhost:8000/v1/midi/quantize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/sloppy.mid","grid_beats":0.25,"output_path":"out/tight.mid"}'

# 8th note grid
curl -X POST http://localhost:8000/v1/midi/quantize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"recorded.mid","grid_beats":0.5,"output_path":"midi/quantized.mid"}'

grid_beats：以拍为单位的网格大小——0.25 = 16 分音符，0.5 = 8 分音符，1.0 = 四分音符。默认值：0.25。

淡入淡出

应用淡入、淡出或两者兼有。提供 13 种曲线形状：tri、qsin、esin、hsin、log、ipar、qua、cub、squ、cbr、par、exp、lin。

# 2s fade-in
curl -X POST http://localhost:8000/v1/audio/fade \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","fade_in":2.0,"output_path":"out/faded.wav"}'

# 3s fade-out with exponential curve
curl -X POST http://localhost:8000/v1/audio/fade \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","fade_out":3.0,"curve":"exp","output_path":"out/faded.wav"}'

# Both — 1s in, 2s out
curl -X POST http://localhost:8000/v1/audio/fade \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","fade_in":1.0,"fade_out":2.0,"output_path":"out/faded.wav"}'

fade_in / fade_out 至少有一项必须大于 0。

反转

通过 ffmpeg areverse 将音频倒放。

curl -X POST http://localhost:8000/v1/audio/reverse \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/sample.wav","output_path":"out/reversed.wav"}'

curl -X POST http://localhost:8000/v1/audio/reverse \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stems/vocals.wav","output_format":"mp3","output_path":"out/reversed.mp3"}'
循环

将音频重复 N 次。使用 ffmpeg aloop 滤镜——每次迭代都无需重新编码。

# Play 4 times total
curl -X POST http://localhost:8000/v1/audio/loop \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/beat.wav","count":4,"output_path":"out/looped.wav"}'

# 8-bar loop → 32 bars
curl -X POST http://localhost:8000/v1/audio/loop \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stems/drums.wav","count":4,"output_path":"loops/drums32.wav"}'

count 必须 ≥ 2（总播放次数，而非额外循环次数）。

BPM 匹配

通过 librosa 检测源 BPM，然后进行时间拉伸以匹配目标 BPM——无需手动计算。

# Stretch anything to 128 BPM
curl -X POST http://localhost:8000/v1/audio/bpm-match \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loop.wav","target_bpm":128,"output_path":"out/matched.wav"}'

# Match tempo and also shift pitch
curl -X POST http://localhost:8000/v1/audio/bpm-match \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loop.wav","target_bpm":140,"pitch_semitones":2,"output_path":"out/matched.wav"}'

响应 JSON 除了暂存的 path / url，还包含 source_bpm、target_bpm 和 tempo_factor。需要 librosa-analyze 和 stretch 引擎。

立体声宽度

通过 M/S 处理拓宽或收窄立体声声像。width=0.0 → 单声道，1.0 → 原始宽度，>1.0 → 更宽。也适用于单声道输入（会先升混）。

# Widen to 1.5×
curl -X POST http://localhost:8000/v1/audio/stereo-width \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mix.wav","width":1.5,"output_path":"out/wide.wav"}'

# Collapse to mono
curl -X POST http://localhost:8000/v1/audio/stereo-width \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mix.wav","width":0.0,"output_path":"out/mono.wav"}'

# Subtle narrowing for mix bus
curl -X POST http://localhost:8000/v1/audio/stereo-width \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"master/mix.wav","width":0.8,"output_path":"master/narrow.wav"}'

范围：[0.0, 3.0]。

分割

将文件分割成多个片段。支持两种模式：equal（分成 N 个等时长片段）或 silence（按安静间隙分割）。返回包含编号文件的 ZIP。

# Split into 4 equal parts
curl -X POST http://localhost:8000/v1/audio/split \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","mode":"equal","count":4,"output_path":"out/segments.zip"}'

# Split a DJ mix on silence
curl -X POST http://localhost:8000/v1/audio/split \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/djmix.wav","mode":"silence","threshold_db":-40,"min_duration_sec":1.0,"output_path":"out/tracks.zip"}'

# Split to mp3
curl -X POST http://localhost:8000/v1/audio/split \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/album.flac","mode":"equal","count":10,"output_format":"mp3","output_path":"out/parts.zip"}'

mode=equal 要求 count >= 2。mode=silence 使用 threshold_db（默认值为 -30）和 min_duration_sec（默认值为 0.5）；需要 silence-detect 引擎。

声像

将音频定位到立体声场中。适用于单声道和立体声输入。

# Hard left
curl -X POST http://localhost:8000/v1/audio/pan \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","position":-1.0,"output_path":"out/left.wav"}'

# Slight right (e.g. guitar in mix)
curl -X POST http://localhost:8000/v1/audio/pan \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stems/guitar.wav","position":0.4,"output_path":"out/guitar_panned.wav"}'

# Center (no-op but valid)
curl -X POST http://localhost:8000/v1/audio/pan \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mono.wav","position":0.0,"output_path":"out/stereo.wav"}'

position：-1.0 = 全左，0.0 = 居中，1.0 = 全右。

均衡器

通过 ffmpeg equalizer 滤镜进行参数均衡。可传入任意数量的频段，每个频段包含中心频率、增益和可选带宽。

# Low-cut + presence boost
curl -X POST http://localhost:8000/v1/audio/eq \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","bands":[{"freq":100,"gain_db":-6,"width_hz":80},{"freq":3000,"gain_db":3,"width_hz":500}],"output_path":"out/eq.wav"}'

# Single band: cut 60 Hz hum
curl -X POST http://localhost:8000/v1/audio/eq \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/recording.wav","bands":[{"freq":60,"gain_db":-20,"width_hz":30}],"output_path":"out/clean.wav"}'

每个频段：freq（Hz，必填）、gain_db（dB，必填，范围 ±30）、width_hz（可选，默认值为 100）。

调性匹配

通过 CLAP 和弦分析检测源调性，然后移调到目标调性——一次调用即可，无需分两步操作。

# Shift everything to C major
curl -X POST http://localhost:8000/v1/audio/key-match \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loop.wav","target_key":"C","output_path":"out/matched.wav"}'

# Match to F# (response includes source_key + semitones shifted)
curl -X POST http://localhost:8000/v1/audio/key-match \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"stems/melody.wav","target_key":"F#","output_path":"matched/melody_fsharp.wav"}'

target_key：根音，例如 C、F#、Bb、D#。调式后缀（major / minor / m）会被忽略——移调时只考虑根音。需要 chord-detect 和 stretch 引擎。

侧链压低

当触发音轨（人声）音量较大时，压低主音轨（音乐）——经典的人声旁白配乐效果。纯 ffmpeg sidechaincompress 处理，无需模型。

# stage music + voice first via PUT /v1/files/...

curl -X POST http://localhost:8000/v1/audio/sidechain-duck \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/music.wav","trigger_file_path":"uploads/voice.wav","threshold_db":-20,"ratio":4,"attack_ms":10,"release_ms":200,"output_path":"out/ducked.wav"}'

# Aggressive duck for podcast-style music bed
curl -X POST http://localhost:8000/v1/audio/sidechain-duck \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"music/bed.wav","trigger_file_path":"voice/narration.wav","threshold_db":-30,"ratio":10,"release_ms":400,"output_path":"final/mix.wav"}'

当触发音轨超过 threshold_db 时，主音轨会被压缩。ratio 设置压缩强度。为获得最佳效果，两个文件时长应相同；较短的触发音轨会用静音补齐。

效果器链

按顺序应用一系列 pedalboard 效果器——提供完整目录，可自行选择顺序和参数。不同于 /v1/audio/master（后者运行预设母带处理链）。

# Compress, then add reverb, then drop -3 dB
curl -X POST http://localhost:8000/v1/audio/fx \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","effects":[
    {"type":"Compressor","params":{"threshold_db":-18,"ratio":4.0}},
    {"type":"Reverb","params":{"room_size":0.5,"wet_level":0.3}},
    {"type":"Gain","params":{"gain_db":-3.0}}
  ],"output_path":"out/out.wav"}'

允许使用的效果器：Compressor、Limiter、NoiseGate、Gain、Clipping、Distortion、Bitcrush、Reverb、Chorus、Delay、Phaser、PitchShift、HighShelfFilter、LowShelfFilter、PeakFilter、HighpassFilter、LowpassFilter、LadderFilter、IIRFilter、GSMFullRateCompressor、MP3Compressor、Resample、Invert、Convolution。

VST3 / AudioUnit / 外部插件不在允许列表中——它们会加载任意原生代码。

循环点

在音频文件中找到最佳的无缝循环边界——audiolla 会分析节拍网格，并返回循环时不会产生咔嗒声或间隙的起始和结束位置。

# Find best loop boundary (default: minimum 4 bars)
curl -X POST http://localhost:8000/v1/audio/loop-point \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/beat.wav"}' | jq '{loop_start_sec, loop_end_sec, bars, score, tempo_bpm}'
# → {"loop_start_sec": 0.0, "loop_end_sec": 7.44, "bars": 4,
#    "score": 0.94, "tempo_bpm": 128.0, "candidates": [...]}

# Require at least 8 bars, return top 3 candidates
curl -X POST http://localhost:8000/v1/audio/loop-point \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/long_track.wav","min_loop_bars":8,"num_candidates":3}'

响应字段：loop_start_sec、loop_end_sec、bars、score（0–1，数值越高表示循环越紧密）、tempo_bpm、candidates（按排名排序的备选项数组）。可选参数：min_loop_bars（默认值为 4）、num_candidates（默认值为 5）。需要 librosa-analyze 引擎。

编写 MIDI

POST 一个 JSON 歌曲规格，即可获取 Standard MIDI File 字节。你可以手动编写规格、从音序器 / DAW / sequencer 生成、用 Python 笔记本编写脚本生成，或让 LLM 生成——audiolla 都不在意。服务器端不会运行 AI；规格本身就是音乐。

# 4-beat C major arpeggio at 120 BPM, piano + kick drum
curl -X POST http://localhost:8000/v1/midi/compose \
  -H 'Content-Type: application/json' \
  -d '{
    "tempo_bpm": 120,
    "tracks": [
      {"name":"Lead","program":0,"channel":0,"notes":[
        {"pitch":60,"start_beats":0.0,"duration_beats":0.5,"velocity":100},
        {"pitch":64,"start_beats":0.5,"duration_beats":0.5,"velocity":100},
        {"pitch":67,"start_beats":1.0,"duration_beats":0.5,"velocity":100},
        {"pitch":72,"start_beats":1.5,"duration_beats":0.5,"velocity":100}
      ]},
      {"name":"Kick","program":0,"channel":9,"notes":[
        {"pitch":36,"start_beats":0.0,"duration_beats":0.1,"velocity":110},
        {"pitch":36,"start_beats":1.0,"duration_beats":0.1,"velocity":110},
        {"pitch":36,"start_beats":2.0,"duration_beats":0.1,"velocity":110},
        {"pitch":36,"start_beats":3.0,"duration_beats":0.1,"velocity":110}
      ]}
    ],
    "output_path": "midi/song.mid"
  }'
curl -o song.mid http://localhost:8000/v1/files/midi/song.mid

# Use a JSON spec file (must include output_path / output_url in the body)
curl -X POST http://localhost:8000/v1/midi/compose \
  -H 'Content-Type: application/json' \
  -d @spec.json

规格字段：tempo_bpm（默认 120）、time_signature（默认 [4,4]）、key_signature（可选，例如 "C"、"Am"）、ticks_per_beat（默认 480）、tracks[].{name, program, channel, volume, pan, notes[].{pitch, start_beats, duration_beats, velocity}}。时间单位为拍。program 是 GM 乐器编号 0-127。通道 9 是 GM 鼓通道——该通道上的音高对应鼓组音色（36 = 底鼓，38 = 军鼓，42 = 闭合踩镲，等等）。

检查 MIDI
# read the structure of any Standard MIDI File
curl -X POST http://localhost:8000/v1/midi/inspect \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid"}'
# → {type, ticks_per_beat, tempo_changes, time_signatures,
#    tracks[{name, note_on_count, channels, programs, length_beats}], ...}
转换 MIDI
# transpose all non-drum tracks up an octave
curl -X POST http://localhost:8000/v1/midi/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","transpose_semitones":12,"output_path":"midi/transposed.mid"}'

# override tempo to 140 BPM and save to staging
curl -X POST http://localhost:8000/v1/midi/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","tempo_bpm":140,"output_path":"midi/fast.mid"}'

# drop the drum track (channel 9)
curl -X POST http://localhost:8000/v1/midi/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","drop_channels":[9],"output_path":"midi/no-drums.mid"}'

# keep only channels 0 and 1
curl -X POST http://localhost:8000/v1/midi/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","keep_channels":[0,1],"output_path":"midi/two-ch.mid"}'

# quantize to 1/16th notes
curl -X POST http://localhost:8000/v1/midi/transform \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","quantize_grid_beats":0.25,"output_path":"midi/quantized.mid"}'

transpose_semitones 的范围为 ±48。quantize_grid_beats 以拍为单位（0.25 = 4/4 拍中的 1/16 音符）。keep_channels 和 drop_channels 接受通道编号的 JSON 数组；每次请求只能设置其中一个。

将 MIDI 渲染为音频
# Synthesise via the bundled FluidR3_GM SoundFont
curl -X POST http://localhost:8000/v1/midi/render \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","output_format":"wav","output_path":"out/song.wav"}'
curl -o song.wav http://localhost:8000/v1/files/out/song.wav

# Use your own SoundFont (must be staged first)
curl -X PUT --data-binary @my.sf2 \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/sf/orchestral.sf2
curl -X POST http://localhost:8000/v1/midi/render \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/song.mid","soundfont_path":"sf/orchestral.sf2","output_format":"flac","output_path":"out/orch.flac"}'
根据规格生成音乐

一次调用即可完成编曲 + 渲染——输入规格，生成音频文件。

# spec.json must include "output_path" or "output_url" alongside the composition fields
curl -X POST http://localhost:8000/v1/midi/generate \
  -H 'Content-Type: application/json' \
  -d @spec.json
curl -o song.wav http://localhost:8000/v1/files/out/song.wav
鼓点模式

步进音序器规格 → GM 鼓 MIDI。为每种鼓声部定义由 0/1 步值组成的数组来描述节奏模式；服务会将其映射到 GM 通道 9 音高，并生成 MIDI 文件。可选的摇摆参数会调整偶数编号的 16 分音符步进，营造摇摆感。

# 4-on-the-floor kick, snare on 2&4, busy hi-hat — 2 bars at 120 BPM
curl -X POST http://localhost:8000/v1/midi/drum \
  -H "Content-Type: application/json" \
  -d '{
    "tempo_bpm": 120,
    "steps": 16,
    "bars": 2,
    "swing": 0.0,
    "pattern": {
      "kick":  [1,0,0,0,1,0,0,0,1,0,0,0,1,0,0,0],
      "snare": [0,0,0,0,1,0,0,0,0,0,0,0,1,0,0,0],
      "hihat": [1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1]
    },
    "output_path": "midi/beat.mid"
  }'
curl -o beat.mid http://localhost:8000/v1/files/midi/beat.mid

# Swing groove — 0.1 = subtle, 0.5 = strong shuffle
curl -X POST http://localhost:8000/v1/midi/drum \
  -H "Content-Type: application/json" \
  -d '{
    "tempo_bpm": 95,
    "steps": 16,
    "bars": 1,
    "swing": 0.2,
    "pattern": {
      "kick":  [1,0,0,1,0,0,1,0,1,0,0,1,0,0,1,0],
      "snare": [0,0,0,0,1,0,0,0,0,0,0,0,1,0,0,0],
      "hihat": [1,0,1,0,1,0,1,0,1,0,1,0,1,0,1,0]
    },
    "output_path": "midi/groove.mid"
  }'

请求体字段：tempo_bpm（默认 120）、steps（每小节的步数，默认 16）、bars（默认 1）、swing（0.0–0.5，默认 0.0）、pattern（对象——键为鼓声部名称，值为 0/1 数组）。支持的声部：kick、snare、hihat、open_hihat、ride、crash、clap、tom_hi、tom_mid、tom_low、rim、cowbell。需要 midi-compose 引擎。

将和弦转换为 MIDI

从音频文件中检测和弦进行，并将每个片段转换为 MIDI 和弦（根音 + 三音 + 五音）。适用于将检测出的和弦谱导出为可演奏的 MIDI、为编曲重新配和弦，或为 DAW 会话提供起始素材。

# Audio → chord MIDI at the detected tempo
curl -X POST http://localhost:8000/v1/audio/chords-to-midi \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav","output_path":"out/chords.mid"}'

# Override tempo, set velocity and octave
curl -X POST http://localhost:8000/v1/audio/chords-to-midi \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/song.wav","tempo_bpm":120,"velocity":90,"octave":3,"output_path":"out/chords.mid"}'

# Stage the output under a different path
curl -X POST http://localhost:8000/v1/audio/chords-to-midi \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"sessions/song.wav","output_path":"midi/song_chords.mid"}'

可选参数：tempo_bpm（默认：从音频中检测）、velocity（1–127，默认 80）、octave（0–8，默认 4）、output_path。需要 chord-detect 引擎。每个和弦片段都会生成一个 MIDI 和弦事件（根音 + 大三度 / 小三度 + 纯五度，时长 = 片段长度）。

音频元数据标签

通过 mutagen 读取和写入 ID3（MP3）、Vorbis（OGG/FLAC）和 WAV/M4A 标签。需要 metadata 引擎。

# Read tags
curl -X POST http://localhost:8000/v1/audio/metadata \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.mp3"}' | jq '{title, artist, bpm, key, duration_sec}'

# Write tags — returns updated tag set
curl -X POST http://localhost:8000/v1/audio/metadata \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.mp3","tags":{"title":"My Track","artist":"DJ Audiolla","bpm":"128","year":"2026"}}'
削波检测

检测数字削波。无需引擎——纯 numpy 运算。

curl -X POST http://localhost:8000/v1/audio/clip-detect \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loud_master.wav"}' | jq '{clipped, clip_count, clip_ratio, peak_db}'
# → {"clipped":true,"clip_count":4219,"clip_ratio":0.0048,"peak_db":0.0}
Mid/Side 编码和解码

将 L/R 立体声编码为 Mid+Side，或解码还原。无需改动 pedalboard 链即可调整立体声宽度。

# Encode L/R → M/S
curl -X POST http://localhost:8000/v1/audio/mid-side \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/stereo.wav","mode":"encode","output_path":"out/ms_encoded.wav"}'

# Decode back to L/R
curl -X POST http://localhost:8000/v1/audio/mid-side \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"out/ms_encoded.wav","mode":"decode","output_path":"out/restored.wav"}'
按节拍切片

使用 librosa 检测节拍位置，并返回包含按编号命名的 WAV/MP3 切片的 ZIP 文件——每个节拍间隔一个文件。

curl -X POST http://localhost:8000/v1/audio/beat-slice \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loop.wav","output_format":"wav","output_path":"out/slices.zip"}'
curl -o slices.zip http://localhost:8000/v1/files/out/slices.zip
# → slices.zip: beat_001.wav, beat_002.wav, beat_003.wav …

# Stage the ZIP at a different path
curl -X POST http://localhost:8000/v1/audio/beat-slice \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/loop.wav","output_path":"beats/loop_slices.zip"}'
# → {"path":"beats/loop_slices.zip","beat_count":32,...}
卷积混响

通过 pedalboard 的 Convolution 将脉冲响应（IR）应用于音频。任何 WAV 文件都可用作 IR。

# Upload your IR first
curl -X PUT --data-binary @plate_reverb.wav \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/ir/plate.wav

# Apply — wet_mix: 0.0=dry only, 1.0=wet only
curl -X POST http://localhost:8000/v1/audio/conv-reverb \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/dry_vocal.wav","ir_file_path":"ir/plate.wav","wet_mix":0.25,"output_format":"wav","output_path":"out/reverbed.wav"}'
瞬态塑形器

混合起音 / 延音双压缩器。正值 attack_gain_db 可让鼓声更有冲击力；负值 sustain_gain_db 可削减房间混响尾音。

# Punchy drums: boost attack, cut sustain
curl -X POST http://localhost:8000/v1/audio/transient \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/drums.wav","attack_gain_db":6,"sustain_gain_db":-4,"output_path":"out/punchy_drums.wav"}'

# Soft attack (pad-like)
curl -X POST http://localhost:8000/v1/audio/transient \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/synth.wav","attack_gain_db":-6,"sustain_gain_db":0,"output_path":"out/softened.wav"}'
多频段压缩

将信号分为 N+1 个频段，并分别压缩。频段通过零相位、等效于 LR4 的分频器进行分割，因此旁通后的链路能还原原始信号。这是母带工程师常用的工具——可收敛低音冲击而不压扁人声齿音、平衡繁杂的中频，等等。

# 3-band mastering pass: low/mid/high
curl -X POST http://localhost:8000/v1/audio/multiband-compress \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mixdown.wav","crossovers_hz":[200,3000],"bands":[
    {"threshold_db":-18,"ratio":4,"attack_ms":15,"release_ms":150,"makeup_db":1.5},
    {"threshold_db":-14,"ratio":3,"attack_ms":8, "release_ms":80, "makeup_db":1.0},
    {"threshold_db":-10,"ratio":2,"attack_ms":3, "release_ms":40, "makeup_db":0.5}
  ],"output_path":"out/mastered.wav"}'

crossovers_hz 的长度为 N，bands 的长度为 N+1。每个频段需要 threshold_db 和 ratio，可选 attack_ms（默认 10）、release_ms（默认 100）、makeup_db（默认 0）。

DJ 准备

一次调用即可返回 DJ 了解一首曲目所需的全部信息。需要 librosa-analyze + chord-detect。有响度引擎可用时会报告 LUFS。

curl -X POST http://localhost:8000/v1/audio/dj-prep \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/track.wav"}' | jq .
# → {"bpm":128.0,"key":"A minor","camelot":"8A","integrated_lufs":-9.4}

Camelot 调性轮上的位置可帮助你快速找到混音时在和声上兼容的曲目。

去齿音

分频段高频去齿音器——衰减高于 frequency_hz 的齿音，不影响信号的其他部分。使用 Butterworth HPF、包络跟随器和逐通道增益衰减实现。无需引擎。

# Default settings (threshold -20 dB, 6 kHz, 4:1 ratio)
curl -X POST http://localhost:8000/v1/audio/deess \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","output_path":"out/deessed.wav"}'

# Gentle pass on a mix
curl -X POST http://localhost:8000/v1/audio/deess \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mix.wav","threshold_db":-15,"frequency_hz":7000,"ratio":2.5,"output_path":"out/mix_deessed.wav"}'

# Stage output under a different path
curl -X POST http://localhost:8000/v1/audio/deess \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/vocal.wav","output_path":"sessions/vocal_deessed.wav"}'
# → {"path":"sessions/vocal_deessed.wav","threshold_db":-20.0,"frequency_hz":6000.0,"ratio":4.0,...}

可选参数：threshold_db（≤ 0，默认 -20）、frequency_hz（2000–15000，默认 6000）、ratio（1.0–20.0，默认 4.0）、output_format（wav/mp3/flac…）、output_path。

立体声场分析

测量立体声宽度、相位相关性、中/侧平衡和单声道兼容性。无需引擎——纯 numpy 实现。

curl -X POST http://localhost:8000/v1/audio/stereo-field \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/stereo_mix.wav"}' | jq .
# → {
#     "correlation": 0.72,       # Pearson L/R correlation [-1,1]
#     "width": 0.41,             # side_rms / mid_rms
#     "balance_db": -0.3,        # L vs R level difference
#     "mono_compatible": true,   # correlation >= 0.5
#     "mid_level_db": -12.1,
#     "side_level_db": -18.4,
#     "phase_issues": false,
#     "channels": 2,
#     "sample_rate": 44100,
#     "duration": 210.5
#   }

# Analyze a different staged file
curl -X POST http://localhost:8000/v1/audio/stereo-field \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"masters/track.wav"}' | jq '{correlation, width, mono_compatible}'

单声道文件会返回 correlation=1.0、width=0.0、mono_compatible=true。如果 correlation < 0，则应视为相位抵消素材的危险信号，因为这类素材在单声道播放时会发生塌缩。

音频缩略片段

提取音频文件中能量最高的片段——即给定窗口内起始事件密度最高的段落。适用于生成预览片段、播客预告或 DJ 提示点。需要 librosa-analyze。

# Default 30-second thumbnail
curl -X POST http://localhost:8000/v1/audio/thumbnail \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/long_track.wav","output_path":"out/preview.wav"}'

# 10-second teaser
curl -X POST http://localhost:8000/v1/audio/thumbnail \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/podcast.wav","duration_sec":10,"output_format":"mp3","output_path":"out/teaser.mp3"}'

# Stage + get timestamps
curl -X POST http://localhost:8000/v1/audio/thumbnail \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/album_track.wav","duration_sec":20,"output_path":"previews/track_thumb.wav"}'
# → {"path":"previews/track_thumb.wav","start_sec":47.3,"end_sec":67.3,"duration_sec":20.0,...}

可选参数：duration_sec（1–300，默认 30）、output_format、output_path。设置 output_path 后，响应 JSON 会包含 start_sec 和 end_sec，以便准确获知缩略片段在源文件中的提取位置。

MIDI 人性化处理

为 MIDI 文件添加细微的时间和力度变化，让听感不那么机械。抖动均匀分布；提供 seed 时，结果完全确定。需要 midi-compose。

# Gentle humanize with defaults (±10 ms timing, ±10% velocity)
curl -X POST http://localhost:8000/v1/midi/humanize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/rigid.mid","output_path":"midi/human.mid"}'

# Heavier feel with a fixed seed for reproducible results
curl -X POST http://localhost:8000/v1/midi/humanize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/drums.mid","timing_ms":20,"velocity_pct":15,"seed":42,"output_path":"midi/drums_human.mid"}'

# Stage output under a different path
curl -X POST http://localhost:8000/v1/midi/humanize \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"midi/pattern.mid","timing_ms":8,"output_path":"midi/pattern_human.mid"}'
# → {"path":"midi/pattern_human.mid","timing_ms":8.0,"velocity_pct":10.0,...}

可选参数：timing_ms（0–500，默认 10）、velocity_pct（0–50，默认 10）、seed（任意整数，可选）、output_path。非 MIDI 输入会返回 400。需要 midi-compose。

批量操作

通过一次 HTTP 调用，对已暂存文件执行多项操作。操作按顺序执行；即使前面的操作失败，每项操作也都会有独立的结果条目。

支持的操作：convert、normalize、trim、fade、reverse、speed、eq。

# Stage input
curl -X PUT http://localhost:8000/v1/files/work/track.wav --data-binary @track.wav

# Batch: trim, convert to MP3, reverse in one call
curl -X POST http://localhost:8000/v1/batch \
  -H "Content-Type: application/json" \
  -d '[
    {"op":"trim","file_path":"work/track.wav","output_path":"work/chorus.wav","start_sec":30,"end_sec":60},
    {"op":"convert","file_path":"work/track.wav","output_path":"work/track.mp3","output_format":"mp3"},
    {"op":"reverse","file_path":"work/track.wav","output_path":"work/reversed.wav"}
  ]' | jq '.results[].status'
# → "ok" "ok" "ok"
异步任务和 Webhook

每个音频端点都接受 async_job=true——请求会立即返回任务 ID，任务在后台执行。可轮询状态或注册 Webhook。

# Pre-stage input (one-time)
curl -X PUT --data-binary @track.wav \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/track.wav

# Submit async with staging path — result written to /v1/files/stems/...
curl -X POST http://localhost:8000/v1/audio/separate \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path":"uploads/track.wav",
    "engine":"htdemucs",
    "stems":["vocals"],
    "async_job":true,
    "webhook_url":"https://my-server.com/hooks/audio",
    "output_path":"stems/track-vocals.wav"
  }'
# → {"job_id":"abc123","status":"pending","status_url":"/v1/jobs/abc123"}

# Submit async with presigned S3 PUT URL — result uploaded on completion
curl -X POST http://localhost:8000/v1/audio/master \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path":"uploads/track.wav",
    "mode":"chain",
    "preset":"transparent",
    "async_job":true,
    "output_url":"https://bucket.s3.amazonaws.com/result.wav?X-Amz-..."
  }'
# → {"job_id":"def456","status":"pending","status_url":"/v1/jobs/def456"}

# Poll
curl http://localhost:8000/v1/jobs/abc123 | jq '{status, duration_sec, result}'

# List all jobs (optional ?status=pending|running|completed|failed|cancelled)
curl http://localhost:8000/v1/jobs

# Cancel a running job
curl -X DELETE http://localhost:8000/v1/jobs/abc123

Webhook 负载（任务完成时 POST 到你的 URL）：

{
  "id": "abc123",
  "endpoint": "/v1/audio/separate",
  "status": "completed",
  "duration_sec": 12.4,
  "result": {"path": "stems/track-vocals.wav", "size": 3145728, ...}
}

投递最多尝试 4 次，采用指数退避（0 秒、1 秒、2 秒、4 秒）。已完成的任务会在内存中保留 AUDIOLLA_JOB_TTL 秒（默认 1 小时），之后会被清理。

暂存文件

/v1/files 下的简易服务端文件存储。支持上传、列出、下载和删除。

默认情况下，暂存的输入和输出文件会在 24 小时后过期。将 AUDIOLLA_FILES_TTL 改为时长，例如 48h 或 86400 秒；设为 0 则禁用清理。从 v1 升级时，如果必须让现有文件永久保留，请在启动新镜像前设置 AUDIOLLA_FILES_TTL=0。文件时效从最后一次写入开始计算，而不是从最后一次读取开始计算。清理器每隔 AUDIOLLA_SWEEPER_INTERVAL 秒运行一次，并会等待活动请求、下载和后台任务完成；即使 CPU 和 CUDA 容器共享 /data，也会如此。持续的活动可能会推迟清理。模型缓存、符号链接和 .part 文件不会被清理。请在文件过期前下载需要保留的内容。任务元数据保留时间（AUDIOLLA_JOB_TTL）与文件保留时间分开计算。

# upload
curl -X PUT http://localhost:8000/v1/files/mytrack.wav \
  --data-binary @track.wav

# list
curl http://localhost:8000/v1/files

# download
curl http://localhost:8000/v1/files/mytrack.wav -o copy.wav

# delete
curl -X DELETE http://localhost:8000/v1/files/mytrack.wav

文件暂存后，可在任何音频端点通过 file_path 参数引用该文件路径：

# Analyze a staged file
curl -X POST http://localhost:8000/v1/audio/analyze \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"mytrack.wav","features":["bpm"]}'

# Separate stems and write the result back to staging
curl -X POST http://localhost:8000/v1/audio/separate \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path":"mytrack.wav",
    "engine":"htdemucs",
    "stems":["vocals"],
    "output_path":"stems/mytrack-vocals.wav"
  }'
# → {"path":"stems/mytrack-vocals.wav","size":...,"output_format":"wav",...}
远程 URL

默认禁用。若要允许服务获取 file_url 或 PUT 到 output_url，请在容器启动时设置策略：

docker run ... \
  -e AUDIOLLA_FETCH_MODE=allowlist \
  -e AUDIOLLA_FETCH_HOSTS="*.s3.amazonaws.com,*.r2.cloudflarestorage.com" \
  psyb0t/audiolla:latest

然后：

# Fetch from S3, master, PUT result back to a presigned S3 URL
curl -X POST http://localhost:8000/v1/audio/master \
  -H 'Content-Type: application/json' \
  -d '{
    "file_url":"https://my-bucket.s3.amazonaws.com/in.wav",
    "reference_url":"https://my-bucket.s3.amazonaws.com/ref.wav",
    "mode":"reference",
    "output_url":"https://my-bucket.s3.amazonaws.com/out.wav?X-Amz-Signature=..."
  }'
# → {"url":"...","size":...,"output_format":"wav",...}

策略模式：

  • disabled（默认）— 拒绝 file_url / output_url，返回 400
  • allowlist — 仅允许与 AUDIOLLA_FETCH_HOSTS 匹配的主机
  • denylist — 允许除列出主机之外的所有主机（与 AUDIOLLA_FETCH_ALLOW_PRIVATE=false 配合使用，以屏蔽私有 IP / 元数据服务）

始终启用的保护措施：

  • 拒绝解析到私有 / 环回 / 链路本地 IP 的 DNS（可切换）
  • 默认仅允许 https；通过 AUDIOLLA_FETCH_SCHEMES 可选择启用 http
  • 重定向会通过相同策略重新验证
  • 硬性超时 + 大小上限 = AUDIOLLA_MAX_UPLOAD_BYTES
  • 记录每个获取 / 上传 URL

所有 AUDIOLLA_FETCH_* 环境变量，请参见配置。

引擎

标识功能
htdemucs4 轨分离：鼓、贝斯、其他、人声。速度与质量之间的最佳平衡。
htdemucs_ft同样分离为 4 轨，使用微调后的权重。质量更高，速度约慢 4 倍。仅限 CUDA——在 CPU 镜像上会返回 400 错误。
htdemucs_6s6 轨分离——还会拆分出吉他和钢琴。实验性功能。
mdx_extra人声隔离效果出色。基于 MUSDB 训练，采用不同架构。
matchering基于参考音轨进行母带处理：使 EQ 和响度与参考音轨匹配。
pedalboard-chain通过 pedalboard 使用预设母带处理链——transparent（轻度处理）或 loud（4:1 压缩）。为 /v1/audio/master 提供 mode=chain 支持。要使用任意处理链，请使用 fx-chain / /v1/audio/fx。
librosa-analyze通过 librosa 分析 BPM、调性、LUFS、时长、频谱特征、节拍网格、起始点检测、旋律（pyin）和结构分段。
sox-transform通过 pysox 调整增益、EQ、压缩、混响、移调和速度。
fx-chain任意 pedalboard 效果链——完整效果目录，可自定顺序和参数。为 /v1/audio/fx 提供支持。
midi-composeJSON 规范 → MIDI 字节。也可检查和转换现有 MIDI 文件。为 /v1/midi/{compose,inspect,transform,generate} 提供支持。
midi-render通过 fluidsynth 和 SoundFont 将 MIDI 转为音频。为 /v1/midi/render 和 /v1/midi/generate 提供支持。
silence-detect通过 ffmpeg silencedetect 定位静音片段。可选择自动修剪。为 /v1/audio/silence 提供支持。
ffmpeg-render通过 ffmpeg 滤镜生成静态 PNG 频谱图/波形图，以及 8 种模式的动态 MP4/WebM 视频。为 /v1/audio/visualize/image/* 和 /v1/audio/visualize/video/{mode} 提供支持。
audio-fingerprint通过 fpcalc 生成 Chromaprint 声学指纹。为 /v1/audio/fingerprint 提供支持。
uvr-dereverbBS-Roformer 去混响——移除房间混响；primary_stem=No Reverb。
uvr-deechoVR Architecture 去回声——提供普通和强力模式；设置 aggressive=true 可加强抑制。
uvr-denoiseMelBand Roformer 降噪（SDR 28）——移除宽带背景噪声。
uvr-karaokeMelBand Roformer 卡拉 OK——移除主唱，保留伴奏；通过 /v1/audio/separate 使用。
uvr-vocal-bsrBS-Roformer 人声/伴奏分离（SDR 13）——最高质量的人声分离；通过 /v1/audio/separate 使用。
basic-pitch通过 Spotify basic-pitch（ONNX 后端）将复音音频转换为 MIDI。为 /v1/audio/to_midi 提供支持。
deepfilter通过 DeepFilterNet DF3 增强语音和人声。为 /v1/audio/enhance 提供支持。
chord-detect通过 librosa 检测和弦和调性——使用 Krumhansl-Schmuckler 估算调性，并通过色度模板进行和弦分段。为 /v1/audio/chords 提供支持。
silero-vad通过 silero-vad（ONNX）检测语音活动——返回带时间戳和语音比例的语音/非语音片段。为 /v1/audio/vad 提供支持。
pyannote通过 pyannote/speaker-diarization-3.1 进行说话人分离——返回带时间戳的逐说话人片段。需要 HUGGINGFACE_TOKEN。为 /v1/audio/diarize 提供支持。
stretch通过 librosa 相位声码器进行时间拉伸和移调——可分别设置速度因子和半音偏移量。为 /v1/audio/stretch 提供支持。
ast-tag通过 Audio Spectrogram Transformer（MIT/ast-finetuned-audioset-10-10-0.4593）进行音频标记——返回排名靠前的 K 个 AudioSet 类别标签。需要 HF 模型缓存。为 /v1/audio/tag 提供支持。
clap-embed通过 LAION CLAP（laion/larger_clap_music_and_speech）生成 512 维 L2 归一化音频嵌入——用于语义音频搜索。需要 HF 模型缓存。为 /v1/audio/embed 提供支持。
hpss通过 librosa HPSS 中值滤波进行谐波/打击乐声源分离——以 ZIP 文件形式返回谐波和打击乐音轨。为 /v1/audio/separate/hpss 提供支持。
noise-reduce通过 noisereduce 进行频谱降噪——提供稳态（恒定嗡嗡声/嘶嘶声）和非稳态（自适应）模式，无需 GPU。为 /v1/audio/noise-reduce/noise-reduce 提供支持。
metadata通过 mutagen 读取/写入音频标签（MP3 使用 ID3，OGG/FLAC 使用 Vorbis，WAV 使用 INFO，M4A 使用 MP4）。无需 ML 权重。为 /v1/audio/metadata 提供支持。
stable-audio-open文本转音频——Stability Stable Audio Open 1.0。Stability Community Licence（低于收入门槛时可用于商业用途；请阅读许可证）。硬性时长上限为 47 秒；适合循环乐段、即兴乐句、氛围音效、SFX 和鼓点。不含人声。fp16 下约需 12 GB VRAM——仅限 CUDA。为 /v1/audio/generate/stable-audio-open 提供支持。
musicgen-small文本转音乐——Meta MusicGen 300M。CC-BY-NC 4.0（仅限非商业用途；需在服务端环境中通过 AUDIOLLA_ENABLE_NONCOMMERCIAL=1 选择启用）。硬性时长上限为 30 秒；仅支持器乐。fp16 下约需 3 GB VRAM——仅限 CUDA。为 /v1/audio/generate/musicgen-small 提供支持。
musicgen-medium文本转音乐——Meta MusicGen 1.5B。CC-BY-NC 4.0（同样需选择启用）。硬性时长上限为 30 秒；质量高于 -small。fp16 下约需 6-8 GB VRAM——仅限 CUDA。为 /v1/audio/generate/musicgen-medium 提供支持。
riffusion文本转音乐——Riffusion-v1，是一种用于生成频谱图的 Stable Diffusion 微调模型（通过 Griffin-Lim 将频谱图转换为音频）。CreativeML OpenRAIL-M（遵守许可证中的使用限制即可用于商业用途）。每次处理约需 5 秒，音质带有 lo-fi 特点，采样率为 22.05 kHz，单声道。fp16 下约需 3 GB VRAM——仅限 CUDA。为 /v1/audio/generate/riffusion 提供支持。
audioldm2文本转音频/SFX——AudioLDM 2（cvssp/audioldm2）。CC-BY 4.0（可用于商业用途——无需选择启用，是此系列中唯一可安全用于商业用途的生成器）。适用于通用 SFX：环境氛围、动物声音、拟音、机械/撞击声。16 kHz 单声道，最长 30 秒。速度较慢（默认使用 200 步 DDIM——传入 num_inference_steps=50 可牺牲质量以换取约 4 倍速度）。fp16 下使用 CPU 卸载约需 8-10 GB VRAM。仅限 CUDA。为 /v1/audio/generate/audioldm2 提供支持。
每个 Demucs 变体都有自己的检查点（托管在 dl.fbaipublicfiles.com 上）。入口点会在启动时将所有已启用的变体预先下载到 /data/torch_cache/，这样首次分离请求就不会卡在下载环节。

AUDIOLLA_ENABLED_ENGINES——限制可用的引擎。AUDIOLLA_PRELOAD——在启动时将指定引擎载入内存，而不是等到收到第一个请求时再加载。

工作流——预设 + 流水线

两种在服务端串联操作的方式，无需在调用之间重新上传音频：

精选预设——位于 presets/ 中的服务端 YAML 工作流。通过一次 POST 运行：

# Pre-stage input
curl -X PUT --data-binary @mix.wav \
  -H 'Content-Type: application/octet-stream' \
  http://localhost:8000/v1/files/uploads/mix.wav

# Master a mix for Spotify (-14 LUFS) — multiband compress + normalise
curl -X POST http://localhost:8000/v1/presets/master-for-spotify \
  -H 'Content-Type: application/json' \
  -d '{"file_path":"uploads/mix.wav","output_path":"out/mastered.wav"}'
# → {"path":"out/mastered.wav","size":...,"steps":[...]}
curl -o mastered.wav http://localhost:8000/v1/files/out/mastered.wav

# List available presets
curl http://localhost:8000/v1/presets | jq '.data[] | {name, description}'

# Inspect a preset's steps before running
curl http://localhost:8000/v1/presets/podcast-cleanup | jq '.steps'

随附预设：master-for-spotify（3 段母带处理 + -14 LUFS）、podcast-cleanup（DeepFilterNet + 去齿音 + -16 LUFS）、vocal-cleanup（UVR 去混响 + 降噪 + 去齿音 + 轻度压缩）。将自己的预设作为 YAML 文件添加到 presets/ 中。

临时流水线——在一次调用中串联任意已注册的操作：

# Restore + multiband + normalise in one request — intermediates stay
# server-side, no re-upload between steps.
curl -X POST http://localhost:8000/v1/pipeline \
  -H 'Content-Type: application/json' \
  -d '{
    "file_path":"uploads/track.wav",
    "output_path":"out/pipelined.wav",
    "steps":[
      {"op":"restore","params":{"engine":"uvr-denoise"}},
      {"op":"multiband_compress","params":{
        "crossovers_hz":[200,3000],
        "bands":[
          {"threshold_db":-18,"ratio":3},
          {"threshold_db":-14,"ratio":2.5},
          {"threshold_db":-10,"ratio":2}
        ]
      }},
      {"op":"normalize","params":{"target_lufs":-14}}
    ]
  }'
# → {"path":"out/pipelined.wav","size":...,"steps":[...]}

# Discover available ops
curl http://localhost:8000/v1/ops | jq .

流水线和预设端点的响应都包含 steps 日志，方便审查已执行的操作。与其他所有音频生成端点一样，这两个端点也支持 async_job=true、output_path 和 output_url。

API 目录

GET /v1/catalog 返回按类别分组的所有端点的机器可读列表（separation、restoration、dynamics、eq-spatial、mastering、time-pitch、editing、analysis、effects-creative、visualize、midi、metadata、workflow、speech、files、jobs、management）。可将其用于发现；LLM Agent 和代码生成脚本都会使用它。

curl http://localhost:8000/v1/catalog | jq '.categories[] | {name, endpoint_count: (.endpoints | length)}'

端点

完整的线路协议：openapi.yaml。

音频处理

每个端点都接受 JSON 请求体。输入必须且只能选择 file_path （FILES_DIR 下预先放置的文件）或 file_url（由服务端获取的 HTTPS URL）。音频生成端点还必须且只能选择 output_path （服务端将结果写入 FILES_DIR）或 output_url（预签名 PUT——服务端上传编码后的字节）。两者都未提供 → 400；两者都已设置 → 400。响应始终为 JSON——不返回原始音频字节、不包含 Content-Disposition: attachment，也不包含 *_base64 字段。

方法路径默认返回内容
POST/v1/audio/separateJSON {path|url, size, ...} — 单个音轨；多音轨（或全部音轨）以 ZIP 流的形式返回，通过 output_path/output_url 获取
POST/v1/audio/masterJSON {path|url, size, output_format, ...}
POST/v1/audio/analyzeJSON — BPM、调性、LUFS、频谱特征
POST/v1/audio/beatsJSON — BPM + 节拍时间戳；可选点击音轨 WAV
POST/v1/audio/onsetsJSON — 起音时间戳
POST/v1/audio/melodyJSON — 主旋律轮廓；可选导出 MIDI
POST/v1/audio/segmentsJSON — 结构片段标签（A、B、C…）
POST/v1/audio/silenceJSON — 静音/非静音区间；可选裁剪后的音频
POST/v1/audio/visualize/image/spectrogramJSON {path|url, size, ...} — 静态 PNG 频谱图（color、scale 参数）
POST/v1/audio/visualize/image/waveformJSON {path|url, size, ...} — 静态 PNG 波形图（color 参数）
POST/v1/audio/visualize/video/{mode}JSON {path|url, size, ...} — 动态 MP4/WebM 视频（8 种模式：spectrum、waves、cqt、…）
POST/v1/audio/fingerprintJSON — Chromaprint 指纹字符串
POST/v1/audio/restore/{engine}JSON {path|url, size, output_format, ...} — 去除混响/回声/噪声；aggressive=true 可启用 uvr-deecho 强力模式
POST/v1/audio/to_midi/{engine}JSON {path|url, size, ...} — 复音转录（MIDI）
POST/v1/audio/enhance/{engine}JSON {path|url, size, output_format, ...} — 神经网络语音/人声增强
POST/v1/audio/generate/{engine}JSON {path|url, size, output_format, ...} — 文本转音频（engine = stable-audio-open / musicgen-small / musicgen-medium / riffusion / audioldm2）；必需提供 prompt，可选提供 duration_sec / seed / lyrics / num_inference_steps
POST/v1/audio/chordsJSON — 检测到的调性和和弦进行
POST/v1/audio/vadJSON — 带时间戳的语音/非语音片段及语音占比
POST/v1/audio/diarize/{engine}JSON — 按说话人划分的带时间戳片段
POST/v1/audio/transformJSON {path|url, size, output_format, ...}
POST/v1/audio/loudnessJSON — {loudness_lufs}（仅测量，不返回音频）
POST/v1/audio/loudness/curveJSON — {curve:[{time_sec,rms_db}],duration,sample_rate,points}；hop_length 参数
POST/v1/audio/normalizeJSON {path|url, size, measured_lufs, ...} — 必须提供 target_lufs；归一化前的 LUFS 会报告在 measured_lufs 字段中
POST/v1/audio/separate/hpssJSON {path|url, size, ...} — ZIP 流，包含 harmonic.<fmt> + percussive.<fmt>
POST/v1/audio/noise-reduce/{engine}JSON {path|url, size, output_format, ...} — engine=noise-reduce（DSP，stationary/prop_decrease）或 uvr-denoise（ML）
POST/v1/audio/stretchJSON {path|url, size, output_format, ...}
POST/v1/audio/pitch-correctJSON {path|url, size, output_format, ...} — strength [0.0–1.0]；需要 librosa-analyze
POST/v1/audio/repairJSON {path|url, size, output_format, ...} — declip 布尔值、dehum 布尔值、hum_freq Hz
POST/v1/audio/tagJSON — 带置信度分数的 AudioSet 前 K 个标签
POST/v1/audio/embedJSON — 512 维嵌入；提供 query_text 时还会返回余弦相似度
POST/v1/audio/classifyJSON — {results: [{label, score}]}，按降序排列；需要 clap-embed
POST/v1/audio/infoJSON — 时长、sample_rate、声道数、编解码器、bit_depth、格式
POST/v1/audio/trimJSON {path|url, size, output_format, ...} — 必须提供 start_sec + end_sec
POST/v1/audio/mixJSON {path|url, size, output_format, ...} — 必须提供 tracks JSON 数组（≥2 个条目）
POST/v1/audio/concatJSON {path|url, size, output_format, ...} — 必须提供 files JSON 数组（≥2 个条目）
POST/v1/audio/speedJSON {path|url, size, output_format, ...} — 必须提供 speed 浮点数（0.1–10.0）
POST/v1/audio/convertJSON {path|url, size, output_format, ...} — 转换格式/sample_rate/声道数
POST/v1/audio/similarJSON — {similarity, dim}；需要 clap-embed
POST/v1/audio/fadeJSON {path|url, size, output_format, ...} — fade_in/fade_out 秒数，13 种 curve 选项
POST/v1/audio/reverseJSON {path|url, size, output_format, ...} — 反转播放方向
POST/v1/audio/loopJSON {path|url, size, output_format, ...} — count 总播放次数（≥2）
POST/v1/audio/bpm-matchJSON {path|url, size, output_format, ...} — 必须提供 target_bpm；需要 librosa-analyze + stretch
POST/v1/audio/stereo-widthJSON {path|url, size, output_format, ...} — width [0.0–3.0]；M/S 立体声处理
POST/v1/audio/splitJSON {path|url, size, ...} — ZIP 流；mode=equal（需要 count）或 mode=silence
POST/v1/audio/panJSON {path|url, size, output_format, ...} — position [-1.0–1.0]
POST/v1/audio/eqJSON {path|url, size, output_format, ...} — bands JSON 数组，每项为 {freq, gain_db, width_hz}
POST/v1/audio/key-matchJSON {path|url, size, output_format, ...} — 必须提供 target_key；需要 chord-detect + stretch
POST/v1/audio/sidechain-duckJSON {path|url, size, output_format, ...} — 主音频 + trigger_file_*；ffmpeg sidechaincompress
POST/v1/audio/fxJSON {path|url, size, output_format, ...}
POST/v1/audio/metadataJSON — 标签字段（标题、艺人、BPM、调性、时长、sample_rate…）；提供 tags JSON 时写入标签
POST/v1/audio/clip-detectJSON — 是否削波、削波次数、削波比例、峰值 dB、时长（秒）
POST/v1/audio/mid-sideJSON {path|url, size, output_format, ...} — mode=encode（L/R→M/S）或 mode=decode（M/S→L/R）
POST/v1/audio/beat-sliceJSON {path|url, size, ...} — 编号节拍切片的 ZIP 流；需要 librosa-analyze
POST/v1/audio/conv-reverbJSON {path|url, size, output_format, ...} — 必须提供 ir_file_path / ir_file_url；wet_mix [0.0–1.0]
POST/v1/audio/transientJSON {path|url, size, output_format, ...} — attack_gain_db + sustain_gain_db
POST/v1/audio/multiband-compressJSON {path|url, size, output_format, ...} — N 段压缩器；crossovers_hz + bands JSON 数组
POST/v1/audio/dj-prepJSON — BPM、调性、Camelot 调性代码、integrated_lufs；需要 librosa-analyze + chord-detect
POST/v1/audio/loop-pointJSON — {loop_start_sec,loop_end_sec,bars,score,tempo_bpm,candidates}；需要 librosa-analyze
POST/v1/audio/chords-to-midiJSON {path|url, size, ...} — 从音频提取和弦进行（MIDI）；需要 chord-detect
POST/v1/audio/deessJSON {path|url, size, output_format, ...} — 分频段削弱齿音；threshold_db、frequency_hz、ratio
POST/v1/audio/stereo-fieldJSON — {correlation, width, balance_db, mono_compatible, mid_level_db, side_level_db, phase_issues, …}
POST/v1/audio/thumbnailJSON {path|url, size, start_sec, end_sec, ...} — 能量最高的 duration_sec 片段；需要 librosa-analyze
工作流 — 预设、流水线、目录

服务端多步骤链式处理与发现。说明和 curl 示例请参阅工作流。

方法路径
GET/v1/catalog按类别分组的机器可读端点列表（17 个类别）
GET/v1/ops可用于预设和 /v1/pipeline 的流水线操作 slug 列表（约 24 个）
GET/v1/presets精选服务端工作流列表（名称和描述）
GET/v1/presets/{name}描述单个预设，包括所有步骤
POST/v1/presets/{name}JSON {path|url, size, steps, ...} — 运行精选预设；响应包含记录每个已执行操作的 steps 审计日志
POST/v1/pipelineJSON {path|url, size, steps, ...} — 即席 steps=[{op, params}, …] 链式处理，中间结果保留在服务端；响应包含 steps 审计日志
批处理
方法路径
POST/v1/batchJSON 请求体：操作对象数组 {op, file_path, output_path, …}。返回 {results:[…]} — 各操作的错误会包含在结果中，不会返回 4xx。支持的操作：convert、normalize、trim、fade、reverse、speed、eq。
异步任务

每个音频端点都接受 JSON 请求体中的 "async_job": true。可选使用 "webhook_url" 实现推送式交付。当 async_job=true 时，端点返回 HTTP 202 和 {job_id, status: "pending", status_url}，而不是在当前请求中直接执行。

方法路径
GET/v1/jobs列出任务；可选使用 ?status=pending|running|completed|failed|cancelled 筛选
GET/v1/jobs/{job_id}轮询单个任务 — 返回状态、结果和 duration_sec
DELETE/v1/jobs/{job_id}取消正在运行的任务或删除已完成的任务
MIDI
方法路径默认返回
POST/v1/midi/composeJSON {path|url, size, ...} — 请求体为 JSON 乐曲规格；写入 MIDI
POST/v1/midi/inspectJSON — 节奏、音轨、通道、音符计数、拍号和调号
POST/v1/midi/transformJSON {path|url, size, ...} — 移调、量化、覆盖节奏、筛选通道；写入 MIDI
POST/v1/midi/quantizeJSON {path|url, size, ...} — grid_beats 将所有音符时序对齐到节奏网格；写入 MIDI
POST/v1/midi/renderJSON {path|url, size, output_format, ...} — 通过 file_path / file_url 提供输入 MIDI；写入音频
POST/v1/midi/generateJSON {path|url, size, output_format, ...} — 请求体为 JSON 乐曲规格（一步完成创作和渲染）；写入音频
POST/v1/midi/drumJSON {path|url, size, ...} — 请求体为 JSON 步进音序器规格；写入 MIDI；需要 midi-compose
POST/v1/midi/humanizeJSON {path|url, size, ...} — 时序和力度抖动；timing_ms、velocity_pct、seed；写入 MIDI；需要 midi-compose
文件暂存
方法路径
GET/v1/files列出暂存文件
PUT/v1/files/{path}上传
GET/v1/files/{path}下载
DELETE/v1/files/{path}删除
管理
方法路径
GET/healthz存活状态 — 始终无需身份验证
GET/v1/engines列出已配置的引擎及每个引擎的 loaded / idle_seconds
GET/v1/ps列出当前在内存中的引擎
DELETE/v1/ps/{engine}卸载单个引擎
POST/v1/unload卸载所有引擎

MCP

audiolla 在 /v1/mcp 提供 Model Context Protocol 服务。将任何支持 MCP 的大模型 Agent 指向该服务，即可将完整的音频处理功能作为可调用工具使用 — 分离音轨、检测和弦、转录为 MIDI、区分说话人、根据 JSON 规格创作音乐、读取/写入标签、提交异步任务 — 全部通过 JSON-RPC 完成，无需编写任何集成代码。 生成音频的 MCP 工具遵循与 REST 相同的约定：调用方 MUST 传入 output_path（服务端将结果写入 FILES_DIR 下；客户端通过 get_file 工具或 HTTP GET /v1/files/<path> 获取；响应为 {path, size, ...}）或 output_url（预签名 PUT——服务端将编码后的字节上传到该 URL；响应为 {url, size, ...}），且必须恰好传入其中一个。两者都未传入 → ValueError；两者都已传入 → ValueError。v1.0.0 已移除内联 base64 音频响应——不再存在 audio_base64 / midi_base64 / image_base64 / video_base64 / zip_base64 字段。使用 list_jobs / get_job / cancel_job 管理长时间运行的异步工作。

端点： http://localhost:8000/v1/mcp

工具：

工具功能
list_engines列出已配置的引擎及其是否已加载
list_presets列出精选的服务端工作流（名称 + 描述）
describe_preset显示预设的完整步骤列表，供运行前查看
list_ops列出 run_pipeline_tool / 预设中可用的约 24 个管道操作标识
run_preset对输入文件运行精选预设
run_pipeline_tool在服务端运行临时的 [{op, params}, …] 操作链
generate_music文本转音频——engine = stable-audio-open / musicgen-small / musicgen-medium / riffusion / audioldm2；必须提供 prompt，可选 lyrics、duration_sec、seed。MusicGen 需要 AUDIOLLA_ENABLE_NONCOMMERCIAL=1。AudioLDM 2 采用 CC-BY 4.0 许可，可用于商业用途，无需选择加入。
separate使用 Demucs 分离音轨——每条音轨可通过 output_paths={stem:path} 暂存，或通过 output_urls={stem:url} 单独 PUT
master参考母带处理（matchering）或预设效果链（pedalboard）
analyze使用 librosa 分析 BPM、调性、LUFS 和频谱特征
beats节拍网格——BPM + 时间戳；可选生成节拍器音频
onsets音符起始时间戳
melody主旋律轮廓（Hz）；可选导出 MIDI
segments结构分段——重复段落标签（A、B、C…）
silence检测静音间隙；可选自动修剪（边缘或全部）
visualize生成 PNG 频谱图/波形图或动画 MP4/WebM——engine + mode 用于选择输出类型
fingerprintChromaprint 声学指纹（兼容 AcoustID）
restore使用 UVR 去除混响/回声/噪声——engine 用于选择模型；设置 aggressive=true 可加强回声抑制
denoise薄封装——建议使用 engine=uvr-denoise 的 restore，或使用 engine=uvr-denoise 的 noise_reduce
audio_to_midi使用 basic-pitch（ONNX）将复音音频转录为 MIDI——将 MIDI 写入 output_path 或 output_url
enhance使用 DeepFilterNet DF3 增强语音和人声
chords使用 librosa 检测和弦与调性——调性 + 分段和弦标签
vad使用 silero-vad 检测语音活动——带时间戳的语音/非语音片段
diarize使用 pyannote 进行说话人分离——按说话人区分的带时间戳片段
transformSox DSP 效果链——增益、均衡、混响、音高、速度等
loudness测量综合 LUFS——仅返回 JSON
loudness_curve随时间变化的 RMS 包络——{curve:[{time_sec,rms_db}],duration,sample_rate,points}
normalize将音频归一化至目标 LUFS 电平——写入 output_path 或 output_url
hpss分离谐波/打击乐——将各音轨分别写入 output_paths={stem:path} 或 output_urls={stem:url}
noise_reduce降噪——engine=noise-reduce（DSP，stationary/prop_decrease）或 engine=uvr-denoise（ML）
stretch使用 librosa 相位声码器调整时长和音高
pitch_correct自动校音至最近的半音——strength [0.0–1.0]；需要 librosa-analyze
repair_audio消除削波和电流嗡声——declip 布尔值、dehum 布尔值、hum_freq Hz
tag使用 AST 为音频添加标签——返回置信度分数最高的前 K 个 AudioSet 标签
embed512 维 CLAP 音频嵌入；提供 query_text 时返回余弦相似度
classify零样本 CLAP 分类——计算音频与任意文本标签列表的余弦相似度
info探测音频元数据——时长、sample_rate、声道数、编码格式、位深
trim将音频剪切至 [start_sec, end_sec)——写入 output_path 或 output_url
mix混合 N 条音轨，并设置每条音轨的增益——tracks 列表包含 {file_path/url, gain_db}
concat按顺序首尾拼接 N 个音频文件——files 列表包含 {file_path/url}
speed更改播放速度，不改变音高——speed 浮点数（0.1–10.0）
convert重新编码：一次调用即可设置格式、sample_rate 和声道数
similar使用 CLAP 计算两个音频文件的余弦相似度——返回 {similarity, dim}
midi_quantize将 MIDI 音符时间对齐至节奏网格——grid_beats 以拍为单位
fade淡入/淡出，可配置时长和曲线形状
reverse反转音频
loop重复播放音频 N 次——count 表示总播放次数
bpm_match检测 BPM 并调整时长以匹配 target_bpm——返回源 BPM、目标 BPM 和 tempo_factor
stereo_widthM/S 立体声宽度——width=0 为单声道，1 为原始宽度，>1 为更宽
split等分音频或按静音处分割——MCP 形式已在 v1.0.0 中弃用；请使用 REST POST /v1/audio/split，并设置 output_path 以暂存各个片段
pan在立体声声场中调整声像——position [-1.0–1.0]
eq参数均衡器——bands 列表包含 {freq, gain_db, width_hz}
key_match检测调性并移调至 target_key——返回 source_key + semitones
sidechain_duck根据触发音轨压低主音轨——threshold_db、ratio、attack_ms、release_ms
fx通用 pedalboard 效果链——完整效果目录，可自行选择顺序和参数
midi_composeJSON 乐曲规格 → MIDI；写入 output_path 或 output_url
midi_inspect读取 MIDI 结构——速度、音轨、通道、音符数量
midi_transform对现有 MIDI 文件进行移调、量化、速度覆盖和通道筛选
midi_render使用 fluidsynth + SoundFont 将 MIDI 转为音频
midi_generate一次性编曲并渲染——输入规格，输出音频
drum_pattern步进音序器 JSON 规格 → GM 鼓组 MIDI；pattern 对象包含各声部数组、swing、steps、bars
chords_to_midi将从音频中检测到的和弦进行转换为 MIDI 文件；参数为 tempo_bpm、velocity、octave
audio_metadata读取或写入音频标签——传入 tags 字典以写入，省略则读取
detect_clipping报告数字削波情况——clipped、clip_count、clip_ratio、peak_db
mid_side对立体声音频进行 M/S 编码（mode=encode）或解码（mode=decode）
slice_at_beats按节拍位置切分音频——将 zip 压缩包写入 output_path 或 output_url；响应中包含 beat_count
convolution_reverb应用 IR 混响——ir_file_path/ir_file_url + wet_mix [0.0–1.0]
transient_shaper调整起音/延音——attack_gain_db、sustain_gain_db
multiband_compressN 段压缩器——crossovers_hz 列表 + 包含各频段规格的 bands 列表
dj_prep一次调用即可获取 BPM、调性、Camelot 调性轮盘和 LUFS
find_loop_point查找最佳无缝循环边界——{loop_start_sec,loop_end_sec,bars,score,tempo_bpm,candidates}
deess分频段减弱齿音——threshold_db、frequency_hz、ratio
stereo_field分析立体声声场——相关性、宽度、balance_db、mono_compatible、Mid/Side 电平
audio_thumbnail提取能量最高的片段——duration_sec；写入 output_path 或 output_url；响应中包含 start_sec/end_sec
midi_humanize为 MIDI 添加时间和力度抖动——timing_ms、velocity_pct；可选使用 seed 生成确定性输出
list_jobs列出异步任务；可选按 status 筛选
get_job根据 job_id 轮询一个异步任务
cancel_job取消正在运行的任务或移除已完成的任务
list_files列出已暂存的文件
put_file将文件（base64）上传至暂存区
get_file读取暂存区中的文件（base64）
delete_file移除已暂存的文件
身份验证（AUDIOLLA_AUTH_TOKEN）与 REST 端点一样适用于 /v1/mcp — 在 Authorization 标头中传递 bearer token。

Agent 集成

skill 适用于任何会读取 .agents/skills/ 的 Agent（例如 peen），并且 可在以下客户端中原生安装。

Claude Code
claude plugin marketplace add psyb0t/agents
claude plugin install audiolla@psyb0t

Claude Code 会提示你输入 audiolla URL，以及在启用身份验证时输入令牌 — 令牌会 存储在操作系统密钥链中。

Codex
codex plugin marketplace add psyb0t/agents
codex plugin add audiolla@psyb0t

通过市场安装后，该 skill 会以 $audiolla:audiolla 的形式调用。Codex 也会在任何包含 .agents/skills/ 的仓库中自动发现 该 skill，无需安装；此时会以纯 $audiolla 的形式调用。

OpenClaw

每次发布时都会将该 skill 发布到 ClawHub：

openclaw skills install @psyb0t/audiolla

对于使用本地 stdio 的 MCP 客户端，@psyb0t/audiolla 插件会桥接到正在运行的服务的 /v1/mcp 端点：

openclaw plugins install clawhub:@psyb0t/audiolla

然后设置 AUDIOLLA_URL（如果服务启用了身份验证，还需设置 AUDIOLLA_AUTH_TOKEN）。

配置

变量默认值
AUDIOLLA_DEVICEautoauto、cpu、cuda 或 cuda:N
AUDIOLLA_ENGINES_FILE/app/engines.json引擎注册表的路径
AUDIOLLA_PRESETS_DIR/app/presets启动时加载 *.yaml 预设工作流的目录
AUDIOLLA_DATA_DIR/data存放模型和暂存文件的位置
AUDIOLLA_UVR_MODELS_DIR<DATA_DIR>/uvr_models缓存 UVR 模型文件的位置
AUDIOLLA_AUTH_TOKEN—bearer 令牌；留空表示不启用身份验证
HF_TOKEN / HUGGINGFACE_TOKEN—HuggingFace 访问令牌。入口点会同步这两个名称，因此设置任意一个都有效。以下受限引擎需要此令牌：pyannote 说话人分离、stable-audio-open、musicgen-small、musicgen-medium。使用前，请在 huggingface.co 上接受各模型的许可协议。
LOG_LEVELINFODEBUG / INFO / WARNING / ERROR / CRITICAL（不区分大小写；WARN 是 WARNING 的别名）。控制所有 audiolla 日志记录器和 uvicorn 日志记录器。日志采用按行分隔的 JSON 格式——每条记录包含 ts / level / logger / file / line / func / msg，以及 service / version / pid / host / thread。HTTP 请求还会包含 request_id（沿用传入的 X-Request-Id，否则自动生成并在响应中回传）、method、path、status、duration_ms、client_ip、user_agent、req_bytes、resp_bytes。
AUDIOLLA_ENABLED_ENGINES(全部)允许使用的引擎 slug，以逗号分隔；留空表示全部允许
AUDIOLLA_PRELOAD—启动时加载的引擎 slug，以逗号分隔
AUDIOLLA_ENGINE_TTL600引擎空闲多久后卸载，以秒为单位（也接受 10m）
AUDIOLLA_FILES_TTL24h暂存输入/输出文件的保留时长。接受秒数或 h/m/s 时长格式。0 表示禁用清理。
AUDIOLLA_SWEEPER_INTERVAL60检查引擎空闲状态和暂存文件清理的间隔秒数。必须是有限正数。
AUDIOLLA_LOAD_TIMEOUT300引擎冷启动加载允许的秒数，超时后视为失败（也接受 5m 等格式）
AUDIOLLA_MAX_UPLOAD_BYTES209715200上传大小上限（200 MB）——也限制 URL 获取的响应正文大小
AUDIOLLA_FETCH_MODEdisableddisabled、allowlist 或 denylist——控制服务端针对 file_url / output_url 的获取行为
AUDIOLLA_FETCH_HOSTS(无)以逗号分隔的主机模式（bucket.s3.amazonaws.com、*.s3.amazonaws.com）。mode=allowlist 时必填。
AUDIOLLA_FETCH_SCHEMEShttps以逗号分隔的协议——https、http（仅主动启用时允许 http）
AUDIOLLA_FETCH_ALLOW_PRIVATEfalse允许 URL 解析到私有 / 环回 / 链路本地 IP
AUDIOLLA_FETCH_TIMEOUT30每次获取/上传的硬超时时间，以秒为单位（也接受 30s、1m）
AUDIOLLA_FETCH_MAX_REDIRECTS5每次获取允许的最大重定向次数；每个 Location 都会重新通过策略验证
AUDIOLLA_JOB_TTL3600已完成/失败/取消的任务在被清理前保留在内存中的秒数。也接受 1h、30m。
AUDIOLLA_JOB_MAX_CONCURRENT8启动时解析，用于未来的异步任务并发限制；当前版本尚未在任何地方强制执行。
AUDIOLLA_SOUNDFONT/usr/share/sounds/sf2/FluidR3_GM.sf2（生产镜像）/v1/midi/render 的默认 SoundFont 路径。可通过请求中的 soundfont_path 覆盖。

此处未包含的内容

原因
MAGNeT / JASCO权重采用 CC-BY-NC 许可，属于 MusicGen 的同一系列（MusicGen 已提供，但需通过 AUDIOLLA_ENABLE_NONCOMMERCIAL=1 启用）。ACE-Step 和 DiffRhythm（均采用 Apache 2.0 许可，支持完整歌曲生成）也经过了研究，但未包含在 v1.0.0 中——原因见上文“推迟到未来版本”。
YuE 7B采用 Apache 2.0 许可，但实际运行需要 16-24 GB VRAM（fp16）；在 12 GB GPU 上无法轻松运行，除非使用 int4 量化工具。待推出 2B 或量化版本后再考虑。
Essentia 分析采用 AGPL v3 许可——任何使用它的网络服务都必须公开完整源代码。librosa 无需如此即可处理常见情况。
流式分离Demucs 需要完整文件。不支持分块或实时推理。
VST3 插件托管Pedalboard 可以实现，但需要挂载主机的插件目录。不属于默认镜像的范围。
rubberband 音高／时间拉伸采用 GPL v2 许可，另有商业许可。Sox 可处理基本的音高和节奏调整。如果接受相关条款，可自行添加。

构建与开发

两个镜像都继承自 Torchbase 的 Python 3.12、Torch 2.5.1 CPU/cu124 变体，并固定到 v0.1.1 及其已发布的摘要。Audiolla 在此基础上安装音频栈。源代码在依赖项安装后才复制，因此编辑 Python 代码不会重新安装 Torch 或音频依赖项。使用 Make 构建时，可通过 TORCHBASE_CPU_IMAGE 和 TORCHBASE_CUDA_IMAGE 覆盖基础镜像。构建会使用 pyproject.toml 中的版本为镜像添加标签，并添加 latest 或 latest-cuda 标签以及本地测试标签。

为确保音频栈兼容性，保留了 Torch 2.5.1。该版本受 CVE-2025-32434 影响。仅使用可信且经过验证的模型检查点，包括挂载到模型缓存中的文件。此次基础镜像迁移并未修复该漏洞。

make build        # CPU image
make build-cuda   # CUDA image
make version      # print the version used for image tags and package metadata
make run          # CPU image on port 8000
make run-cuda     # CUDA image on port 8000

make dev-image          # build the dev container
make shell              # shell inside it
make lint               # flake8 + mypy
make format             # isort + black
make test-unit          # unit tests (no GPU, no ML deps needed)
make test-retention     # retention tests with a 90% module coverage gate
make test-image         # real tensors, DSP, jobs and cleanup in the built CPU image
make test-image DEVICE=cuda # same checks in the built CUDA image, requires a GPU
make test-unit-cov-gate # fail if coverage on support modules drops below 80%
make test-integration   # integration tests (spins up Docker containers)
make generate           # regenerate src/audiolla/schema/ from openapi.yaml
make clean              # wipe build/cache artifacts

make pkg-lock                 # refresh uv.lock
make pkg-add PKG=name[==ver]  # add a dep
make pkg-update PKG=name      # upgrade one dep
make pkg-upgrade              # upgrade everything
make pkg-remove PKG=name      # remove a dep
make pkg-compile-heavy        # recompile both heavy locks, preserving existing versions
make pkg-compile-heavy VARIANT=cuda # recompile only the CUDA lock

pkg-add、pkg-remove、pkg-update 和 pkg-upgrade 会将 [tool.uv] exclude-newer 刷新为操作前七天对应的 UTC 零点。pkg-lock 使用当前截止时间。重型依赖项的锁定编译使用 scripts/compile_heavy_deps.sh 中单独固定的 HEAVY_EXCLUDE_NEWER 截止时间，并将解析限制在现有输出固定版本范围内；更改 wheel 变体不会升级无关的软件包。有意升级依赖项时，必须审核这些固定版本和截止时间。所有操作都在开发容器内运行。主机需要安装 docker、make、git。

供应链

两个生产镜像都分两层安装。

轻量依赖项（fastapi、uvicorn、pydantic 等）：在 uv.lock 中锁定，并使用 uv sync --frozen --no-dev 安装。如果锁文件与 pyproject.toml 不匹配，构建将失败。uv 会验证 wheel 哈希。

重型 ML/DSP 依赖项（torch、demucs、matchering、pedalboard、librosa、sox、numpy、soundfile、huggingface-hub）：每种镜像变体各有一个经过哈希锁定的需求文件（requirements-heavy-cpu.txt、requirements-heavy-cuda.txt），因为 CPU 和 CUDA 使用不同的 torch wheel，且 wheel 位于不同的索引。人工维护的规格文件位于 scripts/heavy-deps-{cpu,cuda}.in，通过 make pkg-compile-heavy 编译，并使用 uv pip install --require-hashes 安装。两个文件都已提交。

基础镜像和 uv 二进制文件均通过 @sha256: 摘要固定。

许可证

WTFPL。

matchering 和 pedalboard 采用 GPL v3 许可。用于自托管没有问题。若要将镜像作为产品分发，则需要进行 GPL 合规性审查。

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。