项目
项目页：由一组角色逐句朗读整本书、剧本或对话，包括导入脚本、编辑台词、生成、管理版本与导出带字幕的音频。
项目 用来朗读长篇内容：一本书、一份剧本或一段多人对话。一个项目由两部分组成：
- 脚本：若干章节，每章是一句一句的台词。每句有文本和说话的角色，可以单独加风格指令。
- 角色表：每个角色有自己的模型、音色（音色库中的音色、预置说话人或模型自带的音色）、语言、说话方式和参数。第一个角色是旁白：没有指定角色的句子都由旁白朗读。没有选模型的角色使用项目的模型。
每一句单独生成，生成结果称为一个版本。改了某句的文本、角色或设置后，只需重新生成这一句；最后把所有句子按设定的停顿拼成一个文件，并附带字幕。不同角色可以用不同引擎的模型。
项目保存在数据文件夹的 projects/<名称>/project.json 中。
项目列表
在导航栏打开 项目。每张卡片显示项目名称、已生成句数/总句数（有失败的句子时显示为红色）、描述、N 章 · N 句、N 个角色、已生成部分的时长，以及一条按句子状态着色的进度条。点卡片打开项目。
新建项目
- 点 新建项目。
- 填写 项目名称。
- 选择 模型：项目的默认模型，旁白和其他没有单独选模型的角色都用它。
- 可选：在 脚本 中粘贴一份脚本（格式见下一节），并在 按此切分台词 中选择 每行文本 或 每个句子。
- 点 创建。
新项目自带一个名为 旁白 的角色。
脚本格式
导入的脚本是纯文本，规则如下（输入框下方也有提示）：
| 写法 | 含义 |
|---|---|
# 标题 | 开始新的一章，标题为 # 之后的文字 |
名字：文本（全角或半角冒号），或 [名字]: 文本 | 该角色的一句台词（见下方规则） |
| 其他行 | 旁白的台词 |
| 空行 | 结束一个段落（导出时段落之后的停顿更长） |
名字： 前缀在以下任一情况下才被当作角色名，否则整行原样作为旁白的台词：
- 这个名字已经在角色表中；
- 同一个名字出现在两行或更多行的开头；
- 脚本是一段对话（已有某个名字满足上面两条之一），并且这个前缀看起来像名字：以字母或汉字开头、最多三个词，例如
Dr. Watson、林黛玉。
因此，在不是对话的脚本中，偶尔出现的“注意：明天停电”不会被当作角色；但在对话脚本中，任何看起来像名字的前缀都会成为角色。每个名字都只出现一次的对话不会被识别，这时先在 角色 中添加同名角色再导入即可。
新出现的名字自动加入角色表。它们还没有模型和音色（使用项目的模型），导入后在 角色 中为它们选择音色。
第一个 # 之前的台词放进一章：项目还没有任何章节时，这章以项目名为标题，否则不加标题。
按此切分台词：每行文本 时每行是一句；每个句子 时每行再按句子拆成多句。
示例：
# 第一章 夜行列车
列车在黑暗中穿行。车厢里只剩下两个人。
安娜：你也睡不着吗？
老人：这条路，我走了四十年了。
安娜：四十年？
老人：从它还是一条土路的时候起。
窗外，一盏灯一闪而过。导入后得到一章、六句：“安娜”和“老人”各出现两次，成为两个新角色；其余句子归旁白；第一段、对话段和最后一句各是一个段落。
导入脚本
在项目页底部点 导入脚本（项目为空时页面中间也有这个按钮），粘贴脚本，选择切分方式和 导入方式：
| 导入方式 | 作用 |
|---|---|
| 作为新章节 | 把脚本中的章节追加到项目末尾 |
| 加到本章 | 把所有台词追加到当前打开的章节，不新建章节（# 标题行会被忽略） |
| 替换现有脚本 | 用脚本中的章节替换全部现有章节；原有台词的版本会被删除 |
点 导入。
编辑脚本
项目页有三个标签页：脚本、角色、导出。顶部显示项目名称、保存状态（正在保存…、已保存、有未保存的修改）和“已生成句数/总句数 · 时长”。
所有修改在停止输入后不久自动保存，离开页面时也会保存，不需要手动保存。
章节
左侧 章节 列出所有章节，每章显示“已生成/总句数”；点章节名切换。添加章节 新建一章。右侧上方是 章节标题，旁边的菜单中有 上移、下移 和 删除本章（会同时删除这些句子的版本）。
台词
每句一行，从左到右是：
- 状态圆点（悬停显示状态名称，见下一节）；
- 角色：选择说这句话的角色；选第一个角色（旁白）就是不指定角色；
- 文本：在文本框中按 Ctrl+Enter 在下方插入一句；
- 播放按钮：播放这句当前使用的版本；
- 重新生成这一句：立即为这句生成一个新版本，即使它已经是最新的；
- 更多操作菜单：
| 菜单项 | 作用 |
|---|---|
| 在下方插入一句 | 新句沿用这一句的角色 |
| 在此结束段落 / 与下一句同段 | 设置段落结尾，影响导出时的停顿 |
| 添加风格指令 | 显示 这一句的风格，这句用它代替角色的 说话方式 |
| 上移 / 下移 | 调整顺序 |
| 在“合成”中试听 | 把这一句的完整请求（模型、音色、文本、参数）载入合成页，方便调试 |
| 第 N 版（秒数） | 这一句的各个版本，当前使用的带有 ✓；点一个切换 |
| 删除 | 删除这一句及其版本 |
本章末尾的 添加一句 在最后追加一句。生成失败的句子下方会显示失败原因。
台词状态
| 状态 | 含义 |
|---|---|
| 已生成 | 有版本，而且与当前的文本和设置一致 |
| 修改后未重新生成 | 有版本，但之后改过文本、角色、角色的模型、音色或参数，或者所用的音色库音色本身改过 |
| 未生成 | 还没有版本 |
| 失败 | 最近一次生成失败，原因显示在句子下方 |
| 生成中 | 正在生成 |
| 空 | 没有文本，生成和导出时跳过 |
角色
角色 标签页上方的 项目 部分可以修改项目的 模型、项目名称 和 描述。下面是每个角色一张卡片：
- 角色名称；第一个角色带有 旁白 标记；旁边显示这个角色的句数和移除按钮。移除角色后，它的台词交给旁白。
- 模型：没选时标签显示 模型（使用项目的：…）；选了之后可以点 使用项目的模型 改回。
- 音色：音色库中的音色、预置说话人 或 模型自带音色，只列出这个模型支持的方式。选音色库音色时，选择器同样标出这个模型能否使用每个音色。
- 语言：使用项目的语言，或模型支持的某种语言。
- 说话方式：这个角色每句话的风格指令（模型支持指令时才显示）。
- 参数：展开后与合成页的参数面板相同；有改动时显示 已设置 N 项。
添加角色 新建一个角色。项目本身的语言在同一标签页的 项目 中设置（语言；由各模型决定 表示交给各模型），也可以用 mizuoto project set --lang。
修改角色会让句子过期
角色的模型、音色、语言、说话方式或参数变化后，这个角色已生成的句子都会变为 修改后未重新生成。导出设置中的 每句音量统一 也属于生成设置，修改它会让所有句子过期。
生成
页面底部有两个按钮：
- 生成本章（N）：生成当前章节中所有不是 已生成 的句子（未生成、过期、失败的）。
- 全部生成（N）：对整个项目做同样的事。
生成是一个 生成项目 任务，每章一个步骤。它为每句提交一个普通的合成任务，同时保持最多 8 个在排队，这样 设置 › 语音 › 合并等待中的请求 可以把模型、音色和设置都相同、只有文本不同的句子合并为一批运行（在支持批处理的引擎上，例如 Qwen3-TTS、GPT-SoVITS、OmniVoice）。这些合成任务不会逐个弹出提示，只有整个生成任务结束时提示一次。
- 一句失败不影响其他句子：失败的句子标为 失败 并记下原因，其余继续生成。
- 取消生成任务会一并取消它已提交的合成任务。
- 生成过程中仍可以编辑脚本；改过的句子会按新的内容判断是否过期。
版本
每次生成一句都会新增一个版本并立即使用它。每句最多保留 5 个版本，更早的、未在使用的版本会被删除。在台词菜单中点 第 N 版 可以换回旧版本。
版本是 FLAC 格式的结果，不显示在历史中。删除句子、章节或项目时，它们的版本一并删除。
导出
导出 标签页：
| 设置 | 默认 | 作用 |
|---|---|---|
| 句间停顿（毫秒） | 350 | 同一段落内两句之间的静音 |
| 段间停顿（毫秒） | 800 | 段落结尾之后的静音 |
| 章间停顿（毫秒） | 2000 | 一次导出多章时，章与章之间的静音 |
| 格式 | WAV | WAV、FLAC、MP3、OGG、M4A |
| 采样率 | 24000 | 所有版本重采样到这个采样率（不同角色的模型采样率可能不同） |
| 每句音量统一 | 按响度 | 按响度、按峰值 或 保持原样；在生成每句时应用 |
导出已生成的部分：关闭时（默认），要导出的范围内每一句都必须是 已生成，否则报错；打开后，从未生成的句子不导出，修改后未重新生成的句子使用它们现有的录音。
然后点：
- 导出本章：只导出当前章节；文件名为“项目名 — 章节标题”。
- 全部导出：整个项目导出为一个文件。
导出是一个 导出项目 任务。完成后文件出现在下方的 已导出的文件 中，每个文件可以播放、下载，以及下载 字幕（SRT）：每句一条字幕，时间与音频对齐。导出的文件也会出现在历史中。
删除
页面底部的 删除 把项目及其全部版本移到回收站。
命令行
| 命令 | 作用 |
|---|---|
mizuoto project new <名称> [-m 模型] [--voice 音色 | --preset 说话人] [-l 语言] [--script 文件] [--split line|sentence] | 新建项目，带一个旁白和可选的脚本 |
mizuoto project import <项目> <脚本> [--split …] [--replace] [--chapter 章节id] | 导入脚本（追加、替换或加到某章） |
mizuoto project cast <项目> <角色id> [--name] [-m] [-v] [--preset] [-l] [--instruct] [-p 参数=值] [-O 选项=值] [--remove] | 添加、修改或移除角色；新的 id 即新角色，'' 表示清空 |
mizuoto project set <项目> [--name] [-m] [-l] [--line-pause] [--paragraph-pause] [--chapter-pause] [-f] [--sample-rate] [--normalize] | 修改项目设置 |
mizuoto project render <项目> [-c 章节id] [--line 句子id] [--force] | 生成没有最新版本的句子；--force 连已生成的也重新生成 |
mizuoto project export <项目> [-o 文件] [-c 章节id] [-f 格式] [--srt 字幕文件] [--allow-missing] | 导出；--srt 写出 .srt 或 .vtt 字幕 |
mizuoto project show <项目> | 显示角色表和每句的状态（含章节和句子的 id） |
mizuoto project script <项目> | 把项目打印为可再次导入的脚本 |
mizuoto project list | 列出项目 |
mizuoto project delete <项目> | 移到回收站 |
示例：
mizuoto project new "夜行列车" -m qwen3tts/1.7b-custom-voice --preset ryan --script book.txt
mizuoto project cast 夜行列车 anna --name 安娜 --preset serena
mizuoto project render 夜行列车
mizuoto project export 夜行列车 -o book.mp3 --srt book.srt