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

# Sound effects

> Play a curated or uploaded sound effect over a clip.

Add an audio clip to play over a clip for a time range. Upload the audio with `create_source` first (`kind: "audio"` with the audio's duration), then reference the returned `sourceId`. Upload the audio file as-is — MP3, WAV, M4A, and other common formats are accepted; no need to wrap it in an MP4.

<Note>
  **All times are milliseconds on the clip's playback timeline** — the video as watched, with cuts applied. It is the same timeline as `get_transcript`, thumbnails, and previews, so nothing needs converting. A start at or past the end of the clip is rejected with a `400`.
</Note>

## list\_sound\_effects

List the sound effects on a clip.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

## add\_sound\_effect

Add a sound effect to a clip, from Tella's curated library or from your own audio.

For a curated effect, call `list_library` with `scope: "default"` and pass the item's `presetId` — there is nothing to upload. For your own audio, pass the `sourceId` of a `private` or `workspace` item from that same tool, or upload a new one: call `create_source` first (`kind: "audio"` with the audio's duration), `PUT` the audio file as-is (MP3, WAV, M4A, …) to the returned `uploadUrl`, then pass the `sourceId` here.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="presetId" type="string">
  Required unless `sourceId` is given. Preset ID of a curated Tella sound effect, from a `default` item in `list_library`
</ParamField>

<ParamField path="sourceId" type="string">
  Required unless `presetId` is given. Source ID for the audio, from `create_source` or a `private`/`workspace` item in `list_library`
</ParamField>

<ParamField path="startTimeMs" type="integer" required>
  Start time in ms
</ParamField>

<ParamField path="durationMs" type="integer" required>
  Duration in ms — use the item's `durationMs` to play it in full
</ParamField>

<ParamField path="name" type="string">
  Sound effect name
</ParamField>

<ParamField path="volume" type="number">
  Playback volume (0 = muted, 1 = original). Defaults to 1.
</ParamField>

Pass exactly one of `presetId` or `sourceId`. Placing a preset copies it into a source owned by your workspace, so the video references its own media.

## update\_sound\_effect

Update an existing sound effect. Only provided fields change.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="soundEffectId" type="string" required>
  Sound effect ID
</ParamField>

<ParamField path="startTimeMs" type="integer">
  New start time in ms
</ParamField>

<ParamField path="durationMs" type="integer">
  New duration in ms
</ParamField>

<ParamField path="name" type="string">
  Sound effect name
</ParamField>

<ParamField path="volume" type="number">
  Playback volume (0 = muted, 1 = original)
</ParamField>

## remove\_sound\_effect

Remove a sound effect from a clip.

<ParamField path="videoId" type="string" required>
  Video ID
</ParamField>

<ParamField path="clipId" type="string" required>
  Clip ID
</ParamField>

<ParamField path="soundEffectId" type="string" required>
  Sound effect ID
</ParamField>


## Related topics

- [Add sound effects](/docs/help/editing/sound-effects.md)
- [Remove a sound effect](/docs/api-reference/clips/remove-a-sound-effect.md)
- [Update a sound effect](/docs/api-reference/clips/update-a-sound-effect.md)
- [List sound effects on a clip](/docs/api-reference/clips/list-sound-effects-on-a-clip.md)
- [Add a sound effect to a clip](/docs/api-reference/clips/add-a-sound-effect-to-a-clip.md)