primocode 11.0.0 → 11.1.0

package/lib/plugin/estudio/maquina-trilha.js

@@ -0,0 +1,199 @@
+/**
+ * maquina-trilha.js — a trilha do motion: energia alta ou nada.
+ *
+ * Regras (Joel, 18/10: "a trilha de fundo é horrível"):
+ *   · LISTA NEGRA permanente: as faixas já usadas pela máquina (inclusive Jesse Keller e Josh Woodward) nunca mais voltam.
+ *     Mora no código (PROIBIDAS) e em ~/.primocode/studio/trilhas-proibidas.json (a pessoa acrescenta; as duas somam).
+ *   · ENERGIA ALTA: BPM ≥ 110, batida confiável (batida.js) e volume de música de verdade (LUFS ≥ −17); gênero pelo assunto
+ *     (phonk, trap, electro, house, techno…). Várias candidatas são baixadas e medidas; ganha a de maior nota.
+ *   · CORTE NO DROP: o início da faixa é escolhido (batida.melhorInicio) para o maior acento cair no corte mais pesado.
+ *   · `trilha:` aceita um ARQUIVO da pessoa (mp3/wav/m4a): ele vence a busca (a lista negra não vale para o que ela escolheu).
+ *   · Sem faixa boa → sem música, só sound design.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const ARQUIVO_PROIBIDAS = () => process.env.PRIMOCODE_TRILHAS_PROIBIDAS || path.join(os.homedir(), '.primocode', 'studio', 'trilhas-proibidas.json');
+
+/** Usadas até 18/10/2026 (lidas das fichas .licenca.json dos projetos e dos vídeos de prova) + as que o Joel apontou. */
+const PROIBIDAS = [
+    { autor: 'Jesse Keller', motivo: 'o Joel apontou: horrível' },
+    { autor: 'Josh Woodward', titulo: 'Motionless Land', motivo: 'o Joel apontou: horrível' },
+    { autor: 'Soundrider', titulo: 'Corporate', motivo: 'usada nos vídeos v1' },
+    { autor: 'Tymphony', motivo: 'usada nos vídeos v1' },
+    { autor: 'Tri-Tachyon', motivo: 'usada nos vídeos v1' },
+    { autor: 'Professor Kliq', motivo: 'usada nos vídeos v1' },
+    { autor: 'Adrian Sanchez', motivo: 'usada nos vídeos v1' },
+    { autor: 'Arhur Yul', motivo: 'usada nos vídeos v1' },
+    { autor: 'Hasenchat', motivo: 'usada nos vídeos v1' },
+    { autor: 'Pakii', motivo: 'usada nos vídeos v1' },
+    { autor: 'Alittlebitdrunkguy', motivo: 'usada nos vídeos v1' },
+    { autor: 'Jahzzar', motivo: 'usada nos vídeos v1' },
+    { autor: 'Fragments Of Winter', motivo: 'usada nos vídeos v1' },
+    { trackid: '1670486' }, { trackid: '1670484' }, { trackid: '764950' }, { trackid: '341547' }, { trackid: '925452' }, { trackid: '432009' },
+    { trackid: '1501961' }, { trackid: '1137475' }, { trackid: '992957' }, { trackid: '509068' }, { trackid: '417168' },
+];
+
+/** Garante o arquivo da lista negra (cria com as entradas de fábrica) e devolve a lista somada (código + arquivo). */
+function lerProibidas(arq = ARQUIVO_PROIBIDAS()) {
+    let doArquivo = [];
+    try { doArquivo = JSON.parse(fs.readFileSync(arq, 'utf8')); } catch { /* ainda não existe */ }
+    if (!Array.isArray(doArquivo)) doArquivo = [];
+    if (!fs.existsSync(arq)) { try { fs.mkdirSync(path.dirname(arq), { recursive: true }); fs.writeFileSync(arq, JSON.stringify(PROIBIDAS, null, 2)); } catch { /* sem disco */ } }
+    return [...PROIBIDAS, ...doArquivo];
+}
+const norm = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '');
+/** A faixa (título, autor, url) está na lista negra? */
+function proibida(item, lista = lerProibidas()) {
+    const t = norm(item.titulo || item.title), a = norm(item.autor || item.creator), u = String(item.url || '');
+    return lista.some((p) => {
+        if (p.trackid && new RegExp('trackid=' + p.trackid + '(?!\\d)').test(u)) return true;
+        if (p.url && p.url === u) return true;
+        if (p.autor && a.includes(norm(p.autor)) && (!p.titulo || t.includes(norm(p.titulo)))) return true;
+        if (!p.autor && p.titulo && t.includes(norm(p.titulo))) return true;
+        return false;
+    });
+}
+/** Acrescenta uma faixa à lista negra permanente. */
+function proibir(item, motivo = 'recusada') {
+    const arq = ARQUIVO_PROIBIDAS();
+    let l = []; try { l = JSON.parse(fs.readFileSync(arq, 'utf8')); } catch { /* nova */ }
+    l.push({ autor: item.autor || undefined, titulo: item.titulo || undefined, url: item.url || undefined, motivo, quando: new Date().toISOString() });
+    fs.mkdirSync(path.dirname(arq), { recursive: true });
+    fs.writeFileSync(arq, JSON.stringify(l, null, 2));
+}
+
+/** Os gêneros que a busca tenta, por tipo de assunto (a chave vem de maquina-diretor.achar). */
+const GENEROS = {
+    software: ['electro house', 'techno', 'phonk', 'synthwave'],
+    financas: ['trap beat', 'phonk', 'electro hip hop', 'house'],
+    padaria: ['tropical house', 'funk groove', 'electro swing', 'house'],
+    clinica: ['deep house', 'electro pop', 'chillhop upbeat', 'house'],
+    geral: ['electro house', 'trap', 'phonk', 'house'],
+};
+
+const LIMITE = { bpmMin: 110, confianca: 0.7, lufsMin: -17 };
+
+/** A trilha pela emoção da frase (ids de helpers/trilhas_humores.json; a emoção vem de editor-pro-maquina.emocaoDaFala).
+    Humor de energia alta usa a régua de sempre (BPM ≥ 110); os calmos aceitam andamento e volume menores, mas nunca trilha sem batida. */
+const HUMORES = {
+    animada: { termos: ['electro house', 'trap beat', 'phonk', 'house'], limite: LIMITE },
+    epica: { termos: ['epic cinematic trailer', 'cinematic hybrid', 'epic electronic'], limite: { bpmMin: 90, confianca: 0.55, lufsMin: -20 } },
+    tensa: { termos: ['dark cinematic suspense', 'dark electro', 'tension drone beat'], limite: { bpmMin: 80, confianca: 0.5, lufsMin: -22 } },
+    triste: { termos: ['sad piano ambient', 'emotional cinematic', 'melancholic ambient'], limite: { bpmMin: 55, confianca: 0.4, lufsMin: -26 } },
+    calma: { termos: ['calm lofi beat', 'chillhop', 'soft ambient groove'], limite: { bpmMin: 60, confianca: 0.45, lufsMin: -24 } },
+    inspiradora: { termos: ['inspiring uplifting beat', 'motivational electronic', 'hopeful piano beat'], limite: { bpmMin: 85, confianca: 0.55, lufsMin: -20 } },
+};
+
+/** As trilhas da biblioteca pessoal (helpers/trilhas.py: ~/.editor-video/trilhas, ou EDITOR_VIDEO_TRILHAS) para um humor, a favorita primeiro.
+    São da própria pessoa: valem sem rede e sem lista negra. */
+function daBiblioteca(humor) {
+    const dir = process.env.EDITOR_VIDEO_TRILHAS || path.join(os.homedir(), '.editor-video', 'trilhas');
+    let idx; try { idx = JSON.parse(fs.readFileSync(path.join(dir, 'trilhas.json'), 'utf8')); } catch { return []; }
+    return (idx.tracks || []).filter((t) => (humor === '*' || t.mood === humor) && t.file && !path.isAbsolute(t.file) && !String(t.file).includes('..'))
+        .sort((a, b) => (b.favorite ? 1 : 0) - (a.favorite ? 1 : 0))
+        .map((t) => ({ arquivo: path.join(dir, t.file), titulo: t.title || path.basename(t.file) }))
+        .filter((t) => fs.existsSync(t.arquivo));
+}
+
+function ff(args, opts = {}) {
+    const r = spawnSync('ffmpeg', ['-y', '-hide_banner', '-loglevel', 'error', ...args], { encoding: 'utf8', timeout: opts.timeout || 120000 });
+    return r.status === 0;
+}
+function lufsDe(arq, segundos = 60) {
+    const r = spawnSync('ffmpeg', ['-hide_banner', '-nostats', '-t', String(segundos), '-i', arq, '-vn', '-af', 'ebur128=peak=true', '-f', 'null', '-'], { encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 });
+    const s = String(r.stderr || '');
+    const m = s.slice(s.lastIndexOf('Summary:')).match(/I:\s+(-?\d+(?:\.\d+)?)\s+LUFS/);
+    return m ? Number(m[1]) : null;
+}
+
+/**
+ * A nota de uma faixa analisada (0 se reprovada): andamento entre 120 e 150 vale mais, batida firme, acentos de drop e
+ * volume de música moderna. `a` = {bpm, confianca, acentos, segundos, lufs}.
+ */
+function nota(a, limite = LIMITE) {
+    if (!a || !a.bpm || a.bpm < limite.bpmMin || a.confianca < limite.confianca) return 0;
+    if (a.lufs != null && a.lufs < limite.lufsMin) return 0;
+    const bpm = Math.max(0, 1 - Math.abs(a.bpm - 135) / 60);
+    const loud = a.lufs == null ? 0.5 : Math.max(0, Math.min(1, (a.lufs - limite.lufsMin) / 6));
+    return Math.round((0.3 * bpm + 0.3 * a.confianca + 0.2 * Math.min(1, (a.acentos || []).length / 6) + 0.2 * loud) * 1000) / 1000;
+}
+
+/**
+ * Escolhe a trilha. `arquivo` (da pessoa) vence. `deps`: {procurar(termo), baixar(item, pasta), analisar(arq), lufs(arq)} (testes).
+ * Devolve {arquivo, titulo, creditos, bpm, batidas, acentos, confianca, lufs, nota, pessoa} ou {semMusica: true, motivo}.
+ */
+async function escolher({ chave = 'geral', humor = null, busca = null, arquivo = null, pasta, rede = true, deps = {}, maximo = 8 } = {}) {
+    const H = humor && HUMORES[humor] ? HUMORES[humor] : null;
+    const lim = H ? H.limite : LIMITE;
+    const batida = require('./batida.js');
+    const analisar = deps.analisar || ((arq) => batida.analisar(arq));
+    const medirLufs = deps.lufs || ((arq) => lufsDe(arq));
+    if (arquivo && fs.existsSync(arquivo)) {
+        const a = await analisar(arquivo).catch(() => null);
+        return { arquivo, titulo: path.basename(arquivo), creditos: null, bpm: a && a.bpm, batidas: a && a.batidas, acentos: a && a.acentos, confianca: a && a.confianca, lufs: medirLufs(arquivo), pessoa: true, nota: 1 };
+    }
+    // a biblioteca pessoal do humor (a pessoa já guardou trilha triste, animada...): vence a busca na rede
+    const daCasa = humor ? (deps.biblioteca || daBiblioteca)(humor) : [];
+    for (const t of daCasa) {
+        const a = await analisar(t.arquivo).catch(() => null);
+        if (a && a.bpm) return { arquivo: t.arquivo, titulo: t.titulo, creditos: null, bpm: a.bpm, batidas: a.batidas, acentos: a.acentos, confianca: a.confianca, segundos: a.segundos, lufs: medirLufs(t.arquivo), humor, biblioteca: true, nota: 1 };
+    }
+    if (!rede && !deps.procurar) return { semMusica: true, motivo: 'sem rede e sem arquivo' };
+    const assets = deps.procurar ? null : require('./assets.js');
+    const procurar = deps.procurar || ((t) => assets.procurarMusica(t, { quantas: 10, duracaoMin: 25 }));
+    const baixar = deps.baixar || ((item, p) => assets.baixar(item, { pasta: p, nome: 'trilha-' + String(item.titulo || 'x').slice(0, 20), sub: path.join('midia', 'trilhas') }));
+    const lista = lerProibidas();
+    const termos = [busca, ...(H ? H.termos : (GENEROS[chave] || GENEROS.geral))].filter(Boolean).slice(0, 4);
+    const vistos = new Set();
+    const analisadas = [];
+    const recusadas = [];
+    const erros = [];
+    for (const termo of termos) {
+        if (analisadas.length >= maximo) break;
+        let r; try { r = await procurar(termo); } catch (e) { erros.push(`busca "${termo}": ${e.message}`); continue; }
+        if (r && r.ok === false) erros.push(`busca "${termo}": ${r.error || 'falhou'}`);
+        for (const item of ((r && r.sons) || [])) {
+            if (analisadas.length >= maximo) break;
+            if (!item.url || vistos.has(item.url)) continue;
+            vistos.add(item.url);
+            if (proibida(item, lista)) { recusadas.push(item.titulo); continue; }
+            let b; try { b = await baixar(item, pasta); } catch (e) { erros.push(`download de "${item.titulo}": ${e.message}`); continue; }
+            if (!b || !b.ok) { erros.push(`download de "${item.titulo}": ${(b && b.error) || 'falhou'}`); continue; }
+            const a = await analisar(b.arquivo).catch(() => null);
+            if (!a) continue;
+            const lufs = medirLufs(b.arquivo);
+            const faixa = { arquivo: b.arquivo, titulo: item.titulo, autor: item.autor, creditos: b.creditos || item.creditos || null, genero: termo, bpm: a.bpm, batidas: a.batidas, acentos: a.acentos, confianca: a.confianca, segundos: a.segundos, lufs };
+            faixa.nota = nota(faixa, lim);
+            analisadas.push(faixa);
+        }
+        // uma boa já basta para o primeiro gênero: não gasta rede à toa
+        if (analisadas.some((f) => f.nota >= 0.75)) break;
+    }
+    const boas = analisadas.filter((f) => f.nota > 0).sort((a, b) => b.nota - a.nota);
+    if (!boas.length) {
+        // a rede falhou ou não achou faixa boa: a biblioteca local, de qualquer humor (o mais próximo primeiro), vale mais que o vídeo sem música
+        for (const t of (deps.biblioteca || daBiblioteca)('*')) {
+            const a = await analisar(t.arquivo).catch(() => null);
+            if (a && a.bpm) return { arquivo: t.arquivo, titulo: t.titulo, creditos: null, bpm: a.bpm, batidas: a.batidas, acentos: a.acentos, confianca: a.confianca, segundos: a.segundos, lufs: medirLufs(t.arquivo), humor: humor || null, biblioteca: true, reserva: true, nota: 0.5 };
+        }
+    }
+    if (!boas.length) return { semMusica: true, motivo: `nenhuma das ${analisadas.length} faixas analisadas tem energia (BPM ≥ ${lim.bpmMin}, batida firme, LUFS ≥ ${lim.lufsMin}${humor ? ', humor ' + humor : ''})${erros.length ? ' · erros: ' + [...new Set(erros)].slice(0, 3).join(' | ') : ''}`, erros, analisadas: analisadas.map((f) => ({ titulo: f.titulo, bpm: f.bpm, confianca: f.confianca, lufs: f.lufs })), recusadas };
+    return { ...boas[0], humor: humor || null, analisadas: analisadas.length, recusadas };
+}
+
+/**
+ * O início da faixa (s) que põe o drop no corte mais pesado: `cortes` = [{t, peso}] do vídeo. Devolve {inicio, alinhados, total}.
+ */
+function inicioNoDrop(cortes, faixa, duracaoDoVideo) {
+    const batida = require('./batida.js');
+    const maximo = Math.max(0, (faixa.segundos || 0) - duracaoDoVideo - 1);
+    return batida.melhorInicio(cortes, { batidas: faixa.batidas, acentos: faixa.acentos, confianca: faixa.confianca }, { maximo, tolerancia: 0.06 });
+}
+
+module.exports = { PROIBIDAS, GENEROS, HUMORES, daBiblioteca, LIMITE, lerProibidas, proibida, proibir, nota, escolher, inicioNoDrop, ARQUIVO_PROIBIDAS };

package/lib/plugin/estudio/maquina-voz.js

@@ -0,0 +1,429 @@
+/**
+ * maquina-voz.js — a narração que MANDA no tempo do motion.
+ *
+ * A voz é gerada de uma vez (uma fala por cena, junta), o whisper-cli mede o instante de CADA palavra
+ * e o roteiro é alinhado a esses instantes. Daí sai a regra "nada aparece antes de ser dito": o kit
+ * pergunta `tempoDaPalavra` e põe o elemento na hora da fala. A legenda vem por palavra, com a
+ * palavra-chave (a que veio entre *asteriscos*) marcada.
+ *
+ *   falarEMedir({falas, pasta, voz, narrar, whisper}) → {ok, mp3, dur, palavras, cenas, motor}
+ *   legendaChunks(palavras, {max})                   → [{t, t2, palavras}]
+ *   tempoDaPalavra(palavras, trecho, {cena, depoisDe}) → segundos | null
+ *
+ * A cadeia de voz (quando `narrar` não é injetado): VoiceStudio local → narrar.py (ElevenLabs/Edge)
+ * → Kokoro → `say` do macOS. A primeira que der certo ganha; o `motor` diz qual foi.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync, spawn } = require('child_process');
+
+const WHISPER_BIN = process.env.PRIMOCODE_WHISPER_BIN || '/opt/homebrew/bin/whisper-cli';
+const WHISPER_MODELO = () => process.env.PRIMOCODE_WHISPER_MODELO || path.join(os.homedir(), '.primocode', 'models', 'ggml-small.bin');
+const NARRAR_PY = path.join(__dirname, '..', '..', '..', 'studio', 'narrar.py');
+const r3 = (n) => Math.round(n * 1000) / 1000;
+
+const norm = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '');
+
+// ── o roteiro em palavras ────────────────────────────────────────────────
+
+/** "Veja *elas* de volta." → [{w:'Veja'}, {w:'elas', chave:true}, ...] (pontuação fica em `w`, `fim` marca pausa). */
+function palavrasDoRoteiro(falas) {
+    const out = [];
+    falas.forEach((fala, cena) => {
+        const brutas = String(fala || '').replace(/\s+/g, ' ').trim().split(' ').filter(Boolean);
+        brutas.forEach((b) => {
+            const chave = /\*/.test(b);
+            const w = b.replace(/\*/g, '');
+            if (!norm(w)) return;
+            out.push({ w, n: norm(w), cena, chave, pausa: /[.!?;:]$/.test(w) });
+        });
+    });
+    return out;
+}
+
+/** Texto único da narração: sem asteriscos, uma frase por cena (ponto no fim se faltar, para a voz respirar). */
+function textoDaNarracao(falas) {
+    return falas.map((f) => String(f || '').replace(/\*/g, '').replace(/\s+/g, ' ').trim()).filter(Boolean)
+        .map((f) => (/[.!?…]$/.test(f) ? f : f + '.')).join(' ');
+}
+
+// ── o whisper ────────────────────────────────────────────────────────────
+
+/** As palavras do whisper: [{w, n, t, t2}] (-ojf com -ml 1 -sow: uma palavra por segmento). */
+function lerJsonDoWhisper(json) {
+    const out = [];
+    for (const s of (json && json.transcription) || []) {
+        const texto = String(s.text || '').trim();
+        if (!texto || /^\[.*\]$/.test(texto) || !norm(texto)) continue;
+        const o = s.offsets || {};
+        out.push({ w: texto, n: norm(texto), t: r3((o.from || 0) / 1000), t2: r3((o.to || 0) / 1000) });
+    }
+    return out;
+}
+
+function medirComWhisper(mp3, { bin = WHISPER_BIN, modelo = WHISPER_MODELO(), lingua = 'pt' } = {}) {
+    if (!fs.existsSync(bin) || !fs.existsSync(modelo)) return { ok: false, error: 'whisper-cli ou o modelo não estão instalados' };
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'mq-voz-'));
+    try {
+        const wav = path.join(tmp, 'v.wav');
+        const f = spawnSync('ffmpeg', ['-y', '-v', 'error', '-i', mp3, '-ar', '16000', '-ac', '1', wav], { encoding: 'utf8' });
+        if (f.status !== 0) return { ok: false, error: 'ffmpeg não converteu a voz: ' + String(f.stderr).slice(-200) };
+        const base = path.join(tmp, 'w');
+        const w = spawnSync(bin, ['-m', modelo, '-f', wav, '-l', lingua, '-ojf', '-ml', '1', '-sow', '-of', base], { encoding: 'utf8', timeout: 5 * 60000 });
+        if (w.status !== 0 || !fs.existsSync(base + '.json')) return { ok: false, error: 'whisper falhou: ' + String(w.stderr).slice(-200) };
+        return { ok: true, palavras: lerJsonDoWhisper(JSON.parse(fs.readFileSync(base + '.json', 'utf8'))) };
+    } catch (e) {
+        return { ok: false, error: e.message };
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+// ── o alinhamento ────────────────────────────────────────────────────────
+
+function lev(a, b) {
+    const m = a.length, n = b.length;
+    if (Math.abs(m - n) > 2) return 9;
+    let ant = Array.from({ length: n + 1 }, (_, j) => j);
+    for (let i = 1; i <= m; i++) {
+        const cur = [i];
+        for (let j = 1; j <= n; j++) cur[j] = Math.min(ant[j] + 1, cur[j - 1] + 1, ant[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        ant = cur;
+    }
+    return ant[n];
+}
+/** 0 = diferente, 1 = parecida, 2 = igual. */
+function parecidas(a, b) {
+    if (!a || !b) return 0;
+    if (a === b) return 2;
+    if (Math.min(a.length, b.length) >= 4 && (lev(a, b) <= 1 || a.startsWith(b) || b.startsWith(a))) return 1;
+    return 0;
+}
+
+/** Casa as palavras do roteiro com as do whisper (programação dinâmica) e interpola as que ficaram sem par. */
+function alinhar(roteiro, ouvidas, dur) {
+    const R = roteiro.length, O = ouvidas.length;
+    const tempos = new Array(R).fill(null);
+    if (R && O) {
+        const D = Array.from({ length: R + 1 }, () => new Array(O + 1).fill(0));
+        for (let i = 1; i <= R; i++) for (let j = 1; j <= O; j++) {
+            const s = parecidas(roteiro[i - 1].n, ouvidas[j - 1].n);
+            D[i][j] = Math.max(D[i - 1][j], D[i][j - 1], s ? D[i - 1][j - 1] + s : 0);
+        }
+        let i = R, j = O;
+        while (i > 0 && j > 0) {
+            const s = parecidas(roteiro[i - 1].n, ouvidas[j - 1].n);
+            if (s && D[i][j] === D[i - 1][j - 1] + s) { tempos[i - 1] = ouvidas[j - 1]; i--; j--; }
+            else if (D[i - 1][j] >= D[i][j - 1]) i--;
+            else j--;
+        }
+    }
+    const casadas = tempos.filter(Boolean).length;
+    // interpola as sem par entre vizinhas casadas (ou pelas pontas: 0 e a duração)
+    const out = roteiro.map((p, i) => ({ ...p, t: tempos[i] ? tempos[i].t : null, t2: tempos[i] ? tempos[i].t2 : null, casada: !!tempos[i] }));
+    let i = 0;
+    while (i < R) {
+        if (out[i].t != null) { i++; continue; }
+        let j = i; while (j < R && out[j].t == null) j++;
+        const a = i > 0 ? out[i - 1].t2 : 0.15, b = j < R ? out[j].t : Math.max(a, dur - 0.1);
+        const passo = (b - a) / (j - i);
+        for (let k = i; k < j; k++) { out[k].t = r3(a + passo * (k - i)); out[k].t2 = r3(a + passo * (k - i + 1)); }
+        i = j;
+    }
+    return { palavras: out, casadas, total: R };
+}
+
+/** Só com a duração: reparte o tempo pelas letras (a reserva se o whisper falhar). */
+function alinharProporcional(roteiro, dur) {
+    const pesos = roteiro.map((p) => p.n.length + 2 + (p.pausa ? 4 : 0));
+    const soma = pesos.reduce((a, b) => a + b, 0) || 1;
+    let t = 0.15;
+    const util = Math.max(0.5, dur - 0.3);
+    return roteiro.map((p, i) => { const d = util * pesos[i] / soma; const o = { ...p, t: r3(t), t2: r3(t + d * 0.85), casada: false }; t += d; return o; });
+}
+
+function cenasDasPalavras(palavras, nCenas, dur) {
+    const cenas = [];
+    for (let c = 0; c < nCenas; c++) {
+        const idx = []; palavras.forEach((p, i) => { if (p.cena === c) idx.push(i); });
+        cenas.push({ idx });
+    }
+    // cena sem fala herda o instante da anterior (dura até a próxima)
+    const inicios = cenas.map((c, k) => (c.idx.length ? Math.max(0, palavras[c.idx[0]].t - 0.2) : null));
+    let ult = 0; for (let k = 0; k < inicios.length; k++) { if (inicios[k] == null) inicios[k] = ult; else ult = inicios[k]; }
+    inicios[0] = 0;
+    return cenas.map((c, k) => ({
+        inicio: r3(inicios[k]),
+        fim: r3(k < cenas.length - 1 ? inicios[k + 1] : dur + 0.5),
+        palavras: c.idx,
+    }));
+}
+
+// ── a voz ────────────────────────────────────────────────────────────────
+
+function sondar(arq) {
+    const r = spawnSync('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=nw=1:nk=1', arq], { encoding: 'utf8' });
+    const d = parseFloat(String(r.stdout || '').trim());
+    return isNaN(d) ? null : d;
+}
+
+function pyNarrar(texto, mp3, voz) {
+    return new Promise((resolve) => {
+        const p = spawn('python3', [NARRAR_PY, 'falar', '--texto', texto, '--saida', mp3, '--voz', String(voz || 'francisca')]);
+        let saida = '', erro = '';
+        p.stdout.on('data', (d) => { saida += d; }); p.stderr.on('data', (d) => { erro += d; });
+        const rel = setTimeout(() => { try { p.kill(); } catch { /* já foi */ } }, 5 * 60000);
+        p.on('close', () => { clearTimeout(rel); try { const r = JSON.parse(saida.trim().split('\n').pop()); resolve({ ...r, motor: 'narrar.py/' + (r.motor || '?') }); } catch { resolve({ ok: false, error: (erro || saida).slice(-300) }); } });
+        p.on('error', (e) => { clearTimeout(rel); resolve({ ok: false, error: e.message }); });
+    });
+}
+
+/** A cadeia local: VoiceStudio → narrar.py → Kokoro → say. Devolve {ok, motor}. */
+async function cadeiaLocal(texto, mp3, voz) {
+    fs.mkdirSync(path.dirname(mp3), { recursive: true });
+    try {
+        const vs = require('./voicestudio.js');
+        if (!process.env.PRIMOCODE_SEM_VOICESTUDIO && await vs.disponivel()) {
+            const r = await vs.falar(texto, { voz: voz && voz !== 'francisca' ? voz : undefined });
+            if (r.ok) { fs.writeFileSync(mp3, r.audio); return { ok: true, motor: 'voicestudio' }; }
+        }
+    } catch { /* segue a cadeia */ }
+    if (fs.existsSync(NARRAR_PY)) {
+        const r = await pyNarrar(texto, mp3, voz);
+        if (r.ok && fs.existsSync(mp3)) return r;
+    }
+    try {
+        const k = require('./kokoro.js');
+        const uv = ['/Users/' + os.userInfo().username + '/.local/bin/uv', '/opt/homebrew/bin/uv'].find((x) => fs.existsSync(x));
+        if (uv) { const r = await k.narrar([{ texto }], mp3, { voz, uv }); if (r && r.ok && fs.existsSync(mp3)) return { ok: true, motor: 'kokoro' }; }
+    } catch { /* segue */ }
+    if (process.platform === 'darwin') {
+        const aiff = mp3.replace(/\.mp3$/, '.aiff');
+        const s = spawnSync('say', ['-v', 'Luciana', '-o', aiff, texto]);
+        if (s.status === 0 && spawnSync('ffmpeg', ['-y', '-v', 'error', '-i', aiff, mp3]).status === 0) { fs.rmSync(aiff, { force: true }); return { ok: true, motor: 'say' }; }
+    }
+    return { ok: false, error: 'nenhuma voz disponível (VoiceStudio, narrar.py, Kokoro, say)' };
+}
+
+/**
+ * A narração do vídeo todo + o instante de cada palavra.
+ * `narrar(texto, mp3, voz)` e `whisper(mp3)` são injetáveis (testes). `whisper` devolve {ok, palavras:[{w,n,t,t2}]}.
+ */
+async function falarEMedirUnico({ falas, pasta, voz, narrar, whisper } = {}) {
+    if (!Array.isArray(falas) || !falas.some((f) => String(f || '').trim())) return { ok: false, error: 'não há fala para narrar.' };
+    if (!pasta) return { ok: false, error: 'faltou a pasta do projeto.' };
+    const mp3 = path.join(pasta, 'midia', 'voz-motion.mp3');
+    fs.mkdirSync(path.dirname(mp3), { recursive: true });
+    const texto = textoDaNarracao(falas);
+    let motor = 'injetada';
+    // mesma fala, mesma voz: reaproveita o áudio (a voz premium custa crédito a cada chamada)
+    const marca = mp3.replace(/\.mp3$/, '.fala.json'), assinatura = JSON.stringify({ texto, voz: voz || null });
+    let r;
+    try { if (!narrar && fs.existsSync(mp3) && fs.readFileSync(marca, 'utf8') === assinatura) r = { ok: true, motor: 'cache' }; } catch { /* sem marca: narra */ }
+    if (!r) {
+        r = narrar ? await narrar(texto, mp3, voz) : await cadeiaLocal(texto, mp3, voz);
+        if (r && r.ok !== false && fs.existsSync(mp3)) { try { fs.writeFileSync(marca, assinatura); } catch { /* sem cache */ } }
+    }
+    if (!r || r.ok === false || !fs.existsSync(mp3)) return { ok: false, error: 'a narração falhou: ' + ((r && r.error) || 'sem áudio') };
+    if (r.motor) motor = r.motor;
+    const dur = sondar(mp3);
+    if (!dur) return { ok: false, error: 'não consegui medir a duração da voz.' };
+
+    const roteiro = palavrasDoRoteiro(falas);
+    const w = whisper ? await whisper(mp3) : medirComWhisper(mp3);
+    let palavras, casadas = 0, medido = false;
+    if (w && w.ok && w.palavras && w.palavras.length) {
+        const a = alinhar(roteiro, w.palavras, dur);
+        palavras = a.palavras; casadas = a.casadas; medido = true;
+        // whisper que ouviu bem menos da metade: o alinhamento é chute, melhor a divisão proporcional
+        if (a.casadas < roteiro.length * 0.4) { palavras = alinharProporcional(roteiro, dur); medido = false; casadas = 0; }
+    } else palavras = alinharProporcional(roteiro, dur);
+    // o tempo nunca anda para trás
+    for (let i = 1; i < palavras.length; i++) if (palavras[i].t < palavras[i - 1].t) { palavras[i].t = palavras[i - 1].t; if (palavras[i].t2 < palavras[i].t) palavras[i].t2 = palavras[i].t; }
+    const limpas = palavras.map(({ w: pw, n, t, t2, cena, chave, pausa, casada }) => ({ w: pw, n, t, t2, cena, chave, pausa, casada }));
+    return { ok: true, mp3, dur: r3(dur), palavras: limpas, cenas: cenasDasPalavras(limpas, falas.length, dur), motor, medido, casadas, total: roteiro.length };
+}
+
+
+// ── a narração por FRASES (Joel, 18/10: "a voz está rápida/emendada") ─────────
+
+const UNIDADES = ['zero', 'um', 'dois', 'três', 'quatro', 'cinco', 'seis', 'sete', 'oito', 'nove', 'dez', 'onze', 'doze', 'treze', 'catorze', 'quinze', 'dezesseis', 'dezessete', 'dezoito', 'dezenove'];
+const DEZENAS = ['', '', 'vinte', 'trinta', 'quarenta', 'cinquenta', 'sessenta', 'setenta', 'oitenta', 'noventa'];
+const CENTENAS = ['', 'cento', 'duzentos', 'trezentos', 'quatrocentos', 'quinhentos', 'seiscentos', 'setecentos', 'oitocentos', 'novecentos'];
+/** O número por extenso em português (0 a 999.999), para a voz não tropeçar em "1.840". */
+function porExtenso(n) {
+    n = Math.floor(n);
+    if (n < 20) return UNIDADES[n];
+    if (n < 100) return DEZENAS[Math.floor(n / 10)] + (n % 10 ? ' e ' + UNIDADES[n % 10] : '');
+    if (n === 100) return 'cem';
+    if (n < 1000) return CENTENAS[Math.floor(n / 100)] + (n % 100 ? ' e ' + porExtenso(n % 100) : '');
+    if (n < 1000000) {
+        const m = Math.floor(n / 1000), r = n % 1000;
+        return (m === 1 ? 'mil' : porExtenso(m) + ' mil') + (r ? (r < 100 || r % 100 === 0 ? ' e ' : ' ') + porExtenso(r) : '');
+    }
+    return String(n);
+}
+/** A grafia de pronúncia por tentativa: 1 = o roteiro; 2 = números, %, R$ e horas por extenso; 3 = também sem pontuação rara. */
+function ajustarGrafia(texto, tentativa) {
+    let t = String(texto);
+    if (tentativa >= 2) {
+        t = t.replace(/R\$\s*([\d.]+)(?:,(\d+))?/g, (_, a) => porExtenso(parseInt(a.replace(/\./g, ''), 10)) + ' reais')
+            .replace(/(\d+)\s*%/g, (_, a) => porExtenso(parseInt(a, 10)) + ' por cento')
+            .replace(/(\d{1,2})[:h](\d{2})/g, (_, h, m) => porExtenso(parseInt(h, 10)) + (parseInt(m, 10) ? ' e ' + porExtenso(parseInt(m, 10)) : ' horas'))
+            .replace(/\b(\d{1,3}(?:\.\d{3})+|\d+)\b/g, (_, a) => porExtenso(parseInt(a.replace(/\./g, ''), 10)));
+    }
+    if (tentativa >= 3) t = t.replace(/[—–"“”«»()]/g, ',').replace(/\s*[:;]\s*/g, ', ').replace(/\s+/g, ' ');
+    return t;
+}
+/** As frases de uma fala (uma frase por arquivo). */
+function frasesDe(fala) {
+    return String(fala || '').replace(/\s+/g, ' ').trim().split(/(?<=[.!?…])\s+/).map((x) => x.trim()).filter((x) => norm(x));
+}
+/** Quanto do roteiro o whisper reconheceu: razão de palavras casadas (LCS aproximada pelo alinhamento) 0–1. */
+function similaridadeFala(roteiroTexto, ouvidas) {
+    const R = String(roteiroTexto).replace(/\*/g, '').split(/\s+/).map(norm).filter(Boolean);
+    const O = (ouvidas || []).map((x) => x.n || norm(x.w)).filter(Boolean);
+    if (!R.length) return 1;
+    const D = Array.from({ length: R.length + 1 }, () => new Array(O.length + 1).fill(0));
+    for (let i = 1; i <= R.length; i++) for (let j = 1; j <= O.length; j++) D[i][j] = Math.max(D[i - 1][j], D[i][j - 1], parecidas(R[i - 1], O[j - 1]) ? D[i - 1][j - 1] + 1 : 0);
+    return D[R.length][O.length] / Math.max(R.length, 1);
+}
+const hashCurto = (s) => { let h = 5381; for (const c of String(s)) h = ((h * 33) ^ c.charCodeAt(0)) >>> 0; return h.toString(36); };
+
+/**
+ * A narração por frases: cada frase vira um arquivo (cache por texto+voz), conferida com o whisper (reconhecido ≥ 90% do roteiro, senão
+ * regenera com outra grafia, até 3 tentativas), desacelerada para 0,95×, e montada com 0,35 s de pausa entre frases e 0,6 s entre partes
+ * (cenas). O tempo de cada palavra vem do whisper de CADA frase, somado ao início dela na montagem.
+ * `narrar(texto, mp3, voz)` e `whisper(mp3)` são injetáveis. Devolve o mesmo formato do falarEMedirUnico + `relatorio`.
+ */
+async function falarEMedir({ falas, pasta, voz, narrar, whisper, velocidade = 0.95, pausaFrase = 0.35, pausaParte = 0.6, minimoReconhecido = 0.9 } = {}) {
+    if (!Array.isArray(falas) || !falas.some((f) => String(f || '').trim())) return { ok: false, error: 'não há fala para narrar.' };
+    if (!pasta) return { ok: false, error: 'faltou a pasta do projeto.' };
+    const dir = path.join(pasta, 'midia', 'voz'); fs.mkdirSync(dir, { recursive: true });
+    const frases = [];
+    falas.forEach((f, cena) => frasesDe(f).forEach((texto, k, arr) => frases.push({ cena, texto, ultima: k === arr.length - 1 })));
+    const relatorio = [];
+    const segs = [];
+    let motor = 'injetada';
+    for (const fr of frases) {
+        const limpo = fr.texto.replace(/\*/g, '');
+        const chave = hashCurto(JSON.stringify([limpo, voz || null]));
+        const arq = path.join(dir, `f-${chave}.mp3`), ficha = arq.replace(/\.mp3$/, '.json');
+        let melhor = null;
+        try { if (!narrar && fs.existsSync(arq)) melhor = JSON.parse(fs.readFileSync(ficha, 'utf8')); } catch { melhor = null; }
+        if (melhor && !fs.existsSync(arq)) melhor = null;
+        if (!melhor) {
+            for (let tent = 1; tent <= 3; tent++) {
+                const texto = ajustarGrafia(limpo, tent);
+                const tmp = arq.replace(/\.mp3$/, `.t${tent}.mp3`);
+                const r = narrar ? await narrar(texto, tmp, voz) : await cadeiaLocal(texto, tmp, voz);
+                if (!r || r.ok === false || !fs.existsSync(tmp)) continue;
+                if (r.motor) motor = r.motor;
+                const w = whisper ? await whisper(tmp) : medirComWhisper(tmp);
+                const ouvidas = w && w.ok ? w.palavras : null;
+                const sim = ouvidas ? similaridadeFala(limpo, ouvidas) : 1;   // sem whisper não dá para conferir: aceita
+                const cand = { arquivo: tmp, tentativa: tent, similaridade: Math.round(sim * 100) / 100, ouvidas, dur: sondar(tmp) };
+                if (!melhor || cand.similaridade > melhor.similaridade) melhor = cand;
+                if (sim >= minimoReconhecido) break;
+            }
+            if (!melhor) return { ok: false, error: 'a narração falhou na frase: ' + limpo.slice(0, 60) };
+            fs.copyFileSync(melhor.arquivo, arq);
+            melhor = { ...melhor, arquivo: arq };
+            for (const f of fs.readdirSync(dir)) if (/\.t\d\.mp3$/.test(f) && f.startsWith(path.basename(arq, '.mp3'))) fs.rmSync(path.join(dir, f), { force: true });
+            if (!narrar) { try { fs.writeFileSync(ficha, JSON.stringify({ ...melhor, ouvidas: melhor.ouvidas })); } catch { /* sem cache */ } }
+        }
+        relatorio.push({ cena: fr.cena, texto: limpo, tentativa: melhor.tentativa, similaridade: melhor.similaridade, ok: melhor.similaridade >= minimoReconhecido });
+        segs.push({ ...fr, arq, ouvidas: melhor.ouvidas, dur: melhor.dur || sondar(arq) });
+    }
+    // a montagem: atempo, cabeça de 0,04 s e rabo de 0,06 s (nenhuma sílaba cortada) + as pausas
+    const SR = 48000, trab = path.join(dir, 'mont'); fs.mkdirSync(trab, { recursive: true });
+    const partes = []; let t = 0.15; const inicios = [];
+    const silencio = (seg, nome) => { const f = path.join(trab, nome + '.wav'); spawnSync('ffmpeg', ['-y', '-v', 'error', '-f', 'lavfi', '-i', `anullsrc=r=${SR}:cl=mono`, '-t', String(seg), f]); return f; };
+    partes.push(silencio(0.15, 'ini'));
+    segs.forEach((s, i) => {
+        const w = path.join(trab, `s${i}.wav`);
+        spawnSync('ffmpeg', ['-y', '-v', 'error', '-i', s.arq, '-ac', '1', '-ar', String(SR), '-af', `atempo=${velocidade},adelay=40|40,apad=pad_dur=0.06`, w]);
+        const d = sondar(w) || (s.dur / velocidade + 0.1);
+        inicios.push(t); partes.push(w); t += d;
+        const pausa = s.ultima ? pausaParte : pausaFrase;
+        if (i < segs.length - 1) { partes.push(silencio(pausa, `p${i}`)); t += pausa; }
+    });
+    const lista = path.join(trab, 'lista.txt');
+    fs.writeFileSync(lista, partes.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join('\n'));
+    const mp3 = path.join(pasta, 'midia', 'voz-motion.mp3');
+    const cc = spawnSync('ffmpeg', ['-y', '-v', 'error', '-f', 'concat', '-safe', '0', '-i', lista, '-ar', String(SR), '-ac', '1', '-b:a', '192k', mp3]);
+    fs.rmSync(trab, { recursive: true, force: true });
+    if (cc.status !== 0 || !fs.existsSync(mp3)) return { ok: false, error: 'não consegui montar a narração.' };
+    const dur = sondar(mp3);
+    // o tempo de cada palavra: o whisper da frase (÷ velocidade) + o início da frase na montagem
+    const roteiroTodo = palavrasDoRoteiro(falas);
+    const palavras = []; let cursor = 0, medidos = 0;
+    segs.forEach((s, i) => {
+        const rot = roteiroTodo.slice(cursor, cursor + palavrasDoRoteiro([s.texto]).length);
+        cursor += rot.length;
+        rot.forEach((p) => { p.cena = s.cena; });
+        const ouvidas = (s.ouvidas || []).map((o) => ({ ...o, t: r3(o.t / velocidade + 0.04), t2: r3(o.t2 / velocidade + 0.04) }));
+        const durSeg = s.dur / velocidade + 0.1;
+        let al;
+        if (ouvidas.length) { const a = alinhar(rot, ouvidas, durSeg); al = a.palavras; if (a.casadas >= rot.length * 0.4) medidos++; else al = alinharProporcional(rot, durSeg); }
+        else al = alinharProporcional(rot, durSeg);
+        al.forEach((p) => palavras.push({ ...p, t: r3(p.t + inicios[i]), t2: r3(p.t2 + inicios[i]), cena: s.cena }));
+    });
+    for (let i = 1; i < palavras.length; i++) if (palavras[i].t < palavras[i - 1].t) { palavras[i].t = palavras[i - 1].t; if (palavras[i].t2 < palavras[i].t) palavras[i].t2 = palavras[i].t; }
+    const limpas = palavras.map(({ w: pw, n, t: tt, t2, cena, chave, pausa, casada }) => ({ w: pw, n, t: tt, t2, cena, chave, pausa, casada }));
+    return { ok: true, mp3, dur: r3(dur), palavras: limpas, cenas: cenasDasPalavras(limpas, falas.length, dur), motor, medido: medidos > 0, casadas: limpas.filter((p) => p.casada).length, total: limpas.length, relatorio, velocidade, pausas: { frase: pausaFrase, parte: pausaParte } };
+}
+
+// ── legenda e consulta ───────────────────────────────────────────────────
+
+/** Agrupa as palavras para a legenda numa FRASE falada de até `maxCar` caracteres (nunca uma palavra solta): quebra em pontuação final,
+ *  em pausa de mais de 0,45 s, ou quando passaria do limite. `max` (palavras) fica como teto de segurança. */
+function legendaChunks(palavras, { max = 12, maxCar = 64 } = {}) {
+    const out = [];
+    let atual = null, car = 0;
+    palavras.forEach((p, i) => {
+        const prev = palavras[i - 1];
+        const novoCar = car + (atual ? 1 : 0) + p.w.length;
+        const quebra = !atual || atual.palavras.length >= max || novoCar > maxCar || (prev && (/[.!?;:]$/.test(prev.w) || p.t - prev.t2 > 0.45 || p.cena !== prev.cena));
+        if (quebra) { atual = { t: p.t, t2: p.t2, cena: p.cena, palavras: [] }; out.push(atual); car = 0; }
+        car += (atual.palavras.length ? 1 : 0) + p.w.length;
+        atual.palavras.push({ w: p.w, t: p.t, t2: p.t2, chave: !!p.chave });
+        atual.t2 = p.t2;
+    });
+    // frases de uma palavra só se juntam à vizinha da mesma cena (legenda nunca solta uma palavra)
+    for (let i = 0; i < out.length; i++) {
+        if (out[i].palavras.length === 1) {
+            const v = out[i + 1] && out[i + 1].cena === out[i].cena ? i + 1 : (out[i - 1] && out[i - 1].cena === out[i].cena ? i - 1 : -1);
+            if (v >= 0 && out[v].palavras.map((x) => x.w).join(' ').length + out[i].palavras[0].w.length < maxCar + 8) {
+                if (v > i) { out[v].palavras.unshift(out[i].palavras[0]); out[v].t = out[i].t; } else { out[v].palavras.push(out[i].palavras[0]); out[v].t2 = out[i].t2; }
+                out.splice(i, 1); i--;
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * O instante (s) em que `trecho` (1 ou mais palavras) é dito, ou null. `cena` limita a busca à cena;
+ * `depoisDe` (s) ignora o que foi dito antes.
+ */
+function tempoDaPalavra(palavras, trecho, { cena = null, depoisDe = -1 } = {}) {
+    const alvo = String(trecho || '').replace(/\*/g, '').split(/\s+/).map(norm).filter(Boolean);
+    if (!alvo.length) return null;
+    const lista = palavras.filter((p) => (cena == null || p.cena === cena) && p.t >= depoisDe);
+    for (let i = 0; i + alvo.length <= lista.length; i++) {
+        if (alvo.every((a, k) => parecidas(a, lista[i + k].n))) return lista[i].t;
+    }
+    // o trecho todo não bateu: a primeira palavra que tem peso (mais de 3 letras)
+    for (const a of alvo.filter((x) => x.length > 3)) {
+        const p = lista.find((q) => parecidas(a, q.n));
+        if (p) return p.t;
+    }
+    return null;
+}
+
+module.exports = { falarEMedirUnico, porExtenso, ajustarGrafia, frasesDe, similaridadeFala, falarEMedir, legendaChunks, tempoDaPalavra, medirComWhisper, alinhar, alinharProporcional, palavrasDoRoteiro, textoDaNarracao, lerJsonDoWhisper, cenasDasPalavras, cadeiaLocal, norm };