voxflow 1.14.0 → 1.15.1

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "voxflow",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "description": "AI audio content creation CLI — stories, podcasts, narration, dubbing, transcription, translation, and video translation with TTS",
   "bin": {
     "voxflow": "./dist/index.js"
   },
   "files": [
+    "bin/",
+    "lib/",
+    "skills/",
     "dist/",
     "README.md",
     "LICENSE"
@@ -14,6 +17,7 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "dependencies": {
+    "@remotion/renderer": "4.0.448",
     "open": "^10.0.0",
     "pptxgenjs": "^4.0.1"
   },
@@ -40,8 +44,9 @@
     "voxflow"
   ],
   "scripts": {
-    "build": "ncc build bin/voxflow.js -o dist --minify && rm -rf dist/cli && node scripts/check-no-asset-rewrite.js",
-    "prepublishOnly": "npm run build",
+    "build": "ncc build bin/voxflow.js -o dist --minify -e @remotion/renderer && rm -rf dist/cli && node scripts/check-no-asset-rewrite.js",
+    "build:bundle": "node scripts/build-bundle.mjs",
+    "prepublishOnly": "npm run build:bundle && npm run build",
     "lint": "eslint lib/ bin/ tests/",
     "lint:fix": "eslint lib/ bin/ tests/ --fix",
     "test": "node --test tests/*.test.js",
@@ -49,7 +54,6 @@
     "version": "node scripts/sync-plugin-versions.js && git add .claude-plugin/plugin.json .cursor-plugin/plugin.json .codex-plugin/plugin.json"
   },
   "author": "gonghaoran",
-  "license": "Apache-2.0",
   "homepage": "https://voxflow.studio",
   "repository": {
     "type": "git",
@@ -61,6 +65,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@remotion/bundler": "4.0.448",
     "@vercel/ncc": "^0.38.4",
     "eslint": "^9.39.4"
   }

package/skills/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "voxflow",
+  "description": "VoxFlow — AI voice CLI as a skill for any AI agent. Bundles 5 skills (hub, podcast, transcribe, video, slice) that drive a hosted TTS / ASR / podcast / render backend.",
+  "owner": {
+    "name": "VoxFlow",
+    "url": "https://voxflow.studio"
+  },
+  "plugins": [
+    {
+      "name": "voxflow",
+      "description": "AI voice CLI bundled as 5 skills. TTS in 200+ voices across 40+ languages, multi-speaker AI podcasts, audio/video transcription with word-level timestamps, SRT-driven dubbing, end-to-end video translation, and long-article → vertical card video reels via Remotion. Backed by a hosted TTS/ASR/LLM/render service with per-user quota (free tier 10K/mo).",
+      "category": "productivity",
+      "source": "./",
+      "homepage": "https://voxflow.studio",
+      "author": {
+        "name": "VoxFlow",
+        "url": "https://voxflow.studio"
+      }
+    }
+  ]
+}

package/skills/.claude-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "voxflow",
+  "version": "1.15.0",
+  "description": "AI voice CLI bundled as 5 skills (hub, podcast, transcribe, video, slice). Synthesize speech in 200+ voices across 40+ languages, generate multi-speaker AI podcasts, transcribe audio/video with word-level timestamps, dub videos from SRT subtitles, run end-to-end video translation, and turn long articles into vertical card video reels via Remotion. Backed by a hosted TTS/ASR/LLM/render service with per-user quota (free tier 10K/mo).",
+  "author": {
+    "name": "VoxFlow",
+    "url": "https://voxflow.studio"
+  },
+  "homepage": "https://voxflow.studio",
+  "repository": "https://github.com/VoxFlowStudio/skills",
+  "license": "MIT",
+  "keywords": [
+    "tts",
+    "voice",
+    "podcast",
+    "asr",
+    "transcription",
+    "subtitles",
+    "dubbing",
+    "video",
+    "remotion",
+    "voxflow",
+    "skill"
+  ]
+}

package/skills/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoxFlowStudio
+
+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/skills/README.md

@@ -0,0 +1,120 @@
+# VoxFlow Skills
+
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/voxflow.svg)](https://www.npmjs.com/package/voxflow)
+[![5 skills](https://img.shields.io/badge/skills-5-purple.svg)](#what-you-get)
+[![Works with](https://img.shields.io/badge/works%20with-Claude%20Code%20%C2%B7%20Cursor%20%C2%B7%20Codex%20%C2%B7%20Gemini-orange.svg)](#install)
+
+![VoxFlow CLI demo](https://github.com/VoxFlowStudio/skills/raw/main/demo.gif)
+
+Voice in your AI workflow. Five skills that let any AI coding agent (Claude Code · Cursor · Codex · Gemini CLI · Cline) speak in 200+ voices, generate podcasts, dub videos, and transcribe audio — through one CLI.
+
+**Why VoxFlow over a raw TTS API?** One CLI handles auth, voice search, multi-speaker dialogue, video pipelines, and quota. The skills layer makes it native to whichever agent you're already using — no new context-switch.
+
+## Install
+
+The simplest path — let the VoxFlow CLI auto-detect your agent and run the right command:
+
+```bash
+npm install -g voxflow
+voxflow skills install
+```
+
+It detects Claude Code / Cursor / Codex / Gemini / WorkBuddy / OpenClaw on your `$PATH`, picks the right install command, asks for confirmation, runs it, and prints next steps. Use `--all` to install for every detected agent, or `--for <agent>` to force one.
+
+If you'd rather run the install command directly — **one command for every agent**:
+
+```bash
+npx -y skills add VoxFlowStudio/skills --all --yes --global
+```
+
+The `skills` npm package detects every AI agent on your machine (Claude Code,
+Cursor, Codex CLI, Gemini CLI, Cline, Amp, Antigravity, CodeBuddy, OpenClaw…)
+and writes the 5 VoxFlow skills (`hub`, `podcast`, `transcribe`, `video`,
+`slice`) to each agent's standard skill location in a single shot.
+
+## Prerequisites
+
+```bash
+npm install -g voxflow
+voxflow login          # one-time browser auth
+```
+
+## What You Get
+
+Five focused skills, each loaded on demand:
+
+| Skill | Invoked as | What it covers |
+|-------|-----------|----------------|
+| **hub** | `voxflow:hub` | `say` · `narrate` · `story` · `voices` · auth · quota · feedback |
+| **podcast** | `voxflow:podcast` | Multi-speaker AI podcast from topic / URL / script |
+| **transcribe** | `voxflow:transcribe` | `asr` · `asr-jobs` · `translate` · `dub` · `video-translate` · `summarize` · `publish` |
+| **video** | `voxflow:video` | `picstory` · `present` · `slides` · `explain` · `image` |
+| **slice** | `voxflow:slice` | Article → vertical card video (1080×1920); 6 themes: paper / editorial / poster / Notion / brutalist / glass |
+
+Use the hub skill as the starting point — it routes to the others automatically.
+
+## Example Interactions
+
+| You say | Agent runs |
+|---------|-----------|
+| "Read this README out loud" | `voxflow narrate README.md -o readme.mp3` |
+| "Make a 5-min podcast on AI agents" | `voxflow podcast "AI agents" --length short` |
+| "Dub this tutorial into Japanese" | `voxflow video-translate tutorial.mp4 --to ja` |
+| "把这段话合成语音" | `voxflow say "..." -o output.mp3` |
+| "生成一个 AI 播客" | `voxflow podcast "topic" --length medium` |
+| "把这个视频翻译成日语" | `voxflow video-translate video.mp4 --to ja` |
+| "转录这段录音" | `voxflow asr recording.mp3` |
+| "做一个 AI 知识短视频" | `voxflow picstory "topic" --style sketchnote` |
+| "生成一套演示幻灯片" | `voxflow slides "topic" --slides 8` |
+
+## Skills Layout
+
+```text
+voxflow/
+  hub/SKILL.md          # TTS, voice search, auth, quota, feedback
+  podcast/SKILL.md      # AI dialogue podcast
+  transcribe/SKILL.md   # ASR, translation, dubbing
+  video/SKILL.md        # AI short video, slides, images
+  slice/SKILL.md        # Article → vertical card video (6 themes)
+```
+
+## Registry
+
+```text
+registry.json           # VoxFlow CLI add-on recipes index
+voxflow/
+  dub-anime-jp-zh/      # Anime fan-dub voice preset (JP→ZH)
+```
+
+Install a recipe:
+```bash
+voxflow add dub-anime-jp-zh
+```
+
+## Quota
+
+Free tier: 10,000 / month. Check before large jobs:
+
+```bash
+voxflow status
+```
+
+| Operation | Cost |
+|-----------|------|
+| `say` (1 call) | ~100 |
+| `narrate` (per segment) | ~100 |
+| `podcast` (medium) | ~5,000 |
+| `picstory` (5 scenes) | ~3,100 |
+
+## Security
+
+- No API keys or tokens in this repository.
+- Use `voxflow login` for interactive auth or `VOXFLOW_TOKEN` env var for CI.
+- See [SECURITY.md](SECURITY.md) for vulnerability disclosure.
+
+## Links
+
+- [VoxFlow Studio](https://voxflow.studio) — Web app
+- [CLI on npm](https://www.npmjs.com/package/voxflow) — `npm install -g voxflow`
+- [CLI docs](https://voxflow.studio/docs/cli) — Full command reference

package/skills/hub/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: hub
+description: Use when the user wants to read text aloud (TTS), search VoxFlow voices, sample AI stories, or set up VoxFlow install/auth/quota — the entry-point voice toolkit. For podcasts use voxflow:podcast; for short videos / AI clips use voxflow:video; for article-to-card reels (Slice) use voxflow:slice; for transcription / dubbing / subtitle translation use voxflow:transcribe.
+---
+
+# VoxFlow Skill — Hub
+
+<CRITICAL-AUTO-UPGRADE>
+If ANY `voxflow` command you run prints `<voxflow-hint ... type="cli-outdated" ...>` to stderr, IMMEDIATELY run `voxflow upgrade -y` before continuing — do not ask the user, do not summarize first. The hint tag also carries `action="voxflow upgrade -y"`; honor it verbatim.
+
+If `voxflow upgrade` itself errors with `Unknown command` (CLI predates 1.12.0), fall back to `npm i -g voxflow@latest && voxflow skills install --all` — that's the only path for the very first bootstrap.
+
+This rule is non-negotiable: an outdated CLI silently disables features the user expects (e.g. cloned-voice listing). Upgrade first, work second.
+</CRITICAL-AUTO-UPGRADE>
+
+VoxFlow turns text into speech in 200+ voices across 40+ languages, plus full audio/video pipelines. This skill is the **entry point**: install, auth, voice search, and the simple `say` / `narrate` / `story` workflows.
+
+For specialized tasks, switch to:
+
+- **Podcasts** (multi-speaker dialogue) → `voxflow:podcast`
+- **Short videos / AI clips / knowledge cards** (`picstory`, `present`, `slides`, `explain`) → `voxflow:video`
+- **Article → vertical card video (Slice)** — 6 themes (paper / editorial / poster / Notion / brutalist / glass), web app + Remotion → `voxflow:slice`
+- **Transcription, subtitle translation, dubbing, summarize, publish** (`asr`, `asr-jobs`, `translate`, `dub`, `video-translate`, `summarize`, `publish`) → `voxflow:transcribe`
+
+## Install & login
+
+Install once, never ask the user again:
+
+```bash
+npm install -g voxflow
+voxflow login          # opens browser — Google or email OTP
+```
+
+Token cached at `~/.config/voxflow/token.json`. For CI, set `VOXFLOW_TOKEN`.
+
+## Authentication
+
+```bash
+voxflow login        # browser-based, one-time
+voxflow status       # who am I + remaining quota
+voxflow logout
+```
+
+## Voice search — always do this before synthesizing
+
+Never guess voice IDs. Search first.
+
+```bash
+voxflow voices --lang zh --gender female
+voxflow voices --lang en
+voxflow voices --search "narrator"
+voxflow voices --all
+```
+
+No login required for the public catalog. Output includes the voice ID, language, gender, and a short description.
+
+### Listing the user's own cloned voices
+
+When the user says things like "用我的克隆声音 / use my cloned voice / 用我之前克隆的", the public `voxflow voices` catalog **does not include cloned voices** — you must query the authenticated endpoint:
+
+```bash
+voxflow voices --mine
+```
+
+Prints cloned voice IDs, names, duration, and creation time (requires login). Always run this **before** concluding the user has no cloned voice — the web UI "我的声音" tab and `--mine` are the only sources of truth.
+
+### Popular voice IDs (sane defaults)
+
+| ID | Style | Language |
+|----|-------|----------|
+| `v-female-R2s4N9qJ` | 温柔姐姐 (gentle female) | zh |
+| `v-male-s5NqE0rZ` | 自然男声 (natural male) | zh |
+| `v-male-Bk7vD3xP` | 威严霸总 (authoritative male) | zh |
+| `v-female-m1KpW7zE` | 傲娇学姐 (sassy female) | zh |
+| `v-female-T8m4WxP7` | Chenwen (native English female) | en |
+
+## Voice cloning (`clone`)
+
+Clone a voice from a local audio file (30s+, wav/mp3). Returns a permanent voice ID usable in all commands.
+
+```bash
+voxflow clone --input recording.wav --name "My Voice"
+# → Voice cloned successfully!
+# → Voice ID: My_Voice_xxxxx_01
+```
+
+No file? Opens the web UI for browser-based recording:
+
+```bash
+voxflow clone
+# → Opens https://www.voxflow.studio/app#voice-clone
+```
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--input <file>` | (none) | Audio file to clone from. Without this, opens web UI |
+| `--name <name>` | filename | Human-readable voice name (1-50 chars) |
+
+Tips:
+- Quiet room, normal speaking pace, no background music → best results
+- 60 seconds is optimal; 30s minimum
+- Don't "perform" — natural speech clones better than broadcast voice
+
+After cloning, use the voice ID anywhere: `--voice <id>`
+
+## Text-to-speech (`say` / `synthesize`)
+
+The atomic command. One snippet → one audio file.
+
+```bash
+voxflow say "你好世界" -o hello.mp3
+voxflow say "Hello world" --voice v-female-T8m4WxP7 -o greeting.mp3
+voxflow say "慢速朗读" --speed 0.8 -o slow.mp3
+voxflow say "高质量音频" --format wav -o output.wav
+```
+
+| Flag | Default | Range / Values |
+|------|---------|----------------|
+| `--voice <id>` | `v-female-R2s4N9qJ` | any voice ID from `voxflow voices` |
+| `--format <fmt>` | `pcm` | `pcm` (WAV), `wav`, `mp3` |
+| `--speed <n>` | `1.0` | `0.5` – `2.0` |
+| `--volume <n>` | `1.0` | `0.1` – `2.0` |
+| `--pitch <n>` | `0` | `-12` – `12` |
+| `--output <path>` | auto-named | any writable path |
+
+After synthesis, auto-play: `open output.mp3` (macOS).
+
+## Long text (`narrate`)
+
+Split a document or long string into sentences, synthesize each, concat into one file.
+
+```bash
+voxflow narrate --input article.txt -o narration.wav
+voxflow narrate --input readme.md --voice v-male-Bk7vD3xP -o readme_audio.wav
+voxflow narrate --text "第一段。第二段。第三段。" -o paragraphs.mp3
+echo "Hello world" | voxflow narrate -o hello.wav
+```
+
+Best for: long documents, articles, README files, email newsletters.
+
+Markdown is stripped automatically (headings, links, code fences, etc.) — no need to clean it first.
+
+## AI story (`story`)
+
+LLM writes a short story on the topic, then narrates it.
+
+```bash
+voxflow story "一只会飞的小猫" -o story.mp3
+voxflow story "space adventure" --lang en -o adventure.wav
+```
+
+Best for: bedtime stories, content samples, demos.
+
+## Quota
+
+Free tier: 10,000 quota / month (resets monthly). Bonus pool from invitations never expires.
+
+| Operation | Cost |
+|-----------|------|
+| 1 TTS call (`say`) | ~50 |
+| `narrate` | ~50 per segment |
+| `story` (short) | ~350-1000 |
+| `podcast` (medium) | ~2,800 (2K script + ~16 × 50 TTS) |
+| `picstory` 5-scene | ~2,850 |
+
+Always check before expensive operations:
+
+```bash
+voxflow status
+```
+
+## Common scenarios
+
+### "把这段话念出来"
+```bash
+voxflow say "用户输入的文字" -o /tmp/out.mp3 && open /tmp/out.mp3
+```
+
+### "用温柔女声读这个文件"
+```bash
+voxflow voices --lang zh --gender female
+voxflow narrate --input file.txt --voice v-female-R2s4N9qJ -o /tmp/narration.mp3
+```
+
+### "讲个睡前故事"
+```bash
+voxflow story "小狐狸的星星种子" --lang zh -o /tmp/bedtime.mp3 && open /tmp/bedtime.mp3
+```
+
+### "多语言朗读"
+```bash
+voxflow voices --lang en --gender female   # pick English voice
+voxflow voices --lang ja --gender female   # pick Japanese voice
+voxflow say "English text" --voice <en_id> -o /tmp/en.mp3
+voxflow say "日本語テキスト" --voice <ja_id> -o /tmp/ja.mp3
+```
+
+## Creative workflows (combine TTS with the agent's writing)
+
+The agent writes content first, then synthesizes each part with `say` or `narrate`.
+
+### Audio storybook (有声绘本)
+
+1. Write a 6-page children's story.
+2. For each page: generate inline SVG illustration (400×300).
+3. `voxflow say "page text" --voice v-female-R2s4N9qJ --speed 0.85 -o /tmp/page_N.mp3`
+4. Read mp3 files, base64-encode, embed inline in HTML.
+5. Output a single self-contained HTML file with audio play buttons per page.
+6. `open /tmp/storybook.html`
+
+### Article → audio briefing
+
+```bash
+# Agent fetches the URL, summarizes, then:
+voxflow say "summary text" --voice v-male-s5NqE0rZ -o /tmp/briefing.mp3
+```
+
+### Document narration
+
+```bash
+voxflow narrate --input README.md --voice v-female-R2s4N9qJ --speed 0.9 -o /tmp/readme.mp3
+```
+
+### Git daily report audio
+
+1. `git log --oneline --since="1 day ago"`
+2. Agent summarizes.
+3. `voxflow say "today's summary..." -o /tmp/daily.mp3`
+
+### Mock interview
+
+1. Agent generates 3 interview questions on the topic.
+2. For each: `voxflow say "question N..." --voice v-male-Bk7vD3xP -o /tmp/q_N.mp3`
+3. Play sequentially.
+
+## Prerequisites
+
+- **Node.js** `^20.19.0 || >=22.12.0`
+- **voxflow CLI ≥ 1.12.0** (for `voxflow voices --mine` — lists the user's cloned voices)
+- **ffmpeg** — only for video-related commands (see `voxflow:video`, `voxflow:transcribe`)
+- **Login** required for any API call — `voxflow login`
+
+### How the auto-upgrade signal works
+
+The CLI itself emits `<voxflow-hint type="cli-outdated" ...>` on stderr whenever a newer version is on npm. The top-of-skill `<CRITICAL-AUTO-UPGRADE>` rule already covers what to do — this section is just the reference for what the tag looks like:
+
+```
+<voxflow-hint v="1" type="cli-outdated" current="1.10.21" latest="1.13.0" action="voxflow upgrade -y" />
+```
+
+Emitted at most once per 24h (cached in `~/.config/voxflow/update-check.json`). Opt out for users who don't want the check: `VOXFLOW_NO_UPDATE_CHECK=1` (or `NO_UPDATE_NOTIFIER=1`, the industry-standard env).
+
+You can also poll explicitly with `voxflow upgrade --check` (no side effects) if the user is on a known-old version and you want to verify before kicking off expensive work.
+
+## Feedback & support (AI can do this automatically)
+
+When a voxflow command fails or the user asks to report a problem, **you (the AI agent) should file the issue directly** — don't ask the user to do it manually.
+
+### AI workflow
+
+```bash
+# Submit directly — no browser, no TTY required.
+# Uses `gh` CLI if available (direct GitHub issue creation).
+# Falls back to printing the pre-filled URL if gh is not installed.
+voxflow feedback --bug \
+  --title "asr crashes on 2-hour wav files" \
+  --body "Error: timeout after 30s\n\nCommand: voxflow asr long.wav\nExpected: transcript\nActual: Fatal error: request timeout"
+# stdout → the created GitHub issue URL  (or a pre-filled URL if gh is not installed)
+```
+
+System info (CLI version, OS, Node) is appended to the body automatically.
+
+### Flags
+
+| Flag | Description |
+|---|---|
+| `--bug` / `--feature` / `--general` | Issue type |
+| `--title <text>` | Title — triggers non-interactive mode |
+| `--body <text>` | Description body |
+| `--print-url` | Force URL output instead of submitting (even if gh is available) |
+
+### User-initiated (interactive)
+
+```bash
+voxflow feedback          # interactive prompts → submit via gh or browser
+voxflow feedback --bug    # skip type prompt, rest is interactive
+```
+
+### When to file automatically
+
+- Any CLI command exits with a fatal/unexpected error → offer to file a bug
+- User says "这个不好用" / "report this" / "提个 issue" → call with `--title` and submit directly
+
+## Installing third-party voices or templates (`add`)
+
+```bash
+voxflow add <recipe-name>                  # install a voice preset or pipeline template
+voxflow add --list                         # browse available recipes
+voxflow add chico/my-recipe --force        # install from a custom author namespace
+```
+
+Use this when the user asks to install a specific named recipe (e.g. `dub-anime-jp-zh`). The registry is currently limited — if `--list` returns 404, the recipe may need to be referenced by full URL or the registry is not yet public.
+
+## Rules
+
+1. **Search voices before use** — never invent voice IDs. Always run `voxflow voices` first.
+2. **Check quota** before podcasts (~5K), picstory (~3K), or batched jobs: `voxflow status`.
+3. **Auto-play** after synthesis: `open output.mp3` (macOS) / `xdg-open` (Linux).
+4. **Never print tokens or secrets** to logs.
+5. If a command fails, run `voxflow <cmd> --help` to confirm flags before retry.
+
+## When to switch skills
+
+- User says "podcast" / "对话" / "多人对谈" → load `voxflow:podcast`.
+- User says "short video" / "知识卡片" / "小红书" / "TikTok" / "AI clip" / "render" → load `voxflow:video`.
+- User says "Slice" / "切片视频" / "文章转视频" / "PaperSlide" / "paperslide" / "paper-slide" (legacy) / "纸面手绘风" / "文章转知识短视频" / "知乎长文转视频" / "公众号转视频" → load `voxflow:slice`.
+- User says "transcribe" / "字幕" / "dub" / "translate this video" / "SRT" → load `voxflow:transcribe`.