Cardscards
- Aspect
- 9:16
- Signature
- Gradient background, a centered white card and bold outlined captions; one point per shot
- Fits
- A single selling point, a how-it-works flow, UI demos, physical products and stores, price lists
Apache-2.0 · Commercial use OK · Previewv0.16.0
Brew great promo reels
with low-cost models
Two paths, each one command: write a product brief and render a vertical promo, or drop in one talking-head clip and get pictures that explain it.
For a promo, install it as a skill for Claude Code, Codex or opencode, use the DeepSeek Harness plugin, or run the plain script with no agent. Talking-head B-roll is a separate command.
Still a preview: treat each video as a first draft; watch it all and edit before you publish. How far along it is
What is BrewReel?
BrewReel is an open-source tool with three paths. Promo: you provide a product brief, a language model writes the storyboard, and code renders it locally from a recipe. Talking-head B-roll: you provide one talking-head video, and one command adds motion cards or AI pictures. Lesson videos: 16:9 animated slides with a presenter. Review either result before publishing.
- Who it is for
- Developers and creators comfortable setting up a local runtime. Use it for product introductions, feature explainers, quiz videos or character-journey promos, or to add explanatory pictures to a talking-head video you already have.
- Inputs and outputs
- Promo: a product brief, optional real photos and voiceover settings in; a vertical promo and its storyboard out. cards and quiz default to 1080×1920, journey to 1080×1350, all at 30 fps. Talking-head B-roll: one talking-head video in, a video with pictures out. The output directory must sit outside the repo.
- Costs and requirements
- The project uses Apache-2.0. Promo model calls and voiceover APIs may charge separately. For talking-head B-roll, on-device transcription, motion cards and the final cut do not charge; AI pictures use MiniMax, print an estimate first, and need a person's approval before the official cut. Remotion has a separate license; for-profit organizations with four or more employees need a Company License.
Project author: Finderchangchang. See the GitHub documentation for installation, test records and known limitations.
Three ways
No.01
Promo video
Write a product brief, let a cheap model write the storyboard, and render a vertical promo with one command. Three recipes, six industries.
No.02 Talking-head B-rollDrop in one talking-head video. One command adds motion cards or AI pictures.
No.03 Lesson videos16:9 lessons: animated slides with a presenter in the corner, 20 layouts, re-render only the page you changed, and vertical clips.
No.01The recipes
Three recipes. Pick one by content.
Set meta.style in the storyboard to pick a recipe; leave it out and you get the default, cards. Each recipe ships its own design tokens, shot components, validation rules and narrative templates.
Cards
Quizquiz
- Aspect
- 9:16
- Signature
- Circle a common misconception in red pen → a countdown question → the reveal → a dictionary card
- Fits
- A common misconception you can frame as one multiple-choice question with exactly one right answer ("What does X actually mean?")
Journeyjourney
- Aspect
- 4:5 (default) / 9:16
- Signature
- Our own red-panda mascot rides a hover board through a paper-cut city in one take, with a postcard at every stop and a punched ticket at the end
- Fits
- 4–6 clear categories, features or stops worth touring along one route
How to choose
- One multiple-choice question
quiz - 4–6 categories to tour
journey - Anything else
cardsthe default
No.02Talking-head B-roll
One talking-head clip,
pictures from one command
If you already have a talking-head video, you do not write a brief. After on-device transcription, DeepSeek picks a picture for each line: a motion card, which does not charge, or an AI picture. Scripts handle timing, cost and the final cut.
Available since v0.9
node scripts/talk.mjs <project-dir> --out <output-dir>Put talk.mp4 in the project directory. The command transcribes on your machine (the first run downloads about a 240MB model), asks DeepSeek to pick a picture per line, then renders. The output directory must sit outside the repo. AI pictures default to 2 clips at most. The first pass is a stand-in and does not charge; real MiniMax generation prints an estimate first, and a person reviews the sheet and approves before the official cut. Talking-head B-roll needs a full ffmpeg.
Two kinds of picture
Motion cards
These do not charge. Every word is copied from what was said, and it lights up as that word is spoken. From v0.11 there is an optional cut-paper look: paper grain, hand-cut cards that toss up on key words and land. From v0.12 every render is checked for motion that freezes or flickers, and a failing video is not delivered.
- Keyword
- Checklist
- Steps
- Number
- Compare
AI pictures
Small scenes from MiniMax H3. The whole video shares one robot. Two AI clips at most, by default. Ink sketch is experimental and only a stand-in preview.
- Wood blocks · default
- Clay stop-motion
- Layered paper
- Ink sketch · experimental
An estimate before anything is spent
Motion cards, on-device transcription and the final cut do not charge. AI pictures print an estimate first, and a person approves before the official cut. A MiniMax subscription key is shown in credits: about 280 credits for 4 seconds. MiniMax's own dashboard is what counts.
Style factoryv0.10
One sentence, one AI picture style
Describe the material and the color in one sentence. The script drafts an AI picture style. The vision check is only the first screen. A person decides whether it is kept.
DeepSeek writes the config and reference images are generated. MiniMax looks at the pictures and checks for text, studs, resemblance to a known work, a mouth, an antenna, and an empty frame. The script picks images, then makes one still. An optional 4-second video test spends credits. Then there is a review page.
node scripts/broll/new-style.mjs --id <id> --name "<name>" --desc "<one sentence>"Without --yes it only prints the requests it would send. Add --yes after you confirm. A 4-second video test needs both --video and --yes, and it prints about 280 credits before submitting. node scripts/broll/approve-style.mjs <id> can only be run by a person in a terminal. An assistant must not run it. Styles you make are welcome back as contributions.
No.03Get started
Install, run a sample,
then hand it to the AI
Set up the render environment and run one of the bundled samples first. For a promo, then pick how the model writes the storyboard. Talking-head B-roll uses the third command below.
1Install and run a sample
git clone https://github.com/Finderchangchang/brewreel.git
cd brewreel/template && npm install && npx remotion browser ensure
cd .. && pip install numpy scipy imageio-ffmpeg
node scripts/validate.mjs examples/en-focus.json
node scripts/make.mjs examples/en-focus.json --out ../brewreel-out/en-focusnpm install installs the rendering engine and npx remotion browser ensure downloads Chrome Headless Shell once. If the validate command passes, your setup is good; the render takes a few minutes and is done when the last line reads 交付：<mp4 path> ("delivered"). --out must not point inside the repo. Talking-head B-roll also needs a full ffmpeg: imageio-ffmpeg in that install is that build. The slim ffmpeg bundled with Remotion is missing filters and is not enough.
2Let the AI write the storyboard. Pick one.
As a skillReady
For AI coding assistants that read SKILL.md. Clone the whole repo into ~/.claude/skills/brewreel/ (Claude Code) or ~/.agents/skills/brewreel/ (a common convention), hand the assistant a brief (template: brief-template.md) and let it follow SKILL.md.
Install as a Claude Code skill
git clone https://github.com/Finderchangchang/brewreel.git ~/.claude/skills/brewreelOptional: route Claude Code to DeepSeek (swap in your own key)
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=<your DeepSeek API key>
export ANTHROPIC_MODEL=deepseek-flash[1m]Headless scriptReady
The script calls an OpenAI-compatible endpoint directly (DeepSeek by default): brief in, video out. Validator errors go back to the model verbatim for a retry, up to 3 times.
export LLM_API_KEY=<your DeepSeek API key>
export LLM_BASE_URL=https://api.deepseek.com
export LLM_MODEL=deepseek-flash
python scripts/llm_make.py path/to/brief.mdOn Windows PowerShell use $env:LLM_API_KEY="..." instead of export. These are placeholders: use your own key, and never commit a key or paste one into an issue. With --dry-run it calls no API and reads no key; it only writes out the assembled prompt and estimates its token count.
DeepSeek HarnessPublished on npm
Published on npm. The plugin has not yet been tested against a real DeepSeek model; please open an issue if you hit problems.
With the plugin installed, the model writes the storyboard by following the skill and uses the plugin's 7 tools to validate, render and verify: check the environment, install dependencies, list recipes and industries, read the docs, validate the storyboard, render in the background with progress, and check the video. Needs dsh 0.1.7-rc.2 or later within 0.1.x (dsh's latest tag on npm still points to the older 0.1.5-rc.3, so pin the version when installing), Node.js 22.x from 22.19 or 24+, and pnpm.
npm install -g @deepseek-ai/dsh@0.1.7-rc.2 pnpm # if dsh is not installed yet
dsh plugin --profile web add dsh-brewreel
dsh webweb can be any profile name; if the profile is already running, restart it for the change to apply. On first use, ask the model to "check the video plugin environment": it calls doctor, and after you agree, calls setup to install the render dependencies. To use unreleased code, clone the repo and run dsh plugin --profile web add ./brewreel/integrations/deepseek-harness from the folder that contains the clone. This version of the plugin does not include talking-head B-roll.
3Talking-head B-roll
node scripts/talk.mjs <project-dir> --out <output-dir>Put talk.mp4 in the project directory. The output directory must sit outside the repo. The first transcription downloads about a 240MB model. Pictures, cost and limits are in Talking-head B-roll.
No.04How it brews
The model fills in one storyboard.
Recipes and scripts do the rest.
Good beer comes from a good recipe. A strong model first turns a style into a recipe: ready-made components plus validation rules. A low-cost model like DeepSeek follows it to fill in the storyboard, and scripts handle validation, music, rendering and QA.
-
01You
Write a brief
You or the merchant fill it in, from the generic template or one of the six industry templates.
brief.md -
02You or the model
Pick a recipe
meta.stylepicks the recipe,meta.industrythe industry pack.meta -
03Cheap model
Write the storyboard
One JSON file: pick shots, fill in text. No code, no coordinates.
storyboard.json -
04Scripts
Validate
Hard rules plus ad-law and industry compliance. The report names the shot and field to fix, and goes back to the model.
validate.mjs -
05Scripts
Brew
Music → render → contact sheet → check frames → manifest. Any ✗ means no delivery.
video.mp4 -
06You
Human check
Photo rights, genuine reviews, price conditions: things a machine can't judge, confirmed by the publisher.
checklist
Also in the recipe
Compliance checked first
Dozens of checks cover ad-law superlatives, rules for six industries, line wraps and safe areas, and every error says what to fix.
A ✗ means no delivery
Layout, blank frames, Chinese characters in an English video: any failed self-check blocks delivery. Every video ships a
manifest.jsontied to its storyboard.Music made on the spot
Original music is synthesized by code, hits the shot cuts and is normalized to -16 LUFS. No copyright issues.
Chinese and English
Bilingual docs; captions in Chinese or English. English videos are scanned every half beat, and any Chinese character blocks delivery.
Voice-over, three providers
Write
meta.voiceand onevoline per shot to get a voice-over from MiniMax, Alibaba Cloud or Volcengine. Shot lengths follow the narration, subtitles light up word by word, and the music ducks about 10 dB under speech; each line is synthesized only once, so changing visuals or re-rendering costs nothing more.Charts and colors
A data-chart shot can draw a bar, line, dot, stacked or donut chart. Every number on it has to appear in the cited facts. cards also has 12 optional color sets; if you do not pick one, an old storyboard renders as before.
No.05Industry packs
Six industry packs, with compliance checked first
Pick an industry with meta.industry. Each pack comes with compliance rules, a recommended shot structure, a brief template for merchants and a regression-test brief.
SoftwareApps, SaaS, tools software
FoodRestaurants, stores, single-item launches food
EcommercePhysical goods ecommerce
EducationAdult vocational training (not K12) education
BeautyNon-medical beauty services beauty
TravelTourism, lodging, homestays travel
Validation blocks
- Ad-law superlatives
- Numbers without a source
- Dropped price conditions
- Illustrations passed off as photos
Not supported
- Medical aesthetics
- Prescription drugs / medicine
- K12 academic tutoring
- Supplement efficacy claims
- Tobacco
The compliance rules don't cover these, so results aren't guaranteed compliant even if you force them.
No.06Known limitations
How far along it is
It's a preview. Here is where things honestly stand; read this before you use it.
Preview
We don't yet recommend publishing a video as rendered, without human edits.
Testing and fixes are ongoing. Treat each video as a first draft: watch it all, edit, then publish. Passing validation alone is not enough.
Recommended use: for industry videos, use the merchant's real photos where you can and pass --brief <brief> when rendering; before delivery, check every price, condition, date, opening hour and distance on screen against the brief.
Cheap-model test: 9 videos, none reached 7
In the round before v0.2.0, a small model played the cheap model: given only the brief and SKILL.md, it wrote each storyboard from scratch, validated and rendered. 7 is the score we set as "fine to publish as is".
| Category | Overall | Compliance |
|---|---|---|
| Software / tools | 5–6 | 7–8 |
| Industry videos | 4–5 | 4–5 |
- quiz / journey not re-tested after the fixes: each recipe was tested with 3 videos and the problems the review listed were fixed, and the sample storyboards passed validation and delivery checks again; but the cheap model hasn't re-run a scored round, so the published scores are still from before the fixes. Nobody has listened to journey's music and sound effects yet.
- Alibaba Cloud and Volcengine voice-over not yet tested with a real key: both follow the official docs and are unit-tested against fake responses built from them; where the timestamps sit in the stream and whether the default voices work will be confirmed on the first real call. MiniMax has been rendered with a real key for all three recipes.
- Real voices read slower than the estimate: validation assumes 5 Chinese characters per second, while MiniMax's real voices measured about 4 per second, so a long line that passes validation can still be blocked at render time (it tells you how many characters to cut in which shot). Plan narration at about 4 characters per second.
- Illustrations only without real photos: with no merchant photos, the visuals come from components and illustrations, which hurts industry videos most.
- The DeepSeek Harness plugin has not been tested against a real DeepSeek model yet. This version also does not include talking-head B-roll.
- Not supported: medical aesthetics, prescription drugs / medicine, K12 academic tutoring, supplement efficacy claims, tobacco.
- Ink sketch is still experimental: its reference images did not ship with this version. It can only be a stand-in preview. It cannot be really generated, and it cannot be the secondary style.
- The character may differ slightly from clip to clip: each AI picture is generated on its own. A shared robot spec brings clips closer, but shape and color are not guaranteed to match.
- A transcription error shows up on the motion card: words on the card can only be copied from what was said. Read
talk.srtbefore you publish, and fix mistakes there. - macOS, and real English speech, are untested: transcription has not been tested on macOS. English was tested only with synthetic speech, not with a real English speaker or an accent.
- Talking-head B-roll needs a full ffmpeg: the copy bundled with Remotion is a slim build and is missing filters. Install
imageio-ffmpeg(pip install imageio-ffmpeg), put ffmpeg on PATH, or point theFFMPEGenvironment variable at it.
Main remaining problems (8)
- Price conditions can be bypassed by deleting facts: checks on price conditions, date ranges and surcharges only apply to what the model itself put in
meta.facts. - Components can silently drop data: e.g. the mockApp dashboard shows only the rows that fit and ignores unsupported fields; validation reports neither.
- Truthfulness of locations and illustrations: the model still invents claims like "a 3-minute walk", and validation doesn't yet catch every illustration that doesn't match its label.
- Template feel: different videos often share the same cover, default line chart and white end card, with only the text and colors changed.
- Copy quality isn't checked automatically: words cut in half, awkward phrasing, a selling point repeated three times, or contradictions all get through.
- The core action isn't required on screen: for a tool, an action like "tap Start" may end up shown as an unrelated screen.
- Layout: some panels leave their lower half empty when there is little content.
- Coverage of English and asset checks: the compliance word lists are written for Chinese, so English copy is checked less thoroughly; assets are only checked at the file level.
No.07Why "BrewReel"
Good beer comes from a good recipe,
even with ordinary ingredients
A strong model first gets a video style right; its layout, motion, pacing and rules are then written down as a "recipe": ready-made components plus a validator. A low-cost model like DeepSeek is the ordinary ingredient: it follows the recipe, fills in a storyboard, and brews a video at the same level.
- Recipe
- a style pack
- Crafting a recipe
- deriving a style from a reference video
- Brewing
- rendering
Paths and fields keep their original names: styles/, meta.style, distill/.
Brew your own, share the recipe
- Use
Brew with an existing recipe.
- Remix · reskin
node scripts/gen-styles.mjs --new <id>scaffolds a new style; change the palette, fonts and characters. For a color-only variant, editingtokens.jsonis enough. - Create · craft a recipe
Follow the six-step process in
distill/to break down a reference video: extract frames, break it down, replicate, redesign, componentize, then test with a cheap model and review.
Redesign + originality check is a required step
The skeleton may stay: narrative structure, rhythm, motion, camera language. The skin must be redone: palette, characters, signature details. check-originality.mjs measures the color difference from the reference (CIEDE2000), and every signature item must say what replaced it or that it was removed.
Practical guides
Setup steps and examples you can refer to when using the project.
Make your first BrewReel promo video: run a sample, then use your own product
Set up the local renderer, validate and render an existing storyboard, then move to a product brief and a human review before publishing.
Write a product brief for an AI promo video: template and fictional café example
Specify the audience, product action, supported claims, price conditions and asset sources. Download a blank Markdown brief and a clearly fictional example.
No.08FAQ
Asked before
the first brew
Didn't find your answer? Open an issue, or message the WeChat Official Account.
Can I publish the video as rendered?
Not yet recommended. Treat the video as a first draft: watch the whole thing, fix awkward copy and repeated selling points, then publish. For industry videos, check every price, condition, date, opening hour and distance on screen against the brief. See "How far along it is" for test results.
Does it cost anything?
The project is free and open source. Model calls, voiceover APIs, and AI pictures in talking-head B-roll use your own key and are billed by the provider; the project handles no money. Rendering runs on your own computer. Motion cards, on-device transcription and the final cut do not charge. The rendering engine Remotion charges for-profit organizations with 4 or more people; see the Remotion question below.
What does talking-head B-roll cost?
Motion cards, on-device transcription and the final cut do not charge. AI pictures use MiniMax H3. An estimate is printed first, and a person approves before the official cut. Two AI clips at most, by default. A subscription key is shown in credits, about 280 credits for 4 seconds. A pay-as-you-go key is billed per second; the price table says 0.5 yuan per second at 768P. Under the default cap, the AI pictures in one video are about 2–12 yuan on that table, or about 280–1680 credits on a subscription key. What MiniMax actually charges is whatever its dashboard shows. DeepSeek uses your own key to write the plan.
Can I make another style?
Yes. You can draft one. The style factory takes the material and the color in one sentence:
node scripts/broll/new-style.mjs --id <id> --name "<name>" --desc "<one sentence>"
DeepSeek writes the config and reference images are generated. MiniMax checks the pictures for text, studs, resemblance to a known work, a mouth, an antenna, and an empty frame. The script picks images and makes one still. An optional 4-second video test spends credits. A person looks at the review page. approve-style.mjs can only be run by a person in a terminal. An assistant must not approve it. Styles you make are welcome back as contributions.
The shipped regular styles are wood blocks (the default), clay stop-motion and layered paper. The whole video shares one robot. Ink sketch is still experimental and only a stand-in preview.
Can I use it commercially? Do I need to credit it?
Yes. It's Apache-2.0: individuals and companies may use, modify and redistribute it, or build it into their own products, with no fee and no prior permission. If you redistribute it or build on it, keep LICENSE and NOTICE and credit the source. Suggested wording:
Based on BrewReel (精酿, https://github.com/Finderchangchang/brewreel)Videos you render with it don't require attribution. Don't use the names "BrewReel" or "精酿" or the brewreel.com domain to imply your work is made or endorsed by the original author. Remotion, which does the rendering, has its own license; see the next question.
Does Remotion need a license? What about upgrading to 5.0?
Remotion is source-available, not open source: free for individuals, for-profit companies with 3 or fewer people, and non-profits (including commercial use); for-profit organizations with 4 or more people must purchase Remotion's Company License, see remotion.dev/license. This repo's Apache-2.0 license doesn't change Remotion's own terms.
This repo pins remotion / @remotion/cli to 4.0.529. After upgrading to 5.0, Remotion's free tier requires a licenseKey in config (individuals / companies with 3 or fewer people / non-profits use free-license); read THIRD_PARTY_LICENSES.md before upgrading.
Where does the background music come from?
scripts/make_bgm.py synthesizes it on the spot with numpy / scipy: instruments, harmony, melody, mixing and mastering all live in the script, with no external sample library. Each shot is one section, notes land on whole or half beats, and every shot change gets a cymbal or a fill, so the music follows the cuts. Loudness is normalized to -16 LUFS.
Because it's synthesized on the spot, there are no copyright issues. When you publish on a platform such as Douyin, you can also render a silent version with --no-bgm and add music on the platform.
Is there a voice-over?
Yes. v0.5.0 added MiniMax text-to-speech, and from v0.5.1 you can also use Alibaba Cloud (Model Studio CosyVoice) or Volcengine (Doubao speech). Write meta.voice and a vo per shot, set the matching environment variable (MINIMAX_API_KEY / DASHSCOPE_API_KEY / VOLCENGINE_TTS_API_KEY), and render. Shot lengths follow the narration, subtitles light up word by word, and the music ducks under speech. Without a key, add --voice-provider mock to preview the rhythm with a placeholder voice. Without meta.voice there is no voice-over, as before. When you publish with an AI voice, tick the platform's AI-generated content declaration as it requires.
Why illustrations instead of real footage?
The project doesn't generate images that look like real photography. Without merchant material, the video falls back to components and simple line illustrations and labels them clearly, rather than passing them off as real photos. With the merchant's real photos (store, finished product, price list), use the real-photo shots; the result is far more convincing. Whether a photo is authorized goes on the human-review list.
Chrome Headless Shell fails to download?
npx remotion browser ensure may not reach Google's download endpoint from some networks. Download it manually and point to a local Chrome / Chromium with --browser-executable (results may differ slightly between Chrome versions).
Anything to watch for on Windows?
x64 only. Set environment variables the PowerShell way, $env:LLM_API_KEY="...", not export. Always pass storyboards as a file path, never as inline JSON on the command line (the Windows shell mangles the quotes). make.mjs calls python on Windows; if yours lives elsewhere, point the PYTHON environment variable at it.
Brew great promo reels with low-cost models.
Open source and free for commercial use. Star it so you don't miss new recipes.
We want to hear real needs: what product do you want a video for? Which recipe or industry is missing? Which compliance rule got in your way? Message the Official Account or open an issue.
Validation rules that block too much or too little, render errors, frames that look wrong. Attaching the storyboard JSON and the error output helps most. Never paste an API key.