Subtitld 项目

文件结构

.usfx 就是一个 ZIP。任何压缩工具都能打开它；如果工具坚持，把扩展名改成 .zip 即可。

Tears of Steel.usfx
subtitles.usf
manifest.xml
thumbnail.png
assets/speakers/Celia.png
assets/dubs/77a03e27.wav
assets/video/Tears_of_Steel.mkv
assets/waveform.npy
assets/audio/vocals.flac

文档说明发生什么；资源是它要播放的内容。subtitles.usf 中的配音用包内路径 assets/dubs/77a03e27.wav 指向自己的片段，因此整个包可以移到另一个文件夹、磁盘或电脑上，依然完整。

成员

assets/ 中的名称由字母、数字、-、_ 和 . 组成；其他字符都变成 _，所以 Tears of Steel.mkv 存为 Tears_of_Steel.mkv。ASCII 以外的字母会保留，名称按 APPNOTE 的要求以 UTF-8 写入并加上相应标记（ZIP 头的第 11 位）。

开头的字节

每个项目的开头都一样：一个 ZIP 本地文件头，然后是第一个成员的名称。

50 4B 03 04
14 00 00 00 08 00
4E 70 51 5D
64 CE 1E 0B
6F 3B 00 00 7F E2 00 00
0D 00 00 00
73 75 62 74 69 74 6C 65 73 2E 75 73 66

即使成员被压缩，名称也从不压缩。这让它成为一种签名：第 30 字节处名称为 subtitles.usf 的 ZIP 就是 Subtitld 项目。Haiku 的 Tracker 正是用这条规则 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml") 把项目与其他压缩包区分开，其优先级高于普通 ZIP 规则。ODF 和 EPUB 也用名为 mimetype 的第一个成员做同样的事。

视频可能超过 ZIP 最初的 4 GiB 上限。从 2 GiB 起，Subtitld 会写入 Zip64 的扩展字段和结尾记录（APPNOTE 第 4.5 节），成员超过 65,535 个时也是如此；Subtitld、它的 Windows 缩略图处理程序以及任何现代 unzip 都能读取。

清单

<?xml version="1.0" encoding="UTF-8"?>
<manifest version="1.0">
  <format>USFX</format>
  <generator>Subtitld</generator>
  <source path="/home/ana/Videos/Tears of Steel.mkv"
          basename="Tears of Steel.mkv"/>
  <voicemix volume="0.5000"/>
  <entry path="subtitles.usf" type="application/x-usf+xml"/>
  <entry path="thumbnail.png" type="image/png"/>
  <entry path="assets/speakers/Celia.png" type="image/png"/>
  <entry path="assets/dubs/77a03e27.wav" type="audio/wav"/>
</manifest>

类型有 application/x-usf+xml、image/png、audio/wav、audio/flac、audio/mpeg、video/mp4、video/x-matroska、video/quicktime、video/webm、video/ogg，波形和其他一切则为 application/octet-stream。

文档

subtitles.usf 是一个 Universal Subtitle Format 文件，UTF-8 编码，与 Subtitld 单独写出的 USF 相同，只是按 USF 自己的风格加上了项目所需的内容：在 USF 没有对应项的地方加入元素和属性。跳过未知内容的 USF 读取器照样能读出其中的字幕。

<USFSubtitles version="1.0"
              xmlns:subtitldcc="https://subtitld.cc/ns/usf/1">
  <metadata>
    <title>Tears of Steel</title>
    <author><name>Subtitld</name></author>
    <language code="eng">English</language>
    <subtitldcc:origin share-id="Xk3pQ9aZ2bT" version="3"/>
  </metadata>
  <styles>
    <style name="Celia">
      <fontstyle color="#e5484d"/>
      <dubbing engine="edge-tts" voice="en-GB-SoniaNeural"
               rate="0" pitch="0" fit_to_subtitle="true"/>
    </style>
  </styles>
  <subtitles>
    <language code="eng">English</language>
    <subtitle start="00:00:23.000" stop="00:00:24.500">
      <text speaker="Celia" style="Celia">You're a jerk, Thom.</text>
      <dubbing uid="77a03e27" engine="edge-tts"
               voice="en-GB-SoniaNeural" rate="0" pitch="0"
               path="assets/dubs/77a03e27.wav"
               start="23.0" end="24.5"/>
    </subtitle>
  </subtitles>
  <subtitles>
    <language code="por">Portuguese (Brazil)</language>
    <subtitle start="00:00:23.000" stop="00:00:24.500">
      <text speaker="Celia" style="Celia">Você é um idiota, Thom.</text>
    </subtitle>
  </subtitles>
</USFSubtitles>

Subtitld 为 USF 添加的内容

在普通的 .usf 中，说话人图片和配音音频可以以 base64 形式放在 XML 里的 <avatar> 和 <data> 中。.usfx 从不这样做：它们是独立的成员，比 base64 小四分之一，而且无需解析 XML 即可读取。

时间

字幕的 start 和 stop 是 USF 时间，四舍五入到最接近的毫秒。配音的时间是完整写出的纯秒数，如 18.01579117916244：能读回为同一个 64 位数的最短小数，因此拖动放置的片段会精确回到原来的位置。

旧版 Subtitld 写入的时间早一毫秒，并把从零开始的时间写成 23:59:59.999。Subtitld 会把该值读作零，其余那一毫秒保持不变。

录音与子片段

一条字幕可以有多条录音。第一个 <dubbing> 是播放的那条；其他是备选，在你选中之前保持静音，选中后会移到最前面。

被分割或拉伸的录音保存一个 <subclip> 列表，像音频编辑器中的片段一样排布：

子片段从录音的 start 加上它的 offset 处开始播放，持续 end 减 start 秒。空隙是静音；重叠部分会混音。源文件从不修改，因此每次分割和拉伸都可以撤销，拉伸也总是从 raw_path 重新生成，绝不在拉伸结果上再拉伸。

译文

每种语言都有自己的 <subtitles> 块，用 ISO 639-2 代码命名，元素中还写有语言名称，以此区分巴西葡萄牙语和葡萄牙的葡萄牙语。每个块在相同时间包含每条字幕；只有第一个块包含配音。Subtitld 按开始时间，或按重叠最多的字幕，把译文与字幕对应起来，因此其他工具写出的块不必严格对齐。

打开项目

大型项目也能立即打开：Subtitld 先读取编辑器需要的内容，其余部分在你工作时读取。

成员会解压到 Subtitld 自己的文件夹中，从不放在项目旁边：文档、头像和配音放入一个以项目路径的 MD5 命名的缓存文件夹。工作期间到达的内容以 1 MiB 的块流式写入临时文件，完成后再重命名到位，因此中途崩溃不会留下写了一半的文件。下次打开同一项目时，已有文件只有在大小与成员完全一致时才会被重用；否则重新解压。

视频按以下顺序查找：

1. 包内 assets/video/ 中的视频；
2. <source path> 中的路径，如果文件仍在；
3. 项目文件夹中名称与 <source basename> 相同的文件；
4. 否则，Subtitld 会请你指定。

不是 ZIP、被截断或未通过 CRC 校验的文件不会打开任何内容：Subtitld 会提示原因，并把它从最近列表中移除。早期的项目也能打开：没有清单的，或 USF 以其他名称放在 ZIP 根目录的。

保存项目

保存绝不会让你现有的项目面临风险。

1. 快照。 项目按你保存那一刻的状态复制，因此写入期间你可以继续编辑。保存、自动保存和备份轮流进行：同一时间只有一个在写入。
2. 新文件。 包被写入项目旁边的 <project>.usfx.tmp。
3. 不缺任何内容。 音频尚未进入缓存（仍在传入或已被清除）的配音，会从即将被替换的文件中复制。没有视频时保存的项目保留原有的图片。
4. 校验。 重新打开新文件，并验证每个成员的 CRC-32。
5. 替换。 只有这时它才通过一次重命名（os.replace）替换项目：项目的名称下永远不会是半个项目。

任何一步失败，临时文件都会被删除，磁盘上仍是你原来的项目，你的编辑也仍在 Subtitld 中打开着。项目的配音仍在传入时，保存会等待它们。

包含哪些内容

全局设置中的 USFX 选择项目还要携带哪些内容，适用于你保存的每个项目：

• 说话人头像说话人的脸。开启。
• 时间轴波形缓存波形，这样项目在另一台电脑上打开时无需重新计算。关闭。
• 原始音频轨视频的声音，FLAC 格式。关闭。
• 处理后的音频（人声 + 背景）分离成人声和其余部分的声音，FLAC 格式，这样无需再次运行分离。关闭。
• 原始视频文件视频本身：一个包含一切的文件，和视频一样大，甚至更大。关闭。

每一项都在 Subtitld 有内容可放时才加入：比如分离的声音，只有运行过分离之后才有。字幕、译文、说话人、声音和每段配音始终包含在内。Deflate 能把配音的 WAV 缩小约六分之一；视频和 FLAC 几乎不会变小。

自动保存与备份

• 自动保存项目文件像保存一样，以同样安全的方式写入你的 .usfx 本身。适用于以 USFX 保存的项目。
• 自动备份有需要保留的改动时，在 Subtitld 的备份文件夹中（与你自己的文件分开）写入一个完整的 .usfx，命名为 <project>_<YYYYMMDDHHMMSS>.usfx。超过最多保留的数量（默认 20，除非你另行选择）时，最旧的会被删除。

在文件管理器中

缩略图是一张 Subtitld 风格的卡片：项目停留处的视频帧、帧上的字幕，下方是播放头周围十二秒的时间轴，带有波形和按说话人颜色显示的字幕。512 × 384 的 4:3 比例，比宽画幅更能填满文件管理器的方形格子。没有视频时，用 Subtitld 的标志代替画面。

在这四个系统上双击项目都会在 Subtitld 中打开。两个缩略图生成器都只读取 thumbnail.png，拒绝超过 8 MiB 的文件，并且不接受任何不以 PNG 签名 89 50 4E 47 0D 0A 1A 0A 开头的内容。Windows 版只接受像 Subtitld 写入的那样不压缩存放的图片。Linux 版只使用 Python 标准库，因为文件管理器会在沙盒中同时运行许多缩略图生成器。

自己读取 .usfx

项目中没有任何东西是 Subtitld 独有的。查看其内容：

unzip -l "Tears of Steel.usfx"
unzip -p "Tears of Steel.usfx" manifest.xml

用 Python 标准库读取所有语言的字幕：

import zipfile
import xml.etree.ElementTree as ET

def text_of(element):
    """A <text>'s words, <br/> as a line break."""
    parts = [element.text or '']
    for child in element:
        parts.append('\n' if child.tag == 'br' else text_of(child))
        parts.append(child.tail or '')
    return ''.join(parts)

with zipfile.ZipFile('Tears of Steel.usfx') as usfx:
    usf = ET.fromstring(usfx.read('subtitles.usf'))

for block in usf.iter('subtitles'):
    language = block.find('language')
    if language is not None:
        print('#', language.get('code'), language.text)
    for subtitle in block.iter('subtitle'):
        text = subtitle.find('text')
        print(subtitle.get('start'), subtitle.get('stop'),
              text.get('speaker'), text_of(text))

对于他人提供的项目，请用 defusedxml 代替 xml.etree 进行解析，处理任何不是你写的 XML 都应如此。

自己制作一个

Subtitld 能打开的最小项目是一个包含 subtitles.usf 的 ZIP。没有清单时，Subtitld 会请你指定视频。要制作一个文件管理器也能识别的项目，请照 Subtitld 的写法：

• 先 subtitles.usf，再 manifest.xml；
• 每个成员都用 Deflate 压缩，只有 thumbnail.png 不压缩存放；
• 配音放在 assets/dubs/ 下，在文档中以包内路径引用；
• 全部使用 UTF-8。

对比

USFX 的构造与办公套件和电子书的文档包相同：一个 ZIP、一个 XML 主文档、一份清单，以及旁边的媒体。

主文档本身就是一种开放格式：把 .usfx 中的 subtitles.usf 取出来，它就是一个 USF 文件，而 USF 自 2002 年起就有公开规范。

小知识