Runbook: TTS (Text-to-Speech)

Service overview

TTS runs on RunPod serverless (kc-tts-{env}). Two models: IndexTTS2 (default high-quality) and CosyVoice2 (voice-clone path). The orchestrator dispatches tts jobs with a voice_id payload.

Symptoms → Diagnosis → Fix

TTS job fails with voice_not_found

Diagnosis

1. Query voice_clone table for the voice_id referenced in the failing job.
2. Check R2 bucket kc-clone-eu-{env} for the corresponding model artefact.

Fix

• If model artefact is missing from R2: re-run the voice clone pipeline for the user.
• If voice_clone row is missing: check whether the clone job succeeded; look at media_job for the original clone job.

Audio output is silent / corrupted

Diagnosis

1. Check media_job.metadata for the job’s output URL.
2. Download the object from R2 and inspect with ffprobe.
3. Check RunPod endpoint logs for CUDA OOM or model load errors.

Fix

• CUDA OOM: reduce batch size in endpoint config, or upgrade GPU tier.
• Model load error: check that the model artefact in R2 is complete (check size vs known-good).

Latency > 30 s for short texts

Diagnosis

• Cold start: RunPod endpoint scaled to 0 workers.

Fix

• Set min_workers: 1 for production endpoint (accepted steady-state cost).
• Use keep_alive flag on the RunPod endpoint to extend idle window.

Useful queries

-- Recent TTS failures
SELECT id, status, metadata->>'error', created_at
FROM media_job
WHERE job_type = 'tts' AND status = 'failed'
ORDER BY created_at DESC
LIMIT 20;