Skip to content

script-format.md

Latest commit

 

History

History
173 lines (122 loc) · 6.31 KB

script-format.md

File metadata and controls

173 lines (122 loc) · 6.31 KB
Raw

📖 EchoForge Script Format Specification / 台本格式完整规范

English below · 中文版见下半部分

English

An EchoForge script is a plain UTF-8 text file. Each line is one of: dialogue, directive, or comment.

1. Dialogue lines

Two interchangeable forms:

【Role Name】The line to speak.
Role Name: The line to speak.
  • Role names: 1–32 characters, no spaces in the Name: form.
  • Lines without a role prefix are appended to the previous dialogue (multi-line speeches).
  • Emotion markers belong inside the line:
    • S2 family models (s2.1-pro, s2.1-pro-free, s2-pro): [softly], [laughing], [pause] — free-form natural language
    • S1 model: (softly), (laughing) — 64+ fixed expressions

2. Directives

All directives start with # and occupy exactly one line.

Directive Arguments Effect
#BGM=name library name (Chinese alias, filename, or with extension) Sets BGM for all following segments
#BGM=name,fadein,fadeout seconds …and per-directive fade lengths for following dialogue blocks
#BGM=none — Clears BGM
#SFX=name SFX name Inserts a sound-effect segment at this position
#SFX=name,volume 0.1–1.5 (default 0.9) …with custom volume
#MUSIC=name,seconds name optional, 1–300 s Music-only interlude, auto-loops if track is shorter
#MUSIC=seconds Uses the current BGM
#END=name,seconds default 20 s Ending theme — long fade-out, place last

3. Comments & decorations

  • // anything — ignored
  • Lines starting with # that are not recognized directives are ignored
  • Pure decoration lines (═══, ───, ***) are filtered automatically

4. Segment types produced by the parser

type counts as dialogue? needs voice? notes
voice yes yes (character must have a bound voice, unless mock mode) may carry pre_seconds / post_seconds inherited from #BGM=f,i,o
sfx no no mixed with 0.15 s compact gap
music no no instrumental interlude
end no no ending theme, 3 s fade-out

5. Full example

// ===== Act 1: The Late Visitor =====

#SFX=doorbell
【Narrator】Half past eleven at night, the bell of the old bookstore rang.
Store owner: A customer… this late?
#SFX=footsteps,1.1
Girl: [softly] I'm looking for a book — one that never grows old.

// ===== Act 2: The Promise =====

#BGM=Night Piano,3,8
#SFX=page flip
【Narrator】Dust drifted through the yellow lamplight.
Store owner: [sigh] This book has waited forty years for you.

#MUSIC=Suspense Pulse,10

Girl: [choked] She never mentioned this place…
Store owner: She said a child with her eyes would come.

#BGM=Moonlight Lullaby
【Narrator】On the flyleaf, a faded line of ink: "To the future Xiaoman — may stories keep you gentle. — Grandma"

// ===== Ending =====
#END=Moonlight Lullaby,18

中文

EchoForge 台本是一个 UTF-8 纯文本文件，每一行要么是台词、要么是指令、要么是注释。

1. 台词行

两种写法可混用：

【角色名】要说的台词。
角色名：要说的台词。
  • 角色名 1~32 字符；角色名： 写法中角色名不能含空格
  • 无角色前缀的行会并入上一段台词（多行台词）
  • 情感标记写在台词内：
    • S2 系模型（s2.1-pro / s2.1-pro-free / s2-pro）：[轻声] [笑] [停顿]，自然语言任意描述
    • S1 模型：(轻声) (笑)，64+ 固定表达式

2. 指令

所有指令以 # 开头，独占一行。

指令 参数 作用
#BGM=名称 库名（中文名/文件名/带扩展名均可） 设置后续所有段落的 BGM
#BGM=名称,前奏秒,尾奏秒 秒数 同时指定后续台词块的淡入/淡出时长
#BGM=无 — 清除 BGM
#SFX=名称 音效名 在此位置穿插一个音效段
#SFX=名称,音量 0.1~1.5（默认 0.9） 自定义音量
#MUSIC=名称,秒数 名称可省略，1~300 秒 纯音乐留白，音源不足自动循环补足
#MUSIC=秒数 使用当前 BGM
#END=名称,秒数 缺省 20 秒 片尾曲——长淡出，放台本最后一行

3. 注释与装饰

  • // 任意内容 —— 忽略
  • 以 # 开头但不是合法指令的行 —— 忽略
  • 纯装饰线（═══、───、***）自动过滤

4. 解析产出的段类型

类型 计入台词 需要音色 说明
voice 是 是（需绑定音色，离线模式除外） 可携带从 #BGM=名,i,o 继承的 pre_seconds / post_seconds
sfx 否 否 混音采用 0.15 秒紧凑间隔
music 否 否 纯音乐留白
end 否 否 片尾曲，3 秒淡出

5. 完整示例

// ===== 第一幕：深夜来客 =====

#SFX=门铃
【旁白】深夜十一点半，旧书店的风铃忽然响了。
店主：这么晚……还有人上门？
#SFX=脚步声,1.1
女孩：[轻声] 我来找一本……不会老去的书。

// ===== 第二幕：尘封的约定 =====

#BGM=夜色钢琴,3,8
#SFX=翻书声
【旁白】灯光昏黄，尘埃在光柱里缓缓飞舞。
店主：[叹息] 这本书，等了你四十年。

#MUSIC=悬疑脉冲,10

女孩：[哽咽] 她从来没提过这里……
店主：她说，等她走后，会有一个眼睛很像她的孩子来找这本书。

#BGM=月光摇篮曲
【旁白】扉页上，一行褪色的钢笔字："给未来的小满——愿故事待你温柔。奶奶字"

// ===== 片尾 =====
#END=月光摇篮曲,18

6. 内置资源名（Built-in library names）

BGM（全部 ≥2 分钟，钢琴为主）: 夜色钢琴 Night Piano · 暖阳圆舞曲 Sunshine Waltz · 月光摇篮曲 Moonlight Lullaby · 雨夜钢琴 Rainy Night Piano · 悬疑脉冲 Suspense Pulse

SFX（20 个）: 雷声 thunder · 关门声 door · 脚步声 footsteps · 电话铃 phone · 门铃 doorbell · 风声 wind · 心跳 heartbeat · 铃铛 bell · 魔法闪光 sparkle · 时钟滴答 clock · 翻书声 page flip · 键盘敲击 typing · 水滴 droplet · 鸟鸣 birds · 玻璃碎裂 glass · 闹钟 alarm · 门轴吱呀 squeak · 篝火 campfire · 电子蜂鸣 buzzer · 远处汽笛 distant whistle

旧版名称（如 温暖氛围垫）会自动映射到新曲。