@ignix-social/editor 0.1.3 → 0.1.5

package/src/analysis/image.mjs

@@ -0,0 +1,123 @@
+// Operaciones de imagen en RGB (uint8, intercalado) para preparar la entrada de los modelos.
+
+/** Reescalado bilineal de un RGB intercalado. */
+export function resize(rgb, w, h, W, H) {
+  const out = new Uint8Array(W * H * 3);
+  const sx = w / W;
+  const sy = h / H;
+  for (let y = 0; y < H; y++) {
+    const fy = Math.max(0, (y + 0.5) * sy - 0.5);
+    const y0 = Math.min(h - 1, Math.floor(fy));
+    const y1 = Math.min(h - 1, y0 + 1);
+    const dy = fy - y0;
+    for (let x = 0; x < W; x++) {
+      const fx = Math.max(0, (x + 0.5) * sx - 0.5);
+      const x0 = Math.min(w - 1, Math.floor(fx));
+      const x1 = Math.min(w - 1, x0 + 1);
+      const dx = fx - x0;
+      const o = (y * W + x) * 3;
+      for (let c = 0; c < 3; c++) {
+        const a = rgb[(y0 * w + x0) * 3 + c];
+        const b = rgb[(y0 * w + x1) * 3 + c];
+        const d = rgb[(y1 * w + x0) * 3 + c];
+        const e = rgb[(y1 * w + x1) * 3 + c];
+        out[o + c] = Math.round((a * (1 - dx) + b * dx) * (1 - dy) + (d * (1 - dx) + e * dx) * dy);
+      }
+    }
+  }
+  return out;
+}
+
+// Núcleo cúbico de Keys (a = -0.5), el del reescalado «bicúbico» de PIL que usa CLIP.
+const cubic = (x) => {
+  const a = -0.5;
+  x = Math.abs(x);
+  if (x <= 1) return ((a + 2) * x - (a + 3)) * x * x + 1;
+  if (x < 2) return (((x - 5) * x + 8) * x - 4) * a;
+  return 0;
+};
+
+/** Reescalado bicúbico separable con antialias al reducir (como PIL). */
+export function resizeBicubic(rgb, w, h, W, H) {
+  const pass = (src, sw, sh, dw, horizontal) => {
+    const len = horizontal ? sw : sh;
+    const out = new Float32Array(horizontal ? dw * sh * 3 : sw * dw * 3);
+    const scale = len / dw;
+    const support = 2 * Math.max(1, scale);
+    const fscale = Math.max(1, scale);
+    for (let i = 0; i < dw; i++) {
+      const center = (i + 0.5) * scale;
+      const lo = Math.max(0, Math.floor(center - support));
+      const hi = Math.min(len, Math.ceil(center + support));
+      const ws = [];
+      let sum = 0;
+      for (let j = lo; j < hi; j++) {
+        const wgt = cubic((j + 0.5 - center) / fscale);
+        ws.push(wgt);
+        sum += wgt;
+      }
+      for (let k = 0; k < ws.length; k++) ws[k] /= sum || 1;
+      const lines = horizontal ? sh : sw;
+      for (let l = 0; l < lines; l++) {
+        for (let c = 0; c < 3; c++) {
+          let acc = 0;
+          for (let j = lo, k = 0; j < hi; j++, k++) {
+            const idx = horizontal ? (l * sw + j) * 3 + c : (j * sw + l) * 3 + c;
+            acc += src[idx] * ws[k];
+          }
+          const o = horizontal ? (l * dw + i) * 3 + c : (i * sw + l) * 3 + c;
+          out[o] = acc;
+        }
+      }
+    }
+    return out;
+  };
+  const a = pass(rgb, w, h, W, true); // W × h
+  const b = pass(a, W, h, H, false); // W × H
+  const out = new Uint8Array(W * H * 3);
+  for (let i = 0; i < out.length; i++) out[i] = Math.max(0, Math.min(255, Math.round(b[i])));
+  return out;
+}
+
+/** Tensor CHW float32 con normalización por canal (`mean`, `std` en la escala dada). */
+export function toCHW(rgb, w, h, { scale = 1, mean = [0, 0, 0], std = [1, 1, 1], bgr = false } = {}) {
+  const out = new Float32Array(3 * w * h);
+  const plane = w * h;
+  for (let i = 0; i < plane; i++) {
+    for (let c = 0; c < 3; c++) {
+      const src = rgb[i * 3 + (bgr ? 2 - c : c)];
+      out[c * plane + i] = (src * scale - mean[c]) / std[c];
+    }
+  }
+  return out;
+}
+
+/** Pega la imagen arriba a la izquierda de un lienzo `S`×`S` relleno de `fill` (letterbox). */
+export function letterbox(rgb, w, h, S, fill = 114) {
+  const r = Math.min(S / w, S / h);
+  const nw = Math.max(1, Math.round(w * r));
+  const nh = Math.max(1, Math.round(h * r));
+  const small = resize(rgb, w, h, nw, nh);
+  const out = new Uint8Array(S * S * 3).fill(fill);
+  for (let y = 0; y < nh; y++) out.set(small.subarray(y * nw * 3, (y + 1) * nw * 3), y * S * 3);
+  return { rgb: out, r };
+}
+
+/** Supresión de no máximos sobre cajas {x,y,w,h,score}. */
+export function nms(boxes, iou = 0.5) {
+  const sorted = [...boxes].sort((a, b) => b.score - a.score);
+  const keep = [];
+  for (const b of sorted) {
+    if (keep.every((k) => overlap(k, b) <= iou)) keep.push(b);
+  }
+  return keep;
+}
+
+function overlap(a, b) {
+  const x0 = Math.max(a.x, b.x);
+  const y0 = Math.max(a.y, b.y);
+  const x1 = Math.min(a.x + a.w, b.x + b.w);
+  const y1 = Math.min(a.y + a.h, b.y + b.h);
+  const inter = Math.max(0, x1 - x0) * Math.max(0, y1 - y0);
+  return inter / (a.w * a.h + b.w * b.h - inter || 1);
+}

package/src/analysis/media.mjs

@@ -0,0 +1,152 @@
+// Leer vídeo, fotos y audio con el ffmpeg del Editor: datos del fichero, fotogramas
+// muestreados en RGB (para los modelos) y el sonido como muestras (para medirlo).
+import { spawn, spawnSync } from 'node:child_process';
+
+/** Duración, fotogramas por segundo, tamaño y si tiene audio. */
+export function probe(ffprobe, path) {
+  const r = spawnSync(ffprobe, ['-v', 'error', '-print_format', 'json', '-show_format', '-show_streams', path], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (r.status !== 0) throw new Error(`Could not read ${path}: ${(r.stderr || '').slice(-200)}`);
+  const j = JSON.parse(r.stdout);
+  const v = (j.streams ?? []).find((s) => s.codec_type === 'video');
+  const rate = (s) => {
+    const [a, b] = String(s ?? '0/1').split('/').map(Number);
+    return b ? a / b : 0;
+  };
+  // Vídeo grabado con el móvil en vertical: el giro va en los metadatos.
+  const rot = Math.abs(Number(v?.tags?.rotate ?? (v?.side_data_list ?? []).find((d) => d.rotation !== undefined)?.rotation ?? 0)) % 180 === 90;
+  return {
+    duration: Number(j.format?.duration ?? v?.duration ?? 0) || 0,
+    fps: rate(v?.avg_frame_rate) || rate(v?.r_frame_rate) || 30,
+    width: rot ? v?.height ?? 0 : v?.width ?? 0,
+    height: rot ? v?.width ?? 0 : v?.height ?? 0,
+    hasVideo: !!v,
+    hasAudio: (j.streams ?? []).some((s) => s.codec_type === 'audio'),
+  };
+}
+
+/** Tamaño de trabajo que cabe en `max` px de lado manteniendo la proporción (par). */
+export function fitSize(w, h, max) {
+  const s = Math.min(1, max / Math.max(w, h));
+  return { w: Math.max(2, Math.round((w * s) / 2) * 2), h: Math.max(2, Math.round((h * s) / 2) * 2) };
+}
+
+/**
+ * Fotogramas del vídeo a `fps` por segundo (o uno, si es una foto), en RGB y a un tamaño de
+ * trabajo de como mucho `max` px. Llama a `onFrame({ t, w, h, rgb })` en orden; si devuelve
+ * `false`, para. `start`/`end` acotan un tramo (segundos).
+ */
+export function frames(ffmpeg, path, { fps = 2, max = 640, width, height, start = 0, end = null, still = false, onFrame }) {
+  const { w, h } = fitSize(width, height, max);
+  const args = ['-nostdin', '-hide_banner', '-loglevel', 'error'];
+  if (start > 0) args.push('-ss', start.toFixed(3));
+  args.push('-i', path);
+  if (end !== null) args.push('-t', Math.max(0.05, end - start).toFixed(3));
+  const vf = still ? `scale=${w}:${h}` : `fps=${fps},scale=${w}:${h}`;
+  args.push('-an', '-vf', vf, ...(still ? ['-frames:v', '1'] : []), '-f', 'rawvideo', '-pix_fmt', 'rgb24', 'pipe:1');
+  const size = w * h * 3;
+  return new Promise((resolve, reject) => {
+    const p = spawn(ffmpeg, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let buf = Buffer.alloc(0);
+    let k = 0;
+    let stopped = false;
+    let err = '';
+    let chain = Promise.resolve();
+    p.stderr.on('data', (d) => (err = (err + d).slice(-400)));
+    p.stdout.on('data', (d) => {
+      if (stopped) return;
+      buf = buf.length ? Buffer.concat([buf, d]) : d;
+      while (buf.length >= size && !stopped) {
+        const rgb = buf.subarray(0, size);
+        buf = buf.subarray(size);
+        // El fps de ffmpeg toma el fotograma de cada tramo de 1/fps: su instante es el centro.
+        const t = still ? 0 : start + (k + 0.5) / fps;
+        k += 1;
+        const copy = Buffer.from(rgb);
+        chain = chain.then(async () => {
+          if (stopped) return;
+          if ((await onFrame({ t, w, h, rgb: copy })) === false) {
+            stopped = true;
+            p.kill();
+          }
+        });
+        // Con muchos fotogramas en cola, que ffmpeg espere (memoria acotada).
+        p.stdout.pause();
+        chain.then(() => p.stdout.resume(), () => p.stdout.resume());
+      }
+    });
+    p.on('error', reject);
+    p.on('close', (code) => {
+      chain.then(() => {
+        if (code !== 0 && !stopped && k === 0) reject(new Error(`Could not read the frames of ${path}: ${err.trim()}`));
+        else resolve({ count: k, w, h });
+      }, reject);
+    });
+  });
+}
+
+/**
+ * El sonido como muestras float32 mono a `rate` Hz, en bloques. `start`/`end` acotan un tramo.
+ * Devuelve false si el fichero no tiene audio.
+ */
+export function pcm(ffmpeg, path, { rate = 16000, start = 0, end = null, onSamples }) {
+  const args = ['-nostdin', '-hide_banner', '-loglevel', 'error'];
+  if (start > 0) args.push('-ss', start.toFixed(3));
+  args.push('-i', path);
+  if (end !== null) args.push('-t', Math.max(0.05, end - start).toFixed(3));
+  args.push('-vn', '-ac', '1', '-ar', String(rate), '-f', 'f32le', 'pipe:1');
+  return new Promise((resolve, reject) => {
+    const p = spawn(ffmpeg, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let carry = Buffer.alloc(0);
+    let err = '';
+    let any = false;
+    p.stderr.on('data', (d) => (err = (err + d).slice(-400)));
+    p.stdout.on('data', (d) => {
+      any = true;
+      const all = carry.length ? Buffer.concat([carry, d]) : d;
+      const n = Math.floor(all.length / 4);
+      const copy = new Float32Array(n);
+      for (let i = 0; i < n; i++) copy[i] = all.readFloatLE(i * 4);
+      carry = all.subarray(n * 4);
+      try {
+        onSamples(copy);
+      } catch (e) {
+        p.kill();
+        reject(e);
+      }
+    });
+    p.on('error', reject);
+    p.on('close', (code) => {
+      if (!any && /does not contain any stream|Output file .* does not contain|matches no streams/i.test(err)) resolve(false);
+      else if (code !== 0 && !any) reject(new Error(`Could not read the audio of ${path}: ${err.trim()}`));
+      else resolve(true);
+    });
+  });
+}
+
+/** Niveles en dBFS de ventanas de `windowSec` (RMS). */
+export async function levels(ffmpeg, path, { windowSec = 0.05, start = 0, end = null, maxSec = 3600 } = {}) {
+  const rate = 16000;
+  const win = Math.round(rate * windowSec);
+  const out = [];
+  let acc = 0;
+  let n = 0;
+  let seen = 0;
+  const ok = await pcm(ffmpeg, path, {
+    rate,
+    start,
+    end,
+    onSamples: (x) => {
+      seen += x.length;
+      if (seen > maxSec * rate) throw new Error('too long');
+      for (let i = 0; i < x.length; i++) {
+        acc += x[i] * x[i];
+        if (++n === win) {
+          out.push(10 * Math.log10(acc / win + 1e-12));
+          acc = 0;
+          n = 0;
+        }
+      }
+    },
+  });
+  return ok ? out : null;
+}

package/src/analysis/montage.mjs

@@ -0,0 +1,356 @@
+// El material del cliente como un ÍNDICE DE PLANOS, y el montaje que lo usa (ADR-0023 E1):
+//  · analyze: cada vídeo partido en sus planos reales (cambios de escena; una toma larga en
+//    trozos de ~4 s), cada plano con tres fotogramas, su movimiento, dónde está la acción o la
+//    cara, su tamaño de plano y su vector CLIP. Lo ya analizado no se repite.
+//  · edit: para cada momento del guion, el plano que ENSEÑA lo que se dice (CLIP imagen↔texto),
+//    sin repetir fuente seguida, variando el tamaño de plano, y el trozo del plano que mejor
+//    encaja; más planos alternativos para los subplanos.
+//  · review: la línea de tiempo terminada, juzgada (¿parece un pase de diapositivas?, ¿varía?).
+// Reglas propias de Ignix (no se copia código de OpenMontage).
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { dot, embedImage, embedTexts, pool } from './clip.mjs';
+import { faces as detectFaces } from './detect.mjs';
+import { frames, probe } from './media.mjs';
+import { cuts } from './sound.mjs';
+
+const DIM = 512;
+const SHOT_SIZES = ['close-up', 'medium', 'wide'];
+// Frases fijas con las que CLIP compara cada plano (tamaño de plano sin entrenar nada).
+const SIZE_PROMPTS = {
+  'close-up': 'an extreme close-up photo of a detail, a face or hands filling the frame',
+  medium: 'a medium shot photo of a person from the waist up',
+  wide: 'a wide shot photo of a whole room, place or scene',
+};
+const MAX_WINDOWS = 12;
+const TAG_WEIGHT = 0.25;
+const NEAR_DUPLICATE = 0.92;
+
+// ── el índice: index.json + un .f32 por plano con [conjunto, etiqueta, fotogramas…]
+function store(workdir) {
+  const dir = join(workdir, 'editor-corpus');
+  mkdirSync(dir, { recursive: true });
+  const indexPath = join(dir, 'index.json');
+  const index = existsSync(indexPath) ? JSON.parse(readFileSync(indexPath, 'utf8')) : { clips: {} };
+  const vecs = new Map();
+  const file = (id) => join(dir, `${id.replace(/[^\w.-]/g, '_')}.f32`);
+  return {
+    index,
+    save: () => writeFileSync(indexPath, JSON.stringify(index)),
+    put(id, meta, pooled, tag, frameVecs) {
+      const all = new Float32Array(DIM * (2 + frameVecs.length));
+      all.set(pooled, 0);
+      all.set(tag, DIM);
+      frameVecs.forEach((v, i) => all.set(v, DIM * (2 + i)));
+      writeFileSync(file(id), Buffer.from(all.buffer));
+      index.clips[id] = meta;
+      vecs.set(id, all);
+    },
+    vectors(id) {
+      if (!vecs.has(id)) {
+        const b = readFileSync(file(id));
+        vecs.set(id, new Float32Array(b.buffer, b.byteOffset, b.length / 4));
+      }
+      const all = vecs.get(id);
+      const n = all.length / DIM - 2;
+      return {
+        pooled: all.subarray(0, DIM),
+        tag: all.subarray(DIM, 2 * DIM),
+        frames: Array.from({ length: n }, (_, i) => all.subarray(DIM * (2 + i), DIM * (3 + i))),
+      };
+    },
+  };
+}
+
+/** Movimiento (diferencia media de grises, 0–255) entre dos fotogramas y dónde ocurre (0..1). */
+export function motionOf(a, b, w, h) {
+  if (!a || !b) return { motion: 0, focus: null };
+  const cols = new Float64Array(w);
+  let sum = 0;
+  for (let i = 0; i < w * h; i++) {
+    const ga = 0.299 * a[i * 3] + 0.587 * a[i * 3 + 1] + 0.114 * a[i * 3 + 2];
+    const gb = 0.299 * b[i * 3] + 0.587 * b[i * 3 + 1] + 0.114 * b[i * 3 + 2];
+    const d = Math.abs(ga - gb);
+    sum += d;
+    cols[i % w] += d;
+  }
+  const motion = sum / (w * h);
+  let focus = null;
+  if (motion > 2) {
+    let tot = 0;
+    let acc = 0;
+    for (let x = 0; x < w; x++) {
+      tot += cols[x];
+      acc += cols[x] * x;
+    }
+    if (tot > 0) focus = acc / tot / w;
+  }
+  return { motion, focus };
+}
+
+export async function analyze({ ffmpeg, ffprobe, workdir, media, log = () => {} }) {
+  const db = store(workdir);
+  const sizeVecs = await embedTexts(SHOT_SIZES.map((s) => SIZE_PROMPTS[s]), log);
+  const shots = [];
+  for (const m of media) {
+    const { id: asset, kind, path } = m;
+    const label = String(m.label ?? '').trim();
+    let windows = [];
+    let faceSamples = [];
+    let info = null;
+    try {
+      info = probe(ffprobe, path);
+    } catch (e) {
+      log(`analyze ${asset}: ${e.message}`);
+      continue;
+    }
+    if (kind === 'video') {
+      const duration = Number(m.duration) || info.duration;
+      // Dónde está la cara (la más grande) dos veces por segundo: encuadre y tamaño de plano.
+      await frames(ffmpeg, path, {
+        fps: 2,
+        max: 640,
+        width: info.width,
+        height: info.height,
+        onFrame: async (f) => {
+          const found = await detectFaces(f, log);
+          const big = found.sort((a, b) => b.w * b.h - a.w * a.h)[0];
+          if (big) faceSamples.push({ t: f.t, x: big.x + big.w / 2, area: big.w * big.h });
+        },
+      }).catch((e) => log(`faces ${asset}: ${e.message}`));
+      const found = await cuts(ffmpeg, path, { minSec: 0.8, maxSec: 24 * 3600 }).catch(() => []);
+      const bounds = [0, ...found, duration];
+      windows = [];
+      for (let i = 0; i + 1 < bounds.length; i++) if (bounds[i + 1] - bounds[i] >= 0.8) windows.push([bounds[i], bounds[i + 1]]);
+      if (!windows.length && duration > 0) windows = [[0, duration]];
+      // Una toma larga: trozos de ~4 s, para poder elegir cada uno.
+      const split = [];
+      for (const [a, b] of windows) {
+        const n = Math.max(1, Math.floor((b - a) / 4));
+        for (let k = 0; k < n; k++) split.push([a + (k * (b - a)) / n, a + ((k + 1) * (b - a)) / n]);
+      }
+      windows = split.slice(0, MAX_WINDOWS);
+    } else windows = [[0, 0]];
+
+    for (const [k, [a, b]] of windows.entries()) {
+      const clip = `${asset}~${k}`;
+      const known = db.index.clips[clip];
+      if (known) {
+        shots.push({ clip, asset, start: a, end: b, motion: known.motion, size: known.size, focus: known.focus });
+        continue;
+      }
+      const grabbed = [];
+      if (kind === 'video') {
+        await frames(ffmpeg, path, { fps: 3 / Math.max(0.1, b - a), max: 448, width: info.width, height: info.height, start: a, end: b, onFrame: (f) => void grabbed.push(f) }).catch(() => {});
+      } else {
+        await frames(ffmpeg, path, { still: true, max: 448, width: info.width, height: info.height, onFrame: (f) => void grabbed.push(f) }).catch(() => {});
+      }
+      if (!grabbed.length) continue;
+      const g = grabbed.slice(0, 3);
+      let { motion, focus } = kind === 'video' && g.length >= 2 ? motionOf(g[0].rgb, g[Math.floor(g.length / 2)].rgb, g[0].w, g[0].h) : { motion: 0, focus: null };
+      let faceSize = null;
+      const inside = faceSamples.filter((s) => s.t >= a && s.t <= b);
+      if (inside.length) {
+        // Una cara en el plano lo encuadra; si no, dónde está la acción.
+        const tot = inside.reduce((s, x) => s + x.area, 0);
+        focus = inside.reduce((s, x) => s + x.x * x.area, 0) / tot;
+        // El tamaño de la cara en el cuadro ES el tamaño de plano (gramática de montaje).
+        const side = Math.sqrt(Math.max(...inside.map((x) => x.area)));
+        faceSize = side > 0.3 ? 'close-up' : side < 0.1 ? 'wide' : 'medium';
+      } else if (kind !== 'video') {
+        const f = (await detectFaces(g[0], log)).sort((p, q) => q.w * q.h - p.w * p.h)[0];
+        if (f) focus = f.x + f.w / 2;
+      }
+      const frameVecs = [];
+      for (const f of g) frameVecs.push(await embedImage(f, log));
+      const pooled = pool(frameVecs);
+      const [tag] = await embedTexts([label || (kind === 'video' ? 'a video clip' : 'a photo')], log);
+      const size = faceSize ?? SHOT_SIZES[sizeVecs.map((v) => dot(pooled, v)).reduce((bi, v, i, arr) => (v > arr[bi] ? i : bi), 0)];
+      const fx = focus === null || focus === undefined ? null : +Math.min(1, Math.max(0, focus)).toFixed(3);
+      const times = g.map((f) => +f.t.toFixed(3));
+      db.put(clip, { asset, kind, label, start: a, end: b, duration: kind === 'video' ? +(b - a).toFixed(3) : 0, motion, size, focus: fx, times }, pooled, tag, frameVecs);
+      shots.push({ clip, asset, start: a, end: b, motion, size, focus: fx });
+    }
+    db.save();
+  }
+  db.save();
+  return { shots, corpus: Object.keys(db.index.clips).length };
+}
+
+/** El trozo del plano cuyos fotogramas se parecen más al momento. */
+function windowFor(shot, meta, frameVecs, seconds, q) {
+  const a = Number(shot.start);
+  const b = Number(shot.end);
+  if (b - a <= seconds + 0.2) return [a, b];
+  let bestT = (a + b) / 2;
+  if (meta?.times?.length && frameVecs.length) {
+    let best = -Infinity;
+    frameVecs.forEach((v, i) => {
+      const s = dot(v, q);
+      if (s > best) {
+        best = s;
+        bestT = meta.times[i];
+      }
+    });
+  }
+  const start = Math.min(Math.max(a + 0.1, bestT - seconds / 2), b - seconds - 0.05);
+  return [+start.toFixed(2), +(start + seconds).toFixed(2)];
+}
+
+export async function edit({ workdir, shots: given = [], beats, allowed = null, preferred = [], minScore = 0.3, minVisual = 0.24, log = () => {} }) {
+  const db = store(workdir);
+  const shotsById = new Map(given.map((s) => [s.clip, s]));
+  const allow = allowed ? new Set(allowed) : null;
+  const prefer = new Set(preferred);
+  const queries = beats.map((b) => String(b.query ?? '').trim().slice(0, 300) || 'a scene');
+  const qvecs = await embedTexts(queries, log);
+  const clips = Object.entries(db.index.clips).map(([id, meta]) => ({ id, ...meta }));
+  const visual = (id, i) => dot(db.vectors(id).pooled, qvecs[i]);
+
+  // Para cada momento: los planos ordenados por lo que ENSEÑAN (CLIP) y, menos, por su etiqueta.
+  const ranked = beats.map((beat, i) => {
+    const fixed = beat.asset;
+    const floor = Number(beat.min_visual ?? minVisual);
+    return clips
+      .filter((c) => (beat.kind === 'video' || beat.kind === 'image' ? c.kind === beat.kind : true))
+      .filter((c) => !allow || allow.has(c.asset))
+      .filter((c) => !fixed || c.asset === fixed)
+      .map((c) => {
+        const v = db.vectors(c.id);
+        const vis = dot(v.pooled, qvecs[i]);
+        return { score: (1 - TAG_WEIGHT) * vis + TAG_WEIGHT * dot(v.tag, qvecs[i]), visual: vis, clip: c };
+      })
+      .filter((x) => fixed || (x.score >= minScore && x.visual >= floor))
+      .sort((p, q) => q.score - p.score);
+  });
+
+  const used = new Set();
+  const picks = new Array(beats.length).fill(null);
+  const choose = (i, avoid) => {
+    const prev = i > 0 ? picks[i - 1]?.clip : null;
+    const next = i + 1 < picks.length ? picks[i + 1]?.clip : null;
+    const fixed = beats[i].asset;
+    let cands = ranked[i].filter((x) => !used.has(x.clip.id) && !avoid.has(x.clip.id) && (fixed || ((!prev || x.clip.asset !== prev.asset) && (!next || x.clip.asset !== next.asset))));
+    if (!cands.length) return null;
+    // Lo que adjuntaron para esta pieza antes que el resto de su biblioteca.
+    const mine = cands.filter((x) => prefer.has(x.clip.asset));
+    if (mine.length) cands = [...mine, ...cands.filter((x) => !prefer.has(x.clip.asset))];
+    let best = cands[0];
+    // Variar el tamaño de plano cuando hay otro casi igual de bueno.
+    if (prev?.size && best.clip.size === prev.size) {
+      const alt = cands.find((x) => x.score >= best.score - 0.02 && x.clip.size !== prev.size);
+      if (alt) best = alt;
+    }
+    return best;
+  };
+  for (let i = 0; i < beats.length; i++) {
+    picks[i] = choose(i, new Set());
+    if (picks[i]) used.add(picks[i].clip.id);
+  }
+  // Casi duplicados (dos planos que se ven iguales): el segundo se cambia por otro distinto.
+  let swapped = 0;
+  const kept = [];
+  for (let i = 0; i < picks.length; i++) {
+    const p = picks[i];
+    if (!p) continue;
+    const pv = db.vectors(p.clip.id).pooled;
+    const dup = kept.some((id) => dot(db.vectors(id).pooled, pv) > NEAR_DUPLICATE);
+    if (dup && !beats[i].asset) {
+      used.delete(p.clip.id);
+      const alt = choose(i, new Set([p.clip.id, ...kept]));
+      picks[i] = alt ?? p;
+      used.add(picks[i].clip.id);
+      if (alt) swapped += 1;
+    }
+    kept.push(picks[i].clip.id);
+  }
+
+  const cut = (i, x, seconds) => {
+    const c = x.clip;
+    const shot = shotsById.get(c.id) ?? { start: c.start ?? 0, end: c.end ?? c.duration ?? 0 };
+    const [a, b] = c.kind === 'video' ? windowFor(shot, c, db.vectors(c.id).frames, seconds, qvecs[i]) : [0, 0];
+    return {
+      beat: beats[i].beat,
+      asset: c.asset,
+      clip: c.id,
+      kind: c.kind,
+      in: a,
+      out: b,
+      score: +x.score.toFixed(4),
+      visual: +visual(c.id, i).toFixed(4),
+      size: c.size || null,
+      motion: +Number(c.motion || 0).toFixed(2),
+      focus: c.focus ?? null,
+    };
+  };
+  const cutsOut = [];
+  const unmatched = [];
+  picks.forEach((p, i) => (p ? cutsOut.push(cut(i, p, Number(beats[i].seconds))) : unmatched.push(beats[i].beat)));
+  // Planos alternativos (subplanos): fuentes distintas, planos sin usar.
+  const alternates = [];
+  beats.forEach((beat, i) => {
+    const want = Number(beat.alternates ?? 0);
+    if (want <= 0 || beat.asset) return;
+    const seen = new Set([picks[i]?.clip.asset]);
+    const part = Number(beat.seconds) / (want + 1);
+    for (const x of ranked[i]) {
+      if (alternates.filter((a) => a.beat === beat.beat).length >= want) break;
+      if (used.has(x.clip.id) || seen.has(x.clip.asset)) continue;
+      used.add(x.clip.id);
+      seen.add(x.clip.asset);
+      alternates.push(cut(i, x, Math.max(1.2, part)));
+    }
+  });
+  return { cuts: cutsOut, alternates, unmatched, swapped };
+}
+
+/**
+ * Juicio de la línea de tiempo terminada. Riesgo de «pase de diapositivas» (0..1, más alto =
+ * peor) por dimensiones, y variedad con sus fallos concretos.
+ */
+export function review({ scenes }) {
+  const n = scenes.length || 1;
+  const pairs = Math.max(1, scenes.length - 1);
+  const same = (f) => scenes.slice(1).filter((s, i) => f(s) && f(s) === f(scenes[i])).length / pairs;
+  const longestRun = (f) => {
+    let best = 0;
+    let run = 0;
+    scenes.forEach((s, i) => {
+      run = i && f(s) === f(scenes[i - 1]) ? run + 1 : 1;
+      best = Math.max(best, run);
+    });
+    return best;
+  };
+  const dimensions = {
+    still_share: scenes.filter((s) => (s.type === 'still' || s.type === 'text_card') && s.shot_language?.camera_movement === 'static').length / n,
+    text_cards: scenes.filter((s) => s.type === 'text_card').length / n,
+    camera_monotony: same((s) => s.shot_language?.camera_movement),
+    size_monotony: same((s) => (s.shot_language?.shot_size === 'none' ? null : s.shot_language?.shot_size)),
+    type_monotony: longestRun((s) => s.type) / n,
+  };
+  const values = Object.values(dimensions);
+  const average = +(values.reduce((a, b) => a + b, 0) / values.length).toFixed(3);
+  const violations = [];
+  const runs = (label, f, min) => {
+    let run = 1;
+    for (let i = 1; i <= scenes.length; i++) {
+      if (i < scenes.length && f(scenes[i]) && f(scenes[i]) === f(scenes[i - 1])) run += 1;
+      else {
+        if (run >= min) violations.push(`${run} consecutive scenes with the same ${label} (${f(scenes[i - 1])}), ending at ${scenes[i - 1].id}`);
+        run = 1;
+      }
+    }
+  };
+  runs('shot size', (s) => (s.shot_language?.shot_size === 'none' ? null : s.shot_language?.shot_size), 3);
+  runs('camera movement', (s) => s.shot_language?.camera_movement, 3);
+  runs('type', (s) => (s.type === 'text_card' ? 'text_card' : null), 3);
+  const score = +Math.max(0, 1 - violations.length / n).toFixed(3);
+  return {
+    slideshow_risk: {
+      average,
+      verdict: average < 0.35 ? 'low' : average < 0.6 ? 'medium' : 'high',
+      dimensions: Object.fromEntries(Object.entries(dimensions).map(([k, v]) => [k, +v.toFixed(3)])),
+    },
+    variation: { score, verdict: violations.length ? 'needs_variety' : 'varied', violations: violations.slice(0, 6), metadata_only: 0 },
+  };
+}