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.5.1
Brew great promo reels
with low-cost models
Write a product brief; the AI picks the shots and writes the copy, and one command renders a vertical promo video (1080×1920, the format Douyin and WeChat Channels use).
Install it as a skill for Claude Code, Codex or opencode, use the DeepSeek Harness plugin, or run the plain script with no agent.
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 for AI-assisted promo video production. You provide a product brief and assets, a language model writes the storyboard, and code renders the video locally using a style recipe. Review the result before publishing.
- Who it is for
- Developers and creators comfortable setting up a local runtime, making product introductions, feature explainers, quiz videos or character-journey promos.
- Inputs and outputs
- Inputs are a product brief, optional real photos and voiceover settings. Outputs include a promo video and its storyboard record. The cards and quiz recipes default to 1080×1920; journey defaults to 1080×1350, all at 30 fps.
- Costs and requirements
- The project uses Apache-2.0. Model and voiceover APIs may charge separately. 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.
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.02Get started
Install, run a sample,
then hand it to the AI
Set up the render environment and run one of the bundled samples first, then pick how the model writes your storyboard.
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
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.
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-chat
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.
No.03How 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.
No.04Industry 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.05Known 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.
- Not supported: medical aesthetics, prescription drugs / medicine, K12 academic tutoring, supplement efficacy claims, tobacco.
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: brand-color numbers on dark themes can have too little contrast, and 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.06Why "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.07FAQ
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 use your own API key and are billed by the provider for what you use; the project handles no money. Rendering runs on your own computer. The rendering engine Remotion charges for-profit organizations with 4 or more people; see the Remotion question below.
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.