VoiceStudio

¿Qué hace VoiceStudio?

Usa el backend de VoiceStudio que el usuario tenga ejecutándose. Prefiere el procesamiento local; los trabajadores remotos, la traducción en la nube, las descargas de modelos y las integraciones externas requieren la elección del usuario. Los modelos instalados pueden funcionar sin conexión; no prometas que cada flujo de trabajo configurado sea offline.

Conectar y descubrir

El backend predeterminado es http://localhost:3900; respeta la dirección configurada por el usuario. El renderizador de Electron y el proxy de desarrollo son servicios separados, no la API pública del backend.

1. Verifica GET /health.
2. Descubre los contratos de la versión en ejecución con GET /openapi.json, y las voces/motores con GET /v1/audio/voices. No inventes ID de perfiles ni infieras modelos instalados a partir de un listado de catálogo.
3. Si no está disponible, inicia la aplicación instalada. Para un checkout de código fuente existente, sigue su README de Electron (bun install, bun run setup:api, luego bun run dev desde la raíz del repositorio). No instales un segundo backend ni sobrescribas un checkout existente.
4. Las configuraciones locales pueden permitir llamadas sin autenticación; los despliegues protegidos requieren las credenciales configuradas. Trata los errores 401/403 como fallos de autenticación, no como permiso para deshabilitar la autenticación. Nunca imprimas tokens ni uses una clave de marcador de posición como si fuera una credencial real.

Generar voz

Guarda este JSON en speech-request.json, reemplazando voice con un ID de perfil descubierto cuando el usuario haya seleccionado una voz:

{"model":"tts-1","voice":"alloy","input":"Every voice has a story. Let's tell yours.","response_format":"wav"}

curl --fail-with-body --show-error http://localhost:3900/v1/audio/speech \
  -H 'Content-Type: application/json' --data-binary @speech-request.json \
  --output speech.wav

tts-1 y tts-1-hd son alias, no garantías de calidad. Los nombres de voz de OpenAI son alias de compatibilidad, no las voces reales de esos proveedores. Prefiere una voz guardada descubierta para narraciones repetibles. Verifica las capacidades de idioma y diseño de voz del motor instalado antes de prometer un resultado.

Comprueba el estado HTTP y decodifica/prueba la salida antes de llamarla audio: una respuesta de error puede escribirse en la ruta de salida. Informa la ruta guardada y la duración/formato reales. Nunca fabriques una generación, transcripción o finalización de trabajo exitosa.

Transcribir

curl --fail-with-body --show-error http://localhost:3900/v1/audio/transcriptions \
  -F [email protected] -F model=whisper-1 -F response_format=verbose_json

Usa json o text para transcripciones simples, verbose_json para marcas de tiempo, y srt/vtt para subtítulos cuando el esquema en ejecución lo soporte. Verifica la disponibilidad del modelo de transcripción antes de grabaciones largas; explica un modelo faltante y obtén autorización de descarga en lugar de instalarlo silenciosamente.

Clonación, diseño, doblaje y flujos de trabajo largos

Usa el esquema OpenAPI instalado para descubrir las operaciones de creación de perfiles, carga de referencias, generación, doblaje y trabajos de formato largo. Sus endpoints nativos son más amplios que la API de compatibilidad de OpenAI y evolucionan de forma independiente.

• Clona solo voces que el usuario esté autorizado a usar. Conserva los archivos de referencia y los perfiles existentes.
• Para diseño, captura el tono, la entrega, el idioma y el texto de muestra solicitados; verifica el soporte del motor.
• Para doblaje, conserva el material original, las asignaciones de hablantes, la temporización de segmentos y la intención del audio de fondo. La finalización de la traducción no es la finalización del doblaje renderizado.
• Para trabajo asíncrono, usa los ID de trabajo devueltos y los endpoints de progreso/estado documentados. Inspecciona los errores terminales; evita reenviar ciegamente generaciones que han expirado.
• Devuelve archivos utilizables y limitaciones honestas, incluyendo modelos faltantes o capacidades no disponibles.

MCP y automatización

El backend en ejecución monta un endpoint MCP en http://localhost:3900/mcp. Usa el transporte HTTP soportado por el cliente y descubre sus herramientas en tiempo de ejecución. Reutiliza una conexión existente en lugar de lanzar otro servicio. Para clientes solo stdio, consulta la guía MCP del proyecto para su shim.

Para n8n, agentes llamantes, contenedores u otros hosts, haz que la dirección del backend sea alcanzable desde ese entorno: el localhost del contenedor se refiere al contenedor. Mantén intactas la autenticación y las elecciones explícitas de enrutamiento remoto. Un listado de directorio de integraciones no significa que la integración esté conectada.

Ante errores, lee el cuerpo de la respuesta, distingue entre backend no disponible, modelo faltante, capacidad no soportada, autenticación y hardware ocupado. Corrige la condición reportada; no cambies a un proveedor alojado ni descargues un modelo sin autorización.

Flujos de trabajo de escritorio y preparación

La aplicación Electron incluye clonación y diseño de voz, perfiles y galería guardados, historias/audiolibros, proyectos de doblaje, transcripción, herramientas e integraciones. Prefiere sus identificadores de proyecto y voz existentes en lugar de crear duplicados. Para automatización de escritorio, inspecciona la interfaz de usuario real y los accesos directos de Configuración actuales; no asumas que los enlaces de accesos directos o los permisos del micrófono son iguales en todos los hosts.

Antes del dictado, verifica que haya un modelo de voz a texto instalado y un dispositivo de entrada funcionando. Distingue entre grabación, grabación en pausa, procesamiento de transcripción y texto completado. Copiar una transcripción e insertarla en otra aplicación son operaciones diferentes; confirma el destino previsto antes de escribir y conserva el contenido del portapapeles donde sea posible. Nunca reportes texto entregado solo porque la transcripción finalizó.

Para doblaje, inspecciona los segmentos faltantes/fallidos y el desbordamiento de temporización antes de exportar. Conserva la música y el audio no verbal cuando se solicite; no reemplaces silenciosamente toda la banda sonora. Conserva la fuente y haz que la salida sea un artefacto separado. Las indicaciones de estilo de traducción pertenecen a la operación de traducción seleccionada, y la traducción mediante agente remoto requiere la elección del proveedor configurada por el usuario.

Usa el directorio de integraciones como guía de descubrimiento y configuración, no como prueba de un conector funcionando. Verifica las credenciales reales, la accesibilidad del endpoint y las operaciones soportadas antes de describir una conexión como lista. Los despliegues en contenedores necesitan volúmenes de datos persistentes y una URL de backend accesible por el cliente llamante.