perso-dubbing 0.2.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "name": "perso-ai",
+  "owner": {
+    "name": "Perso AI"
+  },
+  "description": "Perso AI agent plugins — AI dubbing (video voice translation with lip-sync).",
+  "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",
+      "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",
+      "license": "MIT",
+      "category": "media",
+      "keywords": ["dubbing", "video-translation", "lip-sync", "perso-ai", "media"],
+      "tags": ["dubbing", "video", "translation", "lip-sync", "audio"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "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",
+  "author": {
+    "name": "Perso Dubbing"
+  },
+  "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
+  "repository": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin",
+  "license": "MIT",
+  "keywords": ["dubbing", "video-translation", "lip-sync", "perso-ai", "media"]
+}

package/.codex-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "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.",
+  "skills": "./skills/",
+  "author": "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",
+  "license": "MIT",
+  "keywords": ["dubbing", "video-translation", "lip-sync", "perso-ai", "media"],
+  "interface": {
+    "displayName": "Perso AI Dubbing"
+  }
+}

package/.cursor-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "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.",
+  "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",
+  "license": "MIT",
+  "keywords": ["dubbing", "video-translation", "lip-sync", "perso-ai", "media"]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Perso Dubbing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,148 @@
+# 🎬 /dubbing — Perso AI Video Auto-Dubbing
+
+[![Powered by Perso AI](https://img.shields.io/badge/Powered%20by-Perso%20AI-5A4FF3)](https://perso.ai)
+![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)
+![Agent Skills](https://img.shields.io/badge/Agent%20Skills-SKILL.md-1f6feb)
+![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.
+
+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>
+
+Because every host uses the same **Agent Skills standard** (`SKILL.md`), it works identically wherever you install it — just run `/dubbing` or say *"dub this video for me."*
+
+---
+
+## Quick start (first time)
+
+1. **Create an empty folder** and open your coding agent (Claude Code · Codex · Cursor · Antigravity) in it.
+2. **Tell the agent to install the plugin** — paste this repository's URL and say *"install this"* (or run `npx perso-dubbing` yourself).
+3. **Ask it to dub a video** — e.g. *"Dub this video into English — C:\videos\clip.mp4"* (a YouTube URL or a whole folder works too). On first run it will open a key file for your Perso API key. Unless you pass `--out`, results are saved next to the source video.
+
+---
+
+## 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:
+>
+> ```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.
+
+### Claude Code (plugin marketplace — recommended)
+
+```text
+/plugin marketplace add est-perso-dubbing-agent/perso-dubbing-plugin
+/plugin install perso-dubbing@perso-ai
+```
+
+### Codex
+
+Codex reads skills from the shared Agent Skills folder. Run `npx perso-dubbing --codex`, or copy manually:
+
+```text
+~/.agents/skills/dubbing/        # personal (all repos) — current Codex
+~/.codex/skills/dubbing/         # older Codex versions (the installer writes both)
+<repo>/.agents/skills/dubbing/   # this repository only
+```
+
+The repo also ships a Codex plugin manifest (`.codex-plugin/plugin.json`) for marketplace-based installs.
+
+### Cursor
+
+Run `npx perso-dubbing --cursor`, or copy into:
+
+```text
+~/.cursor/skills/dubbing/        # global
+.cursor/skills/dubbing/          # this project only
+```
+
+The repo ships a Cursor plugin manifest (`.cursor-plugin/plugin.json`) for the Cursor plugin marketplace.
+
+### Antigravity
+
+Run `npx perso-dubbing --antigravity`, or copy into either location:
+
+```text
+~/.antigravity/skills/dubbing/   # Antigravity 1.x
+~/.agents/skills/dubbing/        # Antigravity 2.0+ (shared Agent Skills folder)
+```
+
+### ⚡ One-line installer (any host)
+
+Detects which hosts you use and installs to all of them — no clone needed:
+
+```bash
+npx perso-dubbing
+```
+
+- Specific host only: `--claude` / `--antigravity` / `--codex` / `--cursor` · all: `--all`
+- Current project only (`./.claude`, `./.agents`, …): `--project`
+
+Already have the repo cloned? `node scripts/install.mjs` from the repo root does the same without any network.
+
+### 🔧 Manual install
+
+Copy the skill folder into your host's skills directory under the name **`dubbing`**. From the repo root:
+
+```bash
+# macOS / Linux
+mkdir -p <skills_folder>/dubbing && cp -r skills/dubbing/* <skills_folder>/dubbing/
+```
+
+> 💡 Windows (PowerShell): `New-Item -ItemType Directory -Force <skills_folder>\dubbing; Copy-Item .\skills\dubbing\* <skills_folder>\dubbing\ -Recurse`
+
+After installing, type **`/dubbing`** in your agent or just say **"dub this video for me"** to run it.
+
+---
+
+## Examples
+
+The easiest way — just tell your agent:
+
+> "Dub this video into English — C:\videos\clip.mp4"
+
+You can also run the CLI directly from the repo root:
+
+```bash
+# One video (auto-detect source → English)
+npm run dub -- "clip.mp4" --target en --out result.mp4
+
+# Several languages at once (uploaded/split once, reused per language)
+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
+```
+
+*(Equivalent direct call: `node skills/dubbing/scripts/dubbing.mjs …` — or `node scripts/dubbing.mjs …` from inside an installed skill folder.)*
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| Install/run fails | Requires **Node.js 18+**. Check with `node -v`. |
+| No API key yet | Just run any dubbing command — a key file opens automatically; paste your key and save (it's encrypted and the file is deleted). Manual check: `npm run key:check`. **Do not paste the key into the chat.** → <a href="https://developers.perso.ai/api-keys" target="_blank" rel="noopener noreferrer">Get an API key</a> |
+| ffmpeg-related error | ffmpeg is normally installed automatically. If it fails, run `npm run doctor`. |
+| Stops midway (out of credits, crash, killed process) | Progress is saved to a `*.dubresume.json` state file throughout the run. Run the **`--resume "<state-file>"`** command shown in the notice to finish only the remaining parts (completed parts are skipped automatically). |
+
+---
+
+## Repository layout
+
+```text
+.claude-plugin/    Claude Code plugin + marketplace manifests
+.codex-plugin/     Codex plugin manifest
+.cursor-plugin/    Cursor plugin manifest
+skills/dubbing/    The skill itself (SKILL.md · lib/ · scripts/) — self-contained
+scripts/           Repo-level installer (install.mjs)
+```
+
+## License
+
+This skill's code is distributed under the **[MIT License](LICENSE)**. The actual dubbing is performed through the Perso Dubbing API, so API usage itself is subject to the [Perso AI Terms of Service](https://perso.ai) and pricing.

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "perso-dubbing",
+  "version": "0.2.0",
+  "description": "Perso AI video auto-dubbing agent skill (Claude Code / Codex / Cursor / Antigravity)",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "perso-dubbing": "scripts/install.mjs"
+  },
+  "files": [
+    "skills",
+    "scripts",
+    ".claude-plugin",
+    ".codex-plugin",
+    ".cursor-plugin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin.git"
+  },
+  "keywords": [
+    "agent-skills",
+    "skill",
+    "plugin",
+    "dubbing",
+    "video-translation",
+    "lip-sync",
+    "perso-ai",
+    "claude-code",
+    "codex",
+    "cursor",
+    "antigravity"
+  ],
+  "scripts": {
+    "doctor": "node skills/dubbing/scripts/check_deps.mjs",
+    "key:check": "node skills/dubbing/scripts/resolve_key.mjs --check",
+    "langs": "node skills/dubbing/scripts/languages.mjs",
+    "input": "node skills/dubbing/scripts/prepare_input.mjs",
+    "split": "node skills/dubbing/scripts/probe_split.mjs",
+    "dub": "node skills/dubbing/scripts/dubbing.mjs",
+    "install:skill": "node scripts/install.mjs"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// One-click install: copy the dubbing skill into the skills folder of every detected host.
+//   npx github:est-perso-dubbing-agent/perso-dubbing-plugin        → auto-install to hosts that have a config folder
+//   node scripts/install.mjs --all                                 → all hosts
+//   ... --claude | --antigravity | --codex | --cursor              → specific hosts only
+//   ... --project                                                  → install into the current folder (./.claude etc.)
+import { cp, mkdir, access, writeFile, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = dirname(dirname(fileURLToPath(import.meta.url))); // package root (= parent of scripts/)
+const SRC = join(ROOT, 'skills', 'dubbing'); // skill payload → installs under the name 'dubbing' (→ /dubbing)
+const ITEMS = ['SKILL.md', 'lib', 'scripts', 'agents'];
+
+const args = process.argv.slice(2);
+const baseDir = args.includes('--project') ? process.cwd() : homedir();
+
+// probes: config dirs whose presence means the host is in use. dests: skills dirs to install into.
+// '.agents/skills' is the cross-tool Agent Skills location (Codex · Antigravity 2.0 · Gemini CLI);
+// '.codex/skills' is kept for older Codex versions that only scan their own folder.
+const HOSTS = {
+  claude: { probes: ['.claude'], dests: [join('.claude', 'skills')] },
+  antigravity: { probes: ['.antigravity', '.gemini'], dests: [join('.antigravity', 'skills'), join('.agents', 'skills')] },
+  codex: { probes: ['.codex', '.agents'], dests: [join('.agents', 'skills'), join('.codex', 'skills')] },
+  cursor: { probes: ['.cursor'], dests: [join('.cursor', 'skills')] },
+};
+
+const exists = (p) => access(p).then(() => true, () => false);
+
+let targets = Object.keys(HOSTS).filter((h) => args.includes(`--${h}`));
+if (args.includes('--all')) targets = Object.keys(HOSTS);
+if (!targets.length) {
+  for (const [h, { probes }] of Object.entries(HOSTS)) {
+    for (const probe of probes) {
+      if (await exists(join(baseDir, probe))) { targets.push(h); break; }
+    }
+  }
+  if (!targets.length) targets = ['claude'];
+}
+
+// A minimal package.json goes with the copy so the worker can report its version (User-Agent) from the installed dir.
+const pkg = JSON.parse(await readFile(join(ROOT, 'package.json'), 'utf8'));
+const miniPkg = JSON.stringify({ name: pkg.name, version: pkg.version, description: pkg.description, type: 'module', license: pkg.license }, null, 2);
+
+const dests = [...new Set(targets.flatMap((h) => HOSTS[h].dests))].map((d) => join(baseDir, d, 'dubbing'));
+for (const dest of dests) {
+  await mkdir(dest, { recursive: true });
+  for (const item of ITEMS) {
+    await cp(join(SRC, item), join(dest, item), { recursive: true, force: true }).catch(() => {});
+  }
+  for (const doc of ['README.md', 'LICENSE']) {
+    await cp(join(ROOT, doc), join(dest, doc), { force: true }).catch(() => {});
+  }
+  await writeFile(join(dest, 'package.json'), miniPkg + '\n', 'utf8').catch(() => {});
+  console.log(`✅ ${dest}`);
+}
+console.log('\nInstalled! Use it in your agent with  /dubbing  or just  "dub this video for me".');

package/skills/dubbing/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: dubbing
+description: Auto-dub (voice-translate) videos into other languages, with lip-sync (Perso AI Dubbing).
+---
+
+# /dubbing
+
+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.
+
+## 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`.
+
+## 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).
+- 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.
+
+What happens while it runs (so you can explain the waiting to the user):
+
+- **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`….
+
+## 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:
+
+```
+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.
+
+**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.)
+
+## 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_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).
+
+## Advanced (debug only — not part of the normal flow)
+
+`dubbing.mjs` already does all of this internally; use these only to diagnose a problem:
+
+- `node scripts/prepare_input.mjs "<input>"` — input normalization check (prints JSON).
+- `node scripts/probe_split.mjs '<JSON|path>'` — upload-first split decision. ⚠ Performs a **real upload**; never use it as a pre-step to `dubbing.mjs`.
+- `node scripts/languages.mjs` — list supported language codes.
+- `node scripts/check_deps.mjs` — check/auto-install ffmpeg/ffprobe.

package/skills/dubbing/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Perso AI Dubbing"
+  short_description: "Auto-dub videos into other languages with lip-sync (Perso AI)."
+  default_prompt: "Dub this video into English."
+
+policy:
+  allow_implicit_invocation: true

package/skills/dubbing/lib/api_adapter.mjs

@@ -0,0 +1,226 @@
+// Perso API adapter.
+//   upload → requestTranslation → getStatus → download
+// 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 { 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';
+
+const VT = '/video-translator/api/v1';
+
+// Format rejected by both the video and audio upload endpoints → used to suggest conversion.
+export class UnsupportedMediaError extends Error {
+  constructor(fileName, cause) {
+    super(`Unsupported media format: ${fileName}`);
+    this.name = 'UnsupportedMediaError';
+    this.fileName = fileName;
+    this.cause = cause;
+  }
+}
+// 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(/\/+$/, '');
+const absolutize = (u) => {
+  if (!u) return u;
+  if (/^https?:\/\//i.test(u)) return u;
+  return MEDIA_BASE + encodeURI(u.startsWith('/') ? u : `/${u}`);
+};
+
+// ── upload ──────────────────────────────────────────────
+/** prepared({source,localPath|sourceUrl,originalName}) → { seq:mediaSeq, kind:'video'|'audio' } */
+export async function upload(prepared, spaceSeq) {
+  if (prepared.source === 'external') {
+    const r = await put('/file/api/upload/video/external', {
+      body: { space_seq: spaceSeq, url: prepared.sourceUrl },
+    });
+    return { seq: r.seq, kind: 'video' };
+  }
+  return uploadLocal(prepared.localPath, prepared.originalName, spaceSeq);
+}
+
+async function uploadLocal(localPath, fileName, spaceSeq) {
+  const name = fileName || basename(localPath);
+
+  // 1) SAS token (fileName is encoded by URLSearchParams)
+  const sas = await get('/file/api/upload/sas-token', { query: { fileName: name } });
+  const blobSasUrl = sas?.blobSasUrl;
+  if (!blobSasUrl) throw new Error('Failed to get an upload token — check your API key and permissions.');
+
+  // 2) PUT directly to Azure Blob (without XP-API-KEY).
+  //    Stream the file instead of loading it entirely into memory → safe even for files over 2GiB (the readFile limit).
+  const { size } = await stat(localPath);
+  const blobRes = await fetch(blobSasUrl, {
+    method: 'PUT',
+    headers: { 'x-ms-blob-type': 'BlockBlob', 'Content-Length': String(size) },
+    body: createReadStream(localPath),
+    duplex: 'half', // undici: required for streaming the request body
+  });
+  if (!blobRes.ok) throw new Error(`Azure upload failed (${blobRes.status})`);
+
+  // 3) Register — decide by extension first: for an audio extension, go straight to the audio endpoint (skip the unnecessary video attempt).
+  //    Otherwise (video/unknown), register as video, and if there's no video stream (F4007), fall back to audio → safe even if the extension is wrong.
+  //    If both video and audio are rejected, it's an unsupported format (UnsupportedMediaError) → the caller suggests conversion.
+  const fileUrl = blobSasUrl.split('?')[0];
+  const reg = async (k) => {
+    const r = await put(`/file/api/upload/${k}`, { body: { spaceSeq, fileUrl, fileName: name } });
+    return { seq: r.seq, kind: k };
+  };
+  // Only length/size errors (F4008/F4004) are thrown as-is so the caller can split. Other register rejections (401, audio failure after F4007, etc.)
+  // are treated as unsupported formats — if the key were wrong it would already have failed at the SAS token above, so a 401 here is not an auth problem.
+  const keep = (e) => e instanceof PersoApiError && (e.code === 'F4008' || e.code === 'F4004');
+
+  if (AUDIO_EXT.test(name)) {
+    try { return await reg('audio'); }
+    catch (e) { if (keep(e)) throw e; throw new UnsupportedMediaError(name, e); }
+  }
+  try {
+    return await reg('video');
+  } catch (e) {
+    if (keep(e)) throw e;
+    if (e instanceof PersoApiError && e.code === 'F4007') { // no video stream → try audio
+      try { return await reg('audio'); }
+      catch (e2) { if (keep(e2)) throw e2; throw new UnsupportedMediaError(name, e2); }
+    }
+    throw new UnsupportedMediaError(name, e); // not video and not F4007 → a format problem
+  }
+}
+
+// ── queue status ────────────────────────────────────────
+const _queueInited = new Set(); // initialize the queue once per space (idempotent) — shared by getQueueStatus/requestTranslation
+/** Query queue status (= the queue PUT response: usedQueueCount/maxQueueCount). Returns { used, max, available }, or null on failure. */
+export async function getQueueStatus(spaceSeq) {
+  try {
+    const r = await put(`${VT}/projects/spaces/${spaceSeq}/queue`); // PUT does both init and query
+    _queueInited.add(spaceSeq);
+    const d = r?.data ?? r?.result ?? r ?? {};
+    const max = Number(d.maxQueueCount);
+    if (!Number.isFinite(max) || max <= 0) return null;
+    const used = Number.isFinite(Number(d.usedQueueCount)) ? Number(d.usedQueueCount) : 0;
+    return { used, max, available: Math.max(0, max - used) };
+  } catch {
+    return null;
+  }
+}
+
+// ── requestTranslation ─────────────────────────────────
+/** Initialize the queue, then request translation → array of projectIds (startGenerateProjectIdList) */
+export async function requestTranslation(spaceSeq, mediaSeq, opts = {}) {
+  const {
+    source = 'auto',
+    target = 'en',
+    ttsModel = 'AUDIO_ENGINE_V3',
+    numberOfSpeakers = 1,
+    speed = 'GREEN',
+    title,
+    kind = 'video', // 'audio' means isVideoProject=false
+  } = opts;
+
+  // Initialize the queue — once per space (not on every chunk → halves the request count, eases rate limiting)
+  if (!_queueInited.has(spaceSeq)) {
+    await put(`${VT}/projects/spaces/${spaceSeq}/queue`).catch(() => {});
+    _queueInited.add(spaceSeq);
+  }
+
+  const body = {
+    mediaSeq,
+    isVideoProject: kind !== 'audio',
+    sourceLanguageCode: source,
+    targetLanguages: [{ languageCode: target, ttsModel }],
+    numberOfSpeakers,
+    preferredSpeedType: speed,
+    ...(title ? { title } : {}),
+  };
+  const res = await post(`${VT}/projects/spaces/${spaceSeq}/translate`, { 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) {
+  const p = await get(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}`);
+  const reason = p.progressReason;
+
+  if (reason === 'Completed') {
+    return { state: 'complete', progress: p.progress ?? 100, projectSeq };
+  }
+
+  if (reason === 'Failed') {
+    let message = null;
+    let noVoice = false;
+    try {
+      const pr = await get(`${VT}/projects/${projectSeq}/space/${spaceSeq}/progress`);
+      const em = pr?.result?.engineErrorMessage?.errorMessage;
+      message = em?.en || em?.ko || null;
+      // Only let 'no voice detected' through (use the original). Decide by the English message only (avoid misclassifying other engine errors).
+      noVoice = /no voice|detect any voice/i.test(em?.en ?? '');
+    } catch {
+      /* ignore failures to fetch the message */
+    }
+    return { state: 'failed', failureReason: p.failureReason ?? null, noVoice, message, projectSeq };
+  }
+
+  // State determination is based on progressReason.
+  return { state: 'processing', progress: p.progress ?? 0, progressReason: reason, projectSeq };
+}
+
+// ── cancel ─────────────────────────────────────────────
+/** Cancel an in-progress/pending project. Ignore failures (already finished or cannot be canceled). */
+export async function cancel(projectSeq, spaceSeq) {
+  try {
+    await post(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}/cancel`, { body: {} });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── 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
+  const info = await get(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}/download-info`);
+  const flags = info?.result ?? info;
+  if (isAudio) {
+    if (flags?.hasTranslatedVoice === false && flags?.hasTranslateAudio === false) {
+      throw new Error('Translated audio is not ready yet.');
+    }
+  } else if (flags?.hasTranslatedVideo === false) {
+    throw new Error('Translated video is not ready yet.');
+  }
+
+  const res = await get(`${VT}/projects/${projectSeq}/spaces/${spaceSeq}/download`, { query: { target } });
+  const r = res?.result ?? {};
+  const raw =
+    r.videoFile?.videoDownloadLink ??
+    r.audioFile?.voiceWithBackgroundAudioDownloadLink ??
+    r.zippedFileDownloadLink ??
+    null;
+  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;
+
+  if (outPath) await fetchToFile(link, outPath);
+  return { link, outPath: outPath ?? null, fileName };
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Generation is often already done (projectSeq is valid) and only the transfer fails, so retry the same link a few times (not regeneration).
+async function fetchToFile(url, outPath, attempts = 3) {
+  let lastErr;
+  for (let i = 0; i < attempts; i++) {
+    try {
+      const res = await fetch(url);
+      if (!res.ok || !res.body) throw new Error(`File download failed (${res.status})`);
+      await pipeline(Readable.fromWeb(res.body), createWriteStream(outPath));
+      return;
+    } catch (e) {
+      lastErr = e;
+      if (i < attempts - 1) await sleep(1000 * (i + 1)); // 1s, 2s backoff
+    }
+  }
+  throw lastErr;
+}