primocode 10.0.0 → 10.1.0

package/lib/video/pedido.js

@@ -0,0 +1,191 @@
+/**
+ * pedido.js — `primocode video do {"pedido":"..."}`: o pedido em português
+ * vira operações do editor, por REGRA (palavras-chave), sem modelo.
+ *
+ *   "Tira o fundo e separa em camadas. Quando eu estalar o dedo me coloca
+ *    numa praia. Põe o logo do ChatGPT na minha mão, e o do Claude nessa.
+ *    Quando eu juntar as mãos vira um cérebro. Corta o silêncio depois do
+ *    estalo. A legenda eu quero azul, em cima da minha cabeça."
+ *
+ * Por que regra e não o modelo: o modelo que dirige o editor pode ser um
+ * modelo grátis e pequeno. O pedido comum ("legenda azul") tem que dar
+ * certo sempre, igual, em milissegundos — e o que a regra não entende volta
+ * como "não entendi" com os exemplos, para o modelo usar as operações à mão.
+ *
+ * `interpretar` é pura (o teste roda cada frase); `do` executa o plano,
+ * adiantando EM PARALELO o que é lento e independente (rastreio e
+ * transcrição) antes do primeiro passo.
+ */
+
+'use strict';
+
+const C = require('./camadas.js');
+
+const tira = (s) => String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+
+const LUGARES = ['praia', 'espaco', 'cidade', 'floresta', 'montanha', 'escritorio', 'deserto', 'neve', 'por do sol', 'paris', 'nova york', 'mar'];
+const NOMES_COR = Object.keys(C.CORES).filter((k) => !/[^a-z ]/.test(k)).sort((a, b) => b.length - a.length);
+
+/** A cor PEDIDA: ignora a que só descreve o estado atual ("ela está amarela"). */
+function corPedida(t) {
+    const limpo = t.replace(/\b(esta|ta|e|era|estava|tava|ficou)\s+(\w+)/g, (m, v, w) => (NOMES_COR.includes(w) ? ' ' : m));
+    let melhor = null;
+    for (const nome of NOMES_COR) {
+        const m = new RegExp(`\\b${nome}\\b`).exec(limpo);
+        if (m && (melhor === null || m.index < melhor.i)) melhor = { i: m.index, nome };
+    }
+    return melhor && melhor.nome;
+}
+
+function lugar(t) {
+    for (const l of LUGARES) if (new RegExp(`\\b${l}\\b`).test(t)) return l;
+    const m = t.match(/\bfundo\s+(?:de|com|do|da|num|numa)\s+(?:um|uma\s+)?([a-z][a-z ]{2,30}?)(?=[,.;!?]|\s+e\s|\s+quando|$)/);
+    return m ? m[1].trim() : null;
+}
+
+/** Onde cada objeto é citado, em ordem, com a mão dita logo depois. */
+function objetosCitados(t) {
+    const out = [];
+    const re = /\b(chat ?gpt|gpt|openai|claude|anthropic|chrome|drive)\b|\blogo\s+d[aoe]s?\s+([a-z0-9]+)/g;
+    let m;
+    const todas = [];
+    while ((m = re.exec(t))) todas.push(m);
+    for (let k = 0; k < todas.length; k++) {
+        m = todas[k];
+        const nome = m[1] || m[2];
+        const modelo = C.modeloDe(nome);
+        if (!modelo && m[2] && /^(chat|gpt|claude)/.test(m[2])) continue;
+        if (out.some((o) => o.pos === m.index)) continue;
+        // A mão dita vale até a próxima citação: "ChatGPT na mão, e o do Claude nessa" — o "nessa" é do Claude.
+        const prox = todas.slice(k + 1).find((x) => x.index > m.index + m[0].length);
+        const depois = t.slice(m.index, Math.min(m.index + 70, prox ? prox.index : Infinity));
+        const mao = /\besquerd/.test(depois) ? 'left' : /\bdireit/.test(depois) ? 'right'
+            : /\b(nessa|nesta|outra|dessa|desta|nessa aqui|na outra)\b/.test(depois) ? 'other' : null;
+        if (modelo === 'cerebro') continue;
+        const item = { object: modelo || nome, pos: m.index, mao };
+        // "o logo do ChatGPT": a mesma citação casou duas vezes.
+        if (out.length && out[out.length - 1].object === item.object && m.index - out[out.length - 1].pos < 14) continue;
+        out.push(item);
+    }
+    return out;
+}
+
+/**
+ * pedido → {passos:[{op,args}], avisos}. `ctx`: {temLegenda, objetos:[{modelo,mao}]}.
+ */
+function interpretar(pedido, ctx = {}) {
+    const t = tira(pedido).replace(/\s+/g, ' ');
+    const passos = [];
+    const avisos = [];
+    const add = (op, args = {}) => passos.push({ op, args });
+
+    const camadas = /\bcamadas?\b|\b3d\b|tres dimens/.test(t);
+    const tiraFundo = /\b(tir\w*|remov\w*|apag\w*|recort\w*)\s+(?:o\s+|do\s+|meu\s+)?fundo\b|\brecort\w*\s+(?:eu|me|a pessoa)\b|\bme\s+recort/.test(t);
+    const estalo = /\bestal\w*|\bsnap\b|\bdedo\b/.test(t);
+    const onde = lugar(t);
+    const trocaFundo = !!onde && /\b(coloc\w*|poe|pon\w*|bot\w*|lev\w*|transport\w*|troc\w*|mud\w*|fundo|joga\w*)\b/.test(t);
+
+    if (camadas && /\bsepar\w*|camadas\b/.test(t)) add('separate_layers', { show3d: true });
+    else if (tiraFundo && !trocaFundo) add('separate_layers', {});
+
+    if (trocaFundo) add('replace_background', { with: onde, ...(estalo ? { at: 'snap' } : {}) });
+
+    const objs = objetosCitados(t);
+    let anteriores = (ctx.objetos || []).length;
+    for (const o of objs) {
+        const hand = o.mao || (anteriores > 0 ? 'other' : 'auto');
+        add('attach_3d', { object: o.object, hand });
+        anteriores++;
+    }
+
+    const cerebro = /\bcerebro\b|\bbrain\b/.test(t);
+    const juntar = /\bjunt\w*\s+(?:as\s+|minhas\s+)?maos\b|\bmaos\s+juntas\b|\bfund\w*\s+(?:os|as)\b|\bjunt\w*\s+(?:os|as)\s+(?:dois|duas|logos)\b/.test(t);
+    if (juntar || (cerebro && objs.length + (ctx.objetos || []).length)) add('merge_on_join', { then: cerebro ? 'brain' : 'none' });
+    else if (cerebro) add('attach_3d', { object: 'brain', hand: 'auto' });
+
+    if (/\b(cort\w*|tir\w*|remov\w*|apag\w*)\s+(?:o\s+|os\s+|esse\s+|aquele\s+)?silencios?\b/.test(t)) {
+        if (estalo) add('cut_silence_at', { event: 'snap' });
+        else add('remove_silence', {});
+    }
+
+    if (/\blegenda/.test(t)) {
+        const cor = corPedida(t);
+        let position = null;
+        if (/\b(em cima|acima|sobre|por cima|encima)\s+da\s+(?:minha\s+)?cabeca\b/.test(t)) position = 'above_head';
+        else if (/\b(embaixo|em baixo|rodape|parte de baixo|la embaixo)\b/.test(t)) position = 'bottom';
+        else if (/\b(no topo|la em cima|parte de cima)\b/.test(t)) position = 'top';
+        else if (/\b(no meio|no centro|centralizad)\w*/.test(t)) position = 'center';
+        const estilo = {};
+        if (cor) estilo.color = cor;
+        if (position) estilo.position = position;
+        if (!ctx.temLegenda) add('add_captions', {});
+        if (Object.keys(estilo).length) add('style_captions', estilo);
+        else if (ctx.temLegenda) avisos.push('a legenda já existe: diga a cor ou a posição (ex.: "legenda azul", "em cima da minha cabeça")');
+    }
+
+    return { passos, avisos };
+}
+
+const EXEMPLOS = [
+    'tira o fundo e separa em camadas', 'quando eu estalar o dedo me coloca numa praia', 'põe o logo do ChatGPT na minha mão',
+    'e o do Claude nessa', 'quando eu juntar as mãos vira um cérebro', 'corta o silêncio depois do estalo',
+    'essa legenda eu quero azul', 'quero a legenda em cima da minha cabeça',
+];
+
+const OPS = {
+    do: {
+        uso: 'do {pedido:"<português>",dryRun?} — ex.: "tira o fundo e separa em camadas", "quando eu estalar o dedo me coloca numa praia", "põe o logo do ChatGPT na minha mão", "o do Claude nessa", "quando eu juntar as mãos vira um cérebro", "corta o silêncio depois do estalo", "legenda azul em cima da minha cabeça"',
+        async run(ctx, a) {
+            const T = require('./timeline.js');
+            const pedido = a.pedido || a.request || a.texto;
+            if (!pedido) throw T.erro('faltou "pedido"');
+            const tl = ctx.tl;
+            const info = {
+                temLegenda: !!tl && T.todosOsClipes(tl).some((x) => x.clip.caption),
+                objetos: tl && tl.fx ? Object.values(tl.fx).flatMap((v) => v.objetos || []) : [],
+            };
+            const plano = interpretar(pedido, info);
+            if (!plano.passos.length) {
+                return { ok: false, error: 'não entendi o pedido (nenhuma regra casou)', exemplos: EXEMPLOS,
+                    dica: 'use as operações direto: primocode video help' };
+            }
+            const resumo = plano.passos.map((p) => ({ op: p.op, args: p.args }));
+            if (a.dryRun) return { ok: true, plano: resumo, ...(plano.avisos.length ? { avisos: plano.avisos } : {}) };
+            if (!tl) throw T.erro('nenhum projeto aberto: import {"path":"..."} primeiro');
+            const { OPS: TODAS } = require('./ops.js');
+            // O que é lento e não depende de nada roda JUNTO antes do primeiro passo.
+            const C2 = require('./camadas.js');
+            const asset = C2.base(tl);
+            const precisaRastro = plano.passos.some((p) => p.op !== 'add_captions' && p.op !== 'remove_silence');
+            const precisaFala = plano.passos.some((p) => ['add_captions', 'attach_3d', 'separate_layers'].includes(p.op));
+            const inicio = Date.now();
+            const [rs] = await Promise.all([
+                precisaRastro ? require('./rastrear.js').garantir(ctx.p.dir, asset) : null,
+                precisaFala && asset.hasAudio ? require('./transcript.js').obter(ctx.p.dir, asset).catch(() => null) : null,
+            ]);
+            if (rs && !rs.ok) return rs;
+            const feitos = [];
+            for (const p of plano.passos) {
+                const res = await TODAS[p.op].run(ctx, p.args);
+                feitos.push({ op: p.op, ...compacto(res) });
+                if (!res || res.ok === false) {
+                    return { ok: false, error: `o passo ${p.op} falhou: ${res && res.error}`, feitos, desfazer: feitos.length > 1 ? `undo {"steps":${feitos.length - 1}}` : null };
+                }
+            }
+            return { ok: true, plano: resumo, feitos, tookS: Math.round((Date.now() - inicio) / 100) / 10, ...(plano.avisos.length ? { avisos: plano.avisos } : {}),
+                depois: 'inspect para OLHAR; export renderiza o 3D (Remotion) na primeira vez' };
+        },
+    },
+};
+
+/** O que importa de cada passo, numa linha (o delta inteiro de cada um encheria o contexto). */
+function compacto(res) {
+    if (!res) return { ok: false };
+    const o = { ok: res.ok !== false };
+    for (const k of ['layers', 'show3d', 'background', 'object', 'merge', 'silence', 'removedFrames', 'captions', 'color', 'follow', 'dur', 'error']) if (res[k] !== undefined) o[k] = res[k];
+    return o;
+}
+
+const EX = { do: '{"pedido":"quando eu estalar o dedo me coloca numa praia"}' };
+
+module.exports = { interpretar, corPedida, objetosCitados, lugar, OPS, EX, EXEMPLOS };

package/lib/video/rastrear.js

@@ -0,0 +1,95 @@
+/**
+ * rastrear.js — roda o studio/rastrear.py, em partes e em paralelo, e
+ * guarda o resultado na pasta do projeto (midia/rastro-<asset>.json,
+ * matte-<asset>.mkv, fundo-<asset>.png). Da segunda vez, é leitura de disco.
+ *
+ * O MediaPipe só existe até o Python 3.12: o script roda pelo `uv` num
+ * Python 3.12 isolado (o mesmo caminho do recorte de pessoa do Estúdio);
+ * sem `uv`, tenta o Python da máquina.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn, execFileSync } = require('child_process');
+const T = require('./timeline.js');
+const PAR = require('./paralelo.js');
+
+const PY = path.join(__dirname, '..', '..', 'studio', 'rastrear.py');
+const TAMANHO_PARTE = 96;   // medido: 48 não ganha nada (o MediaPipe já usa vários núcleos por processo)
+const AQUECER = 12;
+
+let _uv;
+function acharUv() {
+    if (_uv !== undefined) return _uv;
+    for (const c of ['uv', path.join(os.homedir(), '.local', 'bin', 'uv'), '/opt/homebrew/bin/uv', '/usr/local/bin/uv']) {
+        try { execFileSync(c, ['--version'], { stdio: 'ignore', timeout: 5000 }); return (_uv = c); } catch { /* próximo */ }
+    }
+    return (_uv = null);
+}
+
+function rodarPy(args, { timeout = 60 * 60000 } = {}) {
+    const uv = acharUv();
+    const [cmd, todos] = uv
+        ? [uv, ['run', '--quiet', '--python', '3.12', '--with', 'mediapipe<0.10.22', '--with', 'opencv-python', '--with', 'numpy', 'python', PY, ...args]]
+        : [require('../voz.js').python() || 'python3', [PY, ...args]];
+    return new Promise((resolve) => {
+        const p = spawn(cmd, todos, { env: { ...process.env, PYTHONWARNINGS: 'ignore', GLOG_minloglevel: '2', TF_CPP_MIN_LOG_LEVEL: '2' } });
+        let out = '';
+        let err = '';
+        p.stdout.on('data', (d) => { out += d; });
+        p.stderr.on('data', (d) => { err = (err + d).slice(-2000); });
+        const rel = setTimeout(() => { try { p.kill(); } catch {} }, timeout);
+        p.on('error', (e) => { clearTimeout(rel); resolve({ ok: false, error: e.message }); });
+        p.on('close', () => {
+            clearTimeout(rel);
+            try { resolve(JSON.parse(out.trim().split('\n').pop())); } catch { resolve({ ok: false, error: (err || out).slice(-400) || 'o rastreio não respondeu' }); }
+        });
+    });
+}
+
+function arquivos(pasta, asset) {
+    const m = path.join(pasta, 'midia');
+    return { rastro: path.join(m, `rastro-${asset.id}.json`), matte: path.join(m, `matte-${asset.id}.mkv`), fundo: path.join(m, `fundo-${asset.id}.png`) };
+}
+
+const _memo = new Map();
+function lerRastro(arq) {
+    const st = fs.statSync(arq);
+    const k = `${arq}:${st.mtimeMs}`;
+    if (!_memo.has(k)) _memo.set(k, JSON.parse(fs.readFileSync(arq, 'utf8')));
+    return _memo.get(k);
+}
+
+/**
+ * O rastro da mídia (do cache, ou medido agora em paralelo).
+ * Devolve {ok, rastro (objeto), arquivos, tookS?, partes?, trabalhadores?}.
+ */
+async function garantir(pasta, asset, { force = false, trabalhadores } = {}) {
+    if (asset.kind !== 'video') throw T.erro(`a mídia ${asset.id} não é vídeo`);
+    const arq = arquivos(pasta, asset);
+    if (!force && fs.existsSync(arq.rastro) && fs.existsSync(arq.matte) && fs.existsSync(arq.fundo)) {
+        return { ok: true, cache: true, rastro: lerRastro(arq.rastro), arquivos: arq };
+    }
+    const inicio = Date.now();
+    const pastaMidia = path.join(pasta, 'midia');
+    fs.rmSync(path.join(pastaMidia, `partes-${asset.id}`), { recursive: true, force: true });
+    const total = Math.max(1, Math.round((asset.seconds || 0) * (asset.fps || 30)));
+    const lista = PAR.partes(total, TAMANHO_PARTE);
+    const n = trabalhadores || PAR.quantos(lista.length);
+    const res = await PAR.emParalelo(lista.map((p) => () => rodarPy(['analisar', '--entrada', asset.path, '--pasta', pastaMidia, '--id', asset.id,
+        '--de', String(p.de), ...(p.ate === null ? [] : ['--ate', String(p.ate)]), '--aquecer', String(AQUECER)])), n);
+    const ruim = res.find((r) => !r || !r.ok);
+    if (ruim) {
+        return { ok: false, error: `o rastreio falhou: ${(ruim && ruim.error) || '?'}`,
+            comoResolver: acharUv() ? 'confira a rede (o uv baixa o MediaPipe na primeira vez)' : 'instale o uv (https://docs.astral.sh/uv) — o MediaPipe precisa do Python 3.12' };
+    }
+    const j = await rodarPy(['juntar', '--pasta', pastaMidia, '--id', asset.id]);
+    if (!j.ok) return { ok: false, error: `não juntei o rastreio: ${j.error}` };
+    return { ok: true, rastro: lerRastro(arq.rastro), arquivos: arq, tookS: Math.round((Date.now() - inicio) / 100) / 10,
+        partes: lista.length, trabalhadores: n, comMao: j.comMao, comRosto: j.comRosto, segmentador: j.segmentador };
+}
+
+module.exports = { garantir, arquivos, rodarPy, acharUv, lerRastro, TAMANHO_PARTE };

package/lib/video/rastro.js

@@ -0,0 +1,276 @@
+/**
+ * rastro.js — o que o studio/rastrear.py mediu vira trilha, evento e posição.
+ *
+ * O Python só MEDE (por quadro: rosto, topo da cabeça, até duas mãos). Tudo
+ * o que DECIDE mora aqui, como conta pura e testável sem vídeo nenhum:
+ *
+ *   · as duas TRILHAS de mão ("left"/"right" = o lado da TELA, que é o que
+ *     quem assiste vê), com identidade por continuidade — o rótulo
+ *     Left/Right do MediaPipe troca sozinho de um quadro para outro;
+ *   · o buraco de poucos quadros (a mão que some por um instante) é
+ *     preenchido, e o tremor sai no filtro One Euro: parado, segura firme;
+ *     rápido, acompanha sem atraso — o que um filtro de média não faz;
+ *   · os EVENTOS: mãos juntas, mãos abertas, e o ESTALO (um transiente
+ *     curto e agudo no áudio, perto de uma mão);
+ *   · a CABEÇA (topo e centro) para a legenda "em cima da minha cabeça".
+ */
+
+'use strict';
+
+// ── suavizar ─────────────────────────────────────────────────────────────
+
+/**
+ * Filtro One Euro (Casiez et al., 2012) sobre uma série com buracos (null).
+ * `minCutoff` baixo = parado fica parado; `beta` alto = movimento rápido passa.
+ */
+function umEuro(serie, fps, { minCutoff = 1.2, beta = 0.6, dCutoff = 1 } = {}) {
+    const alfa = (corte) => { const tau = 1 / (2 * Math.PI * corte); const te = 1 / fps; return 1 / (1 + tau / te); };
+    const out = new Array(serie.length).fill(null);
+    let x = null;
+    let dx = 0;
+    for (let i = 0; i < serie.length; i++) {
+        const v = serie[i];
+        if (v === null || v === undefined || !Number.isFinite(v)) { x = null; dx = 0; continue; }
+        if (x === null) { x = v; out[i] = v; continue; }
+        const d = (v - x) * fps;
+        const ad = alfa(dCutoff);
+        dx = ad * d + (1 - ad) * dx;
+        const a = alfa(minCutoff + beta * Math.abs(dx));
+        x = a * v + (1 - a) * x;
+        out[i] = x;
+    }
+    return out;
+}
+
+/** Preenche buracos de até `max` quadros por interpolação linear. */
+function preencher(serie, max = 6) {
+    const out = serie.slice();
+    let i = 0;
+    while (i < out.length) {
+        if (out[i] !== null) { i++; continue; }
+        let j = i;
+        while (j < out.length && out[j] === null) j++;
+        const antes = i - 1;
+        if (antes >= 0 && j < out.length && j - i <= max) {
+            for (let k = i; k < j; k++) out[k] = out[antes] + ((out[j] - out[antes]) * (k - antes)) / (j - antes);
+        }
+        i = j;
+    }
+    return out;
+}
+
+// ── as mãos ──────────────────────────────────────────────────────────────
+
+/**
+ * As duas trilhas de mão. `rastro.quadros[i].h` = [[x,y,palma,abertura,rotulo,score]].
+ * Devolve {left:[{x,y,s,open}|null], right:[...]}, já preenchido e suavizado.
+ */
+function trilhasDasMaos(rastro, { buraco = 6, suavizar = true } = {}) {
+    const n = rastro.quadros.length;
+    const asp = (rastro.h || 1920) / (rastro.w || 1080);   // y em fração da altura, x da largura
+    const dist = (a, b) => Math.hypot(a.x - b.x, (a.y - b.y) * asp);
+    const cru = { A: new Array(n).fill(null), B: new Array(n).fill(null) };
+    let ult = { A: null, B: null };
+    let sem = { A: 99, B: 99 };
+    for (let i = 0; i < n; i++) {
+        let hs = ((rastro.quadros[i] || {}).h || []).map((h) => ({ x: h[0], y: h[1], s: h[2], open: h[3] }));
+        // A mesma mão achada duas vezes (acontece na borda): fica uma.
+        if (hs.length === 2 && dist(hs[0], hs[1]) < 0.6 * Math.max(hs[0].s, hs[1].s) * asp) hs = [hs[0]];
+        const vivo = (k) => ult[k] && sem[k] <= 15;
+        if (hs.length === 2) {
+            let [p, q] = hs;
+            if (vivo('A') || vivo('B')) {
+                const ref = (k) => (vivo(k) ? ult[k] : { x: ult[k === 'A' ? 'B' : 'A'] ? 1 - ult[k === 'A' ? 'B' : 'A'].x : (k === 'A' ? 0.25 : 0.75), y: 0.8 });
+                const direto = dist(p, ref('A')) + dist(q, ref('B'));
+                const trocado = dist(q, ref('A')) + dist(p, ref('B'));
+                if (trocado < direto) [p, q] = [q, p];
+            } else if (p.x > q.x) [p, q] = [q, p];   // primeira vez: A é a da esquerda da tela
+            cru.A[i] = p; cru.B[i] = q;
+        } else if (hs.length === 1) {
+            const h = hs[0];
+            let k;
+            if (vivo('A') && vivo('B')) k = dist(h, ult.A) <= dist(h, ult.B) ? 'A' : 'B';
+            else if (vivo('A')) k = dist(h, ult.A) < 0.25 ? 'A' : 'B';
+            else if (vivo('B')) k = dist(h, ult.B) < 0.25 ? 'B' : 'A';
+            else k = h.x < 0.5 ? 'A' : 'B';
+            cru[k][i] = h;
+        }
+        for (const k of ['A', 'B']) { if (cru[k][i]) { ult[k] = cru[k][i]; sem[k] = 0; } else sem[k]++; }
+    }
+    // Quem é a "esquerda": a trilha que passa mais tempo do lado esquerdo da tela.
+    const mediaX = (t) => { const v = t.filter(Boolean); return v.length ? v.reduce((s, h) => s + h.x, 0) / v.length : 0.5; };
+    const [L, R] = mediaX(cru.A) <= mediaX(cru.B) ? [cru.A, cru.B] : [cru.B, cru.A];
+    const fps = rastro.fps || 30;
+    const acabar = (t) => {
+        const campos = {};
+        for (const c of ['x', 'y', 's', 'open']) {
+            let serie = preencher(t.map((h) => (h ? h[c] : null)), buraco);
+            if (suavizar) serie = umEuro(serie, fps, c === 's' ? { minCutoff: 0.6, beta: 0.2 } : { minCutoff: 1.0, beta: 0.8 });
+            campos[c] = serie;
+        }
+        return t.map((_, i) => (campos.x[i] === null ? null : { x: campos.x[i], y: campos.y[i], s: campos.s[i], open: campos.open[i] }));
+    };
+    return { left: acabar(L), right: acabar(R) };
+}
+
+/** Os trechos [de, ate) (quadros) em que a trilha existe por pelo menos `min` quadros. */
+function trechosVisiveis(trilha, min = 8) {
+    const out = [];
+    let i = 0;
+    while (i < trilha.length) {
+        if (!trilha[i]) { i++; continue; }
+        let j = i;
+        while (j < trilha.length && trilha[j]) j++;
+        if (j - i >= min) out.push([i, j]);
+        i = j;
+    }
+    return out;
+}
+
+/**
+ * Mãos juntas e mãos abertas: a distância entre as palmas, em palmas.
+ * "Juntas" = abaixo de `junto` por `min` quadros (ou as duas somem logo
+ * depois de chegarem perto — mão sobre mão o detector perde). "Abertas" =
+ * depois de juntas, acima de `aberto`. Devolve [{junta, abre}] em quadros.
+ */
+function juntaEAbre(trilhas, { rastro = null, junto = 2.8, aberto = 3.8, min = 3, desde = 0 } = {}) {
+    const asp = rastro ? (rastro.h || 1920) / (rastro.w || 1080) : 16 / 9;
+    const n = Math.max(trilhas.left.length, trilhas.right.length);
+    const d = new Array(n).fill(null);
+    for (let i = 0; i < n; i++) {
+        const a = trilhas.left[i];
+        const b = trilhas.right[i];
+        if (a && b) d[i] = Math.hypot(a.x - b.x, (a.y - b.y) * asp) / Math.max(1e-6, ((a.s + b.s) / 2) * asp);
+    }
+    const eventos = [];
+    let i = Math.max(0, desde);
+    while (i < n) {
+        let j = i;
+        while (j < n && d[j] !== null && d[j] < junto) j++;
+        const perto = j - i;
+        const sumiu = perto > 0 && j < n && d[j] === null && d.slice(j, j + 6).every((x) => x === null);
+        if (perto >= min || (perto > 0 && sumiu)) {
+            let k = j;
+            while (k < n && !(d[k] !== null && d[k] > aberto)) k++;
+            if (k < n) { eventos.push({ junta: i, abre: k }); i = k + 1; continue; }
+            eventos.push({ junta: i, abre: null });
+            break;
+        }
+        i = Math.max(i + 1, j);
+    }
+    return eventos;
+}
+
+// ── a cabeça ─────────────────────────────────────────────────────────────
+
+/** Por quadro: {top, cx, fy0, fy1} (frações), suavizado; null onde não há rosto. */
+function trilhaDaCabeca(rastro) {
+    const fps = rastro.fps || 30;
+    const q = rastro.quadros;
+    const cx = q.map((x) => (x && x.f ? (x.f[0] + x.f[2]) / 2 : null));
+    const fy0 = q.map((x) => (x && x.f ? x.f[1] : null));
+    // O topo vem da máscara (o cabelo conta); sem ele, o rosto com uma folga para o cabelo.
+    const top = q.map((x) => (x && x.t !== undefined ? x.t : x && x.f ? x.f[1] - 0.35 * (x.f[3] - x.f[1]) : null));
+    const lento = { minCutoff: 0.4, beta: 0.3 };
+    const s = (v) => umEuro(preencher(v, 30), fps, lento);
+    const [A, B, C] = [s(cx), s(fy0), s(top)];
+    return q.map((_, i) => (A[i] === null || C[i] === null ? null : { cx: A[i], fy0: B[i], top: C[i] }));
+}
+
+/**
+ * Onde a legenda fica "em cima da cabeça": o centro da legenda acima do topo,
+ * com margem, sem sair da tela. Tudo em frações do QUADRO DO PROJETO.
+ * `altura` = altura da caixa da legenda (fração); `largura` idem.
+ */
+function acimaDaCabeca(cabeca, { altura = 0.06, largura = 0.86, margem = 0.025, minCy = 0.05 } = {}) {
+    if (!cabeca) return null;
+    const cy = Math.max(minCy + altura / 2, cabeca.top - margem - altura / 2);
+    const meia = Math.min(0.5, largura / 2);
+    const cx = Math.max(meia, Math.min(1 - meia, cabeca.cx));
+    return { cx, cy };
+}
+
+// ── o estalo ─────────────────────────────────────────────────────────────
+
+/**
+ * Os estalos (ou palmas) no áudio: um transiente AGUDO e CURTO. Amostras
+ * mono Float32. Para cada janela de 5 ms mede a energia da derivada (um
+ * passa-alta de graça) e procura:
+ *   · subida grande sobre os 100 ms anteriores (≥ `subida` vezes);
+ *   · queda rápida: 60 ms depois já caiu a menos de 1/`queda` do pico;
+ *   · e o pico forte comparado ao áudio inteiro (não é a sibilante da fala).
+ * Devolve [{t (segundos), score}] em ordem de tempo.
+ */
+function estalos(amostras, taxa, { subida = 20, queda = 6, minimoEntre = 0.3 } = {}) {
+    const hop = Math.max(16, Math.round(taxa * 0.005));
+    const n = Math.floor((amostras.length - 1) / hop);
+    const hf = new Float64Array(n);
+    for (let k = 0; k < n; k++) {
+        let s = 0;
+        for (let j = k * hop + 1; j < (k + 1) * hop + 1 && j < amostras.length; j++) { const d = amostras[j] - amostras[j - 1]; s += d * d; }
+        hf[k] = s / hop;
+    }
+    const ordenado = Array.from(hf).sort((a, b) => a - b);
+    const p99 = ordenado[Math.floor(0.99 * (n - 1))] || 0;
+    const piso = Math.max(1e-7, p99 * 0.5);
+    const out = [];
+    let ultimo = -Infinity;
+    const antes = Math.round(0.1 / 0.005);
+    const depois = Math.round(0.06 / 0.005);
+    for (let k = antes; k < n - depois; k++) {
+        if (hf[k] < piso || hf[k] < hf[k - 1] || hf[k] < hf[k + 1]) continue;
+        let m = 0;
+        for (let j = k - antes; j < k - 1; j++) m += hf[j];
+        m = m / (antes - 1) + 1e-9;
+        const razao = hf[k] / m;
+        if (razao < subida) continue;
+        if (hf[k + depois] > hf[k] / queda) continue;
+        const t = (k * hop) / taxa;
+        if (t - ultimo < minimoEntre) continue;
+        out.push({ t: Math.round(t * 1000) / 1000, score: Math.round(10 * Math.log10(razao) * 10) / 10 });
+        ultimo = t;
+    }
+    return out;
+}
+
+/**
+ * O estalo que vale: o de maior score, com bônus se há uma mão na tela por
+ * perto (±0,5 s). `trilhas` opcional. Devolve [{t, score, mao}] ordenado por score.
+ */
+function escolherEstalos(cands, trilhas, fps) {
+    return cands.map((c) => {
+        let mao = false;
+        if (trilhas) {
+            const f = Math.round(c.t * fps);
+            for (let i = Math.max(0, f - Math.round(fps / 2)); i <= f + Math.round(fps / 2); i++) {
+                if ((trilhas.left[i]) || (trilhas.right[i])) { mao = true; break; }
+            }
+        }
+        return { ...c, mao, total: c.score + (mao ? 6 : 0) };
+    }).sort((a, b) => b.total - a.total);
+}
+
+// ── da origem para a tela ────────────────────────────────────────────────
+
+/**
+ * Um ponto da ORIGEM (frações do vídeo) → frações do quadro do PROJETO,
+ * para um clipe desenhado com o transform dele e fit "cover" (o padrão).
+ */
+function origemParaTela(tl, clip, asset, x, y) {
+    const W = tl.width;
+    const H = tl.height;
+    const tf = clip.transform || { cx: 0.5, cy: 0.5, w: 1, h: 1 };
+    const bw = tf.w * W;
+    const bh = tf.h * H;
+    const aw = asset.width || W;
+    const ah = asset.height || H;
+    let esc;
+    if (clip.fit === 'contain') esc = Math.min(bw / aw, bh / ah);
+    else if (clip.fit === 'stretch') return { x: (tf.cx * W - bw / 2 + x * bw) / W, y: (tf.cy * H - bh / 2 + y * bh) / H };
+    else esc = Math.max(bw / aw, bh / ah);
+    const px = tf.cx * W + (x - 0.5) * aw * esc;
+    const py = tf.cy * H + (y - 0.5) * ah * esc;
+    return { x: px / W, y: py / H, escala: (ah * esc) / H };
+}
+
+module.exports = { umEuro, preencher, trilhasDasMaos, trechosVisiveis, juntaEAbre, trilhaDaCabeca, acimaDaCabeca, estalos, escolherEstalos, origemParaTela };