# PodVoice — 完全仕様書（AI 向け詳細版）

このドキュメントは AI エージェントが PodVoice を完全に理解・操作するための詳細仕様です。
人間向けドキュメント: https://www.podvoice.jp/docs
概要版: https://www.podvoice.jp/llms.txt

---

## 基本情報

- サービス名: PodVoice
- URL: https://www.podvoice.jp
- API ベース URL: https://www.podvoice.jp
- 認証: Bearer トークン（`pv_` で始まる文字列）
- コンテンツタイプ: application/json
- レスポンス言語: 日本語
- 文字コード: UTF-8

---

## MCP Server

npx で即起動可能な stdio MCP Server。

```json
{
  "mcpServers": {
    "podvoice": {
      "command": "npx",
      "args": ["-y", "podvoice-mcp"],
      "env": { "PODVOICE_API_KEY": "pv_xxxx" }
    }
  }
}
```

代替（node 直接実行）:
```json
{
  "command": "node",
  "args": ["/path/to/mcp-server/proxy/index.js"],
  "env": { "PODVOICE_API_KEY": "pv_xxxx" }
}
```

---

## MCP ツール詳細仕様

### get_status
プラン・API残り回数・ストレージ使用量を返す。
パラメータ: なし
レスポンス: `{ plan, api_calls_used, api_calls_limit, api_calls_remaining, storage_used_mb, recordings_count }`

### get_recordings
録音一覧を取得。
パラメータ: `limit: number(1-100, default=20)`
レスポンス: `Array<{ id, filename, format, duration_sec, file_size, created_at, voice_type, url }>`

### recordings_latest
最新録音1件を取得。
パラメータ: なし
レスポンス: `{ id, filename, format, duration_sec, url, created_at }`

### search_recordings
録音をファイル名・日付で検索。
パラメータ: `query: string（ファイル名の部分一致）, after: string（YYYY-MM-DD）`
レスポンス: `Array<Recording>`

### get_recording_info
録音の詳細情報を取得。試聴 URL が含まれる。
パラメータ: `recording_id: string`
レスポンス: `{ id, filename, format, duration_sec, url, created_at, voice_type }`

### export_audio
署名付きダウンロード URL（1時間有効）を取得。
パラメータ: `recording_id: string`
レスポンス: `{ url, expires_at }`

### rename_recording
ファイル名を変更。
パラメータ: `recording_id: string, new_name: string`
レスポンス: `{ id, filename, updated_at }`

### duplicate_recording
録音をコピーして新しいレコードを作成。R2 ストレージは共有（コピーしない）。
破壊的編集前のバックアップに使う。
パラメータ: `recording_id: string, new_name?: string（省略時は "元の名前_コピー"）`
レスポンス: `{ recording_id, filename, duration_sec, original_recording_id }`

### delete_recording
録音を削除。取り消し不可。
パラメータ: `recording_id: string, confirm: boolean（true のみ実行）`
レスポンス: `{ ok: true }`

### trim_audio
録音の指定区間を切り出す。
パラメータ: `recording_id: string, start_sec: number, end_sec: number`
レスポンス: `{ recording_id, url, duration_sec }`

### reduce_noise
ノイズ（環境音・ハム音）を除去。
パラメータ: `recording_id: string`
レスポンス: `{ recording_id, url, duration_sec }`
注意: 処理に30〜120秒かかる場合がある。

### remove_fillers
フィラー語（えー・あのー・んー等）を自動検出して除去。要 AmiVoice API 設定。
パラメータ: `recording_id: string`
レスポンス: `{ recording_id, url, duration_sec, removed_count }`

### change_voice
ボイスチェンジを適用。
パラメータ: `recording_id: string, voice_type: string`
利用可能な voice_type:
  Free: pitch_up, pitch_down, child, robot, narrator
  Pro:  female, male, anime_girl, anime_boy, elder, whisper, echo,
        dark, bright, telephone, monster, alien, choir, helium, deep_bass
レスポンス: `{ recording_id, url, duration_sec, voice_type }`

### adjust_volume
音量をゲイン（dB）で調整。全体または区間単位。
パラメータ:
  `recording_id: string`
  `gain_db: number（全体ゲイン。0=変化なし、+6≈2倍、-6≈半分）`
  `segments?: Array<{ start_sec, end_sec, gain_db }>`
レスポンス: `{ recording_id, url, duration_sec, gain_db, segments_applied }`

### normalize_audio
音量を指定 LUFS に正規化。ポッドキャスト配信前の必須処理。
パラメータ: `recording_id: string, target_lufs: number（default=-14）`
一般的な基準: Spotify=-14LUFS, Apple Podcasts=-16LUFS, YouTube=-14LUFS
レスポンス: `{ recording_id, url, duration_sec, original_lufs_approx, target_lufs, gain_db_applied }`

### remove_silence
無音区間を自動検出して除去。デッドエア・間の詰めに使う。
パラメータ:
  `recording_id: string`
  `min_silence_sec: number（この秒数以上の無音を除去、default=1.0）`
  `threshold_db: number（無音と判断する dB 閾値、default=-40）`
レスポンス: `{ recording_id, url, duration_sec, removed_count, removed_sec, silence_intervals }`
silence_intervals: `Array<{ start_sec, end_sec }>`

### transcribe_recording
音声を文字起こし。
パラメータ: `recording_id: string`
レスポンス: `{ text, segments?: Array<{ start, end, text }>, language }`

### search_bgm
Jamendo CC（クリエイティブコモンズ）楽曲を検索。商用利用可能。
パラメータ:
  `query: string（キーワード、例: "calm piano", "upbeat electronic"）`
  `style?: "relaxing"|"upbeat"|"news"|"podcast"|"stylish"`
  `limit: number（default=5, max=20）`
レスポンス: `{ tracks: Array<{ id, name, artist, duration_sec, url, license, tags }>, query, total }`
url フィールドを bgm_url として add_bgm に渡せる。

### add_bgm
BGM を追加してミックス。project_name を指定するとマルチトラックプロジェクトも同時作成。
パラメータ:
  `recording_id: string`
  `position: "intro"|"outro"|"both"（default="intro"）`
  `style: "relaxing"|"upbeat"|"news"|"podcast"|"stylish"（default="relaxing"）`
  `bgm_url?: string（カスタム BGM URL、search_bgm の url フィールドを使用）`
  `bgm_duration?: number（BGM セグメント長の秒数、default=12）`
  `bgm_volume?: number（BGM 音量比、1.0=本編と同じ音量、default=0.18）`
  `project_name?: string（指定時: マルチトラックプロジェクトを自動作成）`
レスポンス:
  `{ recording_id, url, duration_sec, position, style,
     voice_duration_sec, bgm_url, bgm_duration_sec, bgm_volume, bgm_fade_sec,
     project_regions, project_id?, project_name? }`
project_regions: タイムライン構成（voice トラック + BGM トラック）の AudioRegion 配列

### concatenate_recordings
複数の録音を順番に結合。WebM 形式は非対応（WAV のみ）。
パラメータ: `recording_ids: string[]（結合順）, gap_seconds: number（録音間の無音、default=1.0）`
レスポンス: `{ recording_id, url, duration_sec, track_count, filenames }`

### pipeline
複数の処理をまとめて順番に実行。
パラメータ:
  `recording_id: string`
  `steps: string[]（例: ["noise", "filler", "bgm:both:podcast", "export"]）`
使用可能なステップ: noise, filler, voice:<type>, trim:<start>:<end>, bgm:<position>:<style>, export
レスポンス: `{ recording_id, url, steps_applied, duration_sec }`

---

## プロジェクト管理 API

プロジェクトは GUI エディタのタイムライン状態（voice/BGM/SE の複数トラック）を保存する。
AI で作成した構成をブラウザエディタで確認・微調整できる。

エディタ URL: `https://www.podvoice.jp/editor?project=<project_id>`

### list_projects
プロジェクト一覧。更新日時の降順。
パラメータ: なし
レスポンス: `Array<{ id, name, created_at, updated_at }>`

### create_project
プロジェクトを新規作成。recording_id を指定するとそのトラックが初期ロードされる。
パラメータ: `name: string, recording_id?: string`
レスポンス: `{ id, name, created_at, updated_at }`

### get_project
プロジェクトの詳細（state.regions を含む）を取得。
パラメータ: `project_id: string`
レスポンス: `{ id, name, state: { regions, trackVolumes?, trackMuted? }, created_at, updated_at }`

### describe_project
プロジェクトのタイムライン構成を AI が読みやすい形式で返す。
パラメータ: `project_id: string`
レスポンス: `{ project_name, total_duration_sec, track_count, timeline: Array<{id, type, name, start, end, duration, volume, fade}>, description }`

### rename_project
プロジェクト名を変更。
パラメータ: `project_id: string, name: string`
レスポンス: `{ id, name, updated_at }`

### delete_project
プロジェクトを削除。取り消し不可。録音は削除されない。
パラメータ: `project_id: string, confirm: boolean`
レスポンス: `{ ok: true }`

### list_project_regions
プロジェクトのトラック一覧（音量・フェード・位置情報付き）。
パラメータ: `project_id: string`
レスポンス: `{ project_name, region_count, regions: Array<{ id, type, name, startTime, duration, volume, fadeIn, fadeOut }> }`

### add_region_to_project
録音を既存プロジェクトのタイムラインに追加する。
パラメータ:
  `project_id: string`
  `recording_id: string`
  `type: "voice"|"bgm"|"se"（default="voice"）`
  `start_time?: number（開始秒。省略時は既存トラックの末尾）`
  `volume?: number（default=1.0）`
レスポンス: `{ id, name, updated_at, added_region: { id, type, startTime, duration } }`

### remove_region_from_project
プロジェクトから特定トラックを削除。録音本体は削除されない。
パラメータ: `project_id: string, region_id: string`
レスポンス: `{ id, name, updated_at, removed_region_id }`

### update_region
プロジェクト内の特定トラックの属性を更新。GUI の右クリックメニューと同等。
パラメータ:
  `project_id: string`
  `region_id: string（list_project_regions で確認）`
  `volume?: number（0〜4。1.0=等倍、0.5=半分、2.0=2倍）`
  `fade_in?: number（フェードイン秒数）`
  `fade_out?: number（フェードアウト秒数）`
  `name?: string（トラック名）`
  `start_time?: number（タイムライン上の開始秒）`
レスポンス: `{ id, name, updated_at, updated_region }`

---

## REST API エンドポイント一覧

認証: `Authorization: Bearer pv_xxxx`
ベース URL: `https://www.podvoice.jp`

| メソッド | パス | 説明 |
|---------|------|------|
| GET  | /api/recordings | 録音一覧 |
| GET  | /api/recordings/:id | 録音詳細 |
| PATCH | /api/recordings/:id | ファイル名変更 |
| DELETE | /api/recordings/:id | 録音削除 |
| POST | /api/recordings/:id/signed-url | ダウンロード URL 発行 |
| GET  | /api/mcp/status | 使用量確認 |
| POST | /api/mcp/trim | トリム |
| POST | /api/mcp/noise-reduce | ノイズ除去 |
| POST | /api/mcp/filler-remove | フィラー除去 |
| POST | /api/mcp/voice-change | ボイスチェンジ |
| POST | /api/mcp/transcribe | 文字起こし |
| POST | /api/mcp/adjust-volume | 音量調整 |
| POST | /api/mcp/normalize | 音量正規化 |
| POST | /api/mcp/remove-silence | 無音除去 |
| POST | /api/mcp/duplicate | 録音コピー |
| POST | /api/mcp/concatenate | 結合 |
| POST | /api/mcp/add-bgm | BGM追加 |
| GET  | /api/mcp/search-bgm | BGM検索 |
| POST | /api/mcp/pipeline | パイプライン実行 |
| GET  | /api/mcp/projects | プロジェクト一覧 |
| POST | /api/mcp/projects | プロジェクト作成 |
| GET  | /api/mcp/projects/:id | プロジェクト詳細 |
| PUT  | /api/mcp/projects/:id | プロジェクト更新 |
| DELETE | /api/mcp/projects/:id | プロジェクト削除 |
| GET  | /api/mcp/projects/:id/regions | リージョン一覧 |
| POST | /api/mcp/projects/:id/regions | リージョン追加 |
| DELETE | /api/mcp/projects/:id/regions | リージョン削除 |
| POST | /api/mcp/projects/:id/region | リージョン更新 |

---

## エラーレスポンス

| HTTP | 意味 | フィールド |
|------|------|----------|
| 400  | パラメータ不足・不正 | `{ error: string }` |
| 401  | 認証失敗 | `{ error: "Unauthorized" }` |
| 404  | リソース未存在 | `{ error: string }` |
| 429  | レート制限超過 | `{ error, remaining: 0, reset_at, upgrade_url }` |
| 500  | サーバーエラー | `{ error: string }` |

---

## プラン

| プラン | 月間 API 回数 | 価格 |
|--------|------------|------|
| Free   | 50回/月     | 無料 |
| Pro    | 無制限       | 980円/月（税込）|

毎月1日リセット。`get_status()` で残量確認可能。

---

## AudioRegion 型定義（プロジェクトの regions 配列要素）

```typescript
interface AudioRegion {
  id: string             // "voice-0", "bgm-0", "bgm-1", "se-0" など
  type: 'voice'|'bgm'|'se'
  name: string
  url: string            // 音声ファイルの直接 URL
  recordingId?: string   // recordings テーブルの ID（任意）
  startTime: number      // タイムライン上の表示開始位置（秒）
  duration: number       // 表示上の長さ（秒）
  volume: number         // 音量 (1.0=等倍)
  audioOffset: number    // 音声ファイル内の開始位置（秒）
  audioSpan: number      // 音声ファイル内の使用幅（秒）
  originalDuration: number  // 音声ファイルの全長（秒）
  fadeIn: number         // フェードイン秒数
  fadeOut: number        // フェードアウト秒数
  cuts: number[]         // 仕切り位置（秒）
  segStatus: ('play'|'skip'|'fold')[]
  segNames?: string[]
}
```

---

## 推奨ワークフロー例

### 1. フル処理パイプライン（プロ品質）

```
Step 1: normalize_audio(id, target_lufs=-14)  → id_norm
Step 2: remove_silence(id_norm, min_silence_sec=1.0)  → id_clean
Step 3: search_bgm(query="acoustic warm podcast")  → BGM URL を選択
Step 4: add_bgm(id_clean, position="both", bgm_url=<url>, project_name="EP01")
Step 5: describe_project(project_id)  → タイムラインを確認
Step 6: update_region(project_id, "bgm-0", volume=0.1, fade_in=4, fade_out=4)
Step 7: export_audio(bgm_recording_id)  → 完成ファイルをダウンロード
```

### 2. 複数録音の組み合わせ

```
Step 1: 各録音を normalize_audio で -14LUFS に統一
Step 2: concatenate_recordings([id1, id2, id3], gap_seconds=1)  → id_concat
Step 3: add_bgm(id_concat, position="both", style="podcast", project_name="今週号")
```

### 3. GUI で最終調整

```
プロジェクト URL: https://www.podvoice.jp/editor?project=<project_id>
- voice / BGM / SE が別レイヤーで表示される
- 右クリックでフェード・音量を微調整
- 「WAV 書き出し」ボタンで最終ミックス
```

---

## 注記

- 録音形式: WAV（48kHz ステレオ）推奨。WebM は concatenate 非対応。
- 処理時間: ノイズ除去・フィラー除去は長尺音声で数分かかる場合がある。
- BGM 楽曲: Jamendo の CC BY ライセンス。商用利用可能（クレジット表記推奨）。
- R2 保存: 処理結果は Cloudflare R2 に保存される。public_url で直接アクセス可能。