Instructions to use semfence/pingo-ptbr with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- MLX
How to use semfence/pingo-ptbr with MLX:
# Download the model from the Hub pip install huggingface_hub[hf_xet] hf download semfence/pingo-ptbr --local-dir pingo-ptbr
- Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- LM Studio
- Atomic Chat
Download README.md from semfence/pingo-ptbr: direct link, hf CLI and curl.
- Browser
- Download file 20.8 kB
-
https://huggingface.co/semfence/pingo-ptbr/resolve/main/README.md
- Command line
-
hf download hf://semfence/pingo-ptbr/README.md
-
curl -L -o README.md https://huggingface.co/semfence/pingo-ptbr/resolve/main/README.md
language:
- pt
license: cc-by-4.0
library_name: mlx
pipeline_tag: text-to-speech
tags:
- text-to-speech
- tts
- pt-br
- brazilian-portuguese
- small-model
- quantized
- mlx
- apple-silicon
- pingo
- fargan
inference: false
datasets:
- semfence/ptbr-synthetic-speech
- semfence/ptbr-sentences
pingo-ptbr
Qual o tamanho mínimo de uma voz em português do Brasil? O pingo-ptbr é um sistema completo de texto para fala em um único arquivo de 0,87 MB: duas vozes sintéticas, F_s4 (feminina) e M_sm4 (masculina), com 1.086.678 parâmetros no total, vocoder incluído. Um modelo acústico de 270.081 parâmetros, treinado do zero pela SemFence, prevê as características da voz, e um vocoder FARGAN de 816.597 parâmetros (congelado, vindo do PiVo) as transforma em áudio mono de 16 kHz.
É um de três experimentos da SemFence em voz pequena para português do Brasil, ao lado do pivo-ptbr e do tiny-voca-ptbr: cada um segue um caminho diferente. Aqui o modelo acústico é mais estreito (largura 64, contra 96 do pivo-ptbr) e cada peso é guardado com 5 a 8 bits em vez de 32, com mais bits nas camadas mais sensíveis. Pingo é uma gota, um pouquinho.
Roda em CPU, com MLX no Apple Silicon (a cerca de 24 vezes o tempo real num M4) e no navegador, com ONNX Runtime Web. Na inferência não há PyTorch, modelo professor, codificador de voz nem conexão de rede.
O pingo-ptbr é um modelo de pesquisa. As palavras saem com clareza, mas o vocoder de 16 kHz dá à voz um som de "chamada telefônica" e uma textura um pouco metálica. Veja em Avaliação o que foi e o que não foi medido.
Ouça:
Demo no navegador: semfence/pingo-ptbr-demo · Autor: Gustavo Toledo · SemFence · https://semfence.com
Só português do Brasil. Não lê português europeu nem outras línguas. Versão em inglês deste card:
README.en.md.
| pingo-ptbr | pingo-ptbr-w96 | pivo-ptbr (float32) | |
|---|---|---|---|
| Arquivo de pesos | 0,87 MB | 1,09 MB | 5,6 MB |
| Parâmetros (acústico + vocoder) | 270.081 + 816.597 | 584.897 + 816.597 | 584.897 + 816.597 |
WER no MiniMax pt, F_s4 / M_sm4 |
0,86% / 0,81% | 0,81% / 1,00% | 0,95% / 0,95% |
Ouça
Todas as amostras foram lidas por weights/pingo-ptbr.bin, sem edição.
| Texto | F_s4 | M_sm4 |
|---|---|---|
| Olá! Eu sou uma voz em português do Brasil, feita pela SemFence. Estou rodando aqui mesmo, no seu aparelho: nada do que você escreve sai dele. | ||
| Oi! Tudo bem? Pode escrever qualquer coisa aqui que eu leio para você. | ||
| A reunião foi marcada para as 15h30 do dia 14/03/2026, e o pagamento de R$ 1.250,50 vence em 3 dias. | ||
| Você acha mesmo que eu ia esquecer o seu aniversário? Claro que não! | ||
| Ela nunca tinha visto o mar, e por muito tempo ficou parada na beira da água, sem dizer uma palavra. | ||
| Este modelo cabe em menos de um megabyte e foi treinado pela SemFence, com dados abertos para qualquer pessoa usar. | ||
| Publicamos o código no GitHub e o modelo no Hugging Face, para que outras pessoas possam testar e melhorar. |
samples/startup_sentences/ tem 15 frases de tecnologia e startups (MVP, deploy, API, rodadas de investimento...) nas duas vozes; os
textos estão em eval/startup_sentences.json.
Início rápido
Com Python 3.10 ou mais novo num Mac com Apple Silicon, a partir de um clone deste repositório:
python -m venv .venv && source .venv/bin/activate
python -m pip install -r requirements.txt
python inference.py synthesize --voice F_s4 --text "Olá! Esta é a voz da SemFence." --output hello.wav
python inference.py synthesize --voice M_sm4 --speed 1.1 --text-file text.txt --output out.wav
python inference.py synthesize --model weights/pingo-ptbr-w96.bin --voice F_s4 --text "Olá!" --output hello.wav # a edição de 1,09 MB
Ou em Python:
import sys; sys.path.insert(0, "pingo")
import speak, soundfile as sf
model = speak.Pingo("weights/pingo-ptbr.bin") # lê o arquivo e desquantiza uma vez
audio = speak.speak(model, "Olá! Esta é a voz da SemFence.", voice="M_sm4", speed=1.0)
sf.write("hello.wav", audio, 16000) # PCM mono float32 a 16 kHz
No navegador (ONNX)
Os quatro grafos ONNX (onnx/: encoder, decoder, conditioning, vocoder_step, 1,3 MB no total) têm os mesmos pesos do .bin, guardados em
int8 com escala por canal e expandidos por um nó DequantizeLinear. A demo em web/ os roda com ONNX Runtime Web (WASM, CPU) e o fonemizador
dizione-ptbr-js; nada do que se digita sai do aparelho.
python training/export_onnx.py weights/pingo-ptbr.bin onnx --vocoder-onnx PASTA_COM_ONNX_DO_PIVO # gera onnx/ e confere com o PyTorch
bash web/build_assets.sh onnx ../dizione-ptbr-js # copia para web/public/assets
python3 -m http.server 8767 --directory web/public # abra http://localhost:8767
Conferido no Chromium: a frase do exemplo "Startup" (voz feminina) sai com 117.120 amostras, RMS 0,1322 e pico 0,732, igual ao MLX.
Carregue os grafos com otimização basic (o worker.js já faz): os níveis extended/all do ONNX Runtime fundem o DequantizeLinear com um núcleo
int8 que perde precisão (erro 0,02 no encoder em vez de 1e-6).
O pingo-ptbr usa um runtime próprio e pequeno, então não funciona com o AutoModel do Transformers nem com a Inference API hospedada.
A primeira frase é mais lenta porque o MLX compila o vocoder. Use a CPU (o speak.py já usa): o modelo é pequeno demais para a GPU
compensar, e o vocoder avança em passos de 40 amostras em série.
Tratamento do texto
O front end é o dizione-ptbr: normaliza números, datas, horas e moeda, converte as palavras em 55 símbolos de fonema e marca a sílaba tônica. Textos longos são divididos em frases (o mesmo divisor do tiny-voca-ptbr); uma fala pode ter no máximo 3.000 quadros (30 s), e a velocidade vai de 0,5 a 2,0.
Palavras em inglês. O fonemizador lê palavras estrangeiras com regras do português ("Hugging Face" perderia o "H" e sairia errado).
Por isso o speak.py reescreve uma lista curta de termos de tecnologia do jeito que são falados antes de fonemizar, por exemplo
Hugging Face → Ráguin Feice, GitHub → Guit rub (e a pausa entre as duas palavras sai, com vogal final ɐ), startup → istártape, deploy → diplói. A lista está em
pingo/pronunciation.py e é fácil de estender; --no-respelling desliga. O texto que você exibe mantém a grafia normal.
Como funciona
O texto vira fonemas; os fonemas viram características de voz; um vocoder pequeno e rápido transforma as características em onda sonora.
Em detalhe (docs/HOW-IT-WORKS.md, versão em português em docs/pt-BR/):
- Um codificador de texto (6 blocos que alternam atenção de consulta agrupada com RoPE, RMSNorm e FFN com SiLU em porta, e convolução dilatada) lê os fonemas, um embedding de voz e um embedding de acento.
- Um preditor de duração diz quantos quadros de 10 ms cada fonema dura. Cada fonema é repetido por esse tempo e recebe quatro sinais
de temporização
[2f−1, sin(πf), cos(πf), log1p(n)/log1p(200)]. - Um decodificador causal (2 blocos de atenção, janela de 64 quadros) prevê 20 características a cada 10 ms: 18 coeficientes cepstrais, altura (pitch) e correlação de pitch.
- O vocoder FARGAN do Xiph/Opus, convertido pelo PiVo, gera quatro subquadros de 40 amostras por quadro a 16 kHz. Não depende da língua e não foi retreinado.
O desenho é o do PiVo (relatório técnico); a nossa implementação do modelo acústico e o código de treino são próprios. Aqui a largura é 64 (PiVo e pivo-ptbr usam 96) e o FFN tem 128 unidades.
Quantização por camada
Um peso float32 ocupa 4 bytes. O pingo-ptbr.bin guarda cada matriz como inteiros pequenos mais uma escala fp16 por canal de saída
(peso ≈ inteiro × escala), e escolhe o número de bits de cada camada conforme a importância dela. Ao carregar, os inteiros são
multiplicados de volta para float32 e o modelo roda normalmente: só o arquivo encolhe.
| Parte | Bits | Por quê |
|---|---|---|
| Acústico: atenção, FFN e convoluções do codificador | 5 | tolerantes |
| Acústico: decodificador | 6 | última etapa, mais sensível |
| Acústico: preditor de duração | 6 | erro de duração vira ritmo errado |
| Acústico: embeddings (fonema, voz, acento) | 8 | muito sensíveis e minúsculos (12 mil pesos) |
Vocoder: camadas tolerantes (glu*, gru3.*, gru2.hidden, frame_glu, skip_glu, ...) |
5 ou 6 | medido, veja docs/EXPERIMENTS.md |
| Vocoder: demais camadas | 8 | |
| Tensores 1-D (normas, vieses) | 32 | poucos |
Quantizar tudo em 4 bits dá 0,75 MB, mas com ruído audível no vocoder; um esquema misto de 0,66 MB para o vocoder tem distorção log-mel de
0,28, contra 0,73 de 4 bits uniformes (8 bits: 0,21). As tabelas estão em docs/EXPERIMENTS.md.
Dados de treino
Toda a fala de treino é sintética: semfence/ptbr-synthetic-speech
(24,7 h, CC BY 4.0), gerada com o Chatterbox Multilingual pt-BR (MIT) a partir de duas vozes de referência também sintéticas. Nenhuma
gravação de pessoa real foi usada. Os textos vêm de semfence/ptbr-sentences.
O corpus dá 19.024 trechos de treino e 818 de validação (trechos com erro de palavra acima de 15% na checagem de qualidade do dataset foram
descartados). Os trechos são reamostrados de 24 para 16 kHz; as características vêm do extrator nativo do Opus (fargan_demo -features,
rev bafd40d); as durações dos fonemas vêm do alinhamento forçado CTC com facebook/wav2vec2-lv-60-espeak-cv-ft, usado só para rotular os dados.
Treino
Perda smooth-L1 sobre as características normalizadas mais 0,1 × erro quadrático da duração em log1p; AdamW, lote 16, taxa de aprendizado
3e-4 com 200 passos de aquecimento e decaimento cosseno até 10%. 40.000 passos numa RTX 3090 alugada, a cerca de 18 passos por segundo
(a GPU fica ociosa em ~18%: o gargalo é a CPU montando os lotes), cerca de 37 minutos e aproximadamente US$ 0,14. A perda de validação
(característica + 0,1 × duração) caiu até o fim: 0,2028 (2 mil passos), 0,1789 (10 mil), 0,1736 (20 mil), 0,1707 (30 mil), 0,1699 (40 mil).
Como referência, o acústico de largura 96 do pivo-ptbr chegou a 0,1682. O modelo estreito, com 46% dos parâmetros, não tinha começado a
sobreajustar aos 40 mil passos, então mais passos podem ajudar um pouco. Receita completa e comandos:
docs/HOW-WE-TRAINED.md (em português: docs/pt-BR/).
Avaliação
100 frases do conjunto MiniMax pt (usado pelo open-tts-leaderboard), lidas a partir
do .bin e transcritas com o Qwen3-ASR, usando o normalizador do leaderboard. O conjunto está escrito em português europeu (grafias como
"cerimónia"), o que pesa contra todos os modelos aqui.
| Modelo | Pesos | F_s4 | M_sm4 |
|---|---|---|---|
| pingo-ptbr (largura 64, quantizado, com limite de duração) | 0,87 MB | 0,86% | 0,81% |
| pingo-ptbr-w96 (largura 96, quantizado) | 1,09 MB | 0,81% | 1,00% |
| pivo-ptbr (float32, medido com MLX) | 5,6 MB | 0,95% | 0,95% |
| pivo-ptbr (float32, ONNX, publicado) | 5,8 MB | 0,95% | 0,81% |
| tiny-voca-ptbr (4,5M parâmetros, 24 kHz) | maior | 0,90% | 0,86% |
O WER fica em torno de 1% e a medida oscila cerca de ±0,2 ponto (100 frases por voz), então as diferenças desta tabela estão dentro do
ruído. As transcrições por trecho estão em eval/; os resultados em formato de máquina, em evaluation.json.
O que isto não mostra.
- O avaliador é um modelo automático. WER baixo diz que as palavras são inteligíveis, não que a voz é natural. Nenhum dos dois pingos passou por teste de audição com várias pessoas.
- A audição informal do autor foi feita no esquema de alocação de bits (modelo acústico largo, 1,09 MB): soou igual a manter 8 bits em tudo, enquanto 4 bits em tudo teve ruído audível. O modelo estreito foi comparado só por WER e pela perda de validação do treino.
- O vocoder de 16 kHz dá qualidade de "chamada telefônica" e textura metálica, mais sintética que o tiny-voca-ptbr (24 kHz). Isso já existe em float32; não vem da quantização.
- A voz feminina pode passar um pouco de 1,0 no pico; o
speak.pyreduz o ganho.
Velocidade: cerca de 24× o tempo real num Apple M4 (MLX, CPU, 14 frases incluindo a fonemização). A memória não foi medida à parte: os pesos são desquantizados para float32 ao carregar, então a RAM não encolhe junto com o arquivo.
Limitações
- Só português do Brasil; duas vozes fixas, sem clonagem de voz; sotaques regionais não são modelados.
- O fonemizador não desambigua homógrafos; palavras estrangeiras são lidas com regras do português (só as de
pronunciation.pyforam corrigidas); siglas sem vogais são soletradas. Números, datas, horas e moeda são normalizados por regras; telefones, URLs e unidades não. - No máximo 30 s por chamada; textos longos são divididos em frases. Sem streaming nem controle de tom ou emoção; só voz e velocidade.
- MLX (Apple Silicon) e, via
pingo/qpack.py, NumPy. Os 0,87 MB são o arquivo de pesos.bin; o ONNX (1,3 MB) guarda os mesmos valores em int8, sem empacotar em 5 a 8 bits, e o runtime expande tudo para float32 ao carregar. - A quantização é pós-treino, sem calibração nem treino consciente de quantização. O vocoder é o gargalo de qualidade (e 0,66 dos 0,87 MB); reduzi-lo mais exige ajuste fino ou poda do FARGAN, o que não fizemos.
Uso responsável
As duas vozes são sintéticas e não imitam ninguém. Não use o modelo para se passar por uma pessoa nem para enganar ouvintes: avise quando a voz for gerada por computador. O áudio de treino veio do Chatterbox, que embute a marca d'água Perth; não verificamos se algo dela sobrevive na saída deste modelo.
Arquivos
| Caminho | Conteúdo |
|---|---|
weights/pingo-ptbr.bin |
O modelo: acústico (largura 64) + vocoder FARGAN, 5-8 bits por peso, escalas fp16, cabeçalho com configuração, vozes e símbolos |
weights/pingo-ptbr-w96.bin |
Mesmo formato com o acústico do pivo-ptbr (largura 96), não retreinado, só quantizado (1,09 MB) |
checkpoints/acoustic.pt |
Checkpoint PyTorch float32 do acústico de largura 64, passo 40.000 |
pingo/ |
speak.py (texto → voz), qpack.py (formato do arquivo), pingo_mlx.py (o modelo em MLX), pronunciation.py |
onnx/ |
Os 4 grafos ONNX (1,3 MB, pesos int8) e metadata.json |
web/ |
Demo no navegador (ONNX Runtime Web), build_assets.sh |
inference.py, requirements.txt |
Ponto de entrada de linha de comando e dependências |
training/ |
Preparação de dados, treino, conversão de checkpoint e exportação ONNX (prepare.py, features.py, model.py, train.py, convert_acoustic.py, export_onnx.py) |
evaluation/ |
evaluate_wer.py: gera as frases e mede o WER |
docs/ |
HOW-WE-TRAINED.md, HOW-IT-WORKS.md, EXPERIMENTS.md (versões em português em docs/pt-BR/) |
samples/, eval/ |
Áudios desta página; transcrições por trecho, as frases de startup |
model_manifest.json, SHA256SUMS, PROVENANCE.json, evaluation.json |
Tamanhos e hashes, linhagem, resultados completos |
LICENSE, NOTICE, THIRD_PARTY.md, LICENSES/ |
CC BY 4.0, créditos, avisos de terceiros (o vocoder é BSD-3-Clause) |
SHA256 dos pesos: pingo-ptbr.bin 0df1c086a691379ed2da40f2a5316c1bbfdc5a2ba6585957a008a00e25e4ddd4 ·
pingo-ptbr-w96.bin 640bf3d6c8847e7802015a8acb40d532fc10f2f7adebc50947b2e6977eb204ee ·
checkpoints/acoustic.pt 94ba81b7d5bf0dd334d703f9f2840d4261ec7d67e03d791e640c8cc17bc415ea.
Licença
Pesos acústicos (este repositório): CC BY 4.0. Você pode usar, modificar, redistribuir e vender, inclusive em produtos fechados, desde que dê crédito:
pingo-ptbr, por SemFence (Gustavo Toledo), CC BY 4.0, https://huggingface.co/semfence/pingo-ptbr
Diga se alterou o modelo. Áudio gerado com o modelo não precisa de crédito. Texto da licença em LICENSE; crédito em NOTICE.
- Vocoder (a parte do vocoder dos dois
.bin): FARGAN do Xiph/Opus, BSD-3-Clause, tirado do PiVo-1.4M (Empero Research, Apache-2.0) com os pesos guardados em menos bits. Avisos emLICENSES/; mantenha-os ao redistribuir. - Código: Apache-2.0. Datasets: CC BY 4.0, crédito a SemFence (Gustavo Toledo).
- Léxico do fonemizador: CC BY 4.0, derivado do dicionário de português do Brasil do Montreal Forced Aligner (Michael McAuliffe e Morgan Sonderegger), com alterações.
Citação
@software{semfence2026pingoptbr,
author = {{SemFence} and Toledo, Gustavo},
title = {pingo-ptbr: a 0.87 MB two-voice Brazilian Portuguese text-to-speech model},
year = {2026},
url = {https://huggingface.co/semfence/pingo-ptbr}
}
Cite também o PiVo e o pivo-ptbr.
Agradecimentos
- PiVo-1.4M, de Leon Lehmann (Empero Research): a arquitetura, a receita e o vocoder.
- Opus / FARGAN, Xiph.Org: o vocoder e o extrator de características (BSD-3-Clause).
- tiny-voca, de Muhammed Nazeem: a base do tiny-voca-ptbr, cujo front end e alinhador rotulam nossos dados.
- Chatterbox Multilingual (Resemble AI, MIT): gerou a fala de treino.
- Mozilla Common Voice (CC0): frases em português.
- O dicionário de pronúncia do português do Brasil do Montreal Forced Aligner (CC BY 4.0).
facebook/wav2vec2-lv-60-espeak-cv-ft(alinhamento) e Qwen3-ASR (avaliação).