Audiolla について
Audiollaは、音声エンジニア、クリエイター、エージェントのワークフロー向けのセルフホスト可能な音声処理APIです。分析、編集、修復、音声処理、MIDIツールを一つのDockerコンテナにまとめ、非同期ジョブとWebhookにも対応します。
主な機能
- 01ステム分離とマスタリング
- 02BPM、キー、ラウドネス、構成の分析
- 03音声修復と音声処理
- 04オーディオからMIDIへの変換とMIDIツール
- 05エフェクト、変換、バッチワークフロー
- 06非同期ジョブとWebhookコールバック
活用シーン
- 01ステムを分離してトラックをマスタリングする
- 02DJ用にBPM、キー、ラウドネスを分析する
- 03音声をクリーニングして話者を識別する
- 04音声をMIDIに変換し、MIDIファイルを処理する
MCP 対応
AudiollaはMCPエンドポイントを通じて、LLMエージェントに音声処理機能を提供します。音声を生成するMCPツールは、base64ではなくステージ済みファイルパスまたは出力URLを使用します。
設定
ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。
ツール
ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。
詳細
audiolla
30 種のオーディオエンジン。1 つのポート。クラウド不要。非同期ジョブは投げっぱなしで実行。Webhook 対応。
ステム分離には Demucs が必要でした。次に BPM とキーの解析には librosa が必要でした。その次は MIDI トランスクリプションに basic-pitch、話者ダイアライゼーションに pyannote、音声の強調に DeepFilterNet が必要でした。その後、Python のバージョン競合のデバッグに 3 日を費やし、もう何もかも嫌になりました。
そんなことをやめたら、できあがるのが audiolla です。
使う価値のあるオーディオ処理ツールをすべて、1 つの HTTP API にまとめ、1 つの Docker コンテナで実行します。ファイルを POST すれば、オーディオ、JSON、または MIDI が返ってきます。curl、シェルスクリプト、Python ノートブック、Makefile から操作することも、LLM エージェントから 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 による上位 K 件の AudioSet クラスラベル |
| 🔗 オーディオ埋め込み | LAION CLAP による 512 次元のセマンティック埋め込み＋オプションのテキスト類似度 |
| 🏷️ ゼロショット分類 | CLAP のコサイン類似度による、自由形式の任意のテキストラベルとの照合 — ジャンル、ムード、楽器 |
| 📋 オーディオ情報 | ffprobe メタデータ — 再生時間、サンプルレート、チャンネル数、コーデック、ビット深度 |
| ✂️ トリミング | 開始／終了秒数を指定してクリップをカット — あらゆる形式を入力し、あらゆる形式で出力 |
| 🎚️ ミックス | ゲイン db をトラックごとに指定し、ステージング済みの N 個のトラックを結合 — 純粋な ffmpeg 処理で、モデル不要 |
| 🔗 連結 | N 個のオーディオファイルを指定順に末尾でつなぎ合わせる |
| ⏩ 速度 | ffmpeg atempo によるピッチシフトなしの再生速度変更（0.1× – 10×） |
| 🔄 変換 | 再エンコード：形式、サンプルレート、チャンネル数を 1 回の呼び出しで指定 |
| 🔍 類似度 | CLAP 埋め込みによる 2 つのオーディオファイル間のコサイン類似度 |
| 🎹 MIDI クオンタイズ | MIDI ノートのタイミングをリズムグリッド（16 分音符、8 分音符、4 分音符など）にスナップ |
| 🌅 フェード | 13 種類のカーブ形状によるフェードイン／フェードアウト |
| ⏪ 逆再生 | オーディオを逆向きにする |
| 🔁 ループ | オーディオを N 回繰り返す |
| 🎯 BPM マッチ | BPM を自動検出して目標値に合わせてストレッチ — 手動計算不要 |
| 📈 ラウドネスカーブ | 時間経過に伴う RMS エンベロープ — ゲインオートメーション用のタイムスタンプ付き dB 値 |
| 🎤 ピッチ補正 | 設定可能な強度で、最も近いクロマチック半音に向けて自動チューニング |
| 🔧 修復 | デクリップ＋ハム除去 — クリッピングしたピークを修正し、電源周波数のハムを除去 |
| 🔁 ループポイント | 最適なシームレスループ境界を検出 — スコア、小節数、候補リスト |
| 🥁 ドラムマシン | ステップシーケンサー仕様 → GM ドラム MIDI — 16 ステップパターン、スウィング、テンポ |
| 🎼 コードから MIDI | コード進行 → MIDI ファイル — セグメントごとにルート音＋3 度＋5 度のボイシング |
| ↔️ ステレオ幅 | M/S 処理によるステレオイメージの拡張または縮小 |
| ✂️ 分割 | N 個の等分割、または無音部分で分割 — セグメントを ZIP で返す |
| 🔊 パン | ステレオ空間内でオーディオの位置を設定（-1 左 → 0 中央 → 1 右） |
| 🎚️ EQ | パラメトリック 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 用準備 | 1 回の呼び出しで、BPM＋キー＋Camelot ホイール上の位置＋統合 LUFS を取得 |
| 📦 バッチ処理 | ステージング済みのファイルに対して、trim/convert/fade/reverse/speed/eq を順に実行 |
| 🧩 プリセット＋パイプライン | 厳選された YAML ワークフロー（master-for-spotify、podcast-cleanup、…）＋サーバー側での任意の操作チェーン |
| 🗂️ カタログ | GET /v1/catalog — カテゴリー別にグループ化された、検出用の機械可読なエンドポイント一覧 |
| ⚡ 非同期ジョブ | すべてのエンドポイントが async_job=true に対応 — ファイア・アンド・フォーゲット＋Webhook コールバック |
目次
- 実行する
- クイックスタート
- できること
- ステムを分離する
- マスタリング
- 分析
- ビート、オンセット、メロディー、セグメント
- 無音の検出とトリミング
- 可視化（スペクトログラム、波形、動画）
- 音響フィンガープリント
- リバーブ除去、エコー除去、ノイズ除去
- オーディオからMIDIへの文字起こし
- ニューラル音声とボーカルの強調
- コードとキーの検出
- 音声アクティビティ検出
- 話者ダイアライゼーション
- 変換
- ラウドネス測定
- ラウドネスカーブ
- ラウドネス正規化
- HPSS（調波／打楽器の分離）
- スペクトルノイズ低減
- タイムストレッチとピッチシフト
- ピッチ補正
- 修復
- オーディオタグ付け
- オーディオ埋め込み
- ゼロショット分類
- オーディオ情報
- トリミング
- ミックス
- 連結
- 速度
- 変換
- 類似
- MIDIクオンタイズ
- フェード
- 逆再生
- ループ
- BPM合わせ
- ステレオ幅
- 分割
- パン
- EQ
- キー合わせ
- サイドチェインダッキング
- エフェクトチェーン
- ループポイント
- MIDIの作曲
- MIDIの検査
- MIDIの変換
- MIDIをオーディオにレンダリング
- 仕様から音楽を生成
- ドラムパターン
- コードからMIDIへ
- オーディオメタデータタグ
- クリップ検出
- Mid/Sideのエンコードとデコード
- ビートスライス
- コンボリューションリバーブ
- トランジェントシェイパー
- マルチバンドコンプレッション
- DJ向け準備
- ディエッサー
- ステレオフィールド分析
- オーディオサムネイル
- MIDIのヒューマナイズ
- バッチ操作
- 非同期ジョブとWebhook
- ファイルのステージング
- リモートURL
- エンジン
- ワークフロー — プリセット＋パイプライン
- APIカタログ
- エンドポイント
- MCP
- エージェント連携
- 設定
- 含まれていないもの
- ビルドと開発
- サプライチェーン
- ライセンス
実行する
# 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 仕様になりました。make generateで Pydantic モデルを再生成します。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 の変更履歴をご覧ください。
クイックスタート
コンテナが起動したら、次の 6 つのコマンドでオーディオパイプラインを実行できます（現在、すべてのオーディオエンドポイントで 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>に書き込み、{"path":..., "size":..., ...}という JSON を返しますoutput_url— サーバーが署名付き URL に PUT し、{"url":..., "size":..., ...}という JSON を返します
分析のみを行うエンドポイント（/v1/audio/analyze、/v1/audio/loudness、/v1/audio/info など、JSON データを返すエンドポイント）では、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 を指定しない場合、レスポンスは silent_ranges、non_silent_ranges、duration のみを含む JSON となり、output_path／output_url は不要です。
可視化（スペクトログラム、波形、動画）
可視化出力は、出力タイプに応じて 2 つの名前空間に分かれています。
# 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 にステージングするか、output_url に PUT します）。パラメーター：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 エコシステムのモデルである BS-Roformer と MelBand Roformer を使用した AI 音声復元です。3 つすべてが 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（bool、デフォルト false）、melodia_trick（bool、デフォルト 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 では、音楽と効果音に対応する5つのエンジンを提供します。ライセンス、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-open | Stability Community Licence（収益がしきい値未満なら商用利用可） | 最大47秒 | 約12 GB | 44.1 kHzステレオ。ループ、効果音、アンビエントテクスチャ向け。インストゥルメンタルのみ |
musicgen-small | CC-BY-NC 4.0（非商用のみ。AUDIOLLA_ENABLE_NONCOMMERCIAL=1 でオプトイン） | 最大30秒 | 約3 GB | 32 kHzモノラル。Meta MusicGen 300M、インストゥルメンタル |
musicgen-medium | CC-BY-NC 4.0（同じくオプトインが必要） | 最大30秒 | 約6～8 GB | 32 kHzモノラル。-smallより高品質 |
riffusion | CreativeML OpenRAIL-M（ライセンスの使用制限に従えば商用利用可） | 1回あたり約5秒 | 約3 GB | 22.05 kHzモノラル。SDスタイルのスペクトログラムとGriffin-Limによる再構成。ローファイでループ感のある特性 |
audioldm2 | CC-BY 4.0（商用利用可。オプトイン不要） | 最大30秒 | 約8～10 GB（CPUオフロード） | 16 kHzモノラル。一般的な効果音：環境音、フォーリー、動物音、機械音、衝撃音。低速（DDIMのデフォルトは200ステップ。約4倍高速化するには num_inference_steps=50 を指定） |
すべてのエンジンが、再現性のための async_job=true、webhook_url、output_path、output_url、seed に対応しています。stable-audio-open と audioldm2 は、さらに num_inference_steps（品質と速度のトレードオフ）を指定できます。モデルの重みは初回呼び出し時に HF_HOME（デフォルトではコンテナ内の /data/hf。5つすべてで約7 GB）へダウンロードされます。2回目以降の呼び出しでは推論のみ行われます。5つすべてに 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分のフル楽曲） —
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秒モデル） —
python >=3.10, <3.11に固定されたstable-audio-toolsが必要です。audiolla は Python 3.12 を使用しているため、互換性がありません。stable-audio-toolsの Python バージョン制約が緩和されるか、diffusers に対応パイプラインが追加された時点で再検討します。 - TangoFlux（ICLR 2026、44.1 kHz、30秒、高速） — Git からのインストールのみ対応（PyPI パッケージなし）です。ハッシュ固定サプライチェーンで SHA を指定することはできますが、重い依存関係は PyPI のみとするため、現時点では延期します。
- AudioGen（Meta、CC-BY-NC） —
audiocraft==1.3.0はtransformers<=4.31.0に固定されており、audiolla の 4.51.3 と競合します。分離したサブプロセスまたはサイドカーコンテナが必要です。 - 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 には、path／url／size とともに、正規化前に測定したレベルを示す loudness_lufs が含まれます。
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）。
スペクトルノイズリダクション
同じエンドポイントで 2 種類のエンジンを選べるノイズリダクションです。GPU なしで高速にノイズを除去するには DSP を、より高品質な除去には 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 エンジンが必要です。
修復
クリッピングしたピークのクリッピングを解除したり、電源周波数のハムノイズを除去したりします。クリッピング解除では、3 次補間を使って平坦になった波形の上部と下部を再構築します。ハムノイズ除去では、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 のクラスラベルを上位 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/へ遅延ダウンロードされます。外部ネットワークへの接続が許可されない環境にデプロイする場合は、マウントした/data/hfボリュームにhuggingface-cli download <model>でモデルを事前に取得し、-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 からアクセス可能な複数のトラックを1つにまとめます。トラックごとの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を使用してください。
変換
1回の呼び出しで、オーディオを別の形式、サンプルレート、またはチャンネル数に再エンコードします。
# 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 埋め込みを使って、2つのオーディオファイル間のコサイン類似度を計算します。[-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 = 4分音符です。デフォルト：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]。
分割
ファイルを複数のセグメントに分割します。2つのモードがあります：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 = 右端。
EQ
ffmpeg の equalizer フィルターを使ったパラメトリック EQ です。任意の数のバンドを指定できます。各バンドには、中心周波数、ゲイン、任意で帯域幅を設定します。
# 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 のコード分析でソースのキーを検出し、目標のキーにピッチシフトします。2回の呼び出しを1回にまとめられます。
# 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 を作成
JSON の曲仕様を POST すると、Standard MIDI File のバイト列が返されます。仕様は手作業で記述したり、トラッカー／DAW／シーケンサーから生成したり、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 拍子で 16 分音符）。keep_channels と drop_channels にはチャンネル番号の JSON 配列を指定します。1 リクエストにつき、どちらか一方だけを設定できます。
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"}'
仕様から音楽を生成
作成とレンダリングを 1 回の呼び出しで実行します。仕様を入力すると、オーディオファイルがステージングされます。
# 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 コード（ルート音 + 3 度 + 5 度）に変換します。検出したコード表を再生可能な 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 コードイベントになります（ルート音 + メジャー 3 度／マイナー 3 度 + 完全 5 度、長さ = 区間の長さ）。
オーディオメタデータタグ
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 にエンコードするか、元に戻します。ペダルボードのチェーンに触れずにステレオ幅を調整するのに便利です。
# 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 を返します。各ビート区間につき 1 ファイルです。
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 用の準備
1 回の呼び出しで、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 を超える歯擦音を抑制し、それ以外の信号には影響しません。バターワース 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 が必要です。
バッチ操作
ステージング済みファイルに対して、1 回の 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 ペイロード（ジョブ完了時に指定した URL に POST）：
{
"id": "abc123",
"endpoint": "/v1/audio/separate",
"status": "completed",
"duration_sec": 12.4,
"result": {"path": "stems/track-vocals.wav", "size": 3145728, ...}
}
配信は指数バックオフ（0 秒、1 秒、2 秒、4 秒）で 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 の取得や
output_url への PUT を行えるようにするには、コンテナの起動時にポリシーを設定します。
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— 一覧にあるホスト以外はすべて許可されます（プライベート IP / メタデータサービスをブロックするには、AUDIOLLA_FETCH_ALLOW_PRIVATE=falseと併用してください）
常時有効な保護機能：
- DNS 解決されたプライベート / ループバック / リンクローカル IP は拒否されます（切り替え可能）
- デフォルトでは
httpsのみ許可されます。httpはAUDIOLLA_FETCH_SCHEMESでオプトインできます - リダイレクトも同じポリシーで再検証されます
- ハードタイムアウトとサイズ上限：
AUDIOLLA_MAX_UPLOAD_BYTES - 取得 / アップロード URL はすべてログに記録されます
すべての AUDIOLLA_FETCH_* 環境変数については、設定をご覧ください。
エンジン
| Slug | 機能 |
|---|---|
htdemucs | 4ステム分離：ドラム、ベース、その他、ボーカル。速度と品質のバランスに優れています。 |
htdemucs_ft | 同じ4ステムを、ファインチューニング済みの重みで処理します。品質は高くなりますが、約4倍遅くなります。CUDA 専用 — CPU イメージでは400エラーで拒否されます。 |
htdemucs_6s | 6ステム — ギターとピアノも分離します。実験的な機能です。 |
mdx_extra | ボーカルの分離に優れています。MUSDB で学習されており、アーキテクチャが異なります。 |
matchering | リファレンスベースのマスタリング：リファレンストラックに合わせて EQ とラウドネスを調整します。 |
pedalboard-chain | pedalboard によるプリセットのマスタリングチェーン — transparent（軽め）または loud（4:1 の圧縮）。mode=chain を指定して /v1/audio/master を処理します。任意のチェーンには fx-chain / /v1/audio/fx を使用してください。 |
librosa-analyze | librosa による BPM、キー、LUFS、再生時間、スペクトル特徴量、ビートグリッド、オンセット検出、メロディー（pyin）、構造分割。 |
sox-transform | pysox によるゲイン、EQ、コンプレッション、リバーブ、ピッチシフト、テンポ調整。 |
fx-chain | 任意の pedalboard エフェクトチェーン — カタログ全体を使い、順序とパラメーターを自由に指定できます。/v1/audio/fx を処理します。 |
midi-compose | JSON 仕様 → 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-dereverb | BS-Roformer によるディリバーブ — 部屋の残響を除去します。primary_stem=No Reverb を指定します。 |
uvr-deecho | VR Architecture によるディエコー — 通常モードと強力モードに対応します。より強く抑制するには aggressive=true を指定します。 |
uvr-denoise | MelBand Roformer によるノイズ除去（SDR 28）— 広帯域の背景ノイズを除去します。 |
uvr-karaoke | MelBand Roformer によるカラオケ処理 — リードボーカルを除去し、伴奏を残します。/v1/audio/separate 経由で動作します。 |
uvr-vocal-bsr | BS-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 | テキストから音楽を生成 — スペクトログラムを生成する Stable Diffusion のファインチューニングモデル、Riffusion-v1（Griffin-Lim によりオーディオに変換）。CreativeML OpenRAIL-M（ライセンスの使用制限を守れば商用利用可能です）。1パスあたり約5秒で、ローファイな音質、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 — 品質を下げて約4倍高速化するには num_inference_steps=50 を指定します）。CPU オフロード時、fp16 で約8～10 GB の VRAM が必要です。CUDA 専用。/v1/audio/generate/audioldm2 を処理します。 |
各 Demucs バリアントは、それぞれ独立したチェックポイント（dl.fbaipublicfiles.com でホストされています）です。エントリーポイントは、最初の分離リクエストがダウンロード待ちにならないよう、起動時に有効なバリアントをすべて /data/torch_cache/ に事前取得します。 |
AUDIOLLA_ENABLED_ENGINES — 利用可能なエンジンを制限します。AUDIOLLA_PRELOAD — 最初のリクエストを待つ代わりに、起動時に指定したエンジンをメモリに読み込みます。
ワークフロー — プリセット + パイプライン
呼び出し間で音声を再アップロードせずに、サーバー側で処理を連結する方法は2つあります。
厳選プリセット — 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 エージェントとコード生成スクリプトの両方がこのリストを利用します。
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 フィールドは含まれません。
| Method | Path | デフォルトの戻り値 |
|---|---|---|
POST | /v1/audio/separate | JSON {path|url, size, ...} — 1つのステム。複数のステム（またはすべて）の場合は、output_path／output_url を通じてステムを含む ZIP ストリームを返します |
POST | /v1/audio/master | JSON {path|url, size, output_format, ...} |
POST | /v1/audio/analyze | JSON — BPM、キー、LUFS、スペクトル特徴量 |
POST | /v1/audio/beats | JSON — BPM とビートのタイムスタンプ。クリックトラック WAV はオプションです |
POST | /v1/audio/onsets | JSON — オンセットのタイムスタンプ |
POST | /v1/audio/melody | JSON — 主旋律の輪郭。MIDI エクスポートはオプションです |
POST | /v1/audio/segments | JSON — 構造セグメントのラベル（A、B、C…） |
POST | /v1/audio/silence | JSON — 無音／非無音の範囲。トリミング済みオーディオはオプションです |
POST | /v1/audio/visualize/image/spectrogram | JSON {path|url, size, ...} — 静的な PNG スペクトログラム（color、scale パラメーター） |
POST | /v1/audio/visualize/image/waveform | JSON {path|url, size, ...} — 静的な PNG 波形（color パラメーター） |
POST | /v1/audio/visualize/video/{mode} | JSON {path|url, size, ...} — アニメーション付き MP4／WebM 動画（8 つのモード：spectrum、waves、cqt、…） |
POST | /v1/audio/fingerprint | JSON — Chromaprint フィンガープリント文字列 |
POST | /v1/audio/restore/{engine} | JSON {path|url, size, output_format, ...} — リバーブ／エコー／ノイズを除去します。uvr-deecho のハードモードでは aggressive=true を指定します |
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/chords | JSON — 検出されたキーとコード進行 |
POST | /v1/audio/vad | JSON — タイムスタンプと発話比率を含む発話／非発話セグメント |
POST | /v1/audio/diarize/{engine} | JSON — 話者ごとのタイムスタンプ付きセグメント |
POST | /v1/audio/transform | JSON {path|url, size, output_format, ...} |
POST | /v1/audio/loudness | JSON — {loudness_lufs}（測定のみ。オーディオは返しません） |
POST | /v1/audio/loudness/curve | JSON — {curve:[{time_sec,rms_db}],duration,sample_rate,points}。hop_length パラメーター |
POST | /v1/audio/normalize | JSON {path|url, size, measured_lufs, ...} — target_lufs が必要です。正規化前の LUFS は measured_lufs フィールドで報告されます |
POST | /v1/audio/separate/hpss | JSON {path|url, size, ...} — harmonic.<fmt> と percussive.<fmt> を含む ZIP ストリーム |
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/stretch | JSON {path|url, size, output_format, ...} |
POST | /v1/audio/pitch-correct | JSON {path|url, size, output_format, ...} — strength [0.0–1.0]。librosa-analyze が必要です |
POST | /v1/audio/repair | JSON {path|url, size, output_format, ...} — declip は bool、dehum は bool、hum_freq は Hz |
POST | /v1/audio/tag | JSON — 信頼度スコア付きの AudioSet ラベル上位 K 件 |
POST | /v1/audio/embed | JSON — 512 次元の埋め込み。query_text を指定するとコサイン類似度も返します |
POST | /v1/audio/classify | JSON — 降順に並べ替えられた {results: [{label, score}]}。clap-embed が必要です |
POST | /v1/audio/info | JSON — duration、sample_rate、channels、codec、bit_depth、format |
POST | /v1/audio/trim | JSON {path|url, size, output_format, ...} — start_sec と end_sec が必要です |
POST | /v1/audio/mix | JSON {path|url, size, output_format, ...} — tracks JSON 配列が必要です（2 件以上） |
POST | /v1/audio/concat | JSON {path|url, size, output_format, ...} — files JSON 配列が必要です（2 件以上） |
POST | /v1/audio/speed | JSON {path|url, size, output_format, ...} — speed の float 値が必要です（0.1–10.0） |
POST | /v1/audio/convert | JSON {path|url, size, output_format, ...} — フォーマット／サンプルレート／チャンネルの変換 |
POST | /v1/audio/similar | JSON — {similarity, dim}。clap-embed が必要です |
POST | /v1/audio/fade | JSON {path|url, size, output_format, ...} — 秒単位の fade_in／fade_out、13 種類の curve オプション |
POST | /v1/audio/reverse | JSON {path|url, size, output_format, ...} — 再生方向を反転します |
POST | /v1/audio/loop | JSON {path|url, size, output_format, ...} — 合計再生回数を count で指定します（2 回以上） |
POST | /v1/audio/bpm-match | JSON {path|url, size, output_format, ...} — target_bpm が必要です。librosa-analyze と stretch が必要です |
POST | /v1/audio/stereo-width | JSON {path|url, size, output_format, ...} — width [0.0–3.0]。M/S ステレオ処理 |
POST | /v1/audio/split | JSON {path|url, size, ...} — ZIP ストリーム。mode=equal（count が必要）または mode=silence |
POST | /v1/audio/pan | JSON {path|url, size, output_format, ...} — position [-1.0–1.0] |
POST | /v1/audio/eq | JSON {path|url, size, output_format, ...} — {freq, gain_db, width_hz} の JSON 配列 bands |
POST | /v1/audio/key-match | JSON {path|url, size, output_format, ...} — target_key が必要です。chord-detect と stretch が必要です |
POST | /v1/audio/sidechain-duck | JSON {path|url, size, output_format, ...} — メイン音声と trigger_file_*。ffmpeg sidechaincompress |
POST | /v1/audio/fx | JSON {path|url, size, output_format, ...} |
POST | /v1/audio/metadata | JSON — タグフィールド（title、artist、bpm、key、duration、sample_rate…）。tags JSON を指定するとタグを書き込みます |
POST | /v1/audio/clip-detect | JSON — clipped、clip_count、clip_ratio、peak_db、duration_sec |
POST | /v1/audio/mid-side | JSON {path|url, size, output_format, ...} — mode=encode（L/R→M/S）または mode=decode（M/S→L/R） |
POST | /v1/audio/beat-slice | JSON {path|url, size, ...} — 番号付きビートスライスの ZIP ストリーム。librosa-analyze が必要です |
POST | /v1/audio/conv-reverb | JSON {path|url, size, output_format, ...} — ir_file_path／ir_file_url が必要です。wet_mix [0.0–1.0] |
POST | /v1/audio/transient | JSON {path|url, size, output_format, ...} — attack_gain_db と sustain_gain_db |
POST | /v1/audio/multiband-compress | JSON {path|url, size, output_format, ...} — N バンドコンプレッサー。crossovers_hz と bands の JSON 配列 |
POST | /v1/audio/dj-prep | JSON — bpm、key、camelot、integrated_lufs。librosa-analyze と chord-detect が必要です |
POST | /v1/audio/loop-point | JSON — {loop_start_sec,loop_end_sec,bars,score,tempo_bpm,candidates}。librosa-analyze が必要です |
POST | /v1/audio/chords-to-midi | JSON {path|url, size, ...} — オーディオからコード進行を生成（MIDI）。chord-detect が必要です |
POST | /v1/audio/deess | JSON {path|url, size, output_format, ...} — バンド分割による歯擦音の減衰。threshold_db、frequency_hz、ratio |
POST | /v1/audio/stereo-field | JSON — {correlation, width, balance_db, mono_compatible, mid_level_db, side_level_db, phase_issues, …} |
POST | /v1/audio/thumbnail | JSON {path|url, size, start_sec, end_sec, ...} — 最もエネルギーの高い duration_sec セグメント。librosa-analyze が必要です |
ワークフロー — プリセット、パイプライン、カタログ
サーバー側の複数ステップのチェーンとディスカバリーです。説明と curl の例については、ワークフローを参照してください。
| メソッド | パス | |
|---|---|---|
GET | /v1/catalog | カテゴリ別にグループ化された、機械可読なエンドポイント一覧（17 カテゴリ） |
GET | /v1/ops | プリセットと /v1/pipeline で使用できるパイプライン op のスラッグ一覧（約 24 個） |
GET | /v1/presets | 厳選されたサーバー側ワークフローの一覧（名前と説明） |
GET | /v1/presets/{name} | 1 つのプリセットの全ステップを含む詳細 |
POST | /v1/presets/{name} | JSON {path|url, size, steps, ...} — 厳選されたプリセットを実行します。レスポンスには、実行した各 op の監査ログ steps が含まれます |
POST | /v1/pipeline | JSON {path|url, size, steps, ...} — オンデマンドの steps=[{op, params}, …] チェーンを実行します。中間処理はサーバー側で行われます。レスポンスには監査ログ steps が含まれます |
バッチ
| メソッド | パス | |
|---|---|---|
POST | /v1/batch | JSON ボディ：op オブジェクトの配列 {op, file_path, output_path, …}。{results:[…]} を返します。op ごとにエラーが返され、4xx にはなりません。サポートされる op：convert、normalize、trim、fade、reverse、speed、eq。 |
非同期ジョブ
すべてのオーディオエンドポイントは、JSON ボディで "async_job": true を受け付けます。プッシュ形式で配信する場合は、任意で "webhook_url" を指定できます。async_job=true の場合、インライン実行の代わりに、エンドポイントは {job_id, status: "pending", status_url} と HTTP 202 を返します。
| メソッド | パス | |
|---|---|---|
GET | /v1/jobs | ジョブ一覧。任意で ?status=pending|running|completed|failed|cancelled を指定できます |
GET | /v1/jobs/{job_id} | 1 つのジョブの状態を確認します。status、result、duration_sec を返します |
DELETE | /v1/jobs/{job_id} | 実行中のジョブをキャンセルするか、完了したジョブを削除します |
MIDI
| メソッド | パス | デフォルトの戻り値 |
|---|---|---|
POST | /v1/midi/compose | JSON {path|url, size, ...} — ボディは JSON の曲仕様です。MIDI を書き出します |
POST | /v1/midi/inspect | JSON — テンポ、トラック、チャンネル、ノート数、拍子と調性 |
POST | /v1/midi/transform | JSON {path|url, size, ...} — 移調、クオンタイズ、テンポの上書き、チャンネルフィルターを適用します。MIDI を書き出します |
POST | /v1/midi/quantize | JSON {path|url, size, ...} — grid_beats によってすべてのノートのタイミングをリズムグリッドに合わせます。MIDI を書き出します |
POST | /v1/midi/render | JSON {path|url, size, output_format, ...} — file_path / file_url で MIDI を入力します。オーディオを書き出します |
POST | /v1/midi/generate | JSON {path|url, size, output_format, ...} — ボディは JSON の曲仕様です（作曲とレンダリングを一括実行）。オーディオを書き出します |
POST | /v1/midi/drum | JSON {path|url, size, ...} — ボディは JSON のステップシーケンサー仕様です。MIDI を書き出します。midi-compose が必要です |
POST | /v1/midi/humanize | JSON {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} | 1 つのエンジンをメモリから解放します |
POST | /v1/unload | すべてをメモリから解放します |
MCP
audiolla は /v1/mcp で Model Context Protocol サーバーを公開しています。MCP 対応の LLM エージェントを接続すると、音声処理機能一式を呼び出し可能なツールとして利用できます。ステムの分離、コード検出、MIDI への文字起こし、話者ダイアライゼーション、JSON 仕様からの作曲、タグの読み書き、非同期ジョブの送信などを、統合コードを 1 行も書かずに、すべて JSON-RPC 経由で実行できます。
音声を生成する MCP ツールは REST と同じ契約に従います。呼び出し側は output_path（サーバーが結果を FILES_DIR の下に書き込みます。クライアントは get_file ツールまたは HTTP GET /v1/files/<path> で取得します。レスポンスは {path, size, ...} です）と output_url（署名付き PUT。サーバーがエンコード済みのバイト列を URL にアップロードします。レスポンスは {url, size, ...} です）のどちらか一方を必ず指定する必要があります。どちらも指定しない場合は ValueError、両方を指定した場合も ValueError になります。インラインの base64 音声レスポンスは v1.0.0 で廃止されており、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個のパイプライン op スラッグを一覧表示します |
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}、ステムごとの PUT には output_urls={stem:url} を指定します |
master | リファレンスマスタリング（matchering）またはプリセットチェーン（pedalboard）を実行します |
analyze | librosa を使用して BPM、キー、LUFS、スペクトル特徴量を分析します |
beats | ビートグリッド — BPM とタイムスタンプを返します。クリックトラック音声も任意で生成できます |
onsets | 音符のオンセットのタイムスタンプを返します |
melody | 主旋律の輪郭を Hz で返します。MIDI エクスポートも任意で行えます |
segments | 構造的なセグメンテーション — 繰り返し現れるセクションにラベル（A、B、C…）を付けます |
silence | 無音区間を検出します。自動トリミング（端またはすべて）も任意で行えます |
visualize | PNG スペクトログラム／波形、またはアニメーション付き MP4/WebM を生成します — engine と mode で出力タイプを選択します |
fingerprint | Chromaprint 音響フィンガープリント（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 による話者ダイアライゼーション — 話者ごとのタイムスタンプ付きセグメントを返します |
transform | Sox DSP チェーン — ゲイン、EQ、残響、ピッチ、テンポなどを処理します |
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 bool、dehum bool、hum_freq Hz |
tag | AST による音声タグ付け — 信頼度スコア付きの AudioSet 上位 K ラベルを返します |
embed | 512 次元の CLAP 音声埋め込みを生成します。query_text を指定するとコサイン類似度を返します |
classify | ゼロショット CLAP 分類 — 任意のテキストラベルリストとのコサイン類似度を返します |
info | 音声メタデータ（duration、sample_rate、channels、codec、bit_depth）を調べます |
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 は float（0.1–10.0）です |
convert | 1 回の呼び出しでフォーマット、sample_rate、channels を再エンコードします |
similar | CLAP による 2 つの音声ファイル間のコサイン類似度 — {similarity, dim} を返します |
midi_quantize | MIDI ノートのタイミングをリズムグリッドに合わせます — grid_beats は拍単位です |
fade | 長さとカーブ形状を設定してフェードイン／フェードアウトを行います |
reverse | 音声を逆再生します |
loop | 音声を N 回繰り返します — count は合計再生回数です |
bpm_match | BPM を検出してから target_bpm に合わせてストレッチします — 元と目標の BPM および tempo_factor を返します |
stereo_width | M/S ステレオ幅 — width=0 はモノラル、1 は元の幅、>1 は幅を広げます |
split | 均等なパートまたは無音箇所で分割します — MCP 形式は v1.0.0 で非推奨です。セグメントごとのステージングには REST POST /v1/audio/split と output_path を使用してください |
pan | ステレオフィールド内でパンします — position [-1.0–1.0] |
eq | パラメトリック 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_compose | JSON の曲仕様から 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_compress | N バンドコンプレッサー — crossovers_hz リストと、バンドごとの仕様を含む bands リスト |
dj_prep | 1 回の呼び出しで 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ヘッダーにベアラートークンを渡してください。 |
エージェント連携
スキルは、.agents/skills/を読み込む任意のエージェント（peenなど）で動作し、以下のクライアントにはネイティブにインストールできます。
Claude Code
claude plugin marketplace add psyb0t/agents
claude plugin install audiolla@psyb0t
Claude CodeではaudiollaのURLと、認証が有効な場合はトークンの入力を求められます。トークンはOSのキーチェーンに保存されます。
Codex
codex plugin marketplace add psyb0t/agents
codex plugin add audiolla@psyb0t
マーケットプレイスからインストールすると、スキルは$audiolla:audiollaとして呼び出されます。また、.agents/skills/を含むリポジトリではCodexがスキルを自動的に認識するため、インストールは不要です。この場合、スキルは$audiollaとして呼び出されます。
OpenClaw
スキルはリリースごとにClawHubに公開されます。
openclaw skills install @psyb0t/audiolla
ローカルのstdioを使用するMCPクライアント向けには、@psyb0t/audiollaプラグインが、実行中のサーバーの/v1/mcpエンドポイントに接続します。
openclaw plugins install clawhub:@psyb0t/audiolla
次に、AUDIOLLA_URLを設定してください（サーバーで認証が有効な場合はAUDIOLLA_AUTH_TOKENも設定します）。
設定
| 変数 | デフォルト | |
|---|---|---|
AUDIOLLA_DEVICE | auto | auto、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 | — | ベアラートークン。空の場合、認証は行われません |
HF_TOKEN / HUGGINGFACE_TOKEN | — | HuggingFace アクセストークン。エントリポイントは 2 つの名前を相互に反映するため、どちらを設定しても機能します。ゲート付きエンジン（pyannote の話者ダイアライゼーション、stable-audio-open、musicgen-small、musicgen-medium）で必要です。使用前に huggingface.co で各モデルのライセンスに同意してください。 |
LOG_LEVEL | INFO | DEBUG / INFO / WARNING / ERROR / CRITICAL（大文字と小文字を区別しません。WARN は WARNING の別名です）。すべての audiolla ロガーと uvicorn のロガーを制御します。ログは 1 行ごとの 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 | (すべて) | 許可するスラッグをカンマ区切りで指定します。空の場合はすべて許可されます |
AUDIOLLA_PRELOAD | — | 起動時に読み込むスラッグをカンマ区切りで指定します |
AUDIOLLA_ENGINE_TTL | 600 | エンジンがアンロードされるまでのアイドル秒数（10m も使用できます） |
AUDIOLLA_FILES_TTL | 24h | ステージング済みの入力／出力ファイルを保持する期間です。秒数または h/m/s 単位の期間を指定できます。0 にするとクリーンアップは無効になります。 |
AUDIOLLA_SWEEPER_INTERVAL | 60 | エンジンのアイドル状態とステージング済みファイルのクリーンアップを確認する間隔（秒）です。有限の正の値を指定する必要があります。 |
AUDIOLLA_LOAD_TIMEOUT | 300 | エンジンのコールドロードが失敗とみなされるまでの許容秒数です（5m なども指定できます） |
AUDIOLLA_MAX_UPLOAD_BYTES | 209715200 | アップロードの上限（200 MB）です。URL から取得する本文サイズにもこの上限が適用されます |
AUDIOLLA_FETCH_MODE | disabled | disabled、allowlist、または denylist。file_url / output_url に対するサーバー側の取得を制御します |
AUDIOLLA_FETCH_HOSTS | (なし) | ホストパターンをカンマ区切りで指定します（bucket.s3.amazonaws.com、*.s3.amazonaws.com）。mode=allowlist の場合に必須です。 |
AUDIOLLA_FETCH_SCHEMES | https | スキームをカンマ区切りで指定します（https、http。http は明示的なオプトインが必要です） |
AUDIOLLA_FETCH_ALLOW_PRIVATE | false | プライベート／ループバック／リンクローカル IP に解決される URL を許可します |
AUDIOLLA_FETCH_TIMEOUT | 30 | 取得／アップロードごとのハードタイムアウト（秒）です（30s、1m も指定できます） |
AUDIOLLA_FETCH_MAX_REDIRECTS | 5 | 取得ごとの最大リダイレクト数です。各 Location はポリシーに基づいて再検証されます |
AUDIOLLA_JOB_TTL | 3600 | 完了／失敗／キャンセルされたジョブがメモリ内に保持され、スイープされるまでの秒数です。1h、30m も指定できます。 |
AUDIOLLA_JOB_MAX_CONCURRENT | 8 | 今後の非同期ジョブの同時実行数制限のため、起動時に解析されます。現在のビルドではまだどこにも適用されません。 |
AUDIOLLA_SOUNDFONT | /usr/share/sounds/sf2/FluidR3_GM.sf2（prod イメージ） | /v1/midi/render のデフォルトの SoundFont パスです。リクエストごとに soundfont_path で上書きできます。 |
含まれていないもの
| 理由 | |
|---|---|
| MAGNeT / JASCO | CC-BY-NC ライセンスの重みで、MusicGen（AUDIOLLA_ENABLE_NONCOMMERCIAL=1 を指定した場合に利用可能）と同じファミリーです。ACE-Step と DiffRhythm（どちらも Apache 2.0、フルソング生成）も調査済みですが、v1.0.0 では提供されません。理由については、上記の「今後のリリースに延期」をご覧ください。 |
| YuE 7B | Apache 2.0 ですが、fp16 では現実的に 16〜24 GB の VRAM が必要です。int4 量子化ツールなしでは、12 GB の GPU で快適に動作しません。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 を操作の 7 日前の UTC 午前 0 時に更新します。pkg-lock は現在のカットオフを使用します。重い依存関係のロックファイルのコンパイルでは、scripts/compile_heavy_deps.sh に別途固定された HEAVY_EXCLUDE_NEWER のカットオフを使用し、既存の出力ピンに解決範囲を限定します。ホイールの種類を変更しても、無関係なパッケージはアップグレードされません。依存関係を意図的にアップグレードする場合は、それらのピンとカットオフを確認する必要があります。すべての処理は開発用コンテナ内で実行されます。ホストには docker、make、git が必要です。
サプライチェーン
本番用の両イメージでは、2 層構成でインストールします。
軽量な依存関係（fastapi、uvicorn、pydantic など）：uv.lock でロックし、uv sync --frozen --no-dev でインストールします。ロックファイルが pyproject.toml と一致しない場合、ビルドは失敗します。ホイールのハッシュは uv によって検証されます。
重量級の ML/DSP 依存関係（torch、demucs、matchering、pedalboard、librosa、sox、numpy、soundfile、huggingface-hub）：イメージのバリアントごとに、ハッシュでロックされた要件ファイル（requirements-heavy-cpu.txt、requirements-heavy-cuda.txt）を用意します。CPU と CUDA では torch のホイールが異なり、別々のインデックスにあるためです。人間が編集する仕様ファイル scripts/heavy-deps-{cpu,cuda}.in を make pkg-compile-heavy でコンパイルし、uv pip install --require-hashes でインストールします。両方のファイルはコミットされています。
ベースイメージと uv バイナリは @sha256: ダイジェストで固定されています。
ライセンス
matchering と pedalboard は GPL v3 です。セルフホストでの使用には問題ありません。イメージを製品として配布する場合は、GPL のコンプライアンス確認が必要です。
コメント
AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。