Scenet

Scenet

用于漫画分格、可编译为 SVG 的语义 DSL。

⚠️ 本项目刻意使用 AI 生成

本项目的设计初衷，就是几乎完全由 AI 生成。它是一个个人练习场，用于学习如何使用 AI 编码工具。架构、代码、测试和文档绝大部分由 AI 编写，并由人工指导和审阅。

请据此看待它：首先是一项实验，其次才是一个可用工具。

---

在线体验 · 文档 · 教程 · 更新日志

这是什么

音乐有乐谱。乐谱描述一首曲子的语义——音高、时值、力度——却不描述最终传入你耳中的波形。渲染交由解释器（无论是人还是机器）完成。

图像没有这样的东西。SVG 描述的是如何绘制，而不是描绘了什么：它更像 WAV 文件，而不是乐谱。Scenet 试图补上缺失的这一层，并将范围限定在一个易于处理的领域——漫画分格。

你可以写出分格中的内容：

panel:
  size: [1000, 1000]
camera:
  shot: medium_shot
  angle: eye_level
setting:
  place: street
  weather: rain
cast:
  alice: {reference: alice, pose: pointing,     at: left_third,  facing: right}
  bob:   {reference: bob,   pose: arms_crossed, at: right_third, facing: left}
staging:
  - alice left_of bob
  - alice looking_at bob
script:
  - say: {by: alice, text: "You forgot your umbrella!", prefer: top_left}
  - say: {by: bob,   text: "I know."}

你也可以编写一组分格的序列，每个分格只说明相较于前一个分格发生了哪些变化——这种方式借鉴自 OpenUSD 的稀疏覆盖，因为场景中的连续分格几乎共享所有布景：

panels:
  establishing:
    camera: {shot: full_shot}
    cast: {alice: {reference: alice}, bob: {reference: bob}}
  reaction:
    over: establishing        # same cast, same staging
    camera: {shot: close_up}  # move in

或者使用漫画剧本这种编剧已经在用的格式：

PANEL 1
@shot: full_shot
Alice and Bob face each other on a rainy street corner.

ALICE
You forgot your umbrella!

BOB (whisper)
I know.

Dark Horse 发布的剧本格式可以直接读取，法语剧本也一样。

无论使用哪种格式，编译器都会推导出其余内容：中景下每个人物应该有多大、他们站在哪里、面朝哪个方向、每个气泡需要多大才能容纳文本、气泡放在哪里才不会遮住脸，以及气泡尾巴如何延伸到说话者的嘴边——同时保留阅读顺序。

整个过程不涉及生成式图像模型。 这是一个确定性编译器：使用约束求解和计算几何。同样的输入始终会产生逐字节完全一致的输出。

状态

Alpha 版——分格、序列和页面均可端到端编译，可通过命令行、浏览器或编辑器使用。 取景、角色定位、气泡和说明文字定位、阅读顺序、气泡尾巴路径、面部绘制及其周围的标记、色调背景、分层页面以及 SVG 输出均已实现；支持两种前端，而且屏幕阅读器可以逐格读取每个分格，先读描述，再按阅读顺序读出其中的所有文字。尚未实现：印刷输出，以及为分格赋予风格的解释层。详情请参阅阶段计划。

uv run scenet build examples/duel.panel.yaml --core --debug
uv run scenet build examples/sequence.scene.yaml --strip
uv run scenet build examples/umbrella.script --strip

--core 会将解析后的中间层写入 JSON；--debug 会写入叠加图，显示求解器处理的几何信息——轮廓凸包、人脸排除区、锚点、视线向量和气泡尾巴路径。

工作原理

  duel.panel.yaml     →     Panel Core (.core.json)     →     panel.svg
  authored,                 resolved, fully numeric,          rendered
  no coordinates            still named & inspectable

中间层是一种真正可读写的格式，而非隐藏的数据结构，因此可以独立于绘制方式检查布局、手动调整并进行差异比较。这种做法借鉴自 Vega-Lite：它会先将高级语法编译为低级语法，再输出 SVG。

在浏览器中试用

playground 会通过 Pyodide 在浏览器的 WebAssembly 环境中运行这个编译器——使用的就是同一份未经修改的 Python 代码。这不是重新实现：页面安装的是 uv build 生成的确切 wheel，因此不会有第二份几何逻辑逐渐偏离。

其中的示例涵盖每种镜头类型、每种气泡类型、每种字幕类型、每种表情和标记、每种物块类型和位置、两种前端以及约束优先级。每个示例都是 examples/gallery/ 下的真实文件，测试套件会对其进行编译，因此 playground 不会提供无法运行的示例。

编辑器使用 Monaco，并加载 VS Code 扩展使用的同一份 JSON Schema——该 Schema 根据编译器自身的模型生成，因此补全和悬停文档不会与实际编译结果脱节。所有内容都由同一来源提供：没有 CDN、没有分析工具，也不会从其他任何地方获取内容。

编辑器支持

VS Code 扩展为分镜文档提供补全和行内验证，并支持并排预览。它的 JSON Schema 由 scenet schema 根据编译器自身的模型生成，因此编辑器提供的内容都能实际编译。如果随附的 Schema 过时，测试就会失败。

在模型中使用

模型在训练期间并不了解 Scenet，因此项目会直接提供这门语言。在模型中驱动 Scenet 介绍了各类客户端的用法：

• 无法运行代码的聊天应用——NotebookLM、Gemini 应用——可使用 规范包：一个文件中包含这门语言、漫画脚本格式、角色、所有诊断信息和完整示例库。
• 可加载技能的 Agent 可使用 skills/scenet，这是一个 Agent Skills 文件夹。
• MCP 客户端可使用 scenet mcp，其工具可以验证、编译和渲染，让模型读取自身错误并修复它们。

pip install 'scenet[mcp]'
scenet mcp

安装

pip install scenet

需要 Python 3.12 或更高版本。无需系统库、无需安装字体，也无需进行任何配置。包中附带 py.typed 标记，因此 mypy、pyright、ty 和 basedpyright 可以直接读取包中的类型注解。

from scenet import compile_source, render

result = compile_source("cast: {alice: {reference: alice}}")
svg = render(result.core)

开发

需要 uv。它也会管理 Python 版本，因此完整的设置步骤如下：

uv sync --all-groups
uv run pytest

以下检查都会在 CI 中运行：

uv run ruff check . && uv run ruff format --check .
uv run ty check
uv run pytest

文档

creatoan.github.io/scenet ——也可以阅读 docs/ 下的 Markdown 源文件，GitHub 无需构建步骤即可渲染这些文件。

教程	从零开始，在十五分钟内构建一个分镜
操作指南	连续分镜、漫画脚本、自定义角色，以及将其用作库
语言规范	每种语言结构及其示例
镜头类型	规范性的摄像机取景表
Panel Core	解析后的中间格式
素材约定	角色木偶必须声明的内容
MCP 服务	scenet mcp 提供给模型的工具
API 参考	所有公开名称
设计决策	采用这种设计的原因
先前成果	已有成果以及借鉴之处

文档中的每个 Python 示例都会由测试套件执行。缺少导入，或与代码脱节的示例，都会导致构建失败。

许可证

0BSD — 详见 LICENSE。本许可证特意比 MIT 更宽松一档：你可以出于任何目的使用、复制、修改和分发本软件，无需保留版权声明或附上许可证。无需注明出处，但我们始终欢迎这样做。

第三方组件列于 THIRD_PARTY_NOTICES.md。字母字体作为普通依赖项提供，采用 SIL Open Font License，该许可证确实要求保留其附带的声明。

语言规范可自由实现。 任何人都可以为此语言构建自己的编译器、编辑器、渲染器或工具，并用于任何项目，无论是否用于商业用途，均不受限制，也无需注明出处。只有不归任何人所有的记法才值得拥有。