# オーディオ処理・ボーカル抽出・ステム分離
> 背景のノイズや音楽からクリアなボーカルを抽出したり、楽曲をステムに分離したり、トリム・ループ・フェード・ラウドネス正規化・形式変換を実行します。

ノイズの多い録音や背景音楽からクリアな発話・ボーカルを抽出したり、ミックス済みの楽曲をステムに分離したり、トリム、シームレスなループ延長、フェード、EBU R128 ラウドネス正規化、形式変換などの決定論的なオーディオ処理を行います。

## Agent の主経路

Universal Skill から MCP ツール `beatra.audio.process` を使います。1 つのツールで `operation` フィールドにより 3 つの機能系統すべてを扱い、どの呼び出しも課金対象の非同期タスクを返します。

| `operation` | 機能 ID（`capability`） | モデル | 対応する REST エンドポイント |
| --- | --- | --- | --- |
| `isolate_voice` | `audio_voice_isolation` | `elevenlabs-audio-isolation` | `POST /v1/audio/isolation` |
| `separate_stems` | `audio_stem_separation` | `beatra-stems-v1` | `POST /v1/audio/stems` |
| `trim`、`loop`、`fade`、`normalize_loudness`、`convert_format` | `audio_process` | `beatra-audio-v1` | `POST /v1/audio/process` |

1. ローカルのオーディオを `beatra.assets.upload` でアップロードし、返された `artifact_id` を `source`（MCP・REST ともにエイリアス `audio` も可）に渡します（または `https_url` を直接渡します）。`speech:generate` と `music:generate` のいずれかのスコープを持つトークンで `beatra.audio.process` を呼び出せます。
2. 制限、対応フォーマット、最新価格を確認する場合は、該当する `capability` を指定して `beatra.models.list` を呼びます。
3. 不透明な `client_request_id` を 1 つ作り、一度だけ送信して `beatra.tasks.get` で終端状態までポーリングします。

## AI ガイド

AI integration guide: https://docs.beatra.ai/llms/audio-processing.md

## ボーカル抽出

`operation: "isolate_voice"`（`elevenlabs-audio-isolation`、REST `POST /v1/audio/isolation`）は、背景音楽、部屋の残響、風切り音、交通騒音、雑踏を取り除き、クリアな発話やボーカルだけを抽出します。[ボイスクローン](https://docs.beatra.ai/ja/docs/capabilities/speech/voice-clone)、[音声文字起こし](https://docs.beatra.ai/ja/docs/capabilities/speech/speech-to-text)、[スピーチ変換](https://docs.beatra.ai/ja/docs/capabilities/speech/speech-to-speech)の前にノイズの多い録音をクリーニングする用途に適しています。

```json
{
  "operation": "isolate_voice",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "format": "wav",
  "client_request_id": "isolate-opaque-1"
}
```

- **入力の制限**：長さは **`4.6` 秒以上 `300.0` 秒（`5 分`）以下**、ファイルサイズは `100 MB` 以下です。`4.6` 秒未満または `300.0` 秒超のクリップは課金前に `422 invalid_request`（`details.reason: "audio_too_short"` または `"audio_too_long"`）で拒否され、クレジットは消費されません。MCP の `beatra.audio.process` と REST の `POST /v1/audio/isolation` のどちらでも入力参照として `source` と `audio` の両方を受け付けます（旧モデル名エイリアス `"beatra-voice-isolate-v1"` も `"elevenlabs-audio-isolation"` として正規化されます）。
- **任意の出力フォーマット指定**：`isolate_voice` が受け付けるのは `format`（既定 `"wav"`、ほか `"mp3"`、`"ogg"`、`"flac"`、`"m4a"`、`"ulaw_8k_wav"`）、`sample_rate`（`8000`、`16000`、`22050`、`24000`、`32000`、`44100`、`48000` Hz）、`bitrate_kbps`（非可逆の `"mp3"`、`"ogg"`、`"m4a"` で `64`、`128`、`192`、`256`、`320`。`"m4a"` は最大 `256`）、`channels`（`1` または `2`）のみです。`fade_in_ms`、`fade_out_ms`、`loudness_lufs`、`true_peak_db` は `isolate_voice` には渡せません（必要な場合は抽出後に下記の決定論的オーディオ処理ユーティリティを呼び出してください）。
- **コストと出力**：**入力音声の切り上げ分数**に基づく前払いで、切り上げ 1 分あたり `721 クレジット` です（`60` 秒以下は `721 クレジット`、`5` 分は `3,605 クレジット`）。伴奏ステムは作らず、抽出したボーカルのみを `outputs: [{"role": "voice", ...}]` に返します。

## ステム分離

`operation: "separate_stems"`（`beatra-stems-v1`、REST `POST /v1/audio/stems`）は、ミックス済みの楽曲（最長 `600` 秒 / `10 分`、`100 MB` 以下）をボーカルと各楽器のステムに分離します。

```json
{
  "operation": "separate_stems",
  "source": { "type": "artifact", "artifact_id": "artifact_01JX..." },
  "mode": "two_stem",
  "client_request_id": "stems-opaque-1"
}
```

- `mode: "two_stem"`（既定、1 タスク `180 クレジット`）：`vocals`（ボーカル）と `instrumental`（インストゥルメンタル、`outputs[].role` は `"vocals"`、`"instrumental"`）を返します。
- `mode: "multi_stem"`（1 タスク `360 クレジット`）：最大 6 つのステム（`vocals`、`drums`、`bass`、`guitar`、`piano`、`other`、`outputs[].role` は `"stem:vocals"`、`"stem:drums"`、`"stem:bass"`、`"stem:guitar"`、`"stem:piano"`、`"stem:other"`）に分離します。
- 出力フォーマットはステム分離モデル側で決まり、`separate_stems` は `format` やローカル後処理パラメーターを受け付けません。

## 決定論的オーディオ処理ユーティリティ

`beatra-audio-v1`（REST `POST /v1/audio/process`）は、最長 `3,600` 秒（`60 分`、`300 MB` 以下）のオーディオに対して決定論的な後処理を **1 タスク一律 `60 クレジット`** で実行します。

- `trim`：`start_ms`（`>= 0`、既定 `0`）と、`end_ms`（`> start_ms`）または `target_duration_ms` の**いずれか一方**を指定して区間を切り出します。
- `loop`：全体または部分区間（`loop_start_ms` 既定 `0`、`loop_end_ms`。ループ区間は `4,000` ミリ秒以上）を、`target_duration_ms`（`1,000`〜`3,600,000` ミリ秒）または `loop_count`（`2`〜`100` 回）の**いずれか一方**でループ延長します。`crossfade_ms`（`50`〜`3,000` ミリ秒、既定 `500` ミリ秒）と `end_with_fade`（真偽値、既定 `true`）を指定できます。
- `fade`：`fade_in_ms` および／または `fade_out_ms`（`0`〜`30,000` ミリ秒、少なくとも一方を指定）と `fade_curve`（既定 `"tri"`、ほか `"exp"`、`"log"`、`"qsin"`）でフェードをかけます。
- `normalize_loudness`：2 パスの EBU R128 ラウドネス正規化を行い、`loudness_lufs`（`-30.0`〜`-9.0` LUFS、既定 `-14.0`）と `true_peak_db`（`-9.0`〜`0.0` dBTP、既定 `-1.0`）に揃えます。
- `convert_format`：必須の `format`（`"mp3"`、`"wav"`、`"ogg"`、`"flac"`、`"m4a"`、または 8 kHz モノラル電話音声用 `"ulaw_8k_wav"`）へ変換・リサンプリングします（任意の `sample_rate`、`bitrate_kbps`、`channels` に対応）。
- 上記の決定論的操作ではいずれも、同一タスク内で任意の仕上げ指定（`fade_in_ms`、`fade_out_ms`、`fade_curve`、`loudness_lufs`、`true_peak_db`、`format`、`sample_rate`、`bitrate_kbps`、`channels`）を併用できます。

## 結果

すべての操作で `"type": "audio_process"`、`"operation"`、`"outputs"` が返ります（`separate_stems` では `"mode"`、決定論的ユーティリティでは `"metrics"` と `"steps"` も含まれます）。各 `outputs[]` 要素には `role`（`isolate_voice` は `"voice"`、`two_stem` は `"vocals"` / `"instrumental"`、`multi_stem` は `"stem:<kind>"`、決定論的ユーティリティは `"main"`）、`artifact_id`、CDN の `url`、`mime_type`、`duration_seconds` が入り、`"role": "main"` のみ計測された `loudness_lufs` と `true_peak_db` も含まれます。

```json
{
  "type": "audio_process",
  "operation": "isolate_voice",
  "outputs": [
    {
      "role": "voice",
      "artifact_id": "artifact_01JZ...",
      "url": "https://cdn.beatra.ai/tenants/.../voice.wav",
      "mime_type": "audio/wav",
      "duration_seconds": 18.4
    }
  ]
}
```

## タスクの状態とリカバリー

`queued` と `running` は失敗ではありません。同じ `task_id` をポーリングし続けてください。作成応答を失った場合は同じ `client_request_id` で同一の引数を再送し、入力が変わったら新しい ID を使います。失敗したタスクは自動で返金されます。アーティファクト URL は CDN アドレスです——速やかに自分のストレージへコピーしてください。

## REST で呼び出す

プロトコル直結の統合では、固定の `Idempotency-Key` ヘッダーを付けて `POST /v1/audio/isolation`、`POST /v1/audio/stems`、`POST /v1/audio/process` と共有タスクエンドポイントを使えます。生成された[API リファレンス](https://docs.beatra.ai/ja/docs/api-reference)を参照してください。推奨の統合方法は Skill + MCP です。REST は Agent ではないカスタムアプリケーション向けです。