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以外の文字はそのまま残り、名前はUTF-8で書かれ、APPNOTEの求めるとおりその旨のフラグ（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リーダーなら、その字幕を読めます。

<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 では、話者の画像や吹き替えの音声を <avatar> と <data> にbase64でXML内に持たせられます。.usfx ではそうしません。それらは独立したメンバーになり、base64より4分の1小さく、XMLを解析せずに読めます。

時刻

字幕の start と stop はUSFの時刻で、最も近いミリ秒に丸められます。吹き替えの時刻は省略せずに書いた素の秒数 18.01579117916244 です。同じ64ビットの数値として読み戻せる最短の10進数なので、ドラッグで置いたクリップは元の位置に正確に戻ります。

古いバージョンのSubtitldは時刻を1ミリ秒早く書き、ゼロの開始を 23:59:59.999 と書いていました。Subtitldはその値をゼロとして読み、ミリ秒はそのままにします。

テイクとサブクリップ

1つの字幕は複数のテイクを持てます。最初の <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. スナップショット。 保存した時点のプロジェクトがコピーされるので、書き込み中も編集を続けられます。保存、自動保存、バックアップは順番に行われ、同時に書き込むのは1つだけです。
2. 新しいファイル。 パッケージはプロジェクトの隣の <project>.usfx.tmp に書き込まれます。
3. 欠けなし。 音声がまだキャッシュにない吹き替え（読み込み中、または消去済み）は、置き換えられる予定のファイルからコピーされます。動画なしで保存したプロジェクトは、元の画像を保ちます。
4. 検査。 新しいファイルを開き直し、すべてのメンバーのCRC-32を検証します。
5. 入れ替え。 そのうえで初めて、1回のリネーム（os.replace）でプロジェクトを置き換えます。プロジェクトの名前が書きかけのプロジェクトを指すことはありません。

どこかの段階で失敗すると、一時ファイルは削除され、ディスク上のプロジェクトは元のままで、編集内容はSubtitldで開いたままです。プロジェクトの吹き替えがまだ読み込み中のときは、保存はそれを待ちます。

中に入れるもの

全体設定のUSFXで、保存するすべてのプロジェクトに何を追加で含めるかを選びます。

• 話者のポートレート画像話者の顔。オン。
• タイムラインの波形キャッシュ波形。別のコンピューターで開いても再計算せずに済みます。オフ。
• 元の音声トラック動画の音声をFLACで。オフ。
• 処理済み音声（ボーカル + 背景）ボーカルとそれ以外に分離した音声をFLACで。分離をもう一度実行せずに済みます。オフ。
• 元の動画ファイル動画そのもの。すべてを1ファイルにまとめ、動画以上の大きさになります。オフ。

それぞれ、Subtitldが入れるものを持っているときに入ります。たとえば分離した音声は、分離を実行した後だけです。字幕、翻訳、話者、音声、そしてすべての吹き替えは常に含まれます。Deflateは吹き替えのWAVを約6分の1小さくしますが、動画やFLACはほとんど縮みません。

自動保存とバックアップ

• プロジェクトファイルを自動保存する保存と同じ安全な方法で、.usfx そのものに書き込みます。USFXとして保存したプロジェクトが対象です。
• 自動バックアップ変更があるとき、自分のファイルとは別に、Subtitldのバックアップフォルダーに完全な .usfx を <project>_<YYYYMMDDHHMMSS>.usfx という名前で作ります。最大保持数（指定しなければ20）を超えると、古いものから削除されます。

ファイルマネージャーでの表示

サムネイルはSubtitldの見た目のカードです。プロジェクトを中断した動画のフレームとその字幕、その下に再生ヘッド前後12秒のタイムライン、波形、話者の色の字幕が並びます。4:3の512 × 384なので、横長のフレームよりもファイルマネージャーの正方形のセルをうまく埋めます。動画がない場合は、フレームの代わりにSubtitldのマークが入ります。

4つのどのシステムでも、ダブルクリックするとプロジェクトが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))

他人から受け取ったプロジェクトは、自分が書いたものでないXMLと同じく、xml.etree の代わりに defusedxml で解析してください。

自分で作る

Subtitldが開ける最小のプロジェクトは、subtitles.usf を1つ含むZIPです。マニフェストがなければ、Subtitldは動画の場所を尋ねます。ファイルマネージャーにも認識されるものを作るには、Subtitldが書く形に従ってください。

• 最初に subtitles.usf、次に manifest.xml。
• すべてのメンバーをDeflateで圧縮。ただし thumbnail.png は無圧縮。
• 吹き替えは assets/dubs/ の下に置き、ドキュメントではパッケージ内のパスで指す。
• すべてUTF-8。

他の形式との比較

USFXは、オフィススイートや電子書籍の文書パッケージと同じ作りです。ZIP、XMLのメインドキュメント、目録、そしてその隣のメディア。

メインドキュメントはそれ自体がオープンなフォーマットです。.usfx から subtitles.usf を取り出せば、それは2002年から仕様が公開されているUSFファイルです。

豆知識