primocode 10.13.0 → 10.14.0

package/lib/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 };