hmisaki/voicebox

Adicionar Mecanismo TTS

Objetivo

Integrar um novo mecanismo de texto-para-fala no Voicebox de ponta a ponta: pesquisa de dependências, implementação do protocolo de backend, integração da UI de frontend, empacotamento com PyInstaller e verificação do build congelado. O usuário só precisa testar o build final localmente.

Documento de Referência

O guia completo por fases está em docs/content/docs/developer/tts-engines.mdx. Leia este arquivo por completo antes de começar. Ele contém:

• Fase 0: Pesquisa de dependências (obrigatória antes de escrever código)
• Fase 1: Implementação do backend (protocolo TTSBackend)
• Fase 2: Integração de rota e serviço (geralmente zero alterações)
• Fase 3: Integração de frontend (5 arquivos)
• Fase 4: Dependências (requirements.txt, justfile, CI, Docker)
• Fase 5: Empacotamento com PyInstaller (build_binary.py + server.py)
• Fase 6: Soluções alternativas comuns para upstream
• Checklist de implementação (portão entre as fases)

Fluxo de Trabalho

1. Leia o guia

# Leia o documento completo sobre mecanismos TTS
cat docs/content/docs/developer/tts-engines.mdx

Internalize todas as fases, especialmente a Fase 0 e a Fase 5. O lançamento v0.2.3 teve três patches porque a Fase 0 foi pulada.

2. Pesquisa de dependências (Fase 0)

Clone a biblioteca de modelo em um diretório temporário e a audite. NÃO pule esta etapa.

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <url-da-biblioteca-do-modelo>

Execute as buscas grep da Fase 0.2 no guia contra o código fonte clonado e suas dependências transitivas. Produza uma auditoria de dependências por escrito cobrindo:

1. Pacotes PyPI vs não-PyPI
2. Diretivas PyInstaller necessárias (--collect-all, --copy-metadata, --hidden-import)
3. Arquivos de dados de tempo de execução que devem ser empacotados
4. Caminhos de bibliotecas nativas que precisam de substituições de variáveis de ambiente em builds congelados
5. Monkey-patches necessários (torch.load, float64, MPS, token HF)
6. Taxa de amostragem
7. Método de download do modelo (from_pretrained vs snapshot_download + from_local)

Teste o carregamento e a geração do modelo na CPU no ambiente virtual descartável antes de prosseguir.

3. Implementação (Fases 1–4)

Siga as fases do guia em ordem. Principais arquivos a modificar:

Backend (Fase 1):

• Crie backend/backends/<engine>_backend.py
• Registre em backend/backends/__init__.py (ModelConfig + TTS_ENGINES + factory)
• Atualize a regex em backend/models.py

Frontend (Fase 3):

• app/src/lib/api/types.ts — tipo de união do mecanismo
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS, ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — esquema Zod, mapeamento nome-do-modelo
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

Dependências (Fase 4):

• backend/requirements.txt
• justfile (alvos setup-python, setup-python-release)
• .github/workflows/release.yml
• Dockerfile (se aplicável)

4. Empacotamento com PyInstaller (Fase 5)

Registre o mecanismo em backend/build_binary.py:

• --hidden-import para o módulo backend e pacote do modelo
• --collect-all para pacotes que usam inspect.getsource, enviam arquivos de dados ou bibliotecas nativas
• --copy-metadata para pacotes que usam importlib.metadata

Se o mecanismo tiver caminhos de dados nativos, adicione os.environ.setdefault() em backend/server.py dentro do bloco if getattr(sys, 'frozen', False):.

5. Verifique no modo de desenvolvimento

just dev

Teste a cadeia completa: download do modelo → carregamento → geração → clonagem de voz.

6. Use o checklist

Percorra o Checklist de Implementação no final de tts-engines.mdx. Cada item deve ser verificado antes de entregar o build ao usuário.

Lições Principais (da v0.2.3)

Estes são os modos de falha mais comuns. A pesquisa da Fase 0 detecta todos eles:

Padrão	Sintoma no Build Congelado	Correção
@typechecked / inspect.getsource()	"could not get source code"	--collect-all <pacote>
Pacote fornece arquivos de modelo pré-treinado	FileNotFoundError para .pth.tar, .yaml	--collect-all <pacote>
Biblioteca C com caminhos de sistema fixos	FileNotFoundError para /usr/share/...	--collect-all + variável de ambiente em server.py
importlib.metadata.version()	"No package metadata found"	--copy-metadata <pacote>
torch.load sem map_location	Dispositivo CUDA não disponível no build CPU	Monkey-patch em torch.load
torch.from_numpy em dados float64	RuntimeError de incompatibilidade de dtype	Converter para .float()
token=True em chamadas de download HF	Falha de autenticação sem token HF armazenado	Usar snapshot_download(token=None) + from_local()

Notas

• As camadas de rota e serviço não possuem pontos de despacho por mecanismo. main.py requer zero alterações.
• O registro de configuração de modelo em backends/__init__.py lida com todo o despacho automaticamente.
• Use get_torch_device() e model_load_progress() de backends/base.py — não reimplemente detecção de dispositivo ou rastreamento de progresso.
• Sempre teste com um cache HuggingFace limpo (sem modelos pré-baixados do desenvolvimento).
• NÃO faça push ou crie um lançamento. Entregue o build ao usuário para teste local.