PROJECT-SCOPED: this call acts only on the explicit project_id and returns the project identity with its result. Punctuate a MOMENT with a one-shot sound effect — a whoosh into a real turn, a click on a shown button press, an impact on the payoff. OPTIONAL, never a rule: choose it only when the moment clearly earns a sound (a podcast or talking short carries zero by default and at most 1-2; sounds with no clear on-screen reason make an edit look childish). Each needs a visual partner (something on screen changes within ~50 ms of its hit), never sits as a bright sound (ding, pop, click, shutter) on the onset of a payoff or emphasis word, and never puns on the spoken word (a shutter on 'pictures', a cash register on 'money' with nothing on screen showing it). Analysis, metadata, and deterministic preview AUDIO CHECK are useful evidence; uncertainty is something to judge rather than a reason the tool becomes unavailable. storage_key is 'sound:<id>' for an approved library recording (list_sound_library), or an exact key from list_assets(kind='music') for a sound the user supplied — never invent one, never a web sound. `at` is an OUTPUT-timeline second (the edited program, not source time). For a library recording `at` is the moment it HITS — the visual frame its peak belongs on: the tool starts it early by its measured peak (a riser therefore ends on `at`; typing starts at `at`), skips into the file when the hit is too close to 0s, and reports where the peak lands and the span it plays — never pre-roll by hand. Any other sound starts at `at`. This is NOT background music: it plays once and never ducks. offset_s starts inside source audio — use it when an extracted clip contains the requested hit late in a long track. purpose records the nameable visible/editorial event for later final-mix review; do not add anonymous decorative sounds. dur_s (seconds from where it starts playing) stops a long recording (typing) when its on-screen event stops, with a short fade; long library tails (impact_1) already stop at their measured fade point unless dur_s asks for more. gain_db: leave it UNSET for a library recording — the tool measures the voice's short-term loudness at the hit and sets the gain for the sound's role (whoosh/swish ~8 dB under the voice, ding/pop/click/tick/shutter ~10 under, typing 14 under, an impact louder only below 150 Hz) and reports a MIX line; an explicit gain_db wins and is reported the same way. Other sounds default to -6dB. The result's CHECK lines flag a sound with no visual partner, on a payoff word's onset, a literal pun, a reflexive opening whoosh, a level that is inaudible or too hot, and more than 1-2 sounds in a talking short; a bright library sound on a payoff word's onset is NUDGED to a visual partner in the neighbouring speech gap when one is within reach (a pun, or a sound whose action is shown on that frame, is reported and left where it is).
