@ignix-social/editor 0.1.16 → 0.1.18

package/package.json

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

@@ -15,6 +15,8 @@ Commands. `ignix-editor` means the copy the Ignix playbook installed: `~/.ignix-
 | `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 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. |
+| `ignix-editor pick-audio [dir] --kind music\|sfx --query "inspiring" [--order trending]` | Music (or a specific sound effect) from Pixabay, chosen by the USER: opens Pixabay's search in their browser, waits for their download, copies it into `assets/` and notes its source in `work/audio-sources.json`. Tell the user first that you opened Pixabay for them to pick one. Never fetch pixabay.com yourself: it blocks robots. |
+| `ignix-editor giphy --search "thumbs up" [--kind gifs\|stickers\|clips]` · `ignix-editor giphy <link> [dir]` | GIFs, stickers and clips from GIPHY, chosen by the USER: the first opens GIPHY's search in their browser; they copy the link of the one they like (Share → Copy link) and the second brings it into `assets/`: a GIF as MP4, a clip as MP4 with its audio, a sticker as a transparent frame sheet (see section 2, GIPHY stickers). |
 | `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. `[dir]` defaults to the current folder. |
 | `ignix-editor render [dir] [-o out.mp4]` | Renders to `<dir>/renders/<dir>.mp4`, audio normalised to −14 LUFS. |
@@ -75,6 +77,21 @@ The renderer asks for frames independently (in parallel, out of order). If frame
 - Use `transform` (translate/scale/rotate) and `opacity` for motion; animating `left/top/width/height/font-size` snaps to whole pixels and stutters in slow moves.
 - Toggling `display`, `textContent` or a class from `t` is fine (typed text: `KEY.slice(0, n(t))`).
 
+### GIPHY stickers (transparent, animated)
+
+Never put an animated GIF/WebP in an `<img>`: it plays on the browser's clock, not the render's, and comes out jumpy. `ignix-editor giphy <sticker link>` gives a transparent sheet with every frame and prints `frames`, `cols`, `rows`, `fps` and the frame size. Show one cell at a time, chosen from `t`:
+
+```js
+// e.g. 51 frames, 8×7 sheet, 25 fps, 256×256 each; the element is 256×256 (scale it with transform)
+const S = { frames: 51, cols: 8, rows: 7, fps: 25 };
+sticker.style.background = `url(assets/giphy-sticker-ID-sheet.png) 0 0 / ${S.cols * 100}% ${S.rows * 100}% no-repeat`;
+// inside run(): loops while it is on screen
+const i = Math.floor(Math.max(0, t - start) * S.fps) % S.frames;
+sticker.style.backgroundPosition = `${((i % S.cols) / (S.cols - 1)) * 100}% ${(Math.floor(i / S.cols) / (S.rows - 1)) * 100}%`;
+```
+
+GIFs and clips come as MP4: use them like any `<video>` (a clip keeps its audio; mute it if the voice-over runs over it).
+
 ### Never measure the page while rendering
 
 Do not call `getBoundingClientRect()`/`offsetLeft` to aim arrows, cursors or highlight boxes: fonts may not be ready and layout may differ per frame; arrows pointed 300 px off and vanished in a test because of this. Instead, give the recreated UI fixed coordinates and keep a table:

package/src/cli.mjs

@@ -19,6 +19,8 @@ import { creatorJob } from './creator/job.mjs';
 import { fetchAll } from './fetch.mjs';
 import { measureStyle } from './analysis/style.mjs';
 import { reviewVideo } from './analysis/review.mjs';
+import { pickAudio } from './pick-audio.mjs';
+import { importGiphy, openGiphySearch } from './giphy.mjs';
 
 const PKG_DIR = join(dirname(fileURLToPath(import.meta.url)), '..');
 const PKG = JSON.parse(readFileSync(join(PKG_DIR, 'package.json'), 'utf8'));
@@ -223,6 +225,61 @@ const commands = {
     } else console.log(json);
   },
 
+  // Música o efectos de Pixabay elegidos por la persona (src/pick-audio.mjs): abre la
+  // búsqueda en su navegador, espera su descarga y la copia al proyecto.
+  async 'pick-audio'(argv) {
+    const { pos, opts } = parseArgs(argv, { kind: 'str', query: 'str', order: 'str', count: 'str', timeout: 'str', downloads: 'str', open: 'bool', json: 'bool' });
+    const project = resolve(pos[0] ?? '.');
+    const kind = opts.kind === 'sfx' ? 'sfx' : 'music';
+    if (!opts.query || !existsSync(project)) {
+      fail('Usage: ignix-editor pick-audio [folder] --kind music|sfx --query "inspiring" [--order trending|latest] [--count 1] [--timeout 600] [--no-open] [--downloads <folder>] [--json]');
+    }
+    const r = await pickAudio({
+      project,
+      kind,
+      query: opts.query,
+      order: opts.order,
+      count: Math.max(1, Math.min(10, Number(opts.count ?? 1) || 1)),
+      timeoutSec: Math.max(30, Number(opts.timeout ?? 600) || 600),
+      downloads: opts.downloads,
+      open: opts.open !== false,
+      log,
+    });
+    if (opts.json) console.log(JSON.stringify(r, null, 1));
+    if (r.timedOut) {
+      log(r.picked.length ? `Only ${r.picked.length} downloaded before the time ran out.` : 'Nothing was downloaded. Ask the person whether they found something, then run this again.');
+      process.exitCode = 2;
+    }
+  },
+
+  // GIFs, stickers y clips de GIPHY elegidos por la persona (src/giphy.mjs): abre la
+  // búsqueda en su navegador, o trae el enlace que ha copiado.
+  async giphy(argv) {
+    const { pos, opts } = parseArgs(argv, { search: 'str', kind: 'str', open: 'bool', json: 'bool' });
+    const usage = 'Usage: ignix-editor giphy --search "thumbs up" [--kind gifs|stickers|clips]   or   ignix-editor giphy <link> [folder]';
+    if (opts.search) {
+      const kind = ['stickers', 'clips'].includes(opts.kind) ? opts.kind : 'gifs';
+      const r = opts.open === false ? { url: (await import('./giphy.mjs')).giphySearchUrl(opts.search, kind), opened: false } : openGiphySearch(opts.search, kind);
+      log(r.opened ? `Opened in the browser: ${r.url}` : `Open this in the browser: ${r.url}`);
+      log('Ask the person to copy the link of the one they like (Share → Copy link) and paste it here; then run: ignix-editor giphy <link> <folder>');
+      if (opts.json) console.log(JSON.stringify(r));
+      return;
+    }
+    const link = pos[0];
+    if (!link) fail(usage);
+    const project = resolve(pos[1] ?? '.');
+    if (!existsSync(project)) fail(`Folder not found: ${project}`);
+    const forced = { gifs: 'gif', gif: 'gif', stickers: 'sticker', sticker: 'sticker', clips: 'clip', clip: 'clip' }[opts.kind];
+    const ffmpeg = await ensureTool('ffmpeg', log);
+    const ffprobe = await ensureTool('ffprobe', log);
+    const r = await importGiphy({ link, project, kind: forced, ffmpeg, ffprobe }).catch((e) => fail(e.message));
+    if (r.sheet) {
+      const sh = r.sheet;
+      log(`✓ sticker → ${r.file}: ${sh.frames} frames in a ${sh.cols}×${sh.rows} transparent sheet, ${sh.frameWidth}×${sh.frameHeight} each, ${sh.fps} fps (${sh.durationSec} s loop). Animate it from t as the skill shows (GIPHY section).`);
+    } else log(`✓ ${r.kind} → ${r.file}${r.hasAudio ? ' (with its audio)' : ''}`);
+    if (opts.json) console.log(JSON.stringify(r));
+  },
+
   // El estilo de edición de alguien, medido en 2–3 vídeos suyos (ADR-0023 E3).
   async style(argv) {
     const [sub, ...rest] = argv;
@@ -356,10 +413,14 @@ const commands = {
   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, sound effects
+  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 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]
+                                               opens the Pixabay search in the browser, waits for the person's download, copies it into assets/
+  ignix-editor giphy --search "thumbs up" [--kind gifs|stickers|clips]   opens the GIPHY search in the browser
+  ignix-editor giphy <link> [folder]           brings the GIF (mp4), sticker (transparent frame sheet) or clip (mp4 with audio) into assets/
   ignix-editor style measure <video>… [--speech] [--stills dir] [-o style.json]   someone's editing style, measured on 2–3 of their videos
   ignix-editor ffmpeg|ffprobe <args>           Ignix Editor's own ffmpeg
   ignix-editor skills add                      installs the skill for Claude

package/src/giphy.mjs

@@ -0,0 +1,136 @@
+import { spawnSync } from 'node:child_process';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { openInBrowser } from './pick-audio.mjs';
+
+// GIFs, STICKERS Y CLIPS DE GIPHY, ELEGIDOS POR LA PERSONA (2026-10-08, Fran).
+//
+// Sin la API de GIPHY (pide clave y revisión): la persona busca en giphy.com (esto le
+// abre la búsqueda), copia el enlace del que le gusta y el agente lo trae con
+// `ignix-editor giphy <enlace>`. Con el id del enlace, GIPHY sirve cada formato en
+// media.giphy.com: el GIF como MP4 (mejor para vídeo), el sticker como WebP con
+// transparencia (para superponerlo) y el clip como MP4 con su audio.
+//
+// El sticker NO va como imagen animada: un GIF/WebP en un <img> corre con el reloj del
+// navegador, no con el del render (cada fotograma se pide suelto y fuera de orden), así
+// que saldría a saltos. Va como TIRA de fotogramas en un PNG con transparencia
+// (ffmpeg, filtro tile) que el vídeo recorre desde `t` (ver la guía, sección GIPHY).
+
+const ID = /^[A-Za-z0-9]{6,40}$/;
+
+/** El id y el tipo de un enlace de GIPHY (página, media, i.giphy o embed). null si no lo es. */
+export function parseGiphyLink(raw) {
+  let u;
+  try {
+    u = new URL(String(raw ?? '').trim());
+  } catch {
+    return null;
+  }
+  const host = u.hostname.replace(/^www\./, '');
+  if (!/(^|\.)giphy\.com$/.test(host)) return null;
+  const parts = u.pathname.split('/').filter(Boolean);
+  // giphy.com/gifs/<slug>-<id>, /stickers/<slug>-<id>, /clips/<slug>-<id>, /embed/<id>
+  if (host === 'giphy.com' && parts.length >= 2) {
+    const kind = { gifs: 'gif', stickers: 'sticker', clips: 'clip', embed: 'gif' }[parts[0]];
+    const last = parts[1];
+    const id = last.includes('-') ? last.slice(last.lastIndexOf('-') + 1) : last;
+    return kind && ID.test(id) ? { id, kind } : null;
+  }
+  // media*.giphy.com/media/(v1.xxx/)?<id>/<fichero>
+  const m = parts.indexOf('media');
+  if (m >= 0) {
+    const rest = parts.slice(m + 1);
+    const id = rest[0]?.startsWith('v1.') ? rest[1] : rest[0];
+    return id && ID.test(id) ? { id, kind: null } : null;
+  }
+  // i.giphy.com/<id>.webp
+  if (host === 'i.giphy.com' && parts[0]) {
+    const id = parts[0].replace(/\.[a-z0-9]+$/i, '');
+    return ID.test(id) ? { id, kind: null } : null;
+  }
+  return null;
+}
+
+/** La búsqueda de GIPHY como la usa una persona en su web. */
+export function giphySearchUrl(query, kind = 'gifs') {
+  const slug = String(query ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 80);
+  const suffix = kind === 'stickers' ? '-stickers' : kind === 'clips' ? '-clips' : '';
+  return `https://giphy.com/search/${encodeURIComponent(slug).replace(/%2D/gi, '-')}${suffix}`;
+}
+
+/** Qué fichero traer de media.giphy.com para cada tipo (y el de reserva). */
+export function giphyRenditions(kind) {
+  if (kind === 'clip') return [['giphy480p.mp4', 'mp4'], ['giphy.mp4', 'mp4']];
+  if (kind === 'sticker') return [['giphy.gif', 'gif']];
+  return [['giphy.mp4', 'mp4'], ['giphy.gif', 'gif']];
+}
+
+/** Trae el elegido a `<project>/assets/` y apunta su origen en `work/media-sources.json`. */
+/**
+ * Un GIF con transparencia → una tira PNG (cols × rows fotogramas) + sus medidas.
+ * `ffmpeg`/`ffprobe` son los del Editor.
+ */
+export function gifToSheet({ ffmpeg, ffprobe, gif, out }) {
+  const pr = spawnSync(ffprobe, ['-v', 'error', '-count_frames', '-select_streams', 'v:0', '-show_entries', 'stream=width,height,nb_read_frames,r_frame_rate:format=duration', '-of', 'json', gif], { encoding: 'utf8' });
+  const j = JSON.parse(pr.stdout || '{}');
+  const st = j.streams?.[0] ?? {};
+  const frames = Math.max(1, Number(st.nb_read_frames) || 1);
+  const durationSec = Number(j.format?.duration) || frames / 15;
+  const fps = Math.round((frames / durationSec) * 100) / 100;
+  // Rejilla casi cuadrada: una tira larga pasaría del tamaño máximo de textura de Chrome.
+  const cols = Math.ceil(Math.sqrt(frames));
+  const rows = Math.ceil(frames / cols);
+  const r = spawnSync(ffmpeg, ['-nostdin', '-y', '-v', 'error', '-i', gif, '-vf', `format=rgba,tile=${cols}x${rows}`, '-frames:v', '1', out], { encoding: 'utf8' });
+  if (r.status !== 0) throw new Error(`Could not turn the sticker into frames: ${(r.stderr || '').slice(-300)}`);
+  return { sheet: out, frames, cols, rows, fps, durationSec: Math.round(durationSec * 100) / 100, frameWidth: Number(st.width), frameHeight: Number(st.height) };
+}
+
+export async function importGiphy({ link, project, kind: forced, ffmpeg, ffprobe }) {
+  const parsed = parseGiphyLink(link);
+  if (!parsed) throw new Error('That is not a GIPHY link. Copy the link of the GIF, sticker or clip from giphy.com.');
+  const kind = forced ?? parsed.kind ?? 'gif';
+  const assets = join(project, 'assets');
+  mkdirSync(assets, { recursive: true });
+  let lastErr = null;
+  for (const [file, ext] of giphyRenditions(kind)) {
+    const url = `https://media.giphy.com/media/${parsed.id}/${file}`;
+    const res = await fetch(url).catch((e) => {
+      lastErr = e;
+      return null;
+    });
+    if (!res?.ok || !res.body) continue;
+    let dest = join(assets, `giphy-${kind}-${parsed.id}.${ext}`);
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest));
+    let sheet = null;
+    if (kind === 'sticker' && ffmpeg && ffprobe) {
+      sheet = gifToSheet({ ffmpeg, ffprobe, gif: dest, out: join(assets, `giphy-sticker-${parsed.id}-sheet.png`) });
+      rmSync(dest, { force: true });
+      dest = sheet.sheet;
+    }
+    const work = join(project, 'work');
+    mkdirSync(work, { recursive: true });
+    const log = join(work, 'media-sources.json');
+    let prev = [];
+    try {
+      prev = existsSync(log) ? JSON.parse(readFileSync(log, 'utf8')) : [];
+    } catch {
+      /* fichero roto: se empieza de nuevo */
+    }
+    writeFileSync(log, JSON.stringify([...prev, { source: 'giphy', kind, id: parsed.id, link: String(link), file: dest, at: new Date().toISOString() }], null, 2));
+    return { id: parsed.id, kind, file: dest, hasAudio: kind === 'clip' && file.includes('480p'), ...(sheet ? { sheet } : {}) };
+  }
+  throw new Error(`Could not download that ${kind} from GIPHY${lastErr ? `: ${lastErr.message}` : ''}.`);
+}
+
+/** Abre la búsqueda en el navegador de la persona. */
+export function openGiphySearch(query, kind) {
+  const url = giphySearchUrl(query, kind);
+  return { url, opened: openInBrowser(url) };
+}

package/src/pick-audio.mjs

@@ -0,0 +1,152 @@
+import { spawn } from 'node:child_process';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { basename, extname, join } from 'node:path';
+
+// MÚSICA Y EFECTOS DE PIXABAY, ELEGIDOS POR LA PERSONA (2026-10-08, idea de Fran).
+//
+// Pixabay no tiene API de audio y su web no deja entrar a robots (Cloudflare devuelve 403
+// a todo lo que no sea un navegador con una persona). Así que el agente NO busca ni
+// descarga: abre la búsqueda en el navegador de la persona, ella escucha los avances y
+// pulsa «Descargar» en el que le gusta, y esto lo recoge de su carpeta de Descargas y lo
+// copia al proyecto. La licencia de Pixabay permite usarlo en redes; guardamos de dónde
+// salió (nombre del fichero y búsqueda) porque es lo que Pixabay pide para responder a
+// una reclamación de Content ID en YouTube.
+
+const AUDIO = new Set(['.mp3', '.wav', '.m4a', '.ogg', '.aac', '.flac']);
+/** Descargas a medias de Chrome, Firefox, Safari y Edge. */
+const PARTIAL = /\.(crdownload|part|download|partial|tmp)$/i;
+
+/** La búsqueda de Pixabay, como la usa una persona en su web. */
+export function pixabayAudioUrl(kind, query, order) {
+  const base = kind === 'sfx' ? 'https://pixabay.com/sound-effects/search/' : 'https://pixabay.com/music/search/';
+  const q = encodeURIComponent(String(query ?? '').trim().replace(/\s+/g, ' ').slice(0, 80));
+  const o = order && ['trending', 'latest', 'ec'].includes(order) ? `?order=${order}` : '';
+  return `${base}${q}/${o}`;
+}
+
+/** La carpeta de Descargas de esta persona (la normal; `--downloads` para otra). */
+export function downloadsDir(override) {
+  if (override) return override;
+  return join(homedir(), 'Downloads');
+}
+
+/** Abre la URL en el navegador de la persona. false si no se pudo (sandbox, sin escritorio). */
+export function openInBrowser(url) {
+  try {
+    const os = platform();
+    const [cmd, args] =
+      os === 'darwin' ? ['open', [url]] : os === 'win32' ? ['cmd', ['/c', 'start', '""', url.replace(/&/g, '^&')]] : ['xdg-open', [url]];
+    const child = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Ficheros de audio terminados que han aparecido en `dir` después de `since` (ms). */
+export function newAudioFiles(dir, since, seen = new Set()) {
+  let names = [];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const name of names) {
+    if (seen.has(name) || PARTIAL.test(name) || !AUDIO.has(extname(name).toLowerCase())) continue;
+    let st;
+    try {
+      st = statSync(join(dir, name));
+    } catch {
+      continue;
+    }
+    // birthtime no existe en todos los sistemas de ficheros: vale la última escritura.
+    const t = Math.max(st.mtimeMs, st.birthtimeMs || 0);
+    if (st.isFile() && st.size > 0 && t >= since) out.push({ name, path: join(dir, name), size: st.size });
+  }
+  return out;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Espera a que el fichero deje de crecer (la descarga terminó de escribirse). */
+async function settled(path) {
+  let last = -1;
+  for (let i = 0; i < 20; i++) {
+    let size = -1;
+    try {
+      size = statSync(path).size;
+    } catch {
+      return false;
+    }
+    if (size > 0 && size === last) return true;
+    last = size;
+    await sleep(500);
+  }
+  return true;
+}
+
+const slug = (s) =>
+  s
+    .normalize('NFKD')
+    .replace(/[̀-ͯ]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    .slice(0, 60) || 'audio';
+
+/**
+ * Abre la búsqueda y espera a que la persona descargue `count` ficheros; los copia a
+ * `<project>/assets/` y apunta su origen en `<project>/work/audio-sources.json`.
+ */
+export async function pickAudio({ project, kind, query, order, count = 1, timeoutSec = 600, downloads, open = true, log = () => {} }) {
+  const url = pixabayAudioUrl(kind, query, order);
+  const dir = downloadsDir(downloads);
+  if (!existsSync(dir)) throw new Error(`Downloads folder not found: ${dir}. Pass --downloads <folder>.`);
+  const since = Date.now() - 1000;
+  const opened = open ? openInBrowser(url) : false;
+  log(opened ? `Opened in the browser: ${url}` : `Open this in the browser: ${url}`);
+  log(`Waiting for ${count === 1 ? 'a download' : `${count} downloads`} in ${dir} (up to ${Math.round(timeoutSec / 60)} min)…`);
+
+  const seen = new Set();
+  const picked = [];
+  const deadline = Date.now() + timeoutSec * 1000;
+  while (picked.length < count && Date.now() < deadline) {
+    for (const f of newAudioFiles(dir, since, seen)) {
+      seen.add(f.name);
+      if (!(await settled(f.path))) continue;
+      const assets = join(project, 'assets');
+      mkdirSync(assets, { recursive: true });
+      const ext = extname(f.name).toLowerCase();
+      let dest = join(assets, `${kind === 'sfx' ? 'sfx' : 'music'}-${slug(basename(f.name, ext))}${ext}`);
+      for (let n = 2; existsSync(dest); n++) dest = join(assets, `${kind === 'sfx' ? 'sfx' : 'music'}-${slug(basename(f.name, ext))}-${n}${ext}`);
+      copyFileSync(f.path, dest);
+      picked.push({ file: dest, originalName: f.name, bytes: f.size });
+      log(`✓ Got ${f.name} → ${dest}`);
+      if (picked.length >= count) break;
+    }
+    if (picked.length < count) await sleep(1000);
+  }
+
+  // De dónde salió cada uno: Pixabay pide conservarlo para disputar un Content ID.
+  if (picked.length) {
+    const work = join(project, 'work');
+    mkdirSync(work, { recursive: true });
+    const file = join(work, 'audio-sources.json');
+    let prev = [];
+    try {
+      prev = JSON.parse(readFileSync(file, 'utf8'));
+    } catch {
+      /* primera vez */
+    }
+    const now = new Date().toISOString();
+    writeFileSync(
+      file,
+      JSON.stringify([...prev, ...picked.map((p) => ({ source: 'pixabay', kind, search: url, originalName: p.originalName, file: p.file, downloadedAt: now }))], null, 2),
+    );
+  }
+  return { url, opened, picked, timedOut: picked.length < count };
+}