---
title: "Audio Elements"
canonical_url: https://docs.zvid.io/docs/structure/audio-elements/
source: docs/structure/audio-elements.md
content_revision: 6338386a1dd87e4a
---

# Audio Elements

Set `matchDuration: true` to follow the containing scene or project. The
audio then ends with that timeline (overriding `exit`) and does not determine
its automatic duration. Short source segments loop to fill the window.

`audios` adds background music, narration, and sound effects to the project. Audio items belong in `audios`, not `visuals`, and do not require a `type` field.

## Interface

```typescript
interface AudioItem {
  src: string;
  matchDuration?: boolean;
  enter?: number;
  exit?: number;
  volume?: number;
  speed?: number;
  audioBegin?: number;
  audioEnd?: number;
  audioDuration?: number;
}
```

## Required Fields

| Property | Type     | Notes                               |
| -------- | -------- | ----------------------------------- |
| `src`    | `string` | Remote `http` or `https` audio URL. |

## Properties

| Property        | Default                    | Range/notes                                                                                             |
| --------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
| `enter`         | `0`                        | Start time on the project timeline.                                                                     |
| `exit`          | `project.duration`         | End time on the project timeline.                                                                       |
| `matchDuration` | `false`                    | Follow the containing project/scene end, overriding `exit`; excluded from automatic-length calculation. |
| `audioBegin`    | `0`                        | Start point in source audio.                                                                            |
| `audioEnd`      | project or source duration | End point in source audio.                                                                              |
| `audioDuration` | project or source duration | Source duration hint.                                                                                   |
| `volume`        | `1`                        | `0` to `2`; `1` is the original level.                                                                  |
| `speed`         | `1`                        | `0.1` to `10`.                                                                                          |

## Examples

All timing fields are in **seconds**. `enter`/`exit` use the containing
project or scene timeline; `audioBegin`/`audioEnd` use source-media time.
The examples below are **audio item fragments** for `payload.audios` or
`payload.scenes[n].audios`, not full render requests. See
[Timing](https://docs.zvid.io/docs/concepts/timing/) for trimming, speed, and automatic duration.

### Background Music

```json
{
  "src": "https://cdn.pixabay.com/audio/2025/03/19/audio_56ae1dae5f.mp3",
  "volume": 0.3,
  "enter": 0,
  "exit": 10
}
```

### Sound Effect

```json
{
  "src": "https://cdn.pixabay.com/audio/2025/01/13/audio_c2af364af2.mp3",
  "volume": 0.8,
  "enter": 2,
  "exit": 4
}
```

### Source Segment

```json
{
  "src": "https://cdn.pixabay.com/audio/2025/04/21/audio_ed6f0ed574.mp3",
  "audioBegin": 10,
  "audioEnd": 20,
  "volume": 0.5,
  "enter": 0,
  "exit": 10
}
```

## Related Pages

- [Video Elements](https://docs.zvid.io/docs/structure/video-elements/)
- [Animation Effects](https://docs.zvid.io/docs/structure/animations/)
- [Transitions](https://docs.zvid.io/docs/structure/transitions/)