Skill VoxFlow — Hub
Si voxflow upgrade falla con Unknown command (CLI anterior a 1.12.0), recurre a npm i -g voxflow@latest && voxflow skills install --all — esa es la única ruta para el primer arranque.
Esta regla es innegociable: una CLI desactualizada desactiva silenciosamente funciones que el usuario espera (p. ej., listado de voces clonadas). Primero actualiza, después trabaja.
VoxFlow convierte texto en voz con más de 200 voces en 40+ idiomas, además de pipelines completos de audio/vídeo. Este skill es el punto de entrada: instalación, autenticación, búsqueda de voces y los flujos de trabajo simples say / narrate / story.
Para tareas especializadas, cambia a:
- Podcasts (diálogo multi-locutor) →
voxflow:podcast - Vídeos cortos / clips de IA / tarjetas de conocimiento (
picstory,present,slides,explain) →voxflow:video - Artículo → vídeo en tarjeta vertical (Slice) — 13 temas (paper-slide / editorial-mag / bold-poster / notion-card / brutalist / glass-dark / editorial-stencil / broadsheet / blueprint / daisy-pastel / showa-catalog / photo-feature / atmospheric), aplicación web + Remotion →
voxflow:slice - Imágenes de tarjeta compartibles y vídeos de tarjeta narrados (HTML/CSS + exportación Playwright,
voxflow card renderopcional para MP4 narrado) →voxflow:card - Transcripción, traducción de subtítulos, doblaje, resumen, publicación (
asr,asr-jobs,translate,dub,video-translate,summarize,publish) →voxflow:transcribe
Instalación e inicio de sesión
Instala una vez, no preguntes nunca más al usuario:
npm install -g voxflow
voxflow login # abre el navegador — Google o OTP por correo
Token almacenado en ~/.config/voxflow/token.json. Para CI, configura VOXFLOW_TOKEN.
Autenticación
voxflow login # basada en navegador, una sola vez
voxflow status # quién soy + cuota restante
voxflow logout
Búsqueda de voces — haz esto siempre antes de sintetizar
Nunca adivines IDs de voz. Busca primero.
voxflow voices --lang zh --gender female
voxflow voices --lang en
voxflow voices --search "narrator"
voxflow voices --all
No requiere inicio de sesión para el catálogo público. La salida incluye el ID de voz, idioma, género y una breve descripción.
Listar las voces clonadas del usuario
Cuando el usuario diga cosas como "用我的克隆声音 / use my cloned voice / 用我之前克隆的", el catálogo público voxflow voices no incluye voces clonadas — debes consultar el endpoint autenticado:
voxflow voices --mine
Imprime IDs, nombres, duración y hora de creación de las voces clonadas (requiere inicio de sesión). Ejecuta esto antes de concluir que el usuario no tiene voz clonada — la pestaña "我的声音" de la interfaz web y --mine son las únicas fuentes de verdad.
IDs de voz populares (valores por defecto sensatos)
| ID | Estilo | Idioma |
|---|---|---|
v-female-R2s4N9qJ | 温柔姐姐 (voz femenina suave) | zh |
v-male-s5NqE0rZ | 自然男声 (voz masculina natural) | zh |
v-male-Bk7vD3xP | 威严霸总 (voz masculina autoritaria) | zh |
v-female-m1KpW7zE | 傲娇学姐 (voz femenina altanera) | zh |
v-female-T8m4WxP7 | Chenwen (voz femenina inglesa nativa) | en |
Clonación de voz (clone)
Clona una voz a partir de un archivo de audio local (30s+, wav/mp3). Devuelve un ID de voz permanente utilizable en todos los comandos.
voxflow clone --input recording.wav --name "Mi Voz"
# → ¡Voz clonada con éxito!
# → ID de voz: Mi_Voz_xxxxx_01
¿Sin archivo? Abre la interfaz web para grabación basada en navegador:
voxflow clone
# → Abre https://www.voxflow.studio/app#voice-clone
| Flag | Por defecto | Notas |
|---|---|---|
--input <archivo> | (ninguno) | Archivo de audio para clonar. Sin esto, abre la interfaz web |
--name <nombre> | nombre del archivo | Nombre legible de la voz (1-50 caracteres) |
Consejos:
- Habitación silenciosa, ritmo de habla normal, sin música de fondo → mejores resultados
- 60 segundos es óptimo; mínimo 30s
- No "actúes" — el habla natural se clona mejor que la voz de locutor
Después de clonar, usa el ID de voz en cualquier lugar: --voice <id>
Texto a voz (say / synthesize)
El comando atómico. Un fragmento → un archivo de audio.
voxflow say "你好世界" -o hola.mp3
voxflow say "Hello world" --voice v-female-T8m4WxP7 -o saludo.mp3
voxflow say "慢速朗读" --speed 0.8 -o lento.mp3
voxflow say "高质量音频" --format wav -o salida.wav
| Flag | Por defecto | Rango / Valores |
|---|---|---|
--voice <id> | v-female-R2s4N9qJ | cualquier ID de voz de voxflow voices |
--format <fmt> | pcm | pcm (WAV), wav, mp3 |
--speed <n> | 1.0 | 0.5 – 2.0 |
--volume <n> | 1.0 | 0.1 – 2.0 |
--pitch <n> | 0 | -12 – 12 |
--output <ruta> | nombre automático | cualquier ruta escribible |
Después de la síntesis, reproducción automática: open output.mp3 (macOS).
Texto largo (narrate)
Divide un documento o cadena larga en oraciones, sintetiza cada una, concatena en un solo archivo.
voxflow narrate --input article.txt -o narracion.wav
voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
voxflow narrate --text "Primer párrafo. Segundo párrafo. Tercer párrafo." -o parrafos.mp3
echo "Hello world" | voxflow narrate -o hola.wav
Ideal para: documentos largos, artículos, archivos README, boletines de correo.
Markdown se elimina automáticamente (encabezados, enlaces, bloques de código, etc.) — no es necesario limpiarlo primero.
Historia de IA (story)
El LLM escribe un cuento corto sobre el tema y luego lo narra.
voxflow story "Un gatito que vuela" -o cuento.mp3
voxflow story "space adventure" --lang en -o aventura.wav
Ideal para: cuentos para dormir, muestras de contenido, demostraciones.
Cuota
Nivel gratuito: 10,000 de cuota / mes (se reinicia mensualmente). El bono de invitaciones nunca caduca.
| Operación | Coste |
|---|---|
1 llamada TTS (say) | ~50 |
narrate | ~50 por segmento |
story (corta) | ~350-1000 |
podcast (media) | ~2,800 (2K script + ~16 × 50 TTS) |
picstory 5 escenas | ~2,850 |
Comprueba siempre antes de operaciones costosas:
voxflow status
Escenarios comunes
"读出这段话"
voxflow say "Texto introducido por el usuario" -o /tmp/salida.mp3 && open /tmp/salida.mp3
"用温柔女声读这个文件"
voxflow voices --lang zh --gender female
voxflow narrate --input archivo.txt --voice v-female-R2s4N9qJ -o /tmp/narracion.mp3
"讲个睡前故事"
voxflow story "La semilla de estrella del zorrito" --lang zh -o /tmp/cuento.mp3 && open /tmp/cuento.mp3
"多语言朗读"
voxflow voices --lang en --gender female # elige voz en inglés
voxflow voices --lang ja --gender female # elige voz en japonés
voxflow say "English text" --voice <en_id> -o /tmp/en.mp3
voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3
Flujos de trabajo creativos (combina TTS con la escritura del agente)
El agente escribe contenido primero, luego sintetiza cada parte con say o narrate.
Audiolibro ilustrado (有声绘本)
- Escribe un cuento infantil de 6 páginas.
- Para cada página: genera una ilustración SVG en línea (400×300).
voxflow say "texto de página" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/pagina_N.mp3- Lee archivos mp3, codifícalos en base64, incrústalos en línea en HTML.
- Genera un único archivo HTML autocontenido con botones de reproducción de audio por página.
open /tmp/cuento.html
Artículo → resumen de audio
# El agente obtiene la URL, la resume, luego:
voxflow say "texto del resumen" --voice v-male-s5NqE0rZ -o /tmp/resumen.mp3
Narración de documento
voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3
Informe diario de Git en audio
git log --oneline --since="1 day ago"- El agente lo resume.
voxflow say "resumen de hoy..." -o /tmp/diario.mp3
Entrevista simulada
- El agente genera 3 preguntas de entrevista sobre el tema.
- Para cada una:
voxflow say "pregunta N..." --voice v-male-Bk7vD3xP -o /tmp/p_N.mp3 - Reproduce secuencialmente.
Requisitos previos
- Node.js
^20.19.0 || >=22.12.0 - voxflow CLI ≥ 1.12.0 (para
voxflow voices --mine— lista las voces clonadas del usuario) - ffmpeg — solo para comandos relacionados con vídeo (consulta
voxflow:video,voxflow:transcribe) - Inicio de sesión requerido para cualquier llamada a la API —
voxflow login
Cómo funciona la señal de actualización automática
La propia CLI emite <voxflow-hint type="cli-outdated" ...> en stderr cada vez que hay una versión más reciente en npm. La regla <CRITICAL-AUTO-UPGRADE> al inicio del skill ya cubre qué hacer — esta sección es solo la referencia de cómo se ve la etiqueta:
<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />
Se emite como máximo una vez cada 24h (almacenado en caché en ~/.config/voxflow/update-check.json). Desactívalo para usuarios que no quieran la comprobación: VOXFLOW_NO_UPDATE_CHECK=1 (o NO_UPDATE_NOTIFIER=1, la variable de entorno estándar del sector).
También puedes consultar explícitamente con voxflow upgrade --check (sin efectos secundarios) si el usuario tiene una versión conocida antigua y quieres verificar antes de iniciar un trabajo costoso.
Comentarios y soporte (la IA puede hacer esto automáticamente)
Cuando un comando de voxflow falla o el usuario pide informar de un problema, tú (el agente de IA) debes reportar el problema directamente — no le pidas al usuario que lo haga manualmente.
Flujo de trabajo de IA
# Envía directamente — sin navegador, sin TTY requerido.
# Usa la CLI `gh` si está disponible (creación directa de issue en GitHub).
# Recurre a imprimir la URL pregenerada si gh no está instalado.
voxflow feedback --bug \
--title "asr falla con archivos wav de 2 horas" \
--body "Error: tiempo de espera agotado después de 30s\n\nComando: voxflow asr long.wav\nEsperado: transcripción\nReal: Error fatal: tiempo de espera de solicitud"
# stdout → la URL del issue creado en GitHub (o una URL pregenerada si gh no está instalado)
La información del sistema (versión de CLI, SO, Node) se añade al cuerpo automáticamente.
Flags
| Flag | Descripción |
|---|---|
--bug / --feature / --general | Tipo de issue |
--title <texto> | Título — activa el modo no interactivo |
--body <texto> | Cuerpo de la descripción |
--print-url | Forzar salida de URL en lugar de enviar (incluso si gh está disponible) |
Iniciado por el usuario (interactivo)
voxflow feedback # avisos interactivos → envía mediante gh o navegador
voxflow feedback --bug # omite el aviso de tipo, el resto es interactivo
Cuándo reportar automáticamente
- Cualquier comando CLI termina con un error fatal/inesperado → ofrécete a reportar un error
- El usuario dice "这个不好用" / "report this" / "提个 issue" → llama con
--titley envía directamente
Instalación de voces o plantillas de terceros (add)
voxflow add <nombre-receta> # instala un preset de voz o plantilla de pipeline
voxflow add --list # explora recetas disponibles
voxflow add chico/mi-receta --force # instala desde un espacio de nombres de autor personalizado
Úsalo cuando el usuario pida instalar una receta con nombre específico (p. ej., dub-anime-jp-zh). El registro es actualmente limitado — si --list devuelve 404, la receta puede necesitar ser referenciada por URL completa o el registro aún no es público.
Reglas
- Busca voces antes de usar — nunca inventes IDs de voz. Ejecuta siempre
voxflow voicesprimero. - Comprueba la cuota antes de podcasts (~5K), picstory (~3K) o trabajos por lotes:
voxflow status. - Reproducción automática después de la síntesis:
open output.mp3(macOS) /xdg-open(Linux). - Nunca imprimas tokens o secretos en los registros.
- Si un comando falla, ejecuta
voxflow <cmd> --helppara confirmar las flags antes de reintentar.
Cuándo cambiar de skill
- El usuario dice "podcast" / "对话" / "多人对谈" → carga
voxflow:podcast. - El usuario dice "short video" / "知识卡片" / "小红书" / "TikTok" / "AI clip" / "render" → carga
voxflow:video. - El usuario dice "Slice" / "切片视频" / "文章转视频" / "PaperSlide" / "paperslide" / "paper-slide" (heredado) / "纸面手绘风" / "文章转知识短视频" / "知乎长文转视频" / "公众号转视频" → carga
voxflow:slice. - El usuario dice "transcribe" / "字幕" / "dub" / "translate this video" / "SRT" → carga
voxflow:transcribe.