TAS — Texto y Voz, en Ambos Sentidos (API Speakee)

Un solo script hace ambas direcciones:

Texto → Voz (TTS): 40+ idiomas, 100+ voces, UID de voz personalizada, fragmentación de texto largo, modo de conversación multi-voz, unión con ffmpeg y verificación de calidad de audio.
Audio → Texto (STT): transcribe cualquier archivo de audio/video a texto, marcas de tiempo de palabras y subtítulos SRT/WebVTT, con fragmentación automática para grabaciones largas.

Todo lo realiza el script incluido — nunca lo reimplementes en línea y NUNCA instales nada (ni whisper, ni torch, ni faster-whisper, ni pip):

<directorio base de la skill>/scripts/tas.py

Ubicaciones típicas de instalación: ~/.config/opencode/skills/tas/scripts/tas.py (opencode), ~/.claude/skills/tas/scripts/tas.py (Claude Code), y ~/.agents/skills/tas/scripts/tas.py (la CLI skills, npx skills add). La habilidad se llama tas — cárgala con el nombre tas, nunca tts.

Reglas no negociables (aplican a CADA solicitud)

Usa el script incluido. Sin fragmentos ad-hoc de curl/python para TTS o STT.
NUNCA instales nada. No ejecutes pip install faster-whisper, pip install whisper, pip install torch, ni descargues ningún modelo. El script realiza STT completamente a través de la API Speakee con la biblioteca estándar de Python — sin modelo local, sin descarga local, sin pip.
Verifica antes de entregar. tts y conversation ejecutan la verificación de audio automáticamente; un QA: FALLÓ debe corregirse, nunca enviarse.
Informa el resultado: ruta final, duración, tamaño y estado de QA (TTS); ruta final del SRT/VTT/texto y número de subtítulos (STT).
Siempre haz la verificación previa. El idioma, el modelo y la voz se validan antes de cualquier solicitud; nunca envíes una voz adivinada.
Mantén la caché activada a menos que el usuario indique lo contrario. Hace que las re-ejecuciones sean rápidas y reanuda conversaciones fallidas.
Nunca adivines un nombre de voz. Resuélvelo con voices / suggest, o pasa el UUID.
Respeta la API gratuita: por defecto --workers 4; redúcelo si recibes HTTP 429.
Deja que el script normalice el texto. Markdown, URLs, HTML y emojis se eliminan por defecto; usa --raw solo cuando el usuario quiera texto literal.
Nunca dividas texto largo de antemano. El script fragmenta por límites de oraciones y fusiona automáticamente.
Siempre pasa -l <código> para STT cuando el idioma sea conocido. La detección automática no es confiable (Whisper confunde bengalí/guyaratí); -l bn es obligatorio para un bengalí correcto.
Usa --json cuando otra herramienta o script consuma el resultado.

Comandos

Comando	Propósito
`tts`	sintetizar un bloque de texto (TTS)
`uid`	sintetizar con un UID de voz personalizado (`language=uid`)
`conversation`	diálogo multi-hablante → un MP3 unido y verificado
`stt`	transcribir un archivo de audio/video → texto (+ SRT/VTT opcional)
`transcribe`	alias para `stt`
`subtitle`	transcribir y escribir un SRT
`verify`	ejecutar verificación de calidad de audio en cualquier archivo
`voices -l <código>`	listar voces para un idioma
`suggest -l <código>`	listar voces con recomendaciones marcadas
`presets`	listar preajustes de voz integrados
`languages`	listar idiomas compatibles
`models`	listar modelos (`sonic-3.5` por defecto)
`cache-clear`	eliminar la caché de síntesis

Flujo de trabajo A — Texto a Voz (TTS)

Paso 1 — Alcance

Identifica: idioma (o deja que la detección automática funcione), tono (noticias / historia / asistente / audiolibro), un solo hablante o diálogo, ruta de salida deseada, y si se necesitan subtítulos (--srt) o metadatos (--title/--artist).

Paso 2 — Elige idioma y voz

python3 "$S" languages                 # 43 códigos
python3 "$S" suggest -l bn             # voces recomendadas primero
python3 "$S" presets                   # conjuntos de voces seleccionadas

Si el usuario tiene un UID de voz personalizado, usa el modo uid. De lo contrario, prefiere un preajuste o una voz recomendada sobre la predeterminada.

Paso 3 — Sintetiza

Un solo hablante:

python3 "$S" tts "Tu texto aquí" -l es -o salida.mp3
python3 "$S" tts --text-file articulo.md -l en --preset news -o articulo.mp3

Diálogo:

python3 "$S" conversation dialogo.txt -l es \
  --map "Humano=Nayem,AI=Pooja - Asistente Cotidiano" \
  --loudnorm --srt dialogo.srt -o dialogo.mp3

Usa --dry-run primero para ejecuciones largas o costosas.

Paso 4 — Verifica

La verificación de calidad se ejecuta automáticamente. Para volver a verificar cualquier archivo:

python3 "$S" verify salida.mp3

Comprueba: decodificado, duración, sonoridad integrada (ebur128), pico verdadero/saturación y silencio inicial/final/interno. El código de salida 5 significa FALLO.

Paso 5 — Entrega

Informa:

salida.mp3 — 2.8s, 0.04 MB, QA PASÓ (-18.9 LUFS, pico -4.2 dBFS)

No pegues el JSON sin procesar a menos que te lo pidan.

Paso 6 — Reutilización

Las re-ejecuciones usan la caché (~/.cache/speakee-tas). Usa --force para regenerar, cache-clear para borrar.

Flujo de trabajo B — Voz a Texto (STT)

Usa esto cuando el usuario tenga un archivo de audio o video y quiera una transcripción, subtítulos, o un SRT. No instales Whisper — el script incluido llama al endpoint /api/stt de Speakee directamente.

Paso 1 — Confirma el archivo

python3 "$S" verify /ruta/al/audio.mp3   # opcional: confirma que se decodifica
ls -la /ruta/al/audio.mp3

Paso 2 — Elige el idioma

# Detección automática (no confiable — Whisper confunde bengalí/guyaratí):
python3 "$S" stt audio.mp3

# SIEMPRE prefiere el idioma explícito cuando se conozca:
python3 "$S" stt audio.mp3 -l bn

Importante: pasa -l <código> para el script correcto. Para bengalí usa -l bn; la detección automática devuelve guyaratí para audio bengalí. Las advertencias de baja confianza (< 0.5) significan que el idioma detectado probablemente es incorrecto.

Paso 3 — Transcribe + crea subtítulos

# Escribe SRT + VTT junto a la entrada, y guarda la transcripción:
python3 "$S" stt audio.mp3 -l bn \
  --srt --srt-path audio.srt --vtt --vtt-path audio.vtt \
  -o audio.txt

# Abreviatura: solo el SRT (comando subtitle):
python3 "$S" subtitle audio.mp3 -l bn -o audio.srt

# JSON legible por máquina (para otras herramientas):
python3 "$S" stt audio.mp3 -l bn --json -o resultado.json

# Grabaciones largas: fragmentación automática ~120s; fuerza fragmentos más pequeños o una sola subida:
python3 "$S" stt audio.mp3 -l bn --chunk-seconds 60
python3 "$S" stt audio.mp3 -l bn --no-chunk     # solo si es < ~3.5 MB

Paso 4 — Entrega

Informa:

audio.srt — 111 subtítulos (8.05 min, Bengají)
audio.txt — transcripción guardada

Indicadores de STT: --srt, --srt-path, --vtt, --vtt-path, --no-word-timestamps (más rápido, sincronización estimada), --chunk-seconds, --no-chunk, --workers, --max-chars, --max-line-seconds.

Modo de conversación (TTS)

Formato del script, una línea por turno:

El espectáculo comienza.                <- sin prefijo "Narrador:" -> voz de narrador
Humano: Hermano, ¿cuánto es 2+2?
AI: Su pregunta ha sido recibida.

Las etiquetas de hablante son tokens cortos antes de : (≤16 caracteres, sin espacios).
Las líneas sin prefijo Hablante: son del narrador/comentarista. El narrador se asigna con la clave especial narrator, por lo que una tercera voz distinta es --map "narrator=VozC,Humano=VozA,AI=VozB".
--map "hablante=voz" acepta un nombre de voz (difuso) o UUID.
Sin --map, se asignan voces distintas automáticamente.
Las voces deben ser distintas. Si dos hablantes se resuelven a la misma voz, el script imprime una ADVERTENCIA; asigna cada hablante a una voz diferente. Siempre dale al AI y al humano voces diferentes (y una tercera voz para el narrador cuando haya una línea de comentarista/narrador).
--silence 0.35 pausa entre turnos; --loudnorm normaliza a −16 LUFS.
--manifest ARCHIVO registra cada segmento; --srt ARCHIVO escribe subtítulos.
--no-stitch mantiene archivos de segmento individuales en lugar de un solo MP3.
--workers controla las solicitudes paralelas (por defecto 4).

Opciones (más usadas)

Indicador	Por defecto	Significado
`-l, --language`	auto-detect	código ISO o `uid`
`-m, --model`	`sonic-3.5`	`sonic-3.5` / `sonic-3` / `sonic-turbo` / `sonic-2`
`-v, --voice_id`	preajuste/pordefecto	nombre de voz o UUID
`-o, --out`	auto	archivo / directorio de salida (`--no-stitch`)
`-s, --speed`	`1.2`	0.5–2.0
`--preset`	—	`news`, `story`, `assistant`, `audiobook`
`--chunk-limit`	`1200`	caracteres por solicitud
`--retries`	`4`	reintentos con retroceso exponencial
`--workers`	`4`	solicitudes paralelas
`--no-cache` / `--force`	desactivado	omitir caché / regenerar
`--no-verify`	desactivado	saltar verificación automática de QA (no recomendado)
`--dry-run`	desactivado	imprimir el plan, no hacer solicitudes
`--json`	desactivado	salida legible por máquina

Opciones de STT

Indicador	Por defecto	Significado
`-l, --language`	`auto`	código ISO (usa `bn` para bengalí)
`--chunk-seconds`	`120`	segundos de audio por subida
`--no-chunk`	desactivado	una solicitud (máx. ~3.5 MB)
`--workers`	`2`	subidas paralelas
`--srt` / `--srt-path`	desactivado	escribir un SRT
`--vtt` / `--vtt-path`	desactivado	escribir un WebVTT
`--no-word-timestamps`	desactivado	más rápido; la sincronización de subtítulos es estimada
`--max-chars`	`42`	caracteres máximos por subtítulo
`--max-line-seconds`	`6.0`	segundos máximos por subtítulo
`--timeout` / `--retries`	`300` / `3`	tiempo de espera / reintentos por solicitud

Caché y seguridad

Los segmentos se almacenan en caché por hash de contenido en ~/.cache/speakee-tas; las re-ejecuciones y reintentos se reanudan automáticamente.
Los archivos temporales de concatenación siempre se eliminan; los directorios temporales de --no-cache se limpian al salir.
Las respuestas se validan (Content-Type: audio/* + cabecera MP3), por lo que el JSON de error nunca se guarda como audio.
HTTP 429 respeta Retry-After; 5xx/timeouts reintentan con retroceso; 4xx permanentes fallan inmediatamente con el mensaje del servidor.
STT se ejecuta completamente dentro del proceso con la biblioteca estándar de Python — sin instalación de red, sin descarga de modelos, sin pip.
Códigos de salida: 0 ok, 1 error, 2 uso, 3 validación, 4 red/API, 5 verificación de audio fallida.

Archivos de referencia

references/api.md — endpoints, carga útil, validación, reintentos, caché.
references/voices.md — catálogo de idiomas/voces, modo UID, preajustes.
references/troubleshooting.md — síntomas, soluciones, modos de fallo comunes.
assets/presets.json — preajustes de voz seleccionados (edítalo para añadir los tuyos).

tas

¿Qué es tas?

Preguntar en tu IA favorita

Documentación