mcpField
T
text-to-sfx

text-to-sfx

github.com/sonilo-aiクリエイティブ・メディア1171.4k 回インストール1 日前に更新
リポジトリ

text-to-sfx について

text-to-sfxは、動画を使わずテキストの説明から単一の効果音を生成するSoniloのスキルです。単独の効果音を必要とする制作者向けで、MCPツールまたはCLIから音声ファイルを取得できます。

主な機能

  1. 01テキストから単一の効果音を生成
  2. 02クリップの長さを指定可能
  3. 03WAV、MP3、AAC、FLACに対応
  4. 04MCPとCLIから利用
  5. 05生成タスクを自動でポーリング

活用シーン

  1. 01説明文からUIチャイムを作成
  2. 02編集で重ねるウーシュ音の生成
  3. 03映像素材なしでフォーリー効果を作成

MCP 対応

`text_to_sfx` MCPツールは説明と任意の設定を受け取り、非同期の生成タスクをポーリングして保存先のパスを返します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/sonilo-ai/skills --skill text-to-sfx

インストール後、Claude Code で/text-to-sfxを入力して読み込まれたか確認します。

詳細

Sonilo Text-to-SFX

テキストの説明から単一の効果音を生成します。動画は必要ありません。 プロンプトがそのまま入力になるため、動作や素材を直接説明してください。生成はバックエンドで非同期タスクとして実行され、ツールが内部でポーリングして、保存済みのファイルを返します。

セットアップ： setup-api-key スキルを参照してください。

⚠️ 料金： このツールは、料金が発生する可能性のある API 呼び出しを行います。明示的に依頼された場合にのみ呼び出してください。

映像に音を合わせますか？ video-to-sfx を使用してください。カットを読み取り、特定のタイミングに音を合わせられますが、テキストプロンプトではできません。

トランスポート：MCP または CLI

セッションの開始時にどちらか一方を選び、その方法を使い続けてください。1 つのジョブ内で両方を混在させないでください。また、選択した方法をユーザーに伝える必要はありません。

  1. このセッションで Sonilo MCP ツール（text_to_sfx など）が使用できる場合 — それらを使用してください。シェルが不要で、非常に長い生成処理にも対応できる唯一の推奨方法です。入力内容の問題ではなく、認証に失敗した場合は、このセッションではこのトランスポートを使用できません。再試行せず、2 に進んでください。
  2. 使用可能な Sonilo MCP ツールはないものの、sonilo account が終了コード 0 を返す場合 — 以下の CLI コマンドを使用してください。同じ API、同じアカウント、同じ認証情報ファイルを使います。sonilo whoami ではなく、sonilo account で確認してください。whoami はサインアウト中でも終了コード 0 を返すため、2 つの状態を区別できません。
  3. どちらも使えない場合 — 処理を止めて、setup-api-key スキルを実行してください。回避策として api.sonilo.com に curl でリクエストを送らないでください。どちらのトランスポートも、単純なリクエストでは対応できないアップロード、ポーリング、再試行を処理します。

クイックスタート

MCP ツール呼び出し（推奨）
text_to_sfx(
    prompt="Thunder rumbling in the distance with light rain",
    duration=6
)
Python（pip install sonilo）
from sonilo import Sonilo

client = Sonilo()  # reads SONILO_API_KEY

sfx = client.text_to_sfx.generate(prompt="Thunder rumbling in the distance with light rain", duration=6)
sfx.save("thunder.m4a")
JavaScript / TypeScript（npm install sonilo）
import { SoniloClient } from "sonilo";

const client = new SoniloClient(); // reads SONILO_API_KEY

const sfx = await client.textToSfx.generate({
  prompt: "Thunder rumbling in the distance with light rain",
  duration: 6,
});
CLI（npm install -g sonilo-cli または pip install sonilo-cli）
sonilo text-to-sfx --prompt "Thunder rumbling in the distance with light rain" --duration 6

内部では常に非同期で実行されます。CLI が送信とポーリングを代行します。--format では wav|mp3|aac|flac を指定できます。

cURL（MCP ホストを介さない REST API への直接リクエスト）
curl -X POST "https://api.sonilo.com/v1/text-to-sfx" \
  -H "Authorization: Bearer $SONILO_API_KEY" \
  --data-urlencode "prompt=Thunder rumbling in the distance with light rain" \
  --data-urlencode "duration=6"
# -> {"task_id": "..."}  poll GET /v1/tasks/{task_id} until status is succeeded/failed

エンドポイントは {"task_id": ...} を返し（HTTP 202）、status が終端状態になったら GET /v1/tasks/{task_id} で結果を取得します。MCP ツールはこのポーリングを代行し、保存先のパスを直接返します。呼び出しがタイムアウトした場合に限り、task_id が表示されます（task-recovery を参照）。

ツール

ツール説明
text_to_sfx(prompt, duration?, audio_format?, output_directory?)テキストの説明のみから、効果音のクリップを 1 つ生成します。

パラメーター

パラメーター型デフォルト備考
promptstring—必須です。1～2000 文字。
durationnumberSonilo のデフォルト値、8 秒任意です。0.5～180 秒を指定できます。ユーザーが長さを指定していない場合は省略し、勝手に設定しないでください。小数値も指定できます。ラッチやクリック音などの短い効果音は、1 秒未満で十分です。
audio_formatstringaac（.m4a）wav、mp3、aac、flac のいずれかです。
output_directorystringSONILO_MCP_BASE_PATH絶対パス、またはベースパスからの相対パスを指定します。

プロンプトの作成

プロンプトだけが入力です。対応させる映像はありません。動作や素材を 直接説明し、要素を組み合わせてください。「雨」よりも「トタン屋根に降る激しい雨」のほうが効果的です。演出を加えた効果音には「映画風のブラム音、ホラー」や「8 ビット風のレトロなジャンプ音」のように指定します。動画向けの場合と同じ素材の語彙やサウンドバンドルの考え方が適用できます。references/sfx-prompting.md を参照してください。

まず 1 回生成し、再抽選するのではなくプロンプトを調整してください。失敗した実行では料金が自動的に返金されますが、ユーザー自身による再試行は新たな課金になります。

ワークフローのヒント

  • これは映像の文脈がない単一のクリップ向けです — UI チャイム、ヒュッという効果音、自分で重ねるフォーリー要素などです。ユーザーが映像素材を持っている場合は、代わりに video-to-sfx を使用してください。
  • 長さの指定は任意です。指定されていない長さを勝手に設定しないでください。 ユーザーが指定した長さを渡してください。指定がない場合は duration を省略すると、Sonilo がデフォルトの（8 s）を使用します — 長さがユーザーにとって実際に重要な場合にのみ確認してください。
  • 音楽と混同しないでください。 バックグラウンドスコアやサウンドトラックには、text-to-music または video-to-music を使用してください。

タイムアウトした呼び出しからの復旧

バックエンドではすでに非同期で処理されます。リクエストが上流の処理能力不足で長時間キューに入る場合があるため、このツールは少なくとも 45 分間（TIME_OUT_SECONDS の値がそれより大きい場合はさらに長く）ポーリングします。それでも MCP ホストが独自のツール呼び出しタイムアウトによって、より早く呼び出しを中断することがあります。呼び出しがタイムアウトした場合、エラーには task_id が含まれます — ジョブは実行を続け（料金もすでに発生しています）。後で get_sfx_task(task_id)（ホスト型サーバーでは get_generation_task(task_id)）を呼び出して結果を取得してください。task-recovery を参照してください。

出力ファイル

指定された audio_format（.wav／.mp3／.flac、または aac のデフォルトである .m4a）で保存されます。ファイル名はプロンプト（スラッグ化したもの）または sfx-<first 8 chars of the task id> に基づきます。

エラー処理

よくあるエラー：401 無効なキー、402 残高不足／トライアルの上限到達、422 無効なパラメーター（例：長さが範囲外）、429 レート制限。account スキルを参照してください。

コメント

Markdown 対応