perso-dubbing 0.2.0

package/skills/dubbing/lib/scheduler.mjs

@@ -0,0 +1,228 @@
+// Scheduler (C/Q concurrency). Pools (chunk × language) from multiple inputs into one queue for concurrent processing.
+//   Result: `${inputId}|${index}|${target}` → { inputId, index, target, status, path?, projectId?, name?, reason? }
+//   - OK          : path of the dubbing result downloaded locally
+//   - PASSTHROUGH : silent (split chunk) → original chunk path as-is (merge included)
+//   - DLFAIL      : generated (has projectSeq) · only download failed → re-download on resume (no regeneration)
+//   - HARD_FAIL   : excluded from merge (group boundary)
+import { basename, join } from 'node:path';
+import { makeTempDir } from './tmp.mjs';
+import { upload, requestTranslation, getStatus, download, getQueueStatus, cancel } from './api_adapter.mjs';
+import { PersoApiError } from './http_client.mjs';
+import {
+  BACKOFF_BASE_MS, BACKOFF_MAX_MS, POLL_INTERVAL_MS,
+  MAX_IDLE_MS, MAX_RETRY, QUEUE_WAIT_MS,
+} from './config.mjs';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Credit/usage shortage is judged uniformly by HTTP 402 (does not depend on internal code names)
+const isCreditError = (e) => e instanceof PersoApiError && e.httpStatus === 402;
+// Translation queue full (backpressure): observed as 429 VT4292 (FULL_VT_TRANSLATE_QUEUE). VT5034 (503) also preserved.
+const QUEUE_FULL_CODES = new Set(['VT4292', 'VT5034']);
+
+// chunks: pieces from multiple inputs in one array (each piece identifies its input by inputId, index is 0-based within the input).
+//   An unsplit input has a single piece. The same (inputId,index) shares mediaSeq across languages (uploaded once).
+export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
+  const log = hooks.log ?? (() => {});
+  const onResult = hooks.onResult ?? (() => {}); // fired per confirmed result — lets the caller persist resume state incrementally
+  const outDir = await makeTempDir('dubbing-out-');
+
+  // Unit of work = (input × chunk × language). Expand every chunk of every input per language to fill one queue.
+  const targets = opts.targets ?? [opts.target ?? 'en'];
+  const skip = opts.done instanceof Set ? opts.done : new Set(); // resume: already-completed (inputId|index|target) are not submitted
+  const taskKey = (t) => `${t.inputId ?? 0}|${t.index}|${t.target}`;
+  const mediaKey = (t) => `${t.inputId ?? 0}|${t.index}`;
+
+  const pending = [];
+  for (const c of chunks) for (const target of targets) {
+    const t = { ...c, inputId: c.inputId ?? 0, path: c.path ?? c.localPath, target, retries: 0 };
+    if (!skip.has(taskKey(t))) pending.push(t);
+  }
+  const submitted = new Map(); // projectId → task (input × chunk × language)
+  const results = new Map(); // taskKey → result
+  const mediaByKey = new Map(); // `${inputId}|${index}` → {seq, kind}: uploaded once per chunk, shared across languages
+  let stopAll = false;
+  let stopReason = null;
+  let engineError = null; // unrecoverable engine error message (for reporting upward)
+  let backoff = BACKOFF_BASE_MS;
+  let lastProgressAt = Date.now(); // time of last progress. Guards on 'no progress' rather than absolute elapsed time.
+
+  const timeUp = () => Date.now() - lastProgressAt >= MAX_IDLE_MS;
+  const setResult = (t, r) => {
+    const rec = { inputId: t.inputId ?? 0, index: t.index, target: t.target, ...r };
+    results.set(taskKey(t), rec);
+    try { onResult(rec); } catch { /* state saving must never break scheduling */ }
+  };
+
+  // On stop_all, stop new submissions and only finalize in-flight (submitted) ones → exit when empty (pending is preserved).
+  while ((submitted.size || (!stopAll && pending.length)) && !timeUp()) {
+    let progressed = false;
+    let blocked = false; // no free slots (external/prior jobs occupy the queue), so new submissions are impossible
+
+    // ── Submit ── query the queue state and push only as many as there are 'free slots'; if slots free up, add them next round.
+    //            (on query failure slots=Infinity = push until VT4292 as before = fallback)
+    if (!stopAll && pending.length) {
+      const q = await getQueueStatus(spaceSeq);
+      let slots = q ? q.available : Infinity;
+      if (q) log(`Queue ${q.used}/${q.max} — ${q.available} free slots`);
+      const keep = [];
+      let rejected = false;
+      for (const chunk of pending) {
+        if (stopAll || rejected || slots <= 0) {
+          keep.push(chunk);
+          if (slots <= 0 || rejected) blocked = true; // held due to capacity occupancy (distinct from transient-error retry)
+          continue;
+        }
+        try {
+          if (chunk.mediaSeq === undefined) {
+            let m = mediaByKey.get(mediaKey(chunk));
+            if (!m) { m = await upload(toPrepared(chunk), spaceSeq); mediaByKey.set(mediaKey(chunk), m); } // once per chunk (shared across languages)
+            chunk.mediaSeq = m.seq;
+            chunk.kind = chunk.kind ?? m.kind;
+          }
+          const [pid] = await requestTranslation(spaceSeq, chunk.mediaSeq, { ...opts, target: chunk.target, title: chunk.title ?? opts.title, kind: chunk.kind });
+          if (pid == null) throw new Error('no projectId');
+          submitted.set(pid, chunk);
+          progressed = true;
+          slots -= 1;
+          log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1}(${chunk.target}) submitted`);
+        } catch (e) {
+          const code = e instanceof PersoApiError ? e.code : null;
+          if (isCreditError(e)) {
+            stopAll = true; stopReason = 'credit'; keep.push(chunk);
+            log('Usage (credit) shortage — halting new submissions, finishing only in-flight work');
+          } else if (QUEUE_FULL_CODES.has(code)) {
+            rejected = true; blocked = true; keep.push(chunk); // leave in-flight untouched, stop only this round's new submissions
+            log('Queue full — waiting for a free slot, then retrying');
+          } else if (code === 'F4008') {
+            // local inputs are usually pre-split by resolveChunks → reaching here means an unsplittable case such as external
+            setResult(chunk, { status: 'HARD_FAIL', reason: 'too_long' });
+            log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1} cannot be processed (length)`);
+          } else if (chunk.retries < MAX_RETRY) {
+            chunk.retries++; keep.push(chunk);
+            log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1} retrying`);
+          } else {
+            setResult(chunk, { status: 'HARD_FAIL', reason: 'submit_failed' });
+            log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1} processing failed`);
+          }
+        }
+      }
+      pending.length = 0;
+      pending.push(...keep);
+    }
+
+    // ── Polling ──
+    if (submitted.size) {
+      await sleep(POLL_INTERVAL_MS);
+      for (const [pid, chunk] of [...submitted]) {
+        if (!submitted.has(pid)) continue; // already handled this round (e.g. via sibling cancel) → prevent double processing
+        let st = null;
+        try { st = await getStatus(pid, spaceSeq); } catch { /* transient error → next round */ }
+        if (!st || st.state === 'processing') {
+          // if the server is raising the progress %, treat it as 'progress' and reset the no-progress timer (don't kill slow long videos).
+          if (st && typeof st.progress === 'number' && st.progress > (chunk._progress ?? -1)) {
+            chunk._progress = st.progress;
+            progressed = true;
+          }
+          continue;
+        }
+
+        submitted.delete(pid);
+        progressed = true;
+        const tag = `[Input ${chunk.inputId + 1}] segment ${chunk.index + 1}(${chunk.target})`;
+        if (st.state === 'complete') {
+          const out = join(outDir, `dub_${chunk.inputId}_${String(chunk.index).padStart(3, '0')}_${chunk.target}.mp4`);
+          try {
+            const dl = await download(pid, spaceSeq, { kind: chunk.kind, outPath: out });
+            setResult(chunk, { status: 'OK', projectId: pid, path: out, name: dl.fileName });
+            log(`${tag} done`);
+          } catch {
+            // generation succeeded (has projectSeq) — only download failed. Don't re-dub; mark it as DLFAIL to
+            // preserve projectSeq → re-download on resume (no regeneration).
+            setResult(chunk, { status: 'DLFAIL', projectId: pid, reason: 'download_failed' });
+            log(`${tag} generated (download failed → re-download on resume)`);
+          }
+        } else if (st.noVoice) {
+          // no voice detected. For a split chunk (has endMs), pass the original through → keep silent segments of a long video and dub·merge the rest.
+          // For a single (unsplit whole·external) request, fail it so a result byte-identical to the original is not emitted as 'complete'.
+          if (chunk.endMs != null) {
+            setResult(chunk, { status: 'PASSTHROUGH', projectId: pid, path: chunk.path, reason: 'no_voice' });
+            log(`${tag} passthrough (no voice)`);
+          } else {
+            setResult(chunk, { status: 'HARD_FAIL', projectId: pid, reason: 'no_voice' });
+            log(`${tag} no voice detected — nothing to dub`);
+          }
+        } else if (st.failureReason === 'ENGINE_ERROR') {
+          // engine error (unrecoverable) → fail without retry. The same chunk (same mediaSeq) is identical in any language → cancel siblings.
+          engineError = st.message ?? engineError ?? 'engine processing error';
+          setResult(chunk, { status: 'HARD_FAIL', projectId: pid, reason: st.message ?? 'engine_error' });
+          log(`${tag} cannot be processed (engine error): ${st.message ?? ''}`);
+          await cancelSiblings(chunk.inputId, chunk.index, pid);
+        } else if (chunk.retries < MAX_RETRY) {
+          chunk.retries++; pending.push(chunk); // reuse the upload (mediaSeq) to re-translate
+          log(`${tag} retrying`);
+        } else {
+          setResult(chunk, { status: 'HARD_FAIL', projectId: pid, reason: st.message ?? 'failed' });
+          log(`${tag} processing failed`);
+        }
+      }
+    } else if (pending.length && !stopAll) {
+      if (blocked) {
+        // no free slots (external/prior jobs occupy the queue) + no in-flight of ours either: pure waiting.
+        // reset the no-progress timer (don't time out while waiting on external jobs) and re-check after 5 minutes.
+        lastProgressAt = Date.now();
+        log('No free slot in the queue, waiting — re-checking in 5 minutes');
+        await sleep(QUEUE_WAIT_MS);
+      } else {
+        // nothing in-flight but unable to submit (transient error · persistent VT5034) → retry after exponential backoff
+        await sleep(backoff);
+        backoff = Math.min(backoff * 2, BACKOFF_MAX_MS);
+      }
+    }
+
+    if (progressed) { backoff = BACKOFF_BASE_MS; lastProgressAt = Date.now(); } // on progress, reset backoff/no-progress timer
+  }
+
+  if (timeUp()) failRemaining('elapsed_exceeded');
+
+  return {
+    results,
+    outDir,
+    stopped: stopAll,
+    stopReason,
+    engineError,
+    pendingLeft: pending.map(({ retries, mediaSeq, _progress, ...c }) => c), // preserved on stop_all (for resume). mediaSeq removed → re-upload.
+  };
+
+  function failRemaining(reason) {
+    for (const c of pending) if (!results.has(taskKey(c))) setResult(c, { status: 'HARD_FAIL', reason });
+    // In-flight projects may still finish server-side (credits already spent) → keep the projectSeq as DLFAIL
+    // so resume re-downloads the result instead of re-dubbing (no double billing). A confirmed server-side
+    // failure is converted back to a re-dub by the resume flow.
+    for (const [pid, c] of submitted) if (!results.has(taskKey(c))) setResult(c, { status: 'DLFAIL', projectId: pid, reason });
+    submitted.clear();
+    pending.length = 0;
+  }
+
+  // a chunk with an engine error yields the same result in any language → cancel in-flight siblings (same input·chunk, other languages) + drop pending ones.
+  async function cancelSiblings(inputId, index, exceptPid) {
+    for (const [pid2, t] of [...submitted]) {
+      if (t.inputId === inputId && t.index === index && pid2 !== exceptPid) {
+        await cancel(pid2, spaceSeq);
+        submitted.delete(pid2);
+        setResult(t, { status: 'HARD_FAIL', projectId: pid2, reason: 'engine_error' });
+        log(`[Input ${t.inputId + 1}] segment ${t.index + 1}(${t.target}) canceled (same chunk engine error)`);
+      }
+    }
+    for (let i = pending.length - 1; i >= 0; i--) {
+      if (pending[i].inputId === inputId && pending[i].index === index) {
+        setResult(pending[i], { status: 'HARD_FAIL', reason: 'engine_error' });
+        pending.splice(i, 1);
+      }
+    }
+  }
+}
+
+function toPrepared(chunk) {
+  if (chunk.source === 'external') return { source: 'external', sourceUrl: chunk.sourceUrl };
+  return { source: 'local', localPath: chunk.path, originalName: chunk.originalName ?? basename(chunk.path) };
+}

package/skills/dubbing/lib/space.mjs

@@ -0,0 +1,51 @@
+// spaceSeq resolution. Commonly needed by validate, translate, and quota.
+import { get } from './http_client.mjs';
+
+let _cache = null;
+
+export async function listSpaces() {
+  if (_cache) return _cache;
+  const res = await get('/portal/api/v1/spaces');
+  _cache = res?.result ?? [];
+  return _cache;
+}
+
+/** Spaces where dubbing can run (video_translator; falls back to all), with display names for the user to choose from. */
+export async function dubbingSpaces() {
+  const spaces = await listSpaces();
+  if (!spaces.length) throw new Error('No accessible space.');
+  const vt = spaces.filter((s) => s.serviceType === 'video_translator');
+  return (vt.length ? vt : spaces).map((s) => ({
+    seq: s.spaceSeq,
+    name: s.spaceName ?? s.name ?? `space ${s.spaceSeq}`,
+    tier: s.tier ?? null,
+  }));
+}
+
+/** Non-interactive spaceSeq resolution: env pin → the only space. With several spaces the user must choose
+ *  (dubbing.mjs asks by name); here we can only fail with guidance. */
+export async function resolveSpace() {
+  const pinned = Number(process.env.PERSO_SPACE_SEQ);
+  if (pinned) return pinned;
+  const spaces = await dubbingSpaces();
+  if (spaces.length === 1) return spaces[0].seq;
+  throw new Error(
+    'Several spaces are available — set PERSO_SPACE_SEQ or pass --space <seq>:\n' +
+    spaces.map((s) => `  ${s.seq}: ${s.name}`).join('\n'),
+  );
+}
+
+/** Query plan/quota → { planTier, remainingQuota, resetDateTime }. Returns null on failure. */
+export async function getPlanStatus(spaceSeq) {
+  try {
+    const res = await get(`/video-translator/api/v1/projects/spaces/${spaceSeq}/plan/status`);
+    const r = res?.result ?? res ?? {};
+    return {
+      planTier: r.planTier ?? null,
+      remainingQuota: r.remainingQuota?.remainingQuota ?? r.remainingQuota ?? null,
+      resetDateTime: r.resetDateTime ?? null,
+    };
+  } catch {
+    return null;
+  }
+}

package/skills/dubbing/lib/split.mjs

@@ -0,0 +1,178 @@
+// Upload-first + length/size cap: try uploading the whole file first.
+//   - success           → single chunk (already uploaded). ffmpeg/ffprobe not used.
+//   - F4008 (length)     → lossless segment split by maxLengthMs
+//   - F4004 (size>2GB)   → lossless segment split to a length that fits ~2GB (-c copy → keep original bitrate)
+//   Splitting uses the segment muxer (-c copy + -reset_timestamps 1, SEG=cap−GOP−margin). Re-encode fallback only when lossless is impossible.
+//   Each split piece is uploaded again → if still over the limit, split recursively. Leaf pieces hold a mediaSeq.
+import { stat } from 'node:fs/promises';
+import { extname, join, basename } from 'node:path';
+import { PersoApiError } from './http_client.mjs';
+import { upload } from './api_adapter.mjs';
+import { probe, cut, cutCopy, tempDir, probeGop, probeHasVideo, segmentCopy, segmentReencode } from './ffmpeg.mjs';
+import { ensureFfmpeg } from '../scripts/check_deps.mjs';
+
+// Safe margin below the upload size limit (API 2GB). Overridable via env.
+const SIZE_CAP = Number(process.env.PERSO_SIZE_CAP_BYTES) || Math.floor(1.9 * 1024 ** 3);
+const MAX_DEPTH = 4;
+const SEG_MARGIN_MS = 2000; // SEG = cap − GOP − margin: a safety buffer to stay below the cap
+const MIN_SEG_MS = 3000;    // if SEG is smaller than this (GOP too large relative to the cap), lossless is impossible → re-encode fallback
+
+/** @returns {{chunks:Array<{index,source,path?,sourceUrl?,mediaSeq?,startMs?,endMs?}>, notice:string|null}} */
+export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
+  const log = hooks.log ?? (() => {});
+  const notify = hooks.notify ?? (() => {}); // user-facing milestones (split start, etc.)
+  if (prepared.source === 'external') {
+    return { chunks: [{ index: 0, source: 'external', sourceUrl: prepared.sourceUrl }], notice: null };
+  }
+
+  const localPath = prepared.localPath ?? prepared.path;
+  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify);
+  // carry each leaf's absolute boundaries (startMs/endMs) on the chunk → on resume, re-cut only that segment from the original.
+  // when split, number the title _01,_02… → in the Perso project list, distinguish pieces of the same original (a single piece keeps the original name).
+  const baseTitle = (prepared.originalName ?? basename(localPath)).replace(/\.[^.]+$/, '');
+  const chunks = leaves.map((l, i) => ({
+    index: i, source: 'local', path: l.path, mediaSeq: l.mediaSeq, kind: l.kind, startMs: l.startMs, endMs: l.endMs,
+    title: leaves.length > 1 ? `${baseTitle}_${String(i + 1).padStart(2, '0')}` : baseTitle,
+  }));
+  const notice = chunks.length > 1 ? `Auto-split: ${chunks.length} parts (length/size limit)` : null;
+  return { chunks, notice };
+}
+
+/**
+ * Try to upload → on F4008/F4004, split and recurse into each piece. A successful leaf is {path, mediaSeq, startMs, endMs}.
+ * startMs/spanMs are absolute positions relative to the original (an unsplit whole leaf has endMs=null).
+ * Side optimization: a size overflow can be known in advance via local stat, so split a huge file directly instead of uploading it whole.
+ */
+async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}) {
+  if (depth < MAX_DEPTH) {
+    const { size } = await stat(localPath);
+    if (size > SIZE_CAP) { // size overflow → split before uploading
+      log('The file is large, so the video is processed in parts. Cutting and merging takes a little while.');
+      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify);
+    }
+  }
+  try {
+    if (depth === 0) log('Uploading video... (large videos take a while)');
+    const { seq: mediaSeq, kind } = await upload({ source: 'local', localPath, originalName: basename(localPath) }, spaceSeq);
+    return [{ path: localPath, mediaSeq, kind, startMs, endMs: spanMs == null ? null : startMs + spanMs }];
+  } catch (e) {
+    const code = e instanceof PersoApiError ? e.code : null;
+    if (code !== 'F4008' && code !== 'F4004') throw e; // errors other than length/size are rethrown as-is
+    if (depth >= MAX_DEPTH) throw new Error(`Split limit exceeded (depth ${depth}) — cannot upload`);
+    log('The video exceeds the length/size limit, so it is processed in parts. Cutting and merging takes a little while.');
+    const lengthCapMs = code === 'F4008' ? Number(e.data?.maxLengthMs) : Infinity;
+    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify);
+  }
+}
+
+/** Split localPath by the length/size limit and recursively upload each piece. baseStartMs is the absolute offset relative to the original. */
+async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}) {
+  ensureFfmpeg(); // install only when cutting is confirmed
+  if (depth === 0) notify('Splitting — the video exceeds the length/size limit, so it is processed in parts.'); // user-facing
+  const { durationMs, sizeBytes } = await probe(localPath);
+  if (!durationMs) throw new Error('Could not measure the video length.');
+
+  const capMs = computeChunkMs(durationMs, sizeBytes, lengthCapMs); // the smaller of the length/size caps
+  const parts = await splitByMaxLen(localPath, durationMs, capMs, SIZE_CAP, log);
+
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    log(`Uploading piece ${i + 1}/${parts.length}...`);
+    const p = parts[i];
+    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify)));
+  }
+  return out;
+}
+
+/** For resume: re-cut the [startMs,endMs) segment from the original at the same boundaries as the split, into a temp file. */
+export async function recutChunk(localPath, startMs, endMs) {
+  ensureFfmpeg();
+  const dir = await tempDir();
+  const ext = extname(localPath) || '.mp4';
+  const out = join(dir, `recut_${startMs}_${endMs}${ext}`);
+  try {
+    await cutCopy(localPath, startMs, endMs, out); // lossless first (boundaries are the keyframes from the split)
+    const { durationMs } = await probe(out).catch(() => ({}));
+    if (durationMs && durationMs > 200) return out;
+  } catch { /* fallback ↓ */ }
+  await cut(localPath, startMs, endMs, out, SIZE_CAP); // re-encode fallback (frame-accurate)
+  return out;
+}
+
+/** Determine the piece length (ms) as the smaller of the length cap and size cap. Independent of resolution·fps (cuts by time only). */
+export function computeChunkMs(durationMs, sizeBytes, lengthCapMs = Infinity, sizeCap = SIZE_CAP) {
+  let chunkMs = durationMs;
+  if (Number.isFinite(lengthCapMs) && lengthCapMs > 0) chunkMs = Math.min(chunkMs, lengthCapMs);
+  if (sizeBytes && sizeBytes > sizeCap) {
+    const sizeMs = Math.floor((durationMs * sizeCap) / sizeBytes);
+    if (sizeMs > 0) chunkMs = Math.min(chunkMs, sizeMs);
+  }
+  if (chunkMs >= durationMs) chunkMs = Math.floor(durationMs / 2); // if it can't be narrowed, halve it (avoid infinite loop)
+  return Math.max(1, chunkMs);
+}
+
+/**
+ * Lossless segment split (-c copy) to fit the capMs limit. Set SEG = capMs − GOP − margin so that
+ * even when cut at keyframe boundaries, no piece exceeds the limit. Re-encode fallback only when lossless is impossible/exceeded.
+ * @returns {Array<{index,path,startMs,durationMs}>}
+ */
+export async function splitByMaxLen(path, durationMs, capMs, maxBytes, log = () => {}) {
+  const ext = extname(path) || '.mp4';
+  const audioOnly = !(await probeHasVideo(path)); // an audio file has no video stream
+  let paths = null;
+
+  if (audioOnly) {
+    // audio: keyframe/GOP-independent (can cut anywhere per frame) → SEG = cap − margin. -c copy lossless (container-matched codec fallback).
+    const segMs = Math.max(MIN_SEG_MS, capMs - SEG_MARGIN_MS);
+    log(`Lossless split in progress... (audio, piece ≈${Math.round(segMs / 1000)}s)`);
+    try {
+      paths = await segmentCopy(path, segMs, ext, { audioOnly: true });
+      if (await anyOverCap(paths, capMs)) paths = null;
+    } catch {
+      paths = null;
+    }
+    if (!paths || !paths.length) {
+      log('Audio re-encode split (fallback)');
+      paths = await segmentReencode(path, segMs, ext, maxBytes, { audioOnly: true });
+    }
+  } else {
+    // video: cut only at keyframe boundaries → SEG = cap − GOP − margin.
+    const gopMs = await probeGop(path);
+    const margin = Math.max(SEG_MARGIN_MS, gopMs); // margin against GOP under-measurement
+    const segMs = capMs - gopMs - margin;
+    if (segMs >= MIN_SEG_MS) {
+      log(`Lossless split in progress... (GOP ≈${Math.round(gopMs)}ms, piece ≈${Math.round(segMs / 1000)}s)`);
+      try {
+        paths = await segmentCopy(path, segMs, ext);
+        if (await anyOverCap(paths, capMs)) { log('Some pieces exceed the limit → retrying with re-encode split'); paths = null; }
+      } catch {
+        paths = null; // -c copy failed (container/codec) → fallback
+      }
+    }
+    if (!paths || !paths.length) {
+      const reSeg = Math.max(MIN_SEG_MS, capMs - margin); // re-encode forces a keyframe at the boundary → GOP-independent
+      log(`Re-encode split (fallback) in progress... (piece ≈${Math.round(reSeg / 1000)}s)`);
+      paths = await segmentReencode(path, reSeg, ext, maxBytes);
+    }
+  }
+
+  // measure each piece's actual length → startMs (cumulative) relative to the original + durationMs (used as resume re-cut boundaries)
+  const chunks = [];
+  let acc = 0;
+  for (let i = 0; i < paths.length; i++) {
+    const { durationMs: d } = await probe(paths[i]).catch(() => ({}));
+    const dur = d ?? Math.max(1, Math.min(capMs, durationMs - acc));
+    chunks.push({ index: i, path: paths[i], startMs: acc, durationMs: dur });
+    acc += dur;
+  }
+  return chunks;
+}
+
+/** True if any piece exceeds capMs (detects the rare case where a lossless keyframe cut overshot the limit). */
+async function anyOverCap(paths, capMs) {
+  for (const p of paths) {
+    const { durationMs } = await probe(p).catch(() => ({}));
+    if (durationMs && durationMs > capMs) return true;
+  }
+  return false;
+}

package/skills/dubbing/lib/tmp.mjs

@@ -0,0 +1,21 @@
+// Temp working-folder tracking — bulk-deletes temp artifacts created by splitting/scheduling/merging/downloading on exit.
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const _dirs = new Set();
+
+/** Creates a tracked temp folder. It is bulk-deleted by cleanupTempDirs(). */
+export async function makeTempDir(prefix = 'dubbing-') {
+  const dir = await mkdtemp(join(tmpdir(), prefix));
+  _dirs.add(dir);
+  return dir;
+}
+
+/** Deletes all temp folders created so far (failures are ignored). */
+export async function cleanupTempDirs() {
+  for (const dir of _dirs) {
+    try { await rm(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+  }
+  _dirs.clear();
+}

package/skills/dubbing/scripts/check_deps.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Check ffmpeg/ffprobe. If missing, attempt auto-install without prompting (the OS asks for approval if elevation is needed).
+import { spawnSync } from 'node:child_process';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+function has(bin) {
+  const probe = process.platform === 'win32' ? 'where' : 'which';
+  return spawnSync(probe, [bin], { stdio: 'ignore' }).status === 0;
+}
+
+function installCmd() {
+  if (process.platform === 'win32') {
+    if (has('winget')) return ['winget', ['install', '-e', '--id', 'Gyan.FFmpeg', '--accept-source-agreements', '--accept-package-agreements']];
+    if (has('choco')) return ['choco', ['install', 'ffmpeg', '-y']];
+    if (has('scoop')) return ['scoop', ['install', 'ffmpeg']];
+  } else if (process.platform === 'darwin') {
+    if (has('brew')) return ['brew', ['install', 'ffmpeg']];
+  } else {
+    if (has('apt-get')) return ['sudo', ['apt-get', 'install', '-y', 'ffmpeg']];
+    if (has('dnf')) return ['sudo', ['dnf', 'install', '-y', 'ffmpeg']];
+    if (has('pacman')) return ['sudo', ['pacman', '-S', '--noconfirm', 'ffmpeg']];
+  }
+  return null;
+}
+
+/** Returns true if both ffmpeg and ffprobe are present. Otherwise auto-installs and re-checks. Throws if not possible. */
+export function ensureFfmpeg() {
+  if (has('ffmpeg') && has('ffprobe')) return true;
+
+  const cmd = installCmd();
+  if (!cmd) {
+    throw new Error('ffmpeg/ffprobe not found and no auto-installable package manager available — https://ffmpeg.org/download.html');
+  }
+  const [bin, args] = cmd;
+  const r = spawnSync(bin, args, { stdio: 'inherit' }); // the OS prompts if elevation is needed
+  if (r.status !== 0) throw new Error('ffmpeg auto-install failed');
+
+  if (!(has('ffmpeg') && has('ffprobe'))) {
+    throw new Error('ffmpeg/ffprobe still not found after install. Check your PATH.');
+  }
+  return true;
+}
+
+const isMain = process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+if (isMain) {
+  try {
+    ensureFfmpeg();
+    console.log('ffmpeg/ffprobe OK');
+  } catch (e) {
+    console.error(e.message);
+    process.exit(1);
+  }
+}