puntorigen/avatar-skills / audio-theater
audio-theater
VerifiedTurn a dialogue, a story with dialogue, or a one-line idea into multi-character audio using Gemini TTS, with word-level timecoded transcription (WhisperX or local faster-whisper), realistic ambient/foley SFX (ElevenLabs or the sound-effects skill), and instrumental score/music (MiniMax Music 2.6). Optional stereo spatialization (pan + distance + movement) and an ffmpeg mix with sidechain ducking (music ducks under voices+SFX). Three modes - theater (dramatized radio play), lipsync (clean per-line clips <=15s plus a manifest for the seedance-2 skill), and podcast (two hosts with intro/bed/outro music). With music it delivers three tracks (full mix, music-only, and a no-music stem for animated storyboards) plus a timecoded transcript and per-line voice + SFX/music files. Use for an audio drama, audio theater / audioteatro / radioteatro, a dramatized dialogue, a score for a story/podcast/storyboard, voiceover for lipsync, a TTS conversation, or a podcast episode from a script or idea.
| File | Kind | Size |
|---|---|---|
| REFERENCE.md | markdown | 26.9 KB |
| SKILL.md | skill md | 26.9 KB |
| scripts/_common.py | script | 16.8 KB |
| scripts/audio_music.py | script | 10.3 KB |
| scripts/build_transcript.py | script | 4.8 KB |
| scripts/elevenlabs_sfx.py | script | 3.8 KB |
| scripts/export_lipsync.py | script | 4.4 KB |
| scripts/generate_sfx.py | script | 10.0 KB |
| scripts/generate_voices.py | script | 16.6 KB |
| scripts/mix.py | script | 10.0 KB |
| scripts/mix_spatial.py | script | 23.0 KB |
| scripts/requirements.txt | manifest | 364 B |
| scripts/setup_key.py | script | 4.2 KB |
| scripts/spatial.py | script | 6.8 KB |
| scripts/split_tracks.py | script | 8.3 KB |
| scripts/transcribe.py | script | 8.8 KB |
| scripts/voices.json | config | 2.1 KB |
| scripts/write_script.py | script | 9.9 KB |
scripts/elevenlabs_sfx.py
View on GitHub#!/usr/bin/env python3
"""ElevenLabs Sound Effects backend (eleven_text_to_sound_v2).
Generates a single SFX clip from a natural-language description via the
ElevenLabs Text-to-Sound-Effects REST API and writes it to disk. Used by
audio-theater's generate_sfx.py when --backend elevenlabs (or auto with a key).
Why ElevenLabs for SFX: purpose-built text-to-sound model with markedly more
realistic foley/ambience than Stable Audio, plus native seamless looping
(loop=true) which is ideal for our ambient beds.
Docs: https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert
"""
import json
import sys
import urllib.error
import urllib.request
from pathlib import Path
API_URL = "https://api.elevenlabs.io/v1/sound-generation"
MODEL_ID = "eleven_text_to_sound_v2"
# ElevenLabs accepts 0.5-30s; longer requests are clamped.
MIN_DURATION = 0.5
MAX_DURATION = 30.0
DEFAULT_OUTPUT_FORMAT = "mp3_44100_128"
def _clamp_duration(seconds):
if seconds is None:
return None
return max(MIN_DURATION, min(MAX_DURATION, float(seconds)))
def generate_sfx(
api_key,
description,
out_file,
*,
duration_seconds=None,
loop=False,
prompt_influence=0.4,
output_format=DEFAULT_OUTPUT_FORMAT,
model_id=MODEL_ID,
timeout=180,
):
"""Generate one sound effect and save it to out_file (mp3).
Returns True on success. duration_seconds=None lets the model auto-pick a
natural length (best for one-shots). For loops, pass a duration (<=30s).
"""
out_file = Path(out_file)
out_file.parent.mkdir(parents=True, exist_ok=True)
body = {
"text": description,
"model_id": model_id,
"loop": bool(loop),
"prompt_influence": float(prompt_influence),
}
dur = _clamp_duration(duration_seconds)
if dur is not None:
body["duration_seconds"] = dur
url = f"{API_URL}?output_format={output_format}"
data = json.dumps(body).encode("utf-8")
req = urllib.request.Request(url, data=data, method="POST")
req.add_header("xi-api-key", api_key)
req.add_header("Content-Type", "application/json")
req.add_header("Accept", "audio/mpeg")
try:
with urllib.request.urlopen(req, timeout=timeout) as resp:
payload = resp.read()
except urllib.error.HTTPError as e:
detail = ""
try:
detail = e.read().decode("utf-8", "replace")[:500]
except Exception: # noqa: BLE001
pass
print(f" ElevenLabs HTTP {e.code}: {detail}", file=sys.stderr)
return False
except urllib.error.URLError as e:
print(f" ElevenLabs request failed: {e.reason}", file=sys.stderr)
return False
# A JSON body here means an error was returned instead of audio bytes.
if payload[:1] in (b"{", b"["):
print(f" ElevenLabs returned non-audio: {payload[:300].decode('utf-8', 'replace')}",
file=sys.stderr)
return False
out_file.write_bytes(payload)
return out_file.stat().st_size > 0
def cli():
import argparse
SCRIPT_DIR = Path(__file__).parent
sys.path.insert(0, str(SCRIPT_DIR))
from _common import get_elevenlabs_api_key # noqa: E402
p = argparse.ArgumentParser(description="Generate one SFX via ElevenLabs")
p.add_argument("description")
p.add_argument("--output", "-o", required=True)
p.add_argument("--duration", "-d", type=float, default=None)
p.add_argument("--loop", action="store_true")
p.add_argument("--prompt-influence", type=float, default=0.4)
args = p.parse_args()
key = get_elevenlabs_api_key(required=True)
ok = generate_sfx(
key, args.description, args.output,
duration_seconds=args.duration, loop=args.loop,
prompt_influence=args.prompt_influence,
)
if not ok:
sys.exit(1)
print(args.output)
if __name__ == "__main__":
cli()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |