perso-dubbing 0.2.0

package/skills/dubbing/lib/client_info.mjs

@@ -0,0 +1,24 @@
+// Builds client runtime info (version, execution environment).
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url)); // <skill-root>/lib
+const ROOT = dirname(HERE);
+
+// Every agent host reports as one unified channel — API logs and UTM segment by version only.
+export const CLIENT_HOST = 'agents';
+
+// The skill sits either at the package root (installed copy) or under <repo>/skills/dubbing — check both for package.json.
+function readVersion() {
+  for (const dir of [ROOT, join(ROOT, '..', '..')]) {
+    try {
+      const v = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).version;
+      if (v) return v;
+    } catch { /* try next */ }
+  }
+  return '0.0.0';
+}
+
+export const CLIENT_VERSION = readVersion();
+export const CLIENT_USER_AGENT = `perso-dubbing/${CLIENT_VERSION} (host=${CLIENT_HOST})`;

package/skills/dubbing/lib/config.mjs

@@ -0,0 +1,26 @@
+// Plugin's own constants. Plan info (MaxLen, C/Q, credits) is not kept here; it is discovered from API responses.
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+// API
+export const API_BASE = (process.env.PERSO_API_BASE || 'https://api.perso.ai').replace(/\/+$/, '');
+export const AUTH_HEADER = 'XP-API-KEY';
+
+// Polling / backoff
+export const POLL_INTERVAL_MS = 5_000; // status polling interval (>=5s recommended)
+export const BACKOFF_BASE_MS = 5_000; // VT5034 exponential backoff starting value
+export const BACKOFF_MAX_MS = 60_000; // backoff upper bound
+export const QUEUE_WAIT_MS = Number(process.env.PERSO_QUEUE_WAIT_MS) || 5 * 60_000; // recheck interval when no free slot is available (external/preceding jobs occupy the queue) — default 5 minutes
+
+// Infinite-loop guard (plan-independent · plugin safeguard)
+export const MAX_IDLE_MS = 30 * 60_000; // T: limit on no-progress (no submission/completion/progress%↑) (30 min). Not absolute elapsed time.
+export const MAX_RETRY = 2; // number of retries for other per-chunk failures
+
+// Media extensions — shared by the folder-input filter + choosing the video/audio endpoint at upload time.
+// (Single-file input is accepted regardless of extension, and the upload step makes the final format determination.)
+export const VIDEO_EXT = /\.(mp4|mov|webm|mkv|avi|m4v|wmv|flv|mpg|mpeg|ts|m2ts|3gp|ogv)$/i;
+export const AUDIO_EXT = /\.(mp3|wav|m4a|aac|flac|ogg|oga|opus|wma|aif|aiff|alac)$/i;
+
+// Credentials file
+export const CRED_DIR = join(homedir(), '.perso');
+export const CRED_FILE = join(CRED_DIR, 'credentials');

package/skills/dubbing/lib/ffmpeg.mjs

@@ -0,0 +1,199 @@
+// ffprobe/ffmpeg wrappers: measure duration/resolution, measure GOP, lossless segment splitting, re-encode fallback.
+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 { makeTempDir } from './tmp.mjs';
+
+const exec = promisify(execFile);
+
+/** @returns {{durationMs?:number, width?:number, height?:number, sizeBytes?:number}} */
+export async function probe(path) {
+  const args = [
+    '-v', 'error',
+    '-show_entries', 'format=duration,size',
+    '-show_entries', 'stream=width,height,codec_type',
+    '-of', 'json',
+    path,
+  ];
+  const { stdout } = await exec('ffprobe', args, { maxBuffer: 1 << 20 });
+  const info = JSON.parse(stdout);
+  const durSec = Number(info?.format?.duration);
+  const sizeBytes = Number(info?.format?.size);
+  const v = (info?.streams ?? []).find((s) => s.codec_type === 'video') ?? {};
+  return {
+    durationMs: Number.isFinite(durSec) ? Math.round(durSec * 1000) : undefined,
+    width: v.width,
+    height: v.height,
+    sizeBytes: Number.isFinite(sizeBytes) ? sizeBytes : undefined,
+  };
+}
+
+/**
+ * Cut the [startMs,endMs) range to create outPath. Re-encode (keeping resolution/fps) for exact boundaries (avoids overlap).
+ * When maxBytes is given, cap the bitrate (-maxrate) to keep the piece size at or below it.
+ */
+export async function cut(path, startMs, endMs, outPath, maxBytes) {
+  const ss = (startMs / 1000).toFixed(3);
+  const durSec = (endMs - startMs) / 1000;
+  // -ss before -i = fast input seek + frame-accurate output via re-encoding (-c copy is keyframe-aligned and causes overlap)
+  const args = ['-y', '-ss', ss, '-i', path, '-t', durSec.toFixed(3), '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20'];
+  if (maxBytes && durSec > 0) {
+    // total bitrate = maxBytes*8/dur. Use maxrate as the video cap, excluding the 128k audio.
+    // For short ranges the budget gets very large, so bufsize (=2*kbps*1000) exceeds libx264's int32 limit (2.147e9) → clamp the cap.
+    // (In that case the size constraint is non-binding, so clamping is harmless — short videos don't approach SIZE_CAP.)
+    const vKbps = Math.min(1_000_000, Math.max(100, Math.floor((maxBytes * 8) / 1000 / durSec) - 128));
+    args.push('-maxrate', `${vKbps}k`, '-bufsize', `${vKbps * 2}k`);
+  }
+  args.push('-c:a', 'aac', '-b:a', '128k', '-movflags', '+faststart', outPath);
+  await exec('ffmpeg', args, { maxBuffer: 1 << 20 });
+  return outPath;
+}
+
+// ── GOP measurement ───────────────────────────────────────────
+/** Estimate the maximum keyframe interval (GOP) in ms. Scans only the first scanSec (fast). Returns fallbackMs if measurement fails. */
+export async function probeGop(path, { scanSec = 180, fallbackMs = 4000 } = {}) {
+  try {
+    const { stdout } = await exec('ffprobe', [
+      '-v', 'error', '-select_streams', 'v:0',
+      '-read_intervals', `%+${scanSec}`,
+      '-show_entries', 'packet=pts_time,flags',
+      '-of', 'csv=print_section=0',
+      path,
+    ], { maxBuffer: 32 << 20 });
+    const keys = [];
+    for (const line of stdout.split(/\r?\n/)) {
+      const m = /^([\d.]+),\s*K/.exec(line.trim()); // keyframe packet: flags start with K
+      if (m) keys.push(parseFloat(m[1]) * 1000);
+    }
+    keys.sort((a, b) => a - b);
+    let gap = 0;
+    for (let i = 1; i < keys.length; i++) gap = Math.max(gap, keys[i] - keys[i - 1]);
+    return gap > 0 ? Math.ceil(gap) : fallbackMs;
+  } catch {
+    return fallbackMs;
+  }
+}
+
+// ── Re-encode encoder selection (fallback only): libx264 by default, HW auto-detected by OS ──
+let _venc;
+/** Auto-detect an available HW h264 encoder per OS (verifying it actually opens). Falls back to libx264 if none. Cached once. */
+export async function pickVideoEncoder() {
+  if (_venc !== undefined) return _venc;
+  let enc = 'libx264';
+  try {
+    const { stdout } = await exec('ffmpeg', ['-hide_banner', '-encoders'], { maxBuffer: 4 << 20 });
+    const has = (n) => new RegExp(`\\b${n}\\b`).test(stdout);
+    const prefs = platform() === 'darwin' ? ['h264_videotoolbox']
+      : platform() === 'win32' ? ['h264_nvenc', 'h264_qsv', 'h264_amf']
+        : ['h264_nvenc', 'h264_qsv'];
+    for (const cand of prefs) {
+      if (has(cand) && (await encoderWorks(cand))) { enc = cand; break; } // included in build ≠ actually usable → runtime check
+    }
+  } catch { /* detection failed → libx264 */ }
+  _venc = enc;
+  return enc;
+}
+// Even if included in the build, it fails at runtime without the driver/HW (e.g. nvenc's nvcuda.dll) → verify with a 0.2s dummy encode.
+async function encoderWorks(enc) {
+  try {
+    await exec('ffmpeg', ['-hide_banner', '-v', 'error', '-f', 'lavfi', '-i', 'color=c=black:s=128x128:r=10:d=0.2',
+      ...encoderVideoArgs(enc), '-f', 'null', '-'], { maxBuffer: 1 << 20 });
+    return true;
+  } catch { return false; }
+}
+/** Per-encoder quality args (for the re-encode fallback). */
+export function encoderVideoArgs(enc) {
+  switch (enc) {
+    case 'h264_nvenc': return ['-c:v', 'h264_nvenc', '-preset', 'p4', '-cq', '23'];
+    case 'h264_qsv': return ['-c:v', 'h264_qsv', '-global_quality', '23'];
+    case 'h264_amf': return ['-c:v', 'h264_amf', '-rc', 'cqp', '-qp_i', '23', '-qp_p', '23'];
+    case 'h264_videotoolbox': return ['-c:v', 'h264_videotoolbox', '-q:v', '55'];
+    default: return ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', '20'];
+  }
+}
+
+// ── segment splitting ───────────────────────────────────
+async function listParts(dir, ext) {
+  const names = (await readdir(dir)).filter((n) => /^part_\d+/.test(n) && n.endsWith(ext)).sort();
+  return names.map((n) => join(dir, n));
+}
+
+/** Whether a real video stream exists (excluding album-art attached_pic). Used to branch audio/video splitting. */
+export async function probeHasVideo(path) {
+  try {
+    const { stdout } = await exec('ffprobe', ['-v', 'error', '-select_streams', 'v', '-show_entries', 'stream=codec_type:stream_disposition=attached_pic', '-of', 'json', path], { maxBuffer: 1 << 20 });
+    const streams = JSON.parse(stdout)?.streams ?? [];
+    return streams.some((s) => s.codec_type === 'video' && !s.disposition?.attached_pic);
+  } catch {
+    return false;
+  }
+}
+
+// For audio re-encoding, use a codec matching the container (.wav→PCM, etc.) — avoids breakage from putting aac into wav.
+function audioCodecArgs(ext) {
+  if (/\.wav$/i.test(ext)) return ['-c:a', 'pcm_s16le'];
+  if (/\.mp3$/i.test(ext)) return ['-c:a', 'libmp3lame', '-q:a', '2'];
+  if (/\.(ogg|oga)$/i.test(ext)) return ['-c:a', 'libvorbis'];
+  if (/\.opus$/i.test(ext)) return ['-c:a', 'libopus'];
+  if (/\.flac$/i.test(ext)) return ['-c:a', 'flac'];
+  return ['-c:a', 'aac', '-b:a', '192k'];
+}
+
+/** Lossless (-c copy) split at segMs intervals. Video cuts at keyframe boundaries, audio (audioOnly) at frame boundaries. */
+export async function segmentCopy(path, segMs, ext = '.mp4', { audioOnly = false } = {}) {
+  const dir = await tempDir();
+  const map = audioOnly ? ['-map', '0:a'] : ['-map', '0:v:0', '-map', '0:a:0?'];
+  await exec('ffmpeg', [
+    '-y', '-i', path, ...map, '-c', 'copy',
+    '-f', 'segment', '-segment_time', (segMs / 1000).toFixed(3),
+    '-reset_timestamps', '1',
+    join(dir, `part_%03d${ext}`),
+  ], { maxBuffer: 1 << 20 });
+  return listParts(dir, ext);
+}
+
+/** Re-encode split at segMs intervals (fallback). Video: force keyframes at boundaries (HW→libx264). Audio: re-encode with the container codec. */
+export async function segmentReencode(path, segMs, ext = '.mp4', maxBytes, { audioOnly = false } = {}) {
+  if (audioOnly) {
+    const dir = await tempDir();
+    await exec('ffmpeg', ['-y', '-i', path, '-map', '0:a', ...audioCodecArgs(ext), '-f', 'segment', '-segment_time', (segMs / 1000).toFixed(3), '-reset_timestamps', '1', join(dir, `part_%03d${ext}`)], { maxBuffer: 1 << 20 });
+    return listParts(dir, ext);
+  }
+  const enc = await pickVideoEncoder();
+  try {
+    return await runSegmentReencode(path, segMs, ext, maxBytes, enc);
+  } catch (e) {
+    if (enc === 'libx264') throw e;
+    _venc = 'libx264'; // HW encoder failed at runtime → use libx264 from now on
+    return runSegmentReencode(path, segMs, ext, maxBytes, 'libx264');
+  }
+}
+async function runSegmentReencode(path, segMs, ext, maxBytes, enc) {
+  const dir = await tempDir(); // a fresh folder per attempt (so leftovers from a previous attempt don't mix in)
+  const segSec = (segMs / 1000).toFixed(3);
+  const args = ['-y', '-i', path, ...encoderVideoArgs(enc), '-force_key_frames', `expr:gte(t,n_forced*${segSec})`];
+  if (maxBytes && segMs > 0) {
+    const vKbps = Math.min(1_000_000, Math.max(100, Math.floor((maxBytes * 8) / 1000 / (segMs / 1000)) - 128));
+    args.push('-maxrate', `${vKbps}k`, '-bufsize', `${vKbps * 2}k`);
+  }
+  args.push('-c:a', 'aac', '-b:a', '128k', '-f', 'segment', '-segment_time', segSec, '-reset_timestamps', '1', join(dir, `part_%03d${ext}`));
+  await exec('ffmpeg', args, { maxBuffer: 1 << 20 });
+  return listParts(dir, ext);
+}
+
+/** Lossless extraction (-c copy) of [startMs,endMs). Keyframe boundaries for video, frame boundaries for audio (for resume re-cutting). */
+export async function cutCopy(path, startMs, endMs, outPath) {
+  const ss = (startMs / 1000).toFixed(3);
+  const t = ((endMs - startMs) / 1000).toFixed(3);
+  const hasVideo = await probeHasVideo(path);
+  const map = hasVideo ? ['-map', '0:v:0', '-map', '0:a:0?'] : ['-map', '0:a'];
+  const extra = hasVideo ? ['-movflags', '+faststart'] : [];
+  await exec('ffmpeg', ['-y', '-ss', ss, '-i', path, '-t', t, ...map, '-c', 'copy', '-reset_timestamps', '1', ...extra, outPath], { maxBuffer: 1 << 20 });
+  return outPath;
+}
+
+export function tempDir() {
+  return makeTempDir('dubbing-split-');
+}

package/skills/dubbing/lib/http_client.mjs

@@ -0,0 +1,99 @@
+// HTTP client. Attaches the XP-API-KEY header, waits on 429 rate limits, exposes error code/data.
+// The raw key is used only in the header and is never printed anywhere.
+import { API_BASE, AUTH_HEADER, BACKOFF_MAX_MS } from './config.mjs';
+import { resolveKey } from '../scripts/resolve_key.mjs';
+import { CLIENT_USER_AGENT, CLIENT_HOST } from './client_info.mjs';
+
+/** An error that carries the code/data from the response as-is (e.g. F4008 → data.maxLengthMs, VT4021, A0010). */
+export class PersoApiError extends Error {
+  constructor(httpStatus, code, message, data) {
+    super(message || code || `HTTP ${httpStatus}`);
+    this.name = 'PersoApiError';
+    this.httpStatus = httpStatus;
+    this.code = code;
+    this.data = data ?? null;
+  }
+}
+
+export class MissingKeyError extends Error {
+  constructor() {
+    super('XP_API_KEY not set — see scripts/resolve_key.mjs --check');
+    this.name = 'MissingKeyError';
+  }
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+async function parseBody(res) {
+  const text = await res.text();
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+function toError(httpStatus, body) {
+  const code = body?.code || body?.detailCode || body?.status;
+  return new PersoApiError(httpStatus, code, body?.message, body?.data);
+}
+
+/**
+ * Perso API request. Returns parsed JSON on success; throws PersoApiError (with code/data) on failure.
+ * For 429/G0005, waits until X-RateLimit-Reset and then retries automatically.
+ */
+export async function request(method, path, { body, headers = {}, query } = {}) {
+  const key = resolveKey();
+  if (!key) throw new MissingKeyError();
+
+  let url = path.startsWith('http') ? path : `${API_BASE}${path}`;
+  if (query && Object.keys(query).length) {
+    const qs = new URLSearchParams(query).toString();
+    url += (url.includes('?') ? '&' : '?') + qs;
+  }
+
+  const init = {
+    method,
+    headers: {
+      [AUTH_HEADER]: key,
+      'User-Agent': CLIENT_USER_AGENT,
+      'X-Perso-Client-Host': CLIENT_HOST,
+      ...headers,
+    },
+  };
+  if (body !== undefined) {
+    init.headers['Content-Type'] = 'application/json';
+    init.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  for (let attempt = 0; attempt < 6; attempt++) {
+    const res = await fetch(url, init);
+
+    if (res.status === 429) {
+      const data = await parseBody(res);
+      const code = data?.code || data?.detailCode;
+      // A full queue (VT4292/FULL_VT_TRANSLATE_QUEUE) is a backpressure signal → don't blindly retry; surface it immediately.
+      // (The scheduler polls and waits for a free slot, then resubmits.)
+      if (code === 'VT4292' || code === 'VT5034' || data?.detailCode === 'FULL_VT_TRANSLATE_QUEUE') {
+        throw toError(res.status, data);
+      }
+      // Other ordinary rate limits → retry with exponential backoff
+      const reset = Number(res.headers.get('X-RateLimit-Reset'));
+      const waitMs = Number.isFinite(reset) && reset > 0
+        ? Math.max(0, reset * 1000 - Date.now())
+        : Math.min(BACKOFF_MAX_MS, 2 ** attempt * 1000);
+      await sleep(Math.min(Math.max(waitMs, 1000), BACKOFF_MAX_MS));
+      continue;
+    }
+
+    const data = await parseBody(res);
+    if (!res.ok) throw toError(res.status, data);
+    return data;
+  }
+  throw new PersoApiError(429, 'G0005', 'rate limit retries exceeded');
+}
+
+export const get = (path, opts) => request('GET', path, opts);
+export const post = (path, opts) => request('POST', path, opts);
+export const put = (path, opts) => request('PUT', path, opts);

package/skills/dubbing/lib/input.mjs

@@ -0,0 +1,120 @@
+// Input handling: local path validation / URL processing.
+//  - Local file       → use as-is after existence check
+//  - Direct media URL → download to a local temp file, then merge into the flow
+//  - Platform URL (YouTube·TikTok·Drive·Vimeo) → delegate to the API external flow (no download)
+import { stat, readdir } from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import { join, basename } from 'node:path';
+import { makeTempDir } from './tmp.mjs';
+import { VIDEO_EXT, AUDIO_EXT } from './config.mjs';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const isUrl = (s) => /^https?:\/\//i.test(s);
+const PLATFORM_HOSTS = /(?:^|\.)(youtube\.com|youtu\.be|tiktok\.com|drive\.google\.com|vimeo\.com)$/i;
+// Folder input picks only video+audio (media) files (excludes non-media such as outputs/manifests). Single-file input ignores the extension.
+const isMedia = (name) => VIDEO_EXT.test(name) || AUDIO_EXT.test(name);
+
+/**
+ * Expands the input(s) into a list of processing targets. If there are several, each is expanded and flattened.
+ *  - URL/single file → 1 item
+ *  - Folder → media files inside the folder (by extension). If recursive, includes subfolders too.
+ *  - Multiple inputs (array) → expand each input by the rules above, then concatenate (URLs, paths, and folders can be mixed).
+ */
+export async function expandInputs(input, { recursive = false } = {}) {
+  const list = (Array.isArray(input) ? input : [input]).map((v) => (v ?? '').trim()).filter(Boolean);
+  if (!list.length) throw new Error('No input — provide a video file/folder path or a URL.');
+  const out = [];
+  for (const value of list) out.push(...(await expandOne(value, recursive)));
+  return out;
+}
+
+async function expandOne(value, recursive) {
+  if (isUrl(value)) return [await prepareInput(value)];
+
+  let st;
+  try {
+    st = await stat(value);
+  } catch {
+    throw new Error(`Path not found: ${value}`);
+  }
+  if (st.isFile()) return [await prepareInput(value)];
+  if (st.isDirectory()) {
+    const files = await listVideos(value, recursive);
+    if (!files.length) throw new Error(`No media files in folder: ${value}`);
+    return files.map((f) => ({ source: 'local', localPath: f, originalName: basename(f), folderInput: true }));
+  }
+  throw new Error(`Unsupported input: ${value}`);
+}
+
+async function listVideos(dir, recursive) {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const out = [];
+  for (const e of entries) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) {
+      if (recursive) out.push(...(await listVideos(full, true)));
+    } else if (isMedia(e.name)) {
+      out.push(full);
+    }
+  }
+  return out.sort();
+}
+
+/** Normalizes the input string into the form the next step expects. Throws if there is no input (→ re-prompt). */
+export async function prepareInput(input) {
+  const value = (input ?? '').trim();
+  if (!value) throw new Error('No input — provide a local video path or a URL.');
+  if (!isUrl(value)) return fromLocal(value);
+
+  let host = '';
+  try {
+    host = new URL(value).hostname;
+  } catch {
+    throw new Error(`Invalid URL: ${value}`);
+  }
+  return PLATFORM_HOSTS.test(host) ? { source: 'external', sourceUrl: value } : fromUrl(value);
+}
+
+async function fromLocal(path) {
+  let st;
+  try {
+    st = await stat(path);
+  } catch {
+    throw new Error(`File not found: ${path}`);
+  }
+  if (!st.isFile()) throw new Error(`Not a file: ${path}`);
+  return { source: 'local', localPath: path, originalName: basename(path), bytes: st.size };
+}
+
+async function fromUrl(url) {
+  const res = await fetch(url, { redirect: 'follow' });
+  if (!res.ok) throw new Error(`Failed to access URL (${res.status}): ${url}`);
+  if (!res.body) throw new Error(`URL response has no body: ${url}`);
+
+  const name = urlFileName(url, res.headers.get('content-type'));
+  const dir = await makeTempDir('dubbing-');
+  const localPath = join(dir, name);
+  await pipeline(Readable.fromWeb(res.body), createWriteStream(localPath));
+
+  const st = await stat(localPath);
+  if (st.size === 0) throw new Error(`Downloaded result is empty: ${url}`);
+  return { source: 'url', sourceUrl: url, localPath, originalName: name, bytes: st.size };
+}
+
+function urlFileName(url, contentType) {
+  try {
+    const base = basename(new URL(url).pathname);
+    if (base && /\.[a-z0-9]{2,4}$/i.test(base)) return base;
+  } catch {
+    /* fall through */
+  }
+  const ext = /mp4/i.test(contentType ?? '')
+    ? '.mp4'
+    : /webm/i.test(contentType ?? '')
+      ? '.webm'
+      : /quicktime/i.test(contentType ?? '')
+        ? '.mov'
+        : '.mp4';
+  return `input${ext}`;
+}

package/skills/dubbing/lib/languages.mjs

@@ -0,0 +1,13 @@
+// Fetch supported language codes.
+import { get } from './http_client.mjs';
+
+let _cache = null;
+
+export async function getLanguages() {
+  if (_cache) return _cache;
+  const res = await get('/video-translator/api/v1/languages');
+  // Be flexible about the response shape: result[], languages[], or the array itself
+  const list = res?.result ?? res?.languages ?? res;
+  _cache = Array.isArray(list) ? list : [];
+  return _cache;
+}

package/skills/dubbing/lib/mask.mjs

@@ -0,0 +1,7 @@
+// Key masking for output/logs. The original is never printed as-is.
+export function maskKey(key) {
+  if (!key) return '(none)';
+  const s = String(key);
+  if (s.length <= 8) return '••••';
+  return `${s.slice(0, 8)}••••${s.slice(-4)}`;
+}

package/skills/dubbing/lib/merge.mjs

@@ -0,0 +1,90 @@
+// Group merge. Accumulates OK/PASSTHROUGH in index order and splits at HARD_FAIL as group boundaries,
+// then ffmpeg-concats each run of consecutive successes.
+import { writeFile, rm, copyFile } from 'node:fs/promises';
+import { join, extname } from 'node:path';
+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';
+
+const exec = promisify(execFile);
+
+// Internal reason token → user-friendly text (avoids exposing raw codes/conditions)
+function friendlyReason(reason) {
+  const map = {
+    too_long: 'length limit', submit_failed: 'processing error', download_failed: 'download failed',
+    no_voice: 'no voice detected (nothing to dub)', elapsed_exceeded: 'timed out', failed: 'processing failed',
+  };
+  if (map[reason]) return map[reason];
+  // Pass service-provided human messages through in any language (they contain spaces or non-ASCII);
+  // only unknown internal tokens (snake_case etc.) fall back to the generic text.
+  if (typeof reason === 'string' && (/\s/.test(reason.trim()) || /[^\x20-\x7E]/.test(reason))) return reason;
+  return 'processing failed';
+}
+
+/**
+ * @param results Map(index→{status,path,reason}) or an array of the same shape
+ * @returns {outputs:[{path,indices}], failures:[{index,reason}], report:string|null}
+ */
+export async function mergeGroups(results, { outDir } = {}) {
+  const items = [...(results instanceof Map ? results.values() : results)].sort((a, b) => a.index - b.index);
+  const dir = outDir ?? (await makeTempDir('dubbing-merge-'));
+
+  const groups = [];
+  const failures = [];
+  let cur = [];
+  for (const it of items) {
+    if (it.status === 'OK' || it.status === 'PASSTHROUGH') {
+      cur.push(it);
+    } else {
+      // HARD_FAIL (generation failed) / DLFAIL (generated, only download failed) → a gap in this output (boundary split)
+      failures.push({ index: it.index, reason: it.reason ?? 'unknown' });
+      if (cur.length) { groups.push(cur); cur = []; }
+    }
+  }
+  if (cur.length) groups.push(cur);
+
+  const outputs = [];
+  for (let g = 0; g < groups.length; g++) {
+    const group = groups[g];
+    const persoName = group.find((i) => i.name)?.name ?? null; // file name provided by Perso (if any)
+    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);
+    outputs.push({ path: out, indices: group.map((i) => i.index), name: persoName });
+  }
+
+  const report = failures.length
+    ? failures.map((f) => `Part ${f.index + 1} excluded — ${friendlyReason(f.reason)}`).join('\n')
+    : null;
+
+  return { outputs, failures, report };
+}
+
+async function concat(paths, outPath) {
+  if (paths.length === 1) {
+    // single piece (no cutting) → copy as-is without ffmpeg
+    await copyFile(paths[0], outPath);
+    return outPath;
+  }
+
+  ensureFfmpeg(); // multi-merge needs ffmpeg (usually already installed since splitting occurred)
+  const listFile = `${outPath}.concat.txt`;
+  const list = paths.map((p) => `file '${p.replace(/\\/g, '/').replace(/'/g, "'\\''")}'`).join('\n');
+  await writeFile(listFile, list, 'utf8');
+
+  const base = ['-y', '-f', 'concat', '-safe', '0', '-i', listFile];
+  try {
+    // when codec/resolution/sample rate match, do a lossless fast merge (-c copy)
+    await exec('ffmpeg', [...base, '-c', 'copy', '-movflags', '+faststart', outPath], { maxBuffer: 1 << 20 });
+  } catch {
+    // on mismatch, fall back to re-encoding (libx264 by default, HW auto-detected by OS)
+    const enc = await pickVideoEncoder();
+    await exec('ffmpeg', [...base, ...encoderVideoArgs(enc), '-c:a', 'aac', '-movflags', '+faststart', outPath], { maxBuffer: 1 << 20 });
+  } finally {
+    await rm(listFile, { force: true }).catch(() => {}); // clean up the concat list file immediately
+  }
+  return outPath;
+}

package/skills/dubbing/lib/messages.mjs

@@ -0,0 +1,38 @@
+// User-facing guidance message templates.
+import { CLIENT_HOST, CLIENT_VERSION } from './client_info.mjs';
+
+export const SUBSCRIPTION_URL = 'https://portal.perso.ai/en/workspace/space-settings?tab=Subscription';
+export const PRICING_URL = 'https://perso.ai/en/workspace/vt?pricing';
+
+// UTM identity — mirrors the API-call identity (User-Agent perso-dubbing/<version> (host=agents)):
+// one unified 'agents' channel across all hosts; the skill version is carried in utm_content.
+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 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());
+    const status =
+      `   Current plan: ${planTier ?? 'unknown'} · Credits left: ${remainingQuota ?? '?'}` +
+      (remainingNote ? ` · Remaining: ${remainingNote}` : '');
+    const lines = [
+      'Out of usage/credits — only part of the work completed. The finished items are delivered above.',
+      status,
+      '',
+    ];
+    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');
+  },
+};