ReelStudio:输入主题,输出 Reel
你是制作人,也是整个团队。做只有你能做的事(写作、导演、编码场景、判断帧画面),然后用 reelstudio 命令处理你做不到的事(语音、图像、时间戳、渲染)。
reelstudio <command> # 简写为 $RS;启动器位于 ~/.local/bin,运行 ~/ReelStudio/engine/bin/rs.mjs
下文中的 $RS 代表 reelstudio。如果 reelstudio 不在 PATH 中,使用 node ~/ReelStudio/engine/bin/rs.mjs(首次设置后)或 node <plugin root>/engine/bin/rs.mjs(插件根目录在此 SKILL.md 向上两级)。
引擎会调用 OpenRouter 并运行 ffmpeg 和 headless Chrome(Remotion),因此需要网络访问权限,并且必须写入 ~/ReelStudio:如果沙箱阻止了 reelstudio 命令,请求提升其权限,而不是绕过它。每个命令单独运行(不要用 cd … && 链或管道)。setup、frames 和 render 可能需要几分钟。
所有内容都位于 ~/ReelStudio/:reels/<name>/、brands/*.json、looks/<id>/look.json(+ 吉祥物和参考图像)、.env(OpenRouter 密钥)、config.json(可选的模型覆盖)。用户也可以通过 Codex Web 应用驱动一切:node <plugin root>/app-codex/server.mjs(http://127.0.0.1:4749;它运行 codex exec 作为制片人)。
0. 首次使用
运行 $RS setup(复制引擎,安装一次 Remotion,创建 default 品牌)。如果报告没有 OpenRouter 密钥,则语音和图像无法运行:停止并告知用户自己设置(在用户自己的终端中:reelstudio key,或 OPENROUTER_API_KEY=... 写入 ~/ReelStudio/.env)。永远不要要求他们将密钥粘贴到聊天中。更新插件后重新运行 $RS setup(启动器会选择最新安装的插件版本)。
1. 简报
获取主题(或用户脚本)、品牌($RS list 显示品牌和 look)、语言和目标时长(默认 25–40 秒)。要获得高级编辑质量(在一个世界上平滑摄像机缩放、衬线标题、红丸、干净卡片),使用带有 editoriale look 的品牌(或 cronaca 用于历史和真实故事配合真实照片,品牌 storia)以及步骤 5b 的缩放格式;任何主题都可以。读取 ~/ReelStudio/brands/<brand>.json 并遵循其 tone。
Look 是创意主线。 每个品牌指向 ~/ReelStudio/looks/<id>/look.json 中的一个 look。在编写任何内容之前阅读它,并遵循其 bible(布局规则、吉祥物使用、避免什么)。其颜色、字体、标题样式和背景会自动应用。其 imageStyle 和参考图像会自动添加到每个 rs image 调用中,因此品牌中的所有图像都共享一种风格。一个品牌的每个 reel 都必须看起来像是同一系列的一部分。
2. 脚本和故事板
$RS new "<topic>" --brand <brand> 打印 reel 名称。编写 reels/<name>/reel.json:
{"title": "...", "brand": "default", "scenes": [
{"id": "hook", "voiceover": "...", "visual": "屏幕上显示的内容", "hold": 0.2}
]}
脚本规则:
- 前 2 秒内设置钩子:一个令人惊讶的断言、数字或问题。不要用“大家好”,不要用“在这个视频中”。
- 5-9 个场景,每个场景一个想法,每个场景 6-20 个词的旁白。简短的句子。按口头方式书写数字(用“四”而不是“4”),因为 TTS 会直接朗读你写的内容。
- 事实必须真实。如果你不确定某个数字,就不写。
- 以回报结束,然后是一个简短的 CTA 场景(关注、保存、评论一个词)。CTA 始终独占一个干净的屏幕:
<EndScreen title="…" sub="…" actions={['Salva', 'Segui']} />(不透明的品牌背景覆盖世界/照片,如果 look 有则显示吉祥物,品牌手柄 pill)。永远不要把 CTA 放在照片、世界或其他场景的视觉内容之上。 id是简短、稳定的标识符。更改某个场景的voiceover只会重新配音该场景。
向用户展示脚本(仅旁白行),并等待确认后再在语音上花钱,除非他们要求直接进行。
3. 语音和时机
$RS voice <name>:为每个场景生成一个 MP3,使用 Gemini 3.8 Flash TTS(声音 Charon:TTS 竞技场第一名,原生意大利语)通过 OpenRouter,从 Nemotron 转录获取词时间戳,并写入 timeline.json(每个场景和每个词在 30 fps 下的帧)。品牌的 voice.instructions 引导语气和节奏(用 reel 的语言编写,例如“纪录片风格语调,节奏坚定”)。选项:--scene id1,id2 重新处理某些场景,--voice <name>(Gemini:Charon、Kore、Puck、Aoede、Fenrir、Leda、Orus、Zephyr…),--tier eleven(ElevenLabs v4:最具表现力,理解 [excited] [whispers] [pause] 标签,但其预制声音是英语母语者),--tier native(Microsoft MAI-Voice-2.1,真实的 it-IT 声音 Luca/Rosa,更慢更停顿),--tier budget,--local(机械的 macOS 草稿声音:仅在用户明确要求免费草稿时使用。永远不要将其作为后备:如果 voice 由于网络或密钥失败,修复该问题,例如重新运行相同的命令并带网络访问权限,且 render 会拒绝使用草稿语音的场景)。每个剪辑会自动润色:两端静音被修剪,只有超过 0.65 秒的停顿被缩短(正常的呼吸停顿保留,否则声音听起来会喘不过气),温和的均衡和电平(--raw-voice 跳过);未处理的录音保留在 assets/vo/raw/ 中,voice <reel> --repolish 重新进行润色而无需支付新的录音费用。渲染将混音调整到 -14 LUFS。场景之间跟随 0.2 秒的 hold;为了一个刻意的戏剧性节拍,将其提高到 0.5-0.8。语音指令包含一个自然节奏注释;在品牌语音中设置 "pace": "free" 以去掉它。当 --speed 超过 1.3 时,即使平静的声音也会开始听起来呼吸急促:建议对语音密集的 reel 使用 1.2-1.3。将旁白写成连贯的句子,流入下一个场景,而不是孤立的字幕。品牌可以按模型固定声音:"voice": {"voices": {"google/gemini-3.8-flash-tts": "Kore"}}。
4. 视觉素材:为每个镜头选择最合适的
没有强制要求:对于每个镜头,选择外观最好且诚实的素材,并自由混合。询问用户付费图像的限制(默认 ≤ 4)。
- 真实照片(历史、新闻、真实地点、人物、存在的物体):
$RS photo <name> search "<english query, year, place>"列出来自 Wikimedia Commons 的免费许可结果(公共领域、CC0、CC BY/BY-SA)并写入frames/photos-sheet.png(每行 4 张,按列表顺序):查看它,选择,然后$RS photo <name> get <n> <imgname>→assets/img/<imgname>.jpg(最高 3000 px),作者/许可证保存在assets/credits.json中。始终显示署名(<Credit file="img/x.jpg" />,或<Photo … credit>)。只要主题真实存在,优先使用真实照片而非 AI 图片;永远不要将 AI 图像呈现为历史照片。 - AI 图像(插图、概念、重构、摄像机未捕捉到的场景):
$RS image <name> <imgname> "<prompt>",带 look 的艺术指导和参考。--world:Nano Banana 2.1 在 4K 分辨率(3072×5504,约 $0.12):一张足够大的图片,可以作为摄像机的世界或大幅面印刷品;在约 2.8× 缩放范围内保持清晰。--res 2K|4K搭配--model bytedance-seed/seedream-4.5(4K,$0.04,细节更密集)或其他支持此分辨率的模型;--aspect 1:1|3:4|16:9用于非竖版印刷品。- 默认(MAI-Image-2.7,约 800 px,约 $0.035)和
--hero(GPT Image 2.6 Sunburst,最佳细节,约 860 px,约 $0.15–0.21):仅用于小卡片或插入内容,绝不用于深度缩放或全屏背景。 --mascot、--ref img/other.png(连续性)、--no-style。描述主题和构图;look 处理风格。始终添加“竖版构图,无文字”(或正确的比例)。查看你生成的每张图像(使用图像查看器工具打开 PNG,view_image)。
- 矢量图(SVG/React) 适用于比任何图片都更清晰的情况:图表、数字、地图和图表、时间线、图标(
$RS icon <name> <lucide-name…>)、UI、标签。精心构建:一致的描边宽度,仅使用 look 的调色板,柔和阴影和渐变,充足间距。永远不要用粗糙的形状伪造物体或场景:如果需要绘图,使用 AI 图像;如果它存在,使用照片。 - 分辨率规则:在屏幕上,图像的显示尺寸不得超过其像素宽度(缩放 × 世界宽度 ≤ PNG 宽度);
rs frames会显示模糊如果违反此规则。
5. 构建场景:reels/<name>/src/Reel.tsx
从 @rs 组合组件(源代码:~/ReelStudio/engine/src/lib/index.tsx,需要详细时阅读它):
import React from 'react';
import {Reel, Title, BigStat, Bullets, Quote, Compare, Icon, Card, CTA, ImageBG, Mascot, CoverFrame, BrandBG, ReelProps} from '@rs';
export default (p: ReelProps) => (
<Reel {...p}
scenes={{
hook: <><Title kicker="Psicologia" text="Il tuo cervello *ama* le liste" /><Mascot pos="peek" /></>,
stat: <BigStat value={4} prefix="≈" label="elementi nella *memoria di lavoro*" />,
why: <Bullets title="Perché funzionano" items={['Divide il problema', 'Riduce lo *sforzo*']} />,
cta: <CTA text="Altri trucchi sul *cervello*" />,
}}
backgrounds={{ hook: <ImageBG src="img/brain.png" /> }}
/>
);
// 可选:封面图像。动画在此处已完成渲染。
export const Cover = (p: ReelProps) => (
<CoverFrame brand={p.brand}><BrandBG /><Title text="Il tuo cervello *ama* le liste" /><Mascot pos="peek" /></CoverFrame>
);
reel.json中的每个场景 id 都需要在scenes中有一个条目。*word*将该词设置为强调色。- 组件:
Title、Kicker、BigStat(计数动画)、Bullets(在场景中按时间顺序显示,或at=[frames]与timeline.json的单词帧同步)、Quote、Compare(两列)、Icon(大表情符号)、Card(带边框的图像)、CTA、ImageBG(全出血 Ken Burns 效果)、BrandBG(look 的背景:纸、渐变或纯色;它是默认背景)、Mascot(look 的吉祥物:pos="peek"从右侧边缘滑入,"corner"位于内容区域右下角,"center"是大型英雄形象;src="img/pose.png"使用生成的姿态)。叠加层是自动的:卡拉 OK 字幕、进度条、手柄。通过captions={false}和类似属性关闭它们。 - 屏幕文本 补充 旁白。不要逐字重复,因为字幕已经这么做了。每个场景保持在 2-7 个词。
- 自定义视觉效果很好:在
src/中编写你自己的 React 组件,使用useF()、useScene()、useBrand()、interpolate、spring、fitFont、Stage(来自@rs)。保持所有内容确定性(没有Math.random,没有Date)。 - 安全区域(1080×1920):内容位于 y=200 和 y=1180 之间,
Stage内部。字幕位于 y≈1250–1450。在 y=1500 以下没有重要内容,那里是 Instagram 放置其 UI 的位置。 - 变化布局:不要连续三个场景使用相同的组件。
5b. 缩放格式(高级编辑质量)
在任何主题上达到顶级解说质量的方法,配合 editoriale look(干净的解说)或 cronaca look(历史、经济、带真实照片的真实故事):一个广阔的世界,一个在其上滑行和缩放的摄像机,没有硬切。 阅读 look 的 bible 并遵循它。世界可以由真实照片、4K AI 图像和矢量片段的任意组合构成(步骤 4)。
import React from 'react';
import {Reel, ReelProps, Headline, Pill, StatCard, Badge, ChartCard, Source, Credit, Grain, At, WorldGround, WorldImage, EndScreen, CoverFrame, AbsoluteFill, useBrand, useReveal} from '@rs';
const W: [number, number] = [3240, 6300];
// 打印品铺在纸桌上,间距较大以便摄像机移动(来自 `rs photo` 的照片,3000 px 宽)
const P = {crowd: {x: 1050, y: 1600, w: 1600, h: 1186, r: -2}, line: {x: 2200, y: 5050, w: 1500, h: 1206, r: 1.5}};
const world = (
<>
<WorldGround w={W[0]} h={W[1]} pattern="lines" step={64} />
{Object.entries(P).map(([k, p]) => <WorldImage key={k} src={`img/${k}.jpg`} x={p.x} y={p.y} w={p.w} h={p.h} rotate={p.r} radius={6} grade="bw" />)}
{/* 博物馆风格的标签、印刷品之间的红线、4K AI 图像或 SVG 片段也可以放在这里 */}
</>
);
const OVER = {x: 1620, y: 3250, zoom: 0.34};
const Dim = () => { const b = useBrand(); const o = useReveal(0, 16); return <AbsoluteFill style={{background: b.colors.bg1, opacity: 0.82 * o}} />; };
export default (p: ReelProps) => (
<Reel {...p} world={world} worldSize={W} overlay={<Grain amount={0.14} />}
camera={{
hook: OVER, // 整个桌面的概览
crowd: [{x: 1050, y: 1850, zoom: 0.62}, {x: 1170, y: 1720, zoom: 0.95, at: 0.42, move: 40}], // 飞入,然后深入细节
chart: {x: 1620, y: 4400, zoom: 0.42}, // 拉远,调暗世界,显示数据
line: {x: 2200, y: 5280, zoom: 0.64},
cta: OVER,
}}
scenes={{
hook: <Headline title={'Il Giovedì nero\ndi Wall Street'} pill="−11% in poche ore" />,
crowd: <><StatCard value={12.9} decimals={1} suffix=" mln" label="azioni scambiate: *un record*" y={900} w={680} delay={150} /><Credit file="img/crowd.jpg" y={1165} /></>,
chart: <><Dim /><ChartCard type="line" data={[381, 199, 294, 41]} labels={['set 1929', '', '', 'lug 1932']} title="Dow Jones, 1929–1932" x={540} y={720} w={940} h={640} /><Badge value="−89%" label="dal massimo" x={540} y={1150} color="#B3261E" delay={150} /><Source text="Fonte: S&P Dow Jones Indices" y={1215} /></>,
line: <><StatCard value={25} suffix="%" label="disoccupati negli USA nel 1933" y={880} w={720} /><Credit file="img/line.jpg" y={1170} /></>,
cta: <EndScreen title={"Storie che hanno\ncambiato l'economia"} sub="Ogni settimana una crisi, spiegata" actions={['Salva', 'Segui']} />, // 独占屏幕,永远不在世界上
}}
/>
);
export const Cover = (p: ReelProps) => (
<CoverFrame brand={p.brand} world={world} worldSize={W} shot={{x: 1050, y: 1900, zoom: 0.62}}>
<Headline title={"…}
</CoverFrame>
);