primocode 11.0.0 → 11.1.0

package/lib/plugin/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/plugin/video/render.js

@@ -0,0 +1,274 @@
+/**
+ * render.js — onde o editor encosta no mundo: ffmpeg, Pillow e disco.
+ *
+ * Tudo que decide mora nos módulos puros (filters, texto, analise). Aqui só
+ * se mede, desenha e roda. O ffmpeg é achado pelo mesmo lib/plugin/estudio/video.js
+ * do Estúdio — um lugar só sabe onde o ffmpeg está e como instalar.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn, execFileSync } = require('child_process');
+const T = require('./timeline.js');
+const F = require('./filters.js');
+const TX = require('./texto.js');
+const video = require('../estudio/video.js');
+const { rodarPython } = require('./transcript.js');
+
+const TEXTO_PY = path.join(__dirname, '..', '..', '..', 'studio', 'texto.py');
+const IMAGEM = /\.(png|jpe?g|webp|bmp|gif|tiff?)$/i;
+
+// ── o que o ffmpeg desta máquina sabe ────────────────────────────────────
+
+let _versao = null;
+function versaoMaior() {
+    if (_versao !== null) return _versao;
+    try {
+        const v = execFileSync(video.ffmpeg(), ['-version'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString();
+        const m = v.match(/ffmpeg version n?(\d+)\./);
+        _versao = m ? Number(m[1]) : 99;   // build do git ("N-12345") é recente
+    } catch { _versao = 99; }
+    return _versao;
+}
+
+let _codec = null;
+function codecDeVideo() {
+    if (_codec) return _codec;
+    let lista = '';
+    try { lista = execFileSync(video.ffmpeg(), ['-hide_banner', '-encoders'], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 5000 }).toString(); } catch {}
+    for (const c of ['libx264', 'libopenh264', 'h264_videotoolbox', 'h264_mf', 'mpeg4']) {
+        if (new RegExp(`\\s${c}\\s`).test(lista)) { _codec = c; return c; }
+    }
+    return (_codec = 'mpeg4');
+}
+
+function argsDoCodec(codec, crf) {
+    if (codec === 'libx264') return ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', String(crf)];
+    if (codec === 'h264_videotoolbox') return ['-c:v', codec, '-b:v', '8M'];
+    return ['-c:v', codec, '-b:v', '8M'];
+}
+
+function conferir() { return video.conferir(); }
+
+// ── importar ─────────────────────────────────────────────────────────────
+
+async function medirAsset(tl, arquivo) {
+    const abs = path.resolve(arquivo);
+    if (!fs.existsSync(abs)) throw T.erro(`arquivo não existe: ${abs}`);
+    const m = await video.medir(abs);
+    if (!m.ok) throw T.erro(m.error);
+    const imagem = IMAGEM.test(abs);
+    const kind = imagem ? 'image' : m.largura ? 'video' : 'audio';
+    return {
+        id: T.novoAssetId(tl), path: abs, nome: path.basename(abs), kind,
+        seconds: imagem ? 0 : T.r2(m.segundos), width: m.largura || 0, height: m.altura || 0,
+        fps: m.fps || 0, hasAudio: !!m.temAudio,
+    };
+}
+
+// ── o texto em png ───────────────────────────────────────────────────────
+
+let _pillow = null;
+function python() { return require('../voz.js').python(); }
+
+async function temPillow() {
+    if (_pillow !== null) return _pillow;
+    const py = python();
+    _pillow = py ? !!(await rodarPython(py, [TEXTO_PY, 'conferir'], { cwd: path.dirname(TEXTO_PY), timeout: 30000 })).ok : false;
+    return _pillow;
+}
+
+/** As camadas de texto da janela: {índiceDaFaixa: arquivo .ffconcat}. */
+async function camadasDeTexto(pasta, tl, { from, to, escala }) {
+    const avisosPos = [];
+    const posicao = require('./gerados.js').posicoesDeLegenda(pasta, tl, avisosPos);
+    const faixas = tl.tracks.map((t, i) => ({ t, i })).filter(({ t }) => t.type === 'text' && t.clips.length && !t.hidden);
+    if (!faixas.length) return { camadas: {}, avisos: [] };
+    if (!(await temPillow())) {
+        return { camadas: {}, avisos: ['os textos NÃO foram desenhados: falta o Pillow (python3 -m pip install pillow)'] };
+    }
+    const W = T.par(tl.width * escala);
+    const H = T.par(tl.height * escala);
+    const dir = path.join(pasta, 'cache', 'texto', `${W}x${H}`);
+    fs.mkdirSync(dir, { recursive: true });
+    const vazio = path.join(dir, 'vazio.png');
+    const arquivoDe = (chave) => (chave === 'vazio' ? vazio : path.join(dir, `${chave}.png`));
+    const estados = [];
+    const camadas = {};
+    for (const { t, i } of faixas) {
+        const { segmentos, desenhos } = TX.estadosDaFaixa(tl, t, { from, to, escala, posicao });
+        if (!Object.keys(desenhos).length) continue;
+        for (const [chave, items] of Object.entries(desenhos)) {
+            if (!fs.existsSync(arquivoDe(chave)) && !estados.some((e) => e.chave === chave)) estados.push({ chave, file: arquivoDe(chave), items });
+        }
+        const arq = path.join(dir, `faixa${i}-${from}-${to}.ffconcat`);
+        fs.writeFileSync(arq, TX.ffconcat(segmentos, tl.fps, arquivoDe));
+        camadas[i] = arq;
+    }
+    if (estados.length || !fs.existsSync(vazio)) {
+        const job = path.join(dir, `job-${process.pid}.json`);
+        fs.writeFileSync(job, JSON.stringify({ width: W, height: H, estados: estados.map(({ file, items }) => ({ file, items })), vazio }));
+        const r = await rodarPython(python(), [TEXTO_PY, 'estados', job], { cwd: path.dirname(TEXTO_PY) });
+        try { fs.unlinkSync(job); } catch {}
+        if (!r.ok) return { camadas: {}, avisos: [`os textos não foram desenhados: ${r.error}`] };
+    }
+    return { camadas, avisos: [...new Set(avisosPos)], estados: estados.length };
+}
+
+// ── rodar o ffmpeg ───────────────────────────────────────────────────────
+
+async function rodarGrafo(pasta, g, saida, sufixo = '') {
+    const arq = path.join(pasta, 'cache', `grafo-${process.pid}${sufixo}.txt`);
+    fs.mkdirSync(path.dirname(arq), { recursive: true });
+    fs.writeFileSync(arq, g.grafo);
+    // O grafo vai por arquivo: com cinquenta clipes ele passa do teto de
+    // linha de comando do Windows (32 mil caracteres).
+    const flag = versaoMaior() >= 7 ? ['-/filter_complex', arq] : ['-filter_complex_script', arq];
+    const args = ['-hide_banner', '-loglevel', 'error', '-y', ...g.inputs.flat(), ...flag, ...saida];
+    const r = await video.rodar(video.ffmpeg(), args, { timeout: 60 * 60000 });
+    if (r.ok) { try { fs.unlinkSync(arq); } catch {} }
+    return { ...r, grafo: arq };
+}
+
+/* O EXPORT EM PARTES: o grafo do ffmpeg é quase todo de um núcleo só (cada
+   filtro roda numa thread), e um vídeo com pessoa recortada, fundo novo,
+   3D e legenda passa a maior parte do tempo nele. Então o VÍDEO sai em
+   pedaços de quadros, cada um num ffmpeg, ao mesmo tempo, e junta por
+   concat sem recodificar; o ÁUDIO sai inteiro, numa passada só (é barato,
+   e cortar AAC em pedaços deixa estalo na emenda). As emendas caem em
+   quadro inteiro: o quadro N sai igual com 1 ou com 9 pedaços. */
+async function exportar(pasta, tl, { out, from = 0, to, preview = false, crf = 20, partes } = {}) {
+    const c = conferir();
+    if (!c.ok) return c;
+    const ger = await require('./gerados.js').garantir(pasta, tl);
+    if (!ger.ok) return ger;
+    const escala = preview ? 0.5 : 1;
+    const ate = to === undefined ? T.duracao(tl) : Number(to);
+    const destino = path.resolve(out || path.join(pasta, 'saida', `${tl.nome || 'video'}${preview ? '-preview' : ''}.mp4`));
+    fs.mkdirSync(path.dirname(destino), { recursive: true });
+    const inicio = Date.now();
+    const PAR = require('./paralelo.js');
+    const total = ate - from;
+    const n = partes !== undefined ? Math.max(1, Number(partes)) : Math.max(1, Math.min(PAR.quantos(), Math.floor(total / (tl.fps * 2))));
+    const codec = argsDoCodec(codecDeVideo(), crf);
+    const extra = ger.feitos ? { gerados: ger.feitos, geradosS: ger.tookS } : {};
+    if (n === 1) {
+        const tx = await camadasDeTexto(pasta, tl, { from, to: ate, escala });
+        const g = F.montarGrafo(tl, { from, to: ate, camadasDeTexto: tx.camadas, escala });
+        const r = await rodarGrafo(pasta, g, [
+            '-map', g.saidaV, '-map', g.saidaA, '-t', F.num(g.segundos), '-r', String(tl.fps),
+            ...codec, '-pix_fmt', 'yuv420p', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart', destino,
+        ]);
+        if (!r.ok) return { ok: false, error: 'o ffmpeg falhou', detalhe: r.erro.slice(-600), grafo: r.grafo };
+        return { ok: true, file: destino, s: T.r2(g.segundos), size: `${g.W}x${g.H}`, mb: T.r2(fs.statSync(destino).size / 1048576),
+            tookS: Math.round((Date.now() - inicio) / 100) / 10, partes: 1, ...extra, ...(tx.avisos.length ? { avisos: tx.avisos } : {}) };
+    }
+    const tmp = path.join(pasta, 'cache', `export-${process.pid}`);
+    fs.rmSync(tmp, { recursive: true, force: true });
+    fs.mkdirSync(tmp, { recursive: true });
+    const cortes = Array.from({ length: n + 1 }, (_, i) => from + Math.round((total * i) / n));
+    // Os PNGs do texto antes, em fila: dois pedaços desenhando o mesmo estado ao mesmo tempo se atropelariam.
+    const avisos = new Set();
+    const pedacos = [];
+    for (let i = 0; i < n; i++) {
+        const tx = await camadasDeTexto(pasta, tl, { from: cortes[i], to: cortes[i + 1], escala });
+        tx.avisos.forEach((a) => avisos.add(a));
+        pedacos.push({ de: cortes[i], ate: cortes[i + 1], tx, arq: path.join(tmp, `v${String(i).padStart(3, '0')}.mp4`) });
+    }
+    const res = await PAR.emParalelo([
+        ...pedacos.map((p, i) => () => {
+            const g = F.montarGrafo(tl, { from: p.de, to: p.ate, camadasDeTexto: p.tx.camadas, escala, audio: false });
+            return rodarGrafo(pasta, g, ['-map', g.saidaV, '-frames:v', String(p.ate - p.de), '-r', String(tl.fps), ...codec, '-pix_fmt', 'yuv420p', p.arq], `-v${i}`);
+        }),
+        () => {
+            const g = F.montarGrafo(tl, { from, to: ate, escala, video: false });
+            return rodarGrafo(pasta, g, ['-map', g.saidaA, '-t', F.num(g.segundos), '-c:a', 'aac', '-b:a', '192k', path.join(tmp, 'audio.m4a')], '-a');
+        },
+    ], n + 1);
+    const ruim = res.find((r) => !r.ok);
+    if (ruim) return { ok: false, error: 'o ffmpeg falhou', detalhe: ruim.erro.slice(-600), grafo: ruim.grafo };
+    const lista = path.join(tmp, 'lista.txt');
+    fs.writeFileSync(lista, pedacos.map((p) => `file '${p.arq.replace(/'/g, "'\\''")}'`).join('\n') + '\n');
+    const j = await video.rodar(video.ffmpeg(), ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'concat', '-safe', '0', '-i', lista,
+        '-i', path.join(tmp, 'audio.m4a'), '-map', '0:v', '-map', '1:a', '-c', 'copy', '-movflags', '+faststart', destino]);
+    if (!j.ok) return { ok: false, error: 'não juntei os pedaços do export', detalhe: j.erro.slice(-400) };
+    fs.rmSync(tmp, { recursive: true, force: true });
+    return { ok: true, file: destino, s: T.r2(total / tl.fps), size: `${T.par(tl.width * escala)}x${T.par(tl.height * escala)}`,
+        mb: T.r2(fs.statSync(destino).size / 1048576), tookS: Math.round((Date.now() - inicio) / 100) / 10, partes: n, ...extra,
+        ...(avisos.size ? { avisos: [...avisos] } : {}) };
+}
+
+/** Os quadros pedidos, com a grade 0–1 e o número do quadro, numa folha só. */
+async function inspecionar(pasta, tl, { frames, escala = 0.5, out } = {}) {
+    const c = conferir();
+    if (!c.ok) return c;
+    const ger = await require('./gerados.js').garantir(pasta, tl);
+    if (!ger.ok) return ger;
+    const dur = T.duracao(tl);
+    const lista = [...new Set(frames.map((f) => Math.max(0, Math.min(dur - 1, Math.round(Number(f))))))].slice(0, 12);
+    const dir = path.join(pasta, 'cache', 'inspect');
+    fs.mkdirSync(dir, { recursive: true });
+    const pngs = [];
+    const avisos = new Set();
+    for (const f of lista) {
+        const tx = await camadasDeTexto(pasta, tl, { from: f, to: f + 1, escala });
+        tx.avisos.forEach((a) => avisos.add(a));
+        const g = F.montarGrafo(tl, { from: f, to: f + 1, camadasDeTexto: tx.camadas, escala, audio: false });
+        const png = path.join(dir, `f${f}.png`);
+        const r = await rodarGrafo(pasta, g, ['-map', g.saidaV, '-frames:v', '1', '-update', '1', png]);
+        if (!r.ok) return { ok: false, error: `o quadro ${f} falhou`, detalhe: r.erro.slice(-500), grafo: r.grafo };
+        pngs.push({ png, frame: f, tempo: f / tl.fps });
+    }
+    const destino = path.resolve(out || path.join(pasta, 'saida', 'inspect.png'));
+    fs.mkdirSync(path.dirname(destino), { recursive: true });
+    if (await temPillow()) {
+        const job = path.join(dir, 'grade.json');
+        fs.writeFileSync(job, JSON.stringify({ frames: pngs, out: destino, altura: lista.length > 1 ? 640 : 960 }));
+        const r = await rodarPython(python(), [TEXTO_PY, 'grade', job], { cwd: path.dirname(TEXTO_PY) });
+        if (r.ok) return { ok: true, png: destino, frames: lista, ...(avisos.size ? { avisos: [...avisos] } : {}) };
+        avisos.add(`sem grade: ${r.error}`);
+    }
+    return { ok: true, pngs: pngs.map((p) => p.png), frames: lista, avisos: [...avisos, 'sem Pillow: quadros sem grade'] };
+}
+
+// ── medir áudio ──────────────────────────────────────────────────────────
+
+async function silenciosDe(pasta, asset, { threshold = -35, minSilence = 0.5 } = {}) {
+    const cache = path.join(pasta, 'midia', `silencio-${asset.id}-${threshold}-${minSilence}.json`);
+    if (fs.existsSync(cache)) { try { return JSON.parse(fs.readFileSync(cache, 'utf8')); } catch {} }
+    const r = await video.rodar(video.ffmpeg(), ['-hide_banner', '-i', asset.path, '-vn',
+        '-af', `silencedetect=noise=${threshold}dB:d=${minSilence}`, '-f', 'null', '-']);
+    if (!r.ok) throw T.erro(`o silencedetect falhou: ${r.erro.slice(-200)}`);
+    const lista = [];
+    let inicio = null;
+    for (const linha of r.erro.split('\n')) {
+        const i = linha.match(/silence_start:\s*(-?[\d.]+)/);
+        if (i) { inicio = Math.max(0, Number(i[1])); continue; }
+        const f = linha.match(/silence_end:\s*([\d.]+)/);
+        if (f && inicio !== null) { lista.push({ de: inicio, ate: Number(f[1]) }); inicio = null; }
+    }
+    // Silêncio que vai até o fim do arquivo não tem "silence_end": fecha no fim.
+    if (inicio !== null && inicio < asset.seconds) lista.push({ de: inicio, ate: asset.seconds });
+    fs.mkdirSync(path.dirname(cache), { recursive: true });
+    fs.writeFileSync(cache, JSON.stringify(lista));
+    return lista;
+}
+
+/** As amostras cruas (mono, Float32) — para achar batida. */
+function amostras(arquivo, taxa = 22050) {
+    return new Promise((resolve, reject) => {
+        const p = spawn(video.ffmpeg(), ['-hide_banner', '-loglevel', 'error', '-i', arquivo, '-vn', '-ac', '1', '-ar', String(taxa), '-f', 'f32le', '-']);
+        const partes = [];
+        p.stdout.on('data', (d) => partes.push(d));
+        p.on('error', reject);
+        p.on('close', (code) => {
+            if (code !== 0) return reject(T.erro('não consegui ler o áudio'));
+            const b = Buffer.concat(partes);
+            resolve(new Float32Array(b.buffer, b.byteOffset, Math.floor(b.length / 4)));
+        });
+    });
+}
+
+module.exports = { conferir, medirAsset, temPillow, camadasDeTexto, exportar, inspecionar, silenciosDe, amostras, codecDeVideo, versaoMaior };

package/lib/plugin/video/transcript.js

@@ -0,0 +1,124 @@
+/**
+ * transcript.js — cada palavra dita, com o tempo dela, e onde ela está
+ * AGORA na linha do tempo.
+ *
+ * A transcrição é da MÍDIA (segundos da origem) e fica guardada uma vez por
+ * mídia. O que muda a cada edição é o mapa: depois de cortar um silêncio, a
+ * palavra 42 continua sendo a 42, mas começa 38 quadros antes. É por isso
+ * que o índice da palavra é estável — o modelo pode pedir "apaga as palavras
+ * 12 a 15" com a lista que leu três edições atrás.
+ *
+ * ── DE ONDE VEM ──────────────────────────────────────────────────────────
+ *   1. o faster-whisper local (voz/primo_voz/transcrever.py), se instalado:
+ *      sem rede, sem chave, e o áudio não sai da máquina;
+ *   2. o /api/transcrever do servidor do PrimoCode (o mesmo do Estúdio).
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+const T = require('./timeline.js');
+
+const VOZ = path.join(__dirname, '..', '..', '..', 'voz');
+
+/** O mapa: cada palavra da mídia que aparece na linha do tempo, em quadros. */
+function mapear(tl, assetId, palavras) {
+    const out = [];
+    tl.tracks.forEach((t, ti) => {
+        if (t.type === 'text') return;
+        for (const c of t.clips) {
+            if (c.asset !== assetId) continue;
+            const { de, ate } = T.janelaOrigem(tl, c);
+            palavras.forEach((p, i) => {
+                const meio = (p.de + p.ate) / 2;
+                if (meio < de || meio >= ate) return;
+                const f = T.origemParaQuadro(tl, c, Math.max(de, p.de));
+                const e = T.origemParaQuadro(tl, c, Math.min(ate, p.ate));
+                out.push({ i, texto: p.texto, f, e: Math.max(f + 1, e), clip: c.id, t: ti });
+            });
+        }
+    });
+    // A mesma palavra em dois clipes (clipe duplicado) aparece duas vezes: fica a de cima.
+    const vistos = new Set();
+    return out.sort((a, b) => a.f - b.f || a.t - b.t).filter((w) => {
+        const k = `${w.i}@${w.f}`;
+        if (vistos.has(k)) return false;
+        vistos.add(k);
+        return true;
+    });
+}
+
+function rodarPython(py, args, { cwd, timeout = 20 * 60000 } = {}) {
+    return new Promise((resolve) => {
+        const p = spawn(py, args, { cwd, env: { ...process.env, PYTHONPATH: cwd, PYTHONWARNINGS: 'ignore' } });
+        let out = '';
+        let err = '';
+        p.stdout.on('data', (d) => { out += d; });
+        p.stderr.on('data', (d) => { err += d; });
+        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);
+            const linha = out.trim().split('\n').pop() || '';
+            try { resolve(JSON.parse(linha)); } catch { resolve({ ok: false, error: (err || out).slice(-300) || 'sem resposta' }); }
+        });
+    });
+}
+
+async function local(arquivo, idioma) {
+    const py = require('../voz.js').python();
+    if (!py) return { ok: false, error: 'sem python3' };
+    return rodarPython(py, ['-m', 'primo_voz.transcrever', 'palavras', arquivo, idioma], { cwd: VOZ });
+}
+
+async function servidor(arquivo, idioma, pastaTmp) {
+    const cfg = require('../../config/config.js').loadConfig();
+    if (!cfg.server || !cfg.token) return { ok: false, error: 'sem servidor/conta configurados' };
+    const video = require('../estudio/video.js');
+    const mp3 = path.join(pastaTmp, `audio-${Date.now().toString(36)}.mp3`);
+    const ex = await video.extrairAudio(arquivo, mp3);
+    if (!ex.ok) return ex;
+    try {
+        const r = await require('../../provider/api.js').requestTranscricao(cfg.server, {
+            token: cfg.token, audio: fs.readFileSync(mp3).toString('base64'), nome: path.basename(mp3), idioma,
+        });
+        if (!r || r.ok === false) return { ok: false, error: (r && (r.erro || r.error)) || 'a transcrição falhou' };
+        return { ok: true, palavras: r.palavras || [] };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    } finally {
+        try { fs.unlinkSync(mp3); } catch {}
+    }
+}
+
+/** A transcrição da mídia (do cache, ou feita agora). */
+async function obter(pasta, asset, { force = false, idioma = 'pt' } = {}) {
+    const cache = path.join(pasta, 'midia', `transcricao-${asset.id}.json`);
+    if (!force && fs.existsSync(cache)) {
+        try { return { ok: true, ...JSON.parse(fs.readFileSync(cache, 'utf8')), cache: true }; } catch { /* refaz */ }
+    }
+    if (!asset.hasAudio) return { ok: false, error: `a mídia ${asset.id} não tem áudio` };
+    const tentativas = [];
+    let r = await local(asset.path, idioma);
+    let fonte = 'whisper-local';
+    if (!r.ok) {
+        tentativas.push(`local: ${r.error}`);
+        r = await servidor(asset.path, idioma, path.join(pasta, 'midia'));
+        fonte = 'servidor';
+    }
+    if (!r.ok) {
+        tentativas.push(`servidor: ${r.error}`);
+        return { ok: false, error: 'não consegui transcrever', tentativas,
+            comoResolver: 'python3 -m pip install faster-whisper (local), ou entre na conta do PrimoCode' };
+    }
+    const palavras = (r.palavras || []).filter((p) => p && p.texto && p.ate > p.de)
+        .map((p) => ({ de: Number(p.de), ate: Number(p.ate), texto: String(p.texto).trim(), ...(Number.isFinite(Number(p.p)) && p.p != null ? { p: Number(p.p) } : {}) }));
+    const dados = { asset: asset.id, fonte, idioma, palavras };
+    fs.mkdirSync(path.dirname(cache), { recursive: true });
+    fs.writeFileSync(cache, JSON.stringify(dados));
+    return { ok: true, ...dados };
+}
+
+module.exports = { mapear, obter, rodarPython, VOZ };

package/lib/plugin/voz-ponte.js

@@ -0,0 +1,15 @@
+/**
+ * voz-ponte.js — o aviso do agente para o modo voz, sem um depender do outro.
+ *
+ * O agente (lib/session/runner/act.js) diz "comecei a ferramenta X" aqui; o /voice, se estiver
+ * ligado, se inscreve e repassa ao Primo (painel mostra "executando" e ele
+ * confirma em voz alta: "rodando os testes"). Sem /voice, ninguém escuta.
+ */
+'use strict';
+
+let ouvinte = null;
+
+module.exports = {
+    escutar: (fn) => { ouvinte = typeof fn === 'function' ? fn : null; },
+    ferramenta: (nome, args) => { if (ouvinte) { try { ouvinte(String(nome || ''), args || {}); } catch { /* o aviso nunca derruba o agente */ } } },
+};