O que OmniVoice faz?
Visão Geral
Gere áudio localmente através do servidor MCP OmniVoice Studio. Ferramentas: generate_speech, list_voices, list_personalities, list_languages, check_health. Recursos: voice://{id}, history://recent.
Pré-requisitos — O Backend Deve Estar em Execução
As ferramentas MCP acessam $OMNIVOICE_API_URL (padrão http://localhost:3900). Se o backend estiver desligado, todas as ferramentas retornam um erro de conexão. Instale e inicie:
git clone https://github.com/debpalash/OmniVoice-Studio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'
Depois:
scripts/check-health.sh # exit 0 se estiver funcionando
scripts/start-backend.sh # inicia em segundo plano (MPS/CUDA detectados automaticamente)
A primeira chamada de síntese baixa o modelo k2-fsa/OmniVoice (~2,4 GB) do HuggingFace — armazenado em cache nas execuções seguintes.
Índice de Tarefas — Escolha a Ferramenta Correta
| Tarefa | Ferramenta | Notas |
|---|---|---|
| Verificar se o backend está ativo | check_health | Retorna `{"status":"ok","device":"mps |
| Texto → áudio com uma voz salva | generate_speech(text, profile_id) | Retorna WAV em base64. profile_id="demo0001" é a voz de demonstração incluída |
| Texto → áudio sem clonagem (design de voz) | generate_speech(text, instruct="…") | Omita profile_id; passe um instruct como "narrador feminina meia-idade, ritmo calmo" |
| Narração multilíngue | generate_speech(text, language="pt") | Qualquer código ISO 639 ou "Auto" |
| Listar vozes existentes | list_voices | Retorna id, nome, tipo, personalidade |
| Listar predefinições de personalidade | list_personalities | Retorna narrador / casual / âncora de notícias / etc. com suas strings de instruct |
| Listar idiomas suportados | list_languages | 646 no total; retorna 20 populares + a contagem total |
Para decisões não triviais (qual mecanismo usar, quando escolher OmniVoice em vez de kokoro / Edge TTS / ElevenLabs), consulte references/engines-comparison.md.
Para detalhes de configuração MCP, ciclo de vida do backend, solução de problemas e uma desinstalação limpa, consulte references/mcp-setup.md.
Fluxos de Trabalho Comuns
1. Narração única com a voz de demonstração
# Chamado através do cliente MCP (seu agente fará isso por você):
resultado = generate_speech(
text="Olá — isto é o OmniVoice gerando fala localmente.",
profile_id="demo0001",
language="Português",
steps=16, # 8 = rápido/rascunho · 16 = equilibrado · 32 = qualidade
)
# resultado é JSON com audio_id, generation_time_s, audio_duration_s, format, wav_base64
Benchmark: 4,2 s de áudio em ~24 s no lado do servidor em Apple Silicon MPS com 16 passos de difusão.
2. Salvar o WAV em disco e reproduzir
A ferramenta retorna WAV PCM em base64 (16 bits, mono, 24 kHz). Decodifique e escreva:
import base64, json
payload = json.loads(texto_resultado) # analisa o JSON retornado pela ferramenta
open("out.wav","wb").write(base64.b64decode(payload["wav_base64"]))
No macOS: afplay out.wav. Converta para MP3 com ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3.
3. Clonagem de voz — receita completa
A clonagem precisa de um clipe de referência de 3 a 10 segundos que o modelo usará como incorporação (embedding) do falante. O servidor MCP NÃO expõe a criação de perfis — ele apenas lê perfis existentes. Dois caminhos para criar um:
Caminho A — script auxiliar (macOS, recomendado para novas clonagens):
scripts/record-reference.sh ~/Downloads/minha-ref.wav 12 1
# args: output_path raw_duration_sec mic_index
# mic_index padrão=1 (MacBook embutido); liste dispositivos via:
# ffmpeg -f avfoundation -list_devices true -i ""
O script dá uma contagem regressiva audível e sinais de início/parada via say do macOS + /System/Library/Sounds/Ping.aiff para que o usuário saiba quando falar (a saída do terminal é armazenada em buffer — prompts de texto "fale agora" chegam tarde demais). Ele grava uma janela bruta maior, depois apara para ~10 segundos de fala via silenceremove + atrim, reproduz para verificação e imprime o comando curl da próxima etapa.
Caminho B — manual:
# 1. Gravar (mono, 24 kHz nativo — corresponde à taxa interna do modelo)
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. Aparar silêncio inicial + pegar os primeiros 10 seg de fala
ffmpeg -i raw.wav \
-af "silenceremove=start_periods=1:start_silence=0.05:start_threshold=-40dB,atrim=end=10" \
-ac 1 -ar 24000 ref.wav
# 3. Verificar
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # máximo deve ser > -20 dB
afplay ref.wav
POST para /profiles (multipart/form-data — campos obrigatórios: name, ref_audio):
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=clone-do-carlos" \
-F "[email protected]" \
-F "ref_text=O texto exato falado no clipe" \
-F "language=Português" \
| python3 -m json.tool
# retorna { "id": "abc12345", "name": "clone-do-carlos" }
Uma vez criado, passe profile_id para generate_speech (via MCP) ou diretamente via POST /generate. Os perfis persistem em SQLite + arquivos de áudio de referência em ~/Library/Application Support/OmniVoice/voices/<id>.<ext> (o backend preserva a extensão enviada — .wav se você enviou um WAV, .mp3 se MP3, etc.). O estado persiste entre reinicializações do backend.
Dicas para o clipe de referência que afetam materialmente a qualidade:
| Fator | Por que é importante |
|---|---|
| Único falante | Falantes mistos borram a incorporação (embedding) |
| Fala limpa, sem música/ruído | O modelo também incorpora o ruído |
| Prosódia natural (evite frases artificialmente longas) | As amostras de difusão replicam a prosódia, não apenas o timbre |
| 3-10 s é o ponto ideal | < 3 s falta informação; > 10 s adiciona computação sem ganho de qualidade |
Combine ref_text com o que é falado | Melhora o alinhamento, especialmente em referências ruidosas |
language correto | Idioma errado → artefatos de transferência multilíngue |
| Pico de volume ≥ -15 dB | Referências baixas funcionam, mas normalizam mal |
4. Design de voz (sem clipe de referência)
Pule profile_id; forneça uma string instruct descrevendo a voz desejada:
generate_speech(
text="Bem-vindo ao futuro dos sistemas de agentes.",
instruct="narradora feminina de meia idade, tom calmo e autoritário, estilo documentário",
)
Obtenha instruções prontas via list_personalities e copie a que corresponde à descrição (narrador, casual, âncora de notícias, etc.).
5. Dublagem de vídeo (apenas interface web)
O servidor MCP não expõe o endpoint de dublagem. O pipeline completo de transcrição → tradução → revozeamento → multiplexação fica na interface de desktop (bun run desktop em $OMNIVOICE_HOME) e nas rotas REST /dub/*. Quando o usuário pedir para dublar um vídeo, direcione-o para a interface; use esta skill apenas para os primitivos de síntese acima.
Quando NÃO usar o OmniVoice
- Narração rápida apenas em inglês em hardware fraco →
kokoro-ttsé ~10× menor e 2× tempo real na CPU (veja references/engines-comparison.md) - TTS avulso de menor atrito → Edge TTS não precisa de instalação ou backend
- Maior qualidade possível independentemente do custo → ElevenLabs ainda vence no polimento de narração em inglês; OmniVoice empata ou vence em multilíngue + clonagem
- Dictação em tempo real em streaming → use o widget de desktop do OmniVoice (
⌘+⇧+Space), não o servidor MCP
Recursos
- references/engines-comparison.md — Árvore de decisão entre OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / APIs de nuvem
- references/mcp-setup.md — Configuração MCP, ciclo de vida do backend, variáveis de ambiente, solução de problemas
- scripts/check-health.sh —
curl /health, retorna 0/1 - scripts/start-backend.sh — Inicia uvicorn em 127.0.0.1:3900 com verificação de saúde
- scripts/stop-backend.sh — Desligamento limpo via
kill -TERMno PID vinculado - scripts/record-reference.sh — apenas macOS: gravar + aparar + verificar um clipe de referência para clonagem, com sinais audíveis (
say+ bipes do sistema) que ignoram o buffer da saída do terminal
Swagger / OpenAPI do Backend: http://127.0.0.1:3900/docs (quando o backend estiver ativo).
Upstream: github.com/debpalash/OmniVoice-Studio — FSL-1.1-ALv2 (gratuito para uso pessoal/interno/não comercial; converte automaticamente para Apache-2.0 dois anos após cada lançamento).