@ignix-social/editor 0.1.26 → 0.1.27

package/package.json

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

@@ -53,7 +53,8 @@ The engine reads `<video>`/`<audio>` from the HTML file before the page runs. Me
 - Give each sound effect its own `data-track-index` (overlapping sounds on one track get a warning).
 - Never put `data-start` on BOTH a video and an element that contains it: time the video, and put a plain (untimed) wrapper around it for zoom/crop/position.
 - Never add `crossorigin` to media. Never call `play()`, `pause()` or set `currentTime`: the engine owns playback.
-- Fades and ducking: a volume lane on the element, e.g. 8 ms fades at each cut so it does not click:
+- Music ducks BY ITSELF under the voice at check/render: give the music `<audio>` the id `music` (or `data-role="music"`) and set its `data-volume` to its level when nobody talks; it drops about 13 dB under every voice line (`vo1`, `voice2`… or `data-role="voice"`) and under any `<video>` that keeps its own sound, and comes back up in pauses longer than 0.6 s. Do not draw that by hand. `data-duck="off"` on the music keeps it flat.
+- Fades: a volume lane on the element, e.g. 8 ms fades at each cut so it does not click:
   `data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":0},{"t":0.008,"v":1},{"t":2.95,"v":1},{"t":2.9667,"v":0}]}]}'` (`t` is seconds from the clip's own start).
 - Times are snapped to the nearest frame by the editor; still write them with enough decimals (frame / fps).
 

package/src/cli.mjs

@@ -35,6 +35,11 @@ const requireHere = createRequire(import.meta.url);
 const depDir = (name) => dirname(requireHere.resolve(`${name}/package.json`));
 
 const log = (...a) => console.error(...a);
+// Qué hizo el ducking automático (duck.mjs): que el asistente lo sepa y no lo duplique a mano.
+function logDuck(duck) {
+  for (const d of duck?.ducked ?? []) log(`• Music "${d.id}" ducked under the voice (${d.spans} span${d.spans === 1 ? '' : 's'}). Set data-duck="off" on it to keep it flat.`);
+  for (const d of duck?.skipped ?? []) log(`• Music "${d.id}" not ducked: ${d.reason}.`);
+}
 const fail = (msg) => {
   log(`✗ ${msg}`);
   process.exit(1);
@@ -145,8 +150,9 @@ const commands = {
     const { pos, rest } = parseArgs(argv, {});
     const dir = projectDir(pos[0]);
     const errors = validateProject(dir);
-    const { build, snapped } = prepare(dir);
+    const { build, snapped, duck } = prepare(dir);
     if (snapped) log(`• ${snapped} time(s) snapped to the nearest frame`);
+    logDuck(duck);
     const { env } = await engineEnv(log);
     const code = runEngine(['check', build, ...rest], env, dir);
     process.exit(errors ? 1 : code);
@@ -169,6 +175,7 @@ const commands = {
     const output = resolve(opts.output ?? join(dir, 'renders', `${basename(dir)}.mp4`));
     const r = await renderProject(dir, output, { lufs: opts.lufs, normalize: opts.normalize, engineArgs: rest, log });
     if (r.snapped) log(`• ${r.snapped} time(s) snapped to the nearest frame`);
+    logDuck(r.duck);
     if (r.loudness) log(`✓ Loudness: ${r.loudness.before.toFixed(1)} → ${r.loudness.after?.toFixed(1)} LUFS`);
     // La revisión va SIEMPRE detrás del render (salvo --no-review): un agente con prisa se
     // salta un paso aparte, pero no puede no ver esto. El MP4 queda hecho igualmente.

package/src/creator/build.mjs

@@ -288,7 +288,8 @@ export function buildProject({ spec, media, dir, ffmpeg, ffprobe }) {
     const keys = new Set([0, spec.audio.fadeInSec, duration - spec.audio.fadeOutSec, dur]);
     if (spec.audio.duck) for (const iv of speechIntervals(spec)) for (const x of [iv.start - DUCK_RAMP_SEC, iv.start, iv.end, iv.end + DUCK_RAMP_SEC * 2]) keys.add(x);
     const points = [...keys].filter((x) => x >= 0 && x <= dur).sort((a, b) => a - b).map((x) => [x, musicLevel(spec, duration, x)]);
-    body.push(`<audio ${attrs({ id: 'music', src: file, 'data-start': 0, 'data-duration': dur, 'data-volume': 1, 'data-automation': lane(points), 'data-track-index': track++ })}></audio>`);
+    // Creator ya decide (spec.audio.duck) y lo lleva en la curva: el ducking automático no la toca.
+    body.push(`<audio ${attrs({ id: 'music', src: file, 'data-start': 0, 'data-duration': dur, 'data-volume': 1, 'data-automation': lane(points), 'data-duck': 'off', 'data-track-index': track++ })}></audio>`);
   }
   spec.voice.forEach((v, i) => {
     let file = place(v.asset);

package/src/duck.mjs

@@ -0,0 +1,142 @@
+// Ducking automático: la música baja sola mientras alguien habla y vuelve a subir en las pausas.
+//
+// Creator ya lo hacía (creator/build.mjs, `duck`), pero una composición escrita a mano por un
+// asistente dejaba la música plana: la guía lo mencionaba y nadie lo hacía (2026-10-09, reel
+// «One post. One job.»: música a 0,16 fija bajo once frases). Ahora se aplica en la copia de
+// trabajo (prepare), así que check, snapshot, preview y render lo oyen igual, y el proyecto del
+// usuario no se toca.
+//
+//   música  <audio> con data-role="music", o id music / bgm / soundtrack / song / bed (music2…)
+//   voz     <audio> con data-role="voice|speech|narration", o id vo / voice / narration / line (+n);
+//           y <video> con su sonido (data-has-audio="true", sin muted), salvo data-role="music|sfx".
+//
+// Se respeta: data-duck="off" (o cualquier valor distinto de "auto"/"on") y una música que ya trae
+// su propia curva de volumen con más de 4 puntos (alguien la dibujó a mano). Las fades sencillas
+// (entrada / salida) se conservan: el ducking se MULTIPLICA por la curva que hubiera.
+
+export const DUCKED = 0.22; // ≈ −13 dB bajo la voz (lo mismo que Creator)
+export const DUCK_RAMP_SEC = 0.18; // baja en 0,18 s antes de la frase, sube en 0,36 s después
+const JOIN_GAP_SEC = 0.6; // pausas más cortas no la suben: sin «bombeo» entre frase y frase
+
+const TAG = /<(audio|video)\b[^>]*>/gi;
+const ATTR = /([\w:-]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'))?/g;
+const MUSIC_ID = /^(music|bgm|soundtrack|song|bed)([-_]?\w*)?$/i;
+const VOICE_ID = /^(vo|voice|narration|narrator|line|speech)([-_]?\d+)?$/i;
+
+function attrsOf(tag) {
+  const inner = tag.replace(/^<\w+/, '').replace(/\/?>$/, '');
+  const out = {};
+  for (const m of inner.matchAll(ATTR)) out[m[1].toLowerCase()] = m[2] ?? m[3] ?? true;
+  return out;
+}
+
+const num = (v, d = NaN) => (v === undefined || v === true || v === '' ? d : Number(v));
+
+function isMusic(kind, a) {
+  if (kind !== 'audio') return false;
+  return a['data-role'] === 'music' || (typeof a.id === 'string' && MUSIC_ID.test(a.id));
+}
+
+function isSpeech(kind, a) {
+  if (num(a['data-volume'], 1) <= 0) return false;
+  const role = a['data-role'];
+  if (role === 'voice' || role === 'speech' || role === 'narration') return true;
+  if (role === 'music' || role === 'sfx') return false;
+  if (kind === 'audio') return typeof a.id === 'string' && VOICE_ID.test(a.id);
+  return a['data-has-audio'] === 'true' && a.muted === undefined;
+}
+
+/** Tramos [inicio, fin] (tiempo de la composición) en los que habla alguien, ya unidos. */
+export function speechSpans(html) {
+  const spans = [];
+  for (const m of html.matchAll(TAG)) {
+    const a = attrsOf(m[0]);
+    if (!isSpeech(m[1].toLowerCase(), a)) continue;
+    const s = num(a['data-start']);
+    const d = num(a['data-duration']);
+    if (Number.isFinite(s) && Number.isFinite(d) && d > 0) spans.push([s, s + d]);
+  }
+  spans.sort((x, y) => x[0] - y[0]);
+  const out = [];
+  for (const [s, e] of spans) {
+    const last = out[out.length - 1];
+    if (last && s - last[1] < JOIN_GAP_SEC) last[1] = Math.max(last[1], e);
+    else out.push([s, e]);
+  }
+  return out;
+}
+
+const lin = (t, [a, b], [va, vb]) => (t <= a ? va : t >= b ? vb : va + ((t - a) / (b - a)) * (vb - va));
+
+function laneAt(points, t) {
+  if (!points?.length) return 1;
+  if (t <= points[0].t) return points[0].v;
+  for (let i = 1; i < points.length; i++) {
+    if (t <= points[i].t) return lin(t, [points[i - 1].t, points[i].t], [points[i - 1].v, points[i].v]);
+  }
+  return points[points.length - 1].v;
+}
+
+function duckAt(spans, t) {
+  let g = 1;
+  for (const [s, e] of spans) {
+    if (t < s - DUCK_RAMP_SEC || t > e + DUCK_RAMP_SEC * 2) continue;
+    const down = lin(t, [s - DUCK_RAMP_SEC, s], [1, DUCKED]);
+    const up = lin(t, [e, e + DUCK_RAMP_SEC * 2], [DUCKED, 1]);
+    g = Math.min(g, t < s ? down : t > e ? up : DUCKED);
+  }
+  return g;
+}
+
+/**
+ * Baja la música bajo la voz en un HTML. Devuelve el HTML (igual si no hay nada que hacer) y
+ * qué hizo: { ducked: [{ id, spans }], skipped: [{ id, reason }] }.
+ */
+export function autoDuck(html) {
+  const spans = speechSpans(html);
+  const report = { ducked: [], skipped: [] };
+  if (spans.length === 0) return { html, ...report };
+  const out = html.replace(TAG, (tag, kind) => {
+    const a = attrsOf(tag);
+    if (!isMusic(kind.toLowerCase(), a)) return tag;
+    const id = typeof a.id === 'string' ? a.id : '(music)';
+    const mode = a['data-duck'];
+    if (mode !== undefined && mode !== 'auto' && mode !== 'on') {
+      report.skipped.push({ id, reason: `data-duck="${mode}"` });
+      return tag;
+    }
+    let auto = { version: 1, lanes: [] };
+    if (typeof a['data-automation'] === 'string') {
+      try {
+        auto = JSON.parse(a['data-automation'].replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, '&'));
+      } catch {
+        report.skipped.push({ id, reason: 'its data-automation is not valid JSON' });
+        return tag;
+      }
+    }
+    const lanes = Array.isArray(auto.lanes) ? auto.lanes : [];
+    const vol = lanes.find((l) => l?.target === 'volume');
+    const own = Array.isArray(vol?.points) ? vol.points.filter((p) => Number.isFinite(p?.t) && Number.isFinite(p?.v)).sort((x, y) => x.t - y.t) : [];
+    if (own.length > 4) {
+      report.skipped.push({ id, reason: 'it already has its own volume curve' });
+      return tag;
+    }
+    const start = num(a['data-start'], 0);
+    const dur = num(a['data-duration']);
+    const end = Number.isFinite(dur) ? dur : Math.max(...spans.map(([, e]) => e - start)) + 1;
+    const local = spans.map(([s, e]) => [s - start, e - start]).filter(([s, e]) => e > 0 && s < end);
+    if (local.length === 0) return tag;
+    const keys = new Set([0, end, ...own.map((p) => p.t)]);
+    for (const [s, e] of local) for (const x of [s - DUCK_RAMP_SEC, s, e, e + DUCK_RAMP_SEC * 2]) keys.add(x);
+    const points = [...keys]
+      .filter((x) => x >= 0 && x <= end)
+      .sort((x, y) => x - y)
+      .map((t) => ({ t: Number(t.toFixed(4)), v: Number((laneAt(own, t) * duckAt(local, t)).toFixed(4)) }));
+    const next = { ...auto, version: auto.version ?? 1, lanes: [...lanes.filter((l) => l !== vol), { ...(vol ?? {}), target: 'volume', points }] };
+    report.ducked.push({ id, spans: local.length });
+    const json = JSON.stringify(next).replace(/'/g, '&#39;');
+    const without = tag.replace(/\sdata-automation\s*=\s*(?:"[^"]*"|'[^']*')/i, '');
+    return without.replace(/^<audio\b/i, `<audio data-automation='${json}'`);
+  });
+  return { html: out, ...report };
+}

package/src/engine.mjs

@@ -81,7 +81,7 @@ export function runEngineAsync(args, env, cwd, { onLine = () => {}, signal } = {
  * y, si hay sonido, la mezcla a `lufs` (−14 por defecto; `normalize: false` lo deja tal cual).
  */
 export async function renderProject(dir, output, { lufs = -14, normalize = true, engineArgs = [], quiet = false, onProgress, signal, browser, log = () => {} } = {}) {
-  const { build, snapped } = prepare(dir);
+  const { build, snapped, duck } = prepare(dir);
   const { env, ffmpeg, ffprobe } = await engineEnv(log);
   if (browser) env.HYPERFRAMES_BROWSER_PATH = browser;
   mkdirSync(dirname(output), { recursive: true });
@@ -109,5 +109,5 @@ export async function renderProject(dir, output, { lufs = -14, normalize = true,
     const r = normalizeLoudness(ffmpeg, raw, output, { lufs: Number(lufs ?? -14) });
     level = { before: r.before, after: loudness(ffmpeg, output) };
   } else cpSync(raw, output);
-  return { output, snapped, loudness: level };
+  return { output, snapped, duck, loudness: level };
 }

package/src/prepare.mjs

@@ -7,6 +7,7 @@ import './win-fs-preload.mjs'; // Windows: fs.cpSync con rutas no ASCII (win-fs.
 import { copyFileSync, cpSync, existsSync, linkSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { autoDuck } from './duck.mjs';
 
 const RUNTIME = join(dirname(fileURLToPath(import.meta.url)), 'runtime', 'ignix-frame.js');
 const SKIP = new Set(['.ignix-build', 'renders', 'snapshots', 'node_modules', '.git', '.DS_Store']);
@@ -88,6 +89,9 @@ export function prepare(projectDir) {
   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>'));
   }
+  // La música baja sola bajo la voz (duck.mjs), con los tiempos ya ajustados al fotograma.
+  const duck = autoDuck(readFileSync(root, 'utf8'));
+  if (duck.ducked.length) writeFileSync(root, duck.html);
   cpSync(RUNTIME, join(build, 'ignix-frame.js'));
-  return { build, fps, snapped };
+  return { build, fps, snapped, duck: { ducked: duck.ducked, skipped: duck.skipped } };
 }