结合 Aeg 代码更新文档

README.md

@@ -1,21 +1,39 @@
-# ASS字幕文件说明
+ASS v4.00+ 字幕文件说明
+======================
 
-*这是我多年前所做的笔记，资料都是从网上摘抄，其中内容难免有缺失或错误。*
 
-## 第一部分 [Script Info]
++ ASS 字幕文件格式由 SSA 字幕格式修改而来。SSA v4.00+ 格式即为 ASS 字幕格式
++ Aegisub 为字幕编辑软件。编辑好的 ASS 字幕需要经过渲染才能显示出来
++ [常见的渲染后端][ass-impl]有：
+    [`libass`][libass]（Aeg 和[大多数软件][libass-user]默认后端）、
+    [VSFilter][VSFilter]、[xy-VSFilter][VSFilter]、[VSFilterMod][VSFilterMod]
++ 参考资料
+    + Aegisub ASS 解析实现细节，是当前的事实规范：[Aeg/ASS v4+ 脚本解析实现](https://www.yuque.com/woclass/aeg/aeg-assv4p)
+    + Aegisub 3.2 中文文档：[ASS特效标签](https://aegi.vmoe.info/docs/3.2/ASS_Tags/)
+    + 英文原版 ASS v4+ 规范，仅作历史参考用：[ASS v4.00+ 字幕文件规范](https://www.yuque.com/woclass/aeg/ass-v4.00plus)
+    + libass 库的 ASS v5 规范草稿：[ASS v5.0 · libass/libass Wiki](https://github.com/libass/libass/wiki/ASS-v5.0)
+
+[libass]: https://github.com/libass/libass
+[libass-user]: https://github.com/libass/libass#related-links
+[ass-impl]: https://github.com/libass/libass#other-assssa-implementations
+[VSFilter]: https://github.com/pinterf/xy-VSFilter/releases/latest
+[VSFilterMod]: https://github.com/sorayuki/VSFilterMod/releases/latest
+
+
+## 第一部分 `[Script Info]`
 
 *这一部分主要是记录了一些文件内容的标题和信息*
 
 ``` yaml
 [Script Info]
-; Script generated by Aegisub r8942
+; Script generated by Aegisub 3.3.2
 ; http://www.aegisub.org/
-!: 注释
+; 更多注释 <= Aeg 保存后此行会丢失
 Title: Default Aegisub file
 ScriptType: v4.00+
 WrapStyle: 0
 ScaledBorderAndShadow: yes
-YCbCr Matrix: TV.601
+YCbCr Matrix: None
 Original Script: 脚本原作者
 Original Translation: 译者
 Original Editing: 编辑
@@ -25,110 +43,89 @@ Script Updated By: 修订者
 Update Details: 修订详情，修订部分的描述
 PlayResX: 1280
 PlayResY: 720
-PlayDepth: 颜色深度
-Collsions: Normal
-Timer: 100.0000
 ```
 
-下面就`[Script Info]`这一部分作简单说明：
-
-* ASS文件第一行必须是`[Script Info]`
-
-* `;`后面可以填写任何内容
-
-* `!:`后面是注释部分
-
-* `Title:`脚本文件的标题
-
-* `ScriptType:`脚本格式`ASS`文件为`v4.00+`
-
-* `WrapStyle:`指定了当一行字幕过长时的**换行方式**
-
-  共有4种换行方式：
-
-  `0`:智能换行：上行较宽
-
-  `1`:于行尾词出换行：仅于`\N`后断行
-
-  `2`:不自动换行：于`\n`和`\N`后断行
-
-  `3`：智能换行：下行较宽
-
-* `ScaledBorderAndShadow:`字幕边框宽度和阴影深度是否随着视频分辨率等比缩放，`yes`或`no`
-
-* `YCbCr Matrix:`
-
+除固定字段 `ScriptType` 以外，其余信息均可在 Aeg 的 "脚本配置" 窗口进行设置。
+
+![](images\DialogProperties.png)
+
+下面就 `[Script Info]` 这一部分作简单说明：
+
+* ASS 文件第一行必须是 `[Script Info]`
+* `;` 后面是注释部分。可以填写任何内容，但在 Aeg 保存后会丢失。  
+    前两行注释为 Aegisub 自动生成的，保存时会自动更新。
+* `Title:` 脚本文件的标题
+* `ScriptType:` `ASS` 脚本固定为 `v4.00+`，其他值会报错。
+* `WrapStyle:` 指定了当一行字幕过长时的**换行方式**  
+    共有4种换行方式：
+    + `0`: 智能换行：上行较宽
+    + `1`: 于行尾词出换行：仅于 `\N` 后断行
+    + `2`: 不自动换行：于 `\n` 和 `\N` 后断行
+    + `3`: 智能换行：下行较宽
+* `ScaledBorderAndShadow:` 字幕边框宽度和阴影深度是否随着视频分辨率等比缩放，`yes` 或 `no`
+* `YCbCr Matrix:` 颜色空间转换
 * `Original Script:` 脚本原作者
-
 * `Original Translation:` 译者
-
 * `Original Editing:` 编辑
-
 * `Original Timing:` 时间轴人员
-
 * `Synch Point:` 同步点
-
 * `Script Updated By:` 脚本修订者
-
 * `Update Details:` 修订详情，修订部分的描述
+* `PlayResX:` 视频宽度；`PlayResY:` 视频高度，这两个定义了视频的分辨率
+* 未列出的字段如：`PlayDepth`, `Collisions`, `Timer` 均已废弃
 
-* `PlayResX:` 视频宽度`PlayResY:` 视频高度，这两个定义了视频的分辨率
-
-* `PlayDepth:` 显示颜色深度
-
-* `Collsions:` 字幕碰撞处理，当两条字幕重叠时，如何进行移动，共有两种方式
-
-  `Normal`：后一条字幕出现在前一条的上方
 
-  `Reverse`：前一条字幕向上移动给后一条字幕让位
-
-* `Timer:` 时间轴计时器，单位为`%`，默认为`100.0000`
-
-  大于`100`时，字幕会比预定越来越早的出现
-
-  小于`100`时，字幕会比预定越来越晚的出现
-
-  一般不改变，取默认`100.0000`
-
-## 第二部分 [V4+ Styles]
+## 第二部分 `[V4+ Styles]`
 
 *这一部分主要保存了字幕的样式*
 
 ``` yaml
 [V4+ Styles]
 Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Default,Arial,20,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,1
+Style: Default,Arial,48,&H00FFFFFF,&H000000FF,&H00000000,&H00000000,0,0,0,0,100,100,0,0,1,2,2,2,10,10,10,1
 ```
 
-以`[V4+ Styles]`作为这一部分的开始，紧跟着第二行`Format:`基本也是固定的，而`Style`行的各个**值**和`Format`行的各个**名字**之间是一一对应关系。这个部分就像是一张表单，`Format`行就是表头，`Style`行就是往表格里填的数据，大概就是这么一个关系，一个脚本可以设置多个字幕样式。
-
-下面讲一下每个名字的具体意义：
-
-* `Name`：样式名字
-* `FontName`：字体名称
-* `Fontsize`：字体大小
-* `PrimaryColour`：主要填充颜色
-* `SecondaryColour`：次要填充颜色，用于标准卡拉OK模式下的预填充
-* `OutlineColour`：字体边框颜色
-* `BackColour`：字体阴影色
-* `Bold`：粗体，**1开启，0关闭**
-* `Italic`：斜体，**1开启，0关闭**
-* `Underline`：下划线，**1开启，0关闭**
-* `StrikeOut`：删除线，**1开启，0关闭**
-* `ScaleX`：宽度缩放，单位为`%`，默认`100`
-* `ScaleY`：高度缩放，单位为`%`，默认`100`
-* `Spacing`：字体间距
-* `Angle`：旋转角度
-* `BorderStyle`：边框样式；默认为`1`，即使用正常字体边框，设置为`3`时，则使用不透明背景取代字体边框
-* `Outline`：边框宽度
-* `Shadow`：阴影距离
+![](images\StyleEditor.png)
+
+以 `[V4+ Styles]` 作为这一部分的开始，紧跟着第二行 `Format:` 也是固定的。
+而 `Style` 行的各个**值**和 `Format` 行的各个**名字**之间是一一对应关系。
+这个部分就像是一张表单，`Format` 行就是表头，`Style` 行就是往表格里填的数据，大概就是这么一个关系，一个脚本可以设置多个字幕样式。
+
+下面讲一下每个字段的具体意义：
+
+* `Name`：样式名称
+* 字体
+    * `FontName`：字体名称
+    * `Fontsize`：字体大小
+    * `Bold`：粗体，**1开启，0关闭**
+    * `Italic`：斜体，**1开启，0关闭**
+    * `Underline`：下划线，**1开启，0关闭**
+    * `StrikeOut`：删除线，**1开启，0关闭**
+* 颜色
+    * `PrimaryColour`：主要填充颜色
+    * `SecondaryColour`：次要填充颜色，用于标准卡拉OK模式下的预填充
+    * `OutlineColour`：字体边框颜色
+    * `BackColour`：字体阴影色
+* 边距
+    * `MarginL`：左边距
+    * `MarginR`：右边距
+    * `MarginV`：垂直边距
 * `Alignment`：字幕对齐方式
-* `MarginL`：左边距
-* `MarginR`：右边距
-* `MarginV`：垂直边距
-* `Encoding`：字体编码；默认为`1`
-
-## 第三部分 [Events]
+边框
+    * `Outline`：边框宽度
+    * `Shadow`：阴影距离
+    * `BorderStyle`：边框样式  
+        + 默认为 `1`，即使用正常字体边框；  
+        + 设置为 `3` 时，则使用不透明背景取代字体边框
+* 杂项
+    * `ScaleX`：水平缩放。默认 `100`，单位为 `%`
+    * `ScaleY`：垂直缩放。默认 `100`，单位为 `%`
+    * `Angle`：逆时针旋转角度
+    * `Spacing`：额外字体间距
+    * `Encoding`：字体编码。默认为 `1`
+
+
+## 第三部分 `[Events]`
 
 *这一部分就是字幕的主体部分，记录了对话的开始和结束时间，对话内容和显示等信息*
 
@@ -139,24 +136,28 @@ Dialogue: 0,0:00:01.24,0:00:01.99,Default,,0,0,0,,所以
 Comment: 0,0:00:00.00,0:00:00.00,Default,,0,0,0,,注释
 ```
 
-这一部分以`Events`作为开始，后面紧跟的`Format`基本也是固定的，后面的行和`Format`也是对应关系。
+这一部分以 `Events` 作为开始，后面紧跟的 `Format` 也是固定的，后面的行和 `Format` 也是一一对应关系。
 
-* `Layer`：字幕的**层**，当两条字幕重叠时，层数较大的会叠加在层数小的上面，如果层数相同，那么后出现的会叠加的先出现的上面，层数默认为`0`
-* `Start`：字幕的开始时间，精度为`0.01s`
-* `End`：字幕的结束时间，精度为`0.01s`
-* `Style`：样式名称，对应`[V4+ Styles]`中的`Name`项
+* `Layer`：字幕的**层**，层数默认为 `0`。  
+    当两条字幕重叠时，层数较大的会叠加在层数小的上面；  
+    如果层数相同，那么后出现的会叠加的先出现的上面
+* `Start`：字幕的开始时间，精度为 `1 ms`
+* `End`：字幕的结束时间，精度为 `1 ms`
+* `Style`：样式名称，对应 `[V4+ Styles]` 中的 `Name` 项
 * `Name`：说话人。只做参考，一般省略
-* `MarginL`：左边距。可对样式进行修改，默认为`0`采用原值，若不为`0`则取代原值
-* `MarginR`：右边距。可对样式进行修改，默认为`0`采用原值，若不为`0`则取代原值
-* `MarginV`：垂直边距。可对样式进行修改，默认为`0`采用原值，若不为`0`则取代原值
-* `Effect`：动态效果；`Scroll up, Scroll down, Banner, Karaoke`
-* `Text`：字幕。可以通过添加代码改变字幕，实现多种特效
+* `MarginL`：左边距。默认值为 `0`，非 0 则覆盖样式
+* `MarginR`：右边距。默认值为 `0`，非 0 则覆盖样式
+* `MarginV`：垂直边距。默认值为 `0`，非 0 则覆盖样式
+* `Effect`：特效参数。一般作为字幕模板的参数。  
+    `all, char, furi, fx, fxgroup, keeptags, line, loop,, multi, noblank, notext, pre-line, repeat, syl`
+* `Text`：字幕文本。可以通过添加代码改变字幕，实现多种特效
 
 每一行字幕开头的修饰语有两种：
 
 * `Dialogue`：正常的对话字幕内容
 * `Comment`：注释内容，这些行不会作为字幕内容显示在视频中
 
+
 ## 第四部分 代码及其作用
 
 在这一部分正式开始之前，先作一个简单的说明：
@@ -430,6 +431,3 @@ Comment: 0,0:00:00.00,0:00:00.00,Default,,0,0,0,,注释
 
 `filename: <filename>`
 
-**参考**
-
-[ASS特效标签](https://aegi.vmoe.info/docs/3.2/ASS_Tags/)