voxflow 1.14.0 → 1.15.1

package/skills/slice/references/themes.md

@@ -0,0 +1,172 @@
+# Slice Themes
+
+The Slice product (`voxflow.studio/apps/slice`) ships 13 visual themes. Same deck JSON, thirteen different looks. Pick by platform fit and content mood — not by content topic.
+
+## Quick Picker
+
+| Theme id | Label | Platform fit | Pick when… |
+|---|---|---|---|
+| `paper-slide` | 纸面 | 抖音 · 视频号 · 小红书 | Knowledge / management / investing / psychology / philosophy. Content needs "stop and think for a beat". |
+| `editorial-mag` | 编辑刊 | 知乎 · 公众号 · LinkedIn | Long commentary, policy analysis, profile features, deep industry reports. Wants Atlantic / NYT-magazine credibility. |
+| `bold-poster` | 大字海报 | X · Threads · LinkedIn | One-line takes, investing calls, product judgments, controversial claims, data flashes. The scroll has to stop. |
+| `notion-card` | Notion 卡 | 公众号 · 飞书 · 知识星球 | Methodology notes, SOPs, knowledge-base teardowns, product retros, tutorial roundups. Looks like serious notes. |
+| `brutalist` | 粗野 | X · Mastodon · 独立播客 | Hard takes, tech critiques, podcast episode posters, culture commentary, contrarian positions. Refuses polish. |
+| `glass-dark` | 玻璃夜 | 抖音 · 视频号 · TikTok | AI / tech, future narratives, night-mood content, cinematic interviews, gaming / digital. OLED-first. |
+| `editorial-stencil` | 编辑·海报 | LinkedIn · 知乎 · 公众号 | Agency-pitch posters, brand keynote notes, opinion essays that want letterbox cinema feel + dual-tone heavy display. |
+| `broadsheet` | 财经刊 | LinkedIn · 知乎 · 雪球 | Market commentary, macro analysis, earnings teardowns, fund-manager letters. FT salmon paper + drop-cap = automatic finance credibility. |
+| `blueprint` | 蓝晒图 | 少数派 · 知乎 · GitHub | Engineering / architecture explainers, system design teardowns, dev tooling reviews. Cyan grid + orange dimension marks = "this is a spec, not a vibe". |
+| `daisy-pastel` | 雏菊 | 小红书 · 微博 · 即刻 | Lifestyle, self-care, journaling, soft-skill posts, anything that wants to feel hand-drawn and approachable. Cream + pink + tiny stars. |
+| `showa-catalog` | 昭和目录 | 小红书 · B 站 · 播客 | 70s city-pop nostalgia, music recs, retro book reviews, podcast covers, weekend essays. Rainbow stripes + sun stamp. |
+| `photo-feature` | 摄影刊 | 小红书 · 知乎 · 微博 | Travel diaries, place-based reportage, photography commentary, scene-setting pieces. **Needs `imageUrl` per card** — falls back to SVG stub when missing (plumbing pending). |
+| `atmospheric` | 深夜刊 | 微博 · 即刻 · 播客 | Late-night essays, romantic prose, mood pieces, podcast teasers. Black ground + a single warm spotlight + pink serif italic. |
+
+## Theme Details
+
+### `paper-slide` — 纸面
+
+**Visual signature**: Aged paper texture · serif red headlines · hand-drawn vermilion stamps. Reads halfway between "reading-notebook" and "old-newspaper column" — knowledge feel, trust feel.
+
+**Why it works on 抖音 / 视频号 / 小红书**: Algos no longer reward static text cards, but narrated paper-card video with paged TTS rhythm still ships. Measured completion rate ~30% above pure-subtitle version.
+
+**Good for**: 管理学拆解 · 投资札记 · 心理科普 · 人物访谈节选 · 读书笔记 · 原创随笔
+
+**Skip for**: Pure entertainment / fast hooks — pick `bold-poster` or `brutalist` instead.
+
+### `editorial-mag` — 编辑刊
+
+**Visual signature**: Cream page · serif italic pulls · magazine-grade whitespace · thin column rules · restrained horizontal dividers. Lifted from The Atlantic / The New Yorker / NYT Magazine.
+
+**Why it works on 知乎 / 公众号 / LinkedIn Pulse**: Both algos and readers favour "serious, restrained, professional" layout. Magazine vibe is automatic credibility.
+
+**Good for**: 商业评论 · 政策解读 · 人物特稿 · 行业深度报告 · 长篇书评 · 专栏文章
+
+**Skip for**: Fast hooks / clickbait — `bold-poster` or `glass-dark` will pop more.
+
+### `bold-poster` — 大字海报
+
+**Visual signature**: Left-edge accent block · heavy bold display · oversized numerals as anchors. Page weight is pinned to 1–2 sentence takes — read in one beat, retweet in the next.
+
+**Why it works on X / Threads / LinkedIn**: Slide-feeds don't pause longer than a second. Fewer chars carrying heavier judgement = "stop-and-screenshot" energy. Poster is the natural shape.
+
+**Good for**: 投资观点 · 产品判断 · 一句话洞察 · 数据快报 · 争议论断 · 行业预测
+
+**Skip for**: Long step-by-step reasoning — pick `editorial-mag` or `paper-slide`.
+
+### `notion-card` — Notion 卡
+
+**Visual signature**: Pure white background · warm-grey ink · blue accent rule · top-left page-icon. Lifted directly from Notion document layout: 64px grid, Notion warm-grey body, Notion blue.
+
+**Why it works on 公众号 / 飞书 / 知识星球**: Audiences in "professional knowledge community" surfaces already read Notion-style as "this is real, structured notes". Conversion lift comes free.
+
+**Good for**: 方法论笔记 · SOP 文档 · 知识体系拆解 · 产品复盘 · 教程总结 · Toolkit 推荐
+
+**Skip for**: Emotional / viral-pace content — pick `paper-slide` or `glass-dark`.
+
+### `brutalist` — 粗野主义
+
+**Visual signature**: Pure black/white · 6px hard borders · NO.NN black labels · raw display type. Sourced from 90s zine covers + indie-podcast posters. Refuses to flatter.
+
+**Why it works on X / Mastodon / 独立播客**: Audiences are saturated on polished mini-cards. "Refuses to look produced" pops harder in the feed — recognition factor an order of magnitude over cute aesthetic.
+
+**Good for**: 硬核观点 · 技术批判 · 播客海报 · 文化评论 · 独立宣言 · 争议立场
+
+**Skip for**: Warm / commercial pitches — pick `glass-dark` or `editorial-mag`.
+
+### `glass-dark` — 玻璃夜
+
+**Visual signature**: Deep purple-to-blue gradient · twin radial purple glows · half-transparent glassmorphism icon blocks · purple text-shadow glow. Looks like it was generated inside your phone's dark mode.
+
+**Why it works on 抖音 / TikTok / 视频号**: Visual weight of dark content on OLED screens is markedly higher than light content; glass-dark naturally outweighs in the feed — especially during nighttime peak.
+
+**Good for**: AI / 科技 · 未来叙事 · 夜间情绪 · 电影感人物 · 游戏 / 数字 · 深夜散文
+
+**Skip for**: Policy / education tone — pick `editorial-mag` or `notion-card`.
+
+### `editorial-stencil` — 编辑·海报
+
+**Visual signature**: Cream base bracketed by black letterbox bars · dual-tone heavy display (one word in accent, the rest in ink) · Roman-numeral dateline · agency-pitch poster geometry.
+
+**Why it works on LinkedIn / 知乎 / 公众号**: Reads as "agency keynote / brand manifesto" rather than "social card" — pops in professional feeds without resorting to clickbait weight.
+
+**Good for**: 品牌发布 · 主题演讲笔记 · 观点海报 · 战略复盘 · 行业宣言
+
+**Skip for**: Casual journaling — pick `daisy-pastel` or `paper-slide`.
+
+### `broadsheet` — 财经刊
+
+**Visual signature**: FT salmon paper · heavy serif headlines · drop-cap first letter · red DATELINE tag · column rule. Lifted from Financial Times / Economist front pages.
+
+**Why it works on LinkedIn / 知乎 / 雪球**: Finance audiences already read salmon paper as "real markets writing". Drop-cap + dateline buy ~5 seconds of attention before the reader decides if the take is worth reading.
+
+**Good for**: 市场评论 · 宏观分析 · 财报拆解 · 基金经理信 · 行业观察
+
+**Skip for**: Fast viral hooks — pick `bold-poster` or `brutalist`.
+
+### `blueprint` — 蓝晒图
+
+**Visual signature**: Cyan engineering-blue ground · white grid overlay · orange dimension labels · annotation-style callouts. Looks like a printed blueprint.
+
+**Why it works on 少数派 / 知乎 / GitHub**: Dev / engineering audiences read blueprint as "this is a spec, not a vibe". Lets technical content arrive without the usual SaaS-aesthetic overhead.
+
+**Good for**: 系统设计 · 架构图说明 · 工具拆解 · 开发流程 · 工程笔记
+
+**Skip for**: Emotional or narrative content — pick `atmospheric` or `editorial-mag`.
+
+### `daisy-pastel` — 雏菊
+
+**Visual signature**: Cream ground · hand-drawn daisies + tiny stars · soft pink accent · rounded display type. Reads as journal / sticker book.
+
+**Why it works on 小红书 / 微博 / 即刻**: Lifestyle / self-care feeds reward hand-made warmth. Stickers + cream + pink registers as "real human wrote this" before the first character is read.
+
+**Good for**: 生活方式 · 自我成长 · 手帐分享 · 软话题 · 暖心小记
+
+**Skip for**: Finance / engineering — pick `broadsheet` or `blueprint`.
+
+### `showa-catalog` — 昭和目录
+
+**Visual signature**: 70s city-pop palette · colored circle stacks · rainbow diagonal stripes · sun stamp · retro catalog typography. Closer to a Showa-era record-shop flyer than a slide.
+
+**Why it works on 小红书 / B 站 / 播客**: Nostalgia spike is its own algorithm-friendly hook. Music / book / podcast recs land warmer here than on any "professional" theme.
+
+**Good for**: 音乐推荐 · 书单 · 怀旧随笔 · 播客封面 · 周末长文
+
+**Skip for**: Hard news / policy — pick `editorial-mag` or `broadsheet`.
+
+### `photo-feature` — 摄影刊
+
+**Visual signature**: Full-bleed photograph backdrop · gradient overlay anchoring the bottom · heavy serif title · travel-magazine pacing.
+
+**Why it works on 小红书 / 知乎 / 微博**: Photo-led posts already win in lifestyle / travel verticals. Slice's job is to add a narrated card rhythm without losing the photograph's weight.
+
+**Good for**: 旅行游记 · 在地报道 · 摄影评论 · 场景描写 · 城市观察
+
+**Limitation (current)**: The renderer reads `card.imageUrl` for the backdrop image; until the plumbing for per-card photo upload ships, missing `imageUrl` falls back to a generic SVG stub. Use `paper-slide` or `editorial-mag` if you cannot supply photographs.
+
+**Skip for**: Pure text takes — the theme leans on the image; weak photos make the layout feel empty.
+
+### `atmospheric` — 深夜刊
+
+**Visual signature**: Black ground · one warm-light cone from the top · pink serif italic title · late-night essay restraint. Looks like a single page lit by a desk lamp.
+
+**Why it works on 微博 / 即刻 / 播客**: Late-night reading windows reward mood over information density. Atmospheric concedes the "loud feed" lane and rewards the lurkers scrolling at 1 a.m.
+
+**Good for**: 深夜随笔 · 情感长文 · 朗读节选 · 文学摘录 · 播客预告
+
+**Skip for**: Daytime / data-heavy content — pick `bold-poster` or `notion-card`.
+
+## How To Pass Theme To The Renderer
+
+The deck JSON is theme-agnostic. The theme is a separate field at the top level of the render request:
+
+```json
+{
+  "theme": "editorial-mag",
+  "header": "...",
+  "seriesTitle": "...",
+  "cards": [ /* same shape regardless of theme */ ]
+}
+```
+
+Valid `theme` ids: `paper-slide` · `editorial-mag` · `bold-poster` · `notion-card` · `brutalist` · `glass-dark` · `editorial-stencil` · `broadsheet` · `blueprint` · `daisy-pastel` · `showa-catalog` · `photo-feature` · `atmospheric`. Default: `paper-slide`.
+
+The 13-theme dispatcher only runs on the Slice cloud renderer (the web app). CLI `voxflow present` / `picstory` use a different scheme set — see SKILL.md → "CLI Approximation Route" for the closest CLI scheme per theme.

package/skills/transcribe/SKILL.md

@@ -0,0 +1,473 @@
+---
+name: transcribe
+description: Use when the user wants to transcribe audio/video (including 30-min+ files with word-level timestamps via Azure Batch), translate subtitles, dub a video from SRT, run end-to-end video translation, summarize spoken content, or publish a finished translated video for Skill/agent orchestration. Covers asr, asr-jobs, translate, dub, video-translate, summarize, and publish CLI commands.
+---
+
+# VoxFlow Transcribe / Dub / Translate Skill
+
+Audio/video → text → other languages → re-voiced video. Five tightly-related commands:
+
+| Command | What it does | Output |
+|---|---|---|
+| `asr` (alias `transcribe`) | Audio/video → text. Cloud (Tencent), local (Whisper), or **Azure Batch** for 30-min+ files. | SRT / TXT / JSON |
+| `asr-jobs` | Browse, inspect, cancel, or download long-running Azure jobs | list / show / cancel / download |
+| `translate` | Translate SRT / text / file | SRT / TXT |
+| `dub` | SRT → timeline-aligned TTS, optionally merged into video | WAV / MP4 |
+| `video-translate` | End-to-end: ASR → translate → dub → merge MP4 | MP4 in target language |
+| `summarize` | Audio/video/text → summary slides (PPTX, optional video) | PPTX / MP4 |
+
+## Prerequisites
+
+- `npm install -g voxflow` and `voxflow login`
+- `ffmpeg` installed (`brew install ffmpeg` / `sudo apt install ffmpeg`) — required for `dub --video`, `video-translate`, audio extraction
+- Optional: `whisper.cpp` for local engine (no quota cost). Install via `brew install whisper-cpp` or compile from source.
+- Optional: `sox` / `rec` for `--mic` recording.
+
+---
+
+## 🎙 asr — speech recognition
+
+Transcribe a local file, remote URL, or live mic input. Cloud (Tencent ASR) or local (Whisper).
+
+### Quick start
+
+```bash
+voxflow asr --input recording.mp3                                        # default cloud, zh
+voxflow asr --input meeting.wav --speakers --speaker-number 3            # speaker diarization
+voxflow asr --input video.mp4 --format srt --lang 16k_zh -o out.srt     # video → SRT
+voxflow asr --input recording.mp3 --engine local --model small           # offline Whisper
+voxflow asr --url https://example.com/audio.mp3                          # remote URL
+voxflow asr --mic --lang 16k_en                                          # live mic
+```
+
+### Engines
+
+| `--engine` | Backend | Cost | When |
+|---|---|---|---|
+| `auto` *(default)* | Whisper local if installed, else Tencent cloud | API or free | Default |
+| `cloud` | Tencent ASR | per call | ≤2-hour files, fast turnaround |
+| `local` | whisper.cpp | Free | No quota, offline, slower |
+| `azure` | **Azure Speech Batch (R2-uploaded)** | 150 / min, ceil to next minute | **30-min+ recordings, word-level timestamps, speaker diarization, multi-locale auto-detect** |
+
+#### Azure path (durable jobs)
+
+The `azure` engine is the right choice when a file would time out on Tencent's flash mode (anything over ~2 hours, or anything you want word-level timestamps on). The CLI:
+
+1. Probes duration with `ffprobe`.
+2. Extracts to 16 kHz mono WAV with `ffmpeg` to save uplink bandwidth (falls through to original file if `ffmpeg` is missing).
+3. Uploads to Cloudflare R2 via backend-signed URLs (multipart for files >100 MiB).
+4. Creates an `asr_jobs` row server-side, charges quota (per audio minute, see below), submits to Azure.
+5. Polls the backend until terminal state.
+
+**Ctrl+C is safe** — the server-side job keeps running and `~/.config/voxflow/jobs/asr-<jobId>.json` lets you resume later via `--job-id <uuid>` or `voxflow asr-jobs show <jobId>`. Quota is automatically refunded on failure or cancel.
+
+```bash
+# 30-min Japanese meeting with speaker diarization → word-timed SRT
+voxflow asr --input meeting-2h.mp4 --engine azure --lang ja-JP --diarize --speaker-number 4 --format srt
+
+# Auto-detect language across the four Azure default candidates (en/zh/ja/ko)
+voxflow asr --input multilang.mp3 --engine azure --lang auto
+
+# Resume a job after closing the terminal
+voxflow asr --engine azure --job-id 6f3c2798-87bf-4367-bb4c-08b872e12bef
+```
+
+> **Language codes**: Azure uses BCP-47 (`ja-JP`, `zh-CN`, `en-US`, `ko-KR`). Tencent codes (`16k_zh`, `16k_ja`, …) are auto-mapped, so you can keep `--lang 16k_zh` working across engines.
+
+### Modes (cloud only)
+
+| `--mode` | Use |
+|---|---|
+| `auto` *(default)* | Picks based on duration |
+| `sentence` | <60s clips, lowest latency |
+| `flash` | 1-min to ~30 min, fast batch |
+| `file` | Long files, async with polling, supports diarization |
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--input <file>` / `--url <url>` / `--mic` | one required | input source. azure engine: `--input` only |
+| `--engine` | `auto` | `auto` \| `cloud` \| `local` \| `azure` |
+| `--model` | `base` | local Whisper: `tiny` \| `base` \| `small` \| `medium` \| `large` |
+| `--mode` | `auto` | cloud (Tencent) only — see modes above |
+| `--lang` | `16k_zh` | Tencent: `16k_zh`, `16k_en`, `16k_zh_en`, `16k_ja`, `16k_ko`. Azure: `auto`, `ja-JP`, `zh-CN`, `en-US`, … (BCP-47) |
+| `--format` | `srt` | `srt` \| `txt` \| `json` |
+| `--speakers` / `--diarize` | false | Speaker diarization — cloud (`flash`/`file`) and azure |
+| `--speaker-number <n>` | — | Hint expected speaker count |
+| `--task-id <id>` | — | Resume polling a Tencent async task (numeric) |
+| `--job-id <uuid>` | — | Resume polling an Azure job (UUID) |
+| `--output <path>` | `<input>.<format>` | |
+
+### Common scenarios
+
+**Meeting → SRT with speakers**
+```bash
+voxflow asr --input meeting.mp4 --speakers --speaker-number 4 --format srt -o meeting.srt
+```
+
+**Quick transcript (no quota cost)**
+```bash
+voxflow asr --input recording.mp3 --engine local --model small --format txt
+```
+
+**Mixed Chinese + English audio**
+```bash
+voxflow asr --input bilingual.mp3 --lang 16k_zh_en
+```
+
+---
+
+## 📋 asr-jobs — browse Azure ASR job history
+
+Azure batch jobs run server-side and survive across CLI sessions, so this command is the dashboard for them. All four subcommands talk to `/api/asr/jobs/*` directly.
+
+```bash
+# List the 20 most recent jobs (server-side, paginated)
+voxflow asr-jobs list
+
+# Show one job (with transcript preview if succeeded)
+voxflow asr-jobs show 6f3c2798-87bf-4367-bb4c-08b872e12bef
+
+# Re-emit the transcript locally without re-running ASR
+voxflow asr-jobs download 6f3c2798-87bf-4367-bb4c-08b872e12bef --format srt -o meeting.srt
+
+# Cancel a running job (refunds quota, deletes Azure-side transcription)
+voxflow asr-jobs cancel 6f3c2798-87bf-4367-bb4c-08b872e12bef
+
+# Machine-readable
+voxflow asr-jobs list --json
+voxflow asr-jobs show <jobId> --json
+```
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--limit <n>` | 20 | (list) max 100 |
+| `--format srt\|txt\|json` | srt | (download) output format |
+| `--output, -o <path>` | `asr-<jobId>.<ext>` | (download) target file |
+| `--json` | — | (list, show) raw JSON to stdout |
+
+> The `download` subcommand is idempotent — handy if you ran `asr` long ago and want to re-emit in a different format without paying again. The transcript is stored in `result_json` server-side for at least 30 days (RLS-scoped, only the owner can read it).
+
+---
+
+## 🌐 translate — SRT / text / file translation
+
+LLM batch translation. Accepts SRT (preserves timing), inline text, or a `.txt` / `.md` file.
+
+```bash
+# Translate subtitles, preserve timing
+voxflow translate --srt en.srt --to zh -o zh.srt
+
+# Inline text
+voxflow translate --text "你好世界" --to en
+
+# File
+voxflow translate --input article.md --to en -o article-en.md
+
+# Smart re-timing for length-mismatched languages
+voxflow translate --srt zh.srt --to en --realign
+
+# Smaller batches for very long subtitle files
+voxflow translate --srt long.srt --to ja --batch-size 5
+```
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--srt <file>` / `--text <text>` / `--input <file>` | one required | input |
+| `--to <lang>` | required | `en`, `zh`, `ja`, `ko`, `es`, `fr`, ... (ISO codes) |
+| `--from <lang>` | auto-detect | source language |
+| `--realign` | false | Adjust subtitle timing for target-language length expansion (e.g. EN→ZH usually shrinks; EN→JA usually grows) |
+| `--batch-size <n>` | `10` | Captions per LLM call, 1–20 |
+| `--output <path>` | auto-named | |
+
+> Use `--realign` when translating between languages with very different word density (CJK ↔ Latin) so subs don't crash into each other.
+
+---
+
+## 🎬 dub — SRT → timeline-aligned TTS
+
+Re-voice a video using its SRT. Per-caption TTS placed at the exact timestamp. Optional speed compensation when speech overflows the slot.
+
+```bash
+# Basic — output WAV
+voxflow dub --srt subtitles.srt -o dubbed.wav
+
+# Merge into video (requires ffmpeg)
+voxflow dub --srt subtitles.srt --video input.mp4 -o dubbed.mp4
+
+# Multi-speaker (SRT lines tagged `[Speaker: Name]`)
+voxflow dub --srt show.srt --voices speakers.json --speed-auto -o dubbed.wav
+
+# With background music ducked under speech
+voxflow dub --srt narration.srt --bgm music.mp3 --ducking 0.3 -o final.wav
+
+# Patch mode — re-synthesize one caption without full re-run
+voxflow dub --srt subtitles.srt --patch 5 -o dub-existing.wav
+```
+
+### `speakers.json` format
+
+```json
+{
+  "Alice": "v-female-R2s4N9qJ",
+  "Bob":   "v-male-s5NqE0rZ",
+  "Narrator": "v-female-T8m4WxP7"
+}
+```
+
+SRT captions tag speaker inline:
+```
+1
+00:00:01,000 --> 00:00:03,500
+[Speaker: Alice] Hello from Alice!
+```
+
+Unmatched speakers fall back to `--voice`.
+
+### `--speed-auto` (overflow protection)
+
+When TTS audio is longer than the SRT time slot, dub computes `alpha = T_raw / T_target` and re-synthesizes at `speed × alpha`. If `alpha > 2.0`, prints `OVERFLOW_WARNING` and tries at speed `2.0` (max).
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--srt <file>` | required | |
+| `--video <file>` | — | Merge dub into the original video |
+| `--voice <id>` | `v-female-R2s4N9qJ` | Default voice |
+| `--voices <file>` | — | JSON speaker→voiceId map |
+| `--speed <n>` | `1.0` | 0.5–2.0 |
+| `--speed-auto` | false | Auto-compensate per-caption overflow |
+| `--bgm <file>` | — | Background music |
+| `--ducking <n>` | `0.2` | BGM volume when speech is active (0–1) |
+| `--patch <id>` | — | Re-synthesize a single caption by ID |
+| `--output <path>` | `./dub-<ts>.wav` | `.wav` or `.mp4` |
+
+### Pipeline
+
+```
+SRT → parseSrt() → captions[]
+  ↓
+per-caption TTS (with voice mapping + speed compensation)
+  ↓
+buildTimelineAudio(segments) → 24kHz / 16-bit / mono WAV
+  ↓ optional
+mixWithBgm() → mixed WAV
+  ↓ optional
+mergeAudioVideo() → MP4
+```
+
+---
+
+## 🌍 video-translate — end-to-end pipeline
+
+ASR → translate → dub → burn subtitles → auto-open. The "translate this video into another language" one-shot.
+
+**Pipeline (5 stages):**
+```
+[1/5] FFmpeg check
+[2/5] ASR (flash mode → Azure fallback) → fine-grained per-sentence SRT
+[3/5] Translate → quality check → auto-retry untranslated captions
+[4/5] TTS dub (speed-auto) → merge audio into video
+[5/5] Burn subtitles into video → auto-open output
+```
+
+**Output:** `<input>-<lang>.mp4` (with burned subtitles) + `<input>-<lang>.srt` (standalone subtitle file)
+
+```bash
+# Auto-detect source, dub to English
+voxflow video-translate --input video.mp4 --to en
+
+# Explicit source, with re-timing
+voxflow video-translate --input video.mp4 --from zh --to en --realign
+
+# Specific voice for dubbed track
+voxflow video-translate --input video.mp4 --to ja --voice v-male-Bk7vD3xP
+
+# All-local (no quota cost — uses Whisper for ASR; LLM still consumes quota for translation)
+voxflow video-translate --input video.mp4 --to en --engine local
+
+# Keep SRT + audio intermediates for inspection
+voxflow video-translate --input video.mp4 --to en --keep-intermediates
+```
+
+### Options
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--input <file>` | required | source video |
+| `--to <lang>` | required | target language code |
+| `--from <lang>` | auto | source language |
+| `--voice <id>` | default | TTS voice for dubbed track |
+| `--voices <file>` | — | Multi-speaker map |
+| `--realign` | false | Adjust subtitle timing for target length |
+| `--speed <n>` | `1.0` | TTS speed |
+| `--batch-size <n>` | `10` | Translation batch size |
+| `--keep-intermediates` | false | Keep SRT, raw audio |
+| `--asr-mode <mode>` | auto | Override ASR mode |
+| `--asr-lang <engine>` | auto | Override ASR engine code |
+| `--engine` | `auto` | ASR engine: `auto` \| `local` \| `cloud` |
+| `--model` | `base` | Whisper model for local engine |
+| `--output <path>` | `<input>-<lang>.mp4` | |
+
+> For multi-speaker dubbing, run `asr` separately first with `--speakers`, then edit the resulting SRT to tag `[Speaker: Name]` lines, then run `dub` with `--voices` — `video-translate` doesn't preserve speaker tags through translation by default.
+
+---
+
+## 🚀 publish — one-shot end-to-end (recommended for agents)
+
+`publish` bundles ASR / translation / dubbing / merge into a single command and emits a structured JSON result via `--json`. Use this instead of stitching `asr` + `translate` + `dub` yourself when an agent or web orchestrator drives the run.
+
+Three build modes (auto-selected from inputs):
+
+| Mode | Use when | Inputs |
+|---|---|---|
+| `video-translate` | Source video → translated dubbed video | `--input <video> --to <lang>` |
+| `srt-dub` | You already have an SRT and want it dubbed onto a video | `--input <video> --srt <subs.srt>` |
+| `merge-existing` | Video + audio already produced; just merge + deliver | `--video <v.mp4> --audio <a.wav>` |
+
+Publish targets:
+
+- `--publish local` (default) — copy artifact to `./published/<base>-<platform>-<ts>.mp4`
+- `--publish webhook --publish-webhook <url>` — POST artifact metadata to webhook, return URL
+- `--publish none` — skip publish step, return final MP4 path only
+
+Always pass **`--json`** when invoking from a Skill — stdout becomes a single JSON doc (`artifact.path` / `artifact.durationSec` / `artifact.sizeBytes` / `publish.publishUrl` / `quotaUsed`, etc.) instead of human-readable progress.
+
+```bash
+# End-to-end: source video → translated dubbed publish
+voxflow publish --input talk.mp4 --to en --json
+
+# Hand off to webhook publisher
+voxflow publish --input talk.mp4 --to ja --publish webhook --publish-webhook https://hook.example.com/in --json
+```
+
+---
+
+## 📋 summarize — content → slides (and optional video)
+
+Long video/audio/text → ASR (if needed) → LLM summary → PPTX deck. Optional TTS narration and Remotion video render.
+
+```bash
+voxflow summarize --input lecture.mp4
+voxflow summarize --input meeting.mp4 --lang zh --slides 10
+voxflow summarize --input podcast.mp3 --engine local --tts
+voxflow summarize --input lecture.mp4 --video --scheme aurora
+voxflow summarize --text "长篇文章内容..." --slides 6 --lang zh
+```
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--input <file>` / `--text <text>` | one required | |
+| `--slides <n>` | `8` | 4–12 |
+| `--lang` | `en` | Output language |
+| `--engine` | `auto` | ASR engine for `--input` |
+| `--model` | `base` | Whisper model for local ASR |
+| `--tts` | false | Add TTS narration audio per slide |
+| `--video` | false | Also render an MP4 (needs `remotion-cards/`) |
+| `--scheme` | `aurora` | Video scheme — see `voxflow:video` skill for full table |
+| `--voice <id>` | `v-female-R2s4N9qJ` | |
+| `--output <path>` | `<input>-summary.pptx` | |
+
+> `summarize --video` overlaps with `present`. Use `summarize` when starting from a long video/audio source; use `present` when starting from a topic / pasted article.
+
+---
+
+## Common workflows
+
+### Translate a YouTube video to Chinese (full pipeline)
+
+```bash
+# 1. Download (yt-dlp / etc.) → video.mp4
+# 2. One-shot:
+voxflow video-translate --input video.mp4 --to zh --realign --keep-intermediates
+# Output: video-zh.mp4 + intermediate .srt files
+```
+
+### Generate clean SRT from a recording
+
+```bash
+voxflow asr --input recording.mp3 --speakers --speaker-number 3 --format srt -o clean.srt
+```
+
+### Long meeting / lecture (1 hr+) → word-timed SRT
+
+```bash
+# Kick off — Ctrl+C is safe, the server keeps working.
+voxflow asr --input lecture-2h.mp4 --engine azure --lang ja-JP --diarize --speaker-number 4
+
+# Days later, browse what ran:
+voxflow asr-jobs list
+
+# Re-download in TXT instead of SRT — no extra quota:
+voxflow asr-jobs download <jobId> --format txt -o lecture.txt
+```
+
+### Re-dub an existing SRT with different voices
+
+```bash
+voxflow dub --srt show.srt --video show.mp4 --voices new_cast.json --speed-auto -o new_cast.mp4
+```
+
+### Patch a single bad caption without re-rendering
+
+```bash
+# Edit clean.srt's caption 12, then:
+voxflow dub --srt clean.srt --patch 12 -o updated.wav
+```
+
+### Lecture / podcast → summary deck
+
+```bash
+voxflow summarize --input lecture-2h.mp4 --slides 12 --lang zh --tts -o summary.pptx
+```
+
+---
+
+## Quota cost
+
+| Operation | Cost |
+|---|---|
+| `asr` cloud (Tencent, per call) | ~50–200 |
+| `asr` local (Whisper) | 0 |
+| `asr` azure (per audio minute, ceil) | 150 (78s = 2min = 300; 30-min = 4500; 1-hr = 9000) |
+| `translate` (per 1K target chars) | ~50 |
+| `dub` per caption (TTS) | ~50 |
+| `video-translate` 5-min video | ~2,000–4,000 |
+| `summarize` 1-hr video | ~4,000–6,000 |
+
+Always `voxflow status` before long jobs.
+
+## Rules
+
+1. **Pick the right engine for the file:**
+   - `local` — best when you have whisper.cpp installed and want zero quota.
+   - `cloud` (Tencent) — best for short clips (≤2 hr), fast turnaround.
+   - `azure` — best for **30-min+ recordings, word-level timestamps, multi-locale auto-detect, or anything you might need to resume after a disconnect**. Server-side jobs survive Ctrl+C.
+2. **Translation batch size is critical:**
+   - Default `--batch-size 5` is the sweet spot. Larger batches (10+) cause LLM to silently drop captions.
+   - If you see untranslated lines in output, reduce to `--batch-size 3`.
+   - The CLI auto-retries failed batches up to 2 times with validation.
+3. **`--realign`** when translating between very different language families (EN ↔ JA / ZH).
+4. **For multi-speaker dub**, generate the SRT with `--speakers` first, manually verify and tag, then `dub --voices`.
+5. **Always test on a 1-minute clip** before running `video-translate` on a long video — it consumes quota linearly.
+6. After completion, auto-play: `open output.mp4`.
+7. Keep `--keep-intermediates` on for the first run of any pipeline so you can inspect what failed.
+8. For Azure jobs that are still running, **don't re-submit** if the user closes the terminal — `voxflow asr-jobs list` to find the jobId, then `voxflow asr --engine azure --job-id <uuid>` (or `voxflow asr-jobs download <uuid>`) resumes free of charge.
+9. **video-translate auto-enables `--speed-auto`** — if TTS audio overflows the time slot, it auto-adjusts. No manual flag needed.
+10. **Quality self-check**: After translation, the CLI checks if >30% captions are unchanged (untranslated). If so, it warns you to use a smaller batch size.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Captions left untranslated (original language) | LLM dropped lines in large batch | Use `--batch-size 3` |
+| `cloud` ASR returns 500 error | Tencent service transient failure | Switch to `--engine azure` |
+| TTS audio overflows time slot | Translation text longer than source | Add `--speed-auto` (or use `video-translate` which enables it by default) |
+| `ffmpeg` not found for `--video` | Not installed or not in PATH | `brew install ffmpeg` / install ffmpeg-full for subtitle burn-in |
+| Azure job seems stuck | Still processing | `voxflow asr-jobs show <id>` to check status; don't re-submit |
+| Subtitle timing drift after translation | Different word density between languages | Add `--realign` |
+| Low subtitle quality in specific domain | ASR hot-words not tuned | Try `--engine azure --lang <exact BCP-47>` for better recognition |