Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

docs: add SVML Script Surface v1

kashorin59cde7713856
diff --git a/README.md b/README.md
index 81931b23..e57ed2ff 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,7 @@
# svml
Semantic Video Markup Language — a semantic source language for video
+
+## Specification
+
+- [Script Surface v1](spec/script-surface-v1.md) — the frozen, human-readable
+ source language for narrative, text projections, selections, and moments.
diff --git a/spec/script-surface-v1.md b/spec/script-surface-v1.md
new file mode 100644
index 00000000..6ae90271
--- /dev/null
+++ b/spec/script-surface-v1.md
@@ -0,0 +1,531 @@
+# SVML Script Surface v1
+
+> **Surface frozen; implementation pending.**
+>
+> 本规范冻结 SVML 稿子区的 v1 源语言。Script 是后端无关的语义源,不声明
+> 某个画布、节点注册表或渲染器已经实现这些规则。实现只有在通过本文的
+> parser、projection、source-map 和 temporal golden fixtures 后,才可声称
+> 支持 Script Surface v1。
+
+SVML 是语义视频源语言,不是像素渲染格式。本文只冻结它最高频、最需要保持
+可读性的稿子区 `<script>`;画布、节点、样式、生成参数和其他 Program 区域的
+外层文档结构另行设计。冻结之后,新增语义应首先组合本文已有构造;确需改变
+正文语法时必须发布新的 Script Surface 版本,不能静默扩写 v1。
+
+## 一页合同
+
+正文除自然语言外只有六种语义构造:
+
+| 构造 | 只负责 | 不负责 |
+|---|---|---|
+| `Segment` | 有序的媒体/口播块和结构切点 | 自动 Selection、时长、静音 |
+| `Role Cue` | `dialogue` 导出时的“谁说了什么”文本前缀 | speaker 实体、音色、字段路由 |
+| `Dual Text` | 显示文字与实际读音不同 | TTS 厂商参数、样式、动作 |
+| `Selection` | 一个或多个显式闭合的语义时间区间 | 消费者声明、绝对秒数 |
+| `Moment` | 一个或多个显式完整的语义时刻 | 半截区间、持续时间 |
+| `Slot` | 注入运行时文字值 | 注入 SVML 语法或任意 AST |
+
+注释是 trivia,不是第七种语义构造。任何字幕样式、B-roll、Ranking、Deck、
+音效、静音、生成提示、节点端口和消费策略都在 `<script>` 外引用
+Selection 或 Moment。消费者不归属于某个 Segment;一个消费者可有多个
+端口,每个端口可接一个或多个 Selection/Moment。Selection 可以跨 Segment
+或由非连通区间组成,Moment 也可以有多个 occurrence。
+
+Script 编译必须先生成保留源码映射的 Narrative IR,再从同一份 IR 投影三种
+文本。禁止先生成三个互不相关的字符串,再猜它们之间的对应关系。
+
+| 投影 | 内容 | 典型消费者 |
+|---|---|---|
+| `dialogue` | Role Cue + 实际读音 | Seedance 等对话/视频生成 |
+| `speech` | 仅实际读音 | Estimate、TTS、Speech Reference、对齐 |
+| `caption` | 仅显示文字 | 字幕与文本展示 |
+
+## 正例
+
+```svml
+<script>
+ @whole
+
+ <segment id="hook">
+ <A> I just @laugh @pop! <lmao | laughed my @punch ass out @/punch> @/laugh.
+ </segment>
+
+ @silence
+ <segment id="pause"/>
+ @/silence
+
+ <segment id="close">
+ <B> Meet <${product} | ${product_pronunciation}>.
+ </segment>
+
+ @/whole~
+</script>
+```
+
+若 `product = "Hypit"`、`product_pronunciation = "high pit"`,三个文本投影
+分别是:
+
+```text
+dialogue
+A: I just laughed my ass out.
+B: Meet high pit.
+
+speech
+I just laughed my ass out.
+Meet high pit.
+
+caption
+I just lmao.
+Meet Hypit.
+```
+
+`silence` 只是 Selection 的名字,不会自动让音频静音。它完整选择了空
+Segment 的两个结构切点;真正的静音或素材行为由外部 Program 决定。
+`pop` 是一个默认吸右的 Moment,解析到 `laughed` 的起音;它同样不进入
+任何文本投影。
+
+## 1. 文档与 Segment
+
+一个 Script 有且仅有一个 `<script>` 根。结构标签必须独占一行。v1 的
+Segment 形式只有:
+
+```svml
+<segment id="intro">
+ Hello.
+</segment>
+
+<segment id="pause"/>
+```
+
+规范规则:
+
+- Script 包含一个或多个按源码顺序排列的 Segment。
+- Segment id 在文档内唯一,Segment 不允许嵌套。
+- 自然语言只能出现在 Segment 内;Segment 之间只允许空白、Selection/Moment
+ 标记和注释。
+- 空 Segment 使用自闭合形式。它有结构开始/结束切点,但没有词法锚点。
+- 空 Segment 不蕴含静音,也不蕴含任何默认时长。其物理时长来自媒体、生成
+ 结果或 `<script>` 外的 Program。
+- Segment 不自动声明同名 Selection。选择一个、三个或任意多个 Segment,
+ 都必须显式写闭合 Selection。
+- 相邻 Segment 共享一个切点。因此 `m` 个 Segment 始终贡献 `m + 1` 个
+ 具有稳定身份的结构切点。
+
+例如选择三个连续 Segment:
+
+```svml
+@chapter
+<segment id="one">
+ One.
+</segment>
+<segment id="pause"/>
+<segment id="two">
+ Two.
+</segment>
+@/chapter
+```
+
+## 2. Role Cue
+
+Role Cue 只在 spoken line 的逻辑行首(忽略规范缩进)出现:
+
+```svml
+<segment id="dialogue">
+ <A> What time is it?
+ <B> It’s 8:30.
+</segment>
+```
+
+它在 `dialogue` 投影中由规范 serializer 输出为:
+
+```text
+A: What time is it?
+B: It’s 8:30.
+```
+
+在 `speech` 和 `caption` 投影中,`<A>`、`<B>` 都被移除。Role Cue 不是
+speaker 数据模型,不建立人物实体,不选择音色,不成为可接线字段,也不对
+字幕隐式分组。若这些能力将来需要程序化表达,应放在外部 Program 中显式
+引用 Selection。
+
+为消除歧义:
+
+- Role Cue 只由“逻辑行首、合法尖括号内容、且不含未转义 `|`”这一位置识别,
+ 并且同一行必须跟随非空 spoken content。
+- 正文里的冒号永远是正文;解析器不通过 `A:` 猜说话人。
+- 同一个非空 Segment 要么所有 spoken line 都有 Role Cue,要么都没有。
+ 空白行、纯 Selection 行和注释不算 spoken line。
+- Role label 是 NFC 后 1–32 个 Unicode 字符的可读文本;可由 Unicode
+ Letter、Mark、Number、内部空格、`_`、`-`、`.` 组成,首尾不得有空白。
+ 引号、`=`、`/`、换行、`<`、`>`、`|`、`:` 均非法,因此带属性的未知
+ 结构标签不会被吞成 Role Cue。
+- Role Cue 的作用域只到本行结束。源码自动折行属于编辑器显示,不得写入
+ 语义换行;下一位说话人必须另起一行并再次声明。
+
+## 3. Dual Text
+
+Dual Text 同时写出显示文字和实际读音:
+
+```svml
+<lmao | laughed my ass out>
+```
+
+左侧进入 `caption`,右侧进入 `dialogue` 和 `speech`。普通正文是
+`<text | text>` 的简写,不需要任何标记。
+
+Dual Text 是一个不可嵌套的原子对应单元,而不是简单的字符串替换:
+
+- 两侧可以是任意 N:M 文本映射,不要求词数相等。
+- 右侧去除布局空白后必须非空;只显示不发声的文字不属于 Script,应由外部
+ Text/Deck/Caption Program 表达。
+- 左侧可以为空,例如 `< | um>` 表示实际说出 filler,但字幕不显示。
+- Slot 两侧都可使用;Selection/Moment 只可出现在 speech 侧,并且只能落在
+ 其词法 token 边界。
+- 整个显示侧继承整个 speech 侧的时间跨度。若显示词需要独立计时、选择或
+ 样式,作者必须把它拆成多个 Dual Text 原子。
+- 普通时间消费者可以选择一个 Dual Text speech 侧的部分 token;但字幕
+ ownership/style 消费者若只覆盖一个 Dual Text 原子的部分 speech span,
+ 编译必须以 `partial dual atom` 失败,不能猜测如何切左侧显示文字。
+
+例如合法的细粒度时间选择:
+
+```svml
+<lmao | laughed my @middle ass out @/middle>
+```
+
+`middle` 可以供 B-roll 或音效使用;若它被用作该 `lmao` 的局部字幕替换区,
+则必须报错。作者可通过拆分原子提供明确映射。
+
+Dual Text 只表达“实际说了什么”。IPA、SSML、重音、语速、语种、情绪、
+音色和厂商专用发音字典不是第四种正文文本层,应由外部生成/语音 Program
+引用 Selection 或词典资源表达。
+
+## 4. Selection
+
+Selection 是区间声明,不是供下游自行拼接的两个公开锚点:
+
+```svml
+@id ... @/id
+~@id ... @/id~
+```
+
+每个开始标记都必须有同 id 的结束标记。编译器输出一个完整
+`SelectionSet`,消费者只接收该集合中的闭合 range;不存在 start-only
+对象、消费者默认补尾或“信息传了一半”的状态。
+
+“闭合”指源码的两个端点都被明确声明。物理运行时使用半开
+`[startFrame, endFrameExclusive)` Frame Span。
+
+### 4.1 左右吸附
+
+标记本身零宽,不进入任何文本投影。它位于左右两个可选语义边界之间:
+
+| 端点写法 | 吸附方向 | 典型含义 |
+|---|---|---|
+| `@id` | 右 | 从右侧词首或右侧结构切点开始 |
+| `~@id` | 左 | 向外扩到左侧词尾或左侧结构切点 |
+| `@/id` | 左 | 在左侧词尾或左侧结构切点结束 |
+| `@/id~` | 右 | 向外扩到右侧词首或右侧结构切点 |
+
+例子:
+
+```svml
+before @x hello @/x after
+```
+
+`x` 默认从 `hello` 的词首到 `hello` 的词尾。
+
+```svml
+before ~@x hello @/x~ after
+```
+
+`x` 向两侧外扩,分别取 `~@x` 左侧和 `@/x~` 右侧最近的可选边界。
+
+```svml
+@pause
+<segment id="empty"/>
+@/pause
+```
+
+`pause` 的开始吸附空 Segment 的开始切点,结束吸附它的结束切点。Selection
+可完全位于 Segment 外,也可跨任意数量的 Segment。
+
+### 4.2 闭合、交叉与非连通
+
+同一个 id 可以顺序出现多次,编译为一个非连通 SelectionSet:
+
+```svml
+@beat one @/beat ... @beat three @/beat
+```
+
+不同 id 可以自由交叉,不要求 XML 式嵌套:
+
+```svml
+@a one @b two @/a three @/b
+```
+
+规范要求解析器按 id 管理开放状态,而不是使用一条全局栈。以下情况必须
+失败:
+
+- 未闭合、孤立 close 或 open/close id 不一致;
+- 同一个 id 尚未闭合就再次 open;
+- Selection 标记切进一个 v1 speech token 内;
+- 依赖消费者默认 span 来补齐缺失端点。
+
+同一 id 的多个 occurrence 保持源码顺序和稳定 occurrence identity。不同
+SelectionSet 以及同一集合的不同 occurrence 可以在物理时间上重叠。
+
+### 4.3 可选时间边界
+
+Slot 绑定、Dual Text speech 投影和 NFC 归一化之后,v1 使用规范定义的
+确定性 `speech-tokenizer-v1`:
+
+- 东亚表意文字和假名单字符成 token;
+- 其他受支持文字/数字脚本形成最大连续 run;
+- `'` 或 `’` 只在两个 run 字符之间时保留;
+- 空白、标点、emoji 和其他分隔字符不产生词法 token。
+
+因此标点本身不可被计时,Selection/Moment 也不可切入单个 token。v1
+编译器在移除零宽标记后再 tokenization,所以未来若需要字素、音节或音素
+边界,可以在新的 timing profile / Script Surface 版本中复用相同的
+Selection/Moment 类型;v1 不应为尚不存在的精度引入新正文符号。
+
+若 speech 中有 `n` 个 token、Script 中有 `m` 个 Segment,Temporal Anchor
+Map 恰有:
+
+```text
+2n + m + 1
+```
+
+个稳定身份:每个 token 的词首/词尾各一个,加上 `m + 1` 个唯一结构切点。
+这些身份即使最终解析到同一帧也不能合并。
+
+同一份 SelectionSet 可先在 Estimate Anchor Map 上得到预览区间,再在
+Evidence Anchor Map 上得到精确区间。Script 本身不含秒数、帧号或采样点。
+Script Surface 不绑定帧率、采样率或渲染器。后端一旦选择物理时钟,必须只
+量化一次并让所有消费者复用同一整数边界;后端时钟变化不改变本语言表面。
+
+对齐、结构切点或帧量化可能使某个 occurrence 最终成为零长或反向区间。
+消费者先应用自己的 projection,再只丢弃该非正区间 occurrence;不得移动
+Selection 端点、借用相邻 occurrence 或替作者补范围。
+
+## 5. Moment
+
+Moment 是完整的点声明,不是省略了 close 的 Selection:
+
+```svml
+@id!
+~@id!
+```
+
+`!` 明确标出这个名字的类型是 Moment。它不需要也不允许 close:
+
+| 写法 | 吸附方向 | 典型含义 |
+|---|---|---|
+| `@id!` | 右 | 右侧词首或右侧结构切点 |
+| `~@id!` | 左 | 左侧词尾或左侧结构切点 |
+
+默认右吸覆盖“与某个词一起开始”的高频情况:
+
+```svml
+I just @pop! laughed my ass out.
+```
+
+`pop` 解析到 `laughed` 的起音。显式左吸写成:
+
+```svml
+I laughed ~@pop! and left.
+```
+
+`pop` 解析到 `laughed` 的收音。位于两个 Segment 之间时,左右候选是对应
+方向上的共享结构切点。
+
+规范规则:
+
+- 同 id 的 `@id!` / `~@id!` 可以重复,按源码顺序编译成一个
+ `MomentSet`;一次 occurrence 是单 Moment,多次只是同一集合含多个点。
+- Selection 与 Moment 共享 temporal name namespace。同一个 id 不能同时
+ 声明两种类型;`@x! ... @/x` 必须以类型冲突失败。
+- 单独的 `@x` 永远是未闭合 Selection open,必须报错;解析器不得因为没有
+ 找到 `@/x` 而把它猜成 Moment。
+- `@id!~` 是冗余且非法的右吸写法;右吸只写规范形式 `@id!`。
+- 语法只接受 ASCII `!`。未转义 `@id!`(全角感叹号)是 malformed
+ temporal syntax,不能退化为正文。
+- Moment 与 Selection marker 可出现在相同位置,包括 Segment 之间和
+ Dual Text 的 speech 侧,但均不得切入 v1 speech token。
+- Moment 只选择 Temporal Anchor Map 中已有的一个候选点,不新增 anchor
+ identity;因此 `2n + m + 1` 的精确计数不因 Moment 数量改变。
+- MomentSet 与 SelectionSet 复用同一份 Estimate/Evidence Anchor Map 和
+ 一次性帧量化;区别只在最终载体是 `Point[]` 而不是 `Range[]`。
+
+消费端保持两个互不相混的类型:
+
+```text
+SelectionSet = Range[]
+MomentSet = Point[]
+```
+
+推荐的显式使用关系是:
+
+```svml
+during="phrase" <!-- 只接受 SelectionSet -->
+at="pop" <!-- 只接受 MomentSet -->
+at="phrase.start" <!-- SelectionSet 的各 range 起点投影 -->
+at="phrase.end" <!-- SelectionSet 的各 range 终点投影 -->
+```
+
+`at="phrase"` 不得默认猜成 start,`during="pop"` 也必须类型报错。一个
+消费者若同时需要窗口和触发点,必须使用两个字段/端口,而不是构造
+`Range | Point | mixed[]` 的多态 TemporalRef。端口需要 `one` 还是 `each`
+属于消费者 cardinality 契约,不改变 Script 的单/多 occurrence 语法。
+
+## 6. Slot
+
+Slot 是解析器识别的一等 AST atom:
+
+```svml
+${product}
+<${product} | ${product_pronunciation}>
+```
+
+Slot id 经 NFC 后必须由 1–64 个字符组成:首字符为 Unicode Letter 或 `_`,
+其余字符可为 Unicode Letter、Mark、Decimal Number、`_` 或 `-`。绑定值是
+单行 Unicode 纯文本,不能含 CR/LF 或控制字符。
+
+关键安全规则:
+
+- 先解析 Script,再绑定 Slot;禁止在解析前做字符串替换。
+- 绑定值永远按 literal text 进入已经存在的 atom,不能注入 Segment、Role
+ Cue、Dual Text、Selection、Moment、Slot、注释或转义序列。
+- 未绑定 Slot 可以保留在结构化编辑 IR 中,但凡是生成三种文本、计算 token
+ 或编译时间线,都必须 fail closed。
+- SVML v1 writer 只输出 `${变量}`;未转义的 `[变量]` 只是普通正文。
+
+## 7. 词法保留、转义与规范排版
+
+源码统一把 CRLF/CR 转成 LF,并做 Unicode NFC。源语言中未转义的 `<`、`@`
+和 `${` 是保留语法起点。格式错误的保留语法必须报错,不能退化为 spoken
+text。
+
+正文转义:
+
+```svml
+\@openai
+\<not-a-role>
+\${literal}
+\\
+```
+
+Dual Text 内另有:
+
+```svml
+\|
+\>
+```
+
+未知反斜杠转义必须报错。解析顺序固定为:
+
+1. 独占行的已知结构标签与注释;
+2. spoken line 逻辑行首、不含未转义 `|` 的 `<Role>`;
+3. 含一个未转义分隔 `|` 的 inline `<display | speech>`;
+4. 其他尖括号结构报错。
+
+Segment 与 temporal name 使用独立命名空间;Selection 和 Moment 共享
+temporal name namespace。三者的 id 均满足:
+
+```text
+[a-z][a-z0-9_-]{0,63}
+```
+
+源码缩进、换行和连续空白是 authoring layout,不是字幕换行或停顿指令。
+编译投影在 atom 边界保留必要分隔并规范化布局空白;字幕 cue 切分与硬换行由
+外部 Caption Program 决定。规范 formatter 使用两空格缩进 Segment、四
+空格缩进 spoken line,并在 Segment 之间留一空行;formatter 不得改变
+Narrative IR。
+
+注释使用独立行的 `<!-- ... -->`,可以跨行但不能嵌套,也不能写进 spoken
+line 或 Dual Text。注释不进入任何投影、token、Selection、Moment 或 hash
+的语义内容;需要可复现源码身份时可以另算 source hash。
+
+## 8. Narrative IR 与消费者合同
+
+解析结果至少保留:
+
+- Segment 的顺序、id 和结构边界;
+- 每个 spoken line 的可选 Role Cue;
+- plain / Dual Text / Slot atom 及其源码范围;
+- caption atom 到一个或多个 speech token 的显式映射;
+- 每个 SelectionSet 的一个或多个有序 occurrence;
+- 每个端点的左右 affinity 和端点源码位置。
+- 每个 MomentSet 的一个或多个有序 point、左右 affinity 和源码位置。
+
+SelectionSet/MomentSet 是消费者边界,不是 Segment 的子对象。典型外部
+关系是:
+
+```text
+Script ──compile──> Narrative IR ──project──> dialogue / speech / caption
+ │
+ └──resolve──> SelectionSet[] / MomentSet[]
+
+SelectionSet A ──during──> consumer.port_1
+MomentSet P ──at──────> consumer.port_2
+SelectionSet C ──during──> consumer.item_3
+```
+
+一个 Ranking、B-roll 或其他节点可以有多个动态端口,各端口接受不同
+SelectionSet/MomentSet;同一集合也可以被多个消费者复用。未来 Graph
+语法可以把这些类型边写成 `during=` / `at=`,但它们必须引用已解析的名字
+或端点投影,不能接受模糊自然语言 locator。
+
+Caption 的多样式、region、cue segmentation、annotation、mute 和 layout
+都属于 Caption Program。Caption consumer 若要求互斥 token ownership,重叠必须作为该消费者的
+编译错误;这不是 Script 禁止 Selection 重叠。未来 Caption 若支持 overlay,
+只扩展 Caption Program,不扩展正文语法。
+
+## 9. v1 明确不在 Script 中表达
+
+以下能力不是遗漏的第七种 inline marker:
+
+| 需求 | v1 归属 |
+|---|---|
+| 绝对秒数、帧号、采样点、任意 sub-frame 位置 | Script 外的运行时/Program |
+| token 内音素或字素级切点、标点专属时间 | 后续 timing profile 或新版本 |
+| 空 Segment 的预览时长 | 媒体、生成器或显式 Program |
+| 同时重叠说话 | 多轨媒体/生成 Program;Base Script 仍是顺序语义轴 |
+| 笑声、咳嗽、环境声、SFX、beep | 音频/生成/SFX Program |
+| 无 speech 时间依据的纯显示文字 | Text、Deck 或 Caption Program |
+| 字幕样式、手工断行、动效、画面动作 | 相应 Program 引用 Selection |
+| 语气、情绪、音色、重音、语速、SSML | Speech/Generation Program |
+| Consumer、节点、端口、DAG 接线 | `<script>` 外的 SVML 区域 |
+
+这些边界保证 Script 保持“可直接阅读的稿子”,同时不阻止完整 SVML 最终
+确定性编译 DAG 和时间线。
+
+## 10. 完备性与扩展判定
+
+遇到新需求时按下列顺序归类:
+
+1. 显示文字和实际读音不同:Dual Text。
+2. 对话导出的朗读人前缀不同:Role Cue。
+3. 语义时间范围不同:Selection。
+4. 语义瞬间不同:Moment。
+5. 顺序媒体/口播块不同:Segment。
+6. 运行时文字输入不同:Slot。
+7. 字幕、画面、音频、生成或消费行为不同:Script 外的 Program。
+
+只要需求能落入这七项,就不得发明新的 inline delimiter。若七项都不能
+无损表达,应先证明它属于稿子语义而不是 Program,再以新版本提案处理;
+不得让现有解析器“顺便支持”。
+
+## 11. 实现验收
+
+一个实现只有同时满足以下证据,才能声明支持 Script Surface v1:
+
+1. 冻结本文全部正例、反例、投影和 source-map golden fixtures;
+2. parser、formatter、Narrative IR 与三投影不依赖 provider 或渲染器;
+3. SelectionSet 支持闭合、交叉、非连通 occurrence 与左右 affinity;
+4. MomentSet 支持 `@id!` / `~@id!`、单/多 occurrence 与 `at` 类型闸;
+5. Dual Text 在 speech、caption 与时间映射上保持一个可审计 source map;
+6. Slot 采用 parse-first、literal-only binding,不能注入语法;
+7. 未知版本、未知保留语法、混合 temporal type 与 partial dual atom 全部
+ fail closed。