> ## Documentation Index
> Fetch the complete documentation index at: https://docs.decktalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Put a sound effect on a cue

> Play a one-shot sound effect that starts on a spoken cue.

This guide plays a one-shot sound effect on a cue. The sound starts on a spoken word. Use it when you want a sound to mark a reveal, such as a click as a card lands.

The example puts a click on `1.1word`, the cue in the starter's section 1 where the closing band appears. The starter ships no `[soundscape]` or `[[mix.sfx]]` tables, so every table below is one you add.

## Before you start

* Build the project one time, with `decktalk build --no-voice` or `decktalk build`. The `align` stage must resolve the cue first.
* To generate the effect, put an ElevenLabs API key in `.env`. Generating an effect spends credits. [What spends credits](/requirements#what-spends-credits) lists the cost.
* If you have your own audio file, you need no key. Any file that ffmpeg can read works.

<Steps>
  <Step title="Describe the effect">
    If you brought your own file, put it in the project and skip to step 4.

    Add a `[soundscape.sfx.<name>]` table with a prompt for the ElevenLabs sound generator.

    ```toml decktalk.toml theme={null}
    [soundscape.sfx.tick]
    text = "soft interface click, single, short, no reverb"
    ```

    `decktalk soundscape` writes this effect to `build/sfx/tick.mp3`. To use another path, add an `out` key to the table.
  </Step>

  <Step title="Preview the request">
    Print the request without sending it. The dry run needs no key and spends nothing.

    ```console theme={null}
    decktalk soundscape --dry-run tick
    ```

    ```text theme={null}
    items 1, generated 0
    == tick -> ~/my-lesson/build/sfx/tick.mp3  [planned]
       POST https://api.elevenlabs.io/v1/sound-generation
       {'text': 'soft interface click, single, short, no reverb', 'duration_seconds': 0.5, 'prompt_influence': 0.5, 'model_id': 'eleven_text_to_sound_v2'}
    ```

    Check the output path and the prompt. The effect lasts 0.5 s unless the table sets `duration_seconds`.
  </Step>

  <Step title="Generate the effect">
    Send the request.

    ```console theme={null}
    decktalk soundscape tick
    ```

    The command writes `build/sfx/tick.mp3`. If the request and the file have not changed, a later run sends nothing. To generate the effect again, add `--force`.
  </Step>

  <Step title="Place the effect on a cue">
    Add a `[[mix.sfx]]` table that names the file, the section, and the cue id.

    ```toml decktalk.toml theme={null}
    [[mix.sfx]]
    file = "build/sfx/tick.mp3"
    section = 1
    cue = "1.1word"
    db = -16
    caption = "soft click"
    ```

    * `db` sets the level of the effect. The default is -16.
    * `offset` moves the effect by a number of seconds. The default is 0.
    * `caption` is the line a caption reader sees when the sound plays. Without it the sound is in the video and in no caption. [Accessible video](/guides/accessible-video#captions-that-carry-the-sound-not-only-the-speech) explains why it matters.

    DeckTalk places the effect at the section's start in the final video, plus the cue time, plus `offset`.
  </Step>

  <Step title="Mix the effect into the video">
    Run the `assemble` stage. It mixes the audio again, and it records nothing.

    ```console theme={null}
    decktalk assemble
    ```

    If the file is missing, or the cue did not resolve, `assemble` prints a warning and skips the effect. The video still builds.

    ```text theme={null}
    sfx build/sfx/tick.mp3 is missing, so it is skipped
    ```
  </Step>
</Steps>

## Next

* **Learn every part of the mix:** [Sound](/concepts/sound)
* **Swell or mute the music on a phrase:** [Markers](/concepts/sound#markers)
* **Check what a generated effect costs:** [Requirements and costs](/requirements#what-spends-credits)