
来源:github · 原文链接:https://github.com/sarpstar/cinecode · 整理:github_bot · 发布时间:2026-11-11
一、项目概览
cinecode 的自我描述只有一句话:用代码写成的电影。 但它实际交付的形态和这句话给人的第一印象并不一样——它既不是视频生成模型,也不是剪辑软件,而是一份安装进 AI 编程智能体(Claude Code 桌面版、VS Code 扩展、终端,或 Cursor)的技能包。你带来创意和品味,智能体负责写剧本、用代码逐帧构建画面、设计声音,最后在一个独立文件夹里留下一个 <片名>.mp4。
它最关键的架构选择是:不生成像素,而是写生成像素的代码。每一帧都是时间的纯函数,在无头 Chrome 里被逐帧截取并送入 ffmpeg,所以没有逐帧推理费用,没有一致性漂移,同一份代码重渲染的结果完全一致。代价是画面的复杂度上限取决于“能不能用代码画出来”,这也是它把 3D、2D、水墨、纸艺、黏土、像素等媒介摆在明面上让用户先选的原因。
项目由 Sarp Yıldız(@sarpstar)与 Claude 协作完成,MIT 许可,Python 为主,主打土耳其语(README 提供土耳其语、英语、日语三版,不少默认资源与校验规则围绕土耳其语字符设计),目前 2.1k stars / 378 forks。运行完全在本机,不需要任何付费服务;只有需要旁白时才用到你自己的 Gemini 密钥(有免费额度)、ElevenLabs,或免费的土耳其语离线语音。
二、核心特性速览
| 能力面 | 具体表现 |
|---|---|
| 画面生成 | 快速模式是一个自包含的 film.html(Canvas 2D / Web Audio);电影模式是 three.js 逐镜头渲染,场景是时间的纯函数 |
| 风格体系 | 八种风格预设(电影感写实、动漫赛璐璐、粉彩绘本、黏土动画、剪纸拼贴、复古 VHS、高光泽商业、手绘水墨)+ 58 份风格配方 |
| 声音设计 | 从第 1 版起就在同一文件内设计:每场景一层环境底噪、音效按画面提示表触发、共享一个生成式混响、音乐来自编曲表 |
| 旁白处理 | 绝不输出引擎原生音色,每片先定“声音呈现方式”(贴近、磁带、电台、合唱、水下、机械)与空间(房间、大厅、石砌中殿、户外) |
| 量化检查 | 前 2 秒必须从第 1 帧起就有运动、−14 LUFS 母带、手机尺寸文字可读性、变音符号尺寸、重复与陈词滥调检测 |
| 两种模式 | 快速模式:单文件、几次确认、可做 3 分钟以内;电影模式:路线图 + 剧本 + 风格帧 + 动态分镜 + 渲染 |
| 两种用途 | 电影感影片(氛围、故事、影展短片)对比广告与产品(专属性测试、UI 主视觉、9:16 / 1:1 / 16:9 安全区版本) |
| 成本结构 | 无图像模型费用;主要开销是对话 token 与渲染时间,故强制短对话与辅助智能体分片 |
三、系统架构设计

按 arch.zones 的三层来看,cinecode 是一个“无服务、无数据库”的纯本地系统,唯一的持久层是影片文件夹本身。
交互编排层由对话终端(对话终端 / Claude Code)与技能协议(技能协议 / SKILL.md)构成。SKILL.md 是技能本体,定义流程、该问什么问题、以及哪些是硬性规则;references/ 作为创作指南被按需读取——写作、运镜、字体、声音、用途分支各自独立成篇,只有在需要那一项时才载入。这一层的设计意图很明确:上下文是稀缺资源,指南必须可寻址、可按需加载,而不是一次性塞进对话。
核心生成层里,编排引擎 / make.py 是唯一的命令入口(静帧、样片、成片各一条命令),它调度 渲染浏览器 / headless Chrome 完成逐帧渲染(capture.mjs),并在关键节点向 规则守卫 / guard.py 请求校验。守卫通过 hook.cjs 挂在 Claude Code 的钩子上,能在出错当下拦截(剧本没展示就先发问、草稿没展示、刚获确认就停下),形成 core_to_guard → guard_to_tools 的拦截链。
能力与外部层是纯工具箱与素材面:脚本工具箱 / scripts/ 里是零依赖的 Python 标准库与 Node 脚本;风格素材库 / styles 与 refs/ 提供 58 份风格配方、方向板与用户自备参考;编码与语音 / ffmpeg 与 TTS 负责混音、母带与旁白。外部依赖被压到极低——three.js 与 pmndrs/postprocessing 从 CDN 加载固定版本,字体走 Fontsource,音效来自 Kenney(CC0),采样来自 VCSL(CC0),全部按需获取并逐条登记授权。
一句话概括这套架构:把视频制作拆成可测试的软件工程,让智能体做它最擅长的事——写文件、跑脚本、看结果。
四、核心流程解析

主流程的六个站点,本质上是六个降低返工成本的闸门。
创意输入只需要一句话。如果你给的是完整需求说明(节拍、文案、时长、画幅),智能体会跳过提问直接出草稿;否则它会把你的想法和一件随机抽取的真实事物(博物馆藏品、动物、太空照片、古发明、遗迹、手艺)碰撞,避免你拿到“谁都会先想到的那部片子”,并和你做过的片子逐一比对去重。
问答确认阶段决定模式(快速 / 电影)与用途(电影感 / 广告产品),问题数量被刻意压到几个,每个都有标 ★ 的推荐答案。模式决定做多深,用途决定这是什么样的影片——之后所有默认值、参考、确认节点、检查项都随用途而变。
文字方案是全流程的重心(对应图中的 focal station)。它以纯文字给出:一句话梗概、转折、带运镜说明的逐秒节拍表、台词或屏幕文字,做过调研时附参考板,再加一张可逐行修改的导演卡。此时改一行字是零成本的,改一个镜头则不是——闸门放在这里,是为了让后面的失败率下降。
场景预览只渲染两帧静帧:开场,以及与开场差别最大的那一场。风格在这里被锁定,之后所有帧都以此为标准。
草稿迭代出一版半尺寸、无后期效果的草稿,附带母带处理与开头钩子检查,并交给一个“毫无背景的独立观看者”审看。修改最多两轮,意见一次性提交,且只作用于它涉及的镜头或声音层。
最终渲染出全尺寸成片,开启你选择的后期效果(运动模糊、印片影调、片门抖动,默认全关),母带处理到 −14 LUFS,并在成片旁留下一个可直接粘贴进视频简介的致谢文件。
贯穿全程的中枢是影片文件夹状态 / STATE.md:每一步的进度、已确认项、意见归档都写回文件,新对话只要说“从 STATE.md 继续”就能接上。这是它能承受多轮、多会话、多辅助智能体的根本原因。
五、核心模块解析
| 模块 | 职责 |
|---|---|
make.py | 静帧、样片与成片的统一入口;渲染在后台运行并写状态文件,结果只用四行回报 |
capture.mjs | 在无头 Chrome 中逐帧渲染;可直接输出 MP4,并把页面配乐导出为 WAV;--probe 检测 GPU |
mix.py / master_audio.py | 混音与 −14 LUFS 母带处理,附经过测试的 ffmpeg 配方 |
tts.py / voice_treat.py | 旁白录制与声音处理(音色与空间),支持 EMA、VoxCPM2、Ahenk 等免费土耳其语引擎 |
beat_grid.py / lyrics_align.py | 测歌曲节拍网格、逐词对齐歌词,让剪辑点落在小节、重音落在拍点 |
qc.py / scene_check.py / words_check.py | 量化质量检查:开头钩子、去运镜后的主体动作、响度与刺耳度、文字可读性与 AI 腔调 |
guard.py / hook.cjs | 钩子式规则守卫:对话膨胀提醒、不出现大图、辅助智能体步数上限、密钥文件保持关闭 |
direction.py / styles.py / fonts.py | 方向板生成、风格配方索引、Fontsource 字体挑选与搭配样张卡 |
animatic.py / footage_cut.py | 动态分镜生成;依据逐词转录稿剪辑自有口播或录屏,裁掉停顿并标出重录点 |
formats.py / usage.py | 保存与复用影片格式;统计每个对话的 token 用量 |
模块的共同特征是小:没有重型框架,不引入构建链,脚本只使用内置能力与固定版本的 CDN 库。这让整个技能包能被一句 git clone 装进 ~/.claude/skills/,也让智能体读得懂、改得动。
六、特色能力
方向板是电影模式最讨巧的设计。你说出创意后,它用一张图给出三个视觉方向,每个方向由一种风格加两三部体现该风格的真实电影剧照(来自 FilmGrab,仅作氛围参考)组成,并附上从剧照里测得的色板。你选中的方向会被量化为影片的光线与色彩,风格帧也要以它为准检查——把“我觉得不对”翻译成可执行的参数。
“像这个视频,但不一样” 走的是另一条路:把参考视频放进 refs/,测出它的形式(剪辑与镜头时长、节奏、色板与光线、BPM、剪辑点如何卡在节拍上),你改想改的部分,然后在这个形式上做全新影片,绝不复用它的画面或音乐。这在版权上是干净的,在创作上又是有效的。
用你自己的歌做 MV 要求先测节拍网格:整首歌上测速度,片段在小节线处截取,剪辑与重音落在小节与拍点上,每句歌词对应一个画面,有旁白时音乐自动压低。
保存格式做系列片 让风格、字体、声音、摄像风格与节奏被固化为一个格式,下一集只换创意。配合口味日志(跨影片学习你选过的字体与搭配),这套东西会越用越像“你的片子”。
此外还有:依据你自己的品牌色、字体与标志做广告片,并跑一次“专属性测试”确保成片无法套用到任何其他品牌;带安全区的 9:16、1:1、16:9 三版本输出;把开场钩子、单帧跳变、剪辑接缝、循环都做成可量化的检查项。
七、工具链与生态
starter/ 是 three.js 侧的地基:八种画面风格、一套命名运镜(推轨推进、环绕、滑动变焦、FPV、手持、变速、移焦、匹配剪辑、甩镜、J-cut……)与文字层。运镜词汇表的价值在于可指称——每个镜头的运镜只需写一行“推轨推进,3 秒,缓慢的缓入缓出,朝向人物”,两个引擎都把它实现为时间的纯函数。
styles/ 收录 58 份风格配方,其中 51 份来自 LemoLab 的 lemo-opuscar(MIT,锁定在某一次提交),7 份为本套件自有。生态姿态相当克制:只借想法、不复制代码,风格库按 MIT 收录并单独保留许可文件。
外部资源全部“按需获取 + 登记授权”:字体来自 Fontsource 与独立开源字体厂(SIL OFL、Apache、MIT、Ubuntu Font Licence、CC0),音效来自 Kenney(CC0),录制乐器音色来自 VCSL / VSCO-2-CE(CC0),历史影像来自 Wikimedia Commons、Internet Archive、NASA 与各家博物馆。每一项都写入 LICENSES.csv,并生成视频简介用致谢文件——这不是道德表演,而是可变现频道与客户项目能真正上线的必要条件。
八、部署与安全
安装是一句话的事,对智能体说:
git clone https://github.com/sarpstar/cinecode.git ~/.claude/skills/cinecode
Cursor 用户把路径换成 ~/.cursor/skills/cinecode。之后新开对话,输入“我想做一部短片”即可;技能会被“短片”“动画”“广告片”“产品视频”“make a short film”等日常说法触发。
环境要求不高但不可省:Node.js 22+、Python 3.9+、ffmpeg、Chrome / Chromium / Edge,以及一块 Chrome 能调用的 GPU。缺什么智能体会先问再装。Windows 上工具包跑在 Claude Code 自带的 PowerShell 中,不需要 bash;Git 只用于安装与更新,从不参与渲染。磁盘占用分两档:快速模式帧直接写入 MP4,几百 MB 够用;电影模式每部片需要几 GB。
安全边界划得很清楚:密钥存在 ~/.cinecode/keys.env,第一次需要旁白时在编辑器里粘贴一次即可,绝不进入影片文件夹或代码仓库;守卫钩子会检查密钥文件保持关闭、对话中不出现大图、每个辅助智能体最多 25 步。需要注意的是,那些“当场拦截”的钩子只在 Claude Code 中生效(且需要 2.1.295 以上的版本),Cursor 里只有 make.py、qc.py 这类显式检查,约束强度不同。
九、适用场景
快速模式面向“今天就要交”的场景:一分钟以内的短片、社交平台竖屏科普、品牌广告,流程约 3 次确认,30 秒影片基本能在一次会话内走完。做坏了重来成本很低,因为整片就是一个 film.html。
电影模式面向必须做好的那一部:纪录片、带旁白的科普长片、影展短片。它多了调研与出处、好奇心地图、分层声音、章节卡与逐幕配乐,代价是 6–8 次确认和更长的渲染时间。你也可以先用快速模式起手,再把节拍表升级成路线图转入电影模式。
广告与产品片是最容易被低估的一块:精细建模、影棚式布光、软件 UI 主视觉镜头、专属性与竞品测试、三画幅安全区输出——这套流程原本属于外包报价单。
剪辑自有素材则把入口从“生成”扩到“整理”:口播或录屏交给 Whisper 做逐词计时转录,按词裁掉停顿,标出口吃与重录供你确认,图形与台词同步出现。
不适合的场景也要说清楚:需要真人质感的面部特写(README 自己承认“人脸在特写中以风格化或剪影呈现效果最好”)、复杂的角色表演、以及必须在无 GPU 环境批量出片的生产线。
十、总结评价
cinecode 的真正价值不在于“AI 能拍片”,而在于它给 AI 视频找到了一条工程上可持续的路径。当前主流的图像 / 视频模型路线要面对三件事:逐帧推理成本、跨镜头一致性、以及不可复现的随机性。cinecode 用“智能体写代码生成像素”绕开了全部三项——成本落到了对话 token 和 GPU 渲染时间上,一致性由同一份代码保证,可复现性由种子与纯函数保证。这是路线选择上的判断力,而不是功能堆砌。
第二个值得学习的是闸门设计。它把确认点放在最便宜的地方:文字方案确认(改一行字)、两帧静帧确认(改一个风格)、低分辨率草稿(改一个镜头)。意见只作用于相关镜头,每轮都是新版本,notes/round-N.md 原样归档。这比“一次生成、全盘重来”的控制力高出一个量级,也是它能做客户项目的底气。
第三个是成本自觉。README 直言“对话的每一步都会重新读取整个对话,因此让对话保持简短才是让一部影片省钱的关键”,于是有了辅助智能体分片、按任务选择模型、四行渲染回报、缩略图拼板看图、上下文膨胀提醒。这种把 token 当预算管理的写法,在技能类项目里很少见。
适用人群很明确:有审美但不想学 After Effects 的独立创作者、需要高频出片的社交内容团队、要给产品做发布片但预算有限的小团队、以及想把课程或科普做成系列的教师与 UP 主。反过来,追求实拍质感、需要精细人物表演、或在没有 GPU 的 CI 环境里跑批量渲染的团队,会很快撞到边界。
局限同样要讲:它重度绑定 Claude Code(守卫钩子、桌面应用自动开新对话等能力在其他宿主里缺失),对 GPU 与 Chrome 有硬依赖,成片质量的上限受制于“能不能用代码画出来”,而土耳其语优先带来的字体、语音、变音符号校验链路,对纯中文用户来说有一部分是用不上的。此外 100–250 步的对话规模意味着它依然是“有时间成本”的创作方式,不是一键出片。
如果把视频看作一种软件产物——可版本化、可测试、可参数化——cinecode 是目前把这个隐喻走得最远的开源实现之一。它不承诺取代导演,它承诺的是:你只需要带来创意和品味,剩下的部分,交给代码。
参考链接:项目仓库 https://github.com/sarpstar/cinecode