@ignix-social/editor 0.1.28 → 0.1.29

package/NOTICE

@@ -97,3 +97,5 @@ Inter (font, from @fontsource/inter) — SIL Open Font License 1.1, Copyright (c
 
 Ignix Creator's composition templates (src/creator) were ported from Ignix Creator's own
   code (Copyright (c) 2026 Ignix); no Remotion code is included.
+
+Reference downloads use official standalone yt-dlp release binaries (https://github.com/yt-dlp/yt-dlp), downloaded separately and checked against release SHA-256 checksums. yt-dlp source is Unlicense; standalone executables include third-party dependencies with their own license notices, available with the official release/source distribution. These executables are not included in this npm package.

package/README.md

@@ -6,12 +6,12 @@ Ignix Editor is for Ignix customers: it needs an active [Ignix plan](https://ign
 
 ```sh
 npx @ignix-social/editor license <token> # saves the license from the Ignix MCP
-npx @ignix-social/editor doctor        # checks Node 22+, ffmpeg, whisper and the H.264 encoder
+npx @ignix-social/editor doctor        # checks Node 22+, ffmpeg, whisper, yt-dlp and the H.264 encoder
 npx @ignix-social/editor init my-reel  # creates ~/ignix-videos/my-reel
 npx @ignix-social/editor render ~/ignix-videos/my-reel
 ```
 
-Commands: `license`, `doctor`, `init`, `check`, `snapshot`, `render`, `preview`, `transcribe`, `faces`, `ffmpeg`, `ffprobe`, `skills add`, `fetch`, `serve`, `creator-job`, `help`.
+Commands: `license`, `doctor`, `init`, `check`, `snapshot`, `render`, `preview`, `download`, `transcribe`, `faces`, `ffmpeg`, `ffprobe`, `skills add`, `fetch`, `serve`, `creator-job`, `help`.
 
 - Everything runs locally; your footage never leaves your machine.
 - ffmpeg (GPL build, without libx264) and whisper.cpp are downloaded once per machine into `~/.ignix-editor`, checked against their SHA-256. Chrome for rendering is downloaded once from Google's official channel.
@@ -25,3 +25,5 @@ Requires Node.js 22 or newer. Runs on macOS (Intel and Apple Silicon) and Window
 ## License
 
 Apache-2.0. Ignix Editor is based on [HyperFrames](https://github.com/heygen-com/hyperframes) by HeyGen, Inc. (Apache-2.0), included in `vendor/hyperframes` with the modifications listed in `patches/`. See `NOTICE`. Ignix Editor is not affiliated with or endorsed by HeyGen.
+
+Public references: `ignix-editor download <URL> -o work/ref.mp4` uses a pinned, SHA-256-checked official yt-dlp binary and bundled FFmpeg/Node, without browser cookies or user downloader configuration. Reuse the transcript supplied by Ignix; run local Whisper if it is absent or needs checking. Inspect frames for visual structure and names. Downloaded source footage is study material, not a render asset.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignix-social/editor",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "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

@@ -14,7 +14,8 @@ Commands. `ignix-editor` means the copy the Ignix playbook installed: `~/.ignix-
 | Command | What it does |
 |---|---|
 | `ignix-editor license <token>` | Saves the license from the Ignix MCP (`get_editor_license`). Without a token, shows whether there is a valid one and until when. |
-| `ignix-editor doctor` | Node 22+ and the H.264 encoder; downloads its own ffmpeg and whisper the first time. Run it first. |
+| `ignix-editor download <URL> -o work/ref.mp4` | Downloads a public Instagram, TikTok or YouTube reference with bundled yt-dlp, FFmpeg and Node. No cookies. Keep it in `work/`, never `assets/`. Reuse the transcript supplied by Ignix; use local Whisper if absent. If downloading fails, use that saved speech transcript and disclose that visuals are unverified. |
+| `ignix-editor doctor` | Node 22+ and the H.264 encoder; downloads its own ffmpeg, whisper and yt-dlp 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, plus `pauses` ([start, end] of every silence ≥0.35 s, for cutting silences), on this machine. Over 2 min it prints whisper's progress; without a GPU it takes about as long as the audio. |
 | `ignix-editor faces <video> -o work/faces.json` | Where the face is over time (macOS and Windows; the first run downloads the face detector): a smoothed path `{t, cx, cy, size}` (0–1, top-left origin) to frame the person. |
@@ -273,6 +274,10 @@ run({ id, duration, fps }, (t) => O.draw(t));
 - 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).
 
+### A reel modelled on a reference
+
+When the user brings a reel they want theirs to look like, study it; never use it. Download it first with `ignix-editor download <URL> -o work/ref.mp4`. Read `inspiredBy.transcript` from the Ignix playbook when supplied: the app already obtained it, so the agent never calls APISmith. Reuse that speech evidence; local Whisper is for missing transcripts or recognition errors. If downloading fails, you can still adapt the saved speech argument, but say that visuals are unverified and keep the visual mapping provisional. If neither video nor transcript is available, ask for the file before proposing a script. Verify named recommendations against frames when available and preserve each reason; do not replace a comparison followed by specific recommendations with generic categories. Show the original preview or representative frames, then its sequence and the adaptation mapping before the script. Keep it in `work/` (never `assets/`), tile its frames (`ignix-editor ffmpeg -i work/ref.mp4 -vf "fps=2,scale=240:-1,tile=6x4" work/ref-%02d.jpg`) and transcribe it to read its layout, its beats and their timing, and the moments that carry it. Then rebuild that structure with your own pieces: the layout in CSS (e.g. a split screen with graphics in the top third, the presenter's video below and short captions on the seam), each beat's visual drawn for this brand, the key moment recreated with what you have (a gesture clip, cards fanning out, a reveal). None of it reaches the render: not its footage, music, words or branding. In the review, compare your stills with its contact sheet beat by beat.
+
 ## 5. Generate the HTML from data
 
 When there are many clips, lines or cues, keep them in data and let a script write the media tags and the timing file:

package/src/binaries.json

@@ -20,6 +20,13 @@
         "size": 2912480,
         "sha256": "73fc58436c1e1a9d2cc3ea08bddf18bf78270d8c6940c5fd89a3c9cb31535efe",
         "build": "whisper.cpp v1.7.6, scripts/build-whisper-macos.sh"
+      },
+      "ytdlp": {
+        "file": "yt-dlp_macos",
+        "size": 37146048,
+        "sha256": "0f192b7ec147ab6288885d6351d9ab67367640029b4377576ef46dd79cf7b202",
+        "url": "https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/yt-dlp_macos",
+        "build": "yt-dlp 2026.08.19 official standalone; SHA2-256SUMS verified"
       }
     },
     "darwin-arm64": {
@@ -40,6 +47,13 @@
         "size": 2573144,
         "sha256": "215d93a2edc77f8929311f127f368727859e13833e925652315ca5ea774595ee",
         "build": "whisper.cpp v1.7.6, CI binaries.yml (macos-15, run 37375441240)"
+      },
+      "ytdlp": {
+        "file": "yt-dlp_macos",
+        "size": 37146048,
+        "sha256": "0f192b7ec147ab6288885d6351d9ab67367640029b4377576ef46dd79cf7b202",
+        "url": "https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/yt-dlp_macos",
+        "build": "yt-dlp 2026.08.19 official standalone; SHA2-256SUMS verified"
       }
     },
     "win32-x64": {
@@ -59,7 +73,32 @@
         "file": "whisper-cli.exe",
         "size": 1990144,
         "sha256": "26cef7a9b82544e4076a4977c93635bb1b324bd5ab3b4301d6d06e8224e580ea",
-        "build": "whisper.cpp v1.7.6, MSVC estático sin OpenMP, CI windows.yml (run 37392626795)"
+        "build": "whisper.cpp v1.7.6, MSVC est\u00e1tico sin OpenMP, CI windows.yml (run 37392626795)"
+      },
+      "ytdlp": {
+        "file": "yt-dlp.exe",
+        "size": 17840399,
+        "sha256": "66674953fe251b89f4d08c5f0e35e0728679bd67ab3d7d05c0562af101dd3e7a",
+        "url": "https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/yt-dlp.exe",
+        "build": "yt-dlp 2026.08.19 official standalone; SHA2-256SUMS verified"
+      }
+    },
+    "linux-x64": {
+      "ytdlp": {
+        "file": "yt-dlp_linux",
+        "size": 40446224,
+        "sha256": "58162f9bfdc27458ea47bfcb311cf47028f17d8154a8bf7d689861d46399230a",
+        "url": "https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/yt-dlp_linux",
+        "build": "yt-dlp 2026.08.19 official standalone; SHA2-256SUMS verified"
+      }
+    },
+    "linux-arm64": {
+      "ytdlp": {
+        "file": "yt-dlp_linux_aarch64",
+        "size": 40167448,
+        "sha256": "b16e4dab368a816cd05d477d698a605a6ae87ccee1c8ffd38fa21d7254141fcc",
+        "url": "https://github.com/yt-dlp/yt-dlp/releases/download/2026.08.19/yt-dlp_linux_aarch64",
+        "build": "yt-dlp 2026.08.19 official standalone; SHA2-256SUMS verified"
       }
     }
   },

package/src/binaries.mjs

@@ -17,6 +17,7 @@ const EXE = process.platform === 'win32' ? '.exe' : '';
 const manifest = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'binaries.json'), 'utf8'));
 
 export const TOOLS = {
+  ytdlp: { env: 'IGNIX_EDITOR_YTDLP', file: `yt-dlp${EXE}` },
   ffmpeg: { env: 'IGNIX_EDITOR_FFMPEG', file: `ffmpeg${EXE}` },
   ffprobe: { env: 'IGNIX_EDITOR_FFPROBE', file: `ffprobe${EXE}` },
   whisper: { env: 'IGNIX_EDITOR_WHISPER', file: `whisper-cli${EXE}` },
@@ -44,7 +45,7 @@ export async function ensureTool(name, log = () => {}) {
   if (!entry) {
     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}`;
+  const url = entry.url ?? `${manifest.baseUrl}/${manifest.version}/${PLATFORM}/${entry.file}`;
   log(`Downloading ${name} (${(entry.size / 1e6).toFixed(0)} MB)…`);
   const res = await fetch(url);
   if (!res.ok) throw new Error(`Could not download ${name}: ${res.status} ${url}`);

package/src/cli.mjs

@@ -1,3 +1,4 @@
+import { downloadReference } from './reference-download.mjs';
 // 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.
@@ -215,6 +216,14 @@ const commands = {
     process.exit(runEngine(['preview', build, ...rest], env, dir));
   },
 
+  async download(argv) {
+    const { pos, opts } = parseArgs(argv, { output: 'str' });
+    if (pos.length !== 1 || !opts.output) fail('Usage: ignix-editor download <Instagram|TikTok|YouTube URL> -o work/ref.mp4');
+    const ytdlp = await ensureTool('ytdlp', log);
+    const ffmpeg = await ensureTool('ffmpeg', log);
+    console.log(downloadReference({ url: pos[0], output: opts.output, ytdlp, ffmpeg }));
+  },
+
   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]);
@@ -462,13 +471,14 @@ const commands = {
   async help() {
     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 doctor                          checks Node and the encoder, downloads ffmpeg, whisper and yt-dlp 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] [--no-review]
   ignix-editor review <video.mp4> [--json]     is it ready to show? stillness, empty frame, voice gaps, cuts
   ignix-editor preview [folder]                live preview in the browser
+  ignix-editor download <URL> -o work/ref.mp4   downloads a public reference with yt-dlp (no cookies)
   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
   ignix-editor pick-audio [folder] --kind music|sfx --query "inspiring" [--order trending]

package/src/fetch.mjs

@@ -11,7 +11,7 @@ export async function fetchAll({ whisper = 'small', analysis = true, json = fals
   const emit = (e) => json && process.stdout.write(`${JSON.stringify(e)}\n`);
   if (!WHISPER_MODELS[whisper]) throw Object.assign(new Error(`Unknown model: ${whisper}`), { code: 'invalid_args' });
   const todo = [];
-  for (const name of ['ffmpeg', 'ffprobe', 'whisper']) {
+  for (const name of ['ffmpeg', 'ffprobe', 'whisper', 'ytdlp']) {
     if (!findTool(name).path) todo.push({ item: name, size: toolSize(name), run: () => ensureTool(name, log) });
   }
   if (!existsSync(whisperModelPath(whisper))) todo.push({ item: `whisper-${whisper}`, size: WHISPER_MODELS[whisper].size, run: () => ensureWhisperModel(whisper, log) });

package/src/reference-download.mjs

@@ -0,0 +1,42 @@
+// Reference study only: these files belong in work/, never in render assets.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+export function referenceUrl(raw) {
+  let u;
+  try { u = new URL(raw); } catch { throw new Error('Expected an Instagram, TikTok or YouTube video URL.'); }
+  const host = u.hostname.toLowerCase();
+  const allowed = ['instagram.com', 'www.instagram.com', 'youtube.com', 'www.youtube.com', 'm.youtube.com', 'youtu.be', 'tiktok.com', 'www.tiktok.com', 'vm.tiktok.com', 'vt.tiktok.com'];
+  if (u.protocol !== 'https:' || !allowed.includes(host) || u.username || u.password || u.port) throw new Error('Expected an HTTPS Instagram, TikTok or YouTube video URL.');
+  return u.href;
+}
+
+export function downloadArgs({ url, output, ffmpeg, node = process.execPath }) {
+  return [
+    '--ignore-config', '--no-simulate', '--no-cache-dir', '--no-playlist', '--no-overwrites',
+    '--socket-timeout', '20', '--retries', '1', '--fragment-retries', '1',
+    '--max-filesize', '500M', '--match-filter', 'duration <=? 1800',
+    '--js-runtimes', `node:${node}`, '--ffmpeg-location', dirname(ffmpeg),
+    '--format', 'bv[height<=720][ext=mp4][vcodec^=avc1]+ba[ext=m4a]/b[height<=?720][ext=mp4]/b[height<=?720]',
+    '--merge-output-format', 'mp4', '--remux-video', 'mp4',
+    '--print', 'after_move:filepath', '--output', output.replace(/\.mp4$/i, '') + '.%(ext)s',
+    '--', referenceUrl(url),
+  ];
+}
+
+export function downloadReference({ url, output, ytdlp, ffmpeg, run = spawnSync }) {
+  const dest = resolve(output);
+  if (!/\.mp4$/i.test(dest)) throw new Error('Reference output must end in .mp4.');
+  referenceUrl(url);
+  if (existsSync(dest)) return dest;
+  mkdirSync(dirname(dest), { recursive: true });
+  const r = run(ytdlp, downloadArgs({ url, output: dest, ffmpeg }), {
+    encoding: 'utf8', timeout: 600_000, maxBuffer: 4 * 1024 * 1024,
+    env: { ...process.env, PATH: `${dirname(ffmpeg)}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH ?? ''}` },
+  });
+  if (r.error || r.status !== 0 || !existsSync(dest)) {
+    throw new Error(`Reference download failed. Use the transcript already supplied by Ignix if available; do not claim to have seen the visuals. Otherwise request the original file. ${r.error?.message ?? (r.stderr ?? '').slice(-1200)}`);
+  }
+  return dest;
+}