Sound Effects

The Audio Effects page turns a text description into a sound effect: "heavy wooden door creaking open", "retro arcade power-up", "rain on a tin roof, looping". Generated effects can be auditioned on a waveform, trimmed to a region, downloaded, and saved to Saved Content for reuse.

1. 1Describe the sound. Name the source, the space, and the motion: "metal sword drawn from a leather sheath, close-up".
2. 2Set the duration in seconds. The provider enforces a maximum length (typically 10-30s).
3. 3Optionally adjust prompt influence and loop (see below), then generate.
4. 4Audition on the waveform. Drag to select a region to preview or download just a slice.
5. 5Download the file, or Save SFX to add it to Saved Content — as a new item or a new version of an existing one.

Sound effects are charged per second of requested audio, using the provider's configured rate (with optional free seconds and a minimum). Credits are reserved before generation and refunded automatically if it fails, so a failed generation never costs anything.

Saved effects live in Saved Content with the generation prompt as their description, the decoded duration, and optional tags. Saving supports Save as New and Update Existing — updating appends a new version to an existing effect, and the new version becomes the active one.

Every generated effect you save is handed to the Sound agent the moment it lands. It strips leading and trailing silence, normalises the level to the house target for its kind (a heavy impact at -14 LUFS, a light or UI sound at -18, a loop left untouched at its seams), keeps the true peak under the ceiling, fades the edges and delivers 48 kHz 16-bit WAV, mono for a point-source effect. Its result arrives as the item's next version and becomes the active one; the version you saved stays underneath it. Uploads are your own audio and are stored exactly as sent.

To keep one save exactly as generated, pass gameReady=false: a form field on POST /api/content, save.gameReady on the generate endpoint, saveGameReady on the MCP tool. The pass is a Sound turn and is billed like one.

A generated effect or line is rarely the finished clip. Matching it to the game's loudness, putting it through a helmet radio or a room, trimming the silence, fading, making it loop cleanly, mixing two together — that is a conversation with the Sound agent: an agent with an audio workbench (ffmpeg, SoX, meters that answer in LUFS and true peak) and one step per message. Open it from the clip's page (Post-process with the Sound agent). Each step you keep becomes a draft version of the same effect or line; Export writes the finished one as a new version, and the older versions stay.

• •It measures before it changes: ask "how loud is this?" and it answers in numbers, then normalises to the target you name (game dialogue is often -16 to -18 LUFS, effects -18 to -23).
• •Named treatments — radio, telephone, walkie, small and large rooms, denoise, pitch, tempo — are one message each; anything else is a SoX chain it can write for you.
• •No picture model, no paid vendor: a turn is a small flat reservation settled to the agent's own cost.

A conversation can also start from a brief with no clip at all — Talk to the Sound agent on this page. The agent generates with the same sound-effects model this page uses (a paid call it proposes with its price unless you asked for the sound), makes two or three takes when that helps and picks one, then runs the game-ready pass and exports. That is the way to get a sound that needs judgement: takes to choose between, a loop that has to seam, an effect that wants a room.

By API, the same four routes as the Forge conversation under /api/v1/sound/sessions (start takes the clip's contentId and a message, or just a message and an optional contentType to generate from a brief), and the MCP tools start_sound_session, send_sound_message, get_sound_session, export_sound_session; scope sfx:write for an effect, lines:write for a line.

SFX generation requires the sfx:write scope. The API uploads the result to storage and returns a URL (not base64); pass save to also store it in Saved Content.

curl -s https://<host>/api/v1/sfx/generate \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "heavy castle door slamming shut, big stone hall reverb",
    "durationSeconds": 4,
    "save": { "name": "Castle Door Slam", "tags": ["door", "impact", "castle"] }
  }'

{
  "success": true,
  "result": {
    "audioUrl": "https://<r2-public>/sfx/<org>/unassigned/<uuid>.mp3",
    "audioKey": "sfx/<org>/unassigned/<uuid>.mp3",
    "contentType": "audio/mpeg",
    "filename": "sfx_<uuid>.mp3",
    "tokensCharged": 8,
    "savedContent": { "id": "...", "name": "Castle Door Slam", "contentType": "sfx", ... }
  }
}