Update to Visual Sandbox

{
  "description": "Generate sound effects, full music tracks, spoken voiceovers and new voices designed from a description via Visual Sandbox. Trigger when the user wants short SFX, ambient audio, background music, a soundtrack, a voiceover, narration, text to speech or a custom voice via the vsb CLI. SFX and speech runs are quick; music scales with track length. Submit with `--async` then poll with `vsb status` for anything long.\n",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 280
    }
  ],
  "name": "vsb-audio",
  "skill_md_contents": "---\nname: vsb-audio\nrenamed_from: audio\ndescription: >\n  Generate sound effects, full music tracks, spoken voiceovers and new\n  voices designed from a description via Visual Sandbox. Trigger when the\n  user wants short SFX, ambient audio, background music, a soundtrack, a\n  voiceover, narration, text to speech or a custom voice via the vsb CLI. SFX and speech runs are quick; music scales\n  with track length. Submit with `--async` then poll with `vsb status`\n  for anything long.\nlicense: Proprietary. See LICENSE for the terms.\n---\n\n# Audio generation with vsb\n\n> **On the MCP surface?** If the `visual-sandbox` MCP tools are in your\n> tool list, use `generate` and `get_job` instead of the shell commands\n> below. The model choice and the prompt craft on this page still apply.\n> See `vsb` → Two ways to run.\n\nFour jobs: sound effects, music, speech and voice design. Short SFX finishes in\n5–30 seconds and a few hundred characters of speech in a few seconds\n(sync is fine); music can take longer, so prefer `--async` + `vsb status`\nfor tracks over ~60s.\n\nStart every run in a **background shell** (Claude Code: `run_in_background:\ntrue`) so the turn stays free, and put the wait loop there too — the shell's\nexit is the \"done\" signal. `vsb status` never waits on its own. Rules in\n`vsb` → Background generations.\n\n## What's live\n\n| Task | Slug | Notes |\n|------|------|-------|\n| Sound effects (0.5–30s clips) | `audio/elevenlabs-sound-fx` | ElevenLabs. Foley, ambient, transitions, UI sounds. Loop mode for tiling beds. |\n| Voiceover or narration from a script (text to speech) | `audio/elevenlabs-tts` | ElevenLabs. 21 stock voices (`--voice`, default `george`), or a voice you designed (`--my_voice <name>` or `--designed_voice <sample url>`, see below). No voice cloning: a recording of a real person is refused. `--mode v4` (default) is the newest and most natural and follows audio tags like `[whispers]`, 10,000 characters per run; `v3` also follows tags, 5,000; `multilingual-v2` reads long narration more evenly, 10,000; `flash-v2.5` costs half as much, 40,000. Billed per character. |\n| Voiceover or narration at a much lower rate, or in a language ElevenLabs does not cover | `audio/gemini-3.8-flash-tts` | Google's flagship voice. 30 voices (`--voice`, default `Kore`), over 130 languages detected from the text, 10,000 characters per run, WAV out. Pauses and sounds come from inline tags in English: `<laugh>`, `<sigh>`, `<short pause>`. One voice per run. No designed voice, no cloning, no `[square bracket]` tags. Billed per character. |\n| Many short reads, read-aloud lines or a cheap first draft | `audio/gemini-3.8-flash-lite-tts` | The faster, cheaper Gemini 3.8 voice: about a third less than Flash. The same voices, tags and limit, over 100 languages. Switch to `audio/gemini-3.8-flash-tts` for the final take of a long or emotional read. Billed per character. |\n| A new voice from a written description | `audio/elevenlabs-voice-design` | ElevenLabs Voice Design v3. Returns one MP3 sample of a new voice reading one line. A sample is an audition, not the voiceover: pass it to `audio/elevenlabs-tts` as `--designed_voice`. Run again for another take. Billed per character of the sample line. The web Composer runs one design per click. Safety-filtered: a description that reads as a child, like \"girl\", is refused; \"woman\" passes. Not voice cloning. |\n| Speak a recording again in another voice (voice changer, speech to speech) | `audio/elevenlabs-voice-changer` | ElevenLabs. Takes an audio or a video file of up to 5 minutes and one of the voices TTS takes: `--voice`, `--designed_voice` or `--my_voice`. Keeps the words, the timing and the emotion; only the voice changes. Use it to put one voice back on clips that a video model voiced itself. Billed per minute of the recording: the quote holds 5 minutes, then drops to the real length. |\n| Music (10s–5min tracks) | `audio/eleven-music` | ElevenLabs music_v2. Full structured tracks, vocals (model-written or your own lyrics) or instrumental. 48 kHz MP3. |\n| Full song or instrumental from a style description | `audio/minimax-music-2.6` | MiniMax. One flat price per track whatever the length, so long songs are cheapest here. Own lyrics with section tags, auto-written lyrics, or instrumental. It honours a stated key and BPM. You cannot set the length: expect two to four minutes. |\n| Re-sing a song you already have in a new style | `audio/minimax-music-cover` | MiniMax. The only model that takes a recording as input. Anchors on the melody and swaps the voice, instruments and arrangement, with optional replacement lyrics. The source needs audible singing, and the melody can still drift, so listen before you use it. |\n| Speech-to-text | `audio/scribe` | Transcription, not generation — see `vsb-subtitles`. |\n\n(Verify the live catalog with `vsb models --modality audio --json` before\ntrusting this list.)\n\n## ElevenLabs Sound FX\n\n```bash\nvsb run audio/elevenlabs-sound-fx \\\n  --prompt \"footsteps on wet pavement at night, slow walk, distant traffic\" \\\n  --duration_seconds 10 --json\n```\n\n- `duration_seconds` is a preset: `auto`, `2`, `5`, `10`, `15`, `20`, `30`.\n  `auto` lets the model pick — good for one-shots.\n- `prompt_influence`: `loose` / `balanced` / `strict`.\n- `loop true` produces clips that tile cleanly (beds, rain, room tone).\n\n### Prompt patterns for SFX\n\nDescriptive, sensory, concrete:\n\n- Good: \"heavy wooden door creaking open, then slamming shut\"\n- Good: \"thunder rumbling in the distance, light rain on a tin roof\"\n- Bad: \"scary music\" → that's `audio/eleven-music`\n- Bad: \"happy\" → too abstract, the model won't know what *sounds* happy\n\n## ElevenLabs Text to Speech\n\n```bash\nvsb run audio/elevenlabs-tts \\\n  --prompt \"[excited] We did it! [laughs] Okay... now the hard part.\" \\\n  --voice george --mode v4 --json\n```\n\n- The flag is `--mode`, not `--version`: the CLI owns `--version`. Values:\n  `v4` (default), `v3`, `multilingual-v2`, `flash-v2.5`. Limits are in the table.\n- `--voice` takes one of 21 stock keys: `adam`, `alice`, `bella`, `bill`,\n  `brian`, `callum`, `charlie`, `chris`, `daniel`, `eric`, `george`,\n  `harry`, `jessica`, `laura`, `liam`, `lily`, `matilda`, `river`,\n  `roger`, `sarah`, `will`. `vsb schema audio/elevenlabs-tts --json`\n  lists them.\n- Audio tags (`[whispers]`, `[laughs]`, `[sighs]`, `[excited]`) work in\n  `v4` and `v3` only. Put the tag where it should happen. Remove the tags before\n  you switch to another mode. The voice limits what a tag can do: a calm\n  voice does not shout on cue.\n- Pauses come from commas and `...`. `v3` takes no SSML break tags.\n- Spell hard names the way they sound, and write numbers and dates as\n  words. `flash-v2.5` reads numbers the least reliably.\n- Text over the mode's limit is rejected before any charge. About 1,000\n  characters make a minute of speech. Split a longer script at paragraph\n  breaks and run each part.\n- The MP3 is a voice track for `video/p-video-2` (`--audio`, the cheapest\n  way to keep one voice across shots), `video/kling-avatar-v2` (a photo\n  performs the audio) or `video/lipsync-2-pro` (new words on a clip in which\n  the person already talks). For voice and video in one run,\n  `video/p-video-avatar` writes its own speech. Pick the path in\n  [`vsb-video` → People who talk](../vsb-video/SKILL.md#people-who-talk-pick-the-sound-path-before-you-spend) before you\n  make the lines.\n\n## ElevenLabs Voice Design\n\nUse it when no stock voice fits: a narrator for a series, a voice for each\ncharacter, a brand voice. Design once, then speak every script with it.\n\n```bash\n# 1. Design. One sample comes back in result.urls.\nvsb run audio/elevenlabs-voice-design \\\n  --prompt \"Native British English. Female, in her 40s. Studio quality. Persona: calm documentary narrator. Emotion: warm, measured, curious. Low, smooth timbre with an unhurried pace.\" \\\n  --json | jq -r '.result.urls[0]'\n\n# 2. Give the user the share page, https://visualsandbox.com/share/<job_id>/,\n#    to hear it. Not right? Run step 1 again, or change the description.\n# 3. Speak with it. Pass the sample URL itself, not a downloaded copy.\nvsb run audio/elevenlabs-tts --prompt \"<script>\" \\\n  --designed_voice \"<sample url>\" --mode v3 --json\n```\n\n- `--prompt` is the description, 20 to 1,000 characters. More detail gives\n  a more accurate voice. A structure that works: `Native <Language>.\n  <Gender>, <Age range>. <Quality level>. Persona: <2-5 words>. Emotion:\n  <2-3 adjectives>.` plus a sentence on timbre and delivery.\n- Name the language and the regional accent first, or the voice drifts.\n  Leave out effect words (`reverb`, `echo`) and vague ones (`foreign`).\n- `--text` is the line the sample reads, 100 to 1,000 characters. Omit it\n  and ElevenLabs writes a line that suits the voice; the run reserves the\n  longest line and is repriced down after. A longer line gives steadier,\n  more expressive sample. The web Composer hides this field.\n- `--designed_voice` overrides `--voice` and works in every `--mode`. Use\n  the same sample for every later script so the voice stays the same.\n  The first run with a sample saves it as a voice and takes about 12 s\n  longer. A voice not used for a while can be saved again on its next\n  run, with the same longer wait. It sounds the same and costs no more.\n- Only the user who designed a sample can speak with it. Any other URL,\n  an uploaded recording included, is refused. This is voice design, not\n  voice cloning, and cloning is not offered.\n- `--auditions 3` keeps all three takes that ElevenLabs makes of the voice,\n  for the same price: `result.urls` holds three samples to compare. Each\n  take is its own voice. Pass the take the person picked as\n  `--designed_voice`, or as `--my_voice` (it takes the link of one take).\n  Over MCP in ChatGPT, call `voice_studio` with the job id: the card plays\n  the three takes and saves the picked one to a character.\n\n### Your voices\n\n`vsb voices` lists every voice the user designed, newest first, with its id,\nits name and its sample URL. Name one once, then speak with it by name, with\nno sample URL to keep:\n\n```bash\nvsb voices                                  # list (MCP: list_voices)\nvsb voices rename <id> narrator             # name it; \"\" clears the name\nvsb run audio/elevenlabs-tts --my_voice narrator --prompt \"<script>\" --json\n```\n\n- `--my_voice` takes a name (any case) or an id, and wins over\n  `--designed_voice`. An unknown name fails before any charge.\n- Two voices of one user cannot share a name.\n\n## ElevenLabs Voice Isolator\n\nUse it when a recording has the right voice under noise: a street, a fan,\nmusic. It keeps the speech and removes the rest. Run it on a recording before\na voice clone or a transcript, or on a clip's sound before you put it back\nwith `add_audio`.\n\n```bash\nvsb run audio/elevenlabs-voice-isolator --audio \"<url of the recording or the video>\" --json\n```\n\nUp to 5 minutes; a video gives its sound. Billed by the length of the\nrecording. `vsb pricing audio/elevenlabs-voice-isolator --json` gives the rate.\n\n## ElevenLabs Voice Changer\n\nUse it when a recording has the right words and timing but the wrong voice.\nThe main case is a video model, such as Seedance 2.5, that speaks your line\nagain in its own voice. Change the voice back, then put the sound on the clip.\n\n```bash\n# 1. A video is fine: the run takes its sound.\nNEW=$(vsb run audio/elevenlabs-voice-changer --audio \"<clip url>\" \\\n  --my_voice narrator --json | jq -r '.result.urls[0]')\n# 2. Replace the clip's own sound with the new voice.\nvsb run tool/video-add-audio --video \"<clip url>\" --audio \"$NEW\" --mode replace --json\n```\n\n- The output is as long as the input, so the lip sync of a clip holds.\n- Turn on `--remove_background_noise true` when the recording has room tone\n  or music. Without it, the noise can come back as a hiss in the new voice.\n- 5 minutes at most per run. Cut a longer recording into parts.\n- It takes the same voices as Text to Speech. A recording of a real person\n  cannot become a voice: there is no voice cloning.\n\n## Eleven Music\n\n```bash\nvsb run audio/eleven-music \\\n  --prompt \"Minimal modern electronic promo track. Warm analog synth pads, soft four-on-the-floor kick, sparse bell melody. Clean, premium, optimistic. 100 BPM.\" \\\n  --duration_seconds 30 --instrumental true --json\n```\n\n- `duration_seconds`: 10–300 (default 30). The exact length is pinned in\n  the request, so the price shown at submit is exact and the track comes\n  back at precisely that length — match it to your edit.\n- `instrumental true` forces no vocals — the right call for background\n  beds under dialogue or voiceover. Omit it and the model writes and\n  performs vocals fitting the prompt (multilingual).\n- **Brief it like a composer**: genre, mood, instrumentation, tempo/key\n  (\"100 BPM in A minor\"). Use-case framing also works (\"ad for a sneaker\n  brand\", \"peaceful meditation bed\").\n- **Don't name artists or songs** — the provider rejects prompts that\n  reference copyrighted music. The error includes a suggested rewrite;\n  use it.\n- `lyrics`: your own words, sung verbatim. See the next section.\n- Licensing: commercial use OK (ads, social, podcasts, apps, games).\n  NOT covered: releasing tracks on Spotify/Apple Music or offline\n  TV/radio/film broadcast. Mention this if the user plans distribution.\n\n### Your own lyrics\n\nPass `--lyrics` and the model sings those words instead of writing its\nown. One line per row; blank lines separate sections. Section tags in\nsquare brackets are optional and honoured: `[Verse 1]`, `[Chorus]`,\n`[Bridge]`. Inline directions in curly braces are not sung: `{guitar solo}`.\n\n```bash\nvsb run audio/eleven-music \\\n  --prompt \"Upbeat acoustic pop, female vocals, bright and simple, 120 BPM.\" \\\n  --duration_seconds 60 \\\n  --lyrics \"$(cat lyrics.txt)\" --json\n```\n\n`lyrics.txt`:\n\n```text\n[Verse 1]\nSandbox in the morning light\nEvery pixel feels just right\n\n[Chorus]\nVisual Sandbox, run it now\nOne click and we show you how\n```\n\n- The `prompt` still sets the style: genre, mood, vocals, tempo. Keep the\n  words in `lyrics`, not in the prompt.\n- Lyrics can be in any language. The style prompt should stay in English.\n- Under the hood the server asks ElevenLabs for a composition plan with\n  your lines, checks every line survived, pins the section lengths to\n  `duration_seconds`, then composes. The price is unchanged: by track\n  length only.\n- `--lyrics` and `--instrumental true` together are rejected. Pick one.\n- Size the track to the words: about 4 sung lines per 20 seconds. The\n  planner adds an intro and outro around your sections.\n- Max 3000 characters of lyrics.\n\n### Async + poll (tracks over ~60s)\n\n```bash\nJOB=$(vsb run audio/eleven-music --prompt \"...\" --duration_seconds 120 \\\n  --instrumental true --async --json | jq -r '.job_id')\nvsb status \"$JOB\" --json | jq -r '.status'   # non-blocking peek\n\n# Wait — run this in a BACKGROUND shell; it notifies on completion.\nuntil vsb status \"$JOB\" --json 2>&1 | jq -e '.status | IN(\"completed\",\"failed\",\"cancelled\",\"error\")' > /dev/null; do sleep 10; done\nvsb status \"$JOB\" --result --download \"./out/{request_id}.mp3\" --json > \"/tmp/vsb-$JOB.json\"\n```\n\nPlay the finished track for the user with `open <file>` (the default player).\n\n`--download` only if the user opted into local saves — otherwise fetch with\n`--result --json` alone and hand back the share page\n`https://visualsandbox.com/share/<job_id>/`, never a raw CDN URL\n(vsb critical rule 5).\n\n## Cost estimation\n\n```bash\nvsb pricing audio/elevenlabs-sound-fx --json   # per clip\nvsb pricing audio/eleven-music --json          # per minute of music\nvsb pricing audio/elevenlabs-tts --json        # per 1,000 characters of text\nvsb pricing audio/elevenlabs-voice-design --json  # per 1,000 characters of the sample line\n```\n\nSpeech is billed per character of text, spaces and audio tags included.\n`flash-v2.5` costs half as much as the other modes.\n\nMusic is billed by track length, prorated per second — a 30s bed costs a\nfew cents, a 5-minute song under a dollar.\n\n## Common gotchas\n\n- **Field is `prompt`** on every generation model. For speech it is the\n  text to read. Run `vsb schema audio/<slug> --json` to confirm before\n  guessing flags.\n- **Lyrics go in `--lyrics`, not in the prompt.** Words inside the prompt\n  are treated as style hints and may be paraphrased; `--lyrics` is sung\n  verbatim.\n- **Output is `.mp3`** — set the download template extension accordingly:\n  `--download \"./out/{request_id}.mp3\"`.\n- **SFX duration caps at 30 seconds**; anything longer is a music job.\n- **Music duration must fit the edit** — the model fills exactly the\n  seconds you ask for; a 16s video wants a 16s track, not a trimmed 30s one.\n- **No em/en dashes (— –) in any text a model will speak or sing.** Speech\n  synthesis vocalizes dashes unpredictably (odd pauses, hallucinated\n  words). Use a comma, period, or `...` — full rule in the dialogue section\n  of [`vsb-video`](../vsb-video/SKILL.md).\n"
}