video-director-previs
在最便宜的阶段做出昂贵的创意决策。本技能负责预制作:导演、故事、剧本、故事板、风格帧、动画分镜、音乐、音效、配音、引擎选择、质量审查、版本和批准。引擎(HyperFrames、video-shotcraft、Remotion、motion-reel、bang-motion、Diffusion Studio)仅构建所有者已批准的内容。
工作示例:examples/crumb-previs/(一个虚构的分摊账单应用)。其数据包位于 Previs Studio 中的演示影片(_shared/previs/studio/films/011-crumb/)。
应用本身不因影片而改变。 Previs Studio 是一个固定的 React + TypeScript 应用(源码 _shared/previs/app/,请参阅其 README)。在那里运行 npm run build 会进行类型检查、打包并将其内联到 _shared/previs/studio/index.html 和 _shared/previs/page/index.html(模板);在 scripts/inline.mjs 中为每个影片的目标页面添加目标。npm run smoke 会在真实的 Chrome 浏览器中以桌面、平板、手机和全屏模式驱动构建好的页面(使用 --out 截屏)。切勿手动编辑构建好的 index.html。
所有者将获得:观看(带有真正全屏的视频风格播放器、悬停擦洗预览、片尾卡;评论模式可命名指针下最小的部分,滚动以放大或缩小,框选多个部分,笔和箭头工具,拖拽镜头行以选择时间范围;带有波形、节拍、压缩曲线的音轨,独奏/静音/音量控制和可拖拽到节拍的音效)、选择(可原地重放其时刻的声音)、并排比较、长按听原始声音、故事板(可原地播放镜头的卡片、全部播放、每镜头选择、镜头表)、计划(总导演、故事、导演团队、外观、声音、资产、制作、检查、版本及“请求撤销”、规格导出)、引导式审查、询问导演、⌘K 搜索、撤销/重做、亮色和暗色主题、每个控件上的工具提示。影片仅以数据包形式到达。
两个住所,同一个应用
- Previs Studio(所有影片):
_shared/previs/studio/。添加一部影片 = 添加films/<id>/previs.json+films/<id>/audio/...以及films.json中的一行。本地运行:python3 -m http.server --directory _shared/previs/studio(或使用.claude/launch.json中的previs-studio条目)。 - 每部影片页面:
projects/NNN/previs/page/包含相同index.html的副本(标题<Product> Previs)、films.json中path为""的一行、previs.json和audio/。 - 作为 claude.ai 工件(仅限 Claude): 使用以下配置发布页面:
capabilities: {"db": {}, "user": {}, "sample": {}, "comments": {}, "downloads": true}。db存储笔记和选择,sample支持“询问导演”,comments承载“发送给 Claude Code”,downloads支持规格导出。没有它们,页面仍然可以工作并在浏览器中保存。 - 数据库路径:comments(附加到影片的更改请求;集合保留旧名称)
films/<id>/notes(kind包括帧、区域、范围、声音、镜头、还原或请求;target、targets、box、strokes、quick芯片、t/t2、picks和当时的version);选择和声音调整films/<id>/state/picks(tweaks:<scene>.<sfx>{dt, db},lane.vo|music|sfx{db},mix.duck{on});添加的选项films/<id>/state/custom;批准films/<id>/state/approval;Claude 的状态films/<id>/state/claude;活动films/<id>/activity;笔记(关于整部影片的自由想法:作为背景阅读,不作为任务)films/<id>/pad。
库:按需提供超过三个选项
每个决策都提供三个导演选项;D['libraries'] 会添加审阅者(或“询问”标签页)可以引入的更多内容:direction(外观:令牌集 + fonts_url)、music(CC0 背景乐,包含 bpm、phase、tags、level)、motion(ease、spring {f,d} 或 bezier)、pacing、camera、transition、sfx(影片中的每个声音)和 voice(Fish 语音:dir、durs、其他语言的 texts、intro、sample)。全局 voice 决策选择叙述者;一个语音将每行文本解析为 <dir><scene>-<A|B|C>.mp3;带有 needs 且没有 dir 的语音在录制之前会作为字幕播放。添加的选项存在于页面数据库中,可撤销,并会进入已批准的规格。以 examples/crumb-previs/libraries.py 为模型构建库:
- 音乐:搜索 Freesound CC0(
freesound.py search ... --min-dur 20)、freesound.py get,然后运行python3 _shared/previs/music_lib.py <page>/audio/music/lib <oggs>(节拍对齐的 24 秒片段,已测 BPM);为每个背景乐编写标签和理由;在_shared/ASSETS.md中添加账本行。 - 语音:使用
search_voices选择公共 Fish 语音(无真实人物或角色克隆),在voices/voices.tsv中列出,编写voices/lines-<lang>.txt,运行voices/make_voices.sh(免费模型),然后使用 whisper-cli 抽检录制片段,若有单词遗漏则重新生成。 - AI 导演(“询问”标签页,
lib/director.ts)还可以设计外观(对比度检查,允许的 Google 字体)、运动感觉和新的台词措辞(这些需要录制:它会为 Claude Code 提交一个请求笔记)。
Claude Code 处理笔记的职责(每轮执行)
所有者从页面发送笔记(“发送给 Claude Code”:一个实时评论,会唤醒正在观察的会话,或一条复制的消息)。然后:
0. 修改前先拉取。 claude.ai 上的 Claude 可以自行回复“发送给 Claude Code”线程、编辑数据文件并发布新版本。在构建之前,读取已发布的 previs.json,与本地构建进行比较,并将任何更改移植到 build_previs.py 中,以便下一次构建保留这些更改。
- 设置
films/<id>/state/claude {state:"reading"|"working"|"publishing"|"idle", at, message, version, open},以便页面显示您正在做什么。 - 对于每个公开笔记:读取时
update为claude: {state:"seen"},更改时为{state:"working"},然后设置为status:"done"、claude:{state:"done", at, msg},并在replies中追加{by:"claude", text, at}(如果if_version匹配则固定)。当需要所有者时使用state:"question"(在msg中包含问题),当建议保留时使用"wontfix"。kind:"request"的笔记是来自“询问”标签页的任务(录制新台词、查找声音);prefer指向所有者喜欢的选项;intent:"question"表示需要回答,而非更改。 每个at都是真实时间:取自date -u +%Y-%m-%dT%H:%M:%SZ,切勿猜测。 - 向
films/<id>/activity添加行({at, by:"claude", kind:"seen"|"applied"|"published"|"question", text, version}):您读取的内容、更改的内容、发布的内容。 - 如果所有者使用了“发送给 Claude Code”,则在页面评论线程中回复,然后解决该评论。
规则
- 一位导演,无委员会。 自行按顺序完成下面的专业检查清单。除非所有者要求,否则不使用工作流或子代理(成本规则)。
- 积极推断,仅提问真正的阻塞点(产品事实、缺失的资产、许可问题)。不得在所有者看到任何内容之前使用冗长的问卷。
- 每个决策默认提供三个选项。 包括方向、音乐、运动感、节奏,以及每个场景:过渡、镜头、语音台词、每个音效事件。选项必须真正不同。标记导演的选择,并为每个选项提供一句简单的理由或权衡说明。“无”是一个有效的音效选项。
- 产品真实性。 每个场景都标记为
real_ui、conceptual_ui、conceptual_visual或external_footage;任何非真实的场景都会在播放器中显示标签。 - 通用规则仍然适用(AGENTS.md、OWNER.md):禁止的陈词滥调、携带性、两个文本层级、录制的拟音、默认语音、许可。页面只播放 CC0 或自制的音频;Mixkit(仅用于渲染)只能以名称出现。
- 适当缩放。 一个 6 秒的片头可以是一个方向卡片、3 个音乐选项和一个 6 秒的动画分镜。一个 40 秒的产品影片则获得完整配置。
- 锁定。 一旦所有者批准,故事、文案、顺序、时间安排和选择将被锁定。后续笔记只更改其目标对象;列出您保留了哪些内容。
专业检查清单(导演简要涵盖每项)
故事(2 秒内设置钩子,每个节拍一个状态)· 剧本和语音台词(每秒字数 ≤ 3.4)· 编辑节奏(变化镜头长度、停顿,非每个剪切都在节拍上)· 艺术指导(3 个方向作为令牌集:bg、on-bg、card、on-card、muted、line、paper、on-paper、accent、on-accent、frame、display、ui、mono)· 排版 · 参考(借鉴 / 避免 / 使用位置;语法,而非内容)· 镜头(每个移动都有理由)· 运动(目的、缓动、在 UI 上过冲 ≤ 4%、在文字上无过冲)· 过渡(简单的剪切是有效的)· 资产(现有 / 新生成 / 生成的 / 占位符,附带许可)· 音乐(已测 BPM 和相位、能量曲线、高潮落点位置)· 音效(资产、时间、触发器、增益、理由)· 混音(语音主导、压缩 8 dB、冲击音最响)· 引擎(选择、理由、备选、后备方案)· 质量审查。
文件(每部影片一个文件夹)
projects/NNN-name/previs/
build_previs.py # 写入 page/previs.json;复制 examples/crumb-previs/build_previs.py 并编辑(scenes = HTML 风格帧 + 动画补间)
vo-lines.txt # 每行 3 种措辞,用于 fish_tts.py
page/index.html # 由 _shared/previs/app 构建(npm run build;将此页面作为目标添加到 scripts/inline.mjs)
page/films.json # [{"id": "NNN-name", "name": "Product", "path": ""}]
page/previs.json # 整个计划
page/audio/{music,vo,sfx}/
changes.jsonl # 仅追加的变更日志,每行一个操作
approved-video-spec.json # 批准后由 _shared/previs/freeze_spec.py 写入
步骤
- 阅读简报或一句话需求以及产品源文件(真实 UI、令牌、文案)。编写
BRIEF.md记录推断的决策。 - 音频(廉价、本地):
- 背景乐:通过 85–150 BPM 的低频起始包络梳状拟合测量速度和相位(
AGENTS-tooling.md,“Previs”);从节拍开始处截取 24 秒片段,loudnorm 标准化至 −18 LUFS:ffmpeg -ss <phase> -t 24 -i bed.wav -af "loudnorm=I=-18:TP=-2,afade=t=out:st=22.5:d=1.5" page/audio/music/A.mp3。 - 语音:
python3 _shared/tools/fish_tts.py --lines previs/vo-lines.txt --out-dir previs/vo-wav(免费模型),然后修剪静音至page/audio/vo/sN-{A,B,C}.mp3。 - 拟音:从
_guide/prompt-studio/media/foley/复制 CC0 预览,或使用freesound.py获取。
- 背景乐:通过 85–150 BPM 的低频起始包络梳状拟合测量速度和相位(
- 规划
build_previs.py(参见每个字段的示例):project、summary、chief、story(节拍 → 场景)、directors、assets、gates、pipeline、changes、directions(3 个)、global.music|motion|pacing|voice(各 3 个)、engine、references、style_rules、audio_notes、qa、versions、film_css(所有颜色通过令牌表示,类名以f-为前缀)、fonts_url,以及scenes[],包含html、anim(补间{s, t:[a,b], f, to, e}作用于 x、y、s、sx、sy、r、o、clip、w、blur;{s, set, at, until}类切换;{s, count:[from,to], t, p, d}计数器;e:'m'跟随运动选择)、decisions(过渡类型包括 cut、push、slide、zoom、iris;镜头{s,x,y,origin};语音{text, src, dur, at, copy})、sfx(at可以是列表以表示连续事件)、key(故事板静止画面的时刻)。为所有者可能指向的每个元素提供简单的data-name(如“Receipt total”、“Request button”)。 - 本地检查:提供页面文件夹的服务,查看每个场景的静止画面和一个过渡中间状态,切换所有三个方向一次,确认无控制台错误。一次通过,无需循环。
- 分享页面(本地,或作为具有上述功能的 claude.ai 工件)并将影片添加到 Previs Studio。向所有者提供链接和五行摘要。停下来等待审查。
- 审查循环(每轮重新发布一次):
- 读取笔记、选择和批准状态。
- 对于每个公开笔记:仅更改其目标对象,将操作附加到
changes.jsonl({"v","target","t","change","from","to","reason","preserve":[...]}),然后标记笔记为完成并附带一行回复(遵循上述协议)。revert笔记要求撤销列出的更改。 - 在
build_previs.py中更新versions并添加该轮的changes,重新运行,将previs.json复制到 Studio 的副本中,重新发布。播放器将显示“what changed”横幅,计划将每个更改列出并附带撤销请求。
- 批准:当
state/approval包含approved: true(同时携带picks、tweaks和custom)时,保存它,运行python3 _shared/previs/freeze_spec.py projects/NNN-name/previs --approval <file>(它会解析添加的选项和语音,并列出needs_before_build,例如未录制的台词),根据规范编写SHOTLIST.md,然后移交给规范中指定的引擎技能。引擎按规范精确构建(允许润色,不可更改决策)。
成本
仅限单人工作。一个 20 秒的预可视化需要一次会话的几个小时(大约相当于 30–60 美元的 API 成本),使用 Fish 的免费模型且无需渲染。生产渲染及其检查在批准之后进行。