primocode 8.11.2 → 8.13.0

package/lib/studio.js

@@ -39,7 +39,10 @@ const BASE = `http://127.0.0.1:${PORTA}`;
 
 // Só o código do Studio é atualizado; `arquivos/` e `midia/` (o que o usuário
 // criou) nunca são tocados.
-const COPIAVEIS = new Set(['server.py', 'web', 'ferramentas', 'README.md', 'PRIMOCODE.md']);
+// voz.py é módulo do servidor, não enfeite: sem ele o server.py não importa
+// e o Studio inteiro deixa de subir. Todo arquivo .py do Studio precisa
+// entrar aqui.
+const COPIAVEIS = new Set(['server.py', 'voz.py', 'web', 'ferramentas', 'README.md', 'PRIMOCODE.md']);
 
 /**
  * Onde está o Python 3 desta máquina.
@@ -300,11 +303,32 @@ async function comIdReal(id, fn) {
 
 const ler = (id) => comStudio(() => comIdReal(id, async () => ({ ok: true, arquivo: await pedir('GET', `/api/arquivos/${encodeURIComponent(id)}`) })));
 
+// Quando o documento tem narração, o servidor começa a baixar a voz neural
+// sozinho. São ~90 MB, e o usuário merece saber por que o primeiro vídeo sai
+// com uma voz e o próximo com outra — melhor ele ouvir isso do agente do que
+// achar que o programa está inconstante.
+async function avisoDaVoz(doc) {
+    const temNarracao = !!(doc && (doc.narracao
+        || (doc.cenas || []).some((c) => c && typeof c.narracao === 'string' && c.narracao.trim())));
+    if (!temNarracao) return null;
+    try {
+        const s = await pedir('GET', '/api/voz/status', null, 3000);
+        if (s && s.piper && !s.piper.pronta && s.piper.suportado) {
+            return 'A voz neural (offline, ilimitada) está sendo baixada agora — ~90 MB, uma vez só. '
+                + 'Até terminar a narração sai por uma voz de reserva, mais simples. Diga isso ao usuário.';
+        }
+    } catch { /* status é enfeite; não pode atrapalhar a criação */ }
+    return null;
+}
+
 const criar = ({ ferramenta, titulo, doc }) => comStudio(async () => {
     if (!ferramenta) return { ok: false, error: 'Diga a ferramenta: prisma, tela, prosa, grade, corte ou traco.' };
     if (!doc) return { ok: false, error: 'Falta o doc. Leia a spec com studio_spec antes de criar.' };
     const r = await pedir('POST', '/api/arquivos', { ferramenta, titulo: titulo || 'Sem título', doc });
-    return { ok: true, ...r };
+    const saida = { ok: true, ...r };
+    const voz = await avisoDaVoz(doc);
+    if (voz) saida.voz = voz;
+    return saida;
 });
 
 // O que o agente recebe de volta depois de mexer num arquivo. Devolver o

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.11.2",
+  "version": "8.13.0",
   "description": "PrimoCode — agente de engenharia com IA e cursor próprio. Modelos grátis. Cria arquivos, roda comandos, controla navegador e desktop: abre apps, clica em botões e ícones pelo nome, digita e usa atalhos.",
   "main": "bin/primocode.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/primocode.js",
-    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js && node test/studio-versoes.test.js"
+    "test": "node test/tools.test.js && node test/ui.test.js && node test/modo.test.js && node test/pasta.test.js && node test/catalogo.test.js && node test/desktop.test.js && node test/effort.test.js && node test/claude-engine.test.js && node test/regressao.test.js && node test/memoria-conversa.test.js && node test/repeticao.test.js && node test/referencia.test.js && node test/parar.test.js && node test/continuar.test.js && node test/studio-spec.test.js && node test/studio-versoes.test.js && node test/voz.test.js && node test/editor.test.js"
   },
   "engines": {
     "node": ">=18.17.0"

package/studio/ferramentas/corte.md

@@ -138,12 +138,28 @@ na hora de tocar — sem gravar nada, sem arquivo:
   "elementos": [ ... ] }
 ```
 
-Ajuste da voz no **documento** (opcional):
+Escolha da voz no **documento** (opcional):
 
 ```json
-"voz": { "velocidade": 1, "tom": 1, "volume": 1, "lang": "pt-BR" }
+"voz": { "voz": "jeff", "grave": true, "velocidade": 1 }
 ```
 
+A síntese é neural e roda na máquina do usuário — offline, sem limite. As
+vozes pt-BR, com a frequência de cada uma medida (menor = mais grave):
+
+| id | timbre | Hz |
+|---|---|---|
+| `jeff` | grave, de locução — **é a padrão** | 139 |
+| `cadu` | grave, mais solta | 140 |
+| `edresson` | média, mais leve de baixar | 151 |
+| `faber` | clara, de leitura | 167 |
+| `tugao` | português de Portugal | — |
+
+`"grave": true` abaixa mais uns 10% — é o registro de abertura de vídeo. Não
+há voz feminina em pt-BR neste motor; se pedirem uma, diga isso em vez de
+prometer. Na primeira vez o motor é baixado sozinho (~90 MB); enquanto isso
+a narração sai por uma voz de reserva, e o vídeo nunca fica mudo.
+
 Regras que fazem diferença:
 
 - **Escreva para o ouvido, não para o olho.** A narração NÃO repete o texto da
@@ -169,6 +185,33 @@ Na cena, `transicao` define como ela **entra**:
 
 Vale o mesmo conselho das animações: varie. Tudo em `fade` parece slide, não vídeo.
 
+## Chaves de animação
+
+`anim` faz o elemento **entrar** e parar por ali. Para ele se mexer ao longo da
+cena — atravessar, crescer devagar, sumir no fim — use `chaves`: uma lista de
+instantes, com `t` de 0 (começo da cena) a 1 (fim).
+
+```json
+{ "tipo": "texto", "texto": "Atravessa a tela",
+  "chaves": [
+    { "t": 0,    "x": -400, "opacidade": 0 },
+    { "t": 0.25, "x": 0,    "opacidade": 1 },
+    { "t": 0.75, "x": 0,    "opacidade": 1 },
+    { "t": 1,    "x": 400,  "opacidade": 0 }
+  ] }
+```
+
+Campos de uma chave, todos opcionais: `x` e `y` (**deslocamento** em pixels a
+partir de onde o elemento está — não é posição absoluta), `escala` (1 = tamanho
+normal), `giro` (graus), `opacidade` (0 a 1) e `desfoque` (pixels).
+
+No elemento: `"repetir": true` roda sem parar, e `"suavizar": false` dá
+movimento constante em vez de acelerar e frear.
+
+Duas chaves já bastam. Quem tem `chaves` ignora `anim` — as duas disputariam o
+mesmo movimento, e a chave é mais específica. Use em **um ou dois** elementos
+por vídeo: tudo se mexendo ao mesmo tempo cansa e esconde a mensagem.
+
 ## Acabamento
 
 Textura por cima da cena inteira — é o que tira a cara de template:

package/studio/server.py

@@ -25,6 +25,37 @@ from urllib.parse import urlparse, unquote, urlencode
 import urllib.request
 
 RAIZ = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, RAIZ)
+try:
+    import voz as voz_lib  # noqa: E402  (precisa da RAIZ no path antes)
+except Exception as _e:    # instalação parcial, ou voz.py de uma versão velha
+    # Narração é acabamento; o Studio inteiro não pode morrer por causa dela.
+    # Sem o módulo, a corrente começa direto no Google e tudo mais funciona.
+    sys.stderr.write("[voz] módulo indisponível (%s); narração vai só pelo Google\n" % _e)
+
+    class _SemVoz:
+        @staticmethod
+        def pronta(*a, **k):
+            return False
+
+        @staticmethod
+        def sintetizar(*a, **k):
+            return None
+
+        @staticmethod
+        def instalar(*a, **k):
+            return {"pronta": False, "erro": "módulo de voz indisponível"}
+
+        @staticmethod
+        def estado():
+            return {"pronta": False, "vozes": [], "erro": "módulo de voz indisponível"}
+
+        @staticmethod
+        def apagar():
+            return {"ok": True}
+
+    voz_lib = _SemVoz()
+
 WEB = os.path.join(RAIZ, "web")
 ARQUIVOS = os.path.join(RAIZ, "arquivos")
 FERRAMENTAS = os.path.join(RAIZ, "ferramentas")
@@ -32,13 +63,21 @@ MIDIA = os.path.join(RAIZ, "midia")
 PORTA = int(sys.argv[1]) if len(sys.argv) > 1 else 7777
 
 def _assinatura():
-    """SHA-1 do próprio arquivo, lido NA SUBIDA. Se o npm trocar o código no
+    """SHA-1 do código do Studio, lido NA SUBIDA. Se o npm trocar o código no
     disco depois, o processo no ar continua respondendo a assinatura antiga —
     e é exatamente essa diferença que o CLI usa para saber que precisa
-    reiniciar o Studio em vez de servir a versão velha para sempre."""
+    reiniciar o Studio em vez de servir a versão velha para sempre.
+
+    Entra todo módulo do Studio, não só este arquivo: uma correção que mexa
+    apenas na voz também precisa derrubar o processo velho."""
+    h = hashlib.sha1()
     try:
-        with open(os.path.abspath(__file__), "rb") as fh:
-            return hashlib.sha1(fh.read()).hexdigest()[:12]
+        for nome in ("server.py", "voz.py"):
+            caminho = os.path.join(RAIZ, nome)
+            if os.path.exists(caminho):
+                with open(caminho, "rb") as fh:
+                    h.update(fh.read())
+        return h.hexdigest()[:12]
     except Exception:
         return "?"
 
@@ -234,6 +273,32 @@ def ler_versao(arq_id, versao):
         return json.load(fh)
 
 
+def _tem_narracao(doc):
+    if not isinstance(doc, dict):
+        return False
+    if isinstance(doc.get("narracao"), str) and doc["narracao"].strip():
+        return True
+    for c in doc.get("cenas") or []:
+        if isinstance(c, dict) and isinstance(c.get("narracao"), str) and c["narracao"].strip():
+            return True
+    return False
+
+
+def preparar_voz(doc):
+    """Documento com narração chegou: começa a baixar a voz agora.
+
+    O download é de ~90 MB e leva algum tempo. Fazê-lo quando o usuário
+    aperta play seria tarde — ele ouviria a voz robótica do Google. Fazê-lo
+    aqui, no instante em que o roteiro é gravado, dá ao download a mesma
+    janela que o agente gasta escrevendo o resto: quando alguém toca o vídeo,
+    a voz boa já está na máquina. Se não der tempo, a corrente cobre."""
+    if _tem_narracao(doc) and not voz_lib.pronta():
+        try:
+            voz_lib.instalar()
+        except Exception:
+            pass
+
+
 def mesclar(antigo, novo):
     """O documento novo por cima do antigo, chave a chave.
 
@@ -369,6 +434,7 @@ def criar(dados):
         if problema:
             raise ValueError(problema)
 
+    preparar_voz(doc)
     arq_id = ferramenta + "-" + slugify(titulo) + "-" + uuid.uuid4().hex[:5]
     return gravar({
         "id": arq_id,
@@ -742,17 +808,25 @@ class Handler(SimpleHTTPRequestHandler):
         return super().do_GET()
 
     # ── Voz ────────────────────────────────────────────────────────────
-    # Ponte para o TTS do Google. Existe porque o Google não manda cabeçalho
-    # de CORS: do navegador direto o pedido morre, daqui funciona.
+    # A narração inteira é decidida AQUI, no Python, e não no navegador.
+    #
+    # Antes o navegador tentava a voz neural do Edge por WebSocket e, quando
+    # ela não subia, caía no speechSynthesis — o TTS da própria máquina, que
+    # soa a computador. A voz do Edge parou de subir (a Microsoft responde
+    # 403 na síntese), então na prática TODO vídeo saía com voz de robô. Era
+    # o que o usuário estava ouvindo.
     #
-    # É a rede de segurança da narração. O caminho bom é a voz neural do Edge,
-    # que fala direto do navegador por WebSocket (sem CORS) e tem voz grave de
-    # verdade para vídeo; quando ela não sobe, cai aqui — uma voz só, sem
-    # escolha, mas que responde sempre.
+    # A corrente agora é esta, e o navegador só consome o resultado:
+    #   1. PIPER    neural, roda na máquina, offline, ilimitado, com escolha
+    #               de voz — inclusive graves de verdade (voz.py mede e diz
+    #               a frequência de cada uma). É o bom.
+    #   2. VOICEBOX se o usuário tiver o app: voz clonável.
+    #   3. GOOGLE   uma voz só, robótica, mas responde na hora sem instalar
+    #               nada — é o que cobre enquanto o Piper baixa.
     #
-    # O endpoint recusa texto comprido, então a frase é cortada em pedaços de
-    # até 190 caracteres, sempre numa fronteira de palavra, e os MP3 são
-    # emendados. MP3 aceita concatenação de quadros: é feio, mas toca.
+    # O endpoint do Google recusa texto comprido, então a frase é cortada em
+    # pedaços de até 190 caracteres, sempre numa fronteira de palavra, e os
+    # MP3 são emendados. MP3 aceita concatenação de quadros: é feio, mas toca.
     def voz(self, query):
         from urllib.parse import parse_qs
         q = parse_qs(query or "")
@@ -763,22 +837,45 @@ class Handler(SimpleHTTPRequestHandler):
         if len(texto) > 4000:
             texto = texto[:4000]
 
-        voz = (q.get("voz", [""])[0] or "").strip()
+        voz_pedida = (q.get("voz", [""])[0] or "").strip()
         instrucao = (q.get("instrucao", [""])[0] or "").strip()
         motor = (q.get("motor", [""])[0] or "").strip()
+        grave = (q.get("grave", [""])[0] or "").lower() in ("1", "true", "sim")
+        try:
+            velocidade = float(q.get("velocidade", ["1"])[0])
+        except ValueError:
+            velocidade = 1.0
 
         tipo = "audio/mpeg"
         audio = b""
-        # 1) Voicebox, se o usuário tiver instalado: voz clonável, ilimitada e
+
+        # 1) Piper: o motor bom. Se ainda não baixou, começa a baixar agora e
+        #    segue para o próximo — quem pediu narração hoje ouve o Google, e
+        #    a partir da próxima já é voz de verdade.
+        if motor not in ("google", "voicebox"):
+            try:
+                if voz_lib.pronta(voz_pedida or None):
+                    audio = voz_lib.sintetizar(texto, voz_pedida or None,
+                                               grave=grave, velocidade=velocidade) or b""
+                    if audio:
+                        tipo = "audio/wav"
+                else:
+                    voz_lib.instalar(voz_pedida or None)
+            except Exception as e:
+                sys.stderr.write("[voz] Piper falhou (%s); seguindo a corrente\n" % e)
+                audio = b""
+
+        # 2) Voicebox, se o usuário tiver instalado: voz clonável, ilimitada e
         #    sem depender de nada na internet.
-        if motor != "google" and self._voicebox_vivo():
+        if not audio and motor != "google" and self._voicebox_vivo():
             try:
-                audio, tipo = self._voz_voicebox(texto, voz, instrucao)
+                audio, tipo = self._voz_voicebox(texto, voz_pedida, instrucao)
             except Exception as e:
                 sys.stderr.write("[voz] Voicebox falhou (%s); indo de Google\n" % e)
                 audio = b""
-        # 2) Google: uma voz só, mas responde sempre.
+        # 3) Google: uma voz só, mas responde sempre.
         if not audio:
+            tipo = "audio/mpeg"
             try:
                 audio = b"".join(self._trecho_de_voz(t, idioma) for t in _picar(texto, 190))
             except Exception as e:                  # rede, bloqueio, mudança do serviço
@@ -807,7 +904,8 @@ class Handler(SimpleHTTPRequestHandler):
 
     def voz_status(self):
         """O que está disponível para narrar, para a interface não oferecer o
-        que não existe."""
+        que não existe — e para ela poder mostrar o download em vez de fingir
+        que já está tudo pronto."""
         vivo = self._voicebox_vivo()
         vozes = []
         if vivo:
@@ -818,6 +916,7 @@ class Handler(SimpleHTTPRequestHandler):
             except Exception:
                 vozes = []
         return self.js({
+            "piper": voz_lib.estado(),
             "voicebox": {"ativo": vivo, "vozes": vozes, "site": "https://voicebox.sh"},
             "google": {"ativo": True},
         })
@@ -960,6 +1059,13 @@ class Handler(SimpleHTTPRequestHandler):
             corpo, status = guardar_midia(self.corpo())
             return self.js(corpo, status)
 
+        if rota == "/api/voz/instalar":
+            pedido = self.corpo()
+            if pedido.get("apagar"):
+                return self.js(voz_lib.apagar())
+            return self.js(voz_lib.instalar(pedido.get("voz"),
+                                            esperar=min(60, int(pedido.get("esperar") or 0))))
+
         if rota == "/api/sair":
             # Só o CLI chama, e só quando o código no disco mudou (update do
             # npm). Sem isto o processo antigo ficava no ar servindo o bug que
@@ -1050,6 +1156,7 @@ class Handler(SimpleHTTPRequestHandler):
                 if problema:
                     return self.js({"erro": problema}, 400)
 
+        preparar_voz(novo)
         versao = guardar_versao(a)
         if "titulo" in dados:
             a["titulo"] = dados["titulo"]

package/studio/voz.py

@@ -0,0 +1,307 @@
+"""Narração de verdade, gerada aqui em Python.
+
+── O PROBLEMA ────────────────────────────────────────────────────────────
+A narração era feita no NAVEGADOR. Havia três caminhos lá: a voz neural do
+Edge por WebSocket, o TTS do Google por este servidor, e o speechSynthesis
+da própria máquina. O primeiro morreu — a Microsoft passou a responder 403
+na síntese (a lista de vozes ainda responde; a síntese, não), e isso é uma
+trava que eles impõem de propósito, não um bug para contornar. O terceiro é
+o TTS do sistema: existe em todo computador e soa a computador. Resultado
+prático: o usuário pedia vídeo institucional e ouvia voz de robô.
+
+── A SAÍDA ───────────────────────────────────────────────────────────────
+Trazer a síntese para cá, para o Python, onde ela não depende de navegador
+nem de serviço de ninguém. O motor é o Piper (MIT, do projeto Rhasspy):
+rede neural que roda na máquina, offline, sem chave, sem cota e sem limite.
+Ele não vem no pacote — são ~90 MB entre programa e modelo — então é
+baixado uma vez, sob demanda, e daí em diante a narração é instantânea e
+funciona sem internet.
+
+── AS VOZES ──────────────────────────────────────────────────────────────
+As quatro vozes pt-BR do Piper foram sintetizadas e MEDIDAS: a frequência
+fundamental de cada uma está na tabela abaixo, apurada por autocorrelação
+sobre os quadros com tom. Não é adjetivo de catálogo, é medida. Por isso a
+padrão é a Jeff, de 139 Hz — a mais grave, que é o que sustenta abertura de
+vídeo. E por isso não há voz feminina listada: o Piper não tem nenhuma em
+pt-BR, e inventar rótulo seria pior que admitir a falta.
+
+── A CORRENTE ────────────────────────────────────────────────────────────
+1. PIPER    neural, offline, ilimitado, com escolha de voz. O bom.
+2. VOICEBOX se o usuário tiver o app instalado — voz clonável.
+3. GOOGLE   uma voz só, robótica, mas responde na hora e sem instalar nada.
+
+Cada um cai no seguinte quando falha. A narração nunca fica muda por falta
+de motor: enquanto o Piper baixa, o Google cobre.
+"""
+
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import threading
+import urllib.parse
+import urllib.request
+import wave
+import zipfile
+
+CASA = os.path.join(os.path.expanduser("~"), ".primocode", "vozes")
+
+RELEASE = "https://github.com/rhasspy/piper/releases/download/2023.11.14-2/"
+VOZES_URL = "https://huggingface.co/rhasspy/piper-voices/resolve/main/"
+
+# O pacote do Piper para cada sistema. Os cinco nomes foram conferidos no ar.
+PACOTES = {
+    ("Linux", "x86_64"): "piper_linux_x86_64.tar.gz",
+    ("Linux", "aarch64"): "piper_linux_aarch64.tar.gz",
+    ("Linux", "arm64"): "piper_linux_aarch64.tar.gz",
+    ("Darwin", "x86_64"): "piper_macos_x64.tar.gz",
+    ("Darwin", "arm64"): "piper_macos_aarch64.tar.gz",
+    ("Windows", "AMD64"): "piper_windows_amd64.zip",
+    ("Windows", "x86_64"): "piper_windows_amd64.zip",
+}
+
+# hz: fundamental medida, em Hz. Quanto menor, mais grave.
+CATALOGO = [
+    {"id": "jeff", "nome": "Jeff", "hz": 139, "grave": True, "padrao": True,
+     "tom": "grave, de locução", "caminho": "pt/pt_BR/jeff/medium/pt_BR-jeff-medium", "mb": 60},
+    {"id": "cadu", "nome": "Cadu", "hz": 140, "grave": True,
+     "tom": "grave, mais solta", "caminho": "pt/pt_BR/cadu/medium/pt_BR-cadu-medium", "mb": 60},
+    {"id": "faber", "nome": "Faber", "hz": 167,
+     "tom": "clara, de leitura", "caminho": "pt/pt_BR/faber/medium/pt_BR-faber-medium", "mb": 60},
+    {"id": "edresson", "nome": "Edresson", "hz": 151,
+     "tom": "média, mais leve de baixar", "caminho": "pt/pt_BR/edresson/low/pt_BR-edresson-low", "mb": 21},
+    {"id": "tugao", "nome": "Tugão", "hz": 0,
+     "tom": "português de Portugal", "caminho": "pt/pt_PT/tugão/medium/pt_PT-tugão-medium", "mb": 60},
+]
+
+POR_ID = {v["id"]: v for v in CATALOGO}
+PADRAO = next(v["id"] for v in CATALOGO if v.get("padrao"))
+
+# Estado do download, para a interface poder mostrar em vez de fingir que
+# está tudo pronto. Um dicionário simples, protegido por tranca porque quem
+# escreve é a thread do download e quem lê são as requisições.
+_tranca = threading.Lock()
+_baixando = {"ativo": False, "voz": None, "pct": 0, "etapa": "", "erro": None}
+_thread = None
+
+
+def _versao_pacote():
+    return PACOTES.get((platform.system(), platform.machine()))
+
+
+def pasta_piper():
+    return os.path.join(CASA, "piper")
+
+
+def binario():
+    """O executável do Piper, se já foi baixado."""
+    nome = "piper.exe" if platform.system() == "Windows" else "piper"
+    p = os.path.join(pasta_piper(), nome)
+    return p if os.path.exists(p) else None
+
+
+def modelo(voz_id):
+    v = POR_ID.get(voz_id or PADRAO)
+    if not v:
+        return None
+    base = os.path.join(CASA, os.path.basename(v["caminho"]))
+    return base if os.path.exists(base + ".onnx") and os.path.exists(base + ".onnx.json") else None
+
+
+def instaladas():
+    return [v["id"] for v in CATALOGO if modelo(v["id"])]
+
+
+def pronta(voz_id=None):
+    return bool(binario() and modelo(voz_id or PADRAO))
+
+
+# ------------------------------------------------------------------ baixar --
+
+def _baixar(url, destino, fatia=(0, 100)):
+    """Baixa mostrando progresso dentro da fatia que lhe cabe do total."""
+    ini, fim = fatia
+    with urllib.request.urlopen(url, timeout=60) as r:
+        total = int(r.headers.get("Content-Length") or 0)
+        feito = 0
+        tmp = destino + ".parcial"
+        with open(tmp, "wb") as fh:
+            while True:
+                p = r.read(262144)
+                if not p:
+                    break
+                fh.write(p)
+                feito += len(p)
+                if total:
+                    with _tranca:
+                        _baixando["pct"] = int(ini + (fim - ini) * feito / total)
+        # Só vira o arquivo de verdade quando terminou inteiro: assim uma
+        # queda de rede não deixa um modelo pela metade que "existe".
+        os.replace(tmp, destino)
+
+
+def _instalar_piper():
+    pacote = _versao_pacote()
+    if not pacote:
+        raise RuntimeError("não há Piper para %s/%s" % (platform.system(), platform.machine()))
+    os.makedirs(CASA, exist_ok=True)
+    with _tranca:
+        _baixando["etapa"] = "baixando o motor de voz"
+    alvo = os.path.join(CASA, pacote)
+    _baixar(RELEASE + pacote, alvo, (0, 35))
+
+    with _tranca:
+        _baixando["etapa"] = "instalando o motor"
+    if pacote.endswith(".zip"):
+        with zipfile.ZipFile(alvo) as z:
+            z.extractall(CASA)
+    else:
+        with tarfile.open(alvo) as t:
+            t.extractall(CASA)
+    os.remove(alvo)
+
+    exe = binario()
+    if not exe:
+        raise RuntimeError("o pacote do Piper não trouxe o executável")
+    if platform.system() != "Windows":
+        os.chmod(exe, 0o755)
+
+
+def _instalar_voz(voz_id):
+    v = POR_ID[voz_id]
+    os.makedirs(CASA, exist_ok=True)
+    base = os.path.join(CASA, os.path.basename(v["caminho"]))
+    with _tranca:
+        _baixando["etapa"] = "baixando a voz %s" % v["nome"]
+    # O nome tem "ã" no caso do tugão: a URL precisa disso escapado.
+    url = VOZES_URL + urllib.parse.quote(v["caminho"])
+    _baixar(url + ".onnx.json", base + ".onnx.json", (35, 40))
+    _baixar(url + ".onnx", base + ".onnx", (40, 100))
+
+
+def _rotina(voz_id):
+    global _thread
+    try:
+        if not binario():
+            _instalar_piper()
+        if not modelo(voz_id):
+            _instalar_voz(voz_id)
+        with _tranca:
+            _baixando.update(ativo=False, pct=100, etapa="pronta", erro=None)
+    except Exception as e:
+        sys.stderr.write("[voz] instalação falhou: %s\n" % e)
+        with _tranca:
+            _baixando.update(ativo=False, etapa="", erro=str(e))
+    finally:
+        _thread = None
+
+
+def instalar(voz_id=None, esperar=0):
+    """Começa (ou acompanha) a instalação. Não bloqueia, por padrão.
+
+    Quem chama é a interface e o próprio servidor quando vê um documento com
+    narração: preparar a voz enquanto o agente ainda escreve o roteiro é o
+    que faz ela estar pronta na hora de tocar."""
+    global _thread
+    voz_id = voz_id if voz_id in POR_ID else PADRAO
+    with _tranca:
+        if _thread is None and not pronta(voz_id):
+            _baixando.update(ativo=True, voz=voz_id, pct=0, etapa="começando", erro=None)
+            _thread = threading.Thread(target=_rotina, args=(voz_id,), daemon=True)
+            _thread.start()
+        t = _thread
+    if t and esperar:
+        t.join(esperar)
+    return estado()
+
+
+def estado():
+    with _tranca:
+        b = dict(_baixando)
+    return {
+        "motor": "piper",
+        "pronta": pronta(),
+        "instaladas": instaladas(),
+        "suportado": bool(_versao_pacote()),
+        "baixando": b,
+        "vozes": [{
+            "id": v["id"], "nome": v["nome"], "tom": v["tom"], "hz": v["hz"], "mb": v["mb"],
+            "instalada": bool(modelo(v["id"])),
+            "grave": bool(v.get("grave")),
+            "padrao": bool(v.get("padrao")),
+        } for v in CATALOGO],
+    }
+
+
+# --------------------------------------------------------------- sintetizar --
+
+def _mais_grave(bruto, razao):
+    """Abaixa o tom reescrevendo a taxa declarada do WAV.
+
+    Não há reamostragem: os mesmos quadros, lidos mais devagar, soam mais
+    graves na mesma proporção. Como isso também alonga o áudio, a síntese já
+    foi feita acelerada pelo mesmo fator, e a duração volta ao lugar.
+    Medido: a voz Jeff sai de 139 Hz para 125 Hz com razão 0.9."""
+    with wave.open(bruto, "rb") as w:
+        p = w.getparams()
+        quadros = w.readframes(p.nframes)
+    saida = bruto + ".grave.wav"
+    with wave.open(saida, "wb") as s:
+        s.setnchannels(p.nchannels)
+        s.setsampwidth(p.sampwidth)
+        s.setframerate(max(8000, int(p.framerate * razao)))
+        s.writeframes(quadros)
+    return saida
+
+
+def sintetizar(texto, voz_id=None, grave=False, velocidade=1.0, timeout=120):
+    """O texto vira WAV. None quando o Piper não está pronto — aí quem chamou
+    cai para o próximo motor da corrente."""
+    exe = binario()
+    voz_id = voz_id if voz_id in POR_ID else PADRAO
+    mod = modelo(voz_id)
+    if not exe or not mod:
+        return None
+
+    # Sem isto, um texto com quebra de linha vira várias falas e o Piper
+    # devolve só a última.
+    limpo = re.sub(r"\s+", " ", str(texto or "")).strip()
+    if not limpo:
+        return None
+
+    razao = 0.9 if grave else 1.0
+    # length_scale > 1 é mais devagar. A razão do grave entra aqui para a
+    # duração não crescer quando a taxa for reescrita lá embaixo.
+    escala = (1.0 / max(0.5, min(2.0, velocidade))) * razao
+
+    pasta = tempfile.mkdtemp(prefix="primo-voz-")
+    try:
+        saida = os.path.join(pasta, "voz.wav")
+        r = subprocess.run(
+            [exe, "--model", mod + ".onnx", "--config", mod + ".onnx.json",
+             "--length_scale", "%.3f" % escala, "--sentence_silence", "0.25",
+             "--output_file", saida],
+            input=limpo.encode("utf-8"),
+            stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, timeout=timeout,
+        )
+        if r.returncode != 0 or not os.path.exists(saida):
+            raise RuntimeError((r.stderr or b"").decode("utf-8", "replace")[-300:] or "piper falhou")
+        if grave:
+            saida = _mais_grave(saida, razao)
+        with open(saida, "rb") as fh:
+            return fh.read()
+    finally:
+        shutil.rmtree(pasta, ignore_errors=True)
+
+
+def apagar():
+    """Some com tudo que foi baixado. Existe para o usuário poder desfazer:
+    são 90 MB na máquina dele, e ele tem direito de recuperá-los."""
+    if os.path.isdir(CASA):
+        shutil.rmtree(CASA, ignore_errors=True)
+    return {"ok": True}