tts

O que tts faz?

Converta qualquer texto em áudio de fala. Suporta dois backends (Kokoro local, Noiz nuvem), dois modos (simples ou com timeline) e controle de voz por segmento.

Gatilhos

• text to speech / tts / speak / say
• voice clone / dubbing
• epub to audio / srt to audio / convert to audio
• 语音 / 说 / 讲 / 说话

Modo Simples — texto para áudio

speak é o padrão — o subcomando pode ser omitido:

# Uso básico (speak é implícito)
python3 skills/tts/scripts/tts.py -t "Olá mundo"          # adicione -o caminho para salvar
python3 skills/tts/scripts/tts.py -f artigo.txt -o saida.mp3

# Clonagem de voz — caminho de arquivo local ou URL
python3 skills/tts/scripts/tts.py -t "Olá" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Olá" --ref-audio https://exemplo.com/minha_voz.wav -o clone.wav

# Formato de mensagem de voz
python3 skills/tts/scripts/tts.py -t "Olá" --format opus -o voz.opus
python3 skills/tts/scripts/tts.py -t "Olá" --format ogg -o voz.ogg

A integração com terceiros (Feishu/Telegram/Discord) está documentada em ref_3rd_party.md.

Modo Timeline — SRT para áudio sincronizado

Para temporização precisa por segmento (dublagem, legendas, narração de vídeo).

Passo 1: Obter ou criar um SRT

Se o usuário não tiver um, gere a partir do texto:

python3 skills/tts/scripts/tts.py to-srt -i artigo.txt -o artigo.srt
python3 skills/tts/scripts/tts.py to-srt -i artigo.txt -o artigo.srt --cps 15 --gap 500

--cps = caracteres por segundo (padrão 4, bom para chinês; ~15 para inglês). O agente também pode escrever SRT manualmente.

Passo 2: Criar um mapa de vozes

Arquivo JSON que controla as configurações de voz padrão + por segmento. As chaves de segments suportam índice único "3" ou intervalo "5-8".

Mapa de vozes Kokoro:

{
  "default": { "voice": "zf_xiaoni", "lang": "cmn" },
  "segments": {
    "1": { "voice": "zm_yunxi" },
    "5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
  }
}

Mapa de vozes Noiz (adiciona suporte a emo, reference_audio). reference_audio pode ser um caminho local ou uma URL (áudio próprio do usuário; apenas Noiz):

{
  "default": { "voice_id": "voice_123", "target_lang": "zh" },
  "segments": {
    "1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
    "2-4": { "reference_audio": "./refs/convidado.wav" }
  }
}

Fatia Dinâmica de Áudio de Referência: Se você está traduzindo ou dublando um vídeo e deseja que cada sentença use automaticamente o áudio do vídeo original no mesmo timestamp exato como seu áudio de referência, use o argumento --ref-audio-track em vez de definir reference_audio no mapa:

python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json --ref-audio-track video_original.mp4 -o saida.wav

Veja examples/ para exemplos completos.

Passo 3: Renderizar

python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json -o saida.wav
python3 skills/tts/scripts/tts.py render --srt entrada.srt --voice-map vm.json --backend noiz --auto-emotion -o saida.wav

Quando Escolher Qual

Necessidade	Recomendado
Apenas ler texto em voz alta, sem complicações	Kokoro (padrão)
Audiobook EPUB/PDF com capítulos	Kokoro (suporte nativo)
Mistura de vozes ("v1:60,v2:40")	Kokoro
Clonagem de voz a partir de áudio de referência	Noiz
Controle de emoção (parâmetro emo)	Noiz
Duração exata por segmento no servidor	Noiz

Quando o usuário precisa de controle de emoção + clonagem de voz + duração precisa juntos, Noiz é o único backend que suporta todos os três.

Modo Convidado (sem chave de API)

Quando nenhuma chave de API está configurada, tts.py automaticamente cai para o modo convidado — um endpoint Noiz limitado que não requer autenticação. O modo convidado suporta apenas --voice-id, --speed e --format; clonagem de voz, emoção, duração e renderização de timeline não estão disponíveis.

# Modo convidado (detectado automaticamente quando nenhuma chave de API está definida)
python3 skills/tts/scripts/tts.py -t "Olá" --voice-id 883b6b7c -o ola.wav

# Substituição explícita do backend para usar kokoro
python3 skills/tts/scripts/tts.py -t "Olá" --backend kokoro

Vozes de convidado disponíveis (15 integradas):

voice_id	nome	lang	gênero	tom
063a4491	販売員（なおみ）	ja	F	喜び
4252b9c8	落ち着いた女性	ja	F	穏やか
578b4be2	熱血漢（たける）	ja	M	怒り
a9249ce7	安らぎ（みなと）	ja	M	穏やか
f00e45a1	旅人（かいと）	ja	M	穏やか
b4775100	悦悦｜社交分享	zh	F	Alegre
77e15f2c	婉青｜情绪抚慰	zh	F	Calmo
ac09aeb4	阿豪｜磁性主持	zh	M	Calmo
87cb2405	建国｜知识科普	zh	M	Calmo
3b9f1e27	小明｜科技达人	zh	M	Alegre
95814add	Science Narration	en	M	Calmo
883b6b7c	The Mentor (Alex)	en	M	Alegre
a845c7de	The Naturalist (Silas)	en	M	Calmo
5a68d66b	The Healer (Serena)	en	F	Calmo
0e4ab6ec	The Mentor (Maya)	en	F	Calmo

Segurança e divulgação de dados

Esta skill realiza as seguintes operações de arquivo e rede em tempo de execução:

• Armazenamento de credenciais: Quando você executa config --set-api-key, a chave é salva em ~/.config/noiz/api_key (permissões 0600). A variável de ambiente NOIZ_API_KEY também é suportada como alternativa.
• Migração de chave legada: Se ~/.noiz_api_key existir e ~/.config/noiz/api_key não, a chave é copiada (não excluída) para o novo local. Uma mensagem é impressa; o arquivo antigo permanece intocado para você remover manualmente.
• Chamadas de rede (backend Noiz): O texto e o áudio de referência opcional são enviados para https://noiz.ai/v1/ para síntese. Nenhum dado é enviado a menos que você invoque um comando Noiz.
• Download de áudio de referência: Quando --ref-audio é uma URL, o arquivo é baixado para um arquivo temporário, usado para a chamada de API e depois excluído. Se nenhum voice-id ou ref-audio for fornecido, um áudio de referência padrão é baixado de storage.googleapis.com ou noiz.ai.
• Arquivos temporários: Arquivos temporários de áudio/texto podem ser criados durante a síntese e são limpos após o uso.
• ffmpeg: Invocado apenas no modo de renderização render da timeline para montar o áudio final.

Nenhum arquivo fora do caminho de saída e ~/.config/noiz/ é modificado. O backend Kokoro opera inteiramente offline, sem acesso à rede.

Requisitos

• ffmpeg no PATH (apenas modo timeline)
• Pacote requests: uv pip install requests (necessário para o backend Noiz)
• Obtenha sua chave de API em Noiz Developer e depois execute python3 skills/tts/scripts/tts.py config --set-api-key SUA_CHAVE (o modo convidado funciona sem chave, mas tem recursos limitados)
• Kokoro: se já instalado, use --backend kokoro para usar o backend local

Autenticação da API Noiz

Use apenas a chave de API codificada em base64 como Authorization—sem prefixo (por exemplo, sem APIKEY ou Bearer ). Qualquer prefixo causa 401.

Para detalhes do backend e referência completa de argumentos, veja reference.md.