Sounds

Sound effects are globally stored audio files that can be added to any scene block's sound timeline. They can be uploaded manually or generated via AI (ElevenLabs).

Endpoints overview

Method	Endpoint	Permission	Description
GET	/api/sounds	authenticated	List all sounds
GET	/api/sounds/:id	authenticated	Get sound by ID
GET	/api/sounds/file/:filename	authenticated	Download sound file
POST	/api/sounds	sound:create	Upload a sound
POST	/api/sounds/generate	sound:create	Generate sound effect (AI)
PATCH	/api/sounds/:id	sound:edit	Update a sound
DELETE	/api/sounds/:id	sound:delete	Delete a sound

Endpoints

List all sounds

GET /api/sounds — Auth required

Query params (all optional)

Param	Type	Description
search	string	Filter by name
page	number	Page number (default: 1)
limit	number	Page size (default: 10)

Response — 200

{
  "sounds": [
    {
      "id": "sound-uuid-001",
      "name": "Fanfare",
      "url": "/api/sounds/file/fanfare.mp3",
      "duration": 3,
      "createdAt": "2025-02-10T09:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

---

Get sound by ID

GET /api/sounds/:id — Auth required

Response — 200

{
  "id": "sound-uuid-001",
  "name": "Fanfare",
  "url": "/api/sounds/file/fanfare.mp3",
  "duration": 3,
  "createdAt": "2025-02-10T09:00:00.000Z"
}

---

Download sound file

GET /api/sounds/file/:filename — Auth required

Returns the audio file as a binary stream. Use authenticated fetch (Bearer token) in the frontend — not new Audio(url) directly — to avoid 401 errors.

---

Upload sound

POST /api/sounds — Auth required, multipart/form-data, Permission: sound:create

Form fields:

Field	Type	Required
audio	audio file (MP3, WAV, OGG)	yes
name	string	yes
duration	number (seconds, integer)	yes

Response — 201

{
  "id": "sound-uuid-002",
  "name": "Thunder",
  "url": "/api/sounds/file/thunder.mp3",
  "duration": 5,
  "createdAt": "2025-04-01T10:00:00.000Z"
}

---

Generate sound effect (AI)

POST /api/sounds/generate — Auth required, Permission: sound:create

Calls ElevenLabs to generate a sound effect from a text prompt, then saves and returns the result.

Request body

{
  "prompt": "thunderstorm with heavy rain on a metal roof",
  "name": "Thunderstorm",
  "durationSeconds": 10
}

Field	Required	Notes
prompt	yes	Text description of the desired sound
name	yes	Display name for the saved sound
durationSeconds	no	Target duration in seconds; defaults to 5

Response — 201 — same shape as the upload response

---

Update sound

PATCH /api/sounds/:id — Auth required, Permission: sound:edit

Request body

{ "name": "Updated Fanfare" }

Response — 200

{
  "id": "sound-uuid-001",
  "name": "Updated Fanfare",
  "url": "/api/sounds/file/fanfare.mp3",
  "duration": 3,
  "createdAt": "2025-02-10T09:00:00.000Z"
}

---

Delete sound

DELETE /api/sounds/:id — Auth required, Permission: sound:delete

Response — 204