Manage sound files stored on the server. These are audio files (MP3, WAV, OGG) that can be played through the creature’s speaker independently of animations. Multi-creature dialog renders live here too, in a dialog/ subdirectory.
GET /api/v1/sound — List all stored sound files, walking subdirectories so dialog renders appear alongside hand-uploaded clips. Every entry carries its file_name, size, and lip sync data, plus metadata read from the file itself: a title, a transcript, and — for dialog renders — the source_script_id, generation_ids, and the full rendered script text embedded in the file. The has_embedded_script and has_embedded_lipsync booleans flag which files carry that provenance, so a list of otherwise-anonymous renders becomes self-describing.
{
"file_name": "e03af394-....wav",
"size": 522880952,
"title": "MongoDB is Web Scale",
"transcript": "",
"source_script_id": "...",
"generation_ids": "...",
"script": "Beaky: [proud] And in conclusion, we have found my-sequel to be an excellent database...",
"has_embedded_script": true,
"has_embedded_lipsync": true,
"lipsync": { }
}GET /api/v1/sound/{filename} — Download a sound file. Returns binary audio with the appropriate content type (audio/mpeg, audio/wav, or audio/ogg). The filename is resolved by basename, so a dialog render in the dialog/ subdirectory can be fetched by its bare filename without knowing the path.
GET /api/v1/sound/shareable/{filename} — Encode a sound file to Ogg/Opus for easy sharing. Multi-channel WAVs (like dialog renders) are downmixed to mono before encoding. The server looks in the permanent sound store first, then the ad-hoc store. Returns audio/ogg.
GET /api/v1/sound/provenance/{filename} — Return the embedded provenance of a dialog render. Dialog WAVs carry an iXML (BWFXML) chunk describing the source script, generation ids, channel and track layout, the full rendered script text, and per-channel lip sync mouth cues. Returns the raw iXML document as application/xml, or 404 if the file has no embedded provenance.
GET /api/v1/sound/ad-hoc — List ad-hoc generated sounds (TTS output stored in the TTL collection).
GET /api/v1/sound/ad-hoc/{filename} — Download an ad-hoc sound file. Returns audio/wav.
POST /api/v1/sound/play — Queue a sound file for playback on the creature’s speaker.
{
"file_name": "squawk.wav"
}POST /api/v1/sound/generate-lipsync — Generate lip sync data from a stored sound file using whisper.cpp. Runs as an async job, returns 202 with a job ID.
{
"sound_file": "hello.wav",
"allow_overwrite": false
}POST /api/v1/sound/generate-lipsync/upload — Upload a WAV file and generate lip sync data synchronously. Send raw WAV binary as the request body with a filename query parameter. Returns lip sync mouth cue data.