primocode 9.9.0 → 10.0.0

package/lib/video/filters.js

@@ -0,0 +1,247 @@
+/**
+ * filters.js — a linha do tempo vira UM filter_complex do ffmpeg.
+ *
+ * É uma função pura: entra o json, sai a lista de entradas e o texto do
+ * grafo. Quem roda é o render.js. Separado assim, o grafo inteiro é testável
+ * como string, sem ffmpeg na máquina de teste.
+ *
+ * ── COMO O GRAFO É MONTADO ───────────────────────────────────────────────
+ *   · um fundo preto do tamanho do projeto;
+ *   · cada clipe visual, da faixa de BAIXO para a de cima, entra como uma
+ *     entrada própria já cortada na origem (-ss/-t na entrada, que é o corte
+ *     rápido e exato), passa pela cadeia dele (velocidade, recorte, encaixe,
+ *     zoom, efeitos, opacidade, fade, giro) e é sobreposto na posição;
+ *   · cada faixa de TEXTO entra como uma sequência de PNGs transparentes (o
+ *     texto.js decide os estados, o studio/texto.py desenha) e cobre a tela
+ *     inteira — uma entrada por faixa, não uma por legenda;
+ *   · o áudio de cada clipe atrasa até o lugar dele e tudo vira um amix.
+ *
+ * ── POR QUE O ZOOM É zoompan E NÃO scale ─────────────────────────────────
+ * Um scale animado muda o TAMANHO do quadro no meio do fluxo, e o overlay
+ * não aceita isso. O zoompan devolve sempre o mesmo tamanho e aproxima por
+ * dentro — que é exatamente o "punch-in" de quem edita fala para a câmera.
+ */
+
+'use strict';
+
+const T = require('./timeline.js');
+
+// ── números e expressões ─────────────────────────────────────────────────
+
+function num(n) {
+    const s = Number(n).toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
+    return s === '-0' ? '0' : s;
+}
+
+/**
+ * Keyframes → expressão do ffmpeg, em função do tempo `X` (segundos desde
+ * o começo do clipe). Antes do primeiro vale o primeiro; depois do último,
+ * o último.
+ */
+function expressao(keys, X, fps) {
+    if (!keys || !keys.length) return null;
+    const ks = keys.map((k) => ({ t: k.frame / fps, v: k.value, i: k.interp || 'ease' }));
+    let e = num(ks[ks.length - 1].v);
+    for (let j = ks.length - 2; j >= 0; j--) {
+        const a = ks[j];
+        const b = ks[j + 1];
+        const dt = Math.max(1e-6, b.t - a.t);
+        const p = `((${X})-${num(a.t)})/${num(dt)}`;
+        const curva = a.i === 'hold' ? '0' : a.i === 'linear' ? p : `(${p})*(${p})*(3-2*(${p}))`;
+        const seg = a.i === 'hold' ? num(a.v) : `${num(a.v)}+(${num(b.v - a.v)})*${curva}`;
+        e = `if(lt(${X},${num(b.t)}),${seg},${e})`;
+    }
+    return `if(lt(${X},${num(ks[0].t)}),${num(ks[0].v)},${e})`;
+}
+
+// ── efeitos ──────────────────────────────────────────────────────────────
+
+const PRESETS_COR = {
+    warm: { temperature: 0.35, saturation: 0.1 },
+    cool: { temperature: -0.35, saturation: 0.05 },
+    cinematic: { contrast: 0.18, saturation: -0.2, temperature: 0.12, curves: 'medium_contrast' },
+    punchy: { contrast: 0.2, saturation: 0.35 },
+    bw: { saturation: -1, contrast: 0.15 },
+    vintage: { curves: 'vintage', saturation: -0.15 },
+    bright: { exposure: 0.25, gamma: 1.1 },
+};
+
+const CURVAS = ['color_negative', 'cross_process', 'darker', 'increase_contrast', 'lighter', 'linear_contrast', 'medium_contrast', 'negative', 'strong_contrast', 'vintage'];
+
+const lim = (v, a, b) => Math.max(a, Math.min(b, Number(v)));
+
+// Cada efeito: parâmetros com padrão → os filtros do ffmpeg.
+const EFEITOS = {
+    'color.adjust': {
+        params: 'exposure contrast saturation temperature tint (-1..1), gamma (0.1..3), curves',
+        filtro(p) {
+            const f = [];
+            const eq = [];
+            if (p.exposure) eq.push(`brightness=${num(lim(p.exposure, -1, 1) * 0.3)}`);
+            if (p.contrast) eq.push(`contrast=${num(1 + lim(p.contrast, -1, 1))}`);
+            if (p.saturation) eq.push(`saturation=${num(1 + lim(p.saturation, -1, 2))}`);
+            if (p.gamma && Number(p.gamma) !== 1) eq.push(`gamma=${num(lim(p.gamma, 0.1, 3))}`);
+            if (eq.length) f.push('eq=' + eq.join(':'));
+            const t = lim(p.temperature || 0, -1, 1) * 0.25;
+            const g = lim(p.tint || 0, -1, 1) * -0.2;
+            if (t || g) f.push(`colorbalance=rs=${num(t)}:gs=${num(g)}:bs=${num(-t)}:rm=${num(t)}:gm=${num(g)}:bm=${num(-t)}`);
+            if (p.curves) {
+                if (!CURVAS.includes(p.curves)) throw T.erro(`curves "${p.curves}" (use ${CURVAS.join('/')})`);
+                f.push(`curves=preset=${p.curves}`);
+            }
+            return f;
+        },
+    },
+    'blur.gaussian': { params: 'sigma (px, 8)', filtro: (p) => [`gblur=sigma=${num(lim(p.sigma != null ? p.sigma : 8, 0.1, 200))}`] },
+    sharpen: { params: 'amount (0..3, 1)', filtro: (p) => [`unsharp=5:5:${num(lim(p.amount != null ? p.amount : 1, 0, 3))}`] },
+    'stylize.vignette': { params: 'strength (0..1, 0.5)', filtro: (p) => [`vignette=angle=${num(0.25 + 0.9 * lim(p.strength !== undefined ? p.strength : 0.5, 0, 1))}`] },
+    'stylize.grain': { params: 'strength (0..1, 0.3)', filtro: (p) => [`noise=alls=${Math.round(lim(p.strength != null ? p.strength : 0.3, 0, 1) * 40)}:allf=t+u`] },
+    'key.chroma': {
+        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)}`],
+    },
+};
+
+function filtrosDoEfeito(e) {
+    const def = EFEITOS[e.type];
+    if (!def) throw T.erro(`efeito "${e.type}" não existe (use ${Object.keys(EFEITOS).join('/')})`);
+    return def.filtro(e.params || {});
+}
+
+/** apply_color → o efeito color.adjust (preset + ajustes por cima). */
+function efeitoDeCor(args) {
+    const base = args.preset ? PRESETS_COR[args.preset] : {};
+    if (args.preset && !base) throw T.erro(`preset "${args.preset}" (use ${Object.keys(PRESETS_COR).join('/')})`);
+    const params = { ...base };
+    for (const k of ['exposure', 'contrast', 'saturation', 'temperature', 'tint', 'gamma', 'curves']) {
+        if (args[k] !== undefined) params[k] = args[k];
+    }
+    filtrosDoEfeito({ type: 'color.adjust', params });   // valida já
+    return { type: 'color.adjust', params };
+}
+
+// ── o grafo ──────────────────────────────────────────────────────────────
+
+/** O pedaço do clipe que cai na janela [from, to) — ou null. */
+function naJanela(c, from, to) {
+    const s = Math.max(c.startFrame, from);
+    const e = Math.min(T.fim(c), to);
+    if (e <= s) return null;
+    const corte = s - c.startFrame;
+    return { start: s - from, dur: e - s, corte, trim: c.trimStartFrame + Math.round(corte * (c.speed || 1)) };
+}
+
+function atempo(speed) {
+    // atempo aceita 0.5..2 por filtro: acima disso, em cadeia.
+    const f = [];
+    let s = speed;
+    while (s > 2) { f.push('atempo=2'); s /= 2; }
+    while (s < 0.5) { f.push('atempo=0.5'); s /= 0.5; }
+    if (Math.abs(s - 1) > 1e-6) f.push(`atempo=${num(s)}`);
+    return f;
+}
+
+/**
+ * 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 } = {}) {
+    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;
+    const W = T.par(tl.width * escala);
+    const H = T.par(tl.height * escala);
+    const D = (ate - from) / fps;
+    const inputs = [];
+    const linhas = [`color=c=black:s=${W}x${H}:r=${fps}:d=${num(D)}[base]`];
+    const audios = [];
+    let atual = 'base';
+    let n = 0;
+
+    for (let ti = tl.tracks.length - 1; ti >= 0; ti--) {
+        const faixa = tl.tracks[ti];
+        if (faixa.type === 'text') {
+            const arq = camadasDeTexto[ti];
+            if (!arq || faixa.hidden) continue;
+            const k = inputs.length;
+            inputs.push(['-f', 'concat', '-safe', '0', '-i', arq]);
+            linhas.push(`[${k}:v]fps=${fps},format=rgba,setpts=PTS-STARTPTS[tx${k}]`);
+            linhas.push(`[${atual}][tx${k}]overlay=0:0:eof_action=pass[v${++n}]`);
+            atual = `v${n}`;
+            continue;
+        }
+        for (const c of faixa.clips) {
+            const j = naJanela(c, from, ate);
+            if (!j) continue;
+            const a = tl.assets[c.asset];
+            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;
+            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 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)
+
+            if (visivel) {
+                const bw = T.par(c.transform.w * W);
+                const bh = T.par(c.transform.h * H);
+                const f = [speed !== 1 ? `setpts=(PTS-STARTPTS)/${num(speed)}` : 'setpts=PTS-STARTPTS', `fps=${fps}`];
+                const cr = c.crop;
+                if (cr.l || cr.t || cr.r || cr.b) f.push(`crop=iw*${num(1 - cr.l - cr.r)}:ih*${num(1 - cr.t - cr.b)}:iw*${num(cr.l)}:ih*${num(cr.t)}`);
+                if (c.fit === 'contain') f.push(`scale=${bw}:${bh}:force_original_aspect_ratio=decrease`, 'format=yuva420p', `pad=${bw}:${bh}:(ow-iw)/2:(oh-ih)/2:color=black@0`);
+                else if (c.fit === 'stretch') f.push(`scale=${bw}:${bh}`);
+                else f.push(`scale=${bw}:${bh}:force_original_aspect_ratio=increase`, `crop=${bw}:${bh}`);
+                f.push('setsar=1');
+                const zoom = expressao(c.keyframes.zoom, X, fps);
+                if (zoom) f.push(`zoompan=z='max(1,${zoom})':x='iw/2-(iw/zoom/2)':y='ih/2-(ih/zoom/2)':d=1:s=${bw}x${bh}:fps=${fps}`);
+                for (const e of c.effects) f.push(...filtrosDoEfeito(e));
+                f.push('format=yuva420p');
+                const op = expressao(c.keyframes.opacity, Xt, fps);
+                if (op) f.push('format=rgba', `geq=r='r(X,Y)':g='g(X,Y)':b='b(X,Y)':a='alpha(X,Y)*max(0,min(1,${op}))'`);
+                else if (c.opacity < 1) f.push(`colorchannelmixer=aa=${num(Math.max(0, c.opacity))}`);
+                if (c.fadeIn && j.corte === 0) f.push(`fade=t=in:st=0:d=${num(c.fadeIn / fps)}:alpha=1`);
+                if (c.fadeOut && j.start + j.dur + from === T.fim(c)) f.push(`fade=t=out:st=${num(Math.max(0, durS - c.fadeOut / fps))}:d=${num(c.fadeOut / fps)}:alpha=1`);
+                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}]`);
+                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;
+                linhas.push(`[${atual}][c${k}]overlay=x='(${cx})*W-w/2':y='(${cy})*H-h/2':eof_action=pass:enable='between(t,${num(startS)},${num(fimS - 0.0001)})'[v${++n}]`);
+                atual = `v${n}`;
+            }
+
+            if (audio && temSom && !faixa.muted && !(c.volume === 0 && !c.keyframes.volume)) {
+                const f = ['asetpts=PTS-STARTPTS', ...atempo(speed), 'aformat=sample_rates=48000:channel_layouts=stereo'];
+                const vol = expressao(c.keyframes.volume, Xt, fps);
+                if (vol) f.push(`volume='max(0,${vol})':eval=frame`);
+                else if (c.volume !== 1) f.push(`volume=${num(c.volume)}`);
+                if (c.fadeIn && j.corte === 0) f.push(`afade=t=in:st=0:d=${num(c.fadeIn / fps)}`);
+                if (c.fadeOut && j.start + j.dur + from === T.fim(c)) f.push(`afade=t=out:st=${num(Math.max(0, durS - c.fadeOut / fps))}:d=${num(c.fadeOut / fps)}`);
+                f.push(`atrim=0:${num(durS)}`);
+                const ms = Math.round(startS * 1000);
+                if (ms > 0) f.push(`adelay=${ms}:all=1`);
+                linhas.push(`[${k}:a]${f.join(',')}[a${k}]`);
+                audios.push(`[a${k}]`);
+            }
+        }
+    }
+
+    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 };
+}
+
+module.exports = { num, expressao, EFEITOS, PRESETS_COR, CURVAS, filtrosDoEfeito, efeitoDeCor, naJanela, atempo, montarGrafo };

package/lib/video/ops.js

@@ -0,0 +1,322 @@
+/**
+ * ops.js — as operações do editor, uma por nome, com o texto de ajuda junto.
+ *
+ * O texto de ajuda mora AO LADO da operação de propósito: é ele que o modelo
+ * lê (`primocode video help`) para saber o que existe, e ajuda escrita
+ * noutro arquivo envelhece diferente do código. Cada linha é curta, com a
+ * unidade de cada número — quadro na linha do tempo, segundo na origem.
+ *
+ * Toda operação que MUDA o projeto passa por `mutar`: foto de antes, edição,
+ * validação, gravação, delta. Se qualquer passo falha, nada é gravado — um
+ * add_clips de dez clipes com um errado não deixa nove pela metade.
+ */
+
+'use strict';
+
+const T = require('./timeline.js');
+const E = require('./edits.js');
+const F = require('./filters.js');
+const { diff } = require('./delta.js');
+const P = require('./projeto.js');
+const TR = require('./transcript.js');
+const A = require('./analise.js');
+
+const r = () => require('./render.js');   // só carrega o ffmpeg quando precisa
+
+const lista = (v) => (v === undefined ? [] : Array.isArray(v) ? v : [v]);
+
+/** Os clipes que a operação pediu: ids, id, ou "all" (todos os visuais). */
+function alvos(tl, args, { tipos = ['video', 'image'] } = {}) {
+    const refs = lista(args.ids !== undefined ? args.ids : args.id);
+    if (!refs.length) throw T.erro('faltou "ids" (ou "all")');
+    if (refs.length === 1 && (refs[0] === 'all' || refs[0] === '*')) {
+        return T.todosOsClipes(tl).filter((x) => tipos.includes(x.clip.type)).map((x) => x.clip.id);
+    }
+    return refs.map((ref) => T.achar(tl, ref).clip.id);
+}
+
+async function mutar(ctx, op, fn) {
+    const antes = T.clone(ctx.tl);
+    const extra = (await fn(ctx.tl)) || {};
+    T.ordenar(ctx.tl);
+    const probs = T.problemas(ctx.tl);
+    if (probs.length) throw T.erro(`edição recusada (nada mudou): ${probs.slice(0, 4).join('; ')}`);
+    P.fotografar(ctx.p, antes, op);
+    P.salvar(ctx.p, ctx.tl);
+    const d = diff(antes, ctx.tl, extra);
+    P.anotar(ctx.p, op, { dur: d.dur, added: (d.added || []).length, removed: (d.removed || []).length });
+    return d;
+}
+
+function precisaProjeto(ctx) {
+    if (!ctx.tl) throw T.erro('nenhum projeto aberto: comece com import {"path":"..."} (cria o projeto) ou new');
+}
+
+// ── as operações ─────────────────────────────────────────────────────────
+
+const OPS = {
+    new: {
+        uso: 'new {name?,width?:1080,height?:1920,fps?:30} — cria projeto em ./video/<id>/ e o torna atual',
+        async run(ctx, a) {
+            const { p, tl } = P.criar({ nome: a.name, width: a.width, height: a.height, fps: a.fps });
+            return { ok: true, project: p.id, dir: p.dir, fps: tl.fps, size: `${tl.width}x${tl.height}` };
+        },
+    },
+    open: {
+        uso: 'open {id} | list {} — troca de projeto / lista os projetos desta pasta',
+        async run(ctx, a) {
+            const x = P.abrir(a.id);
+            if (!x) throw T.erro(`não há projeto "${a.id}"`);
+            P.usar(x.p.id);
+            return { ok: true, project: x.p.id, ...T.vista(x.tl) };
+        },
+    },
+    list: { oculto: true, async run() { return { ok: true, current: P.atual(), projects: P.listar() }; } },
+    import: {
+        uso: 'import {path|paths[],track?,at?,from?,to?,noClip?} — mídia vira asset + clipe no fim da faixa (sem projeto, cria um do tamanho do vídeo)',
+        async run(ctx, a) {
+            const caminhos = lista(a.paths || a.path);
+            if (!caminhos.length) throw T.erro('faltou "path"');
+            if (!ctx.tl) {
+                const probe = await r().medirAsset(T.novo(), caminhos[0]);
+                const vert = probe.width && probe.height;
+                const x = P.criar({ nome: a.name || probe.nome.replace(/\.[^.]+$/, ''),
+                    width: a.width || (vert ? probe.width : 1080), height: a.height || (vert ? probe.height : 1920),
+                    fps: a.fps || (probe.fps ? Math.min(60, Math.round(probe.fps)) : 30) });
+                Object.assign(ctx, x);
+            }
+            const medidos = [];
+            for (const c of caminhos) medidos.push(await r().medirAsset(ctx.tl, c));
+            return mutar(ctx, 'import', (tl) => {
+                for (const m of medidos) {
+                    m.id = T.novoAssetId(tl);
+                    tl.assets[m.id] = m;
+                    if (!a.noClip) E.adicionar(tl, { asset: m.id, track: a.track, at: a.at, from: a.from, to: a.to });
+                }
+                return { project: ctx.p.id };
+            });
+        },
+    },
+    get_timeline: {
+        uso: 'get_timeline {from?,to?} — o projeto compacto (só o que não é padrão). src=[s,s] segundos da origem',
+        async run(ctx, a) { precisaProjeto(ctx); return { ok: true, project: ctx.p.id, ...T.vista(ctx.tl, a) }; },
+    },
+    inspect: {
+        uso: 'inspect {frames:[f..]|at:f} — renderiza os quadros com grade 0–1 + nº do quadro numa folha PNG (abra e OLHE)',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const d = T.duracao(ctx.tl);
+            const frames = a.frames ? lista(a.frames) : a.at !== undefined ? [a.at] : [0, Math.floor(d / 2), d - 1];
+            return r().inspecionar(ctx.p.dir, ctx.tl, { frames, escala: a.scale || 0.5, out: a.out });
+        },
+    },
+    get_transcript: {
+        uso: 'get_transcript {asset?,from?,to?,force?} — palavras [i,texto,f,e] em QUADROS da timeline atual; i é estável entre edições',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const asset = T.acharAsset(ctx.tl, a.asset);
+            const t = await TR.obter(ctx.p.dir, asset, { force: a.force, idioma: a.lang || 'pt' });
+            if (!t.ok) return t;
+            const mapa = TR.mapear(ctx.tl, asset.id, t.palavras)
+                .filter((w) => w.e > (a.from || 0) && w.f < (a.to === undefined ? Infinity : a.to));
+            return { ok: true, asset: asset.id, fonte: t.fonte, total: t.palavras.length, onTimeline: mapa.length, words: mapa.map((w) => [w.i, w.texto, w.f, w.e]) };
+        },
+    },
+    add_clips: {
+        uso: 'add_clips {clips:[{asset,track?,at?,from?,to?|dur?,...props}]} — lote atômico (tudo ou nada)',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            return mutar(ctx, 'add_clips', (tl) => { lista(a.clips).forEach((c) => E.adicionar(tl, c)); });
+        },
+    },
+    insert: {
+        uso: 'insert {asset|type:"text",at,from?,to?|dur?,track?,rippleTracks?} — insere empurrando tudo depois de at (ripple)',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'insert', (tl) => { E.inserir(tl, a); }); },
+    },
+    move: {
+        uso: 'move {id,to?(quadro),track?(índice|"new")} — move sem ripple (sobrepor na mesma faixa é recusado)',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'move', (tl) => { E.mover(tl, a.id, a); }); },
+    },
+    remove: {
+        uso: 'remove {ids,ripple?:false} — apaga clipes; ripple fecha o buraco se nenhuma faixa usa o trecho',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'remove', (tl) => { E.remover(tl, lista(a.ids || a.id), { ripple: a.ripple }); }); },
+    },
+    split: {
+        uso: 'split {id,at(quadro da timeline)} — divide em dois',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'split', (tl) => { E.dividir(tl, a.id, a.at); }); },
+    },
+    ripple_delete_ranges: {
+        uso: 'ripple_delete_ranges {ranges:[[de,ate],..](quadros, ate exclusivo),tracks?} — apaga trechos em todas as faixas e fecha',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            return mutar(ctx, 'ripple_delete_ranges', (tl) => E.apagarTrechos(tl, lista(a.ranges), { tracks: a.tracks }));
+        },
+    },
+    remove_silence: {
+        uso: 'remove_silence {asset?,threshold?:-35(dB),minSilence?:0.5(s),padding?:0.15(s),dryRun?} — silencedetect → ripple',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const asset = T.acharAsset(ctx.tl, a.asset);
+            const sil = await r().silenciosDe(ctx.p.dir, asset, { threshold: a.threshold ?? -35, minSilence: a.minSilence ?? 0.5 });
+            const clipes = T.todosOsClipes(ctx.tl).map((x) => x.clip).filter((c) => c.asset === asset.id);
+            const ranges = A.trechosDeSilencio(ctx.tl, clipes, { [asset.id]: sil }, { padding: a.padding ?? 0.15 });
+            if (a.dryRun) return { ok: true, silences: sil.length, ranges: E.juntar(ranges) };
+            return mutar(ctx, 'remove_silence', (tl) => ({ silences: sil.length, ...E.apagarTrechos(tl, ranges) }));
+        },
+    },
+    remove_words: {
+        uso: 'remove_words {words:[i..],asset?} — apaga as palavras (índices do get_transcript) com ripple',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const asset = T.acharAsset(ctx.tl, a.asset);
+            const t = await TR.obter(ctx.p.dir, asset);
+            if (!t.ok) return t;
+            const { ranges, faltou } = E.trechosDasPalavras(TR.mapear(ctx.tl, asset.id, t.palavras), lista(a.words));
+            if (!ranges.length) throw T.erro('nenhuma dessas palavras está na timeline');
+            return mutar(ctx, 'remove_words', (tl) => ({ ...E.apagarTrechos(tl, ranges), ...(faltou.length ? { notOnTimeline: faltou } : {}) }));
+        },
+    },
+    set_clip_properties: {
+        uso: 'set_clip_properties {ids|"all",props:{volume,opacity,speed,fadeIn,fadeOut(quadros),dur,cx,cy,w,h,rotation,crop{l,t,r,b},fit(cover|contain|stretch),hidden,content,style,animation}}',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            return mutar(ctx, 'set_clip_properties', (tl) => { E.propriedades(tl, alvos(tl, a, { tipos: ['video', 'image', 'audio', 'text'] }), a.props || {}); });
+        },
+    },
+    set_keyframes: {
+        uso: 'set_keyframes {id,prop(zoom|cx|cy|rotation|opacity|volume),keys:[{frame(timeline),value,interp?:ease|linear|hold}]} — keys:[] limpa',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'set_keyframes', (tl) => { E.keyframes(tl, a.id, a.prop, a.keys); }); },
+    },
+    apply_layout: {
+        uso: `apply_layout {layout(${E.LAYOUTS.join('|')}),ids:[principal,..],size?:0.34} — posiciona (transform 0–1)`,
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            return mutar(ctx, 'apply_layout', (tl) => { const av = E.layout(tl, a.layout, lista(a.ids), a); return av.length ? { avisos: av } : {}; });
+        },
+    },
+    add_texts: {
+        uso: 'add_texts {texts:[{content,at,dur(quadros),cx?,cy?,w?,animation?,style?}]} — títulos/letreiros',
+        async run(ctx, a) { precisaProjeto(ctx); return mutar(ctx, 'add_texts', (tl) => { E.textos(tl, lista(a.texts)); }); },
+    },
+    add_captions: {
+        uso: 'add_captions {asset?,maxWords?:3,animation?:highlightPop,cy?:0.72,style?} — legenda da transcrição, já nos cortes atuais (refazer substitui)',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const asset = T.acharAsset(ctx.tl, a.asset);
+            const t = await TR.obter(ctx.p.dir, asset);
+            if (!t.ok) return t;
+            return mutar(ctx, 'add_captions', (tl) => ({ captions: E.legendas(tl, TR.mapear(tl, asset.id, t.palavras), a).length }));
+        },
+    },
+    apply_color: {
+        uso: `apply_color {ids|"all",preset?(${Object.keys(F.PRESETS_COR).join('|')}),exposure,contrast,saturation,temperature,tint(-1..1),gamma}`,
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const ef = F.efeitoDeCor(a);
+            return mutar(ctx, 'apply_color', (tl) => {
+                for (const id of alvos(tl, a)) { const { clip } = T.achar(tl, id); clip.effects = clip.effects.filter((e) => e.type !== 'color.adjust').concat(ef); }
+            });
+        },
+    },
+    apply_effect: {
+        uso: `apply_effect {ids|"all",type(${Object.keys(F.EFEITOS).filter((k) => k !== 'color.adjust').join('|')}),params?,remove?:true}`,
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const ef = { type: a.type, params: a.params || {} };
+            if (!a.remove) F.filtrosDoEfeito(ef);
+            return mutar(ctx, 'apply_effect', (tl) => {
+                for (const id of alvos(tl, a)) {
+                    const { clip } = T.achar(tl, id);
+                    clip.effects = clip.effects.filter((e) => e.type !== a.type);
+                    if (!a.remove) clip.effects.push(ef);
+                }
+            });
+        },
+    },
+    detect_beats: {
+        uso: 'detect_beats {asset,sensitivity?:1.4,markers?:false} — batidas em quadros da timeline (+bpm); markers:true grava marcadores',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const asset = T.acharAsset(ctx.tl, a.asset);
+            const taxa = 22050;
+            const b = A.batidas(await r().amostras(asset.path, taxa), taxa, { sensibilidade: a.sensitivity || 1.4 });
+            const clipes = T.todosOsClipes(ctx.tl).map((x) => x.clip).filter((c) => c.asset === asset.id);
+            const quadros = clipes.length
+                ? [...new Set(clipes.flatMap((c) => b.beats.map((s) => T.origemParaQuadro(ctx.tl, c, s)).filter((f) => f !== null)))].sort((x, y) => x - y)
+                : b.beats.map((s) => T.quadros(ctx.tl, s));
+            const res = { bpm: b.bpm, count: quadros.length, beats: quadros.slice(0, 300) };
+            if (!a.markers) return { ok: true, ...res };
+            return mutar(ctx, 'detect_beats', (tl) => {
+                tl.markers = tl.markers.filter((m) => m.label !== 'beat').concat(quadros.map((f) => ({ frame: f, label: 'beat' })));
+                return res;
+            });
+        },
+    },
+    undo: {
+        uso: 'undo {steps?:1} — volta edições (cada edição guarda foto; edite sem pedir licença)',
+        async run(ctx, a) {
+            precisaProjeto(ctx);
+            const antes = ctx.tl;
+            const u = P.desfazer(ctx.p, a.steps || 1);
+            P.salvar(ctx.p, u.tl);
+            ctx.tl = u.tl;
+            return diff(antes, u.tl, { undone: u.desfeitas, left: u.restam });
+        },
+    },
+    export: {
+        uso: 'export {out?,from?,to?(quadros),preview?:false(meia resolução),crf?:20} — renderiza o mp4',
+        async run(ctx, a) { precisaProjeto(ctx); return r().exportar(ctx.p.dir, ctx.tl, a); },
+    },
+};
+
+const ALIAS = { timeline: 'get_timeline', transcript: 'get_transcript', captions: 'add_captions', texts: 'add_texts', render: 'export' };
+
+// Um exemplo por operação: o modelo copia a forma, e não inventa a chave.
+const EX = {
+    new: '{"name":"aula","width":1920,"height":1080,"fps":30}',
+    open: '{"id":"2026-09-29-aula"}',
+    import: '{"path":"gravacao.mp4"}',
+    get_timeline: '{"from":0,"to":300}',
+    inspect: '{"frames":[0,150,299]}',
+    get_transcript: '{"from":0,"to":600}',
+    add_clips: '{"clips":[{"asset":"a2","track":"new","at":90,"from":2.5,"to":6}]}',
+    insert: '{"asset":"a2","at":120,"from":0,"to":3}',
+    move: '{"id":"3f2a","to":240,"track":"new"}',
+    remove: '{"ids":["3f2a"],"ripple":true}',
+    split: '{"id":"3f2a","at":180}',
+    ripple_delete_ranges: '{"ranges":[[120,150],[400,410]]}',
+    remove_silence: '{"padding":0.12,"minSilence":0.4}',
+    remove_words: '{"words":[12,13,14]}',
+    set_clip_properties: '{"ids":["3f2a"],"props":{"volume":0.3,"fadeIn":15,"opacity":0.9}}',
+    set_keyframes: '{"id":"3f2a","prop":"zoom","keys":[{"frame":60,"value":1},{"frame":64,"value":1.2}]}',
+    apply_layout: '{"layout":"pip_br","ids":["<fala>","<broll>"]}',
+    add_texts: '{"texts":[{"content":"3 DICAS","at":0,"dur":60,"cy":0.2,"animation":"popIn","style":{"bg":"#E11D48"}}]}',
+    add_captions: '{"maxWords":3,"animation":"highlightPop","style":{"upper":true}}',
+    apply_color: '{"ids":"all","preset":"warm","contrast":0.1}',
+    apply_effect: '{"ids":["3f2a"],"type":"stylize.vignette","params":{"strength":0.6}}',
+    detect_beats: '{"asset":"a3","markers":true}',
+    undo: '{"steps":2}',
+    export: '{"out":"final.mp4"}',
+};
+
+function ajuda() {
+    const linhas = [
+        "primocode video <op> [--json '{...}'] [--project <id>]   — editor de vídeo por linha do tempo (ffmpeg)",
+        'UNIDADES: posição/duração na timeline = QUADROS inteiros (fps do projeto); from/to da mídia = SEGUNDOS da origem.',
+        'Faixa 0 = a de cima. cx,cy,w,h em 0–1 do quadro (cx,cy = centro). Clipe por id curto ou prefixo único. Mídia: a1, a2…',
+        'Toda edição devolve um DELTA (added/removed/changed/shifted[{by,ids}]/dur) e é desfeita com undo — não peça licença.',
+        'Saída: 1 linha JSON no stdout (ok:false + error se falhou). Depois de editar, use inspect e OLHE o png.',
+    ];
+    for (const [nome, o] of Object.entries(OPS)) {
+        if (o.oculto) continue;
+        linhas.push('  ' + o.uso);
+        if (EX[nome]) linhas.push(`      ex: primocode video ${nome} --json '${EX[nome]}'`);
+    }
+    linhas.push(
+        'Texto: animation none|fade|popIn|typewriter|wordReveal|highlightPop; style {size(0–1 da altura),color,stroke,',
+        '  strokeWidth,highlight,bg,upper,font(bold|black|regular|caminho .ttf),align}.',
+    );
+    return linhas.join('\n');
+}
+
+module.exports = { OPS, ALIAS, ajuda, mutar, alvos };