Sound Effects
Overview​
Sound effects can be attached to action blocks to describe the ambient audio for a scene beat. Each effect has precise timing so it can be placed and trimmed on a visual timeline.
Sound library​
The sound library (/admin → Sound Effects, or via the Sound Manager in the studio) holds all available sound effects. Sounds are generated via AI and stored on the server.
Generating a sound​
- Open the Sound Manager (manage mode)
- Click Add Sound
- Enter a name and a text description (prompt)
- Set duration (0–21 seconds)
- Click Create — the AI generates and uploads the audio
Requires sound:create permission.
Attaching sounds to a block​
- Edit an action block (pencil icon → BlockModal)
- In the Sounds section, click + to open the Sound Picker (picker mode)
- Preview sounds by clicking the play button (audio is fetched via Bearer token)
- Click Add to attach the sound to the block
The block can have multiple sounds attached.
Sound timeline​
Each attached sound is displayed on a timeline relative to the block's duration. You can drag the sound bar to adjust:
- Block start (
blockStart) — when within the block this sound starts playing - Block end (
blockEnd) — when within the block this sound stops
The timeline visually shows overlapping sounds and their relative positions.
Playback in BlockModal​
| Button | Action |
|---|---|
| â–¶ (Play All) | Plays all sounds simultaneously according to their blockStart timing |
| â–¶ (Play Selected) | Plays the currently selected sound from its soundStart trim point |
| 🗑 | Deletes the selected sound from this block |
All audio is fetched via apiFetch (Bearer token) and played from blob URLs.
Inline playback (scene view)​
Each attached sound is shown as a pill on the action block. Clicking the play button on a pill plays that specific sound clip (trimmed to soundStart/soundEnd).
Sound fields​
| Field | Description |
|---|---|
blockStart | Seconds into the block when sound begins |
blockEnd | Seconds into the block when sound ends |
soundStart | Trim start within the source audio file |
soundEnd | Trim end within the source audio file |
duration | Total duration of the source audio |
API​
| Method | Endpoint | Description |
|---|---|---|
GET | /api/sounds | List sounds (paginated, searchable) |
POST | /api/sounds/generate | Generate a new sound |
PATCH | /api/sounds/:id | Rename a sound |
DELETE | /api/sounds/:id | Delete a sound |