primocode 8.19.0 → 8.20.0

package/lib/act.js

@@ -529,6 +529,26 @@ async function runAct(userPrompt, opts) {
 
         let finished = null;
         let algoRodou = false;
+
+        // ORQUESTRAÇÃO: subagentes da MESMA rodada rodam juntos. O modelo que
+        // pede "3 agentes, um por arquivo" esperava paralelismo e recebia uma
+        // fila — cada subagente só começava quando o anterior terminava, e a
+        // rodada custava a soma dos três. Agora as chamadas spawn_agent da
+        // rodada disparam de uma vez (Promise.all) e cada resultado volta na
+        // posição certa da conversa. Limite de 4 por rodada: acima disso é
+        // sinal de decomposição ruim, e o excedente roda em série mesmo.
+        const spawns = toolCalls.filter((tc) => tc.name === 'spawn_agent');
+        const resultadosSpawn = new Map();
+        if (spawns.length > 1 && !PARAR) {
+            const juntos = spawns.slice(0, 4);
+            console.log(ident(profundidade) + `  ${c.magenta('◆')} ${c.bold(c.magenta('Agentes'))} ${c.muted(`${juntos.length} em paralelo`)}`);
+            const rs = await Promise.all(juntos.map((tc) =>
+                runSubagent(tc.arguments || {}, {
+                    server, model, token, projectDir: pastaAtual, projectName, profundidade, motor,
+                }).catch((e) => `Subagente falhou: ${e && e.message}`)));
+            juntos.forEach((tc, i) => resultadosSpawn.set(tc.id, rs[i]));
+        }
+
         for (const tc of toolCalls) {
             if (PARAR) break;
             if (tc.name === 'finish') {
@@ -552,9 +572,11 @@ async function runAct(userPrompt, opts) {
 
             if (tc.name === 'spawn_agent') {
                 algoRodou = true;
-                const r = await runSubagent(tc.arguments || {}, {
-                    server, model, token, projectDir: pastaAtual, projectName, profundidade, motor,
-                });
+                const r = resultadosSpawn.has(tc.id)
+                    ? resultadosSpawn.get(tc.id)
+                    : await runSubagent(tc.arguments || {}, {
+                        server, model, token, projectDir: pastaAtual, projectName, profundidade, motor,
+                    });
                 messages.push({ role: 'tool', tool_call_id: tc.id, content: r });
                 continue;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primocode",
-  "version": "8.19.0",
+  "version": "8.20.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": {

package/studio/ferramentas/corte.md

@@ -174,6 +174,33 @@ Regras que fazem diferença:
 O usuário também pode gravar a própria voz pelo editor; aí a cena ganha
 `narracaoAudio` com o arquivo, e ela tem prioridade sobre a voz sintetizada.
 
+**Sincronia é automática.** Quando o estúdio gera a narração em arquivo, ele
+mede o áudio e grava `narracaoDur` na cena; a cena então dura o que for maior —
+a `duracao` pedida ou a fala inteira mais um respiro. Não calcule isso à mão,
+e não apague `narracaoDur` ao ajustar um documento.
+
+**Mixagem é automática.** A música abaixa sozinha enquanto a voz fala (ducking)
+e volta no intervalo entre as falas. Não compense baixando o `volume` da trilha:
+deixe em 0.6–0.8 e o duck cuida do resto.
+
+---
+
+## Efeitos sonoros
+
+Cada troca de cena ganha um efeito sintetizado na hora, sem arquivo e sem
+licença: transição `flash` e `zoom` soam um **impacto** grave; as demais, um
+**whoosh** (variado, para não repetir); `corte` fica em silêncio.
+
+Para controlar:
+
+```json
+"sfx": false                  // no documento: desliga todos os efeitos
+{ "transicao": "deslizar", "sfx": "impacto" }   // na cena: força um efeito
+```
+
+Valores por cena: `"whoosh"` · `"impacto"` · `"click"` · `"nenhum"`.
+O padrão (sem declarar nada) já é o certo para a maioria dos vídeos.
+
 ---
 
 ## Transições

package/studio/server.py

@@ -20,6 +20,7 @@ import threading
 import time
 import unicodedata
 import uuid
+import wave
 from datetime import datetime, timezone
 from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
 from urllib.parse import urlparse, unquote, urlencode
@@ -184,11 +185,30 @@ def ler(arq_id):
 
 def gravar(arq):
     arq["atualizado"] = datetime.now(timezone.utc).isoformat(timespec="seconds")
-    with open(caminho(arq["id"]), "w", encoding="utf-8") as fh:
+    destino = caminho(arq["id"])
+    # Escrita atômica: o servidor é multi-thread (autosave do editor a cada
+    # 600 ms + a thread de narração gravando o mesmo doc). Escrever direto
+    # podia deixar um JSON pela metade se duas gravações se cruzassem ou o
+    # processo caísse no meio. Com tmp + replace, ou o arquivo antigo está
+    # inteiro, ou o novo está inteiro — nunca metade.
+    tmp = destino + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as fh:
         json.dump(arq, fh, ensure_ascii=False, indent=2)
+    os.replace(tmp, destino)
     return arq
 
 
+def _duracao_wav(dados):
+    """Segundos de um WAV em bytes; None se não der para medir."""
+    try:
+        import io
+        with wave.open(io.BytesIO(dados), "rb") as w:
+            fr = w.getframerate()
+            return (w.getnframes() / fr) if fr else None
+    except Exception:
+        return None
+
+
 # ------------------------------------------------------------------ versões --
 #
 # Um pedido de ajuste apagou o trabalho de um usuário: ele tinha um vídeo de
@@ -335,6 +355,11 @@ def _gravar_narracao(arq_id):
         for _ in range(120):
             if voz_lib.pronta():
                 break
+            # Máquina onde o Piper nunca vai rodar (binário de outra
+            # arquitetura): esperar 10 minutos aqui era esperar por nada.
+            if voz_lib.bloqueado():
+                sys.stderr.write("[voz] motor neural bloqueado: %s\n" % voz_lib.bloqueado())
+                return
             voz_lib.instalar()
             time.sleep(5)
         if not voz_lib.pronta():
@@ -376,6 +401,14 @@ def _gravar_narracao(arq_id):
                 fh.write(audio)
             c["narracaoAudio"] = "/midia/" + nome
             c["narracaoVoz"] = assinatura
+            # A duração medida do WAV vai junto: com ela o player sabe quanto
+            # a cena REALMENTE dura (a fala inteira + respiro) e a linha do
+            # tempo vira determinística — sem ela, o relógio congela na
+            # beirada da cena esperando a voz, e a duração do vídeo muda a
+            # cada reprodução.
+            dur = _duracao_wav(audio)
+            if dur:
+                c["narracaoDur"] = round(dur, 2)
             mudou = True
 
         if mudou:
@@ -389,6 +422,8 @@ def _gravar_narracao(arq_id):
                             and cenas[i].get("narracao") == c.get("narracao"):
                         cenas[i]["narracaoAudio"] = c["narracaoAudio"]
                         cenas[i]["narracaoVoz"] = c["narracaoVoz"]
+                        if c.get("narracaoDur"):
+                            cenas[i]["narracaoDur"] = c["narracaoDur"]
                 gravar(atual)
     except Exception as e:
         sys.stderr.write("[voz] narração em arquivo falhou: %s\n" % e)
@@ -1577,7 +1612,7 @@ def html_autonomo(a):
             return fh.read()
 
     js = "\n".join(leia("js", n) for n in
-                   ("icones.js", "audio.js", "render.js", "render-prosa.js", "render-grade.js"))
+                   ("icones.js", "audio.js", "sfx.js", "render.js", "render-prosa.js", "render-grade.js"))
 
     dados = json.dumps(a, ensure_ascii=False).replace("</script", "<\\/script")
 
@@ -1603,7 +1638,50 @@ def html_autonomo(a):
 
 # -------------------------------------------------------------------- main --
 
+def _abrir_log():
+    """Diagnóstico que sobrevive ao `stdio: 'ignore'` do CLI.
+
+    O CLI sobe este servidor descartando stdout/stderr — e era exatamente
+    para lá que iam os erros de voz e o traceback de porta ocupada. Ninguém
+    via nada: o Studio "não subia" em silêncio. Espelhar stdout/stderr num
+    arquivo ao lado do código dá onde olhar. Rotação simples: passou de
+    2 MB, o log atual vira `.old` e começa outro.
+    """
+    try:
+        destino = os.path.join(RAIZ, "studio.log")
+        if os.path.exists(destino) and os.path.getsize(destino) > 2 * 1024 * 1024:
+            os.replace(destino, destino + ".old")
+        fh = open(destino, "a", encoding="utf-8", buffering=1)
+
+        class _Tee:
+            def __init__(self, original):
+                self.original = original
+            def write(self, s):
+                try:
+                    self.original.write(s)
+                except Exception:
+                    pass
+                try:
+                    fh.write(s)
+                except Exception:
+                    pass
+            def flush(self):
+                for alvo in (self.original, fh):
+                    try:
+                        alvo.flush()
+                    except Exception:
+                        pass
+
+        sys.stdout = _Tee(sys.stdout)
+        sys.stderr = _Tee(sys.stderr)
+        print("[studio] %s — iniciando na porta %d" %
+              (datetime.now(timezone.utc).isoformat(timespec="seconds"), PORTA))
+    except Exception:
+        pass          # sem log ainda é melhor que sem servidor
+
+
 if __name__ == "__main__":
+    _abrir_log()
     url = "http://localhost:%d" % PORTA
     print("""
   ██  PrimoCode Studio
@@ -1619,3 +1697,12 @@ if __name__ == "__main__":
         ThreadingHTTPServer(("127.0.0.1", PORTA), Handler).serve_forever()
     except KeyboardInterrupt:
         print("\n  Encerrado.\n")
+    except OSError as e:
+        # Porta ocupada saía como traceback — e com stdio descartado pelo
+        # CLI, saía para lugar nenhum. Mensagem clara + código de saída
+        # próprio: quem supervisiona sabe o que houve sem ler stack.
+        if getattr(e, "errno", None) in (48, 98, 10048):   # mac, linux, windows
+            print("\n  A porta %d já está em uso — outro Studio no ar?\n"
+                  "  Feche-o (POST /api/sair) ou use PRIMOCODE_STUDIO_PORT.\n" % PORTA)
+            sys.exit(2)
+        raise

package/studio/voz.py

@@ -117,8 +117,66 @@ def instaladas():
     return [v["id"] for v in CATALOGO if modelo(v["id"])]
 
 
+# O binário EXISTIR não prova que ele RODA. O pacote macos_aarch64 do Piper
+# 2023.11.14-2 veio com executável x86_64 dentro — num Mac Apple Silicon sem
+# Rosetta, spawná-lo morre com "Bad CPU type" (errno 86). Sem esta checagem,
+# `pronta()` dizia sim, o servidor esperava a voz que nunca viria, e cada
+# pedido de narração travava a corrente inteira de motores por minutos.
+# A prova roda UMA vez e o veredito fica em arquivo: reiniciar não re-testa,
+# e reinstalar (apagar()) limpa o veredito junto.
+_MARCA_INCOMPATIVEL = os.path.join(CASA, "binario-incompativel")
+_roda_cache = None
+
+
+def marcar_incompativel(motivo):
+    global _roda_cache
+    _roda_cache = False
+    try:
+        os.makedirs(CASA, exist_ok=True)
+        with open(_MARCA_INCOMPATIVEL, "w") as fh:
+            fh.write(str(motivo))
+    except Exception:
+        pass
+
+
+def bloqueado():
+    """Por que o Piper nunca vai funcionar nesta máquina — ou None."""
+    try:
+        if os.path.exists(_MARCA_INCOMPATIVEL):
+            with open(_MARCA_INCOMPATIVEL) as fh:
+                return fh.read().strip() or "binário incompatível com esta máquina"
+    except Exception:
+        pass
+    return None
+
+
+def _binario_roda():
+    global _roda_cache
+    if _roda_cache is not None:
+        return _roda_cache
+    if bloqueado():
+        _roda_cache = False
+        return False
+    exe = binario()
+    if not exe:
+        return None                     # ainda não baixou: sem veredito
+    try:
+        subprocess.run([exe, "--version"], stdout=subprocess.DEVNULL,
+                       stderr=subprocess.DEVNULL, timeout=10)
+        _roda_cache = True
+    except OSError as e:
+        if getattr(e, "errno", None) == 86:      # Bad CPU type (macOS)
+            marcar_incompativel("o pacote do Piper veio com binário de outra "
+                                "arquitetura (x86_64 num Mac ARM sem Rosetta)")
+        else:
+            marcar_incompativel("o binário do Piper não executa: %s" % e)
+    except Exception:
+        _roda_cache = True              # demorou mas executa: não é errno 86
+    return _roda_cache
+
+
 def pronta(voz_id=None):
-    return bool(binario() and modelo(voz_id or PADRAO))
+    return bool(binario() and modelo(voz_id or PADRAO) and _binario_roda())
 
 
 # ------------------------------------------------------------------ baixar --
@@ -209,6 +267,11 @@ def instalar(voz_id=None, esperar=0):
     que faz ela estar pronta na hora de tocar."""
     global _thread
     voz_id = voz_id if voz_id in POR_ID else PADRAO
+    # Baixar de novo não conserta binário de arquitetura errada: viria o
+    # mesmo pacote. Sem esta guarda, cada pedido de narração re-disparava
+    # os ~90 MB de download para nada.
+    if bloqueado():
+        return estado()
     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)
@@ -227,7 +290,11 @@ def estado():
         "motor": "piper",
         "pronta": pronta(),
         "instaladas": instaladas(),
-        "suportado": bool(_versao_pacote()),
+        # "suportado" responde à pergunta de verdade: o Piper VAI funcionar
+        # aqui? Pacote inexistente para a plataforma e binário que não roda
+        # são o mesmo "não" — e `bloqueado` explica o porquê.
+        "suportado": bool(_versao_pacote()) and not bloqueado(),
+        "bloqueado": bloqueado(),
         "baixando": b,
         "vozes": [{
             "id": v["id"], "nome": v["nome"], "tom": v["tom"], "hz": v["hz"], "mb": v["mb"],
@@ -265,7 +332,7 @@ def sintetizar(texto, voz_id=None, grave=False, velocidade=1.0, timeout=120):
     exe = binario()
     voz_id = voz_id if voz_id in POR_ID else PADRAO
     mod = modelo(voz_id)
-    if not exe or not mod:
+    if not exe or not mod or not _binario_roda():
         return None
 
     # Sem isto, um texto com quebra de linha vira várias falas e o Piper
@@ -282,13 +349,22 @@ def sintetizar(texto, voz_id=None, grave=False, velocidade=1.0, timeout=120):
     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,
-        )
+        try:
+            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,
+            )
+        except OSError as e:
+            # errno 86 = binário de outra arquitetura (macOS). Marca de vez:
+            # a corrente cai para o próximo motor e ninguém trava de novo.
+            if getattr(e, "errno", None) == 86:
+                marcar_incompativel("o pacote do Piper veio com binário de "
+                                    "outra arquitetura (x86_64 num Mac ARM sem Rosetta)")
+                return None
+            raise
         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:
@@ -301,7 +377,12 @@ def sintetizar(texto, voz_id=None, grave=False, velocidade=1.0, timeout=120):
 
 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."""
+    são 90 MB na máquina dele, e ele tem direito de recuperá-los.
+    O veredito de incompatibilidade vai junto (mora dentro de CASA): quem
+    instalar de novo — num Mac com Rosetta, num pacote corrigido — merece
+    uma prova nova, não a sentença antiga."""
+    global _roda_cache
+    _roda_cache = None
     if os.path.isdir(CASA):
         shutil.rmtree(CASA, ignore_errors=True)
     return {"ok": True}

package/studio/web/js/audio.js

@@ -65,7 +65,8 @@ function criarTrilha(cfg, aoErro) {
 
   var ctx = new Ctx();
   var mestre = ctx.createGain();
-  mestre.gain.value = cfg.volume != null ? cfg.volume : 0.7;
+  var volumeBase = cfg.volume != null ? cfg.volume : 0.7;
+  mestre.gain.value = volumeBase;
 
   var compressor = ctx.createDynamicsCompressor();
   compressor.threshold.value = -14;
@@ -77,17 +78,49 @@ function criarTrilha(cfg, aoErro) {
   var paraGravar = ctx.createMediaStreamDestination();
   compressor.connect(paraGravar);
 
+  /* Entrada da NARRAÇÃO: depois do `mestre`, antes do compressor. A voz não
+     passa pelo volume da trilha nem pelo duck — quem abaixa é a música, nunca
+     a fala. E como desemboca no mesmo compressor, a voz entra na gravação
+     MP4 pelo grafo, sem depender de "compartilhar áudio da aba". */
+  var entradaVoz = ctx.createGain();
+  entradaVoz.gain.value = 1;
+  entradaVoz.connect(compressor);
+
   var api = {
     ctx: ctx,
+    no: compressor,                 // onde SFX e outras fontes se conectam
+    entradaVoz: entradaVoz,
     fluxo: paraGravar.stream,
     tocando: false,
     tocar: function () {},
     parar: function () {},
-    volume: function (v) { mestre.gain.value = v; },
+    volume: function (v) { volumeBase = v; mestre.gain.value = v; },
     esmaecer: function () {},
     duracao: function () { return null; },
+    /* Ducking: a trilha cede espaço enquanto a narração fala.
+       Rampa curta para descer (a voz não espera) e longa para voltar. */
+    duck: function (ligado) {
+      var agora = ctx.currentTime;
+      mestre.gain.cancelScheduledValues(agora);
+      mestre.gain.setValueAtTime(mestre.gain.value, agora);
+      mestre.gain.linearRampToValueAtTime(
+        ligado ? volumeBase * 0.35 : volumeBase,
+        agora + (ligado ? 0.15 : 0.5));
+    },
   };
 
+  /* -------------------------------------------------------- sem trilha ---- */
+  /* tipo "nenhuma": o documento não tem música, mas o grafo ainda serve —
+     é por ele que narração e SFX entram na gravação. */
+  if (cfg.tipo === "nenhuma") {
+    api.tocar = function () {
+      if (ctx.state === "suspended") ctx.resume();
+      api.tocando = true;
+    };
+    api.parar = function () { api.tocando = false; };
+    return api;
+  }
+
   /* --------------------------------------------------------- arquivo ---- */
 
   if (cfg.tipo !== "gerada" && cfg.src) {

package/studio/web/js/player.js

@@ -33,8 +33,17 @@
   function duracaoDe(i) {
     /* "duracao": "3s" (texto) fazia acc virar concatenação e o relógio dava
        vídeo de 00:00. Número são ou o padrão — nunca corrente de texto. */
-    var d = Number(cenas[i] && cenas[i].duracao);
-    return (isFinite(d) && d > 0) ? Math.min(60, d) : 4;
+    var c = cenas[i] || {};
+    var d = Number(c.duracao);
+    d = (isFinite(d) && d > 0) ? Math.min(60, d) : 4;
+    /* A narração pré-renderizada tem duração conhecida (o servidor mediu o
+       WAV e gravou `narracaoDur` na cena). A cena dura o que for MAIOR:
+       o que o autor pediu ou a fala inteira + um respiro. É isto que torna
+       a linha do tempo determinística — o "cena espera a voz" do laço vira
+       só a rede de segurança para narração sintetizada na hora. */
+    var n = Number(c.narracaoDur);
+    if (isFinite(n) && n > 0 && c.narracaoAudio) d = Math.max(d, Math.min(90, n + 0.4));
+    return d;
   }
   function total() { return cenas.reduce(function (s, _, i) { return s + duracaoDe(i); }, 0); }
   function inicioDe(i) { var s = 0; for (var k = 0; k < i; k++) s += duracaoDe(k); return s; }
@@ -129,6 +138,7 @@
 
   function ir(n, semRelogio) {
     if (!cenas.length) return;
+    var anterior = atual;
     atual = Math.max(0, Math.min(cenas.length - 1, n));
     Array.prototype.forEach.call(palco.children, function (no, i) {
       no.style.display = i === atual ? "block" : "none";
@@ -139,6 +149,17 @@
         contar(no);
       }
     });
+    /* SFX na entrada da cena — só durante a reprodução (navegar com as setas
+       não faz barulho) e nunca na primeira montagem. `doc.sfx === false`
+       desliga tudo; `cena.sfx` escolhe o efeito ("whoosh" | "impacto" |
+       "click" | "nenhum") e ganha do automático por transição. */
+    if (sfx && tocando && ehVideo && atual !== anterior && doc.sfx !== false) {
+      var cenaNova = cenas[atual] || {};
+      if (cenaNova.sfx !== "nenhum") {
+        if (cenaNova.sfx && sfx[cenaNova.sfx]) sfx[cenaNova.sfx]();
+        else sfx.transicao(cenaNova.transicao, atual);
+      }
+    }
     narrar();
     pintarApresentador();
     if (!semRelogio) decorrido = inicioDe(atual);
@@ -255,6 +276,7 @@
   function narrar() {
     if (typeof Narracao !== "undefined") Narracao.parar();
     if (vozGravada) { vozGravada.pause(); vozGravada = null; }
+    if (trilha && trilha.duck) trilha.duck(false);
     if (mudo || doc.narracao === false) return;
 
     var cena = cenas[atual] || {};
@@ -263,13 +285,35 @@
     if (cena.narracaoAudio) {
       vozGravada = new Audio(cena.narracaoAudio);
       vozGravada.volume = (doc.voz && doc.voz.volume != null) ? doc.voz.volume : 1;
+      /* Pelo grafo da trilha, quando ele existe: a voz entra na gravação MP4
+         sem "compartilhar áudio da aba", e a música cede espaço (duck)
+         enquanto a fala dura. Sem grafo, toca direto como antes. */
+      if (trilha && trilha.ctx && trilha.entradaVoz) {
+        try {
+          var fonteVoz = trilha.ctx.createMediaElementSource(vozGravada);
+          fonteVoz.connect(trilha.entradaVoz);
+        } catch (_) { /* elemento já conectado ou grafo indisponível */ }
+        if (trilha.duck) {
+          trilha.duck(true);
+          vozGravada.onended = function () { if (trilha && trilha.duck) trilha.duck(false); };
+        }
+      }
       var p = vozGravada.play();
       if (p && p.catch) p.catch(function () {});
       return;
     }
 
     if (typeof Narracao === "undefined" || !Narracao.disponivel()) return;
-    if (cena.narracao) Narracao.falar(cena.narracao, doc.voz || {});
+    if (cena.narracao) {
+      if (trilha && trilha.duck) {
+        trilha.duck(true);
+        Narracao.falar(cena.narracao, doc.voz || {}).then(function () {
+          if (trilha && trilha.duck) trilha.duck(false);
+        });
+      } else {
+        Narracao.falar(cena.narracao, doc.voz || {});
+      }
+    }
   }
 
   /* ----------------------------------------------------- apresentador --- */
@@ -317,11 +361,18 @@
 
   /* ------------------------------------------------------------ trilha -- */
 
+  var sfx = null;
+
   function prepararTrilha() {
-    var cfg = doc.trilha;
-    if (!cfg || (!cfg.src && cfg.tipo !== "gerada")) return;
     if (typeof criarTrilha !== "function") return;
+    var cfg = doc.trilha;
+    /* Sem trilha o grafo ainda nasce (tipo "nenhuma"): é por ele que a
+       narração e os SFX entram na gravação MP4. */
+    if (!cfg || (!cfg.src && cfg.tipo !== "gerada")) cfg = { tipo: "nenhuma" };
     trilha = criarTrilha(cfg, function (msg) { aviso(msg, 3000); });
+    if (trilha && trilha.ctx && trilha.no && typeof criarSfx === "function" && doc.sfx !== false) {
+      sfx = criarSfx(trilha.ctx, trilha.no);
+    }
   }
 
   /* --------------------------------------------------------- transporte -- */

package/studio/web/js/sfx.js

@@ -0,0 +1,107 @@
+/* ==========================================================================
+   sfx.js — efeitos sonoros do Corte, sintetizados na hora.
+
+   Nenhum arquivo, nenhuma licença: whoosh é ruído filtrado com varredura,
+   impacto é um seno grave despencando, click é um blip curto. Tudo entra no
+   mesmo grafo da trilha (via `destino`), então a gravação MP4 captura os
+   efeitos junto — sem depender de "compartilhar áudio da aba".
+
+   Uso:
+     var sfx = criarSfx(ctx, destino);   // destino: nó do grafo (compressor)
+     sfx.whoosh();      // transição de cena
+     sfx.impacto();     // ênfase (flash, número grande)
+     sfx.click();       // entrada de elemento, feedback discreto
+
+   O volume de cada efeito já vem calibrado para sentar SOB a narração.
+   ========================================================================== */
+
+function criarSfx(ctx, destino) {
+  "use strict";
+  if (!ctx || !destino) return null;
+
+  var saida = ctx.createGain();
+  saida.gain.value = 1;
+  saida.connect(destino);
+
+  var ruido = null;
+  function bufferRuido() {
+    if (ruido) return ruido;
+    ruido = ctx.createBuffer(1, ctx.sampleRate * 1.2, ctx.sampleRate);
+    var d = ruido.getChannelData(0);
+    for (var i = 0; i < d.length; i++) d[i] = Math.random() * 2 - 1;
+    return ruido;
+  }
+
+  /* Varredura de ruído — o "passar de página" do vídeo. `variacao` muda o
+     miolo da varredura para os whooshes não saírem todos idênticos. */
+  function whoosh(variacao) {
+    var agora = ctx.currentTime;
+    var v = (variacao == null ? Math.random() : variacao) % 1;
+    var s = ctx.createBufferSource(), g = ctx.createGain(), f = ctx.createBiquadFilter();
+    s.buffer = bufferRuido();
+    f.type = "bandpass";
+    f.Q.value = 1.1;
+    f.frequency.setValueAtTime(300 + v * 300, agora);
+    f.frequency.exponentialRampToValueAtTime(2200 + v * 1400, agora + 0.16);
+    f.frequency.exponentialRampToValueAtTime(500, agora + 0.42);
+    g.gain.setValueAtTime(0.0001, agora);
+    g.gain.exponentialRampToValueAtTime(0.11, agora + 0.10);
+    g.gain.exponentialRampToValueAtTime(0.0001, agora + 0.45);
+    s.connect(f); f.connect(g); g.connect(saida);
+    s.start(agora); s.stop(agora + 0.5);
+  }
+
+  /* Seno grave despencando + um sopro de ruído no ataque. */
+  function impacto() {
+    var agora = ctx.currentTime;
+    var o = ctx.createOscillator(), g = ctx.createGain();
+    o.type = "sine";
+    o.frequency.setValueAtTime(120, agora);
+    o.frequency.exponentialRampToValueAtTime(36, agora + 0.5);
+    g.gain.setValueAtTime(0.30, agora);
+    g.gain.exponentialRampToValueAtTime(0.0001, agora + 0.9);
+    o.connect(g); g.connect(saida);
+    o.start(agora); o.stop(agora + 1.0);
+
+    var s = ctx.createBufferSource(), gr = ctx.createGain(), f = ctx.createBiquadFilter();
+    s.buffer = bufferRuido();
+    f.type = "lowpass";
+    f.frequency.value = 900;
+    gr.gain.setValueAtTime(0.09, agora);
+    gr.gain.exponentialRampToValueAtTime(0.0001, agora + 0.22);
+    s.connect(f); f.connect(gr); gr.connect(saida);
+    s.start(agora); s.stop(agora + 0.3);
+  }
+
+  /* Blip de interface: curto, agudo, discreto. */
+  function click() {
+    var agora = ctx.currentTime;
+    var o = ctx.createOscillator(), g = ctx.createGain();
+    o.type = "sine";
+    o.frequency.setValueAtTime(2100, agora);
+    g.gain.setValueAtTime(0.06, agora);
+    g.gain.exponentialRampToValueAtTime(0.0001, agora + 0.05);
+    o.connect(g); g.connect(saida);
+    o.start(agora); o.stop(agora + 0.07);
+  }
+
+  /* O efeito certo para a ENTRADA de uma cena, pela transição dela.
+     flash e zoom pedem peso; corte seco não pede nada. */
+  function transicao(tipo, indice) {
+    if (tipo === "corte") return;
+    if (tipo === "flash" || tipo === "zoom") return impacto();
+    whoosh(((indice || 0) * 0.37) % 1);
+  }
+
+  return {
+    whoosh: whoosh,
+    impacto: impacto,
+    click: click,
+    transicao: transicao,
+    volume: function (v) { saida.gain.value = v; },
+  };
+}
+
+if (typeof module !== "undefined" && module.exports) {
+  module.exports = { criarSfx: criarSfx };
+}

package/studio/web/tool.html

@@ -67,6 +67,7 @@
   document.getElementById("btn-baixar").innerHTML = svgIcone("baixar");
 </script>
 <script src="/js/audio.js"></script>
+<script src="/js/sfx.js"></script>
 <script src="/js/voz-neural.js"></script>
   <script src="/js/narracao.js"></script>
 <script src="/js/midia.js"></script>

package/studio/web/view.html

@@ -17,6 +17,7 @@
 <script src="/js/render-prosa.js"></script>
 <script src="/js/render-grade.js"></script>
 <script src="/js/audio.js"></script>
+<script src="/js/sfx.js"></script>
 <script src="/js/voz-neural.js"></script>
   <script src="/js/narracao.js"></script>
 <script src="/js/player.js"></script>