VoiceStudio

O que VoiceStudio faz?

Use o backend VoiceStudio em execução do usuário. Prefira processamento local; trabalhadores remotos, tradução em nuvem, downloads de modelos e integrações externas exigem escolha do usuário. Modelos instalados podem funcionar offline; não prometa que todos os workflows configurados sejam offline.

Conectar e descobrir

O backend padrão é http://localhost:3900; respeite o endereço configurado pelo usuário. O renderizador do Electron e o proxy de desenvolvimento são serviços separados, não a API pública do backend.

1. Verifique GET /health.
2. Descubra os contratos da versão em execução com GET /openapi.json, e vozes/motores com GET /v1/audio/voices. Não invente IDs de perfil nem infira modelos instalados a partir de uma listagem de catálogo.
3. Se indisponível, inicie o aplicativo instalado. Para uma cópia existente do código-fonte, siga o README do Electron (bun install, bun run setup:api, depois bun run dev a partir da raiz do repositório). Não instale um segundo backend nem sobrescreva uma cópia existente.
4. Configurações locais podem permitir chamadas não autenticadas; implantações protegidas exigem as credenciais configuradas. Trate 401/403 como falhas de autenticação, não como permissão para desabilitar a autenticação. Nunca imprima tokens nem use uma chave placeholder como se fosse uma credencial real.

Gerar fala

Salve este JSON em speech-request.json, substituindo voice por um ID de perfil descoberto quando o usuário selecionar uma voz:

{"model":"tts-1","voice":"alloy","input":"Cada voz tem uma história. Vamos contar a sua.","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 e tts-1-hd são aliases, não garantias de qualidade. Nomes de voz da OpenAI são aliases de compatibilidade, não as vozes reais desses provedores. Prefira uma voz salva descoberta para narração repetível. Verifique a capacidade de idioma e design de voz do motor instalado antes de prometer um resultado.

Verifique o status HTTP e decodifique/inspecione a saída antes de chamá-la de áudio: uma resposta de erro pode ser gravada no caminho de saída. Informe o caminho salvo e a duração/formaato reais. Nunca invente uma geração, transcrição ou conclusão de tarefa bem-sucedida.

Transcrever

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

Use json ou text para transcrições simples, verbose_json para timestamps, e srt/vtt para legendas quando suportado pelo schema em execução. Verifique a prontidão do modelo de transcrição antes de gravações longas; explique a falta de um modelo e obtenha autorização para download, em vez de instalá-lo silenciosamente.

Clonagem, design, dublagem e workflows longos

Use o schema OpenAPI instalado para descobrir operações de criação de perfil, uploads de referência, geração, dublagem e tarefas de longa duração. Seus endpoints nativos são mais amplos que a API de compatibilidade da OpenAI e evoluem de forma independente.

• Clone apenas vozes que o usuário está autorizado a usar. Preserve arquivos de referência e perfis existentes.
• Para design, capture o tom solicitado, entrega, idioma e texto de amostra; verifique o suporte do motor.
• Para dublagem, mantenha a mídia original, atribuições de falantes, segmentação temporal e intenção do áudio de fundo. Conclusão da tradução não é conclusão da dublagem renderizada.
• Para trabalho assíncrono, use IDs de tarefa retornados e endpoints de progresso/status documentados. Inspecione erros terminais; evite reenviar cegamente gerações que expiraram.
• Retorne arquivos utilizáveis e limitações honestas, incluindo modelos ausentes ou capacidades indisponíveis.

MCP e automação

O backend em execução monta um endpoint MCP em http://localhost:3900/mcp. Use o transporte HTTP suportado pelo cliente e descubra suas ferramentas em tempo de execução. Reutilize uma conexão existente em vez de iniciar outro serviço. Para clientes somente stdio, consulte o guia MCP do projeto para seu shim.

Para n8n, agentes de chamada, contêineres ou outros hosts, torne o endereço do backend acessível a partir desse ambiente: o localhost do contêiner refere-se ao contêiner. Mantenha a autenticação e as escolhas explícitas de roteamento remoto intactas. Uma listagem de diretório de integração não significa que a integração está conectada.

Em caso de erros, leia o corpo da resposta, distinga entre backend indisponível, modelo ausente, capacidade não suportada, autenticação e hardware ocupado. Corrija a condição relatada; não mude para um provedor hospedado nem baixe um modelo sem autorização.

Workflows desktop e prontidão

O aplicativo Electron inclui clonagem e design de voz, perfis e galeria salvos, histórias/audiolivros, projetos de dublagem, transcrição, ferramentas e integrações. Prefira seus IDs de projeto e voz existentes em vez de criar duplicatas. Para automação desktop, inspecione a UI real e os atalhos de Configurações atuais; não presuma que os atalhos de teclado ou permissões de microfone são os mesmos em todos os hosts.

Antes do ditado, verifique um modelo de fala-para-texto instalado e um dispositivo de entrada funcionando. Distinga entre gravação, gravação pausada, processamento de transcrição e texto concluído. Copiar uma transcrição e inseri-la em outro aplicativo são operações diferentes; confirme o destino pretendido antes de digitar e preserve o conteúdo da área de transferência quando suportado. Nunca relate texto entregue apenas porque a transcrição foi concluída.

Para dublagem, inspecione segmentos ausentes/com falha e estouro de tempo antes da exportação. Preserve música e áudio não-fala quando solicitado; não substitua silenciosamente toda a trilha sonora. Preserve a fonte e torne a saída um artefato separado. Prompts de estilo de tradução pertencem à operação de tradução selecionada, e a tradução por agente remoto exige a escolha do provedor configurada pelo usuário.

Use o diretório de integrações como descoberta e orientação de configuração, não como prova de um conector funcionando. Verifique credenciais reais, acessibilidade do endpoint e operações suportadas antes de descrever uma conexão como pronta. Implantações em contêineres precisam de volumes de dados persistentes e uma URL de backend acessível pelo cliente chamador.