示例一 · Blender 3D
《芒原决战》
落日，芒草原。无主之忍对上年迈的剑豪，决斗分为剑、焰、雷三幕。角色、动作、镜头和特效都是在 Blender 里运行的 Python，每一个音符和音效都是合成的。
示例二 · 2D 绘画
《韩熙载夜宴图 · 猫》
一场画在绢上的夜宴，每一位宾客都是猫。小猫画师躲在屏风后偷看，一身唐代华服的宫廷猫们却不断露出马脚：被推下桌的酒杯、打断舞蹈的飞蛾、拒绝洗手的主人、吹破音的笛子。全片用 skia 绘制成工笔木偶。
亮点
用语言导演，用代码成片
由 coding agent 创作的影片
两部示例影片都是用自然语言导演，由 coding agent 从头到尾完成的，包括故事、角色、动画、镜头、配乐、音效和母带。
两部完整的示例影片
一部是 160 秒的武士决斗，用 Blender 3D 渲染；一部是 128 秒的“活”长卷，用 2D 绘制。技术完全不同，用的是同一个框架。
约定很小，渲染器随意
影片在 film.toml 里声明步骤，codecinema run <影片> <步骤> 用这部影片的设置来运行它。Blender、矢量绘图、着色器，能输出画面帧的都行。
共享的声音工具包
两部影片配乐背后的 DSP 随框架提供：振荡器、拨弦和模态物理模型、卷积混响、真峰值限制器和响度工具。
可复现，可配置
渲染结果确定，并行任务可断点续跑，分层设置无需改动受版本管理的文件，辅助工具支持 macOS、Linux 和 Windows。
快速开始
运行示例影片
git clone https://github.com/ZJUCQR/CodeCinema.git && cd CodeCinema
python3 -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install . # 安装 `codecinema` 命令
codecinema check # 检查 Python 依赖、ffmpeg，以及 3D 示例需要的 Blender
codecinema list # 列出影片和它们的步骤
codecinema run nightrevels all # 2D 示例：几分钟生成整部影片
codecinema run silvergrass all # 3D 示例：需要 Blender 5.2+，渲染时间较长| 命令 | 作用 |
|---|---|
codecinema list | 列出 films/ 里的影片，以及它们的步骤和依赖 |
codecinema run <影片> <步骤> [参数] | 用影片自己的设置运行它的一个步骤 |
codecinema new <id> [--title "…"] | 从模板开始一部新影片 |
codecinema check | 检查工具链和 Python 依赖 |
制作影片
开始你自己的影片
模板本身就是一部完整的小影片：draw_frame() 绘制每一帧，score() 生成声音，框架负责编码和混流。把这两个函数换成你自己的内容，再一步步扩展。完整说明见 docs/FRAMEWORK.md（英文）。
codecinema new myfilm --title "My Film" # 用模板创建 films/myfilm/
codecinema run myfilm all # 渲染一部 6 秒的起步影片[film]
id = "myfilm"
title = "My Film"
entry = "src/run.py" # 运行影片各步骤的脚本
steps = ["render", "audio", "assemble", "all"]
[settings.video]
width = 1920
height = 1080
fps = 24项目结构
文件都在哪里
CodeCinema/
├── codecinema/ # 框架
│ ├── cli.py # codecinema list | run | new | check
│ ├── settings.py # 每部影片的分层设置，工具和字体查找
│ ├── films.py # 影片发现和步骤运行
│ ├── media.py # ffmpeg：探测、编码、拼接、混流
│ ├── procutil.py # 跨平台的锁、进程、内存工具
│ ├── audio/dsp.py # 共享的声音工具包
│ └── template/ # `codecinema new` 使用的起步影片
├── films/
│ ├── silvergrass/ # 示例：《芒原决战》（Blender 3D）
│ └── nightrevels/ # 示例：《韩熙载夜宴图 · 猫》（2D）
├── docs/ # 框架说明
├── site/ # 本主页
└── pyproject.toml # 包和依赖工作原理
一部影片是怎样制作的
图 1. 一部 CodeCinema 影片是怎样制作出来的。(a) 影片先写成数据：film.toml 声明步骤和设置，一份 config 存放整个故事（时间轴、节拍、角色、写成音符的乐谱）。(b) 影片把这些数据变成场景：角色、动作编排、镜头、环境和特效，全部按同一个影片时钟打关键帧，每个动作都会发出带时间的声音事件。(c) 渲染器以并行、可续渲的分块绘制画面：一部示例用 Blender 3D，另一部用 skia 2D 绘画。(d) 配乐、音效和环境声根据音符和事件合成，再混音和母带处理。(e) 字幕、画面和声音按采样精度合成并通过质检。框架用影片自己的设置运行每一步，并提供共享的设置、声音工具包和 ffmpeg 工具。