@ignix-social/editor 0.1.0 → 0.1.2

package/bin/ignix-editor.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 const major = Number(process.versions.node.split('.')[0]);
 if (major < 22) {
-  console.error(`Ignix Editor necesita Node 22 o superior (tienes ${process.versions.node}). Instala la versión LTS desde nodejs.org.`);
+  console.error(`Ignix Editor needs Node 22 or newer (this is ${process.versions.node}). Install the LTS from nodejs.org.`);
   process.exit(1);
 }
 const { main } = await import('../src/cli.mjs');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignix-social/editor",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Ignix Editor: render HTML video compositions (reels, edits, clips) on your own computer. Based on HyperFrames.",
   "license": "Apache-2.0",
   "type": "module",

package/skills/ignix-editor/SKILL.md

@@ -11,11 +11,12 @@ Commands (`npx @ignix-social/editor <cmd>` if `ignix-editor` is not on the PATH)
 
 | Command | What it does |
 |---|---|
-| `ignix-editor doctor` | Node 22+, ffmpeg, whisper, H.264 encoder. Run it first. |
+| `ignix-editor doctor` | Node 22+ and the H.264 encoder; downloads its own ffmpeg and whisper the first time. Run it first. |
 | `ignix-editor init <name>` | Creates `~/ignix-videos/<name>` with a working skeleton, GSAP, local fonts and `ignix-frame.js`. |
 | `ignix-editor transcribe <file> --lang es [--script "…"] -o words.json` | Words with start/end seconds, on this machine. |
+| `ignix-editor faces <video> -o work/faces.json` | Where the face is over time (macOS, Apple Vision): a smoothed path `{t, cx, cy, size}` (0–1, top-left origin) to frame the person. |
 | `ignix-editor check [dir]` | HTML well-formed, no network assets, media rules, layout/contrast/motion audit. |
-| `ignix-editor snapshot [dir] --at 0,1.5,3` | PNG frames into `<dir>/snapshots/` to LOOK at. |
+| `ignix-editor snapshot [dir] --at 0,1.5,3` | PNG frames into `<dir>/snapshots/` to LOOK at. `[dir]` defaults to the current folder. |
 | `ignix-editor render [dir] [-o out.mp4]` | Renders to `<dir>/renders/<dir>.mp4`, audio normalised to −14 LUFS. |
 | `ignix-editor ffmpeg …` / `ffprobe …` | The editor's own ffmpeg (do not rely on a system one). |
 
@@ -94,16 +95,26 @@ Decide the zones once per video (e.g. header y 270–440, stage y 460–1300, ca
 - Transcribe on the machine: `ignix-editor transcribe assets/take.mp4 --lang es -o work/words.json`. Show the user the text and fix obvious mishearings (names, brands) without rewriting what they said.
 - Cuts: one `<video>` per kept range, edge to edge (`data-start` of the next = previous start + duration). Build a map from source time to edited time and pass every word time, zoom, overlay and sound through it.
 - Voice clean-up before building: `ignix-editor ffmpeg -i take.mp4 -vn -ac 1 -ar 48000 -af "highpass=f=80,acompressor=threshold=-22dB:ratio=3:attack=5:release=120:makeup=2" assets/voice.wav`, then one `<audio>` per kept range with `data-media-start` and 8 ms fade lanes, and the videos `muted`.
-- Reframing a horizontal source to 9:16 and following the face: a fixed card/frame element with `overflow:hidden`; inside it a wrapper sized like the card, `transform-origin:0 0`, moved with `translate(-x·z, -y·z) scale(z)` per frame from a face path (one point per frame, smoothed). Zooms multiply `z`.
+- Reframing a horizontal source to 9:16 and following the face: `ignix-editor faces assets/take.mp4 -o work/faces.json` gives a smoothed path (`cx`, `cy` = centre of the face, `size` = its height, all 0–1). Map it through your cut map like the words. Then a fixed card/frame element with `overflow:hidden`; inside it a wrapper sized like the card, `transform-origin:0 0`, moved with `translate(-x·z, -y·z) scale(z)` per frame from that path (interpolate between samples). Zooms multiply `z`.
+- The cover is the first frame: the face AND the hook. If the person is not in shot yet in the first second (sitting down, walking in), use a still of their face from later (`ignix-editor ffmpeg -ss <t> -i take.mp4 -frames:v 1 assets/cover.jpg`) under the hook for ~1 s, with a slow push, then cut to the footage.
+- The same file in two places at once (main shot + a small picture-in-picture window): give the second one its own copy (`cp take.mp4 take-pip.mp4`); `check` flags two simultaneous clips of one file.
 - Blurred background of the same footage: a second set of the same `<video>` elements behind, in a wrapper with `filter: blur(60px) brightness(.32)` and `transform: scale(1.25)`. (Heavy without a GPU: on a machine without one, prefer a pre-blurred copy made with ffmpeg.)
 - Long sources (lives, podcasts) are fine: the editor seeks straight to `data-media-start`.
 
+### The bundled ffmpeg (LGPL)
+
+`ignix-editor ffmpeg` is a licence-clean build: everything you need for audio and simple video prep, but no GPL parts.
+- Encode H.264 with `-c:v h264_videotoolbox -b:v 10M -allow_sw 1` (there is no `libx264` and no `-crf`). AAC audio: `-c:a aac -b:a 192k`.
+- Present: `scale`, `crop`, `pad`, `overlay`, `trim`/`atrim`, `concat`, `gblur`, `avgblur`, `curves`, `lutyuv`, `colorbalance`, `colorchannelmixer`, `fade`, `afade`, `highpass`, `lowpass`, `acompressor`, `loudnorm`, `ebur128`, `silencedetect`, `amix`, `volume`.
+- Missing (GPL): `eq` (use `curves`/`lutyuv` for contrast and warmth), `boxblur` (use `gblur`), `delogo` (cover a burned-in label with a cropped, `gblur`red patch of the same frame placed by `overlay`, or with a card in the HTML).
+- Grading and blur are usually easier in the HTML anyway (CSS `filter: contrast() saturate() blur()`).
+
 ## 4. Audio and captions for reels from scratch
 
 - One `<audio>` per voice line (Ignix `generate_voiceover`), placed back to back with ~0.25 s of air: the scenes follow the voice.
 - Word times: `ignix-editor transcribe assets/vo/l1.wav --lang es --script "<the exact line>" -o work/l1.json`. With `--script` the words are the script's and the times are whisper's (whisper mishears and sometimes drops the last words; the script wins).
 - Anchor every gesture (click, pop, highlight, cut) to a word time: `cue = line.start + word.s`. Sound effects start on their gesture.
-- Captions: groups of 2–3 words that never cross the end of a line; current word in the brand accent; font size shrinks for long groups so they fit the ~820 px column.
+- Captions: groups of 2–3 words that never cross the end of a line; current word in the brand accent; font size shrinks for long groups so they fit the ~820 px column. Keep a real gap between words (`gap: 0 0.3em` on the flex row): if the active word grows (`scale`), it eats a smaller gap and «EDITORES DE» reads «EDITORESDE» — grow it at most ~5 %, or only change its colour.
 - The final mix is normalised to −14 LUFS by `render` (`--lufs` to change, `--no-normalize` to skip).
 
 ## 5. Generate the HTML from data
@@ -123,7 +134,8 @@ Re-run it whenever the voice or the cuts change; the animation code reads `windo
 - Centring with CSS `transform: translate(-50%,-50%)` on an element you also transform from JS fights; centre with flex/inset instead.
 - Emojis render with the operating system's emoji font (different design on other machines).
 - An element that ends past `data-duration` is cut; a timeline shorter than it holds the last frame.
-- `check` reports layout overlaps: real ones (a zoomed window under the header) must be fixed; intentional ones get `data-layout-allow-overlap` / `data-layout-allow-overflow` on the element.
+- `check` also reads HTML comments: never leave example `<video>`/`<audio>` tags inside `<!-- -->` (it reports their files as missing).
+- `check` reports layout overlaps: real ones (a zoomed window under the header) must be fixed; intentional ones get `data-layout-allow-overlap` / `data-layout-allow-overflow` on the element. A title split in lines (one element per line) is reported line against line: put `data-layout-allow-overlap` on EACH line, not only on the container.
 
 ## 7. Review before showing anything
 

package/src/audio.mjs

@@ -4,7 +4,7 @@ import { spawnSync } from 'node:child_process';
 
 function ffmpegRun(ffmpeg, args) {
   const r = spawnSync(ffmpeg, ['-nostdin', '-hide_banner', ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
-  if (r.status !== 0) throw new Error(`ffmpeg falló: ${(r.stderr || r.error?.message || '').slice(-400)}`);
+  if (r.status !== 0) throw new Error(`ffmpeg failed: ${(r.stderr || r.error?.message || '').slice(-400)}`);
   return r.stderr; // ffmpeg informa por stderr
 }
 

package/src/binaries.mjs

@@ -28,7 +28,7 @@ const binDir = () => join(HOME, 'bin', PLATFORM, manifest.version);
 export function findTool(name) {
   const t = TOOLS[name];
   const fromEnv = process.env[t.env];
-  if (fromEnv) return existsSync(fromEnv) ? { path: fromEnv, source: 'env' } : { path: null, source: 'env', error: `${t.env} apunta a ${fromEnv}, que no existe` };
+  if (fromEnv) return existsSync(fromEnv) ? { path: fromEnv, source: 'env' } : { path: null, source: 'env', error: `${t.env} points to ${fromEnv}, which does not exist` };
   const cached = join(binDir(), t.file);
   if (existsSync(cached)) return { path: cached, source: 'cache' };
   const entry = manifest.platforms[PLATFORM]?.[name];
@@ -42,15 +42,15 @@ export async function ensureTool(name, log = () => {}) {
   if (found.error) throw new Error(found.error);
   const entry = manifest.platforms[PLATFORM]?.[name];
   if (!entry) {
-    throw new Error(`${name} todavía no está publicado para ${PLATFORM}. Mientras tanto, apunta ${TOOLS[name].env} a un ${TOOLS[name].file} local.`);
+    throw new Error(`${name} is not available for ${PLATFORM} yet. Meanwhile, point ${TOOLS[name].env} to a local ${TOOLS[name].file}.`);
   }
   const url = `${manifest.baseUrl}/${manifest.version}/${PLATFORM}/${entry.file}`;
-  log(`Descargando ${name} (${(entry.size / 1e6).toFixed(0)} MB)…`);
+  log(`Downloading ${name} (${(entry.size / 1e6).toFixed(0)} MB)…`);
   const res = await fetch(url);
-  if (!res.ok) throw new Error(`No se pudo descargar ${name}: ${res.status} ${url}`);
+  if (!res.ok) throw new Error(`Could not download ${name}: ${res.status} ${url}`);
   const buf = Buffer.from(await res.arrayBuffer());
   const sha = createHash('sha256').update(buf).digest('hex');
-  if (sha !== entry.sha256) throw new Error(`El ${name} descargado no coincide con su huella (sha256). No se usa.`);
+  if (sha !== entry.sha256) throw new Error(`The downloaded ${name} does not match its SHA-256. Not using it.`);
   const dir = binDir();
   mkdirSync(dir, { recursive: true });
   const dest = join(dir, TOOLS[name].file);
@@ -69,14 +69,14 @@ export const WHISPER_MODELS = {
 
 export async function ensureWhisperModel(model = 'medium', log = () => {}) {
   const m = WHISPER_MODELS[model];
-  if (!m) throw new Error(`Modelo desconocido: ${model}. Opciones: ${Object.keys(WHISPER_MODELS).join(', ')}`);
+  if (!m) throw new Error(`Unknown model: ${model}. Options: ${Object.keys(WHISPER_MODELS).join(', ')}`);
   const dir = join(HOME, 'models');
   const dest = join(dir, m.file);
   if (existsSync(dest)) return dest;
   mkdirSync(dir, { recursive: true });
-  log(`Descargando el modelo de transcripción ${model} (${(m.size / 1e9).toFixed(1)} GB, solo la primera vez)…`);
+  log(`Downloading the ${model} transcription model (${(m.size / 1e9).toFixed(1)} GB, first time only)…`);
   const res = await fetch(`https://huggingface.co/ggerganov/whisper.cpp/resolve/main/${m.file}`);
-  if (!res.ok) throw new Error(`No se pudo descargar el modelo ${model}: ${res.status}`);
+  if (!res.ok) throw new Error(`Could not download the ${model} model: ${res.status}`);
   await pipeline(Readable.fromWeb(res.body), createWriteStream(`${dest}.part`));
   renameSync(`${dest}.part`, dest);
   return dest;

package/src/cli.mjs

@@ -1,7 +1,10 @@
 // ignix-editor — CLI de Ignix Editor. El motor (HyperFrames, en vendor/) corre siempre por
 // debajo con nuestro entorno: sin telemetría, sin actualizaciones solas, con nuestros binarios.
+// Los mensajes van en inglés, como el manual y la skill: los lee sobre todo el agente.
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -17,12 +20,21 @@ const ENGINE = join(PKG_DIR, 'vendor', 'hyperframes', 'bin', 'hyperframes.mjs');
 const UPSTREAM = JSON.parse(readFileSync(join(PKG_DIR, 'vendor', 'hyperframes', 'UPSTREAM.json'), 'utf8'));
 export const VIDEOS_DIR = join(homedir(), 'ignix-videos');
 
+// Las dependencias pueden estar en <paquete>/node_modules o, según cómo instale npm,
+// al lado del paquete (npm install --prefix …): se resuelven como lo haría Node.
+const requireHere = createRequire(import.meta.url);
+const depDir = (name) => dirname(requireHere.resolve(`${name}/package.json`));
+
 const log = (...a) => console.error(...a);
 const fail = (msg) => {
   log(`✗ ${msg}`);
   process.exit(1);
 };
 
+// Opciones del motor que llevan valor detrás: `snapshot --at 0,1.5` sin carpeta no debe
+// tomar «0,1.5» por la carpeta del proyecto.
+const ENGINE_VALUE_FLAGS = new Set(['--at', '--frames', '--timeout', '--angle', '--zoom', '--zoom-scale', '--against', '--describe', '-w', '--workers', '-q', '--quality', '-f', '--fps', '--format', '--crf', '--video-bitrate', '--resolution', '--variables', '--variables-file', '-c', '--composition', '--port']);
+
 // ── argumentos: posicionales, nuestras opciones y el resto pasa al motor tal cual
 function parseArgs(argv, ours) {
   const pos = [];
@@ -36,9 +48,10 @@ function parseArgs(argv, ours) {
       if (ours[key] === 'bool') opts[key] = m?.[2] !== 'false';
       else opts[key] = m?.[2] ?? argv[++i];
     } else if (key && key.startsWith('no-') && key.slice(3) in ours && ours[key.slice(3)] === 'bool') opts[key.slice(3)] = false;
-    else if (a.startsWith('-')) rest.push(a);
-    else if (rest.length && rest[rest.length - 1].startsWith('-') && !rest[rest.length - 1].includes('=') && pos.length >= 1) rest.push(a);
-    else pos.push(a);
+    else if (a.startsWith('-')) {
+      rest.push(a);
+      if (ENGINE_VALUE_FLAGS.has(a) && i + 1 < argv.length) rest.push(argv[++i]);
+    } else pos.push(a);
   }
   return { pos, opts, rest };
 }
@@ -80,13 +93,13 @@ function validateProject(dir) {
   const issues = projectHtml(dir).flatMap(validateHtml);
   for (const i of issues) log(`${i.level === 'error' ? '✗' : '⚠'} ${i.rule} ${i.file.replace(dir + '/', '')}:${i.line} — ${i.msg}`);
   const errors = issues.filter((i) => i.level === 'error').length;
-  log(errors ? `✗ ${errors} error(es) de Ignix Editor` : `✓ Ignix Editor: HTML y recursos correctos${issues.length ? ` (${issues.length} aviso(s))` : ''}`);
+  log(errors ? `✗ ${errors} Ignix Editor error(s)` : `✓ Ignix Editor: HTML and assets OK${issues.length ? ` (${issues.length} warning(s))` : ''}`);
   return errors;
 }
 
 const projectDir = (p) => {
   const dir = resolve(p ?? '.');
-  if (!existsSync(join(dir, 'index.html'))) fail(`No hay index.html en ${dir}. ¿Es la carpeta del proyecto? (créala con: ignix-editor init <nombre>)`);
+  if (!existsSync(join(dir, 'index.html'))) fail(`No index.html in ${dir}. Is this the project folder? (create one with: ignix-editor init <name>)`);
   return dir;
 };
 
@@ -94,38 +107,53 @@ const projectDir = (p) => {
 const commands = {
   async doctor() {
     const major = Number(process.versions.node.split('.')[0]);
-    log(`${major >= 22 ? '✓' : '✗'} Node ${process.versions.node}${major >= 22 ? '' : ' — hace falta Node 22 o superior'}`);
-    log(`✓ Ignix Editor ${PKG.version} · motor HyperFrames ${UPSTREAM.version} (parches: ${UPSTREAM.patches.join(', ')})`);
-    log(`  Plataforma ${PLATFORM} · datos en ${HOME}`);
+    log(`${major >= 22 ? '✓' : '✗'} Node ${process.versions.node}${major >= 22 ? '' : ' — Node 22 or newer is required'}`);
+    log(`✓ Ignix Editor ${PKG.version} · HyperFrames engine ${UPSTREAM.version} (patches: ${UPSTREAM.patches.join(', ')})`);
+    log(`  Platform ${PLATFORM} · data in ${HOME}`);
     let ok = major >= 22;
+    // doctor deja la máquina lista: descarga lo que falte en vez de solo avisar.
     for (const name of Object.keys(TOOLS)) {
-      const f = findTool(name);
-      const line = f.path ? `✓ ${name}: ${f.path}${f.source === 'env' ? ' (variable de entorno)' : ''}` : f.error ? `✗ ${name}: ${f.error}` : f.source === 'download' ? `• ${name}: se descargará la primera vez` : `✗ ${name}: aún no publicado para ${PLATFORM} (apunta ${TOOLS[name].env} a uno local)`;
-      log(line);
-      if (!f.path && f.source !== 'download' && name !== 'whisper') ok = false;
+      const before = findTool(name);
+      if (before.path) {
+        log(`✓ ${name}: ${before.path}${before.source === 'env' ? ' (environment variable)' : ''}`);
+        continue;
+      }
+      try {
+        const path = await ensureTool(name, log);
+        log(`✓ ${name}: ${path} (downloaded)`);
+      } catch (e) {
+        log(`✗ ${name}: ${e.message}`);
+        if (name !== 'whisper') ok = false;
+      }
     }
-    if (findTool('ffmpeg').path) {
-      const enc = spawnSync(findTool('ffmpeg').path, ['-hide_banner', '-encoders'], { encoding: 'utf8' }).stdout ?? '';
+    const ff = findTool('ffmpeg').path;
+    if (ff) {
+      const enc = spawnSync(ff, ['-hide_banner', '-encoders'], { encoding: 'utf8' }).stdout ?? '';
       const h264 = /\blibx264\b/.test(enc) ? 'libx264' : /\bh264_videotoolbox\b/.test(enc) ? 'VideoToolbox' : null;
-      log(`${h264 ? '✓' : '✗'} codificador H.264: ${h264 ?? 'ninguno (hace falta libx264 o VideoToolbox)'}`);
+      log(`${h264 ? '✓' : '✗'} H.264 encoder: ${h264 ?? 'none (needs libx264 or VideoToolbox)'}`);
       if (!h264) ok = false;
     }
+    log(ok ? '✓ Ready.' : '✗ Not ready: see the lines above.');
     process.exit(ok ? 0 : 1);
   },
 
   async init(argv) {
     const { pos, opts } = parseArgs(argv, { dir: 'str' });
     const name = pos[0];
-    if (!name || !/^[\w.-]+$/.test(name)) fail('Uso: ignix-editor init <nombre> [--dir carpeta]  (nombre sin espacios)');
+    if (!name || !/^[\w.-]+$/.test(name)) fail('Usage: ignix-editor init <name> [--dir folder]  (name without spaces)');
     const dir = resolve(opts.dir ?? join(VIDEOS_DIR, name));
-    if (existsSync(dir)) fail(`${dir} ya existe. Elige otro nombre o trabaja dentro de ese proyecto.`);
+    if (existsSync(dir)) fail(`${dir} already exists. Pick another name or work inside that project.`);
+    // Todo se prepara antes de crear la carpeta: si algo falta, no queda un proyecto a medias.
+    const gsap = join(depDir('gsap'), 'dist', 'gsap.min.js');
+    const fonts = join(depDir('@fontsource/montserrat'), 'files');
+    if (!existsSync(gsap) || !existsSync(fonts)) fail('Ignix Editor is missing GSAP or its fonts. Reinstall it (npm install --prefix ~/.ignix-editor/cli @ignix-social/editor).');
     cpSync(join(PKG_DIR, 'templates', 'blank'), dir, { recursive: true });
     mkdirSync(join(dir, 'assets', 'fonts'), { recursive: true });
-    cpSync(join(PKG_DIR, 'node_modules', 'gsap', 'dist', 'gsap.min.js'), join(dir, 'assets', 'gsap.min.js'));
+    cpSync(gsap, join(dir, 'assets', 'gsap.min.js'));
     for (const w of [700, 800, 900]) {
       for (const sub of ['latin', 'latin-ext']) {
         const f = `montserrat-${sub}-${w}-normal.woff2`;
-        cpSync(join(PKG_DIR, 'node_modules', '@fontsource', 'montserrat', 'files', f), join(dir, 'assets', 'fonts', f));
+        cpSync(join(fonts, f), join(dir, 'assets', 'fonts', f));
       }
     }
     cpSync(join(PKG_DIR, 'src', 'runtime', 'ignix-frame.js'), join(dir, 'ignix-frame.js'));
@@ -139,7 +167,7 @@ const commands = {
     const dir = projectDir(pos[0]);
     const errors = validateProject(dir);
     const { build, snapped } = prepare(dir);
-    if (snapped) log(`• ${snapped} tiempo(s) ajustado(s) al fotograma`);
+    if (snapped) log(`• ${snapped} time(s) snapped to the nearest frame`);
     const { env } = await engineEnv();
     const code = runEngine(['check', build, ...rest], env, dir);
     process.exit(errors ? 1 : code);
@@ -158,19 +186,19 @@ const commands = {
   async render(argv) {
     const { pos, opts, rest } = parseArgs(argv, { output: 'str', lufs: 'str', normalize: 'bool', force: 'bool' });
     const dir = projectDir(pos[0]);
-    if (validateProject(dir) && !opts.force) fail('Arregla los errores de arriba antes de renderizar (o --force si sabes lo que haces).');
+    if (validateProject(dir) && !opts.force) fail('Fix the errors above before rendering (or --force if you know what you are doing).');
     const { build, snapped } = prepare(dir);
-    if (snapped) log(`• ${snapped} tiempo(s) ajustado(s) al fotograma`);
+    if (snapped) log(`• ${snapped} time(s) snapped to the nearest frame`);
     const { env, ffmpeg, ffprobe } = await engineEnv();
     const output = resolve(opts.output ?? join(dir, 'renders', `${basename(dir)}.mp4`));
     mkdirSync(dirname(output), { recursive: true });
     const raw = join(build, 'raw.mp4');
     const code = runEngine(['render', build, '-o', raw, ...rest], env, dir);
-    if (code !== 0 || !existsSync(raw)) fail('El render falló (mira los mensajes de arriba).');
+    if (code !== 0 || !existsSync(raw)) fail('The render failed (see the messages above).');
     if (opts.normalize !== false && hasAudio(ffprobe, raw)) {
       const lufs = Number(opts.lufs ?? -14);
       const r = normalizeLoudness(ffmpeg, raw, output, { lufs });
-      log(`✓ Volumen: ${r.before.toFixed(1)} → ${loudness(ffmpeg, output)?.toFixed(1)} LUFS`);
+      log(`✓ Loudness: ${r.before.toFixed(1)} → ${loudness(ffmpeg, output)?.toFixed(1)} LUFS`);
     } else cpSync(raw, output);
     console.log(output);
   },
@@ -180,14 +208,14 @@ const commands = {
     const dir = projectDir(pos[0]);
     const { build } = prepare(dir);
     const { env } = await engineEnv();
-    log('Vista previa de la copia de trabajo: si cambias el proyecto, vuelve a lanzar este comando.');
+    log('Previewing the working copy: if you change the project, run this command again.');
     process.exit(runEngine(['preview', build, ...rest], env, dir));
   },
 
   async transcribe(argv) {
     const { pos, opts } = parseArgs(argv, { lang: 'str', model: 'str', script: 'str', output: 'str', threads: 'str' });
     const input = pos[0] && resolve(pos[0]);
-    if (!input || !existsSync(input)) fail('Uso: ignix-editor transcribe <audio|vídeo> [--lang es] [--model medium] [--script "texto dicho"] [-o palabras.json]');
+    if (!input || !existsSync(input)) fail('Usage: ignix-editor transcribe <audio|video> [--lang es] [--model medium] [--script "what was said"] [-o words.json]');
     const ffmpeg = await ensureTool('ffmpeg', log);
     const ffprobe = await ensureTool('ffprobe', log);
     const whisper = await ensureTool('whisper', log);
@@ -198,8 +226,57 @@ const commands = {
       words = alignToScript(opts.script, words, dur);
     }
     const json = JSON.stringify({ language: opts.lang ?? 'es', words }, null, 1);
-    if (opts.output) writeFileSync(resolve(opts.output), json);
-    else console.log(json);
+    if (opts.output) {
+      mkdirSync(dirname(resolve(opts.output)), { recursive: true });
+      writeFileSync(resolve(opts.output), json);
+    } else console.log(json);
+  },
+
+  // Dónde está la cara a lo largo del vídeo, para encuadrar en vertical siguiéndola.
+  // macOS: Apple Vision desde un Swift propio (src/native/faces.swift), compilado una vez.
+  async faces(argv) {
+    const { pos, opts } = parseArgs(argv, { every: 'str', output: 'str', smooth: 'str' });
+    const input = pos[0] && resolve(pos[0]);
+    if (!input || !existsSync(input)) fail('Usage: ignix-editor faces <video> [--every 0.2] [--smooth 1] [-o work/faces.json]');
+    if (process.platform !== 'darwin') fail('faces needs macOS for now. Elsewhere, frame the person by hand from stills (snapshot) or keep a centred crop.');
+    const src = join(PKG_DIR, 'src', 'native', 'faces.swift');
+    const hash = createHash('sha256').update(readFileSync(src)).digest('hex').slice(0, 12);
+    const bin = join(HOME, 'bin', PLATFORM, `faces-${hash}`);
+    if (!existsSync(bin)) {
+      mkdirSync(dirname(bin), { recursive: true });
+      log('Compiling the face tracker (first time only)…');
+      const c = spawnSync('xcrun', ['swiftc', '-O', '-parse-as-library', src, '-o', bin], { encoding: 'utf8' });
+      if (c.status !== 0) fail(`Could not compile the face tracker. It needs Apple's Command Line Tools (xcode-select --install).\n${(c.stderr || c.error?.message || '').slice(-400)}`);
+    }
+    const every = Math.max(0.05, Number(opts.every ?? 0.2));
+    const r = spawnSync(bin, [input, String(every)], { encoding: 'utf8', maxBuffer: 256 * 1024 * 1024 });
+    if (r.status !== 0) fail(`Face tracking failed: ${(r.stderr || '').slice(-400)}`);
+    const raw = JSON.parse(r.stdout);
+    const S = raw.samples;
+    // Huecos sin cara: la posición conocida más cercana; si no hay ninguna, el centro.
+    const known = S.map((x, i) => (x.w ? i : -1)).filter((i) => i >= 0);
+    const filled = S.map((x, i) => {
+      if (x.w) return x;
+      if (!known.length) return { t: x.t, x: 0.4, y: 0.3, w: 0.2, h: 0.2 };
+      const k = known.reduce((a, b) => (Math.abs(b - i) < Math.abs(a - i) ? b : a));
+      return { ...S[k], t: x.t };
+    });
+    // Suavizado: media móvil de ~1 s (configurable) sobre el centro y el tamaño.
+    const half = Math.max(1, Math.round(Number(opts.smooth ?? 1) / every / 2));
+    const avg = (i, f) => {
+      let sum = 0, n = 0;
+      for (let j = Math.max(0, i - half); j <= Math.min(filled.length - 1, i + half); j++) (sum += f(filled[j])), n++;
+      return +(sum / n).toFixed(4);
+    };
+    const path = filled.map((x, i) => ({ t: x.t, cx: avg(i, (y) => y.x + y.w / 2), cy: avg(i, (y) => y.y + y.h / 2), size: avg(i, (y) => y.h) }));
+    const out = { source: input, width: raw.width, height: raw.height, duration: raw.duration, every, found: known.length, samples: S.length, path };
+    const json = JSON.stringify(out);
+    log(`✓ Face found in ${known.length}/${S.length} samples${known.length < S.length ? ' (gaps filled with the nearest position)' : ''}`);
+    if (opts.output) {
+      mkdirSync(dirname(resolve(opts.output)), { recursive: true });
+      writeFileSync(resolve(opts.output), json);
+      console.log(resolve(opts.output));
+    } else console.log(json);
   },
 
   async ffmpeg(argv) {
@@ -214,38 +291,39 @@ const commands = {
 
   async skills(argv) {
     const { pos, opts } = parseArgs(argv, { dir: 'str' });
-    if (pos[0] !== 'add') fail('Uso: ignix-editor skills add [--dir ~/.claude/skills]');
+    if (pos[0] !== 'add') fail('Usage: ignix-editor skills add [--dir ~/.claude/skills]');
     const target = resolve(opts.dir ?? join(homedir(), '.claude', 'skills'), 'ignix-editor');
     rmSync(target, { recursive: true, force: true });
     cpSync(join(PKG_DIR, 'skills', 'ignix-editor'), target, { recursive: true });
-    log(`✓ Skill instalada en ${target}`);
+    log(`✓ Skill installed in ${target}`);
   },
 
   async version() {
-    console.log(`ignix-editor ${PKG.version} (motor HyperFrames ${UPSTREAM.version})`);
+    console.log(`ignix-editor ${PKG.version} (HyperFrames engine ${UPSTREAM.version})`);
   },
 
   async help() {
-    console.log(`Ignix Editor ${PKG.version} — vídeo con HTML, renderizado en tu ordenador.
-
-  ignix-editor doctor                      comprueba Node, ffmpeg, whisper y el codificador
-  ignix-editor init <nombre>               crea ~/ignix-videos/<nombre> listo para trabajar
-  ignix-editor check [carpeta]             HTML, recursos, maqueta, movimiento y contraste
-  ignix-editor snapshot [carpeta] --at 0,2.5,5   fotogramas sueltos para revisar
-  ignix-editor render [carpeta] [-o salida.mp4] [--lufs -14] [--no-normalize]
-  ignix-editor preview [carpeta]           vista previa en el navegador
-  ignix-editor transcribe <fichero> [--lang es] [--script "texto"] [-o palabras.json]
-  ignix-editor ffmpeg|ffprobe <args>       el ffmpeg de Ignix Editor
-  ignix-editor skills add                  instala la skill para Claude
-
-Basado en HyperFrames (Apache-2.0) de HeyGen, Inc. Ver NOTICE.`);
+    console.log(`Ignix Editor ${PKG.version} — video from HTML, rendered on your own computer.
+
+  ignix-editor doctor                          checks Node and the encoder, downloads ffmpeg and whisper if missing
+  ignix-editor init <name>                     creates ~/ignix-videos/<name>, ready to work in
+  ignix-editor check [folder]                  HTML, assets, layout, motion and contrast
+  ignix-editor snapshot [folder] --at 0,2.5,5  single frames to look at (into <folder>/snapshots)
+  ignix-editor render [folder] [-o out.mp4] [--lufs -14] [--no-normalize]
+  ignix-editor preview [folder]                live preview in the browser
+  ignix-editor transcribe <file> [--lang es] [--script "text"] [-o words.json]
+  ignix-editor faces <video> [--every 0.2] [-o faces.json]   where the face is, smoothed (macOS)
+  ignix-editor ffmpeg|ffprobe <args>           Ignix Editor's own ffmpeg
+  ignix-editor skills add                      installs the skill for Claude
+
+The folder defaults to the current one. Based on HyperFrames (Apache-2.0) by HeyGen, Inc. See NOTICE.`);
   },
 };
 
 export async function main(argv) {
   const [cmd = 'help', ...rest] = argv;
   const fn = commands[cmd === '--version' || cmd === '-v' ? 'version' : cmd === '--help' || cmd === '-h' ? 'help' : cmd];
-  if (!fn) fail(`Comando desconocido: ${cmd}. Usa: ignix-editor help`);
+  if (!fn) fail(`Unknown command: ${cmd}. See: ignix-editor help`);
   try {
     await fn(rest);
   } catch (e) {

package/src/native/faces.swift

@@ -0,0 +1,60 @@
+// faces — dónde está la cara en cada momento de un vídeo (Apple Vision, macOS 13+).
+// Uso: faces <vídeo> <cada_segundos>  → JSON por stdout:
+//   { "duration": s, "width": px, "height": px, "samples": [ { "t": s, "x":…, "y":…, "w":…, "h":… } | { "t": s } ] }
+// x, y, w, h normalizados 0–1 con origen ARRIBA a la izquierda (como CSS). Sin cara → solo "t".
+import AVFoundation
+import Foundation
+import Vision
+
+@main
+struct Faces {
+  static func main() async {
+    let args = CommandLine.arguments
+    guard args.count >= 2 else {
+      FileHandle.standardError.write("usage: faces <video> [every_seconds]\n".data(using: .utf8)!)
+      exit(2)
+    }
+    let url = URL(fileURLWithPath: args[1])
+    let every = args.count >= 3 ? (Double(args[2]) ?? 0.2) : 0.2
+    let asset = AVURLAsset(url: url)
+    do {
+      let duration = try await asset.load(.duration).seconds
+      guard let track = try await asset.loadTracks(withMediaType: .video).first else {
+        FileHandle.standardError.write("no video track\n".data(using: .utf8)!)
+        exit(1)
+      }
+      let size = try await track.load(.naturalSize).applying(try await track.load(.preferredTransform))
+      let gen = AVAssetImageGenerator(asset: asset)
+      gen.appliesPreferredTrackTransform = true
+      gen.requestedTimeToleranceBefore = CMTime(value: 1, timescale: 30)
+      gen.requestedTimeToleranceAfter = CMTime(value: 1, timescale: 30)
+      gen.maximumSize = CGSize(width: 960, height: 960)
+
+      var samples: [[String: Double]] = []
+      var t = 0.0
+      while t < duration {
+        var sample: [String: Double] = ["t": (t * 1000).rounded() / 1000]
+        if let (image, _) = try? await gen.image(at: CMTime(seconds: t, preferredTimescale: 600)) {
+          let req = VNDetectFaceRectanglesRequest()
+          try? VNImageRequestHandler(cgImage: image, options: [:]).perform([req])
+          // La cara más grande: la de quien habla a cámara.
+          if let f = (req.results ?? []).max(by: { $0.boundingBox.width * $0.boundingBox.height < $1.boundingBox.width * $1.boundingBox.height }) {
+            let b = f.boundingBox // Vision: origen ABAJO a la izquierda
+            sample["x"] = b.minX
+            sample["y"] = 1 - b.maxY
+            sample["w"] = b.width
+            sample["h"] = b.height
+          }
+        }
+        samples.append(sample)
+        t += every
+      }
+      let out: [String: Any] = ["duration": duration, "width": abs(size.width), "height": abs(size.height), "samples": samples]
+      let data = try JSONSerialization.data(withJSONObject: out)
+      FileHandle.standardOutput.write(data)
+    } catch {
+      FileHandle.standardError.write("faces failed: \(error)\n".data(using: .utf8)!)
+      exit(1)
+    }
+  }
+}

package/src/prepare.mjs

@@ -60,7 +60,7 @@ export function prepare(projectDir) {
   mirror(projectDir, build);
 
   const root = join(build, 'index.html');
-  if (!existsSync(root)) throw new Error(`No hay index.html en ${projectDir}`);
+  if (!existsSync(root)) throw new Error(`No index.html in ${projectDir}`);
   const fps = Number(readFileSync(root, 'utf8').match(/data-fps="(\d+(?:\.\d+)?)"/)?.[1] ?? 30);
 
   let snapped = 0;
@@ -69,6 +69,13 @@ export function prepare(projectDir) {
     if (changes) writeFileSync(f, html);
     snapped += changes;
   }
+  // IgnixFrame.run registra la línea de tiempo al ejecutarse, pero el lint del motor busca
+  // el registro LITERAL en el HTML: sin él da «missing_timeline_registry» (un error que,
+  // además, apaga las comprobaciones de maquetación y contraste). Se lo damos literal.
+  const rootHtml = readFileSync(root, 'utf8');
+  if ((/IgnixFrame/.test(rootHtml) || /ignix-frame\.js/.test(rootHtml)) && !/window\.__timelines\s*(=|\[|\.|\?\?=)/.test(rootHtml)) {
+    writeFileSync(root, rootHtml.replace(/<\/body>/i, '<script>window.__timelines = window.__timelines || {};</script>\n</body>'));
+  }
   cpSync(RUNTIME, join(build, 'ignix-frame.js'));
   return { build, fps, snapped };
 }

package/src/transcribe.mjs

@@ -14,7 +14,7 @@ export function transcribe({ ffmpeg, whisper, model, input, language = 'es', thr
   try {
     const wav = join(tmp, 'audio.wav');
     const a = spawnSync(ffmpeg, ['-nostdin', '-hide_banner', '-loglevel', 'error', '-y', '-i', input, '-vn', '-ar', '16000', '-ac', '1', '-c:a', 'pcm_s16le', wav], { encoding: 'utf8' });
-    if (a.status !== 0) throw new Error(`No se pudo leer el audio de ${input}: ${a.stderr.slice(-300)}`);
+    if (a.status !== 0) throw new Error(`Could not read the audio of ${input}: ${a.stderr.slice(-300)}`);
     const out = join(tmp, 'out');
     const args = ['-m', model, '-l', language, '-ml', '1', '-sow', '-oj', '-of', out, '-t', String(threads), '-f', wav];
     const run = (extra) => spawnSync(whisper, [...extra, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
@@ -23,7 +23,7 @@ export function transcribe({ ffmpeg, whisper, model, input, language = 'es', thr
     const intelMac = process.platform === 'darwin' && process.arch === 'x64';
     let w = run(intelMac ? ['-ng'] : []);
     if (w.status !== 0 && !intelMac) w = run(['-ng']);
-    if (w.status !== 0) throw new Error(`whisper falló: ${(w.stderr || '').slice(-400)}`);
+    if (w.status !== 0) throw new Error(`whisper failed: ${(w.stderr || '').slice(-400)}`);
     const j = JSON.parse(readFileSync(`${out}.json`, 'utf8'));
     const words = [];
     for (const seg of j.transcription ?? []) {

package/src/validate.mjs

@@ -28,10 +28,10 @@ function balance(src) {
     if (VOID.has(tag) || m[2] === '/' || ['html', 'head', 'body', 'svg', 'path'].includes(tag)) continue;
     if (m[0].startsWith('</')) {
       if (stack.length && stack[stack.length - 1].tag === tag) stack.pop();
-      else issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'html_unmatched_close', msg: `</${tag}> sin su etiqueta de apertura${stack.length ? ` (está abierta <${stack[stack.length - 1].tag}> de la línea ${stack[stack.length - 1].line})` : ''}. Saca de su sitio todo lo que viene detrás.` });
+      else issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'html_unmatched_close', msg: `</${tag}> has no matching opening tag${stack.length ? ` (<${stack[stack.length - 1].tag}> from line ${stack[stack.length - 1].line} is open)` : ''}. Everything after it moves out of place.` });
     } else stack.push({ tag, line: lineOf(src, m.index) });
   }
-  for (const open of stack) issues.push({ level: 'error', line: open.line, rule: 'html_unclosed', msg: `<${open.tag}> sin cerrar.` });
+  for (const open of stack) issues.push({ level: 'error', line: open.line, rule: 'html_unclosed', msg: `<${open.tag}> is never closed.` });
   return issues;
 }
 
@@ -42,7 +42,7 @@ export function validateHtml(file) {
   parse(src, {
     sourceCodeLocationInfo: true,
     onParseError: (e) => {
-      if (!BENIGN.has(e.code)) issues.push({ level: 'error', line: e.startLine, rule: `html_${e.code}`, msg: `HTML mal formado (${e.code}).` });
+      if (!BENIGN.has(e.code)) issues.push({ level: 'error', line: e.startLine, rule: `html_${e.code}`, msg: `Malformed HTML (${e.code}).` });
     },
   });
   issues.push(...balance(src));
@@ -50,22 +50,22 @@ export function validateHtml(file) {
   for (const s of src.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)) {
     const body = s[1];
     if (/createElement\(\s*['"`](video|audio)['"`]/.test(body) || /<(video|audio)\b/.test(body)) {
-      issues.push({ level: 'error', line: lineOf(src, s.index), rule: 'media_from_js', msg: 'Hay <video>/<audio> creados desde JavaScript. El motor solo ve los que están escritos en el HTML: genera el HTML antes (un script de preparación) en vez de crearlos al cargar.' });
+      issues.push({ level: 'error', line: lineOf(src, s.index), rule: 'media_from_js', msg: '<video>/<audio> created from JavaScript. The engine only sees media written in the HTML: write the HTML beforehand (a build script) instead of creating them at load time.' });
     }
   }
   for (const m of src.matchAll(/<(script|link|img|video|audio|source)\b[^>]*\b(src|href)\s*=\s*["'](https?:)?\/\/[^"']+["']/gi)) {
     const tag = m[1].toLowerCase();
     const font = /fonts\.(googleapis|gstatic)\.com|use\.typekit|fonts\.bunny/.test(m[0]);
-    issues.push({ level: (tag === 'script' || tag === 'link') && !font ? 'warning' : 'error', line: lineOf(src, m.index), rule: 'network_asset', msg: `<${tag}> carga algo de internet. Descárgalo a assets/: el render no debe depender de la red.` });
+    issues.push({ level: (tag === 'script' || tag === 'link') && !font ? 'warning' : 'error', line: lineOf(src, m.index), rule: 'network_asset', msg: `<${tag}> loads something from the internet. Download it into assets/: the render must not depend on the network.` });
   }
   for (const m of src.matchAll(/@import\s+url\(\s*["']?https?:|url\(\s*["']?https?:\/\/fonts\./gi)) {
-    issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'network_font', msg: 'Fuente cargada de internet: llega tarde en algunos fotogramas. Usa @font-face con un fichero en assets/fonts/.' });
+    issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'network_font', msg: 'Font loaded from the internet: it arrives late in some frames. Use @font-face with a file in assets/fonts/.' });
   }
   for (const m of src.matchAll(/\bid\s*=\s*["']([^"']+)["']/g)) {
-    if (RESERVED_IDS.has(m[1])) issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'reserved_id', msg: `id="${m[1]}" lo trata el motor de forma especial (cambia la fuente). Usa otro nombre, p. ej. "subs".` });
+    if (RESERVED_IDS.has(m[1])) issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'reserved_id', msg: `id="${m[1]}" is special to the engine (it changes the font). Use another name, e.g. "subs".` });
   }
   for (const m of src.matchAll(/<audio\b(?![^>]*\bid\s*=)[^>]*>/gi)) {
-    issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'audio_without_id', msg: '<audio> sin id: el mezclador lo ignora y se queda sin sonido.' });
+    issues.push({ level: 'error', line: lineOf(src, m.index), rule: 'audio_without_id', msg: '<audio> without an id: the mixer ignores it and it stays silent.' });
   }
   return issues.map((i) => ({ ...i, file }));
 }

package/templates/blank/index.html

@@ -1,36 +1,33 @@
 <!DOCTYPE html>
-<html lang="es">
+<html lang="en">
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=1080, height=1920" />
     <script src="assets/gsap.min.js"></script>
     <script src="ignix-frame.js"></script>
     <style>
-      /* Fuentes SIEMPRE locales (assets/fonts): las de internet llegan tarde en algunos fotogramas. */
+      /* Fonts are ALWAYS local (assets/fonts): web fonts arrive late in some frames. */
       @font-face { font-family: 'Montserrat'; font-weight: 700; font-display: block; src: url('assets/fonts/montserrat-latin-700-normal.woff2') format('woff2'); }
       @font-face { font-family: 'Montserrat'; font-weight: 800; font-display: block; src: url('assets/fonts/montserrat-latin-800-normal.woff2') format('woff2'); }
       @font-face { font-family: 'Montserrat'; font-weight: 900; font-display: block; src: url('assets/fonts/montserrat-latin-900-normal.woff2') format('woff2'); }
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body { width: 1080px; height: 1920px; overflow: hidden; background: #121313; }
       #root { position: relative; width: 100%; height: 100%; overflow: hidden; background: #121313; font-family: 'Montserrat', sans-serif; color: #f5f5f5; }
-      /* Zona segura de un reel: columna central de ~820 px, libre de los 250 px de arriba y los 450 de abajo. */
+      /* Reel safe area: the central ~820 px column, clear of the top 250 px and the bottom 450 px. */
       #title { position: absolute; left: 130px; width: 820px; top: 760px; text-align: center; font-size: 110px; font-weight: 900; line-height: 1.02; text-transform: uppercase;
         -webkit-text-stroke: 12px #000; paint-order: stroke fill; text-shadow: 0 8px 0 rgba(0,0,0,.5); }
     </style>
   </head>
   <body>
-    <!-- data-duration en segundos; cámbialo a la duración real (la de la voz + un respiro). -->
+    <!-- data-duration in seconds: set it to the real length (the voice plus a short tail). -->
     <div id="root" data-composition-id="__ID__" data-width="1080" data-height="1920" data-duration="5" data-fps="30">
-      <div id="title">Hola</div>
-      <!-- Vídeo y audio SIEMPRE escritos aquí (no creados desde JS), cada uno con su id:
-      <video id="clip1" src="assets/toma.mp4" muted playsinline data-start="0" data-duration="3" data-media-start="1.5" data-track-index="0"></video>
-      <audio id="voz1" src="assets/voz-1.wav" data-start="0" data-duration="2.4" data-track-index="1" data-volume="1"></audio>
-      -->
+      <div id="title">Hello</div>
+      <!-- Video and audio go here, written in the HTML (never created from JS), each with its own id: see the ignix-editor skill. -->
     </div>
     <script>
       const { run, lerp, spring, ease } = IgnixFrame;
       const title = document.getElementById('title');
-      // Todo lo que se ve depende SOLO de t (segundos). Nada de medir la página aquí dentro.
+      // Everything visible depends ONLY on t (seconds). Never measure the page in here.
       run({ id: '__ID__', duration: 5, fps: 30 }, (t) => {
         const p = spring(t, { stiffness: 220, damping: 14 });
         title.style.transform = `scale(${0.6 + 0.4 * p})`;