perso-dubbing 0.2.0 → 0.4.0

package/skills/dubbing/lib/ffmpeg.mjs

@@ -3,7 +3,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { platform } from 'node:os';
 import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, extname } from 'node:path';
 import { makeTempDir } from './tmp.mjs';
 
 const exec = promisify(execFile);
@@ -114,6 +114,46 @@ export function encoderVideoArgs(enc) {
   }
 }
 
+// ── passthrough normalization (mixed-group concat safety) ─────
+/** Codec parameters of the first video/audio stream — the reference for normalizing passthrough pieces. */
+export async function probeStreams(path) {
+  const { stdout } = await exec('ffprobe', ['-v', 'error',
+    '-show_entries', 'stream=codec_type,width,height,pix_fmt,avg_frame_rate,sample_rate,channels',
+    '-of', 'json', path], { maxBuffer: 1 << 20 });
+  const streams = JSON.parse(stdout)?.streams ?? [];
+  const v = streams.find((s) => s.codec_type === 'video');
+  const a = streams.find((s) => s.codec_type === 'audio');
+  // keep fps as the exact ffprobe fraction (e.g. 30000/1001) — a float would drift on NTSC rates
+  const fps = /^[1-9]\d*\/[1-9]\d*$/.test(v?.avg_frame_rate ?? '') ? v.avg_frame_rate : null;
+  return {
+    video: v ? { width: v.width, height: v.height, pixFmt: v.pix_fmt ?? null, fps } : null,
+    audio: a ? { sampleRate: Number(a.sample_rate) || null, channels: a.channels ?? null } : null,
+  };
+}
+
+/** Re-encode one piece to the reference parameters (H.264/AAC for video, container codec for audio-only)
+ * so a following concat -c copy is stream-compatible. Used on passthrough pieces only — dubbed output is never touched. */
+export async function normalizeTo(path, ref, outPath) {
+  const args = ['-y', '-i', path];
+  if (ref.video) {
+    const vf = [];
+    if (ref.video.width && ref.video.height) vf.push(`scale=${ref.video.width}:${ref.video.height}`);
+    if (ref.video.fps) vf.push(`fps=${ref.video.fps}`);
+    if (vf.length) args.push('-vf', vf.join(','));
+    args.push(...encoderVideoArgs(await pickVideoEncoder()));
+    if (ref.video.pixFmt) args.push('-pix_fmt', ref.video.pixFmt);
+    args.push('-c:a', 'aac', '-b:a', '128k');
+  } else {
+    args.push('-map', '0:a', ...audioCodecArgs(extname(outPath)));
+  }
+  if (ref.audio?.sampleRate) args.push('-ar', String(ref.audio.sampleRate));
+  if (ref.audio?.channels) args.push('-ac', String(ref.audio.channels));
+  if (ref.video) args.push('-movflags', '+faststart');
+  args.push(outPath);
+  await exec('ffmpeg', args, { maxBuffer: 1 << 20 });
+  return outPath;
+}
+
 // ── segment splitting ───────────────────────────────────
 async function listParts(dir, ext) {
   const names = (await readdir(dir)).filter((n) => /^part_\d+/.test(n) && n.endsWith(ext)).sort();

package/skills/dubbing/lib/merge.mjs

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { ensureFfmpeg } from '../scripts/check_deps.mjs';
 import { makeTempDir } from './tmp.mjs';
-import { pickVideoEncoder, encoderVideoArgs } from './ffmpeg.mjs';
+import { pickVideoEncoder, encoderVideoArgs, probeStreams, normalizeTo } from './ffmpeg.mjs';
 
 const exec = promisify(execFile);
 
@@ -52,7 +52,7 @@ export async function mergeGroups(results, { outDir } = {}) {
     const ext = (persoName && extname(persoName)) || '.mp4'; // result container (e.g. .wav for audio dubbing)
     const name = groups.length === 1 ? `output${ext}` : `output_${g + 1}${ext}`;
     const out = join(dir, name);
-    await concat(group.map((i) => i.path), out);
+    await concat(await normalizeMixed(group, ext), out);
     outputs.push({ path: out, indices: group.map((i) => i.index), name: persoName });
   }
 
@@ -63,6 +63,27 @@ export async function mergeGroups(results, { outDir } = {}) {
   return { outputs, failures, report };
 }
 
+// A group can mix Perso-encoded (OK) pieces with local original (PASSTHROUGH) pieces whose codec
+// parameters rarely match — and concat -c copy does not validate stream parameters, so it can "succeed"
+// into a file that plays back broken (boundary glitches, A/V desync). Re-encode ONLY the passthrough
+// pieces to a dubbed piece's parameters; the paid dubbed output is concatenated untouched. Any failure
+// here falls back to the original piece — concat's own re-encode fallback still guards the result.
+async function normalizeMixed(group, ext) {
+  const dubbed = group.find((i) => i.status === 'OK' && i.path);
+  const pass = group.filter((i) => i.status === 'PASSTHROUGH' && i.path);
+  if (!dubbed || !pass.length) return group.map((i) => i.path);
+  ensureFfmpeg(); // mixed groups only exist for split videos, so ffmpeg was already installed for the split
+  const ref = await probeStreams(dubbed.path).catch(() => null);
+  if (!ref) return group.map((i) => i.path);
+  const dir = await makeTempDir('dubbing-norm-');
+  const normalized = new Map();
+  for (const p of pass) {
+    try { normalized.set(p, await normalizeTo(p.path, ref, join(dir, `norm_${p.index}${ext}`))); }
+    catch { /* keep the original piece */ }
+  }
+  return group.map((i) => normalized.get(i) ?? i.path);
+}
+
 async function concat(paths, outPath) {
   if (paths.length === 1) {
     // single piece (no cutting) → copy as-is without ffmpeg

package/skills/dubbing/lib/messages.mjs

@@ -9,30 +9,25 @@ export const PRICING_URL = 'https://perso.ai/en/workspace/vt?pricing';
 export const UTM_SOURCE = CLIENT_HOST;
 export const UTM_PARAMS =
   `utm_source=${UTM_SOURCE}&utm_medium=agent-skill&utm_campaign=perso-dubbing&utm_content=v${CLIENT_VERSION}`;
-const withUtm = (url) => url + (url.includes('?') ? '&' : '?') + UTM_PARAMS;
-
-// free/starter have no credit purchase, so only a plan upgrade is suggested.
-const LOW_TIERS = new Set(['free', 'starter']);
+export const withUtm = (url) => url + (url.includes('?') ? '&' : '?') + UTM_PARAMS;
 
 export const messages = {
-  // Out-of-usage guidance. Depending on planTier: free/starter get upgrade-only, others get both upgrade and credits.
-  //   { planTier, remainingQuota, remainingNote, resumeHint }
-  quotaExceeded: ({ planTier, remainingQuota, remainingNote, resumeHint } = {}) => {
-    const isLow = LOW_TIERS.has(String(planTier ?? '').toLowerCase());
+  // Out-of-usage guidance. The agent can generate a direct Stripe link via scripts/billing.mjs, which
+  // routes by the current plan tier (free → subscribe · starter/creator → change plan · pro/business → credits).
+  //   { planTier, remainingQuota, remainingNote, resumeHint, note }
+  quotaExceeded: ({ planTier, remainingQuota, remainingNote, resumeHint, note } = {}) => {
     const status =
       `   Current plan: ${planTier ?? 'unknown'} · Credits left: ${remainingQuota ?? '?'}` +
       (remainingNote ? ` · Remaining: ${remainingNote}` : '');
-    const lines = [
+    return [
       'Out of usage/credits — only part of the work completed. The finished items are delivered above.',
       status,
+      ...(note ? [note] : []),
       '',
-    ];
-    if (isLow) {
-      lines.push('To continue, upgrade your plan:', `  → ${withUtm(PRICING_URL)}`);
-    } else {
-      lines.push('To continue, upgrade your plan or buy more credits (Get credits), then run again:', `  → ${withUtm(SUBSCRIPTION_URL)}`);
-    }
-    if (resumeHint) lines.push(`  Resume: ${resumeHint}`);
-    return lines.join('\n');
+      'To continue you can generate a payment link (routes by plan: subscribe / change plan / buy credits):',
+      '  → node scripts/billing.mjs options   (add --shortfall <estimated remaining credits> for a recommendation)',
+      '  Then give the returned Stripe link to the user to complete payment in their browser — never pay on their behalf.',
+      ...(resumeHint ? [`  Resume after topping up: ${resumeHint}`] : []),
+    ].join('\n');
   },
 };

package/skills/dubbing/lib/scheduler.mjs

@@ -4,13 +4,17 @@
 //   - 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)
+// With opts.lipsync, a completed dubbing task is re-queued as a stage:'lipsync' task (parentSeq = dubbing
+// projectSeq) in the same pool: lip-sync jobs share the queue slots, are polled less often, and are never
+// re-submitted on failure (a repeat request bills again) — a failed lip-sync falls back to the dubbed video.
 import { basename, join } from 'node:path';
 import { makeTempDir } from './tmp.mjs';
-import { upload, requestTranslation, getStatus, download, getQueueStatus, cancel } from './api_adapter.mjs';
+import { upload, requestTranslation, requestLipSync, 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,
+  LIPSYNC_POLL_INTERVAL_MS, LIPSYNC_IDLE_PER_DURATION, LIPSYNC_IDLE_MS,
 } from './config.mjs';
 
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
@@ -23,7 +27,9 @@ const QUEUE_FULL_CODES = new Set(['VT4292', 'VT5034']);
 //   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 notify = hooks.notify ?? (() => {});
   const onResult = hooks.onResult ?? (() => {}); // fired per confirmed result — lets the caller persist resume state incrementally
+  const onSubmit = hooks.onSubmit ?? (() => {}); // fired right after a submission — persists the projectSeq before any result exists
   const outDir = await makeTempDir('dubbing-out-');
 
   // Unit of work = (input × chunk × language). Expand every chunk of every input per language to fill one queue.
@@ -33,9 +39,15 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
   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);
+  for (const c of chunks) {
+    if (c.stage === 'lipsync') { // pre-targeted (resume/lipsync-only): explicitly requested by the caller, carries its own language
+      pending.push({ ...c, inputId: c.inputId ?? 0, retries: 0 });
+      continue;
+    }
+    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
@@ -45,13 +57,29 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
   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.
+  let lipsyncAnnounced = false;
 
-  const timeUp = () => Date.now() - lastProgressAt >= MAX_IDLE_MS;
+  const taskMs = (t) => (Number.isFinite(t?.startMs) && Number.isFinite(t?.endMs) ? t.endMs - t.startMs : null);
+  // No-progress allowance: while a lip-sync job is in flight, scale it to the (known) video duration.
+  const idleLimit = () => {
+    let limit = MAX_IDLE_MS;
+    for (const t of submitted.values()) {
+      if (t.stage !== 'lipsync') continue;
+      const ms = taskMs(t);
+      limit = Math.max(limit, ms ? ms * LIPSYNC_IDLE_PER_DURATION : LIPSYNC_IDLE_MS);
+    }
+    return limit;
+  };
+  const timeUp = () => Date.now() - lastProgressAt >= idleLimit();
   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 */ }
   };
+  const checkpoint = (t, pid) => {
+    try { onSubmit({ inputId: t.inputId ?? 0, index: t.index, target: t.target, stage: t.stage ?? 'dub', projectId: pid, parentSeq: t.parentSeq ?? null, lipsync: !!opts.lipsync }); }
+    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()) {
@@ -73,18 +101,29 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
           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;
+          let pid;
+          if (chunk.stage === 'lipsync') {
+            [pid] = await requestLipSync(chunk.parentSeq, spaceSeq, { speed: opts.speed });
+          } else {
+            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;
+            }
+            [pid] = await requestTranslation(spaceSeq, chunk.mediaSeq, { ...opts, target: chunk.target, title: chunk.title ?? opts.title, kind: chunk.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);
+          checkpoint(chunk, pid); // persisted before any result — a killed process must not lose a paid submission
           progressed = true;
           slots -= 1;
-          log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1}(${chunk.target}) submitted`);
+          if (chunk.stage === 'lipsync') {
+            if (!lipsyncAnnounced) { lipsyncAnnounced = true; notify('Lip-sync generation started — this takes considerably longer than dubbing; progress updates will follow.'); }
+            log(`[Input ${chunk.inputId + 1}] segment ${chunk.index + 1}(${chunk.target}) lip-sync submitted`);
+          } else {
+            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)) {
@@ -115,8 +154,10 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
       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
+        if (chunk.stage === 'lipsync' && Date.now() < (chunk._nextPollAt ?? 0)) continue; // long-running → poll on a relaxed cadence
         let st = null;
         try { st = await getStatus(pid, spaceSeq); } catch { /* transient error → next round */ }
+        if (chunk.stage === 'lipsync') chunk._nextPollAt = Date.now() + LIPSYNC_POLL_INTERVAL_MS;
         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)) {
@@ -129,7 +170,40 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
         submitted.delete(pid);
         progressed = true;
         const tag = `[Input ${chunk.inputId + 1}] segment ${chunk.index + 1}(${chunk.target})`;
+
+        if (chunk.stage === 'lipsync') {
+          // Lip-sync outcome. Never re-submit (a repeat request generates & bills again) — on failure fall back to the dubbed video.
+          if (st.state === 'complete') {
+            const out = join(outDir, `lip_${chunk.inputId}_${String(chunk.index).padStart(3, '0')}_${chunk.target}.mp4`);
+            try {
+              const dl = await download(pid, spaceSeq, { lipsync: true, outPath: out });
+              setResult(chunk, { status: 'OK', projectId: pid, dubProjectId: chunk.parentSeq, lipsync: true, path: out, name: dl.fileName });
+              log(`${tag} lip-sync done`);
+            } catch {
+              setResult(chunk, { status: 'DLFAIL', projectId: pid, dubProjectId: chunk.parentSeq, lipsync: true, reason: 'download_failed' });
+              log(`${tag} lip-sync generated (download failed → re-download on resume)`);
+            }
+          } else {
+            log(`${tag} lip-sync failed${st.message ? ` (${st.message})` : ''} — falling back to the dubbed video`);
+            const out = join(outDir, `dub_${chunk.inputId}_${String(chunk.index).padStart(3, '0')}_${chunk.target}.mp4`);
+            try {
+              const dl = await download(chunk.parentSeq, spaceSeq, { kind: chunk.kind, outPath: out });
+              setResult(chunk, { status: 'OK', projectId: chunk.parentSeq, lipsyncFailed: true, reason: st.message ?? 'lipsync_failed', path: out, name: dl.fileName });
+            } catch {
+              setResult(chunk, { status: 'DLFAIL', projectId: chunk.parentSeq, lipsyncFailed: true, reason: 'download_failed' });
+            }
+          }
+          continue;
+        }
+
         if (st.state === 'complete') {
+          // Chain: with opts.lipsync, a dubbed video is not the final deliverable — re-queue as a lip-sync task.
+          if (opts.lipsync && chunk.kind !== 'audio') {
+            pending.push({ ...chunk, stage: 'lipsync', parentSeq: pid, retries: 0, _progress: undefined });
+            log(`${tag} dubbed — queueing lip-sync`);
+            continue;
+          }
+          if (opts.lipsync && chunk.kind === 'audio') log(`${tag} is audio — lip-sync skipped, delivering the dubbed audio`);
           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 });
@@ -182,6 +256,24 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
     if (progressed) { backoff = BACKOFF_BASE_MS; lastProgressAt = Date.now(); } // on progress, reset backoff/no-progress timer
   }
 
+  // Credit stop with lip-sync still owed: the dubbing is already paid for — save the dubbed videos now
+  // and leave only the lip-sync step to resume (no re-dub charge).
+  if (stopAll && stopReason === 'credit') {
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const c = pending[i];
+      if (c.stage !== 'lipsync') continue;
+      pending.splice(i, 1);
+      const out = join(outDir, `dub_${c.inputId}_${String(c.index).padStart(3, '0')}_${c.target}.mp4`);
+      try {
+        const dl = await download(c.parentSeq, spaceSeq, { kind: c.kind, outPath: out });
+        setResult(c, { status: 'OK', projectId: c.parentSeq, lipsyncPending: true, path: out, name: dl.fileName });
+        log(`[Input ${c.inputId + 1}] segment ${c.index + 1}(${c.target}) dubbed video saved — lip-sync will run on resume`);
+      } catch {
+        setResult(c, { status: 'DLFAIL', projectId: c.parentSeq, lipsyncPending: true, reason: 'download_failed' });
+      }
+    }
+  }
+
   if (timeUp()) failRemaining('elapsed_exceeded');
 
   return {
@@ -190,22 +282,31 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
     stopped: stopAll,
     stopReason,
     engineError,
-    pendingLeft: pending.map(({ retries, mediaSeq, _progress, ...c }) => c), // preserved on stop_all (for resume). mediaSeq removed → re-upload.
+    pendingLeft: pending.map(({ retries, mediaSeq, _progress, _nextPollAt, ...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 });
+    for (const c of pending) if (!results.has(taskKey(c))) {
+      // A pending lip-sync task still has a completed dubbing behind it — keep that seq so resume only re-runs lip-sync.
+      if (c.stage === 'lipsync') setResult(c, { status: 'DLFAIL', projectId: c.parentSeq, lipsyncPending: true, reason });
+      else 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 });
+    for (const [pid, c] of submitted) if (!results.has(taskKey(c))) {
+      if (c.stage === 'lipsync') setResult(c, { status: 'DLFAIL', projectId: pid, dubProjectId: c.parentSeq, lipsync: true, reason });
+      else 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.
+  // Lip-sync siblings are left alone: their dubbing already succeeded, so the media itself is fine.
   async function cancelSiblings(inputId, index, exceptPid) {
     for (const [pid2, t] of [...submitted]) {
+      if (t.stage === 'lipsync') continue;
       if (t.inputId === inputId && t.index === index && pid2 !== exceptPid) {
         await cancel(pid2, spaceSeq);
         submitted.delete(pid2);
@@ -214,6 +315,7 @@ export async function runSchedule(chunks, spaceSeq, opts = {}, hooks = {}) {
       }
     }
     for (let i = pending.length - 1; i >= 0; i--) {
+      if (pending[i].stage === 'lipsync') continue;
       if (pending[i].inputId === inputId && pending[i].index === index) {
         setResult(pending[i], { status: 'HARD_FAIL', reason: 'engine_error' });
         pending.splice(i, 1);

package/skills/dubbing/lib/split.mjs

@@ -17,16 +17,23 @@ 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
 
+/** Thrown at depth 0 when a split is required but the user hasn't authorized it yet (no allowSplit).
+ *  Carries what the caller needs to build the confirmation prompt: { reason:'length'|'size', limitMs?, actualMs?, actualBytes? }. */
+export class SplitConfirmNeeded extends Error {
+  constructor(details) { super('split confirmation required'); this.name = 'SplitConfirmNeeded'; this.details = details; }
+}
+
 /** @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.)
+  const allowSplit = hooks.allowSplit ?? false; // false → stop and ask before the first split (SplitConfirmNeeded)
   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);
+  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify, allowSplit);
   // 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(/\.[^.]+$/, '');
@@ -43,12 +50,13 @@ export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
  * 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 = () => {}) {
+async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}, allowSplit = true) {
   if (depth < MAX_DEPTH) {
     const { size } = await stat(localPath);
-    if (size > SIZE_CAP) { // size overflow → split before uploading
+    if (size > SIZE_CAP) { // size overflow → split before uploading (known locally, so no upload is wasted)
+      if (depth === 0 && !allowSplit) throw new SplitConfirmNeeded({ reason: 'size', actualBytes: size });
       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);
+      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify, allowSplit);
     }
   }
   try {
@@ -59,14 +67,27 @@ async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = n
     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`);
+    if (depth === 0 && !allowSplit) throw await splitConfirmFor(code, e, localPath);
     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);
+    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify, allowSplit);
+  }
+}
+
+// Build the confirmation error for a length (F4008) or size (F4004) rejection, best-effort filling the actual value.
+async function splitConfirmFor(code, err, localPath) {
+  if (code === 'F4008') {
+    let actualMs = null;
+    try { ({ durationMs: actualMs } = await probe(localPath)); } catch { /* ffmpeg absent → omit the actual length */ }
+    return new SplitConfirmNeeded({ reason: 'length', limitMs: Number(err.data?.maxLengthMs) || null, actualMs });
   }
+  let actualBytes = null;
+  try { ({ size: actualBytes } = await stat(localPath)); } catch { /* omit the actual size */ }
+  return new SplitConfirmNeeded({ reason: 'size', actualBytes });
 }
 
 /** 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 = () => {}) {
+async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}, allowSplit = true) {
   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);
@@ -79,7 +100,7 @@ async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCa
   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)));
+    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify, allowSplit)));
   }
   return out;
 }

package/skills/dubbing/lib/update_check.mjs

@@ -0,0 +1,83 @@
+// Once-a-day (UTC) check against the npm registry for a newer release. Both npx and the plugin marketplace
+// install from npm, so the registry is the single source of truth. Non-blocking, fail-silent, throttled to
+// at most one network call per UTC day; never delays or fails a run. Opt out with PERSO_NO_UPDATE_CHECK.
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { CRED_DIR } from './config.mjs';
+import { CLIENT_VERSION } from './client_info.mjs';
+
+const PKG = 'perso-dubbing';
+const REGISTRY = `https://registry.npmjs.org/${PKG}/latest`;
+const CACHE_FILE = join(CRED_DIR, 'update-check.json');
+const TIMEOUT_MS = 3000;
+
+const utcDate = () => new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+
+function readCache() {
+  try { return JSON.parse(readFileSync(CACHE_FILE, 'utf8')); } catch { return {}; }
+}
+function writeCache(obj) {
+  try { mkdirSync(CRED_DIR, { recursive: true }); writeFileSync(CACHE_FILE, JSON.stringify(obj)); } catch { /* ignore */ }
+}
+
+// x.y.z compare: a>b → 1, a<b → -1, equal → 0. parseInt drops any pre-release/build suffix (e.g. "3-beta" → 3).
+function cmpSemver(a, b) {
+  const part = (s) => String(s).split('.').map((n) => parseInt(n, 10) || 0);
+  const pa = part(a), pb = part(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0, y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+async function fetchLatest() {
+  try {
+    const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!res.ok) return null;
+    const j = await res.json();
+    return typeof j?.version === 'string' ? j.version : null;
+  } catch { return null; }
+}
+
+// Best-effort install-method guess from the running file path (marketplace copies live under a plugins dir).
+function installMethod() {
+  try {
+    const p = fileURLToPath(import.meta.url).replace(/\\/g, '/').toLowerCase();
+    if (p.includes('/plugins/') || p.includes('/marketplace')) return 'marketplace';
+  } catch { /* fall through */ }
+  return 'npx';
+}
+
+function buildNotice(latest) {
+  const lines = [`ℹ️  Update available: ${PKG} ${latest} (you have ${CLIENT_VERSION}).`];
+  if (installMethod() === 'marketplace') {
+    lines.push('   In Claude Code (plugin):  /plugin update perso-dubbing');
+    lines.push('   Otherwise (npx / manual): npx perso-dubbing@latest');
+  } else {
+    lines.push('   Update:                   npx perso-dubbing@latest');
+    lines.push('   In Claude Code (plugin):  /plugin update perso-dubbing');
+  }
+  return lines.join('\n');
+}
+
+/** Returns a one-line update notice (string) if a newer version exists, else null. Never throws.
+ *  Fetches from npm at most once per UTC day (cached); reuses the last known result otherwise. */
+export async function checkForUpdate() {
+  if (process.env.PERSO_NO_UPDATE_CHECK) return null;
+  if (CLIENT_VERSION === '0.0.0') return null; // version unknown → can't compare reliably
+
+  const today = utcDate();
+  const cache = readCache();
+  let latest = cache.latest ?? null;
+  if (cache.date !== today) {
+    const fetched = await fetchLatest();
+    latest = fetched ?? cache.latest ?? null; // keep last known on failure
+    writeCache({ date: today, latest }); // mark checked today regardless → ≤1 fetch/day
+  }
+
+  if (!latest || cmpSemver(latest, CLIENT_VERSION) <= 0) return null;
+  return buildNotice(latest);
+}