primocode 9.3.1 → 9.5.0

package/voz/primo_voz/orbe.py

@@ -1,36 +1,37 @@
 """orbe.py — a única coisa que aparece na tela no modo voz.
 
-    "ia ser a flutuante ali na parte inferior da tela, bem centralizada,
-     toda cheia de partículas, toda bonita."
+    "Quero que ele fique na parte inferior da tela, bem centralizado, um pouco
+     maior [...] mas ele tá rodando em uma caixa, deve ser totalmente
+     transparente." (23/09/2026)
 
-── POR QUE A PRIMEIRA VERSÃO FICOU FEIA, E A CULPA É DE QUATRO COISAS ──────
+── O QUE ERA A "CAIXA" ─────────────────────────────────────────────────────
+Medido com uma captura da própria janela, no Tk 9 do macOS:
 
-1. `-transparentcolor` SÓ EXISTE NO WINDOWS. No macOS ele levanta TclError,
-   que o código engolia — e a janela ficava com o fundo opaco pintado nela.
-   Era o "quadrado feio": não era desenho, era a janela inteira aparecendo.
-   No macOS a transparência de verdade se pede de outro jeito:
-   `-transparent` mais o fundo mágico `systemTransparent`.
+1. `overrideredirect(True)` NÃO tira a moldura: a janela nascia com barra de
+   título, os três botões e o nome "Primo Code Voice".
+2. O fundo `systemTransparent` saía PRETO.
+3. O Canvas não apaga o quadro anterior sobre fundo transparente: cada
+   partícula deixava um rastro, e em segundos a janela virava um borrão.
 
-2. O VÉU cobria a tela inteira com 72% de preto. A ideia era destacar a orb;
-   o efeito é escurecer o trabalho da pessoa enquanto ela fala. Saiu.
+Nenhum dos três se conserta de dentro do Tk. Então, no macOS, a orb é
+desenhada pelo próprio sistema (PyObjC): uma NSWindow sem borda, sem fundo e
+sem sombra, e uma NSView que limpa e pinta cada quadro com transparência de
+verdade — o brilho é um gradiente com alfa, não discos misturados contra uma
+cor de fundo adivinhada. Só a orb aparece; o resto da janela não existe.
 
-3. Ela nascia no CENTRO da tela — bem no meio do que a pessoa está fazendo.
-   Agora mora embaixo, centralizada na horizontal, como uma barra flutuante.
+O Tk continua sendo quem roda o laço de eventos (é ele que o resto do modo
+voz já usa), e segue como desenho de reserva fora do macOS ou sem PyObjC.
 
-4. Não havia partícula nenhuma. Havia três círculos concêntricos.
+── ONDE ELA MORA ───────────────────────────────────────────────────────────
+Embaixo, centralizada na ÁREA ÚTIL da tela — acima do Dock, não atrás dele.
+A posição é aplicada depois de a janela existir: dada cedo demais, a janela
+sem moldura ignora.
 
 ── O QUE ELA DESENHA ───────────────────────────────────────────────────────
-Um núcleo com halo suave e um enxame de partículas em órbita. A cor diz o
+Um núcleo com brilho suave e um enxame de partículas em órbita. A cor diz o
 estado; o MOVIMENTO diz a intensidade — as partículas se afastam e aceleram
 com a voz, e respiram devagar quando ele está pensando. Nenhuma palavra: quem
 está falando não lê.
-
-── O QUE NÃO DÁ PARA FAZER EM TKINTER, E COMO SE CONTORNA ─────────────────
-Não há desfoque nem gradiente: o Canvas do Tk desenha forma chapada. O halo é
-feito de círculos concêntricos com a cor interpolada contra o fundo — o
-mesmo truque de sempre, e o motivo de o fundo precisar ser conhecido. Onde a
-janela é transparente de verdade, o "fundo" para a mistura é o preto, que é o
-que mais se aproxima de qualquer tela.
 """
 from __future__ import annotations
 
@@ -39,23 +40,27 @@ import queue
 import random
 import sys
 import tkinter as tk
-from typing import Callable, Optional
+from typing import Callable, List, Optional, Tuple
 
 # Os quatro estados, e a cor de cada um. A paleta é a do PrimoCode (ciano de
 # marca, âmbar de aviso) para o modo voz não parecer outro produto.
 CORES = {
-    "esperando": ("#0891b2", "#0e3a4a"),   # ciano recuado: pronto, sem pressa
+    "esperando": ("#22b8d8", "#0e3a4a"),   # ciano calmo: pronto, sem pressa
     "ouvindo":   ("#22d3ee", "#0e7490"),   # ciano vivo: a vez é sua
     "pensando":  ("#fbbf24", "#78350f"),   # âmbar: ele está trabalhando
     "falando":   ("#67e8f9", "#0891b2"),   # ciano claro: a voz é dele
 }
 
-LARGURA = 340          # a janela, deitada: é uma barra flutuante, não um disco
-ALTURA = 170
-RAIO_BASE = 26         # o núcleo
-MARGEM_INFERIOR = 72   # distância do pé da tela
-PARTICULAS = 34
-FUNDO_FALSO = "#05070a"   # só onde o sistema não dá transparência
+LARGURA = 360          # só a área da orb e do brilho — o resto é transparente
+ALTURA = 220
+RAIO_BASE = 34         # o núcleo
+MARGEM_INFERIOR = 24   # acima da área útil (o Dock já fica de fora)
+PARTICULAS = 44
+FUNDO_FALSO = "#05070a"   # só no desenho de reserva, onde não há alfa
+
+
+def _rgb(cor: str) -> Tuple[float, float, float]:
+    return int(cor[1:3], 16) / 255, int(cor[3:5], 16) / 255, int(cor[5:7], 16) / 255
 
 
 def _mistura(a: str, b: str, quanto: float) -> str:
@@ -80,11 +85,111 @@ class Particula:
 
     def __init__(self, rnd: random.Random) -> None:
         self.ang = rnd.uniform(0, math.tau)
-        self.raio = rnd.uniform(1.0, 2.2)          # múltiplo do raio do núcleo
+        self.raio = rnd.uniform(1.25, 2.3)         # múltiplo do raio do núcleo
         self.giro = rnd.uniform(-0.9, 0.9) or 0.4
-        self.tam = rnd.uniform(1.2, 3.0)
+        self.tam = rnd.uniform(1.3, 3.0)
         self.fase = rnd.uniform(0, math.tau)
-        self.brilho = rnd.uniform(0.35, 1.0)
+        self.brilho = rnd.uniform(0.45, 1.0)
+
+
+class Quadro:
+    """Um quadro da animação, sem saber quem vai pintá-lo."""
+
+    def __init__(self, vivo: str, fundo: str, raio: float, pulso: float,
+                 particulas: List[Tuple[float, float, float, float]]):
+        self.vivo, self.fundo = vivo, fundo
+        self.raio, self.pulso = raio, pulso
+        self.particulas = particulas       # (x, y, tamanho, intensidade 0..1)
+
+
+# ── O desenho nativo do macOS ────────────────────────────────────────────
+
+def _criar_nativa(orbe: "Orbe"):
+    """A janela sem borda e sem fundo, desenhada pelo macOS. None se não der."""
+    if sys.platform != "darwin":
+        return None
+    try:
+        import objc
+        from AppKit import (NSBackingStoreBuffered, NSBezierPath, NSColor,
+                            NSCompositingOperationClear, NSGradient, NSMakeRect,
+                            NSRectFillUsingOperation, NSScreen, NSView, NSWindow)
+    except Exception:
+        return None
+
+    def cor(hexa: str, alfa: float):
+        r, g, b = _rgb(hexa)
+        return NSColor.colorWithSRGBRed_green_blue_alpha_(r, g, b, max(0.0, min(1.0, alfa)))
+
+    # A classe Objective-C só pode ser registrada uma vez por processo.
+    try:
+        Vista = objc.lookUpClass("PrimoOrbeVista")
+    except objc.nosuchclass_error:
+        class PrimoOrbeVista(NSView):
+            def isOpaque(self):
+                return False
+
+            def acceptsFirstMouse_(self, evento):
+                return True
+
+            def drawRect_(self, rect):
+                NSColor.clearColor().set()
+                NSRectFillUsingOperation(self.bounds(), NSCompositingOperationClear)
+                q = getattr(self, "quadro", None)
+                if q is None:
+                    return
+                cx, cy = LARGURA / 2, ALTURA / 2
+                centro = (cx, cy)
+
+                # BRILHO: um gradiente radial com alfa, que some no nada. É o
+                # que o Tk não sabia fazer — e o que tira o "disco escuro".
+                alcance = q.raio * (2.6 + q.pulso * 0.9)
+                brilho = NSGradient.alloc().initWithColors_(
+                    [cor(q.vivo, 0.34 + q.pulso * 0.20), cor(q.vivo, 0.10), cor(q.vivo, 0.0)])
+                brilho.drawFromCenter_radius_toCenter_radius_options_(centro, q.raio * 0.6, centro, alcance, 0)
+
+                # PARTÍCULAS
+                for (px, py, t, forca) in q.particulas:
+                    cor(q.vivo, 0.25 + forca * 0.75).set()
+                    NSBezierPath.bezierPathWithOvalInRect_(NSMakeRect(px - t, py - t, 2 * t, 2 * t)).fill()
+
+                # NÚCLEO: gradiente do claro ao vivo, com um anel fino por fora.
+                r = q.raio
+                nucleo = NSGradient.alloc().initWithColors_(
+                    [cor(_mistura(q.vivo, "#ffffff", 0.55), 1.0), cor(q.vivo, 1.0),
+                     cor(_mistura(q.vivo, q.fundo, 0.45), 1.0)])
+                nucleo.drawFromCenter_radius_toCenter_radius_options_(
+                    (cx - r * 0.25, cy + r * 0.25), 0, centro, r, 0)
+                cor(q.vivo, 0.55).set()
+                anel = NSBezierPath.bezierPathWithOvalInRect_(
+                    NSMakeRect(cx - r * 1.18, cy - r * 1.18, r * 2.36, r * 2.36))
+                anel.setLineWidth_(1.5)
+                anel.stroke()
+
+        Vista = PrimoOrbeVista
+
+    try:
+        janela = NSWindow.alloc().initWithContentRect_styleMask_backing_defer_(
+            NSMakeRect(0, 0, LARGURA, ALTURA), 0, NSBackingStoreBuffered, False)   # 0 = sem borda
+        janela.setOpaque_(False)
+        janela.setBackgroundColor_(NSColor.clearColor())
+        janela.setHasShadow_(False)
+        janela.setLevel_(25)                       # NSStatusWindowLevel: por cima de tudo
+        janela.setMovableByWindowBackground_(True)  # arrasta pela orb
+        janela.setCollectionBehavior_(1 | 16)      # todos os espaços; fora do Exposé
+        janela.setReleasedWhenClosed_(False)
+        vista = Vista.alloc().initWithFrame_(NSMakeRect(0, 0, LARGURA, ALTURA))
+        janela.setContentView_(vista)
+
+        # Embaixo, centralizada na área útil (acima do Dock). O Cocoa conta
+        # de baixo para cima, então a margem é somada ao pé da área útil.
+        util = NSScreen.mainScreen().visibleFrame()
+        x = util.origin.x + (util.size.width - LARGURA) / 2
+        y = util.origin.y + MARGEM_INFERIOR
+        janela.setFrameOrigin_((x, y))
+        janela.orderFrontRegardless()
+        return janela, vista
+    except Exception:
+        return None
 
 
 class Orbe:
@@ -103,97 +208,65 @@ class Orbe:
         self._rnd = random.Random(7)   # semente fixa: o enxame é sempre o mesmo
         self._particulas = [Particula(self._rnd) for _ in range(PARTICULAS)]
 
-        self._montar()
+        nativa = _criar_nativa(self)
+        if nativa:
+            # O macOS desenha; a janela do Tk fica escondida e só roda o laço.
+            self.janela, self.vista = nativa
+            self.nativa = True
+            self.raiz.withdraw()
+        else:
+            self.janela = self.vista = None
+            self.nativa = False
+            self._montar_tk()
+
         self.raiz.protocol("WM_DELETE_WINDOW", self.fechar)
         self.raiz.bind("<Escape>", lambda e: self.fechar())
         self._pintar()
 
-    # ── a janela ─────────────────────────────────────────────────────────
-    def _montar(self) -> None:
-        """Sem moldura, embaixo, centralizada — e transparente onde dá.
-
-        A transparência se pede de um jeito em cada sistema, e pedir errado
-        não avisa: devolve TclError, que engolido deixa a janela OPACA. Era
-        exatamente o "quadrado feio". Por isso aqui cada caminho é explícito,
-        e o fundo falso só entra quando nenhum funcionou.
-        """
+    # ── a reserva em Tk (fora do macOS, ou sem PyObjC) ───────────────────
+    def _montar_tk(self) -> None:
         self.raiz.overrideredirect(True)
-        larguraTela = self.raiz.winfo_screenwidth()
-        alturaTela = self.raiz.winfo_screenheight()
-        x = (larguraTela - LARGURA) // 2
-        y = alturaTela - ALTURA - MARGEM_INFERIOR
-        self.raiz.geometry(f"{LARGURA}x{ALTURA}+{x}+{max(0, y)}")
-
         self.fundo = FUNDO_FALSO
-        transparente = False
-
-        if sys.platform == "darwin":
-            # macOS: `-transparent` mais o fundo mágico. Os dois juntos, ou
-            # nenhum dos dois funciona.
-            try:
-                self.raiz.attributes("-transparent", True)
-                self.fundo = "systemTransparent"
-                transparente = True
-            except tk.TclError:
-                pass
-        elif sys.platform == "win32":
+        if sys.platform == "win32":
+            # No Windows o Tk dá transparência por cor-chave, e ela funciona.
             try:
                 self.raiz.attributes("-transparentcolor", FUNDO_FALSO)
-                transparente = True
             except tk.TclError:
                 pass
-
         try:
             self.raiz.attributes("-topmost", True)
         except tk.TclError:
             pass
-
         self.raiz.configure(bg=self.fundo)
         self.tela = tk.Canvas(self.raiz, width=LARGURA, height=ALTURA,
                               bg=self.fundo, highlightthickness=0, bd=0)
         self.tela.pack()
-
-        # Para a MISTURA de cor do halo, o fundo tem de ser um valor de cor —
-        # e "systemTransparent" não é. Contra o preto é a aproximação que
-        # some melhor em qualquer tela.
-        self.fundoDaMistura = FUNDO_FALSO if transparente else self.fundo
-
-        # Sem moldura não há barra de título para arrastar: o arrasto é na
-        # janela toda. Quem quiser a orb noutro canto, leva.
+        self.raiz.update_idletasks()
+        self._posicionar_tk()
+        self.raiz.after(120, self._posicionar_tk)
         self.raiz.bind("<Button-1>", self._pegar)
         self.raiz.bind("<B1-Motion>", self._arrastar)
         self._pego = (0, 0)
 
+    def _posicionar_tk(self) -> None:
+        x = (self.raiz.winfo_screenwidth() - LARGURA) // 2
+        y = self.raiz.winfo_screenheight() - ALTURA - MARGEM_INFERIOR - 48
+        try:
+            self.raiz.geometry(f"{LARGURA}x{ALTURA}+{x}+{max(0, y)}")
+        except tk.TclError:
+            pass
+
     def _pegar(self, e) -> None:
         self._pego = (e.x_root - self.raiz.winfo_x(), e.y_root - self.raiz.winfo_y())
 
     def _arrastar(self, e) -> None:
         self.raiz.geometry(f"+{e.x_root - self._pego[0]}+{e.y_root - self._pego[1]}")
 
-    # ── o desenho ────────────────────────────────────────────────────────
-    def _pintar(self) -> None:
-        if not self._vivo:
-            return
-        while True:
-            try:
-                estado, nivel = self._fila.get_nowait()
-                if estado == "__esconder__":
-                    self._aplicarVisibilidade(False)
-                    continue
-                if estado == "__mostrar__":
-                    self._aplicarVisibilidade(True)
-                    continue
-                if estado:
-                    self.estado = estado
-                if nivel is not None:
-                    self.nivel = max(0.0, min(1.0, nivel))
-            except queue.Empty:
-                break
-
+    # ── a animação ───────────────────────────────────────────────────────
+    def _quadro(self) -> Quadro:
         self._fase += 0.045
         vivo, fundo = CORES.get(self.estado, CORES["esperando"])
         cx, cy = LARGURA / 2, ALTURA / 2
-        self.tela.delete("all")
 
         # A respiração de cada estado. Quem espera respira devagar; quem
         # pensa, num ritmo próprio; quem ouve pulsa com a VOZ, não com o
@@ -206,49 +279,77 @@ class Orbe:
             pulso = 0.55 + 0.38 * math.sin(self._fase * 3.4)
         else:
             pulso = 0.16 + 0.10 * math.sin(self._fase * 0.9)
+        raio = RAIO_BASE * (1 + pulso * 0.30)
 
-        raio = RAIO_BASE * (1 + pulso * 0.42)
-
-        # HALO: círculos concêntricos, do mais largo e apagado ao núcleo. É o
-        # desfoque que o Canvas não tem — e por isso a cor de cada anel é
-        # interpolada contra o fundo, em vez de ter opacidade.
-        for i in range(11, 0, -1):
-            f = i / 11
-            r = raio * (1 + f * 2.6)
-            cor = _mistura(self.fundoDaMistura, fundo, (1 - f) ** 2 * 0.85)
-            self.tela.create_oval(cx - r, cy - r, cx + r, cy + r, fill=cor, outline="")
-
-        # PARTÍCULAS: entre o halo e o núcleo, para o núcleo ficar por cima.
+        pontos = []
         for p in self._particulas:
             p.ang += p.giro * 0.012 * (0.6 + pulso)
             # O raio respira junto com a voz: quanto mais alto se fala, mais
             # longe o enxame se abre.
             osc = math.sin(self._fase * 1.7 + p.fase)
-            r = raio * (p.raio + 0.30 * osc + pulso * 0.55)
-            px = cx + math.cos(p.ang) * r * 1.55      # elipse: a janela é deitada
-            py = cy + math.sin(p.ang) * r * 0.80
-            t = p.tam * (0.7 + pulso * 0.8)
-            cor = _mistura(self.fundoDaMistura, vivo, p.brilho * (0.35 + pulso * 0.65))
-            self.tela.create_oval(px - t, py - t, px + t, py + t, fill=cor, outline="")
-
-        # NÚCLEO: dois discos, o de dentro mais claro. Dá volume sem gradiente.
-        self.tela.create_oval(cx - raio, cy - raio, cx + raio, cy + raio,
-                              fill=_mistura(fundo, vivo, 0.72), outline="")
-        rn = raio * 0.55
-        self.tela.create_oval(cx - rn, cy - rn, cx + rn, cy + rn,
-                              fill=_mistura(vivo, "#ffffff", 0.35), outline="")
+            r = raio * (p.raio + 0.25 * osc + pulso * 0.40)
+            # Elipse leve, mais larga que alta — e dentro da janela: o que
+            # passa da borda é cortado seco, e partícula cortada é defeito.
+            px = cx + math.cos(p.ang) * r * 1.2
+            py = cy + math.sin(p.ang) * r * 0.74
+            t = p.tam * (0.75 + pulso * 0.6)
+            pontos.append((px, py, t, p.brilho * (0.5 + pulso * 0.5)))
+        return Quadro(vivo, fundo, raio, pulso, pontos)
 
+    def _pintar(self) -> None:
+        if not self._vivo:
+            return
+        while True:
+            try:
+                estado, nivel = self._fila.get_nowait()
+                if estado == "__esconder__":
+                    self._aplicarVisibilidade(False)
+                    continue
+                if estado == "__mostrar__":
+                    self._aplicarVisibilidade(True)
+                    continue
+                if estado:
+                    self.estado = estado
+                if nivel is not None:
+                    self.nivel = max(0.0, min(1.0, nivel))
+            except queue.Empty:
+                break
+
+        q = self._quadro()
+        if self.nativa:
+            self.vista.quadro = q
+            self.vista.setNeedsDisplay_(True)
+        else:
+            self._pintar_tk(q)
         self.raiz.after(33, self._pintar)
 
+    def _pintar_tk(self, q: Quadro) -> None:
+        """A reserva: forma chapada, sem alfa. Misturas contra o fundo."""
+        cx, cy = LARGURA / 2, ALTURA / 2
+        self.tela.delete("all")
+        for i in range(6, 0, -1):
+            f = i / 6
+            r = q.raio * (1 + f * 1.3)
+            self.tela.create_oval(cx - r, cy - r, cx + r, cy + r,
+                                  outline=_mistura(self.fundo, q.vivo, (1 - f) ** 1.6 * 0.7), width=2)
+        for (px, py, t, forca) in q.particulas:
+            self.tela.create_oval(px - t, py - t, px + t, py + t,
+                                  fill=_mistura(self.fundo, q.vivo, 0.3 + forca * 0.7), outline="")
+        r = q.raio
+        self.tela.create_oval(cx - r, cy - r, cx + r, cy + r,
+                              fill=_mistura(q.fundo, q.vivo, 0.8), outline="")
+        rn = r * 0.55
+        self.tela.create_oval(cx - rn, cy - rn, cx + rn, cy + rn,
+                              fill=_mistura(q.vivo, "#ffffff", 0.4), outline="")
+
     # ── visibilidade ─────────────────────────────────────────────────────
     def esconder(self) -> None:
         """Some da tela sem morrer.
 
         No modo de espera ele fica horas sem nada acontecer, e uma orb parada
         na tela todo esse tempo é estorvo. Destruir e recriar a janela a cada
-        despertar seria o caminho óbvio, e é o errado: recriar uma Tk leva
-        centenas de milissegundos, pisca, e em alguns sistemas rouba o foco da
-        janela onde a pessoa estava digitando. `withdraw` guarda tudo de pé.
+        despertar pisca e, em alguns sistemas, rouba o foco de onde a pessoa
+        estava digitando. Esconder guarda tudo de pé.
         """
         self._fila.put(("__esconder__", None))
 
@@ -256,9 +357,14 @@ class Orbe:
         self._fila.put(("__mostrar__", None))
 
     def _aplicarVisibilidade(self, visivel: bool) -> None:
-        # Só na thread da interface: tkinter não perdoa chamada de fora.
+        # Só na thread da interface: nem o Tk nem o AppKit perdoam chamada de fora.
         try:
-            if visivel:
+            if self.nativa:
+                if visivel:
+                    self.janela.orderFrontRegardless()
+                else:
+                    self.janela.orderOut_(None)
+            elif visivel:
                 self.raiz.deiconify()
                 self.raiz.lift()
                 if sys.platform != "linux":
@@ -282,6 +388,12 @@ class Orbe:
                 self._ao_fechar()
         except Exception:
             pass
+        try:
+            if self.janela is not None:
+                self.janela.orderOut_(None)
+                self.janela.close()
+        except Exception:
+            pass
         try:
             self.raiz.destroy()
         except Exception:

package/voz/primo_voz/transcrever.py

@@ -0,0 +1,106 @@
+"""transcrever.py — a fala vira texto AQUI, na máquina.
+
+    "Pode ser local, daí pra transcrever ele instala Whisper." (23/09/2026)
+
+── POR QUE LOCAL ───────────────────────────────────────────────────────────
+A transcrição ia para o servidor do PrimoCode (`/api/transcrever`). Com o
+servidor fora do ar, o modo voz ouvia, pensava — e não entendia nada. Local,
+ela não depende de rede, não custa chave e o áudio não sai do computador.
+
+── POR QUE faster-whisper, E POR QUE O `small` ─────────────────────────────
+É o Whisper da OpenAI reimplementado em CTranslate2: roda no processador de
+qualquer máquina (Mac Intel ou Apple Silicon, Linux, Windows), instala por pip
+sem compilar nada e lê o wav direto, sem ffmpeg. O modelo `small` (~480 MB,
+uma vez) é o menor que entende português falado sem tropeçar em nome próprio;
+o `base` erra demais, o `medium` dobra o tempo de resposta. Quem quiser outro
+troca por PRIMOCODE_WHISPER_MODELO.
+
+O modelo carrega UMA vez por sessão, em segundo plano, logo que o modo voz
+abre — senão a primeira frase esperaria o carregamento inteiro.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+from pathlib import Path
+from typing import Optional
+
+MODELO = os.environ.get("PRIMOCODE_WHISPER_MODELO", "small").strip() or "small"
+PASTA = Path.home() / ".primocode" / "modelos" / "whisper"
+
+_modelo = None
+_trava = threading.Lock()
+_erro: Optional[str] = None
+
+
+def disponivel() -> bool:
+    try:
+        import faster_whisper  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def carregar():
+    """O modelo, carregado uma vez (e baixado, se for a primeira)."""
+    global _modelo, _erro
+    with _trava:
+        if _modelo is not None:
+            return _modelo
+        from faster_whisper import WhisperModel
+        PASTA.mkdir(parents=True, exist_ok=True)
+        try:
+            # int8 no processador: é o que cabe em qualquer máquina e ainda
+            # responde uma frase de dez segundos em um ou dois.
+            _modelo = WhisperModel(MODELO, device="cpu", compute_type="int8",
+                                   download_root=str(PASTA))
+            _erro = None
+        except Exception as e:
+            _erro = str(e)
+            raise
+        return _modelo
+
+
+def aquecer() -> None:
+    """Carrega em segundo plano. Erro aqui não derruba nada: a transcrição
+    tenta de novo na hora, e cai para o servidor se não der."""
+    def _ir():
+        try:
+            carregar()
+        except Exception:
+            pass
+    threading.Thread(target=_ir, daemon=True).start()
+
+
+def transcrever(wav: Path, idioma: str = "pt") -> str:
+    modelo = carregar()
+    # vad_filter corta o silêncio das pontas: sem ele, o Whisper às vezes
+    # "ouve" uma frase inteira inventada no silêncio ("Obrigado por assistir").
+    segmentos, _ = modelo.transcribe(str(wav), language=idioma, beam_size=5,
+                                     vad_filter=True, condition_on_previous_text=False)
+    return " ".join(s.text.strip() for s in segmentos).strip()
+
+
+def main() -> int:
+    """`python -m primo_voz.transcrever baixar` — usado pelo /voice para deixar
+    o modelo pronto antes da primeira frase. Responde uma linha de JSON."""
+    acao = sys.argv[1] if len(sys.argv) > 1 else "baixar"
+    if acao != "baixar":
+        print(json.dumps({"ok": False, "error": f"ação desconhecida: {acao}"}))
+        return 2
+    if not disponivel():
+        print(json.dumps({"ok": False, "error": "o faster-whisper não está instalado"}))
+        return 1
+    try:
+        carregar()
+    except Exception as e:
+        print(json.dumps({"ok": False, "error": f"não consegui baixar o modelo {MODELO}: {e}"}))
+        return 1
+    print(json.dumps({"ok": True, "modelo": MODELO, "pasta": str(PASTA)}))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())