primocode 9.10.0 → 10.0.9

package/lib/video/projeto.js

@@ -0,0 +1,133 @@
+/**
+ * projeto.js — onde a edição mora: `<pasta atual>/video/<id>/`.
+ *
+ *   timeline.json   o projeto (lib/video/timeline.js)
+ *   history/        uma foto da timeline ANTES de cada edição (o undo)
+ *   log.jsonl       o caderno: que operação, quando, com que resultado
+ *   midia/          transcrição e silêncio medidos (cache por mídia)
+ *   cache/          os pngs do texto e os quadros do inspect
+ *   saida/          o mp4 exportado e a folha do inspect
+ *
+ * A pasta fica NA PASTA DO TRABALHO, e não em ~/.primocode como os projetos
+ * do Estúdio: a gravação é da pessoa, está ali, e o vídeo editado tem que
+ * aparecer ao lado dela. O id segue a convenção do Estúdio (data na frente,
+ * apelido depois), para "o de semana passada" ser achado pela ordem.
+ *
+ * ── POR QUE O UNDO É FOTO E NÃO OPERAÇÃO INVERSA ─────────────────────────
+ * Desfazer um ripple de quarenta clipes com a conta inversa é reescrever o
+ * ripple ao contrário, com os mesmos defeitos. A foto do json custa alguns
+ * kB e desfaz qualquer coisa, inclusive o que for criado amanhã. É o que
+ * deixa o agente editar sem pedir licença a cada passo.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const T = require('./timeline.js');
+const { apelidar } = require('../estudio/projeto.js');
+
+const MAX_HISTORICO = 100;
+
+function raiz(cwd = process.cwd()) {
+    return process.env.PRIMOCODE_VIDEO_DIR || path.join(cwd, 'video');
+}
+
+function escreverAtomico(arq, texto) {
+    const tmp = `${arq}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, texto);
+    fs.renameSync(tmp, arq);
+}
+
+function criar({ nome = 'video', width, height, fps, cwd } = {}) {
+    const base = raiz(cwd);
+    const dia = new Date().toISOString().slice(0, 10);
+    const semente = `${dia}-${apelidar(nome)}`;
+    let id = semente;
+    for (let n = 2; fs.existsSync(path.join(base, id)); n++) id = `${semente}-${n}`;
+    const dir = path.join(base, id);
+    for (const sub of ['history', 'midia', 'cache', 'saida']) fs.mkdirSync(path.join(dir, sub), { recursive: true });
+    const tl = T.novo({ nome: apelidar(nome), width, height, fps });
+    const p = { id, dir };
+    salvar(p, tl);
+    fs.writeFileSync(path.join(base, '.atual'), id);
+    return { p, tl };
+}
+
+function atual(cwd) {
+    try { return fs.readFileSync(path.join(raiz(cwd), '.atual'), 'utf8').trim() || null; } catch { return null; }
+}
+
+function abrir(id, cwd) {
+    const base = raiz(cwd);
+    const alvo = id || atual(cwd);
+    if (!alvo) return null;
+    let dir = path.join(base, alvo);
+    if (!fs.existsSync(path.join(dir, 'timeline.json'))) {
+        // Aceita o começo do id ("2026-09-29-aula") como no clipe.
+        const casa = listar(cwd).filter((x) => x.id.startsWith(alvo) || x.id.endsWith(alvo));
+        if (casa.length !== 1) return null;
+        dir = path.join(base, casa[0].id);
+    }
+    const tl = JSON.parse(fs.readFileSync(path.join(dir, 'timeline.json'), 'utf8'));
+    return { p: { id: path.basename(dir), dir }, tl };
+}
+
+function usar(id, cwd) { fs.writeFileSync(path.join(raiz(cwd), '.atual'), id); }
+
+function listar(cwd) {
+    const base = raiz(cwd);
+    if (!fs.existsSync(base)) return [];
+    return fs.readdirSync(base).filter((n) => fs.existsSync(path.join(base, n, 'timeline.json'))).sort().map((id) => {
+        let tl = null;
+        try { tl = JSON.parse(fs.readFileSync(path.join(base, id, 'timeline.json'), 'utf8')); } catch {}
+        return { id, s: tl ? T.r2(T.duracao(tl) / tl.fps) : null, clips: tl ? T.todosOsClipes(tl).length : null };
+    });
+}
+
+function salvar(p, tl) {
+    escreverAtomico(path.join(p.dir, 'timeline.json'), JSON.stringify(tl));
+}
+
+function historico(p) {
+    const dir = path.join(p.dir, 'history');
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir).filter((n) => /^\d+\.json$/.test(n)).sort();
+}
+
+/** Guarda a foto de ANTES da edição. */
+function fotografar(p, antes, op) {
+    const lista = historico(p);
+    const n = lista.length ? Number(lista[lista.length - 1].slice(0, -5)) + 1 : 1;
+    fs.mkdirSync(path.join(p.dir, 'history'), { recursive: true });
+    fs.writeFileSync(path.join(p.dir, 'history', `${String(n).padStart(6, '0')}.json`), JSON.stringify({ op, tl: antes }));
+    for (const velho of lista.slice(0, Math.max(0, lista.length + 1 - MAX_HISTORICO))) {
+        try { fs.unlinkSync(path.join(p.dir, 'history', velho)); } catch {}
+    }
+}
+
+/** Volta `passos` edições. Devolve {tl, desfeitas:[ops]} ou erro. */
+function desfazer(p, passos = 1) {
+    const lista = historico(p);
+    if (!lista.length) throw T.erro('não há nada para desfazer');
+    // "abc" daria NaN, e slice(-NaN) é o histórico INTEIRO.
+    const n = Math.max(1, Math.min(lista.length, Math.round(Number(passos)) || 1));
+    const alvo = lista.slice(-n);
+    const desfeitas = [];
+    let tl = null;
+    for (const arq of [...alvo].reverse()) {
+        const foto = JSON.parse(fs.readFileSync(path.join(p.dir, 'history', arq), 'utf8'));
+        desfeitas.push(foto.op);
+        tl = foto.tl;
+        fs.unlinkSync(path.join(p.dir, 'history', arq));
+    }
+    return { tl, desfeitas, restam: lista.length - n };
+}
+
+function anotar(p, op, resumo) {
+    try {
+        fs.appendFileSync(path.join(p.dir, 'log.jsonl'), JSON.stringify({ q: new Date().toISOString(), op, ...resumo }) + '\n');
+    } catch { /* o caderno não pode derrubar a edição */ }
+}
+
+module.exports = { raiz, criar, abrir, atual, usar, listar, salvar, fotografar, desfazer, historico, anotar, MAX_HISTORICO };

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 };