wael-wq/natural-voice

O que natural-voice faz?

A maioria das narrações ElevenLabs que soam "robóticas" não é um problema de voz. É um problema de roteiro. O modelo lê exatamente o que recebe, e um roteiro escrito para os olhos (manchetes, fragmentos com ponto final, dígitos, travessões) sai staccato independentemente de qual voz o lê.

Três ferramentas nesta pasta realmente funcionam. Use-as; não julgue o fluxo apenas lendo o texto.

python3 speakable.py script.txt                  # isto foi escrito para o ouvido?
python3 takes.py script.txt --voice VOICE_ID     # takes com sementes (pago, pergunta primeiro)
python3 gaps.py takes/                           # classifica os takes por pausas dentro das frases

Todas são Python 3.9+ puro, sem pacotes. gaps.py usa ffmpeg se estiver no PATH para confirmar as pausas no próprio áudio.

O ciclo

1. Diagnostique antes de mudar qualquer coisa. Se já existe um take, execute gaps.py nele. Uma pausa acima de 0,2 s dentro de uma frase (não após uma vírgula ou ponto final) é o que as pessoas ouvem como "IA". No nosso take anterior, a voz parou 0,3 s antes de "run" e novamente antes de "Instagram", no meio da chamada. Nada na nossa edição causou isso: as pausas estavam no arquivo bruto.

2. Reescreva para o ouvido. Execute speakable.py e corrija cada sinalização. As regras:

• Frases, não manchetes. "13 free Claude skills now run your Instagram." é um título. "Thirteen free Claude skills run your whole Instagram." é algo que uma pessoa diz.
• Listas usam vírgulas, não pontos finais. "Reels. Captions. Carousels." faz o modelo parar três vezes. "reels, captions, carousels, stories" flui.
• Números por extenso na linha falada: "eighty-four out of a hundred", não "84 out of 100". O texto na tela pode manter os dígitos.
• Contrações (you've, it's, we'll). Ninguém diz "you have" em voz alta.
• Conecte os fragmentos com "so", "and", "then". Uma conjunção é uma dica para o modelo continuar.
• Sem travessões. O ElevenLabs trata um travessão como uma pausa curta e diz que é "menos consistente". Use uma vírgula para continuar, ou reticências para uma pausa.
• Sem SSML. <break time="1s"/> não é suportado no Eleven v4 ou v3.

3. Dirija-o. O Eleven v4 aceita tags de áudio entre colchetes. Coloque uma tag no início de uma batida, não em cada linha, e faça com que corresponda ao que a linha está fazendo. Veja tags.md para a lista. speakable.py sinaliza tags que não conhece, porque uma tag desconhecida pode ser lida como um efeito sonoro.

[excited] Thirteen free Claude skills run your whole Instagram.
[mischievously] So we let it write this Reel...

Pontuação também é direção. Reticências adicionam uma pausa com peso, exclamação adiciona energia, e MAIÚSCULAS adicionam ênfase (use uma vez, na palavra que importa).

4. Configurações. No eleven_v4:

configuração	uso	por que
stability	0.30 a 0.40	Mais baixo dá "alcance emocional mais amplo"; o padrão 0.5 é mais plano. Abaixo de 0.3, um take pode derivar.
similarity_boost	0.75	o padrão; mantém a voz em si
style	0	o padrão; qualquer outra coisa adiciona latência
speed	1.0 a 1.08	a faixa permitida é 0.7 a 1.2; narração social fica logo acima de 1

5. Três takes, mesmo texto, sementes diferentes. Um take é um cara ou coroa. Execute takes.py com sementes 1, 2 e 3, depois gaps.py para classificá-los. Ouça os dois primeiros e escolha pelo ouvido. Guarde a semente: ela faz uma reexecução ficar próxima do mesmo take (ElevenLabs chama de "best effort", não garantido).

6. Edite com cuidado. Se seu editor cortar silêncios, mantenha cerca de um segundo após frases e a maior parte de um segundo após vírgulas. Pausas cortadas para a mesma duração curta sempre são a outra coisa que soa feita por máquina.

7. Ainda soa gerado? Pare de girar botões. Grave você mesmo dizendo a linha no seu telefone e passe pelo Conversor de Voz do ElevenLabs (speech-to-speech) na voz que deseja. Seu tempo, ênfase e emoção são transferidos; apenas a voz muda.

O que medimos

Em um dos nossos próprios Reels (os arquivos estão em examples/):

	antes	depois
roteiro	escrito para os olhos: fragmentos, dígitos	escrito para o ouvido: speakable.py limpo
tags	nenhuma	[excited], [mischievously]
configurações	stability 0.5, speed 1.0	stability 0.35, speed 1.05
takes	1	3 sementes, escolhido por gaps.py e depois pelo ouvido
speakable.py	65, REWRITE (uma lista em pontos finais, dígitos, sem tags)	100, SPEAKABLE
pausas dentro de frases	0,34 s entre "now" e "run", na chamada	nenhuma

A voz também mudou (Will para Chris), então este não é um teste de laboratório com uma única configuração. A reescrita do roteiro fez a maior diferença que pudemos ouvir.

Regras

• Nunca envie uma requisição paga sem dizer quanto custa. takes.py imprime a contagem de caracteres e para a menos que você passe --yes.
• Nunca imprima ou cometa a chave da API. takes.py lê ELEVENLABS_API_KEY do ambiente e nada mais.
• Identifique. Se a voz for gerada, ative o rótulo de IA da plataforma.