SonicCraft

SonicCraft

AI エージェント向けの宣言的で決定論的なオーディオエンジンです。 制作内容を YAML（または JSON）のタイムラインで記述します。誰が何を、どの順番で、どの音楽に合わせて、どの音量で話すかを指定します。SonicCraft はこれを TTS 音声、音楽のベッド、効果音に変換し、サイドチェーンによるダッキングでミックスして、EBU R128 のラウドネス目標に合わせてマスタリングします。また、実際にレンダリングした音声に合った WebVTT/SRT 字幕も生成します。CLI、MCP サーバー、エージェントスキルとして提供されています。

ウェブサイト · クイックスタート · AI エージェントから使う · MCP サーバー · エージェントスキル

AI エージェントから使う

このリポジトリへのリンクをエージェント（Claude Code、Codex、Cursor、Gemini CLI など）に渡し、たとえば 「https://github.com/user-github-me/soniccraft を使って、製品動画用に BGM 付きの 30 秒のナレーションを作ってください。」 と依頼します。必要な情報はすべて以下と AGENTS.md にあります。

1. CLI をインストールします（ビルド済みでチェックサム検証済みのため、Rust は不要です）。Homebrew、Scoop、Docker、Cargo も利用できます。詳しくはクイックスタートをご覧ください。

   curl -fsSL https://raw.githubusercontent.com/user-github-me/soniccraft/main/install.sh | sh   # macOS, Linux
   

   irm https://raw.githubusercontent.com/user-github-me/soniccraft/main/install.ps1 | iex        # Windows
   

2. タイムラインを作成します。 soniccraft init my-audio を実行すると、オフラインでレンダリングできるタイムラインが作成されます。Mac では macOS の音声が使われ、それ以外ではモックのテスト音声（実際の音声ではありません）が使われます。どこでも実際の音声を使うには、Kokoro または Piper（無料、ローカル）、あるいは ElevenLabs、OpenAI、Cartesia の API キーを利用します。詳しくはプロバイダーをご覧ください。soniccraft init --list でテンプレートを、soniccraft providers でここで使用できる音声を、soniccraft schema で JSON Schema を確認できます。エージェントスキルではフォーマットを説明しています。

3. チェックし、コストを確認して、レンダリングします。

   soniccraft validate my-audio/timeline.yaml           # errors with a code, line, column and fix hint
   soniccraft plan my-audio/timeline.yaml               # free dry run: timing, ducking, characters to synthesize
   soniccraft render my-audio/timeline.yaml --preview   # mastered audio, subtitles, manifest, preview page
   

SonicCraft をエージェントで継続して使うには、スキルと MCP サーバーを追加します。どちらも手順 1 の CLI を使います。Node.js 20 以降の場合は、何もインストールせずに MCP サーバーを実行することもできます。その場合は、以下の soniccraft mcp の代わりに npx -y soniccraft-mcp を使います。

エージェント	スキル	MCP サーバー
Claude Code	claude plugin marketplace add user-github-me/soniccraft を実行し、続けて claude plugin install soniccraft@soniccraft	プラグインに同梱、または claude mcp add soniccraft -- soniccraft mcp
Codex	npx skills add user-github-me/soniccraft -g -a codex	codex mcp add soniccraft -- soniccraft mcp
Cursor	npx skills add user-github-me/soniccraft -g -a cursor	.cursor/mcp.json に {"mcpServers": {"soniccraft": {"command": "soniccraft", "args": ["mcp"]}}} を記述
Gemini CLI など	npx skills add user-github-me/soniccraft -g（エージェントを選択）	同じ mcpServers エントリー（Gemini CLI の場合は ~/.gemini/settings.json）

このサーバーは、コンテナイメージとして公式 MCP レジストリにも io.github.user-github-me/soniccraft の名前で登録されています。詳しくはMCP サーバーとエージェントスキルをご覧ください。

理由

エージェントにBGM付きの2人の掛け合い解説を頼むと、たいていはffmpegのフィルターグラフを手作業で作成します。推測した発話時間から算出したadelayのオフセットにamixを加え、うろ覚えのsidechaincompressを使うこともあります。しかし、次のような問題が予測どおりに起こります。

• タイミングのずれや重なり。 合成音声の長さがエージェントの推測と完全に一致することはないため、セリフが重なったり、無音が生じたりします。また、スクリプトを編集するたびに、その後のオフセットがすべてずれます。
• ダッキングがない。 フィルターグラフでサイドチェーン圧縮を適切に設定するのは厄介なため、音楽が声をかき消すか、全体を通して音量が低すぎるかのどちらかになります。
• ラウドネスのばらつき。 プロバイダーや音声によって出力レベルが異なります。統合ラウドネスやトゥルーピークが測定されないため、仕上がりにばらつきが出て、クリッピングすることもあります。
• 字幕のずれ。 レンダリングされた音声ではなく、推定時間をもとに字幕が作成されます。
• 不透明でコストのかかる反復作業。 グラフに問題があると、原因の分かりにくいffmpegのエラーが発生し、再試行のたびにすべてのTTS呼び出しで再課金されます。

SonicCraft の仕組み

HyperFrames は、エージェントが宣言的な HTML を記述し、決定論的なレンダラーがフレーム精度の処理を行うことで、より優れた動画を作成できることを示しました。SonicCraft は同じ考え方をオーディオに適用します。エージェントは意図をデータとして記述し、コンパイラーがそれを検証して実際の長さを測定し、すべてのタイミングを整数のサンプルフレームで解決したうえで、Rust でネイティブにレンダリングします。同じタイムライン、TTS キャッシュ、バイナリを使えば、常にバイト単位で同一のオーディオ、字幕、マニフェストが生成されます。

version: "1.0"
output:
  format: "mp3"
  sample_rate: 48000
  bitrate: "320k"
  target_lufs: -16.0 # integrated loudness target, measured per EBU R128 / ITU-R BS.1770
  export_subtitles: true # Emits matching .vtt and .srt

tracks:
  - id: ambient_bed
    type: "music"
    source: "assets/audio/synthwave_loop.wav"
    loop: true
    volume: 0.65
    fade_in_ms: 1200
    fade_out_ms: 2500
    ducking:
      trigger_tracks: ["voice_primary", "voice_secondary"]
      reduction_db: -18.0
      attack_ms: 80
      release_ms: 350

  - id: voice_primary
    type: "speech"
    pan: -0.15 # Subtle left stereo placement
    sequence:
      - id: cue_01
        speaker: "narrator"
        provider: "elevenlabs"
        voice_id: "21m00Tcm4TlvDq8ikWAM"
        text: "Autonomous software development requires deterministic compilation targets."
      - pause_duration: 350ms
      - id: cue_03
        speaker: "narrator"
        provider: "elevenlabs"
        voice_id: "21m00Tcm4TlvDq8ikWAM"
        text: "By separating high-level planning from digital signal processing, systems eliminate runtime hallucinations."

  - id: voice_secondary
    type: "speech"
    pan: 0.15 # Subtle right stereo placement
    sequence:
      - id: cue_02
        start_relative:
          after_cue: "cue_01"
          offset_ms: 150
        speaker: "guest"
        provider: "local_kokoro"
        voice_id: "am_adam"
        text: "Exactly. SonicCraft treats audio composition the same way Hyperframes treated web-based video."

  - id: sfx_impact
    type: "sfx"
    source: "assets/sfx/whoosh.wav"
    volume: 0.8
    start_at_ms: 0

これは examples/tech-briefing/timeline.yaml です。soniccraft render を実行すると、次の処理が行われます。

1. すべてを一括で検証します。 未知のキー、スペルミスのある列挙値、参照先のないアンカー、音声の不足、ファイルの不足、API キーの不足をすべてまとめて報告します。各項目には、安定したコード、パス、行と列、および修正のヒントが含まれます。
2. 音声を合成してキャッシュします。 cue_01 と cue_03 は ElevenLabs に送信されます（単語のタイムスタンプ付き）。cue_02 はローカルの Kokoro-FastAPI サーバーに送信されます（local_kokoro は組み込みの kokoro プロバイダーのエイリアスです）。各結果はコンテンツハッシュでキャッシュされるため、後続のレンダリングでは変更された行の分だけ費用がかかります。
3. 音声レベルを調整します。 各キューの先頭と末尾の無音をトリミングし、-20 LUFS に正規化することで、クラウド音声とローカル音声のレベルをそろえます。
4. サンプルフレーム単位でタイムラインを配置します。 cue_01 は 0 から始まります。cue_02 は cue_01 の終了から 150 ms 後に始まります。cue_03 は cue_01 から 350 ms 後の連続した位置に配置されますが、そのスロットは cue_02 と重なります。そのため、デフォルトの重複ポリシー（push）により、cue_03 は cue_02 の終了から 350 ms 後へ自動的に移動し、休止時間を間隔として保ち、情報メッセージ cue_pushed を報告します。エージェントがタイミングを計算することなく、自然な 3 ターンのやり取りが実現します。
5. 音楽を配置します。 ベッドは長さが指定されていないループクリップのため、1.2 s のフェードインを付けてタイムラインの最後まで再生されます。タイムラインは最後の単語から 2.5 s 後に終了し（ベッドの fade_out_ms）、ベッドはその末尾の区間全体にわたってフェードアウトします。ウーシュ音は 0 で鳴ります。
6. ベッドの音量をダッキングします。 どちらかの音声が話している間、ベッドの音量を 18 dB 下げます。検出は音声自体の信号を対象に 80 ms の先読みで行われ（デフォルトではアタック時間が使われます）、最初の音節が聞こえる前にベッドの音量が下がります。350 ms かけて音量が戻り、デフォルトの 250 ms のホールドにより、ターン間の 150 ms の間隔がつながります。
7. パンを設定します。 2 つの音声を -0.15 と +0.15 に配置します（コンスタントパワー）。
8. ミックスをマスタリングします。 デフォルトの podcast プリセットを使い、統合音量を -16 LUFS、トゥルーピークの上限を -1.0 dBTP に設定します。音量ゲインと 4 倍オーバーサンプリングのトゥルーピークリミッターを反復適用し、0.2 LU 以内を目指します。目標に達するパスがない場合は、最も近いパスを採用し、どれだけ目標に届かなかったかを loudness_target_missed で示します。目標に到達できない場合は、目標値にかかわらず、平均リミッティングから 6 dB 以内で最も音量の大きいマスターを採用します。
9. エンコードします。 48 kHz、320 kbps の MP3 をネイティブにエンコードし、生成ファイルをデコードして測定します（コーデックによってピークが上限を超えた場合は再度リミッティングします）。配置済みの単語のタイミングから timeline.vtt と timeline.srt を生成し、ラベルを narrator と guest に設定します。

費用が発生する前に、soniccraft plan（エイリアスは dry-run）を実行すると、TTS API を呼び出さずに、推定時間に基づいた同じレイアウトを確認できます（JSON の簡略版、数値は推定値です）。

{ "valid": true, "duration_ms": 20616.9, "estimated": true,
  "items": [
    { "id": "cue_01", "kind": "cue", "start_ms": 0.0,     "end_ms": 4838.7,  "duration_source": "estimate" },
    { "id": "cue_02", "kind": "cue", "start_ms": 4988.7,  "end_ms": 10863.7, "duration_source": "estimate" },
    { "id": "cue_03", "kind": "cue", "start_ms": 11213.7, "end_ms": 18116.9, "duration_source": "estimate",
      "pushed_from_ms": 5188.7 } ],
  "synthesis": { "cues": 3, "cached": 0, "characters_to_synthesize": 276 } }

機能

• YAML または JSON で記述する Timeline DSL v1.0 と、公開済みの JSON Schema を提供します。厳格なバリデーションにより、未知のキーは「もしかして」のヒント付きでエラーになり、すべての問題が安定したコード、パス、行・列番号、機械的に適用できる修正とともに一度に報告されます。
• 計算不要のタイミング指定： キューとポーズの順次配置、絶対開始時刻、相対アンカー（after_cue、with_cue、before_cue。符号付きオフセット指定可）を、キュー、クリップ、トラック全体に設定できます。音声の重なりは自動的に解消されます（または、クロストーク用にキューごとに警告、拒否、許可を設定できます）。
• 8 種類の TTS プロバイダー： ElevenLabs、OpenAI 互換の /audio/speech サーバー、Cartesia、Kokoro（Kokoro-FastAPI）、Piper、macOS の say、任意のローカルコマンド、決定論的なモック音声に対応します。1 つのタイムラインで自由に組み合わせられます。階層化された音声設定を持つ話者レジストリも利用できます。
• 低コストで反復： コンテンツアドレス指定型の TTS キャッシュ、有料 API を呼び出さないドライラン（推定再生時間とプロバイダーごとの文字数を表示）、上限付きの並列処理、バックオフ付きの再試行に対応します。
• 音楽と効果音： ループ（シームレス、またはループ間のクロスフェード付き）、トリミング、3 種類のカーブによるフェード、クリップ間のクロスフェード、終端にフェードアウトの余韻が自動で追加される終端未指定のベッドに対応します。
• 実際の音声信号（またはタイムライン）を基準にしたサイドチェインダッキングに対応し、アタック、リリース、ホールド、ルックアヘッドを設定できます。
• 適切なラウドネス処理： ソースごとに BS.1770 で正規化した後、プリセット（ポッドキャスト -16、ストリーミング -14、放送 EBU R128 -23、ATSC A/85 -24 LUFS）に合わせてマスターを正規化し、オーバーサンプリング対応のトゥルーピークリミッターを適用します。非可逆形式の出力はデコードして納品時の状態で測定し、コーデックによるトゥルーピークとラウドネスのずれを補正します。
• ネイティブ DSP とエンコーダー： wav、mp3、flac は ffmpeg なしで対応し、ogg、opus、m4a は ffmpeg がインストールされている場合に対応します。16/24 ビット整数または 32 ビット浮動小数点、シード固定の TPDF ディザリングを利用できます。
• レンダリング済み音声から字幕を生成： WebVTT、SRT、単語ごとのタイムスタンプを含む JSON、HyperFrames 互換のトランスクリプトに対応します。話者ラベルとキューごとの字幕上書きも利用できます。
• サイドファイル： トラックごとのステム、決定論的なマニフェスト、波形、ダッキングエンベロープ、字幕を含む自己完結型の HTML プレビューを生成します。
• エージェント向けの機能： validate、plan、render、providers、voices から機械可読な --json レポートを出力できます。両方のプロトコル世代に対応する MCP サーバー、Agent Skill、Claude Code プラグインも提供します。

クイックスタート

ビルド済みバイナリをインストールします（チェックサム検証済み。Rust や C のツールチェーンは不要です）。

curl -fsSL https://raw.githubusercontent.com/user-github-me/soniccraft/main/install.sh | sh   # macOS, Linux: ~/.local/bin
brew install user-github-me/soniccraft/soniccraft                                            # Homebrew (macOS, Linux)

irm https://raw.githubusercontent.com/user-github-me/soniccraft/main/install.ps1 | iex        # Windows
scoop bucket add soniccraft https://github.com/user-github-me/scoop-soniccraft; scoop install soniccraft

Rust を使う場合：cargo binstall soniccraft は同じリリースバイナリをダウンロードし、cargo install --locked soniccraft はcrates.ioからビルドします（必要条件は以下を参照）。

ソースからビルドする場合。 必要条件：Rust 1.89 以降（rustup）と、同梱の LAME MP3 エンコーダー用の C ツールチェーン（cc と make：macOS では Xcode Command Line Tools、Linux では build-essential、Windows では Visual Studio Build Tools。NASM がインストールされていない場合は、環境に AWS_LC_SYS_PREBUILT_NASM=1 も設定してください）。 ffmpeg は任意です（ogg／opus／m4a 形式での出力、追加の入力形式に必要です）。ビルド済みバイナリにはこれらは不要です。以下を参照してください。

git clone https://github.com/user-github-me/soniccraft
cd soniccraft
cargo install --locked --path crates/soniccraft-cli    # installs `soniccraft` and `soniccraft-mcp` into ~/.cargo/bin
soniccraft --version

--locked を指定すると、Cargo.lock に記載された依存関係のバージョン（CI でテストされたもの）を使ってビルドします。

ビルド済みバイナリ。 各GitHub リリースには、Linux（x86_64-unknown-linux-gnu、aarch64-unknown-linux-gnu。glibc 2.35 以降）、macOS（aarch64-apple-darwin、x86_64-apple-darwin。macOS 11 以降）、Windows（x86_64-pc-windows-msvc）向けのアーカイブがあります。 soniccraft-v<version>-<target>.tar.gz（Windows では .zip）には、soniccraft、soniccraft-mcp、ライセンス文書、THIRD-PARTY-LICENSES.txt が含まれています。-no-mp3 アーカイブには LGPL の MP3 エンコーダーが含まれていないため、mp3 形式での出力には ffmpeg が必要です。sha256sum --check --ignore-missing SHA256SUMS（macOS では shasum -a 256 --check --ignore-missing SHA256SUMS）でダウンロードを検証してください。バイナリは公証されていません。macOS ではブラウザーでダウンロードすると隔離されます。xattr -d com.apple.quarantine soniccraft soniccraft-mcp で解除してください（curl と npm ランチャーではこの属性は設定されません）。

コンテナーイメージ。 各リリースは、ogg、opus、m4a 形式の出力用 ffmpeg を含むイメージ（linux/amd64、linux/arm64）として、ghcr.io/user-github-me/soniccraft にも公開されています。

docker run --rm -v "$PWD":/work ghcr.io/user-github-me/soniccraft render timeline.yaml
docker run -i --rm -v "$PWD":/work ghcr.io/user-github-me/soniccraft mcp --base-dir /work   # MCP on stdio

マウントしたディレクトリに書き込まれるファイルの所有者は uid 1000 です。自分のユーザーとして書き込むには、--user "$(id -u):$(id -g)" を追加してください。API キーは -e ELEVENLABS_API_KEY で渡してください（タイムラインには決して記載しないでください）。コンテナーでは macOS の say は使えません。モック音声、クラウドプロバイダー、またはローカルサーバーを使用してください。docker build -t soniccraft . でソースから同じイメージをビルドできます。

API キーをまったく使わずにデモをレンダリングします。

# macOS: Samantha and Daniel from macOS `say`, plus the built-in mock voice
soniccraft render examples/offline-demo/timeline.yaml --preview

# any OS: the same timeline with mock voices only
soniccraft render examples/offline-demo/timeline.mock.yaml

macOS で実行すると、examples/offline-demo/offline-demo.wav と、.vtt、.srt、.words.json、.transcript.json 形式の字幕、.manifest.json、offline-demo.preview.html が生成されます（ブラウザーで開くと、波形、ダッキングのエンベロープ、キャプションを確認できます）。エージェントが実行する一連の流れは次のとおりです。

soniccraft validate examples/offline-demo/timeline.mock.yaml          # errors, warnings, fix hints
soniccraft plan     examples/offline-demo/timeline.mock.yaml          # dry run: layout, ducking, cost
soniccraft render   examples/offline-demo/timeline.mock.yaml --json   # one JSON report on stdout

API キーとローカルの Kokoro サーバーを使って、README のタイムラインをレンダリングします。

export ELEVENLABS_API_KEY=...                                          # never put keys in timelines
docker run -d -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest
soniccraft render examples/tech-briefing/timeline.yaml

テンプレートから独自のプロジェクトを開始します（タイムラインと、音声アセット用に生成された仮データを書き込みます）。

soniccraft init my-episode --template two-person-podcast

CLI

soniccraft validate <TIMELINE> [--json] [--check-credentials]
soniccraft plan <TIMELINE> [--json]                      (alias: dry-run)
soniccraft render <TIMELINE> [-o PATH] [--format F] [--subtitles] [--stems] [--manifest] [--preview]
                  [--no-cache] [--cache-dir DIR] [--jobs N] [--json]
soniccraft schema [-o FILE]
soniccraft init [DIR] [--template NAME] [--list] [--no-assets] [--force]
soniccraft providers [--json]
soniccraft voices <PROVIDER> [--json]
soniccraft cache <info|clear> [--cache-dir DIR] [TIMELINE]
soniccraft mcp [--base-dir DIR] [--allow-command]

コマンド	内容
validate	タイムラインとその実行環境を解析して検証します（アセットが存在し、デコードできること、認証情報があり、その送信先ホストへの送信が許可されていること、ローカル TTS サーバーが応答すること、macOS の音声と piper モデルがインストールされていること、必要に応じて ffmpeg が利用可能であること、レンダリングがメモリ上限内に収まること、キャッシュの状態）。--check-credentials を指定すると、低コストの認証リクエストで API キーも検証します。
plan / dry-run	検証後、キャッシュ済みまたは推定された再生時間（モック音声は正確な再生時間）を使ってタイムラインを配置します。項目の時刻、重なりを避けるための移動、ダッキング領域、プロバイダーごとに合成するキャラクター、ASCII 図を表示します。有料 API は呼び出しません。
render	パイプライン全体を実行します。-o は出力パスを指定します（output.format が設定されていない場合に限り、拡張子で形式が決まります。format: wav のタイムラインを使って -o out.mp3 --format mp3 のように指定します）。--format では wav、mp3、flac、ogg、opus、m4a のいずれかを指定でき、両方の設定を上書きします。--subtitles、--stems、--manifest を指定すると、それぞれのエクスポートが有効になります（output.export_* フィールドと同様です）。--preview は <stem>.preview.html を書き出します。--no-cache はキャッシュ済みの TTS 音声を無視します（新しい結果は引き続きキャッシュされます）。--cache-dir はキャッシュの保存先を指定します。--jobs N は同時合成リクエスト数を制限します（既定値は 4 です）。レンダリングが成功した場合にのみ出力が配置され、SonicCraft の出力ではない既存ファイルが上書きされることはありません。
schema	タイムラインの JSON Schema を表示します。-o を指定するとファイルに書き出します。
init	テンプレートから DIR/timeline.yaml（DIR の既定値は現在のディレクトリ）と、手続き的に生成した参照先の音声アセットを書き出します（シームレスなシンセループと 3 つの SFX。決定論的に生成され、ロイヤリティフリーです）。テンプレート（--list）：offline-demo（macOS での既定値：システム音声とモック）、offline-demo-mock（その他の環境での既定値：どこでもレンダリング可能）、tech-briefing、two-person-podcast、voiceover-with-music、dialogue-crosstalk。--no-assets を指定するとタイムラインのみを書き出します。--force を指定しない限り、既存ファイルは上書きされません。
providers	組み込みプロバイダーの利用可否、認証情報の状態、既定の音声を一覧表示します。
voices	1 つのプロバイダーの音声を一覧表示します（API を呼び出す場合があります）。プロバイダー名の大文字と小文字、および - と _ の違いは区別されません。
cache	info は TTS キャッシュの保存先、エントリー数、サイズを表示し、clear はキャッシュを空にします。
mcp	MCP サーバーを stdio で実行します。--allow-command（または SONICCRAFT_ALLOW_COMMAND=1）を指定すると、タイムラインで command プロバイダーを実行できます。既定では拒否されます。

終了コード：0 は成功、1 はタイムラインが無効（エラー診断あり）、2 は使用方法のエラー、3 は実行時またはレンダリングの失敗、130 は中断です。--json を指定すると、標準出力には JSON ドキュメントが 1 つだけ出力されます（レポート、またはコマンドが失敗した場合は {"message", "diagnostics", "hint"}。使用方法のエラーも含みます）。進行状況とログは標準エラーに出力されます。実行環境やオプションによってレンダリングが停止した場合（キーがない、プロバイダーを実行できない、音声がインストールされていない、メモリ上限に達した場合など）も終了コードは 1 となり、error: render stopped: N errors で終了します。タイムライン（ファイル、FIFO、標準入力を表す -）は 5 MB のドキュメント上限まで読み込まれ、それ以上は読み込まれません。すべてのオプションについては soniccraft <command> --help を実行してください。

MCP サーバー

soniccraft mcp は stdio 経由でエンジンを提供します（改行区切りの JSON-RPC 2.0）。soniccraft-mcp は引数なしで起動できる同じサーバーです。どちらの MCP プロトコル世代にも対応しています。initialize ハンドシェイク（2024-11-05 から 2025-11-25 まで。Codex と Cursor が使用）と、server/discover を備えたステートレスな 2026-07-28 改訂版（Claude Code が最初に照会）です。

ツール	入力	結果
soniccraft_validate_timeline	{yaml_content?, yaml_path?, base_dir?, check_credentials?, detail?}（content/path のいずれか。path は yaml_path のエイリアスです）	ValidationReport
soniccraft_dry_run	{yaml_content?, yaml_path?, base_dir?, detail?}	PlanReport（テキスト形式の図を含む）
soniccraft_render	{yaml_content?, yaml_path?, output_path?, format?, base_dir?, export_subtitles?, no_cache?, detail?}	RenderReport
soniccraft_get_schema	{detail?}	DSL クイックリファレンス（detail: "full" の場合は JSON Schema も含む）
soniccraft_list_providers	{}	プロバイダー、利用可否（ローカルサーバーを確認）、認証情報の状態、デフォルトの音声
soniccraft_list_voices	{provider}	音声（プロバイダー API を呼び出す場合があります）

レポートは structuredContent として返されます（JSON テキストと短い要約も併せて返されます）。長いタイムラインは、エージェントのコンテキストで読みやすい状態を保つため、デフォルトではコンパクトなレポート（detail: "auto"）になります。すべての項目を取得するには、detail: "full" を渡してください。レンダリング結果には、音声と関連ファイルの file:// URI を含む resource_link ブロックが追加されます（2025-06-18 より前のプロトコルリビジョンのセッションでは、ファイルはテキストとして返されます）。音声が base64 としてインライン化されることはありません。format はタイムラインの output.format を上書きします（別の形式を指定する拡張子の output_path とともに渡してください）。mp3/ogg/opus/m4a の場合、レポートのラウドネスは出力ファイルの値を示します（マスターの値は loudness.pre_encode にあります）。無効なタイムラインでも validate/dry-run の呼び出し自体は成功します（valid: false）。レンダリングの失敗や不正な引数の場合は、修正箇所とともに isError: true が返されるため、エージェントは修正して再試行できます。相対パスは base_dir、soniccraft mcp --base-dir、CLAUDE_PROJECT_DIR、サーバーの作業ディレクトリの順に基準として解決されます。長時間のレンダリングでは notifications/progress が報告され、キャンセルも受け付けます。同時に実行できるのは最大 2 件です（SONICCRAFT_MCP_MAX_RENDERS）。各レンダリングでは最大 SONICCRAFT_MAX_RENDER_GB のメモリを使用できます（デフォルトは 8 GB）。そのため、サーバーのピークメモリ使用量はその合計（デフォルトでは 16 GB）に達する可能性があります。メモリの少ないマシンでは、どちらかの値を下げてください。タイムラインで command プロバイダーを実行するには、サーバーの起動時に soniccraft mcp --allow-command を指定する必要があります（セキュリティを参照）。ツールの引数とレポートの形式： skills/soniccraft/reference/mcp-tools.md。

Claude Code

claude mcp add soniccraft -- soniccraft mcp                    # local scope (default): this project, private to you
claude mcp add --scope user soniccraft -- soniccraft mcp       # all your projects
claude mcp add --scope project soniccraft -- soniccraft mcp    # writes .mcp.json to commit with the project
claude mcp add soniccraft -- soniccraft mcp --allow-command    # only if your timelines use `command` providers (they run local programs)

または、プロジェクトの .mcp.json に設定します（timeout は呼び出しごとの制限時間をミリ秒単位で指定します）。stdio サーバーは Claude Code の実行環境を引き継ぐため、エクスポート済みの API キーは env ブロックなしでサーバーに渡されます。

{
  "mcpServers": {
    "soniccraft": {
      "type": "stdio",
      "command": "soniccraft",
      "args": ["mcp"],
      "timeout": 900000
    }
  }
}

"env": {"ELEVENLABS_API_KEY": "${ELEVENLABS_API_KEY}"} は追加しないでください。変数が未設定の場合、クライアントは文字列 ${ELEVENLABS_API_KEY} をそのまま渡します。SonicCraft はこのようなプレースホルダーをキーがない状態として扱い、その旨を通知します（missing_credentials）。env エントリが必要な場合は、"${ELEVENLABS_API_KEY:-}" と記述してください。

Rust をインストールせずに使う場合は、npm 経由で利用できます（Node.js 20 以降）。soniccraft-mcp パッケージは、PATH に soniccraft があればそれを使用します。ない場合は、初回使用時にお使いのプラットフォーム向けのビルド済みリリースをダウンロードし、パッケージに固定された SHA-256 チェックサムと照合して検証します。npm の各バージョンは、GitHub Actions から provenance とともに公開された、リリースの soniccraft-mcp-X.Y.Z.tgz アセットです。

claude mcp add soniccraft -- npx -y soniccraft-mcp

{ "mcpServers": { "soniccraft": { "command": "npx", "args": ["-y", "soniccraft-mcp"] } } }

パッケージ名の後に続く引数は soniccraft mcp に渡されます（例：--base-dir）。 packages/soniccraft-mcp/README.md では、対応プラットフォーム、環境変数、プロキシ、オフラインインストールについて説明しています。以下の Cursor と Codex の設定でも、同じ npx 形式（コマンドは npx、引数は ["-y", "soniccraft-mcp"]）を使用できます。

Cursor：~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクト）：

{
  "mcpServers": {
    "soniccraft": {
      "type": "stdio",
      "command": "soniccraft",
      "args": ["mcp"],
      "env": { "ELEVENLABS_API_KEY": "${env:ELEVENLABS_API_KEY}" }
    }
  }
}

プロジェクトレベルのファイルでは、"CLAUDE_PROJECT_DIR": "${workspaceFolder}" を env に追加すると、ツール呼び出しの相対パスがワークスペースを基準に解決されます。キー変数が未設定で、クライアントがプレースホルダーテキストをそのまま渡した場合、SonicCraft はプレースホルダーを送信せず、キーが不足していることを報告します。

Codex

codex mcp add soniccraft -- soniccraft mcp

次に、~/.codex/config.toml でツールのタイムアウトを延長し（Codex のデフォルトは 60 s ですが、レンダリングにはそれ以上かかる場合があります）、使用する API キーを渡して、レンダリングツールの承認方法を決めます。

[mcp_servers.soniccraft]
command = "soniccraft"
args = ["mcp"]
env_vars = ["ELEVENLABS_API_KEY", "OPENAI_API_KEY", "CARTESIA_API_KEY"]
startup_timeout_sec = 20
tool_timeout_sec = 900
default_tools_approval_mode = "approve"   # needed for non-interactive `codex exec`, see below

soniccraft_render はファイルを書き込むため、Codex は実行前に確認を求めます。対話型セッションでは承認を求めるプロンプトが表示されます。非対話型の codex exec（承認ポリシーが never）では、サーバーエントリーで承認を設定しない限り、「MCP tool call requires approval」というエラーで呼び出しが失敗します。設定方法は、すべての SonicCraft ツールに対して default_tools_approval_mode = "approve" を指定する方法と、レンダリングツールのみに次の設定を行う方法があります。

[mcp_servers.soniccraft.tools.soniccraft_render]
approval_mode = "approve"

1 回の実行のみ設定する場合：codex exec -c 'mcp_servers.soniccraft.default_tools_approval_mode="approve"' ...。

エージェントスキル

skills/soniccraft/ は Agent Skills パッケージです。SKILL.md（ワークフロー、DSL の基本、時間の目安、ミキシングの実践方法、診断の修正表）と、必要に応じて参照する資料（DSL の完全なリファレンス、プロバイダー、ミキシングガイド、すべての診断コード、MCP ツール）、5 つのテンプレートが含まれています。CLI を中心に作成されているため、どのエージェントでも使用でき、代替手段として MCP ツールについても説明しています。

npx skills add user-github-me/soniccraft                                              # pick agents interactively
npx skills add user-github-me/soniccraft --skill soniccraft -a claude-code -a codex -a cursor -y   # project scope
npx skills add user-github-me/soniccraft --skill soniccraft -g -a claude-code -y                   # global

ディレクトリを手動でコピーすることもできます：cp -R skills/soniccraft ~/.claude/skills/（Claude Code、ユーザー用）、.claude/skills/soniccraft（Claude Code、プロジェクト用）、~/.agents/skills/soniccraft または .agents/skills/soniccraft（.agents/skills を読み込む Codex、Cursor、その他のエージェント用）。

Claude Code プラグイン（スキルと MCP サーバーを一度に導入します。PATH に soniccraft が必要です）：

claude plugin marketplace add user-github-me/soniccraft
claude plugin install soniccraft@soniccraft

プラグインの MCP サーバーが失敗として表示される場合、通常は soniccraft バイナリが PATH にありません。インストールして（クイックスタートを参照）、Claude Code を再起動してください。スキルのセットアップセクションでも、エージェントに同じ手順を案内しています。

Codex の場合、skills/soniccraft/agents/openai.yaml で MCP 依存関係を宣言し、soniccraft-mcp として起動します。

プロバイダー

プロバイダー	provider:	認証情報／セットアップ	デフォルトの音声	単語のタイミング
ElevenLabs	elevenlabs	ELEVENLABS_API_KEY	なし（voice_id が必要）	あり
OpenAI 互換	openai	OPENAI_API_KEY。その他のサーバーでは base_url	alloy	推定
Cartesia	cartesia	CARTESIA_API_KEY	なし（voice_id が必要）	あり
Kokoro（Kokoro-FastAPI）	kokoro	ローカルサーバー：KOKORO_BASE_URL（デフォルトは http://localhost:8880）、KOKORO_API_KEY は任意	af_heart	あり
Piper	piper	pip install piper-tts。音声モデル（voices_dir、PIPER_VOICES_DIR、またはタイムラインと同じ場所）	なし（voice_id が必要）	推定
macOS 音声	macos_say	macOS	Samantha	推定
カスタムコマンド	command	独自の argv テンプレート	なし（voice_id が必要）	推定
モック	mock	不要（決定論的な合成音声）	mock	正確

• ElevenLabs の音声は、デフォルトで未加工の pcm_24000 としてリクエストされます（設定された形式が利用中のプランで使えない場合も、pcm_24000 にフォールバックします）。eleven_v4 が受け付けるのは stability と similarity_boost のみです。
• openai は、OpenAI 互換の /audio/speech を利用する汎用クライアントです。OpenAI 独自の TTS モデルは 2027-01-06 に提供終了となるため、base_url を Kokoro-FastAPI、Speaches、LocalAI、またはその他の互換サーバーに設定してください。
• Cartesia は API バージョン 2026-08-14 を使用し、デフォルトは sonic-3.6 です。
• Kokoro：docker run -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:latest。単語のタイムスタンプは、字幕付き音声エンドポイントから取得します。soniccraft providers と validate は、ローカルサーバー（Kokoro-FastAPI、このマシン上またはプライベートネットワーク上の OpenAI 互換サーバー）を TCP 接続 300 ms で確認します。応答しないサーバーは利用できません（http://localhost:8880 で Kokoro-FastAPI サーバーから応答がありません）。また、validate は provider_unavailable を報告します。
• Piper は OHF-Voice/piper1-gpl としてメンテナンスされています。pip install piper-tts を実行してから、音声をプロジェクトにダウンロードします：python3 -m piper.download_voices en_US-lessac-medium --data-dir voices。次に、プロバイダーで voices_dir: voices を設定します（またはタイムラインの隣にダウンロードします）。voice_id: en_US-lessac-medium は、voices_dir、$PIPER_VOICES_DIR、タイムラインのディレクトリ、~/.local/share/piper/voices の順に検索されます。soniccraft voices piper は、見つかった内容、または検索対象ディレクトリとダウンロードコマンドを一覧表示します。また、モデルが見つからない場合、validate は unknown_voice を報告します。
• macOS の say は、名前が不明な場合にデフォルトの音声へ黙ってフォールバックするため、SonicCraft は事前に say -v '?' を使って音声名を確認します（validate では unknown_voice と、インストール済みの最も近い名前が表示されます）。
• API キーは、プロバイダー独自の API ホスト、このマシン上のサーバー（プロバイダー固有のキー変数（OPENAI_API_KEY など）のみ）、または SONICCRAFT_ALLOWED_HOSTS に記載されたホストにのみ送信されます。それ以外の場所に送信されるキーは、リクエストの前に拒否されます（provider_unavailable）。セキュリティを参照してください。

プロバイダーごとのセットアップ、モデル、音声、設定、制限： skills/soniccraft/reference/providers.md。

環境変数	用途
ELEVENLABS_API_KEY、OPENAI_API_KEY、CARTESIA_API_KEY	プロバイダーの API キー（api_key_env でインスタンスごとに変更できます）。
KOKORO_BASE_URL、KOKORO_API_KEY	Kokoro-FastAPI の場所と任意のキー。
PIPER_VOICES_DIR	<voice_id>.onnx の検索ディレクトリ（プロバイダーの voices_dir の次に検索されます）。
SONICCRAFT_ALLOWED_HOSTS	各プロバイダー独自の API ホストと、このマシン上のサーバー（プロバイダー固有のキー変数のみを受け取ります）に加えて、API キーの送信を許可するホスト（カンマ区切り、*.example.com 形式のパターン）。
SONICCRAFT_CACHE_DIR	TTS キャッシュの場所（--cache-dir で上書きされます）。
SONICCRAFT_MAX_RENDER_GB	1 回のレンダリングのメモリ上限（GB、デフォルトは 8）。これを超えるメモリが必要なタイムラインは、TTS リクエストの前に timeline_too_long で失敗します。
CLAUDE_PROJECT_DIR	MCP サーバー：呼び出しに base_dir がない場合の相対パスの基準ディレクトリ。
SONICCRAFT_ALLOW_COMMAND	MCP サーバー：1 にすると、タイムラインでローカルプログラムを実行できます（command プロバイダー、Piper の command）。デフォルトではオフです。soniccraft mcp --allow-command と同じです。
SONICCRAFT_MCP_MAX_RENDERS	MCP サーバー：同時に実行するレンダリング数（デフォルトは 2）。後続のレンダリングは待機します。

字幕と HyperFrames

output.export_subtitles には、true（= vtt + srt）、または vtt、srt、json、transcript のリストを指定します。 json（<stem>.words.json）には字幕と各単語のタイミングが格納されます。transcript （<stem>.transcript.json）は、HyperFrames の transcribe コマンドが読み込む形式の、秒単位の単語配列です。HyperFrames の動画に SonicCraft の ナレーションを付けるには、次のようにします。

soniccraft render voiceover.yaml            # with output.export_subtitles: [vtt, transcript]
npx hyperframes transcribe voiceover.transcript.json --dir my-video

また、コンポジションの開始時点からマスタリング済みの音声を再生するには、たとえば次のようにします。 <audio id="voiceover" src="assets/voiceover.wav" data-start="0" data-duration="21.04"></audio>。

決定性とキャッシュ

• 決定的な出力。 同じタイムライン、TTS キャッシュ、バイナリを使うと、音声、字幕、マニフェストはバイト単位で同一になります。レンダリングされた成果物に、壁時計のタイムスタンプ、乱数シード、ホスト名、絶対パスが混入することはありません。ディザとモック音声には固定シードを使用し、すべてのジオメトリは整数のサンプルフレームで扱います。ステージの所要時間とキャッシュ統計はライブレポートにのみ表示され、マニフェストには含まれません。そのため、ウォームキャッシュからのレンダリングでも、新規キャッシュからのレンダリングと同じマニフェストが書き込まれます。
• コンテンツアドレス方式の TTS キャッシュ。 各キューのキーは、音声に影響するすべての要素（プロバイダーの種類、API バージョン、デフォルト以外のベース URL、モデル、音声、言語、テキスト、設定、出力形式。command/piper の場合はテンプレート、プログラムとその内容のハッシュ、引数で指定されたファイル、piper モデルも含む）を含む正規化 JSON の blake3 ハッシュです。エントリーは <key>.wav（32 ビット浮動小数点、プロバイダーのネイティブレート、トリミング前）と <key>.json（メタデータと単語のタイミング）で、アトミックに書き込まれます。1 行を変更すると、そのキューだけが再合成されます。タイミング調整、再ミックス、再マスタリングにはコストがかかりません。キャッシュに書き込めない場合は cache_write_failed 警告が表示されますが、レンダリングは成功します。
• 保存場所： --cache-dir > SONICCRAFT_CACHE_DIR > <timeline dir>/.soniccraft/cache。 soniccraft cache info と soniccraft cache clear で管理できます。render --no-cache は再合成を行いますが、キャッシュは引き続き更新されます。
• 無料のドライラン。 plan は、利用可能な場合はキャッシュ済みの再生時間を使い、モック音声をプロセス内で正確にレンダリングし、残りをプロバイダーごとの発話速度（1 秒あたりの文字数）から推定します。プロバイダーは呼び出しません。

セキュリティ

タイムラインはデータであり、多くの場合、エージェントがどこかで見つけたテキストから作成するため、SonicCraft は信頼できないものとして扱います。

• シークレットをタイムラインに含めないでください。 タイムライン内の API キー、トークン、パスワード（api_key／token／secret／password という名前のキー、sk-... 形式の値、URL 内のパスワード、プロバイダーの command 内のキー）は secret_in_timeline エラーになり、診断情報に値が再掲されることはありません（CLI のスニペットでは <redacted> と表示されます）。キーは環境変数（api_key_env）からのみ取得されます。
• キーは適切な場所にのみ送信されます。 各プロバイダー独自の API ホスト、このマシン上のサーバー（プロバイダー独自のキー変数のみ：ローカルサーバーを指定した openai インスタンスには OPENAI_API_KEY、Kokoro には KOKORO_API_KEY）、または SONICCRAFT_ALLOWED_HOSTS に指定したホスト（soniccraft または MCP サーバーの環境変数で指定し、タイムラインには記述しません）に限られます。ホストが指定されていない限り、タイムラインから任意の環境変数（api_key_env: GITHUB_TOKEN など）をローカルサーバーに送信したり、ローカルネットワーク上の別のデバイスにキーを送信したりすることはできません。ネットワーク上の別の場所やリモートにある OpenAI 互換サーバー、リモートの Kokoro、またはリージョナルエンドポイントでキーを使うには、たとえば SONICCRAFT_ALLOWED_HOSTS=tts.example.com を設定します。それ以外は、リクエストを送信する前に拒否されます。リダイレクトは追跡されず、サーバーから返されたキーはメッセージから取り除かれます。
• ローカルプログラム： command プロバイダー（および独自の command を持つ piper）はプログラムを実行します。MCP 経由では、soniccraft mcp --allow-command（または SONICCRAFT_ALLOW_COMMAND=1）を指定して起動しない限り、サーバーは実行を拒否します。プログラムからプロバイダーの API キーを参照することはできず、独立したプロセスグループで実行されます（タイムアウトまたはキャンセル時にはグループ全体が終了します）。キューテキストはファイルまたは標準入力から渡されます。- で始まる引数は拒否されます。
• ファイル： 出力は一時ファイルに書き込まれ、レンダリング全体が成功した場合にのみ所定の場所に配置されます。レンダリングが失敗またはキャンセルされた場合、既存の出力は変更されません。既存のファイルは、同じ種類の出力でのみ置き換えられます（テキストファイルに対する -o notes.txt は拒否されます）。MCP 経由では、タイムライン自身の output.path はベースディレクトリ内に収める必要があります（明示的に指定する output_path 引数は任意の場所を指定できます）。
• 読み込み： タイムラインのサイズは最大 5 MB です。また、/dev/zero、FIFO、終わりのない標準入力は即座に失敗します。

リソース

レンダリング中、マスタリング済みのミックスはメモリに保持されます。トラックはウィンドウ単位でミックスされ、そのまま全長のマスターに出力されます。ステムはファイルにストリーミングされ、マスタリングはインプレースで行われます。測定されたピーク値（ステレオ、48 kHz）は、音楽が主体の場合、WAV、MP3、ogg、opus、m4a で出力 1 分あたり約 23 MB（10 分のベッド：245 MB）、音声が全編にわたる場合は 1 分あたり約 40 MB（16 分のナレーション：615 MB）です。エンコーダーがストリーム全体を保持する 24-bit FLAC では、1 分あたり約 85 MB です（10 分：870 MB）。SONICCRAFT_MAX_RENDER_GB（デフォルトは 8）はレンダリングの上限を設定します。これを超える必要があるレンダリングは timeline_too_long エラーとなり、TTS リクエストを送信する前に失敗します。validate／plan は事前に警告します。タイムラインの長さは最大 24 時間です。

アーキテクチャ

  timeline.yaml / .json
          |
          v
  +----------------+   diagnostics: code, path, line:col, hint
  | parse + lower  |-------------------------------------------------+
  | (core)         |                                                 |
  +-------+--------+                                                 |
          | IR (Program): resolved voices, defaults, anchors          |
          v                                                          |
  +----------------+  cached / estimated durations  +-------------+   |
  | synthesis      |------------------------------->|  layout     |   |
  | (tts + cache)  |  exact durations (render)      |  (frames)   |   |
  +-------+--------+                                +------+------+   |
          | audio + word timings                          | placements|
          v                                               v           v
  +------------------------------------------------------------+  reports:
  | DSP (dsp): decode -> resample -> trim -> normalize -> clips |  validate,
  | -> pan -> stems -> ducking -> master (R128 + true peak)     |  plan,
  +-------+----------------------------------------------------+  render
          |
          v
  encode (wav/mp3/flac native; ogg/opus/m4a via ffmpeg) + captions (vtt/srt/json/transcript)
  + stems + manifest + preview.html

クレート／ディレクトリ	責務
soniccraft-core	DSL の生 AST（serde + schemars）、ソーススパン付きの YAML／JSON 解析、診断、検証と IR への変換、JSON Schema の生成、静的なプロバイダーメタデータ。純粋で、環境変数を除き I/O は行いません。
soniccraft-layout	サンプルフレーム単位のタイムラインジオメトリ：スケジューリング、音声の重複ポリシー、クリップの長さ、コンテンツの終了位置と末尾、ASCII のプラン図。純粋です。
soniccraft-captions	単語のアラインメント（プロバイダーのタイミング情報または推定値）、字幕の分割、WebVTT／SRT／JSON／トランスクリプトの出力機能。
soniccraft-dsp	AudioBuffer、デコード（symphonia、ffmpeg によるフォールバック）、リサンプリング（rubato）、解析、クリップのレンダリング、パン、ダッキング、ラウドネス（ebur128）、トゥルーピークリミッター、マスタリングループ、エンコーダー（WAV、LAME MP3、FLAC。ogg／opus／m4a には ffmpeg を使用）。
soniccraft-tts	プロバイダートレイトと組み込みの 8 つのプロバイダー、コンテンツアドレス指定型キャッシュ、再生時間の推定、再試行と同時実行制御、認証情報の確認、音声の一覧表示。
soniccraft-engine	オーケストレーション：validate()、plan()（ドライラン）、render()、環境チェック、すべてのレポート型。
soniccraft-mcp	エンジンをツールとして公開する MCP stdio サーバー。
soniccraft（crates/soniccraft-cli）	soniccraft バイナリ（および soniccraft-mcp ランチャー）。人間が読みやすい形式と --json 出力に対応します。
packages/soniccraft-web-preview	依存関係ゼロの WebAudio ビジュアライザー。エンジンには render --preview 用として、ベンダー化したコピー（crates/soniccraft-engine/assets/preview.html）が組み込まれています。
packages/soniccraft-mcp	npm ランチャー（npx -y soniccraft-mcp）。リリースバイナリを検索またはダウンロードして、soniccraft mcp を実行します。
skills/soniccraft	エージェントスキル：SKILL.md、リファレンス、テンプレート。
examples	ロイヤリティフリーでプロシージャルに生成されたアセットを使用する、実行可能なタイムライン。

依存関係は一方向です：layout → core、tts → {core, dsp}、engine → {core, layout, captions, dsp, tts}、mcp → engine、cli → {engine, mcp}。仕様全体は docs/DESIGN.md、パイプラインをたどるコントリビューター向けの解説は docs/architecture.md をご覧ください。

ロードマップ

• フェーズ 1：DSL とコンパイラー（v0.1 で実装済み）
  • Timeline DSL v1.0（YAML/JSON）、JSON Schema、「もしかして」候補のヒント付き厳密検証
  • 解決済み IR への変換：ボイス、プロバイダー、デフォルト値、アンカー、依存関係のチェック
  • サンプル単位の正確なレイアウト、音声の重なりに関するポリシー、ドライラン計画、ASCII 図
• フェーズ 2：合成（v0.1 で実装済み）
  • 8 つのプロバイダー：ElevenLabs、OpenAI 互換、Cartesia、Kokoro、Piper、macOS say、command、mock
  • コンテンツアドレス指定キャッシュ、再生時間の推定、同時実行数の制限、再試行、認証情報のチェック
• フェーズ 3：ネイティブ DSP とマスタリング（v0.1 で実装済み）
  • デコード、リサンプリング、無音部分のトリミング、ソースの正規化、ループ、フェード、クロスフェード、パン
  • サイドチェーンとキュー駆動のダッキング、EBU R128 マスタリングループ、オーバーサンプリング対応のトゥルーピークリミッター
  • WAV/MP3/FLAC エンコーダー、ffmpeg 経由の ogg/opus/m4a
• フェーズ 4：エージェント向けインターフェイスと出力（v0.1 で実装済み）
  • WebVTT、SRT、JSON の単語タイムスタンプ、HyperFrames トランスクリプト
  • --json 対応 CLI、MCP サーバー（両方のプロトコル世代）、Agent Skill、Claude Code プラグイン
  • ステム、マニフェスト、ウェブプレビュー、生成済みアセットを含むサンプル
• フェーズ 5：配布（v0.1）
  • リリースワークフロー：macOS、Linux、Windows 向けのビルド済みバイナリ（LGPL MP3 エンコーダーあり・なし）、SHA256SUMS、サードパーティのライセンス通知、soniccraft-mcp npm ランチャー
  • パッケージマネージャー：ワンライナーインストーラー（install.sh、install.ps1）、Homebrew tap、Scoop bucket、コンテナーイメージ
  • プロジェクトの GitHub オーナー配下での掲載：公式 MCP Registry （io.github.user-github-me/soniccraft）、このリポジトリの Claude Code プラグインマーケットプレイス、 npx skills add 用 Agent Skill
  • crates.io：cargo install soniccraft と cargo binstall soniccraft
  • npm：npx -y soniccraft-mcp（リリースバイナリをダウンロードして検証する MCP サーバー）
  • 厳選ディレクトリ：Anthropic プラグインディレクトリと Cursor Marketplace

コントリビューション

CONTRIBUTING.md を参照してください。各コンポーネントの動作は docs/DESIGN.md に仕様として記載されています。仕様とコードは一緒に変更してください。

ライセンス

SonicCraftは、Apache License, Version 2.0またはMIT licenseのいずれかのライセンスの下で、利用者の選択によりライセンスされます。明示的に別段の定めをしない限り、Apache-2.0ライセンスで定義される、本プロジェクトへの収録を目的として意図的に提出されたすべてのコントリビューションは、追加の条件を付けずに上記の両ライセンスの下でライセンスされます。

ネイティブのMP3エンコードにはLAME 3.100（LGPL-2.0-or-later）を使用し、mp3lame-sysおよびmp3lame-encoderクレート（LGPL-3.0）を通じて静的にリンクします。これはデフォルトで有効なcargo機能mp3の背後にあります。除外するには、--no-default-featuresを指定してビルドしてください（例：cargo install --locked --path crates/soniccraft-cli --no-default-features）。その場合、MP3出力には、利用可能であればffmpegを使用します（それ以外の場合はformat_requires_ffmpeg）。-no-mp3リリースアーカイブはこの方法でビルドされており、LGPLコードは含まれていません。それ以外のリリースアーカイブにはlicenses/内にライセンステキストが含まれており、licenses/README.mdでは、変更を加えたLAMEを使用してsoniccraftを再ビルドする方法を説明しています。オーディオのデコードにはsymphoniaを使用し、dirsはoption-extを使用します。どちらもMPL-2.0（ファイル単位のコピーレフト）であり、変更せずに使用し、ソースコードはcrates.ioで公開されています。それ以外のすべての依存関係は、寛容なライセンス（MIT、Apache-2.0、BSD-3-Clause、ISC、Zlib、Unicode-3.0）の下にあります。各リリースアーカイブには、コンパイルされたすべてのクレートと、それらのクレートに同梱されているライセンステキストがTHIRD-PARTY-LICENSES.txtに記載されています。また、CIではcargo-deny（deny.toml）を使ってこのポリシーを強制しています。

examples/*/assets/内のサンプルオーディオは、scripts/generate-example-assets.shによってゼロから合成されており、同じライセンスが適用されます。