Source Command Sfx

source-command-sfx

Use this skill when the user asks to run the migrated source command sfx.

Command Template

• /sfx "<prompt>" — minimum form. Defaults: 2s, no loop, apps/web/public/sfx/misc/, mp3_44100_128.
• /sfx <class> "<prompt>" — class drives the output subdirectory. Valid: ui, foley, cinematic, mechanical, ambience, event, misc. Path becomes apps/web/public/sfx/<class>/.
• /sfx <class> <name> "<prompt>" — name becomes the filename stem (<name>.mp3). Without a name, the MCP picks one.
• /sfx <class> <name> <duration>s "<prompt>" — explicit duration in seconds (0.5–5).
• /sfx <class> <name> <duration>s loop "<prompt>" — loop ON.

If invoked with no prompt at all, ask the user for one or hand off to the sound-design skill to author one.

1. Validate

• Prompt length: warn if < 10 words (likely too generic) or > 60 words (likely contradictions). Don't block — warn and proceed.
• Duration: clamp to [0.5, 5]. The MCP rejects values outside this range. If the user requested > 5s, tell them and proceed at 5s, OR ask if they want to chain calls / switch to the public UI.
• Loop sanity check: if loop: true and the prompt looks event-shaped (contains "slam", "click", "hit", "impact", "shot", "drop", "snap"), warn the user — looping makes no sense for transient events. Ask before flipping it off.
• Multi-event sanity check: if the prompt contains commas-then-conjunctions like "then", "followed by", "and then", "after that" implying a sequence of distinct events, stop and route to the sound-design skill — the consolidated framework's load-bearing rule is "one event per generation".

2. Resolve the output path

• Class → subdirectory: apps/web/public/sfx/<class>/ (default misc).
• Create the directory if it doesn't exist (mkdir -p).
• Filename: if the user provided one, use <name>.mp3 (or matching extension for chosen output_format). If not, let the MCP name it.
• Never save outside apps/web/public/sfx/ without explicit user override — that directory is the project convention for static SFX served by Vite.
• Confirm the path back to the user before generating, so they can redirect if needed.

3. Call the MCP

mcp__elevenlabs__text_to_sound_effects(
  text:              "<the six-slot prompt>",
  duration_seconds:  <0.5–5, default 2>,
  loop:              <true|false, default false>,
  output_directory:  "<absolute path to apps/web/public/sfx/<class>/>",
  output_format:     "mp3_44100_128",  // override only on user request
)

This is a paid API call. The MCP tool's own description carries a cost warning. Each call generates ONE file (the MCP returns one variation, not the four the public UI returns). If the user might iterate, warn them up front: "I'll generate one variation. If it misses, we re-prompt — each call has a credit cost."

4. After the MCP returns

• Surface the saved file path to the user — exact, copyable.
• Show the prompt, duration, and loop flag that produced it (so the user has the recipe).
• DO NOT auto-play. If the user asks, call mcp__elevenlabs__play_audio with the returned path.
• DO NOT auto-git add. Tell the user the file is on disk; they decide whether to track it.

5. If iteration is needed

If the user is dissatisfied, do NOT immediately call /sfx again with the same prompt. Hand off to the sound-design skill which owns the iteration protocol (change one slot, simplify, add naturalism cues, etc. — see docs/sound-design/CONSOLIDATED.md). One regen with the same prompt is a coin flip; the framework gets you to "right" in 2–3 deliberate iterations.

SAVED:    <absolute path>
DURATION: <Ns>
LOOP:     <true|false>
PROMPT:   "<the prompt that produced it>"

Play it?  Say "play" — I'll call mcp__elevenlabs__play_audio.
Iterate?  Tell me what's off; I'll route to the sound-design skill for round 2.