perso-dubbing 0.2.0 → 0.4.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.4.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.4.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.4.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.4.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>
 
@@ -24,13 +24,16 @@ Because every host uses the same **Agent Skills standard** (`SKILL.md`), it work
 
 ## Install
 
-> **🤖 To the agent:** If you were given only this repository's URL, run this single command — it fetches the package, auto-detects every installed host (Claude Code · Codex · Cursor · Antigravity), and installs the skill into each:
+> **🤖 To the agent:** If you were given only this repository's URL, pick the path for your host:
+>
+> - **Claude Code:** do **not** run npx right away — even if the user said "install this". Show the user the two plugin-marketplace commands below and ask them to type the commands themselves (they are user-typed slash commands you cannot execute). Fall back to npx only if the user still wants you to handle the install after seeing them.
+> - **Codex · Cursor · Antigravity, or the user delegated the install to you:** run this single command — it fetches the package, auto-detects every installed host, and installs the skill into each:
 >
 > ```bash
 > npx perso-dubbing
 > ```
 >
-> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed). In Claude Code, prefer the plugin-marketplace commands below.
+> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed).
 
 ### Claude Code (plugin marketplace — recommended)
 
@@ -116,6 +119,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.4.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,128 @@ 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):
+**Split confirmation** — if the input exceeds the length or size limit and must be auto split & merged (dubbing, dub+lip-sync, or audio separation), the worker stops (exit 3) and prints `[split-confirm]` lines. Relay them and ask the user: it exceeds the length/size limit, so it needs **automatic split → process → merge**, which can come out **less polished than splitting it up themselves** — proceed automatically? On a yes, re-run the **same command with `--allow-split`** (nothing is billed until this point, so re-running is free). Batch runs: `--allow-split` authorizes every split in the run.
 
-- **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`….
+While it runs (for explaining the wait):
+
+- **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.
+- **Resume** — separation saves the same `*.dubresume.json` state with a per-part checkpoint, so an interrupted run (credits, crash, killed shell) continues with `node scripts/dubbing.mjs --resume "<state-file>"` **without re-submitting already-paid parts**. Re-running the original command is blocked (`[resume-check]`, exit 3) — run the printed `--resume` instead.
 
 ## 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, then relay the worker's guidance and resume command **verbatim** — plain stdout (not `[progress]`), so don't drop it while summarizing. The guidance points to `scripts/billing.mjs` for a payment link — see **Plan upgrade & credits** below.
+
+## Plan upgrade & credits
+
+When the user runs out of credits (the stop above) **or** asks to upgrade / buy more credits, you can generate a Stripe payment link. **You only ever hand the link to the user — never open it or complete payment yourself**, even if the user asks you to pay.
+
+Run this first — it detects the plan and prints the fitting flow, the choices, and (with `--shortfall`) a recommendation:
+
+`node scripts/billing.mjs options [--shortfall <estimated remaining credits>] [--space "<space name>"]`
+
+It routes by the current plan tier — ask only the question for that branch, then generate the link:
+
+- **free → subscribe.** Ask which plan and **monthly or yearly** (starter is monthly-only). Currency defaults to USD; use KRW only if the user asks.
+  `node scripts/billing.mjs link --checkout --plan <starter|creator|pro> --period <monthly|yearly> [--currency usd|krw]`
+- **starter / creator → change plan.** Ask which plan; billing period and currency are locked to the existing subscription (handled automatically).
+  `node scripts/billing.mjs link --billing --plan <creator|pro>`
+- **pro / business → buy credits.** Ask how many packs (1 pack = 60 credits, USD). With `--shortfall`, `options` recommends a quantity.
+  `node scripts/billing.mjs link --credits --quantity <n>`
+- **enterprise → no self-serve.** Tell the user to contact their workspace administrator.
+
+**Recommending on a credit-out stop**: estimate the remaining work's credits (dubbing ≈ ×1/s · lip-sync ≈ ×2 · separation ≈ ×0.5, and ×3 for 4K on pro+), pass it as `--shortfall`, and relay the tool's recommendation. If even the top self-serve plan or a reasonable credit quantity can't cover it, point the user to their administrator (Enterprise) instead.
+
+Hand the returned link to the user to complete payment in their browser; after they top up, resume the interrupted job with the printed `--resume` command (no re-billing).
+
+## Perso portal (answer only when asked)
+
+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.
+
+## Version updates
+
+Once a day (first run after 00:00 UTC) the worker checks npm for a newer release and, **after the current job finishes** (never mid-run), may print a one-line `ℹ️  Update available: …` notice. When you see it, relay it and act by install method:
+
+- **Claude Code plugin (marketplace):** tell the user to run `/plugin update perso-dubbing` — a slash command you cannot run yourself.
+- **npx / manual install:** ask the user whether to update, and on yes run `npx perso-dubbing@latest`.
 
-**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.)
+The notice lists both commands; pick the one matching how it was installed. It never blocks a run and can be silenced with `PERSO_NO_UPDATE_CHECK=1`.
 
 ## 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).
+- `PERSO_NO_UPDATE_CHECK` — skip the once-a-day npm version-update check (headless/CI, or to avoid the extra network call).
 
 ## 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/billing.mjs

@@ -0,0 +1,159 @@
+// Plan-upgrade / credit-purchase helpers. All calls go to the Perso payment service with the same
+// XP-API-KEY the rest of the skill uses; the agent only ever receives a Stripe link to hand to the user —
+// it must never open or complete payment itself.
+import { get, post, PersoApiError } from './http_client.mjs';
+
+export const CURRENCIES = ['usd', 'krw'];
+export const DEFAULT_CURRENCY = 'usd'; // international default for new subscriptions; KRW on request
+export const ONE_TIME_CURRENCY = 'usd'; // credit packs are always charged in USD
+// Credits granted per pack — used only to turn a credit shortfall into a pack quantity.
+// Server billing is authoritative.
+export const CREDIT_PER_UNIT = 60;
+export const RETURN_URL = 'https://perso.ai/en/workspace/vt';
+const SUCCESS_PARAMS = 's_seq={spaceSeq}';
+
+// Low → high. Used to find which tiers are an upgrade from the current one.
+const TIER_ORDER = ['free', 'starter', 'creator', 'pro', 'business', 'enterprise'];
+const tierRank = (t) => TIER_ORDER.indexOf(String(t ?? '').toLowerCase());
+
+/** Which purchase flow fits the current plan tier. */
+export function actionForTier(tier) {
+  const t = String(tier ?? '').toLowerCase();
+  if (t === 'starter' || t === 'creator') return 'billing';   // has a subscription → change plan
+  if (t === 'pro' || t === 'business') return 'one-time';      // top self-serve → buy credits
+  if (t === 'enterprise') return 'contact';                    // custom → contact admin, no self-serve
+  return 'checkout';                                           // free/unknown → new subscription
+}
+
+const extractLink = (res) => res?.link ?? res?.result?.link ?? null;
+
+function normalizePlan(tier, p) {
+  return {
+    tier: p.tier ?? tier,
+    planSeq: p.planSeq,
+    planName: p.planName,
+    isCurrentPlan: !!p.isCurrentPlan,
+    isAccessible: p.isAccessible !== false,
+    isSwitchable: p.isSwitchable !== false,
+    priceOptions: (p.priceOptions ?? []).map((o) => ({
+      priceId: o.priceId,
+      price: o.price,
+      priceUnit: o.priceUnit,
+      billingPeriod: o.billingPeriod,
+      discountRate: o.discountRate ?? 0,
+      isCurrentPlan: !!o.isCurrentPlan,
+    })),
+  };
+}
+
+/** Recurring subscription plans for one billing period + currency, one entry per tier. */
+export async function getRecurringPlans(spaceSeq, { billingPeriod, currency }) {
+  const res = await get('/payment/api/v1/plan/groups', {
+    query: { spaceSeq, productType: 'recurring', billingPeriod, currency },
+  });
+  const groups = res?.result ?? {};
+  const plans = [];
+  for (const [tier, arr] of Object.entries(groups)) {
+    const p = Array.isArray(arr) ? arr[0] : null;
+    if (p) plans.push(normalizePlan(tier, p));
+  }
+  return plans;
+}
+
+/** The one-time credit pack (productType=single, USD). Quantity-priced: unitPrice per pack. */
+export async function getCreditProduct(spaceSeq) {
+  const res = await get('/payment/api/v1/plan', {
+    query: { spaceSeq, productType: 'single', currency: ONE_TIME_CURRENCY },
+  });
+  const p = (res?.result ?? [])[0] ?? null;
+  if (!p) return null;
+  const opt = (p.priceOptions ?? [])[0] ?? null;
+  return {
+    planSeq: p.planSeq,
+    planName: p.planName,
+    minQuantity: p.purchaseSeatCountMin ?? 1,
+    maxQuantity: p.purchaseSeatCountMax ?? -1, // -1 = unlimited
+    priceId: opt?.priceId ?? null,
+    unitPrice: opt?.price ?? null,
+    priceUnit: opt?.priceUnit ?? ONE_TIME_CURRENCY,
+    creditPerUnit: CREDIT_PER_UNIT,
+  };
+}
+
+/** Tiers strictly above `currentTier` that can be switched to (for the plan list to offer). */
+export function upgradeCandidates(plans, currentTier) {
+  const rank = tierRank(currentTier);
+  return plans.filter((p) =>
+    tierRank(p.tier) > rank && p.tier !== 'enterprise' && p.isAccessible && p.isSwitchable && !p.isCurrentPlan);
+}
+
+/** Find a tier's price option for the exact billing period (null if that tier has no option for it). */
+export function findPriceOption(plans, tier, billingPeriod) {
+  const plan = plans.find((p) => String(p.tier).toLowerCase() === String(tier).toLowerCase());
+  if (!plan) return null;
+  const opt = plan.priceOptions.find((o) => o.billingPeriod === billingPeriod);
+  return opt ? { planSeq: plan.planSeq, plan, opt } : null;
+}
+
+/** The billing period of the current subscription (billing requires the target to match it). */
+export function currentBillingPeriod(plans) {
+  for (const p of plans) {
+    const cur = p.priceOptions.find((o) => o.isCurrentPlan);
+    if (cur) return cur.billingPeriod;
+  }
+  return null;
+}
+
+/** Credit packs needed to cover a shortfall (each pack = CREDIT_PER_UNIT credits). */
+export function recommendCredits(shortfall) {
+  const quantity = Math.max(1, Math.ceil(Number(shortfall) / CREDIT_PER_UNIT));
+  return { quantity, credits: quantity * CREDIT_PER_UNIT };
+}
+
+// --- link generation (each returns a Stripe URL string) ---
+
+/** Free → new subscription. */
+export async function createCheckoutLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/checkout', {
+    body: {
+      priceId, planSeq, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** Existing subscriber → change plan (Stripe billing-portal preview; body is just these three). */
+export async function createBillingLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/billing', { body: { priceId, planSeq, spaceSeq } });
+  return extractLink(res);
+}
+
+/** Subscriber → buy N credit packs (one-time checkout, USD). */
+export async function createOneTimeLink({ spaceSeq, priceId, planSeq, quantity }) {
+  const res = await post('/payment/api/v1/charge/checkout/one-time', {
+    body: {
+      priceId, planSeq, quantity, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** PAY4052 = Stripe session creation failed — for an existing subscriber this usually means the priceId's
+ *  currency (or period) doesn't match the live subscription, so callers try the preferred currency then
+ *  fall back to the other. */
+export const isCurrencyMismatch = (err) => err instanceof PersoApiError && err.code === 'PAY4052';
+
+/** Run `fn(currency)` for the preferred currency, falling back to the other on a currency mismatch. */
+export async function withCurrencyFallback(preferred, fn) {
+  const order = preferred === 'krw' ? ['krw', 'usd'] : ['usd', 'krw'];
+  let lastErr = null;
+  for (const currency of order) {
+    try { return { currency, result: await fn(currency) }; }
+    catch (e) { if (isCurrencyMismatch(e)) { lastErr = e; continue; } throw e; }
+  }
+  throw lastErr;
+}

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;