primocode 10.0.0 → 10.0.9

package/lib/video/auto.js

@@ -0,0 +1,329 @@
+/**
+ * auto.js — `primocode video auto`: o vídeo é o pedido.
+ *
+ *   "Quero que ele leia o que eu falo no vídeo e aplique cada pedido no
+ *    momento em que eu digo." (01/10)
+ *
+ * A pessoa grava falando o que quer ("separe em camadas", "coloca o logo do
+ * Claude aqui", "com o estalar de dedos me coloca numa praia") e o editor
+ * acha cada pedido na transcrição e o ancora no que o rastro viu: a palavra,
+ * a mão que aparece logo depois, o estalo que vem em seguida, o juntar das
+ * mãos. Nada de quadro escrito à mão.
+ *
+ *   planejar(dados) → [{op, args(segundos da origem), motivo}]   pura (o teste roda)
+ *   OPS.auto.run    → junta os dados, executa o plano, devolve o que fez
+ *
+ * Tudo em SEGUNDOS DA ORIGEM até a hora de executar: os cortes (silêncio,
+ * fim) vão por último e a legenda depois deles, já nos cortes.
+ */
+
+'use strict';
+
+const PED = require('./pedido.js');
+
+const tira = (s) => String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+const r2 = (n) => Math.round(n * 100) / 100;
+
+/* O que o Whisper ouve no lugar do que a pessoa disse — visto nos dois
+   primeiros vídeos de verdade: "cloud", "Claudio", "xgbt", "estravar",
+   "instruar de dedos". Normaliza antes de qualquer regra. */
+const OUVIDO = [
+    [/\b(claudio|claudia|cloud|clode|clod|claud|cloude)\b/g, 'claude'],
+    [/\b(x ?gbt|x ?gpt|chat ?gbt|chat ?gpt|chat ?jpt|tchat ?gpt|chatgbt|gbt)\b/g, 'chatgpt'],
+    [/\bgoogle\s+(chrome|drive)\b/g, '$1'],
+    [/\b(estr[ae]l\w*|estrav\w*|estal\w*|instru\w*|estral\w*)\s+(?:os|nos|dos|de|o|do)?\s*dedos?\b/g, 'estalar o dedo'],
+    [/\b(estal\w*|estral\w*)\b/g, 'estalar'],
+];
+function normal(t) {
+    let s = tira(t).replace(/[^a-z0-9 ]/g, ' ').replace(/\s+/g, ' ').trim();
+    for (const [re, por] of OUVIDO) s = s.replace(re, por);
+    return s;
+}
+
+/* "colocar um foguete aqui na palma da minha mão": qualquer coisa na mão, não
+   só as logos. Vira o modelo, se houver, ou a placa com o nome. */
+const NA_MAO = /\b(?:coloc\w*|po[er]\w*|bot\w*|aparec\w*)\s+(?:um|uma|o|a)\s+([a-z]{3,20})(?:\s+[a-z]{3,20})?\s+(?:aqui\s+)?(?:na|em|sobre|nas)\s+(?:a\s+)?(?:palma|mao|maos)\b/g;
+const NAO_OBJETO = /^(logo|imagem|foto|fundo|legenda|praia|cerebro|video|mao|coisa)$/;
+function objetoNaMao(t) {
+    const out = [];
+    let m;
+    NA_MAO.lastIndex = 0;
+    while ((m = NA_MAO.exec(t))) if (!NAO_OBJETO.test(m[1])) out.push({ object: m[1], pos: m.index, mao: null });
+    return out;
+}
+
+/** As palavras viram frases: ponto final, ou pausa de mais de 0,7 s. */
+function frases(palavras) {
+    const out = [];
+    let atual = [];
+    const fecha = () => { if (atual.length) out.push({ ws: atual, de: atual[0].de, ate: atual[atual.length - 1].ate }); atual = []; };
+    palavras.forEach((p, i) => {
+        const ant = palavras[i - 1];
+        if (ant && p.de - ant.ate > 0.7) fecha();
+        atual.push(p);
+        if (/[.!?]$/.test(String(p.texto).trim())) fecha();
+    });
+    fecha();
+    for (const f of out) f.t = normal(f.ws.map((w) => w.texto).join(' '));
+    return out;
+}
+
+/** O segundo em que a frase diz `re` (a primeira palavra que casa), ou o começo dela. */
+function quando(f, re) {
+    for (let i = 0; i < f.ws.length; i++) {
+        const um = normal(f.ws[i].texto);
+        const dois = normal(f.ws.slice(i, i + 3).map((w) => w.texto).join(' '));
+        if (re.test(um) || (re.test(dois) && !re.test(normal(f.ws.slice(i + 1, i + 3).map((w) => w.texto).join(' '))))) return f.ws[i].de;
+    }
+    return f.de;
+}
+
+const RE = {
+    camadas: /\bcamadas?\b|\btres dimens|\b(tir\w*|remov\w*|recort\w*|separ\w*)\s+(?:me\s+)?(?:o\s+|do\s+|meu\s+)?fundo\b|\bme\s+(tir\w*|recort\w*)\s+do\s+fundo\b/,
+    volta: /\bvolt\w*\b|\bnormal\b/,
+    estalo: /\bestalar\b/,
+    juntar: /\bjunt\w*\b|\buni\w*\b/,
+    cerebro: /\bcerebro\b/,
+    silencio: /\bsilencios?\b/,
+    fim: /\b(encerr|acab|termin|finaliz)\w*\b/,
+    legenda: /\blegendas?\b/,
+    acima: /\b(em cima|acima|encima|sobre|por cima)\s+da\s+(?:minha\s+)?cabeca\b|\baqui em cima\b|\bla em cima\b/,
+    imagem: /\b(?:imagem|foto|fundo)\s+(?:de|do|da)\s+(?:(?:um|uma)\s+)?([a-z]{3,20})\b/,
+};
+
+/** O fundo pedido na frase: um lugar conhecido, ou "imagem de um tubarão". */
+function fundoPedido(t) {
+    const l = PED.lugar(t);
+    if (l && !/^(tras|atras|aqui)$/.test(l)) return l;
+    const m = t.match(RE.imagem);
+    return m && !/^(tras|atras|aqui|novo|nova)$/.test(m[1]) ? m[1] : null;
+}
+
+/**
+ * dados: {palavras:[{texto,de,ate}], estalos:[{t,score,mao}], juntaAbre:[{junta,abre}],
+ *         maos:{left:[[de,ate]],right:[[de,ate]]}, silencios:[{de,ate}], dur}  — tudo em segundos.
+ * → {passos:[{op,args,motivo}], legenda:{color?,position?,desde?}}
+ */
+function planejar(d) {
+    const fs = frases(d.palavras || []);
+    const passos = [];
+    const bons = (d.estalos || []).filter((e) => e.mao || e.score >= 20);
+    const usados = new Set();
+    /* O estalo da janela é o MAIS FORTE dela, não o primeiro: o dedo que se
+       prepara faz um "tec" fraco antes do estalo de verdade (visto: 10,3 s
+       com 17 antes do 11,8 s com 21). */
+    const estaloDepois = (t, janela) => {
+        const c = bons.filter((x) => x.t >= t - 0.2 && x.t <= t + janela && !usados.has(x.t)).sort((a, b) => b.score - a.score)[0];
+        if (!c) return undefined;
+        usados.add(c.t);
+        return c.t;
+    };
+    const ehPedido = (f) => RE.camadas.test(f.t) || !!fundoPedido(f.t) || PED.objetosCitados(f.t).length || RE.juntar.test(f.t) || RE.silencio.test(f.t) || RE.fim.test(f.t);
+
+    // 1. As camadas em 3D: da palavra até o "volta" (ou o próximo pedido), 2,5–5 s.
+    const iCam = fs.findIndex((f) => RE.camadas.test(f.t) && !fundoPedido(f.t));
+    if (iCam >= 0) {
+        const de = Math.max(0, quando(fs[iCam], /camada|fundo|tir|recort|separ/) - 0.2);
+        const prox = fs.slice(iCam + 1).find((f) => f.de > de + 1 && (RE.volta.test(f.t) || ehPedido(f)));
+        const ate = Math.min(d.dur, de + 5, Math.max(de + 2.5, prox ? prox.de : de + 4));
+        passos.push({ op: 'separate_layers', args: { show3d: true, from: r2(de), to: r2(ate) }, motivo: `"${fs[iCam].t}"` });
+    }
+
+    // 2. Os objetos: na palavra, na mão que aparece logo ali (a outra, se a primeira já tem um).
+    const objetos = [];
+    const maoEm = (t, ocupadas) => {
+        const cand = [];
+        for (const lado of ['left', 'right']) {
+            for (const [a, b] of (d.maos && d.maos[lado]) || []) {
+                if (b < t - 0.2 || a > t + 3) continue;
+                cand.push({ lado, a: Math.max(a, t), b });
+            }
+        }
+        cand.sort((x, y) => (ocupadas.has(x.lado) - ocupadas.has(y.lado)) || x.a - y.a);
+        return cand[0] || null;
+    };
+    for (const f of fs) {
+        for (const o of [...PED.objetosCitados(f.t), ...objetoNaMao(f.t)]) {
+            const nome = o.object === 'chatgpt' ? /chatgpt|gpt/ : new RegExp(o.object.slice(0, 5));
+            const t = quando(f, nome);
+            if (objetos.some((x) => x.object === o.object && Math.abs(x.t - t) < 4)) continue;
+            const ocupadas = new Set(objetos.filter((x) => x.ate === null || x.ate > t).map((x) => x.mao));
+            const m = maoEm(t, ocupadas);
+            const mao = o.mao === 'left' || o.mao === 'right' ? o.mao : m ? m.lado : (ocupadas.has('left') ? 'right' : 'auto');
+            objetos.push({ object: o.object, t, de: m && m.lado === mao ? m.a : t, mao, ate: null, motivo: `"${f.t}"` });
+        }
+    }
+
+    // 3. Juntar as mãos (com objeto na mão): a junção que vem depois da frase; o cérebro se for dito.
+    let fusao = null;
+    if (objetos.length) {
+        const iJ = fs.findIndex((f) => (RE.juntar.test(f.t) || RE.cerebro.test(f.t)) && f.ate > objetos[0].t);
+        if (iJ >= 0) {
+            const f = fs[iJ];
+            const ev = (d.juntaAbre || []).find((e) => e.junta >= f.de - 1.5 && e.junta > objetos[0].de + 0.5);
+            if (ev) {
+                const cerebro = [f, fs[iJ + 1]].some((x) => x && RE.cerebro.test(x.t));
+                fusao = { junta: ev.junta, abre: ev.abre, then: cerebro ? 'brain' : 'none', motivo: `"${f.t}"` };
+            }
+        }
+    }
+    for (const o of objetos) {
+        o.ate = fusao && fusao.junta > o.de ? fusao.junta : Math.min(d.dur, o.de + 4);
+        if (o.ate > o.de + 0.3) passos.push({ op: 'attach_3d', args: { object: o.object, hand: o.mao, from: r2(o.de), to: r2(o.ate) }, motivo: o.motivo });
+    }
+    if (fusao) passos.push({ op: 'merge_on_join', args: { junta: r2(fusao.junta), ...(fusao.abre !== null ? { abre: r2(fusao.abre) } : {}), then: fusao.then }, motivo: fusao.motivo });
+
+    // 4. Fundos novos: no estalo, se a frase (ou a anterior) fala dele, ou se um estalo vem logo depois; senão na palavra.
+    const fundos = [];
+    fs.forEach((f, i) => {
+        const onde = fundoPedido(f.t);
+        if (!onde || !/\b(coloc\w*|poe|pon\w*|bot\w*|lev\w*|troc\w*|mud\w*|fundo|imagem|foto|me\s+em)\b/.test(f.t)) return;
+        const t = quando(f, new RegExp(onde.split(' ')[0].slice(0, 5)));
+        /* Um estalo logo depois do lugar é o gatilho, dito ou não. Se o estalo
+           foi dito ANTES do lugar ("se estalar os dedos ela coloca um
+           tubarão"), ele pode vir uns segundos depois da frase. */
+        const antes = f.t.slice(0, f.t.indexOf(onde.split(' ')[0]));
+        const falaEstalo = RE.estalo.test(antes) || (fs[i - 1] && RE.estalo.test(fs[i - 1].t) && !fundoPedido(fs[i - 1].t));
+        let e = estaloDepois(t, 3);
+        if (e === undefined && falaEstalo) e = estaloDepois(f.de, 10);
+        // "só aqui", "somente aqui": o fundo vale para a frase, depois volta o original.
+        const so = /\b(somente|so|apenas)\s+(aqui|agora|nessa parte|nesse momento)\b/.test(f.t) ? Math.min(d.dur, f.ate + 0.6) : null;
+        fundos.push({ with: onde, at: e !== undefined ? e : t, ...(so ? { ate: so } : {}), motivo: `"${f.t}"` + (e !== undefined ? ' (no estalo)' : '') });
+    });
+    fundos.forEach((b, i) => {
+        const until = b.ate !== undefined ? b.ate : fundos[i + 1] ? fundos[i + 1].at : null;
+        passos.push({ op: 'replace_background', args: { with: b.with, at: r2(b.at), ...(until !== null ? { until: r2(until) } : {}) }, motivo: b.motivo });
+    });
+
+    // 5. Legenda: sempre (é reels); a cor e a posição se forem pedidas, a partir do estalo se ele for citado.
+    const legenda = {};
+    const iL = fs.findIndex((f) => RE.legenda.test(f.t));
+    if (iL >= 0) {
+        const janela = fs.slice(iL, iL + 3);
+        const cor = janela.map((f) => PED.corPedida(f.t)).find(Boolean);
+        if (cor) legenda.color = cor;
+        const fp = janela.find((f) => RE.acima.test(f.t));
+        if (fp) {
+            legenda.position = 'above_head';
+            if (RE.estalo.test(fp.t)) { const e = estaloDepois(fp.de, 8); if (e !== undefined) legenda.desde = e; }
+            // "a legenda que tá aqui… aqui em cima": sobe quando ela diz onde.
+            else if (/\b(aqui|la) em cima\b/.test(fp.t)) legenda.desde = quando(fp, /cima/);
+        } else {
+            /* "a legenda daqui ficar aqui", apontando: o pedido é mudar de lugar, e
+               o lugar que se aponta em quem fala para a câmera é perto do rosto —
+               a legenda sobe para a cabeça no segundo "aqui". (01/10) */
+            const fd = janela.find((f) => /\bdaqui\b[\s\S]*\b(ficar|ir|pra|para)\b[\s\S]*\baqui\b|\b(mud|muda|mover|move|pass)\w*\b[\s\S]*\baqui\b/.test(f.t));
+            if (fd) {
+                legenda.position = 'above_head';
+                const aquis = fd.ws.filter((w) => /^aqui/.test(normal(w.texto)));
+                legenda.desde = (aquis[aquis.length - 1] || fd.ws[0]).de;
+            }
+        }
+    }
+
+    // 6. Cortes, por último: o silêncio que a pessoa cita, e o fim que ela anuncia.
+    const cortes = [];
+    const iS = fs.findIndex((f) => RE.silencio.test(f.t) && /\b(cort\w*|tir\w*|remov\w*|apag\w*|retir\w*)\b/.test(f.t));
+    if (iS >= 0) {
+        const t0 = fs[iS].de;
+        const sil = juntarSilencios(d.silencios || []).filter((s) => s.de >= t0 && s.de <= t0 + 15 && s.ate - s.de >= 1.5)
+            .sort((a, b) => (b.ate - b.de) - (a.ate - a.de))[0];
+        if (sil) cortes.push({ de: r2(sil.de + 0.1), ate: r2(sil.ate - 0.1), motivo: `"${fs[iS].t}" (${r2(sil.ate - sil.de)} s parado)` });
+    }
+    const iF = fs.findIndex((f) => RE.fim.test(f.t) && /\bvideo\b/.test(f.t));
+    if (iF >= 0) {
+        const f = fs[iF];
+        const ultima = fs[fs.length - 1].ate;
+        const e = RE.estalo.test(f.t) ? estaloDepois(f.de, 6) : undefined;
+        const fim = Math.max(ultima, e !== undefined ? e : 0) + 0.4;
+        if (d.dur - fim > 0.8) cortes.push({ de: r2(fim), ate: r2(d.dur), motivo: `"${f.t}"` });
+    }
+    if (cortes.length) passos.push({ op: 'cortes', args: { trechos: cortes.map(({ de, ate }) => [de, ate]) }, motivo: cortes.map((c) => c.motivo).join(' · ') });
+
+    return { passos, legenda };
+}
+
+/** Silêncios separados por um respiro (< 0,4 s) são um só. */
+function juntarSilencios(sil) {
+    const out = [];
+    for (const s of [...sil].sort((a, b) => a.de - b.de)) {
+        const u = out[out.length - 1];
+        if (u && s.de - u.ate < 0.4) u.ate = Math.max(u.ate, s.ate);
+        else out.push({ de: s.de, ate: s.ate });
+    }
+    return out;
+}
+
+const OPS = {
+    auto: {
+        uso: 'auto {asset?,dryRun?} — O VÍDEO É O PEDIDO: lê o que a pessoa FALA na gravação ("separe em camadas", "coloca o logo do Claude aqui", "com o estalar de dedos me coloca numa praia", "junta e vira um cérebro", "cortou o silêncio", "o vídeo acaba") e aplica cada efeito no momento em que ela diz, ancorado na palavra, na mão, no estalo e no juntar das mãos; legenda sempre. Use logo depois do import quando pedirem "edite esse vídeo" sem dizer o quê',
+        async run(ctx, a) {
+            const T = require('./timeline.js');
+            const C = require('./camadas.js');
+            const R = require('./rastro.js');
+            const RT = require('./rastrear.js');
+            const TR = require('./transcript.js');
+            const FXO = require('./ops-fx.js');
+            const tl = ctx.tl;
+            if (!tl) throw T.erro('nenhum projeto aberto: import {"path":"..."} primeiro');
+            const asset = C.base(tl, a.asset);
+            const inicio = Date.now();
+            // O lento e independente junto: rastreio (MediaPipe em paralelo) e transcrição.
+            const [rs, tr] = await Promise.all([RT.garantir(ctx.p.dir, asset), TR.obter(ctx.p.dir, asset)]);
+            if (!rs.ok) return rs;
+            if (!tr.ok) return { ok: false, error: 'sem a fala não sei o que fazer: ' + tr.error };
+            const fps = rs.rastro.fps;
+            const trilhas = R.trilhasDasMaos(rs.rastro);
+            const trechos = (t) => R.trechosVisiveis(t, Math.round(fps * 0.3)).map(([x, y]) => [x / fps, y / fps]);
+            const dados = {
+                palavras: tr.palavras,
+                estalos: (await FXO.estalosDe(ctx, asset)).map((e) => ({ t: e.t, score: e.score, mao: e.mao })),
+                juntaAbre: R.juntaEAbre(trilhas, { rastro: rs.rastro }).map((e) => ({ junta: e.junta / fps, abre: e.abre === null ? null : e.abre / fps })),
+                maos: { left: trechos(trilhas.left), right: trechos(trilhas.right) },
+                silencios: await require('./render.js').silenciosDe(ctx.p.dir, asset, { threshold: -35, minSilence: 0.8 }),
+                dur: asset.seconds,
+            };
+            const plano = planejar(dados);
+            const q = (s) => C.origemParaQuadro(ctx.tl, asset.id, s);
+            const ver = plano.passos.map((p) => ({ op: p.op, motivo: p.motivo, args: p.args }));
+            if (a.dryRun) return { ok: true, plano: ver, legenda: plano.legenda, segundos: 'da gravação' };
+
+            const { OPS: TODAS } = require('./ops.js');
+            const feitos = [];
+            const roda = async (op, args, motivo) => {
+                const res = await TODAS[op].run(ctx, args);
+                feitos.push({ op, motivo, ok: !!res && res.ok !== false, ...(res && res.ok === false ? { error: res.error } : {}) });
+                return res;
+            };
+            for (const p of plano.passos) {
+                const g = p.args;
+                if (p.op === 'separate_layers') await roda(p.op, { show3d: true, from: q(g.from), to: q(g.to) }, p.motivo);
+                else if (p.op === 'attach_3d') await roda(p.op, { object: g.object, hand: g.hand, from: q(g.from), to: q(g.to) }, p.motivo);
+                else if (p.op === 'merge_on_join') await roda(p.op, { junta: q(g.junta), ...(g.abre !== undefined ? { abre: q(g.abre) } : {}), then: g.then }, p.motivo);
+                else if (p.op === 'replace_background') await roda(p.op, { with: g.with, at: q(g.at), ...(g.until !== undefined ? { until: q(g.until) } : {}) }, p.motivo);
+                else if (p.op === 'cortes') {
+                    const ranges = g.trechos.map(([de, ate]) => [q(de), Math.min(T.duracao(ctx.tl), q(Math.min(ate, asset.seconds - 0.001)) + 1)]).filter(([x, y]) => x !== null && y > x);
+                    if (ranges.length) await roda('ripple_delete_ranges', { ranges }, p.motivo);
+                }
+            }
+            // A legenda, já nos cortes; a posição a partir do estalo, se ele foi citado.
+            await roda('add_captions', { maxWords: 3, animation: 'highlightPop' }, 'legenda (reels)');
+            const L = plano.legenda;
+            if (L.color || L.position) {
+                const leg = T.todosOsClipes(ctx.tl).filter((x) => x.clip.caption).map((x) => x.clip);
+                const desde = L.desde !== undefined ? q(L.desde) : null;
+                if (L.color) await roda('style_captions', { color: L.color }, 'cor pedida');
+                const ids = leg.filter((c) => desde === null || c.startFrame >= desde).map((c) => c.id);
+                if (L.position && ids.length) await roda('style_captions', { ids, position: L.position }, desde !== null ? 'em cima da cabeça, desde o momento dito' : 'em cima da cabeça');
+            }
+            const falhou = feitos.filter((f) => !f.ok);
+            return { ok: !falhou.length, feitos, tookS: Math.round((Date.now() - inicio) / 100) / 10,
+                ...(falhou.length ? { error: falhou.map((f) => `${f.op}: ${f.error}`).join('; ') } : {}),
+                depois: 'inspect para OLHAR os momentos; export renderiza (o 3D sai no export)' };
+        },
+    },
+};
+
+const EX = { auto: '{}' };
+
+module.exports = { planejar, frases, normal, fundoPedido, juntarSilencios, OPS, EX };

package/lib/video/camadas.js

@@ -0,0 +1,207 @@
+/**
+ * camadas.js — as peças comuns das operações "de efeito" (separar, trocar
+ * fundo, objeto na mão, legenda na cabeça): achar a fala, espelhar clipes
+ * sobre ela, ordenar as faixas por papel e converter "o estalo", "quando eu
+ * falar camadas" ou um quadro em SEGUNDO DA ORIGEM.
+ *
+ * ── POR QUE TUDO MORA EM SEGUNDO DA ORIGEM ───────────────────────────────
+ * O que se rastreia (a mão, a cabeça, o estalo) aconteceu na GRAVAÇÃO. Se a
+ * receita de um efeito guardasse quadro da timeline, o primeiro corte de
+ * silêncio a deixaria apontando para o lugar errado. Guardando o segundo da
+ * origem, o efeito é redesenhado em cima da timeline que existir — e a
+ * camada gerada entra "espelhando" os clipes da fala: o corte que pega a
+ * fala pega a camada no mesmo quadro.
+ *
+ * ── AS FAIXAS TÊM PAPEL ──────────────────────────────────────────────────
+ * De cima para baixo: textos, objetos 3D, o momento das camadas, a pessoa
+ * recortada, o fundo novo e, por baixo de tudo, a gravação (que segue
+ * levando o áudio). `arrumar` impõe essa ordem depois de cada operação, em
+ * qualquer ordem que o pedido venha.
+ */
+
+'use strict';
+
+const T = require('./timeline.js');
+
+const ORDEM = { objetos: 1, camadas3d: 2, pessoa: 3, fundo: 4 };
+
+/** A gravação: a mídia de vídeo pedida, ou a primeira com áudio que está na timeline. */
+function base(tl, ref) {
+    if (ref) {
+        const a = T.acharAsset(tl, ref);
+        if (a.kind !== 'video' || a.gerado) throw T.erro(`a mídia ${a.id} não é uma gravação de vídeo`);
+        return a;
+    }
+    const usados = new Set(clipesBase(tl).map((c) => c.asset));
+    const lista = Object.values(tl.assets).filter((a) => a.kind === 'video' && !a.gerado && usados.has(a.id));
+    const achada = lista.find((a) => a.hasAudio) || lista[0];
+    if (!achada) throw T.erro('não há gravação de vídeo na timeline: comece com import {"path":"..."}');
+    return achada;
+}
+
+/** Os clipes da gravação "de verdade": faixa de vídeo sem papel. */
+function clipesBase(tl, assetId) {
+    const out = [];
+    for (const t of tl.tracks) {
+        if (t.type !== 'video' || t.role) continue;
+        for (const c of t.clips) if (c.type === 'video' && (!assetId || c.asset === assetId) && !(tl.assets[c.asset] || {}).gerado) out.push(c);
+    }
+    return out.sort((a, b) => a.startFrame - b.startFrame);
+}
+
+/** Quadro da timeline → segundo da origem da gravação (ou null fora dela). */
+function quadroParaOrigem(tl, assetId, f) {
+    for (const c of clipesBase(tl, assetId)) {
+        if (f >= c.startFrame && f < T.fim(c)) return T.segundos(tl, c.trimStartFrame + (f - c.startFrame) * (c.speed || 1));
+    }
+    return null;
+}
+
+/** Segundo da origem → quadro da timeline (null se o trecho foi cortado). */
+function origemParaQuadro(tl, assetId, seg) {
+    for (const c of clipesBase(tl, assetId)) {
+        const f = T.origemParaQuadro(tl, c, seg);
+        if (f !== null && f < T.fim(c)) return f;
+    }
+    // O fim exato da gravação (o "até o fim") cai no fim do último clipe.
+    const ult = clipesBase(tl, assetId).slice(-1)[0];
+    if (ult && Math.abs(T.janelaOrigem(tl, ult).ate - seg) < 0.5 / tl.fps) return T.fim(ult);
+    return null;
+}
+
+/** O clipe da gravação que está no quadro f (para saber o encaixe na tela). */
+function clipeNoQuadro(tl, assetId, f) {
+    return clipesBase(tl, assetId).find((c) => f >= c.startFrame && f < T.fim(c)) || null;
+}
+
+function arrumar(tl) {
+    const rank = (t) => (t.type === 'text' ? 0 : t.type === 'audio' ? 9 : ORDEM[t.role] || 5);
+    tl.tracks = tl.tracks.map((t, i) => ({ t, i })).sort((a, b) => rank(a.t) - rank(b.t) || a.i - b.i).map((x) => x.t);
+    return tl;
+}
+
+/** A faixa com aquele papel (cria se não houver). Devolve o índice já na ordem certa. */
+function faixa(tl, papel) {
+    let t = tl.tracks.find((x) => x.role === papel);
+    if (!t) {
+        const i = T.faixaPara(tl, 'video', 'new');
+        t = tl.tracks[i];
+        t.role = papel;
+    }
+    arrumar(tl);
+    return tl.tracks.indexOf(t);
+}
+
+/** Tira os clipes de um papel (de uma gravação), e a faixa se esvaziar. */
+function limparPapel(tl, papel, assetId) {
+    for (const t of tl.tracks) {
+        if (t.role !== papel) continue;
+        t.clips = t.clips.filter((c) => assetId && c.base !== assetId);
+    }
+    tl.tracks = tl.tracks.filter((t) => t.role !== papel || t.clips.length);
+}
+
+/** Apaga os assets gerados que nenhum clipe usa mais. */
+function limparGerados(tl) {
+    const usados = new Set(T.todosOsClipes(tl).map((x) => x.clip.asset));
+    for (const [id, a] of Object.entries(tl.assets)) if (a.gerado && !usados.has(id)) delete tl.assets[id];
+}
+
+/**
+ * Cria, na faixa `ti`, um clipe por clipe da gravação que cai em [de, ate)
+ * (segundos da origem), no MESMO lugar da timeline. `asset`: a mídia do
+ * clipe novo; `origemDe`: o segundo da gravação que corresponde ao 0 dela
+ * (a própria gravação: 0; uma camada gerada a partir de `de`: `de`).
+ */
+function espelhar(tl, assetId, ti, { de = 0, ate = Infinity, asset = assetId, origemDe = 0, props = {}, papel } = {}) {
+    const criados = [];
+    for (const c of clipesBase(tl, assetId)) {
+        const j = T.janelaOrigem(tl, c);
+        const i0 = Math.max(j.de, de);
+        const i1 = Math.min(j.ate, ate);
+        if (i1 - i0 < 0.5 / tl.fps) continue;
+        const s = T.origemParaQuadro(tl, c, i0);
+        const e = Math.min(T.fim(c), T.origemParaQuadro(tl, c, i1));
+        if (s === null || e === null || e <= s) continue;
+        const o = s - c.startFrame;
+        const kf = {};
+        for (const [k, keys] of Object.entries(c.keyframes || {})) if (k !== 'volume') kf[k] = keys.map((x) => ({ ...x, frame: x.frame - o }));
+        const novo = T.clipe(tl, {
+            type: 'video', asset, startFrame: s, durationFrames: e - s,
+            trimStartFrame: Math.max(0, Math.round((i0 - origemDe) * tl.fps)), speed: c.speed,
+            transform: { ...c.transform }, crop: { ...c.crop }, fit: c.fit, volume: 0, ...props,
+        });
+        novo.keyframes = kf;
+        novo.base = assetId;
+        if (papel) novo.papel = papel;
+        tl.tracks[ti].clips.push(novo);
+        criados.push(novo);
+    }
+    T.ordenar(tl);
+    return criados;
+}
+
+// ── os momentos ──────────────────────────────────────────────────────────
+
+const sem = (s) => String(s || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+
+/** A primeira palavra da transcrição que casa (sem acento, sem espaço: "chat gpt" casa "chatgpt"). */
+function acharPalavra(palavras, alvo, { desde = 0 } = {}) {
+    const a = sem(alvo);
+    if (!a) return null;
+    for (let i = 0; i < palavras.length; i++) {
+        const p = palavras[i];
+        if (p.de < desde) continue;
+        const um = sem(p.texto);
+        const dois = um + sem((palavras[i + 1] || {}).texto);
+        if (um.startsWith(a) || (a.length > 4 && um.length >= 4 && a.startsWith(um) && dois.startsWith(a))) return p;
+    }
+    return null;
+}
+
+/** Cor por nome (português ou inglês) → hex. Hex passa direto. */
+const CORES = {
+    azul: '#2F80FF', blue: '#2F80FF', 'azul claro': '#5AC8FA', ciano: '#22D3EE', cyan: '#22D3EE',
+    vermelho: '#EF4444', vermelha: '#EF4444', red: '#EF4444', verde: '#22C55E', green: '#22C55E',
+    amarelo: '#FFD400', amarela: '#FFD400', yellow: '#FFD400', laranja: '#FF8A00', orange: '#FF8A00',
+    rosa: '#FF4FA3', pink: '#FF4FA3', roxo: '#8B5CF6', roxa: '#8B5CF6', purple: '#8B5CF6', lilas: '#C084FC',
+    branco: '#FFFFFF', branca: '#FFFFFF', white: '#FFFFFF', preto: '#000000', preta: '#000000', black: '#000000',
+    dourado: '#F5C542', dourada: '#F5C542', gold: '#F5C542', cinza: '#9CA3AF', gray: '#9CA3AF',
+};
+function cor(nome) {
+    if (nome === undefined || nome === null) return undefined;
+    const s = String(nome).trim();
+    if (/^#?[0-9a-f]{6}$/i.test(s)) return s.startsWith('#') ? s.toUpperCase() : '#' + s.toUpperCase();
+    const k = s.normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase();
+    if (CORES[k]) return CORES[k];
+    throw T.erro(`cor "${nome}" (use #RRGGBB ou azul/vermelho/verde/amarelo/laranja/rosa/roxo/ciano/branco/preto/dourado/cinza)`);
+}
+
+/** Fundo pedido por palavra → termo de busca que acha foto boa (o acervo é em inglês). */
+const FUNDOS = {
+    praia: 'tropical beach turquoise sea', beach: 'tropical beach turquoise sea', mar: 'ocean waves', espaco: 'outer space nebula stars',
+    space: 'outer space nebula stars', cidade: 'city skyline night', floresta: 'green forest', montanha: 'mountain landscape',
+    escritorio: 'modern office interior', deserto: 'desert dunes', neve: 'snowy mountains', estudio: 'dark studio backdrop',
+    paris: 'paris eiffel tower', 'nova york': 'new york skyline', por_do_sol: 'sunset sky', 'por do sol': 'sunset sky',
+};
+function termoDeFundo(pedido) {
+    const k = String(pedido || '').normalize('NFD').replace(/[̀-ͯ]/g, '').toLowerCase().trim();
+    return FUNDOS[k] || FUNDOS[k.replace(/^(uma?|o|a|na|no|numa|num)\s+/, '')] || k;
+}
+
+/** Objeto pedido → modelo do fx3d/modelos.jsx. */
+function modeloDe(nome) {
+    const k = sem(nome);
+    if (/^(chatgpt|gpt|openai|chat)/.test(k)) return 'chatgpt';
+    if (/^(claude|claud|anthropic)/.test(k)) return 'claude';
+    if (/^(brain|cerebro)/.test(k)) return 'cerebro';
+    if (/^(chrome|google ?chrome|navegador)/.test(k)) return 'chrome';
+    if (/^(drive|google ?drive)/.test(k)) return 'drive';
+    if (/^(foguete|rocket|nave)/.test(k)) return 'foguete';
+    return null;
+}
+
+module.exports = {
+    ORDEM, base, clipesBase, quadroParaOrigem, origemParaQuadro, clipeNoQuadro, arrumar, faixa, limparPapel, limparGerados,
+    espelhar, acharPalavra, sem, cor, CORES, termoDeFundo, FUNDOS, modeloDe,
+};

package/lib/video/cli.js

@@ -52,7 +52,7 @@ async function main(argv, { out = process.stdout, err = process.stderr } = {}) {
     try {
         const { op, args } = lerArgs(argv);
         if (!op || op === 'help' || op === '--help' || op === '-h') {
-            out.write(ajuda() + '\n');
+            out.write(ajuda(argv[1]) + '\n');
             return 0;
         }
         const nome = ALIAS[op] || op;

package/lib/video/filters.js

@@ -100,6 +100,27 @@ const EFEITOS = {
         params: 'color (hex, #00FF00), similarity (0.12), blend (0.08)',
         filtro: (p) => ['format=yuva420p', `chromakey=${String(p.color || '#00FF00').replace('#', '0x')}:${num(p.similarity || 0.12)}:${num(p.blend || 0.08)}`],
     },
+    /* A pessoa recortada: a máscara (studio/rastrear.py) entra como uma
+       segunda entrada, cortada no MESMO trecho do clipe, e vira o alfa
+       (alphamerge) antes de qualquer outro filtro — ver montarGrafo. Aqui
+       só ficam os números: `choke` encolhe a borda (px), `feather` a suaviza. */
+    'key.matte': {
+        params: 'matte (arquivo, posto pelo separate_layers), choke (0..4, 1), feather (0..6, 1.2)',
+        filtro: () => [],
+        cadeiaDaMascara(p) {
+            const f = ['format=gray'];
+            for (let i = 0; i < Math.round(lim(p.choke ?? 1, 0, 4)); i++) f.push('erosion');
+            const fe = lim(p.feather ?? 1.2, 0, 6);
+            if (fe > 0) f.push(`gblur=sigma=${num(fe)}`);
+            return f;
+        },
+    },
+    /* A pessoa no fundo novo: um empurrão leve da cor dela para a luz do
+       fundo (ganho por canal perto de 1) — o "colado" some sem mudar a pele. */
+    'color.match': {
+        params: 'r g b (ganho por canal, 0.85..1.15), medido pelo replace_background',
+        filtro: (p) => [`colorchannelmixer=rr=${num(lim(p.r ?? 1, 0.85, 1.15))}:gg=${num(lim(p.g ?? 1, 0.85, 1.15))}:bb=${num(lim(p.b ?? 1, 0.85, 1.15))}`],
+    },
 };
 
 function filtrosDoEfeito(e) {
@@ -145,7 +166,7 @@ function atempo(speed) {
  * Monta tudo. `camadasDeTexto`: {índiceDaFaixa: caminho do .ffconcat}.
  * `escala`: 0.5 para prévia. Devolve {inputs, grafo, saidaV, saidaA, segundos}.
  */
-function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio = true } = {}) {
+function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio = true, video = true } = {}) {
     const ate = to === undefined ? T.duracao(tl) : Math.min(to, T.duracao(tl));
     if (!(ate > from)) throw T.erro('nada para renderizar nesse trecho');
     const fps = tl.fps;
@@ -161,7 +182,7 @@ function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio
     for (let ti = tl.tracks.length - 1; ti >= 0; ti--) {
         const faixa = tl.tracks[ti];
         if (faixa.type === 'text') {
-            const arq = camadasDeTexto[ti];
+            const arq = video ? camadasDeTexto[ti] : null;
             if (!arq || faixa.hidden) continue;
             const k = inputs.length;
             inputs.push(['-f', 'concat', '-safe', '0', '-i', arq]);
@@ -177,13 +198,17 @@ function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio
             if (!a) continue;
             const speed = c.speed || 1;
             const temSom = a.kind === 'audio' || (a.kind === 'video' && a.hasAudio);
-            const visivel = faixa.type === 'video' && !c.hidden && !faixa.hidden;
+            // video:false — só o áudio (o export em partes faz o som numa passada à parte).
+            const visivel = video && faixa.type === 'video' && !c.hidden && !faixa.hidden;
             if (!visivel && !(audio && temSom)) continue;
             const k = inputs.length;
             const startS = j.start / fps;
             const durS = j.dur / fps;
             if (a.kind === 'image') inputs.push(['-loop', '1', '-framerate', String(fps), '-t', num(durS), '-i', a.path]);
             else inputs.push(['-ss', num(j.trim / fps), '-t', num(durS * speed + 0.05), '-i', a.path]);
+            const matte = visivel && c.effects.find((e) => e.type === 'key.matte' && e.params && e.params.matte);
+            let km = null;
+            if (matte) { km = inputs.length; inputs.push(['-ss', num(j.trim / fps), '-t', num(durS * speed + 0.05), '-i', matte.params.matte]); }
             const X = `on/${fps}+${num(j.corte / fps)}`;          // tempo do clipe, dentro do zoompan
             const Xt = `t+${num(j.corte / fps)}`;                   // tempo do clipe, nos filtros com t local
             const Xo = `(t-${num(startS)})+${num(j.corte / fps)}`;  // tempo do clipe, no overlay (t global)
@@ -210,7 +235,13 @@ function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio
                 const rot = expressao(c.keyframes.rotation, Xt, fps) || (c.transform.rotation ? num(c.transform.rotation) : null);
                 if (rot) f.push(`rotate=a='(${rot})*PI/180':c=none:ow='hypot(iw,ih)':oh='ow'`);
                 f.push(`setpts=PTS+${num(startS)}/TB`);
-                linhas.push(`[${k}:v]${f.join(',')}[c${k}]`);
+                if (km !== null) {
+                    // O alfa vem da máscara, no mesmo tempo e no mesmo tamanho da origem.
+                    const pre = f.splice(0, 2);
+                    linhas.push(`[${k}:v]${pre.join(',')}[pre${k}]`);
+                    linhas.push(`[${km}:v]${[...EFEITOS['key.matte'].cadeiaDaMascara(matte.params), ...pre].join(',')}[mt${k}]`);
+                    linhas.push(`[pre${k}][mt${k}]alphamerge,${f.join(',')}[c${k}]`);
+                } else linhas.push(`[${k}:v]${f.join(',')}[c${k}]`);
                 const cx = expressao(c.keyframes.cx, Xo, fps) || num(c.transform.cx);
                 const cy = expressao(c.keyframes.cy, Xo, fps) || num(c.transform.cy);
                 const fimS = (j.start + j.dur) / fps;
@@ -234,14 +265,16 @@ function montarGrafo(tl, { from = 0, to, camadasDeTexto = {}, escala = 1, audio
         }
     }
 
-    linhas.push(`[${atual}]format=yuv420p[vout]`);
+    // Só o áudio: o vídeo (uma cor preta) termina num ralo — saída solta derruba o ffmpeg.
+    if (!video) linhas.push(`[${atual}]nullsink`);
+    else linhas.push(`[${atual}]format=yuv420p[vout]`);
     if (!audio) return { inputs, grafo: linhas.join(';\n'), saidaV: '[vout]', saidaA: null, segundos: D, W, H };
     if (audios.length) {
         linhas.push(`${audios.join('')}amix=inputs=${audios.length}:duration=longest:dropout_transition=0:normalize=0,apad,atrim=0:${num(D)}[aout]`);
     } else {
         linhas.push(`anullsrc=r=48000:cl=stereo,atrim=0:${num(D)}[aout]`);
     }
-    return { inputs, grafo: linhas.join(';\n'), saidaV: '[vout]', saidaA: '[aout]', segundos: D, W, H };
+    return { inputs, grafo: linhas.join(';\n'), saidaV: video ? '[vout]' : null, saidaA: '[aout]', segundos: D, W, H };
 }
 
 module.exports = { num, expressao, EFEITOS, PRESETS_COR, CURVAS, filtrosDoEfeito, efeitoDeCor, naJanela, atempo, montarGrafo };