@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/brewreel/docs/broll.en.md

@@ -1,252 +0,0 @@
-# Talking-head B-roll (experimental)
-
-[← Back to README](../README.en.md) · [中文](broll.md)
-
-Add explanatory pictures to a real talking-head video. There are two kinds:
-
-- **Motion clips**: free. Five card types (keyword, checklist, steps, counter, compare). Every word on the card is copied from what the speaker said, and it lights up as the word is spoken.
-- **AI clips**: small scenes generated with MiniMax H3. They cost money and a person must review them. Three regular styles: wood blocks (the default), clay stop-motion and layered paper; ink sketch is experimental and only works as a stand-in preview. The same robot appears throughout.
-
-The model only writes `broll.json`: which lines get a picture, and which kind. Scripts handle timing, cost, generation and the final cut.
-
-## Who it is for
-
-Authors who already have a talking-head video and want a picture on the lines that explain a step, a number, a comparison or an object. The opening, the ending and lines about personal feelings stay on the face.
-
-## One command
-
-Install the dependencies first ([Install and get started](quickstart.en.md); `npm install` in `template`, then `pip install numpy scipy imageio-ffmpeg`). If you are upgrading from v0.8, run `npm install` in `template` again to get the transcription component.
-
-Talking-head B-roll needs a **full ffmpeg** (talk conversion, stand-in clips, clip checks and the contact sheet all use it). The copy bundled with Remotion is a slim build that lacks many filters. `pip install imageio-ffmpeg` is the easiest; you can also put your own ffmpeg on PATH, or point the `FFMPEG` environment variable at it. Without it the command stops at the start and says so, instead of failing after transcription.
-
-Make a project folder, rename the talk to `talk.mp4`, put it in, then:
-
-```
-node scripts/talk.mjs <project> --out <dir-outside-the-repo>
-```
-
-It runs three steps. The first two are skipped once done; rendering runs every time, but when the talk, captions, `broll.json`, generated clips and render code are all unchanged it reuses the last video. So you can keep running the same command:
-
-1. **Transcribe**: without `talk.srt`, it transcribes the talk on your machine. The first run downloads a speech model of about 240 MB, once. An existing `talk.srt` is never overwritten.
-2. **Write `broll.json`**: a cheap model writes it; set `DEEPSEEK_API_KEY` (or `LLM_API_KEY`) first. If validation fails, the error text goes back to the model, at most 3 rounds. An existing `broll.json` is kept; `--rewrite-broll` rewrites it.
-3. **Render**: motion clips are drawn for real; AI clips start as solid-color stand-ins, at no cost.
-
-After the first run, open `video.mp4` and the contact sheet `sheet.png` in the output folder and check the pacing. By default there are at most 2 AI clips; the other lines that need a picture get motion clips or keep the face. To change the cap, add something like `--max-ai 1` together with `--rewrite-broll` (without `--yes`: price the new plan first).
-
-`--rewrite-broll`, `--only` and `--force-redo` should take effect once. When the script stops it prints the full next command with them removed; copy that one.
-
-Words the proofreading pass was unsure about and nobody has checked yet (the "suggested only" ones in `talk.fixes.txt`) are never put on a motion card, and the command reminds you at the end. Listen to the talk; if a word is wrong, fix `talk.srt`, and add `--rewrite-broll` if `broll.json` should be rewritten for the new words.
-
-To fix the captions before going further, run only the transcription, edit `talk.srt`, then run the command above.
-
-```
-node scripts/broll/transcribe.mjs <project>
-```
-
-No DeepSeek key? Ask an AI coding assistant to write `broll.json` by [`broll/SKILL-broll.en.md`](../broll/SKILL-broll.en.md), put it in the project folder, and run the same command. A full v2 example is [`examples/talk/motion/broll.json`](../examples/talk/motion/broll.json), as a reference for the format; the repo has no example talk video, so to run it as is, first run `node tests/broll/demo.mjs` to generate a 20-second test talk.
-
-### Really generating AI clips
-
-> The three regular styles (wood blocks, clay stop-motion, layered paper) ship with reference images and can be generated for real. Ink sketch (`ink-sketch`) is experimental and has no reference images yet: real generation with it stops before submitting (exit code 2, nothing spent), so it only works as a stand-in preview.
-
-When the stand-in version looks right, switch to MiniMax H3. Set `MINIMAX_API_KEY` first.
-
-```
-node scripts/talk.mjs <project> --out <dir-outside-the-repo> --provider minimax-h3 --dry-run
-node scripts/talk.mjs <project> --out <dir-outside-the-repo> --provider minimax-h3 --yes
-```
-
-The first command only prints the estimate and spends nothing. Run the second after you agree. A person must watch the review page and approve it before the final render (see "Review gate" below). `--dry-run` and `--yes` only affect the render step; the first two steps are skipped when done.
-
-Once clips are really generated, every command on the same `--out` needs `--provider minimax-h3`. If you leave it out, the script stops (exit code 2) instead of replacing paid clips with stand-ins; to look at a stand-in layout, use another `--out`.
-
-### Common options
-
-| Option | What it does |
-|---|---|
-| `--out <dir>` | Output folder. Required, must be outside the repo |
-| `--provider placeholder\|local\|minimax-h3` | Where AI clips come from. Defaults to `broll.json` (the cheap model writes `placeholder`) |
-| `--dry-run` | Validate, plan and estimate only; no generation |
-| `--yes` | Agree to spend money and really generate |
-| `--draft` | Render a draft before review; AI clips are marked 「B-roll 未审」 (not reviewed) |
-| `--style <id>` | Main style used when writing `broll.json`, default `wood-blocks` |
-| `--max-ai <n>` | Most AI clips when writing `broll.json`, default 2 |
-| `--budget <yuan>` | Budget written into `broll.json`, default 20 |
-| `--captions add\|none\|burned` | Captions, default `add` |
-| `--lang auto\|zh\|en\|yue\|ja\|ko` | Transcription language, default `auto` |
-| `--terms "word1,word2"` | Proper nouns, to help the proofreading pass |
-| `--no-fix` | Skip the DeepSeek proofreading pass after transcription |
-| `--rewrite-broll` | Rewrite `broll.json` even if it exists. Replaced only after it validates; the old one is kept as `broll.json.bak-<time>`. Cannot be combined with `--yes` |
-| `--only b03` | Redo only this AI clip (every run with it redoes and pays again; drop it once done) |
-| `--concurrency <1–12>` | How many clips to submit at once, default 3 |
-| `--force-redo` | Needed for the third redo of the same clip |
-
-`--style`, `--max-ai`, `--budget` and `--captions` are only used when `broll.json` is written. If it already exists, edit the file, or add `--rewrite-broll`.
-
-## Step by step
-
-The one command chains these steps. To run them one at a time:
-
-```
-node scripts/broll/transcribe.mjs <project> [--lang auto] [--terms "word1,word2"] [--no-fix] [--force]
-node scripts/broll/list-cues.mjs <project>
-node scripts/broll/llm_broll.mjs <project> [--style wood-blocks] [--budget 20] [--captions add] [--max-ai 2] [--dry-run]
-node scripts/broll/validate.mjs <project> [--max-ai 2]
-node scripts/make-talk.mjs <project> --out <dir-outside-the-repo> [--dry-run] [--provider minimax-h3] [--yes] [--draft]
-node scripts/broll/review-sheet.mjs <project> --out <dir-outside-the-repo>
-node scripts/broll/approve.mjs <project> --out <dir-outside-the-repo>
-```
-
-`llm_broll.mjs --dry-run` only prints the assembled prompt and a token estimate; it calls nothing. `make-talk.mjs` does not transcribe: without `talk.srt` it stops and tells you to transcribe first.
-
-## Two kinds of picture
-
-| | Motion clip | AI clip |
-|---|---|---|
-| Written as | `"source": "motion"` | `"source": "ai"` or no `source` |
-| Cost | Free | Per second, see "Price" |
-| Text on screen | Copied from the speech, checked character by character | None (text inside generated pictures is unreliable) |
-| Review | Not needed | A person watches and approves |
-| Badge | None | 「AI 生成画面」 (AI-generated) in a corner while on screen |
-| Length per clip | 1.8–12 seconds | 2.5–12 seconds |
-
-### The five motion cards
-
-| Template | Use it for | On screen |
-|---|---|---|
-| `keyword` | A line the viewer should remember | Big keyword text (about 80% of the frame width, two lines when long) that lights up word by word; the key phrase gets a highlighter stroke |
-| `checklist` | Two to four things | A list; each item appears and gets a tick as it is said |
-| `steps` | An order of steps | Steps laid out as a staircase; each step lights up as it is said (dots on the block show which step) |
-| `counter` | One exact number | A rolling number that lands when the number is said |
-| `compare` | Before and after, or two ways, old way said first | Two stacked cards on a vertical talk (two columns on a horizontal one); the side said later wins. Do not use it when the new way is said first |
-
-The words on a card must be consecutive words from the speech, not reworded; a negation before the quote (不用, 不要, 不会, "don't"...) must be included; a number to show goes in `counter`, only if the speaker really said it, and two numbers separated by a space, line break or sentence break are never joined into one. So **transcription mistakes show up on screen as is**: check `talk.srt` before rendering and fix typos there. After the last word, a card holds a little longer when silence follows.
-
-Layout: motion clips default to `split` (card on the top 60%, speaker on the bottom 40%), `pip` on a horizontal talk, so the speaker stays on screen; `keyword` cannot use `full`, and `full` is only for a checklist or steps with 3 or more items (validation blocks the rest). Colours and finish follow the main style: wood blocks get a warm wood table, off-white cards and blue-grey and warm-orange wooden blocks; clay stop-motion gets warm pastels; layered paper gets off-white paper with a few coloured sheets; ink sketch (experimental) gets white paper and ink lines. The background has a faint texture and slowly drifting shapes; decorations only go in the corners away from the text and captions, and there are no words. On version 2, a top-level `motionTheme` in `broll.json` (`wood`, `clay`, `paper`, `ink`, `cutpaper-meadow`, `cutpaper-dusk`) overrides the motion look for that film; omit it and the main style's look is used.
-
-Transitions: there is only one picture of the speaker. In `split` it shrinks from full screen to the bottom while the card slides down from the top; in `pip` it shrinks into the circle at the bottom right (a bit larger for motion clips, with the face zoomed in a little and a card-coloured ring). The exit plays it backwards, so two faces never overlap. When a `keyword` clip's caption says the same words as the big text, the caption keeps only the extra words, or is hidden. A money amount (元, 块, ¥ ...) with an old price does not roll: it flips to the new price at the moment it is said, so no price that was never said appears; without an old price it only rolls for the 0.6 s before it is said.
-
-### AI clip styles
-
-| Style | Name | Fits |
-|---|---|---|
-| `wood-blocks` | Wood blocks (default, 「积木风」) | Anything; best for steps, amounts, showing one object |
-| `clay-stopmotion` | Clay stop-motion | Doing things by hand, places, mood |
-| `paper-layers` | Layered paper | Explaining, places, comparisons |
-| `ink-sketch` | Ink sketch (experimental) | Experimental: no reference images yet, stand-in previews only, cannot be a second style |
-| `brick-diorama` | Plastic bricks (experimental) | Experimental, not the default; its output shows studs; not recommended |
-
-The AI clips of one film use at most two styles: the main `style` and an optional second `styleAlt` (only one the main style pairs with). The robot's shape and colors live in `broll/character.json` and are shared by every style; a style only decides what the robot is made of. Which jobs and cameras each style allows, and whether its reference images exist yet: [`broll/styles/README.en.md`](../broll/styles/README.en.md).
-
-If a style has no reference images yet, real generation with it stops before submitting (exit code 2, nothing spent) and says which style to switch to, or to use motion clips instead. Previews with `placeholder` are not affected. In this release the three regular styles ship with reference images; only ink sketch (experimental) has none.
-
-## Three placements
-
-| mode | Picture |
-|---|---|
-| full | The picture fills the frame |
-| pip | The face stays in a circle at the bottom right; the circle scales with the frame size (a bit larger for motion clips) |
-| split | Picture on the top 60%, face on the bottom 40%. Vertical only |
-
-## Captions
-
-| captions | Meaning |
-|---|---|
-| add | Draw `talk.srt` onto the finished video |
-| none | No captions |
-| burned | The talk already has burned-in captions. Only `split`, so they are not covered again. A landscape talk with `burned` is not supported in this release (`split` is portrait only); use `none` |
-
-With `full` and `pip`, captions sit in the lower quarter of the frame; when a `pip` clip's captions do not fit left of the circle, the whole clip moves them above the circle at full width. With `split`, they sit just above the divider, and two-line captions move up as a block so they never cover the face. When a line is slightly too long, the font shrinks a little so one or two characters are not left alone on a line.
-
-## Transcription
-
-- It uses the SenseVoice speech model on your machine (run through sherpa-onnx). No network after the download, no cost. The model is about 240 MB the first time, tried from ModelScope, HuggingFace and hf-mirror in that order; downloads resume, and files whose sha256 does not match are rejected.
-- The model sits in a global cache shared by all projects: `%LOCALAPPDATA%\brewreel\asr` on Windows, `~/.cache/brewreel/asr` on macOS / Linux. `BREWREEL_ASR_DIR` changes the cache folder; `BREWREEL_ASR_MODEL_DIR` points to a folder you downloaded yourself (with `model.int8.onnx` and `tokens.txt`), and nothing is downloaded.
-- On Windows, the first load after the download takes about 30 seconds longer.
-- The language is detected automatically. If Mandarin is detected as Cantonese or Japanese, re-run with `node scripts/broll/transcribe.mjs <project> --lang zh --force`.
-- With `DEEPSEEK_API_KEY` (or `LLM_API_KEY`), a cheap model proofreads the transcript: it only returns "change this character to that one" patches, and the script decides from the pronunciation whether to apply each one. Changes that touch numbers, negations or opposites are only suggested, never applied; a change to a proper noun also needs a similar pronunciation. The recognizer cannot tell 他 / 她 / 它 apart (all read tā) and almost always writes 他: the pass lists every 他 and 她 in the transcript for the model one by one and asks what each refers to and whether it is a person; the ones that refer to software, a tool, a robot, an animation or another thing become 它, and the ones that refer to people stay (all in the same request, no extra call). What changed, what each pronoun refers to, and which lines you should listen to again are in `talk.fixes.txt`. The suggested-only words are never put on a motion card; editing that line counts as checked. `--no-fix` skips this pass.
-- The same video transcribed in two projects can get different proofreading results (the model's answers vary); re-running one project uses the cache and gives the same result.
-- Proper nouns (product names, people's names) go in `talk.terms.txt` in the project folder, one per line, or in `--terms "word1,word2"`.
-- An existing `talk.srt` is never overwritten. `--force` re-transcribes: the old file is renamed to `talk.srt.bak-<time>`, and the same video is not recognized again.
-- Fix typos in `talk.srt` freely, but once `broll.json` is written **do not split or merge cues**: the cue ids would shift. The script records the cues at that point; if they change, validation stops you and asks you to rewrite `broll.json`.
-- The transcription cache, the cue record and the converted talk live in `.brewreel/` in the project folder. You can delete it and still render; the motion cards then estimate word timings, and the cue check goes away.
-
-If you already have captions, put them in as `talk.srt` (an SRT exported from an editor such as CapCut) and nothing is transcribed.
-
-## Automatic conversion of the talk
-
-Phone videos often use HEVC, a variable frame rate, mono audio, a rotation flag or a non-integer frame rate such as 29.97. Before rendering, the script converts the talk to H.264 with a constant frame rate and stereo audio, stores that copy in `.brewreel/` in the project folder, and leaves the original untouched. Later runs reuse the copy. A talk that is already H.264 with a constant frame rate is used as is.
-
-## Price
-
-Only AI clips cost money; motion clips and stand-ins are free. An estimate is always printed first: above `budgetYuan` it stops; under budget it still needs `--yes`. The estimate also prints the total seconds of AI video.
-
-MiniMax has two kinds of key, charged differently:
-
-| | Pay-as-you-go key | Subscription key (starts with `sk-cp-`) |
-|---|---|---|
-| How it is charged | Per second from your balance | No pay-as-you-go. H3 video is not in the plan's quota; it is paid in credits |
-| Price | 768P 0.5 yuan/s, 2K 0.8 yuan/s | 768P about 70 credits/s (measured 2026-10); 2K not measured |
-| Estimate shows | 「AI 视频共 N 秒，按价目表 X 元」 (N seconds, X yuan) | An extra 「约 N 积分（订阅 key，从积分扣，以 MiniMax 后台为准）」 (about N credits, from your credits; the MiniMax console is the authority) |
-| Budget gate | Stops in yuan | Also stops in yuan (from the price table); credits are an extra line |
-
-- The price table lives in the script; the API receipt has no amount. MiniMax's site and console are the source of truth.
-- Generated length per clip is the window rounded up and clamped to 4–15 seconds. By default there are at most 2 AI clips of at most 12 seconds each: at 768P the AI clips of one film cost about 2–12 yuan, or about 280–1680 credits with a subscription key.
-- Style reference stills (image-01) cost 0.025 yuan each. The maintainer makes them and ships them in the repo; users do not need to.
-
-## Review gate
-
-A final `minimax-h3` video needs a person to look at every AI clip.
-
-1. `node scripts/broll/review-sheet.mjs <project> --out <dir-outside-the-repo>`
-2. Open `review.html` in that folder. One row per clip: the spoken line, style, prompt, start / middle / end frames, cost. The strip at the top puts the middle frame of every AI clip side by side, so you can see whether the robot and the material stay consistent. Motion clips are marked 「动效，不用审」 (motion, no review needed) and list their on-screen text.
-3. The person runs `node scripts/broll/approve.mjs <project> --out <dir-outside-the-repo>`
-4. Run the same command again for the final video
-
-An AI assistant must not run approve for the person, and `talk.mjs` never runs it. The approval binds the AI part of `broll.json` and the sha256 of each generated clip; changing either needs a new review, while editing only motion clips does not. To see the cut before review, add `--draft`: while an AI clip is on screen, the top right says 「B-roll 未审」 (not reviewed).
-
-`placeholder` and `local` are free and skip review.
-
-If a run is interrupted, run it again with the same `--out`: clips already submitted are only queried, never submitted or paid for twice. When you "run the same command again", drop `--only`, `--rewrite-broll` and `--force-redo` (the next command the script prints already has them removed).
-
-## What the output folder holds
-
-| File | Contents |
-|---|---|
-| `video.mp4` | The finished video |
-| `sheet.png` | Contact sheet of check frames around, at the start, middle and end of each clip |
-| `check/` | The check frames themselves |
-| `broll.plan.json` | The plan: each clip's window, source, style and cost |
-| `manifest.json` | Delivery record: style, money spent, whether the captions were transcribed or supplied, whether the talk was converted |
-| `ledger.json` | Ledger (AI clips only): task id, actual seconds, cost |
-| `review.html` / `broll.review.json` | Review page and approval record |
-
-## Extra files in the project folder
-
-| File | Contents | Safe to delete? |
-|---|---|---|
-| `talk.srt` | The transcribed captions | Keep it; deleting re-transcribes and cue ids may change |
-| `talk.fixes.txt` | What the proofreading pass changed and what it only suggested | Yes, it is for people only |
-| `llm_log.json` | Token usage and validation report of each round when the cheap model wrote `broll.json` | Yes, for troubleshooting |
-| `broll.llm-error.txt` | The last error when writing `broll.json` failed | Yes |
-| `broll.llm-draft.json` | The model's last attempt when `--rewrite-broll` failed validation (the old `broll.json` is untouched) | Yes |
-| `broll.json.bak-<time>` | The old `broll.json` before `--rewrite-broll` replaced it | Yes; rename it back to return to the old plan |
-| `.brewreel/` | Transcription cache, cue record, converted talk, unsure words | Yes; motion cards then estimate word timings, and the cue check and unsure-word reminders go away |
-
-## Known limits
-
-- **Experimental**: not yet used on many real talking-head videos. Treat the result as a first cut and watch the whole video before publishing.
-- **Studs may still show up now and then**: the new styles' prompts describe only what should be seen and never mention studs, but the video model occasionally still draws bricks with round studs. Check frame by frame on the review page. `brick-diorama` shows studs reliably and is kept only for old projects.
-- **Ink sketch (`ink-sketch`) is only experimental**: in two rounds of reference images the robot always got an antenna on its head, which does not match the shared character, so this release ships no reference images for it. It only works with `placeholder` and cannot be a second style. The three regular styles ship with reference images.
-- **Changing a v0.8 file to version 2 costs money again**: v2 changes the prompt and the request, so AI clips already generated are generated again. Old files still run as version 1.
-- **Each AI clip is generated on its own**: the shared character, reference images and `link: continue` keep clips closer, but shape and colors can still differ; clips are not guaranteed to match.
-- **At most two styles of AI clip per film**: one main style plus one second style, not a different style per clip.
-- **Text inside generated pictures is unreliable**: for exact words, use a motion clip.
-- **Motion cards copy the transcript**: transcription mistakes show up on screen; check `talk.srt` before rendering.
-- **English transcription was tested only with synthetic speech**: not with real English speakers or accents. In an English talk, numbers must be digits to make a counter card.
-- **Transcription is not tested on macOS**, nor on Linux or a clean Windows without the VC++ runtime. The two download sources other than ModelScope were not tested on a real machine.
-- **Background music under the speech** hides the pauses, so cue splitting and timing get less accurate.
-- **10-bit HDR phone videos** only get their pixel format converted, without tone mapping, so colors may look washed out.
-- **The 2K credit price for subscription keys is not measured**; the estimate only says to check the console.
-- **Cheap models writing v2 `broll.json` and the proofreading pass** have not yet been tested at scale with DeepSeek.
-- The DeepSeek Harness plugin does not include this feature in this version.

package/skills/brewreel/docs/broll.md

@@ -1,252 +0,0 @@
-# 口播配画面（实验）
-
-[← 返回 README](../README.md) · [English](broll.en.md)
-
-给一段真人口播配上解释用的画面。画面有两种：
-
-- **动效画面**：免费。关键词、清单、步骤、数字、对比五种卡片，上面的字全部从口播原话里摘，说到哪个字亮到哪个字。
-- **AI 画面**：用 MiniMax H3 生成的小场景，花钱，要人审过。正式风格三种：积木风（默认）、黏土定格、分层纸艺；手绘线稿是实验风格，只能占位预览。全片同一个机器人。
-
-模型只写 `broll.json`：哪几句配画面、配哪种。时间、费用、生成和合成都由脚本做。
-
-## 适合谁
-
-已经有真人口播，想在讲步骤、讲数字、讲对比、讲物件的句子上加一段解释画面的作者。开场、收尾和讲自己感受的句子继续露脸。
-
-## 一条命令上手
-
-先按 [安装与上手](quickstart.md) 装好依赖（`template` 目录里 `npm install`，再 `pip install numpy scipy imageio-ffmpeg`）。从 v0.8 升级的，要在 `template` 目录重新跑一次 `npm install`，装上转写组件。
-
-口播配画面要**完整版 ffmpeg**（转码、占位画面、片段检查、拼图都要用）。Remotion 自带的那份是精简版，缺很多滤镜，不够用。`pip install imageio-ffmpeg` 最省事；也可以自己装 ffmpeg 放进 PATH，或者设环境变量 `FFMPEG` 指向它。没装的话，命令一开头就会停下告诉你，不会等转写完才失败。
-
-新建一个项目目录，把口播视频改名为 `talk.mp4` 放进去，然后：
-
-```
-node scripts/talk.mjs <项目目录> --out <仓库外目录>
-```
-
-它做三步。前两步做过就跳过；出片每次重做，但原片、字幕、`broll.json`、生成片和合成代码都没变时，直接用上次的成片。所以可以一直重复跑同一条命令：
-
-1. **转写**：没有 `talk.srt` 就在本机转写出一份。第一次要下载约 240MB 的识别模型，之后不再下载。已有 `talk.srt` 永远不会被覆盖。
-2. **写 `broll.json`**：交给便宜模型写，要先设好 `DEEPSEEK_API_KEY`（或 `LLM_API_KEY`）。校验没过，会把报错原文交回模型再写，最多 3 轮。已有 `broll.json` 就跳过，加 `--rewrite-broll` 才重写。
-3. **出片**：动效画面直接画出来；AI 画面先用纯色占位，不花钱。
-
-第一次跑完，打开输出目录里的 `video.mp4` 和拼图 `sheet.png` 看节奏。默认 AI 画面最多 2 段，其余要配画面的句子用动效画面或留脸；想改上限加 `--max-ai 1` 之类，再加 `--rewrite-broll` 重写（重写时不要带 `--yes`：新方案先看估价）。
-
-`--rewrite-broll`、`--only`、`--force-redo` 只该生效一次。脚本停下时会把下一条命令完整印出来（已经去掉这几个），照抄那一条就行。
-
-转写校对时拿不准、还没人核对的字（`talk.fixes.txt` 里「只提示」的那些），不会被做成动效卡片；命令跑完也会再提醒一次。听一下原片，错了就改 `talk.srt`；改完要按新字重写 `broll.json` 就加 `--rewrite-broll`。
-
-想先改字幕再往下走：先只跑转写，改好 `talk.srt`，再跑上面那条命令。
-
-```
-node scripts/broll/transcribe.mjs <项目目录>
-```
-
-没有 DeepSeek key 也能用：让 AI 编程助手照 [`broll/SKILL-broll.md`](../broll/SKILL-broll.md) 写 `broll.json` 放进项目目录，再跑同一条命令。v2 写法的完整示例在 [`examples/talk/motion/broll.json`](../examples/talk/motion/broll.json)，用来参考写法；仓库里没有示例口播视频，想直接拿它试跑，先跑 `node tests/broll/demo.mjs` 生成一段 20 秒的测试口播。
-
-### 真生成 AI 画面
-
-> 三个正式风格（积木风、黏土定格、分层纸艺）的参考图已经随仓库发布，可以真生成。手绘线稿 `ink-sketch` 是实验风格，参考图还没出，用它真生成会在提交前停下（退出码 2，没花钱），只能占位预览。
-
-占位版看着没问题，再换成 MiniMax H3 真生成。先设好 `MINIMAX_API_KEY`。
-
-```
-node scripts/talk.mjs <项目目录> --out <仓库外目录> --provider minimax-h3 --dry-run
-node scripts/talk.mjs <项目目录> --out <仓库外目录> --provider minimax-h3 --yes
-```
-
-第一条只印估价，不花钱。确认后跑第二条。生成完要人看过审片页、自己批准，才能出正式片（见下面的「审片关卡」）。`--dry-run`、`--yes` 只作用于出片这一步，前两步做过就跳过。
-
-真生成以后，同一个 `--out` 的每条命令都要带 `--provider minimax-h3`。漏写了，脚本会停下（退出码 2），不会把付费片段换成占位片；只想看占位排版就换一个 `--out`。
-
-### 常用参数
-
-| 参数 | 作用 |
-|---|---|
-| `--out <目录>` | 输出目录，必填，不能在仓库里面 |
-| `--provider placeholder\|local\|minimax-h3` | AI 画面从哪来，默认用 `broll.json` 里写的（便宜模型写的是 `placeholder`） |
-| `--dry-run` | 只校验、出计划和估价，不生成 |
-| `--yes` | 确认花钱，真生成 |
-| `--draft` | 还没审片时先出一版草稿，AI 画面上标「B-roll 未审」 |
-| `--style <风格>` | 写 `broll.json` 时用的主风格，默认 `wood-blocks` |
-| `--max-ai <段数>` | 写 `broll.json` 时 AI 画面最多几段，默认 2 |
-| `--budget <元>` | 写进 `broll.json` 的预算，默认 20 |
-| `--captions add\|none\|burned` | 字幕怎么处理，默认 `add` |
-| `--lang auto\|zh\|en\|yue\|ja\|ko` | 转写语种，默认 `auto` |
-| `--terms "词1,词2"` | 专有名词，帮转写校对认对 |
-| `--no-fix` | 转写后不让 DeepSeek 校对 |
-| `--rewrite-broll` | 已有 `broll.json` 也重写。通过校验才替换，旧的备份成 `broll.json.bak-<时间>`；不能和 `--yes` 一起用 |
-| `--only b03` | 只重做这一段 AI 画面（每带一次就重做一次、花一次钱，重做完就去掉） |
-| `--concurrency <1–12>` | 同时提交几段，默认 3 |
-| `--force-redo` | 同一段第 3 次重做时要加 |
-
-`--style`、`--max-ai`、`--budget`、`--captions` 只在写 `broll.json` 那一步用。`broll.json` 已经有了还想改，直接改文件，或加 `--rewrite-broll`。
-
-## 分步命令
-
-一条命令其实是把下面几步串起来。想一步一步看，按顺序跑：
-
-```
-node scripts/broll/transcribe.mjs <项目目录> [--lang auto] [--terms "词1,词2"] [--no-fix] [--force]
-node scripts/broll/list-cues.mjs <项目目录>
-node scripts/broll/llm_broll.mjs <项目目录> [--style wood-blocks] [--budget 20] [--captions add] [--max-ai 2] [--dry-run]
-node scripts/broll/validate.mjs <项目目录> [--max-ai 2]
-node scripts/make-talk.mjs <项目目录> --out <仓库外目录> [--dry-run] [--provider minimax-h3] [--yes] [--draft]
-node scripts/broll/review-sheet.mjs <项目目录> --out <仓库外目录>
-node scripts/broll/approve.mjs <项目目录> --out <仓库外目录>
-```
-
-`llm_broll.mjs` 加 `--dry-run` 只打印拼好的提示和估算 token，不调接口。`make-talk.mjs` 不自己转写：项目目录里没有 `talk.srt` 时它会停下，告诉你先转写。
-
-## 两种画面
-
-| | 动效画面 | AI 画面 |
-|---|---|---|
-| 写法 | `"source": "motion"` | `"source": "ai"` 或不写 |
-| 费用 | 不花钱 | 按秒计费，见「费用」 |
-| 画面上的字 | 全部照抄原话，脚本逐字核对 | 不放字（生成画面里的字不可靠） |
-| 审片 | 不用审 | 要人看过、自己批准 |
-| 角标 | 没有 | 出现时角落标「AI 生成画面」 |
-| 每段长度 | 1.8–12 秒 | 2.5–12 秒 |
-
-### 动效画面的五种卡片
-
-| 模板 | 什么时候用 | 画面 |
-|---|---|---|
-| `keyword` | 一句要观众记住的话 | 大字关键词（占画面宽度约八成，长了两行），说到哪个字亮到哪个字，重点词扫一道马克笔 |
-| `checklist` | 列两到四样东西 | 清单，说到哪条哪条出来打勾 |
-| `steps` | 讲先后 | 台阶式步骤，说到第几步亮第几步（积木上的点数表示第几步） |
-| `counter` | 报一个确定的数 | 数字滚动，说完这个数时落定 |
-| `compare` | 前后、两种做法对比，先说旧的、后说新的 | 竖版上下两张卡（横版左右两栏），后说的一边胜出。先说新做法的句子别用它 |
-
-卡片上的字必须是原话里连着的几个字，不能改写；摘词前面的否定（不用、不要、不会、don't……）要一起摘；要显示的数字用 `counter`，而且要原话里真说了，隔着空格、换行或分句的两个数不会被拼成一个。所以**转写错的字会照样上屏**：出片前看一眼 `talk.srt`，错字直接改。卡片说完最后一个字后，后面是静音的话会多停一会儿再收。
-
-摆法：动效画面默认 `split`（上 60% 卡片、下 40% 真人），横版用 `pip`，说话的人一直在画面里；`keyword` 不能用 `full`，`full` 只给 3 条以上的清单和步骤，校验会拦。配色和质感跟着主风格走：积木风是暖木色桌面、米白卡片、浅蓝灰和暖橙的木积木，黏土定格是暖粉彩，分层纸艺是米白纸加几层彩纸，手绘线稿（实验）是白纸墨线；背景有很淡的纹理和慢慢漂的形状，装饰只放在字和字幕以外的边角，不加字。version 2 可以在 `broll.json` 顶层写 `motionTheme`（`wood`、`clay`、`paper`、`ink`、`cutpaper-meadow`、`cutpaper-dusk`）换这一支片子的动效外观，不写就沿用主风格。
-
-进出场：真人只有一个画面，`split` 从全屏收到下方、卡片从上面推下来，`pip` 收进右下角圆窗（动效段的圆窗大一点、脸也放大一点，带一圈卡片色描边），出场倒放，不会叠出两张脸。`keyword` 段的字幕和大字说的是同一句时，字幕只留多出来的那几个字，或者不显示。数字是钱（元、块、¥……）又有旧价时不滚动，在说出新价的那一刻直接翻牌，不出现原话里没有的中间价；没有旧价时只在说出来之前滚 0.6 秒。
-
-### AI 画面的风格
-
-| 风格 | 名字 | 适合 |
-|---|---|---|
-| `wood-blocks` | 积木风（默认，木头积木） | 什么都能配，最适合讲步骤、讲数量、讲一样东西 |
-| `clay-stopmotion` | 黏土定格 | 动手做事、点一个地方、给气氛 |
-| `paper-layers` | 分层纸艺 | 讲道理、点一个场景、做对比 |
-| `ink-sketch` | 手绘线稿（实验） | 实验风格，参考图还没出，只能占位预览，不能当副风格 |
-| `brick-diorama` | 塑料积木（实验） | 实验风格，不是默认，生成画面会出凸点，不建议用 |
-
-一部片的 AI 画面最多用两种风格：主风格 `style`，加一个可选的副风格 `styleAlt`（只能选主风格搭得上的）。机器人的形状和颜色写在 `broll/character.json`，所有风格共用；风格只决定它用什么材质做。每种风格能做哪些事、能用哪些镜头、参考图出了没有，见 [`broll/styles/README.md`](../broll/styles/README.md)。
-
-某个风格还没有参考图时，用它真生成会在提交前停下（退出码 2，没花钱），并告诉你换哪个风格、或改成动效画面。用 `placeholder` 预览不受影响。这一版三个正式风格的参考图都已随仓库发布，只有手绘线稿（实验）还没有。
-
-## 三种放法
-
-| mode | 画面 |
-|---|---|
-| full | 画面盖满 |
-| pip | 右下角圆窗露脸，圆窗大小跟着画面大小缩放（动效段大一点） |
-| split | 上面 60% 是画面，下面 40% 是脸。只给竖版 |
-
-## 字幕
-
-| captions | 意思 |
-|---|---|
-| add | 按 `talk.srt` 把字幕加到成片上 |
-| none | 不加字幕 |
-| burned | 口播里已经烧了字幕。只能用 `split`，免得再盖住。横版原片加 `burned` 这一版不支持（`split` 只给竖版），改用 `none` |
-
-`full` 和 `pip` 的字幕在画面下方 1/4；`pip` 段的字幕在圆窗左边放不下时，整段挪到圆窗上方、用满宽度。`split` 的字幕贴在分界线上方，两行字幕会整体往上挪，不压脸。一行字稍长放不下时，字号会缩一点，不让末尾剩一两个字单独成行。
-
-## 转写
-
-- 用的是本机的 SenseVoice 识别模型（通过 sherpa-onnx 运行），不联网、不花钱。模型第一次下载约 240MB，按顺序试魔搭、HuggingFace、hf-mirror 三个源，断了能续传，sha256 对不上的文件不收。
-- 模型放在全局缓存里，所有项目共用：Windows 是 `%LOCALAPPDATA%\brewreel\asr`，macOS / Linux 是 `~/.cache/brewreel/asr`。环境变量 `BREWREEL_ASR_DIR` 改缓存目录；`BREWREEL_ASR_MODEL_DIR` 指向你手动下载好的目录（里面放 `model.int8.onnx` 和 `tokens.txt`），就不再下载。
-- Windows 上下完模型后，第一次加载会多等约 30 秒。
-- 语种默认自动识别。普通话被认成粤语、日语时，用 `node scripts/broll/transcribe.mjs <项目目录> --lang zh --force` 重转。
-- 有 `DEEPSEEK_API_KEY`（或 `LLM_API_KEY`）时，转写完会请便宜模型校对：模型只交「哪个字改成哪个字」的补丁，脚本按读音规则决定改不改。涉及数字、否定、反义的改动只提示、不改；改成专有名词也要读音接近才改。识别器分不出「他」「她」「它」，几乎一律写成「他」：校对会把字幕里的每一个「他」「她」逐个列给模型，问它指的是什么、是不是人，指软件、工具、机器人、动画这类东西的改成「它」，指人的不动（同一次请求里做完，不多调一次接口）。改了什么、指的是什么、哪几句请你听一下原片，都写在 `talk.fixes.txt`。只提示的那几处字不会被做成动效卡片，改过那一句就算核对过。不要校对加 `--no-fix`。
-- 同一个视频放进两个项目各转写一次，校对结果可能不一样（模型每次回答会有出入）；同一个项目重跑用的是缓存，结果不变。
-- 专有名词（产品名、人名）可以写进项目目录的 `talk.terms.txt`，一行一个；或者用 `--terms "词1,词2"`。
-- 已有 `talk.srt` 永远不覆盖。要重转加 `--force`：旧字幕先改名为 `talk.srt.bak-<时间>`，同一个视频不重新识别。
-- `talk.srt` 可以随便改错字，但写好 `broll.json` 之后**不要拆句、并句**：句子号会错位。脚本记下了当时的分句，分句一变校验就会拦下，让你重写 `broll.json`。
-- 转写缓存、分句记录、转码后的原片都放在项目目录的 `.brewreel/` 里。这个目录可以删，删了也能出片，只是动效卡片的逐字时刻会改用估算、分句检查也跟着没了。
-
-自己有字幕也可以直接放 `talk.srt`（剪映等软件导出的 SRT），脚本就不转写。
-
-## 原片自动转码
-
-手机直出的口播常见 HEVC 编码、可变帧率、单声道、旋转标记、29.97 这类非整数帧率。出片前脚本会自动转成 H.264、恒定帧率、双声道的一份，存在项目目录的 `.brewreel/` 下，原片一个字节都不动。转过一次之后直接用缓存。已经是 H.264 恒定帧率的原片不转。
-
-## 费用
-
-只有 AI 画面花钱，动效画面和占位画面都不花钱。花钱前一定先印估价：超过 `budgetYuan` 就停下；没超也要加 `--yes` 才生成。估价同时印出 AI 视频一共多少秒。
-
-MiniMax 的 key 有两种，扣法不一样：
-
-| | 按量付费的 key | 订阅套餐的 key（`sk-cp-` 开头） |
-|---|---|---|
-| 怎么扣 | 按秒扣余额 | 不能按量付费。H3 视频不在套餐额度里，扣的是积分 |
-| 价格 | 768P 0.5 元/秒，2K 0.8 元/秒 | 768P 约 70 积分/秒（2026-10 实测），2K 没实测 |
-| 估价显示 | 「AI 视频共 N 秒，按价目表 X 元」 | 多一句「约 N 积分（订阅 key，从积分扣，以 MiniMax 后台为准）」 |
-| 预算闸门 | 按元拦 | 也按元拦（价目表折算），积分只是多显示一行 |
-
-- 价目表是脚本里写的，不是接口回执（回执里没有金额）。实际扣费以 MiniMax 官网和后台为准。
-- 每段生成秒数由脚本把窗口向上取整，再夹到 4–15 秒。默认最多 2 段 AI 画面，每段最长 12 秒：768P 一部片的 AI 画面大约 2–12 元，订阅 key 大约 280–1680 积分。
-- 风格参考图（image-01）每张 0.025 元，由维护者出好随仓库发，普通用户不用出。
-
-## 审片关卡
-
-`minimax-h3` 的正式片，每段 AI 画面都要人看过。
-
-1. `node scripts/broll/review-sheet.mjs <项目目录> --out <仓库外目录>`
-2. 用浏览器打开输出目录里的 `review.html`。每段一行：原句、风格、提示词、开头 / 中间 / 结尾三帧、费用。最上面一条把每段 AI 画面的中间帧并排放，一眼看出角色和材质前后是否一致。动效段标「动效，不用审」，列出屏幕上的字。
-3. 人自己跑 `node scripts/broll/approve.mjs <项目目录> --out <仓库外目录>`
-4. 再跑同一条命令，出正式片
-
-AI 助手不许替人运行 approve，`talk.mjs` 也永远不跑它。批准记录绑定 `broll.json` 里 AI 画面的部分和每段生成片的 sha256，改了就要重新审；只改动效段不用重审。还没审、先看合成效果，加 `--draft`：AI 画面出现时右上角写「B-roll 未审」。
-
-`placeholder` 和 `local` 不花钱，不用审。
-
-中断了用同一个 `--out` 再跑：已经提交过的段只查询，不重新提交、不重复花钱。「再跑同一条命令」时去掉 `--only`、`--rewrite-broll`、`--force-redo`（脚本印出的下一条命令已经去掉了）。
-
-## 输出目录里有什么
-
-| 文件 | 内容 |
-|---|---|
-| `video.mp4` | 成片 |
-| `sheet.png` | 每段前后、开头、中间、结尾的检查帧拼图 |
-| `check/` | 检查帧原图 |
-| `broll.plan.json` | 计划：每段的时间窗、来源、风格、费用 |
-| `manifest.json` | 交付清单：用了哪个风格、花了多少、字幕是自动转写还是自己给的、原片有没有转码 |
-| `ledger.json` | 账本（只有 AI 画面）：task id、实际秒数、费用 |
-| `review.html` / `broll.review.json` | 审片页和批准记录 |
-
-## 项目目录里多出来的文件
-
-| 文件 | 内容 | 能不能删 |
-|---|---|---|
-| `talk.srt` | 自动转写出来的字幕 | 别删，删了会重新转写，句子号可能变 |
-| `talk.fixes.txt` | 转写校对改了什么、哪几处只提示 | 能删，只给人看 |
-| `llm_log.json` | 便宜模型写 `broll.json` 时每一轮的 token 用量和校验报告 | 能删，排查用 |
-| `broll.llm-error.txt` | 写 `broll.json` 没成功时的最后一份报错 | 能删 |
-| `broll.llm-draft.json` | `--rewrite-broll` 没通过校验时，模型的最后一版（原来的 `broll.json` 没动） | 能删 |
-| `broll.json.bak-<时间>` | `--rewrite-broll` 替换前的旧 `broll.json` | 能删，想回到旧方案就改名回来 |
-| `.brewreel/` | 转写缓存、分句记录、转码后的原片、拿不准的字 | 能删，删了动效卡片的逐字时刻改用估算，分句检查和拿不准提醒也跟着没了 |
-
-## 已知限制
-
-- **实验功能**：还没有用大量真人口播出过完整样片。成片当初稿，发布前整片看一遍。
-- **凸点可能仍会偶发**：新风格的提示词只写想看到的东西，不提凸点，但生成模型偶尔还是会画出带圆点的积木，发布前在审片页逐帧看。`brick-diorama` 会稳定出凸点，只为老项目保留。
-- **手绘线稿 `ink-sketch` 只是实验风格**：两轮出的角色图机器人头顶都有天线，和共用角色对不上，这一版没发参考图，只能用 `placeholder` 占位预览，也不能当副风格。三个正式风格的参考图已随仓库发布。
-- **v0.8 的老文件改成 version 2 要重新花钱**：v2 的提示词和请求都变了，已经生成过的 AI 段会重新生成。老文件留 version 1 照常能跑。
-- **每段 AI 画面单独生成**：共用的角色规格、参考图和 `link: continue` 能让几段看着更接近，但造型和颜色仍可能有出入，不保证段与段完全连贯。
-- **AI 画面最多两种风格**：一个主风格加一个副风格；不能每段换一种。
-- **生成画面里的文字不可靠**：要准确的字请用动效画面。
-- **动效画面的字照抄转写**：转写错的字会上屏，出片前看一眼 `talk.srt`。
-- **英文转写只用合成语音测过**：没测过真人英文口播和口音。英文口播的数字要是阿拉伯数字才能做数字卡片。
-- **macOS 没有实测转写**；Linux、没装 VC++ 运行库的干净 Windows 也没测过。魔搭以外的两个下载源没有实机测过。
-- **口播带背景音乐时**，转写找不到停顿，切句和时间会不准。
-- **10-bit HDR 的手机片**只转了像素格式，没做色调映射，颜色可能发灰。
-- **订阅 key 的 2K 积分价没实测**，估价只写「以后台为准」。
-- **便宜模型写 v2 的 `broll.json` 和转写校对**，还没用 DeepSeek 大量实测。
-- DeepSeek Harness 插件这一版没有接这个能力。

package/skills/brewreel/docs/custom-shot.en.md

@@ -1,66 +0,0 @@
-# Free shots for strong models
-
-Cheap models must not use `custom`. 便宜模型不要用 custom. Keep picking a shot type and filling in text.
-
-This page is for models that can write code. A `custom` shot is one scene whose picture you draw yourself. The storyboard only holds the words and numbers for that scene. The component lives next to `storyboard.json`, never inside `template/`.
-
-It is local skill mode only. The DeepSeek plugin rejects `custom` with: 自由镜头只能在本地用，插件里不运行模型自己写的代码.
-
-## When to use it
-
-Use it when no built-in shot can do the motion, and you can write the React yourself. If you only need to change a sentence or a field that already exists, do not use `custom`.
-
-## Storyboard
-
-```json
-{
-  "type": "custom",
-  "dur": 4,
-  "component": "shots/keyword-toss.tsx",
-  "slots": {"keyword": "少一步"}
-}
-```
-
-- `component` is `shots/<name>.tsx` only. No `..`, no absolute path.
-- `slots` is every word and number that appears on screen. Nesting maxes out at 4 levels.
-- Do not put copy in `params`. Params are not passed to the component.
-- Captions, ad-law words, numbers with units, and bare numbers inside `slots` go through the same checks as other shots. Effect numbers (`from`, `to`, `value`, `percent`, `delta`) need a real `meta.facts` entry. A fact you marked as a sample does not count.
-
-## What the component receives
-
-Import from `../../custom-api`. That relative path is correct after the render step copies the file.
-
-Props: `slots`, `theme` (card, cardText, accent, accentInk, line, …), `geo` (safe, card, cap), `frame`, `fps`, `t`, `dur`, `frames`, `lang`, `beat`, `index`.
-
-Allowed imports: `react`, `remotion`, `../../custom-api`, and a `./` helper in the same `shots/` folder.
-
-`custom-api` re-exports fonts, `fitLine` / `fitSize`, safe-area geometry, `useTheme`, and the talk motion kit: `PaperGrain`, `CutShape`, `Confetti`, `toss`, `entrance`, `leave`, `floatMotion`, `settle`, `shadowByHeight`.
-
-## Why words have to live in slots
-
-Ad-law, number provenance, and length checks only see the storyboard. Before render, the source is scanned. Hard-coded Chinese, an English sentence (two or more words), or a number rendered as JSX (`{12}`, or digits in JSX text) is an error with file and line. The fix is: move it into `slots`.
-
-Numbers that are coordinates, `style` values, or allow-listed attributes (`seed`, `opacity`, `width`, …) are fine. So are numbers used only as math in the function body.
-
-## How a render packages it
-
-Remotion bundles `template/src` only. On render the pipeline:
-
-1. Scans `shots/*.tsx`. Hard-coded copy stops the run before render.
-2. After the render lock, copies `shots/*.tsx` to `template/src/shots/_custom/<film hash>/` (gitignored).
-3. Writes a registry and runs `tsc --noEmit`. A type error is reported at the original file and line. No render.
-4. Renders. A thrown error, text outside the safe area, or a run of blank frames is attributed to that shot. The freeze check from the talk motion checker runs on the main rect of each free shot.
-5. Deletes the copy and restores the empty registry.
-
-Example: `examples/custom/storyboard.json` (a cut-paper keyword toss, and a hand-drawn growing bar).
-
-## Errors you will see
-
-| Message | Meaning |
-|---|---|
-| `shots/name.tsx:12:3` … 挪进 slots | Chinese, an English sentence, or a rendered number is hard-coded |
-| `第 N 镜（custom）shots/name.tsx(10,7): error TS…` | TypeScript failed at that line |
-| `第 N 镜（custom）shots/name.tsx:8：…` | The component threw during render |
-| `出了 x150–930（组件 shots/name.tsx:9）` | Text left the safe area |
-| `动效停死` | A 0.4s window barely moved. Keep a real motion going; a tiny float is not enough |
-| `自由镜头只能在本地用，插件里不运行模型自己写的代码` | `custom` was used inside the plugin |