perso-dubbing 0.2.0 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -3,13 +3,13 @@
   "owner": {
     "name": "Perso AI"
   },
-  "description": "Perso AI agent plugins — AI dubbing (video voice translation with lip-sync).",
+  "description": "Perso AI agent plugins — AI dubbing (video voice translation with lip-sync & audio separation).",
   "plugins": [
     {
       "name": "perso-dubbing",
       "source": { "source": "npm", "package": "perso-dubbing" },
-      "description": "Auto-dub videos into other languages with lip-sync (Perso AI Dubbing). Single files, folders, URLs, auto split & merge for long media, multi-language output, resume.",
-      "version": "0.2.0",
+      "description": "Auto-dub videos into other languages with lip-sync (Perso AI Dubbing), plus voice/background audio separation. Single files, folders, URLs, auto split & merge for long media, multi-language output, resume.",
+      "version": "0.3.0",
       "author": { "name": "Perso AI" },
       "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
       "repository": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
-  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
-  "version": "0.2.0",
+  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
+  "version": "0.3.0",
   "author": {
     "name": "Perso Dubbing"
   },

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
-  "version": "0.2.0",
-  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
+  "version": "0.3.0",
+  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "skills": "./skills/",
   "author": "Perso AI",
   "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,8 @@
 {
   "name": "perso-dubbing",
-  "version": "0.2.0",
-  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
+  "displayName": "Perso AI Dubbing",
+  "version": "0.3.0",
+  "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "author": { "name": "Perso AI" },
   "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
   "repository": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin",

package/README.md

@@ -6,7 +6,7 @@
 ![Platforms](https://img.shields.io/badge/platforms-Claude%20Code%20%C2%B7%20Antigravity%20%C2%B7%20Codex%20%C2%B7%20Cursor-555)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-A coding-agent skill that brings [Perso AI](https://perso.ai)'s **Dubbing (AI dubbing)** to your agent. It **auto-dubs** videos into other languages — a single file or a whole folder, and even oversized or very long media is automatically split, processed, and merged back together.
+A coding-agent skill that brings [Perso AI](https://perso.ai)'s **Dubbing (AI dubbing)** to your agent. It **auto-dubs** videos into other languages — a single file or a whole folder, and even oversized or very long media is automatically split, processed, and merged back together. It can also **lip-sync** the dubbed video and **separate voice from background audio**.
 
 It calls the Perso Dubbing API under the hood, so **a Perso Dubbing API key is required.** → <a href="https://developers.perso.ai/api-keys" target="_blank" rel="noopener noreferrer">Get an API key</a>
 
@@ -116,6 +116,12 @@ npm run dub -- "clip.mp4" --target en,ja,zh
 
 # Several inputs at once (URLs, files, and folders can be mixed)
 npm run dub -- "https://youtu.be/..." "clip2.mp4" "C:\videos" --target en
+
+# Dub + lip-sync (mouth matched to the dubbed audio; extra credits)
+npm run dub -- "clip.mp4" --target en --lipsync
+
+# Separate voice / background audio tracks (no dubbing)
+npm run dub -- "clip.mp4" --separate
 ```
 
 *(Equivalent direct call: `node skills/dubbing/scripts/dubbing.mjs …` — or `node scripts/dubbing.mjs …` from inside an installed skill folder.)*

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
-  "version": "0.2.0",
-  "description": "Perso AI video auto-dubbing agent skill (Claude Code / Codex / Cursor / Antigravity)",
+  "version": "0.3.0",
+  "description": "Perso AI video auto-dubbing agent skill — dubbing, lip-sync, audio separation (Claude Code / Codex / Cursor / Antigravity)",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skills/dubbing/SKILL.md

@@ -9,58 +9,94 @@ A skill that auto-dubs videos via the Perso AI Dubbing API.
 
 ## Core rules (must follow)
 
-- **Only the worker sees the raw key.** Never open the key with `Read`, echo it, or pass it as a command-line argument. The real key is used by the `lib/`·`scripts/` workers in the `XP-API-KEY` header only.
-- **One command = the whole job.** `scripts/dubbing.mjs` does everything: validate input → upload → split only if needed → translate → merge → save. **Never run `prepare_input.mjs` or `probe_split.mjs` before it** — they are debug tools, and `probe_split.mjs` performs a real upload (running it first uploads the same video twice).
-- **Always run `dubbing.mjs` in the background.** Jobs take minutes to hours; a foreground shell with a timeout kills the run mid-way.
-- When languages are unspecified: source `auto`, target `en`.
-- **Multiple languages in a single command** — comma-separate them (`--target en,zh,ja`): split/upload happens once per video and the mediaSeq is reused per language. Running once per language re-uploads the same source once per language — avoid it.
-- **Relay progress faithfully.** Surface the `[progress]` lines the worker prints to stdout to the user's chat **verbatim (or summarized)** — don't let them stay buried in background logs, and don't announce steps that didn't appear: splitting/merging happen only for videos that exceeded the limit, so an unsplit video is just "translation → save" (never promise a "merge" step for it). The two-space-indented stderr detail logs don't need relaying.
-- **Unsupported formats are skipped automatically.** If upload doesn't accept a format, that file is skipped and the rest keep processing. Relay the skip notice to the user too.
+- **Only the worker sees the raw key.** Never open the key with `Read`, echo it, or pass it as a command-line argument. Workers send it in the `XP-API-KEY` header only.
+- **One command = the whole job.** `scripts/dubbing.mjs` handles upload · split · translate · merge · save by itself. **Never run `prepare_input.mjs` or `probe_split.mjs` before it** — they are debug tools, and `probe_split.mjs` performs a real upload (the video would upload twice).
+- **Always run `dubbing.mjs` in the background.** Jobs take minutes to hours; a foreground shell timeout kills the run mid-way.
+- Languages unspecified → source `auto`, target `en`.
+- **Multiple languages go in one command** (`--target en,zh,ja`) — upload/split happens once and is reused per language. Never run once per language (re-uploads the source each time).
+- **Relay progress faithfully.** Surface the worker's stdout `[progress]` lines to chat, verbatim or summarized — and don't announce steps that didn't appear (splitting/merging exist only for over-limit videos). The indented stderr detail logs don't need relaying.
+- **Unsupported formats are skipped automatically** and the rest keep processing — relay the skip notice.
 
 ## One-time setup
 
-1. **API key** — no separate step needed: if no key is registered, `dubbing.mjs` opens a key file itself on first run (self-heal) — show the user the printed key-file path (as a **clickable** path) and tell them to "click to open, paste just the key, and save." It's encrypted on save and the file is deleted. To check/register ahead of time: `node scripts/resolve_key.mjs --check` (exit 2 = missing → `--watch` registers the same way; don't run `--watch` if a dubbing run is already waiting for the key — two watchers would open two editors). Never paste the key into chat. Get a key: https://developers.perso.ai/api-keys
-2. **ffmpeg/ffprobe** — no need to pre-install. Installed automatically **only when a video exceeds the plan's length limit and must be split** (approve only if permission is requested). Manual check: `node scripts/check_deps.mjs`.
+1. **API key** — no separate step: with no key registered, `dubbing.mjs` opens a key file on first run. Show the user the printed key-file path (clickable) and tell them to paste just the key and save (it's encrypted and the file deleted). Pre-check: `node scripts/resolve_key.mjs --check` (exit 2 = missing; `--watch` registers the same way — never start it while a run is already waiting for the key). Never paste the key into chat. Get a key: https://developers.perso.ai/api-keys
+2. **ffmpeg/ffprobe** — auto-installed only when a video exceeds the plan limit and must be split (approve if permission is requested). Manual check: `node scripts/check_deps.mjs`.
 
 ## Run
 
 After the key gate, collect the input (local path or URL — re-ask if missing) and run **in the background**:
 
-- Single: `node scripts/dubbing.mjs "<file|URL>" [--source auto] [--target en] [--space "space name"] [--out result.mp4]`
-- Multi-language: `node scripts/dubbing.mjs "<file|URL>" --target en,zh,ja` — one output file per language.
-- Multiple inputs (URLs, files, and folders can be mixed): `node scripts/dubbing.mjs "<URL1>" "<URL2>" "<file>" --target en,ja` — results are saved per input × language next to each source (`--out <folder>` collects them into that folder).
+- Single: `node scripts/dubbing.mjs "<file|URL>" [--source auto] [--target en] [--space "space name"] [--out result.mp4] [--lipsync]`
+- Multi-language / multi-input (one or more inputs; URLs and files can be mixed): `node scripts/dubbing.mjs "<URL>" "<file>" --target en,ja` — one output per input × language, saved next to each source (`--out <folder>` collects them).
 - Folder (batch): `node scripts/dubbing.mjs "<folder>" [--target en,zh] [--recursive] [--out output-folder]`
 
-**Space selection** — if the account has several workspaces, the worker stops before uploading anything, prints `[space-select]` lines listing each space as **name | (plan) | remaining credits**, and exits (code 3). Show the user ONLY those options (no internal numbers), ask which one to dub in, then re-run the same command with `--space "<space name>"`. A single-space account proceeds without asking; `PERSO_SPACE_SEQ` pins the choice for every run.
+**Space selection** — with several workspaces the worker stops before uploading, prints `[space-select]` lines (**name | (plan) | remaining credits**) and exits (code 3). Show the user ONLY those options (no internal numbers), ask which one, and re-run with `--space "<space name>"`. One space → no question; `PERSO_SPACE_SEQ` pins it.
 
-What happens while it runs (so you can explain the waiting to the user):
+While it runs (for explaining the wait):
 
-- **Upload-first split decision**: the whole file is uploaded first; only if the plan limit rejects it (`F4008`/size) is ffmpeg installed and the video split losslessly (`-c copy`, re-encode only when lossless isn't possible). External URLs (YouTube·TikTok·Drive·Vimeo) are handled server-side.
-- **One global queue**: all inputs × parts × languages fill a single pool. Only as many jobs as there are free slots are submitted; when the queue is fully occupied by other jobs, it re-checks every 5 minutes. An engine error on a part cancels that part's other languages; a silent (no-voice) part of a split video passes the original through; an idle guard prevents hanging forever.
-- **Merge & save**: consecutive successful parts are concatenated into one file per (input × language). Output names: a non-split single output keeps the **Perso download filename as-is**; a split-and-merged output is `<original-name>.dubbed.<lang>.<ext>`; on name collision, `_2`,`_3`….
+- **Split**: the whole file is uploaded first; only a plan-limit rejection installs ffmpeg and splits losslessly. External URLs (YouTube·TikTok·Drive·Vimeo) are handled server-side.
+- **Queue**: all inputs × parts × languages share one pool; a full queue is re-checked every 5 minutes. An engine error on a part cancels that part's other languages; a silent part passes the original through; an idle guard prevents hanging forever.
+- **Save**: parts are merged back into one file per (input × language). An unsplit output keeps the Perso filename; a merged one is `<original-name>.dubbed.<lang>.<ext>`; collisions get `_2`,`_3`….
+
+## Lip-sync
+
+Lip-sync (mouth matched to the dubbed audio) runs **after** dubbing, on the finished dubbing project. Video only — audio inputs are rejected. It is a long job: **run in the background and tell the user up-front it takes considerably longer than dubbing.** Credits (server billing is authoritative): dubbing ≈ seconds ×1 · lip-sync ≈ ×2 · both ≈ ×3 — dubbing now + lip-sync later costs the same as both at once. **4K+ sources: every rate ×3 on pro/business/enterprise plans** (e.g. a 1-min 4K dub+lip-sync ≈ 60×3×3 = 540) — mention this when the video is 4K.
+
+Pick the flow by what exists:
+
+1. **New video + lip-sync** — one command runs the whole chain (dub → lip-sync → save); warn that both stages bill:
+   `node scripts/dubbing.mjs "<file|URL>" --target en --lipsync`
+   If `[credit-check]` lines print and it exits (code 3), the estimate exceeds the remaining credits: show those lines (top-up URL included), and re-run with `--force` only after the user tops up or approves continuing anyway.
+2. **Dubbed earlier in this session** — every finished run prints a `[project-ref] {...}` line. **Keep it; never show it to the user.** Lip-sync without re-dubbing (×2, no dubbing charge):
+   `node scripts/dubbing.mjs --lipsync-only '<that [project-ref] JSON>'`
+3. **No [project-ref] in this session** — ask if the user knows the project number from the Perso portal (`--lipsync-only <number>`, ×2). Otherwise the video must be dubbed again (`--lipsync`, ×3) — confirm before re-dubbing.
+
+Rules:
+
+- **Repeating lip-sync on the same project bills again** (no server-side dedup). If this session already lip-synced it, point at the existing file and re-run only on explicit confirmation.
+- **If lip-sync fails, the worker saves the dubbed video instead** and says so in the final report — relay that clearly; the dubbing credits are not wasted.
+- Credits running out between dubbing and lip-sync: the dubbed videos are saved and resume finishes only the lip-sync — relay the printed top-up URL and resume command verbatim.
+
+## Audio separation
+
+To split voice from background sound (no dubbing involved), run **in the background**:
+
+`node scripts/dubbing.mjs --separate "<file|URL|folder>" [--space "space name"] [--out folder]`
+
+- Outputs per input, next to the source (`--out` is a folder here): `<name>.voice.wav` · `<name>.background.wav` · `<name>.sub_background.wav`.
+- Credits ≈ seconds ×0.5. No language options; cannot combine with lip-sync flags.
+- Auto-split/merge, key gate, `[space-select]` and `[progress]` rules apply unchanged.
+- **No resume for separation yet** — re-running an interrupted run re-bills (parts run one at a time, so at most one part is at risk). Don't kill a running separation casually.
 
 ## Interruption & resume
 
-The worker saves a state file (`*.dubresume.json`, next to the source or `--out`) **from the moment the split plan is known and after every completed piece** — so a run that dies for ANY reason (out of credits, crash, killed shell, Ctrl+C) can resume without redoing paid work:
+The worker saves a state file (`*.dubresume.json`, next to the source or `--out`) from the moment the split plan is known and after every completed piece, so a run that dies for ANY reason (credits, crash, killed shell) resumes without redoing paid work:
 
 ```
 node scripts/dubbing.mjs --resume "<state-file>"
 ```
 
-Completed parts are skipped automatically (same for single · multi-input · batch). The state file is deleted when everything finishes.
+Completed parts are skipped automatically; the state file is deleted when everything finishes.
+
+**Re-running the original command while a state file exists is blocked** — the worker prints `[resume-check]` lines (exit 3) instead of re-billing. Relay the printed `--resume` command and run that. Delete the state file **only** if the user explicitly chooses to pay for the completed parts again — never on your own.
+
+**On an insufficient-credits stop**: deliver the completed parts and relay the worker's upgrade/Get-credits URL and resume command **verbatim** — that URL is plain stdout (not `[progress]`), so don't drop it while summarizing.
+
+## Perso portal (answer only when asked)
 
-**When it stops due to insufficient usage (credits)**: deliver the completed parts and **surface the upgrade / buy-more-credits (Get credits) URL and the resume instructions printed by the worker, verbatim and without omission**. (That URL line is plain stdout, not a `[progress]` line, so it's easy to drop while summarizing — never just say "top up credits and re-run" without the upgrade/credit path. Always include the URL.)
+Every run is also a project in the user's Perso portal account. If the user wants more than the delivered files (subtitles, audio-only, other formats) or to browse/re-download earlier projects, point them to https://portal.perso.ai — projects live in the workspace used for the run; split parts are numbered `_01`, `_02`, …. Never add this to progress relays or final reports.
 
 ## Config (env)
 
-- `PERSO_API_BASE` — API base URL (default `https://api.perso.ai`).
-- `PERSO_MEDIA_BASE` — media host for result files (default `https://portal-media.perso.ai`). Prepended when a response path is relative.
+- `PERSO_API_BASE` — API base URL (default `https://api.perso.ai`). **https `perso.ai` hosts only** — anything else is rejected at startup (the API key travels in a header to this host).
+- `PERSO_MEDIA_BASE` — media host for result files (default `https://portal-media.perso.ai`). Prepended when a response path is relative. Same https `perso.ai`-only rule.
 - `PERSO_SPACE_SEQ` — pin the space to use for every run (skips the space question).
 - `XP_API_KEY` — set the key directly (highest priority). Otherwise resolved from `~/.perso/credentials` (DPAPI-encrypted on Windows).
 - `PERSO_NO_WATCH` — when no key is registered, `dubbing.mjs` normally self-heals by opening a key file and waiting for the user to paste the key. Set this to fail fast instead (headless/CI).
 - `PERSO_NO_OPEN` — don't auto-open the key file in an editor during key registration (headless; the file path is still printed).
 - `PERSO_SIZE_CAP_BYTES` — upload size cap used for the split decision (default ≈1.9 GB, under the API's 2 GB limit).
 - `PERSO_QUEUE_WAIT_MS` — how long to wait between queue re-checks when all slots are occupied by other jobs (default 5 minutes).
+- `PERSO_LIPSYNC_IDLE_MS` — no-progress allowance for a lip-sync job whose video length is unknown (default 3 hours).
 
 ## Advanced (debug only — not part of the normal flow)
 

package/skills/dubbing/lib/api_adapter.mjs

@@ -3,11 +3,11 @@
 // Errors are thrown as-is via PersoApiError (with code/data) so the caller (scheduler) can branch on them.
 import { stat } from 'node:fs/promises';
 import { createWriteStream, createReadStream } from 'node:fs';
-import { basename } from 'node:path';
+import { basename, extname } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { get, post, put, PersoApiError } from './http_client.mjs';
-import { AUDIO_EXT } from './config.mjs';
+import { AUDIO_EXT, persoBaseUrl } from './config.mjs';
 
 const VT = '/video-translator/api/v1';
 
@@ -21,8 +21,9 @@ export class UnsupportedMediaError extends Error {
   }
 }
 // A file path in the response may be relative (perso-storage) → turn it into an absolute URL via the media base + encoding.
-// The media host can differ per environment, so it can be overridden with PERSO_MEDIA_BASE (defaults to production).
-const MEDIA_BASE = (process.env.PERSO_MEDIA_BASE || 'https://portal-media.perso.ai').replace(/\/+$/, '');
+// The media host can differ per environment, so it can be overridden with PERSO_MEDIA_BASE (defaults to
+// production) — perso.ai hosts only, or an injected env could swap the delivered result files.
+const MEDIA_BASE = persoBaseUrl('PERSO_MEDIA_BASE', process.env.PERSO_MEDIA_BASE, 'https://portal-media.perso.ai');
 const absolutize = (u) => {
   if (!u) return u;
   if (/^https?:\/\//i.test(u)) return u;
@@ -137,6 +138,49 @@ export async function requestTranslation(spaceSeq, mediaSeq, opts = {}) {
   return res?.result?.startGenerateProjectIdList ?? [];
 }
 
+// ── audio separation ───────────────────────────────────
+/** Request voice/background separation of an uploaded media → array of projectIds (same async project pattern as translate). */
+export async function requestAudioSeparation(spaceSeq, mediaSeq, { title, kind = 'video' } = {}) {
+  if (!_queueInited.has(spaceSeq)) {
+    await put(`${VT}/projects/spaces/${spaceSeq}/queue`).catch(() => {});
+    _queueInited.add(spaceSeq);
+  }
+  const body = { mediaSeq, isVideoProject: kind !== 'audio', ...(title ? { title } : {}) };
+  const res = await post(`${VT}/projects/spaces/${spaceSeq}/audio-separation`, { body });
+  return res?.result?.startGenerateProjectIdList ?? [];
+}
+
+/** Download the separated tracks of a completed separation project. `download?target=` does not serve the
+ *  voice/base-background tracks (server gap, verified 2026-07: VT4001/VT5001) — the project detail's
+ *  downloadPathInfo does. outPathFor(label, ext) decides where each track is written. */
+export async function downloadSeparation(projectSeq, spaceSeq, outPathFor) {
+  const p = await get(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}`);
+  const d = p?.downloadPathInfo ?? {};
+  const tracks = [
+    ['voice', d.originalVoicePath],
+    ['background', d.originalBackgroundPath],
+    ['sub_background', d.originalSubBackgroundPath],
+  ].filter(([, rel]) => rel);
+  if (!tracks.length) throw new Error('No separated tracks found on the project.');
+  const saved = [];
+  for (const [label, rel] of tracks) {
+    const link = absolutize(rel);
+    const fileName = decodeURIComponent(new URL(link).pathname.split('/').pop() || '') || null;
+    const outPath = outPathFor(label, extname(fileName ?? '') || '.wav');
+    await fetchToFile(link, outPath);
+    saved.push({ label, path: outPath, fileName });
+  }
+  return saved;
+}
+
+// ── requestLipSync ─────────────────────────────────────
+/** Request lip-sync generation for a completed translation project → array of new projectIds (a lip-sync run is a separate project). */
+export async function requestLipSync(projectSeq, spaceSeq, { speed = 'GREEN', title } = {}) {
+  const body = { preferredSpeedType: speed, ...(title ? { title } : {}) }; // title omitted → the parent project's title is used
+  const res = await post(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}/lip-sync`, { body });
+  return res?.result?.startGenerateProjectIdList ?? [];
+}
+
 // ── getStatus ──────────────────────────────────────────
 /** Normalize based on progressReason. On failure, classify whether it's silence via engineErrorMessage from /progress. */
 export async function getStatus(projectSeq, spaceSeq) {
@@ -178,13 +222,28 @@ export async function cancel(projectSeq, spaceSeq) {
 }
 
 // ── download ───────────────────────────────────────────
-/** Check download-info → download?target → download link (save to outPath if needed). */
-export async function download(projectSeq, spaceSeq, { kind = 'video', outPath } = {}) {
-  const isAudio = kind === 'audio';
-  const target = isAudio ? 'voiceWithBackgroundAudio' : 'dubbingVideo'; // target for the audio-dubbing result
+// Fallback link scan: any string value under a *DownloadLink key (payload field names vary per target).
+function findDownloadLink(o) {
+  if (!o || typeof o !== 'object') return null;
+  for (const [k, v] of Object.entries(o)) {
+    if (typeof v === 'string' && /DownloadLink$/.test(k) && v) return v;
+    if (v && typeof v === 'object') {
+      const hit = findDownloadLink(v);
+      if (hit) return hit;
+    }
+  }
+  return null;
+}
+
+/** Check download-info → download?target → download link (save to outPath if needed). lipsync:true fetches the lip-sync video. */
+export async function download(projectSeq, spaceSeq, { kind = 'video', outPath, lipsync = false } = {}) {
+  const isAudio = !lipsync && kind === 'audio';
+  const target = lipsync ? 'lipSyncVideo' : isAudio ? 'voiceWithBackgroundAudio' : 'dubbingVideo';
   const info = await get(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}/download-info`);
   const flags = info?.result ?? info;
-  if (isAudio) {
+  if (lipsync) {
+    if (flags?.hasLipSyncVideo === false) throw new Error('Lip-sync video is not ready yet.');
+  } else if (isAudio) {
     if (flags?.hasTranslatedVoice === false && flags?.hasTranslateAudio === false) {
       throw new Error('Translated audio is not ready yet.');
     }
@@ -198,7 +257,7 @@ export async function download(projectSeq, spaceSeq, { kind = 'video', outPath }
     r.videoFile?.videoDownloadLink ??
     r.audioFile?.voiceWithBackgroundAudioDownloadLink ??
     r.zippedFileDownloadLink ??
-    null;
+    findDownloadLink(r);
   if (!raw) throw new Error('Could not find a download link.');
   const link = absolutize(raw);
   const fileName = decodeURIComponent(new URL(link).pathname.split('/').pop() || '') || null;

package/skills/dubbing/lib/config.mjs

@@ -3,7 +3,20 @@ 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(/\/+$/, '');
+// PERSO_API_BASE / PERSO_MEDIA_BASE come from env, which a hostile repo config can plant for the agent —
+// and every API call sends the key in a header to whatever host API_BASE names. Only https perso.ai hosts.
+export function persoBaseUrl(name, raw, fallback) {
+  const v = (raw ?? '').trim();
+  if (!v) return fallback;
+  let u = null;
+  try { u = new URL(v); } catch { /* rejected below */ }
+  const host = u?.hostname ?? '';
+  if (u?.protocol !== 'https:' || (host !== 'perso.ai' && !host.endsWith('.perso.ai'))) {
+    throw new Error(`${name} must be an https:// URL on a perso.ai host (e.g. ${fallback}) — got "${v}"`);
+  }
+  return v.replace(/\/+$/, '');
+}
+export const API_BASE = persoBaseUrl('PERSO_API_BASE', process.env.PERSO_API_BASE, 'https://api.perso.ai');
 export const AUTH_HEADER = 'XP-API-KEY';
 
 // Polling / backoff
@@ -16,6 +29,19 @@ export const QUEUE_WAIT_MS = Number(process.env.PERSO_QUEUE_WAIT_MS) || 5 * 60_0
 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
 
+// Lip-sync jobs run far longer than dubbing → poll less often and allow a longer no-progress window.
+export const LIPSYNC_POLL_INTERVAL_MS = 30_000;
+export const LIPSYNC_IDLE_PER_DURATION = 15; // no-progress allowance = video duration × this (when the duration is known)
+export const LIPSYNC_IDLE_MS = Number(process.env.PERSO_LIPSYNC_IDLE_MS) || 3 * 60 * 60_000; // fallback allowance when the duration is unknown
+
+// Credit pre-check estimate (per second of video). The server's billing is authoritative — these only power an upfront warning.
+export const CREDIT_RATE_DUB = 1;
+export const CREDIT_RATE_LIPSYNC = 2;
+export const CREDIT_RATE_SEPARATION = 0.5;
+// 4K+ sources are billed ×3 for dubbing/lip-sync on pro/business/enterprise plans only.
+export const UHD_CREDIT_MULT = 3;
+export const UHD_BILLED_TIERS = ['pro', 'business', 'enterprise'];
+
 // 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;

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,15 +9,15 @@ 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;
+export 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 } = {}) => {
+  //   { planTier, remainingQuota, remainingNote, resumeHint, note }
+  quotaExceeded: ({ planTier, remainingQuota, remainingNote, resumeHint, note } = {}) => {
     const isLow = LOW_TIERS.has(String(planTier ?? '').toLowerCase());
     const status =
       `   Current plan: ${planTier ?? 'unknown'} · Credits left: ${remainingQuota ?? '?'}` +
@@ -25,6 +25,7 @@ export const messages = {
     const lines = [
       'Out of usage/credits — only part of the work completed. The finished items are delivered above.',
       status,
+      ...(note ? [note] : []),
       '',
     ];
     if (isLow) {