Subtitld-Projekt

Aufbau einer Datei

Eine .usfx ist ein ZIP. Jedes Archivprogramm öffnet sie, notfalls in .zip umbenannt, wenn das Programm darauf besteht.

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

Das Dokument sagt, was geschieht; die Assets sind, was es abspielt. Eine Synchronisation in subtitles.usf nennt ihren Clip über seinen Pfad im Paket, assets/dubs/77a03e27.wav, sodass das Paket in einen anderen Ordner, auf eine andere Festplatte oder einen anderen Computer wandern kann und vollständig bleibt.

Die Einträge

Namen in assets/ bestehen aus Buchstaben, Ziffern, -, _ und .; alles andere wird zu _, also wird Tears of Steel.mkv als Tears_of_Steel.mkv gespeichert. Buchstaben außerhalb von ASCII bleiben erhalten; der Name wird in UTF-8 geschrieben und als solcher markiert (Bit 11 des ZIP-Headers), wie APPNOTE es verlangt.

Die ersten Bytes

Jedes Projekt beginnt gleich: mit einem lokalen ZIP-Dateiheader, dann dem Namen seines ersten Eintrags.

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

Der Name wird nie komprimiert, auch wenn der Eintrag es ist. Das macht ihn zu einer Signatur: Ein ZIP, dessen Name bei Byte 30 subtitles.usf lautet, ist ein Subtitld-Projekt. Der Tracker von Haiku unterscheidet Projekte genau nach dieser Regel von anderen Archiven, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), höher eingestuft als die Regel für einfaches ZIP. ODF und EPUB machen es ebenso, mit einem ersten Eintrag namens mimetype.

Ein Video kann größer sein als die ursprüngliche Grenze von ZIP, 4 GiB. Ab 2 GiB schreibt Subtitld die Zusatzfelder und Endeinträge von Zip64 (APPNOTE Abschnitt 4.5), ebenso ab 65.535 Einträgen; Subtitld, sein Windows-Miniaturansichts-Handler und jedes aktuelle unzip lesen sie.

Das Manifest

<?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>

Die Typen sind application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg und application/octet-stream für die Wellenform und alles andere.

Das Dokument

subtitles.usf ist eine Datei im Universal Subtitle Format, UTF-8, so wie Subtitld sie auch allein schreibt, ergänzt um das, was ein Projekt braucht, im Stil von USF: Elemente und Attribute, wo USF keine hat. Ein USF-Leser, der überspringt, was er nicht kennt, liest seine Untertitel.

<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>

Was Subtitld zu USF hinzufügt

In einer einfachen .usf können Sprecherbilder und der Ton von Synchronisationen im XML mitreisen, als Base64 in <avatar> und <data>. Eine .usfx tut das nie: Sie sind eigene Einträge, ein Viertel kleiner als in Base64, und werden gelesen, ohne das XML zu parsen.

Zeiten

start und stop eines Untertitels sind USF-Zeiten, auf die nächste Millisekunde gerundet. Die Zeiten einer Synchronisation sind einfache Sekunden, vollständig ausgeschrieben, 18.01579117916244: die kürzeste Dezimalzahl, die sich als dieselbe 64-Bit-Zahl zurücklesen lässt, sodass ein per Ziehen platzierter Clip genau dorthin zurückkehrt, wo er war.

Ältere Versionen von Subtitld schrieben Zeiten eine Millisekunde zu früh, und einen Beginn bei null als 23:59:59.999. Subtitld liest diesen Wert als null und lässt die Millisekunde, wie sie ist.

Aufnahmen und Teilclips

Ein Untertitel kann mehrere Aufnahmen haben. Das erste <dubbing> ist das, was spielt; die anderen sind Alternativen, stumm, bis Sie eine wählen, die dann nach vorn rückt.

Eine geteilte oder gedehnte Aufnahme führt eine Liste von <subclip>s, platziert wie Clips in einem Audioeditor:

Ein Teilclip spielt ab dem start der Aufnahme plus seinem offset, für end minus start Sekunden. Lücken sind Stille; Überlappungen werden gemischt. Die Quellen werden nie verändert, sodass sich jedes Teilen und Dehnen rückgängig machen lässt, und eine Dehnung wird immer aus raw_path neu erstellt, nie aus der Dehnung einer Dehnung.

Übersetzungen

Jede Sprache hat ihren eigenen <subtitles>-Block, benannt nach ihrem ISO-639-2-Code und, im Element, dem Namen der Sprache, der brasilianisches von europäischem Portugiesisch unterscheidet. Jeder Block enthält jeden Untertitel zu denselben Zeiten; nur der erste enthält Synchronisationen. Subtitld ordnet eine Übersetzung ihrem Untertitel nach der Startzeit zu, oder dem, mit dem sie sich am meisten überlappt, sodass Blöcke anderer Werkzeuge nicht übereinstimmen müssen.

Ein Projekt öffnen

Große Projekte öffnen sich sofort: Subtitld liest zuerst, was der Editor braucht, und den Rest, während Sie arbeiten.

Einträge werden in die eigenen Ordner von Subtitld entpackt, nie neben das Projekt: das Dokument, die Gesichter und die Synchronisationen in einen Cache-Ordner, benannt nach dem MD5 des Projektpfads. Was während der Arbeit hinzukommt, fließt in Blöcken von 1 MiB in eine temporäre Datei, die nach Abschluss an ihren Platz umbenannt wird, sodass ein Absturz mittendrin nichts halb Geschriebenes hinterlässt. Öffnet sich dasselbe Projekt erneut, wird eine bereits vorhandene Datei nur wiederverwendet, wenn sie genau die Größe des Eintrags hat; sonst wird sie erneut entpackt.

Das Video wird in dieser Reihenfolge gesucht:

1. ein Video im Paket, in assets/video/;
2. der Pfad in <source path>, wenn er noch existiert;
3. eine Datei mit dem Namen aus <source basename>, im Ordner des Projekts;
4. sonst fragt Subtitld danach.

Eine Datei, die kein ZIP ist, abgeschnitten ist oder eine CRC-Prüfung nicht besteht, öffnet nichts: Subtitld meldet das und entfernt sie aus der Liste der zuletzt geöffneten. Frühere Projekte öffnen sich ebenfalls: eines ohne Manifest oder mit seinem USF unter einem anderen Namen im Stammverzeichnis des ZIP.

Ein Projekt speichern

Speichern gefährdet nie das Projekt, das Sie haben.

1. Ein Schnappschuss. Das Projekt wird so kopiert, wie es beim Speichern ist, damit Sie weiterarbeiten können, während es geschrieben wird. Speichern, automatisches Speichern und Backups wechseln sich ab: Es schreibt immer nur eines.
2. Eine neue Datei. Das Paket wird als <project>.usfx.tmp neben das Projekt geschrieben.
3. Nichts fehlt. Eine Synchronisation, deren Ton noch nicht im Cache ist, weil er noch hereinkommt oder gelöscht wurde, wird aus der Datei kopiert, die gleich ersetzt wird. Ein ohne Video gespeichertes Projekt behält das Bild, das es hatte.
4. Geprüft. Die neue Datei wird erneut geöffnet und die CRC-32 jedes Eintrags überprüft.
5. Ausgetauscht. Erst dann ersetzt sie das Projekt, mit einer einzigen Umbenennung (os.replace): Unter dem Namen des Projekts liegt nie ein halbes Projekt.

Schlägt ein Schritt fehl, wird die temporäre Datei gelöscht, das Projekt auf der Festplatte ist das, das Sie hatten, und Ihre Änderungen sind in Subtitld noch offen. Solange die Synchronisationen eines Projekts noch hereinkommen, wartet Speichern auf sie.

Was hineinkommt

Globale Einstellungen, dann USFX, legt fest, was ein Projekt sonst noch mitführt, für jedes Projekt, das Sie speichern:

• SprecherporträtsDie Gesichter der Sprecher. An.
• Wellenform-Cache der ZeitleisteDie Wellenform, damit sich ein Projekt auf einem anderen Computer öffnet, ohne sie neu zu berechnen. Aus.
• Originale AudiospurDer Ton des Videos, als FLAC. Aus.
• Bearbeitetes Audio (Stimmen + Hintergrund)Der Ton, getrennt in Stimmen und den Rest, als FLAC, damit die Trennung nicht erneut laufen muss. Aus.
• Originale VideodateiDas Video selbst: eine Datei mit allem, so groß wie das Video und mehr. Aus.

Jedes kommt hinein, wenn Subtitld etwas hineinzulegen hat: der getrennte Ton etwa erst, wenn die Trennung gelaufen ist. Die Untertitel, Übersetzungen, Sprecher, Stimmen und jede Synchronisation sind immer darin. Deflate spart etwa ein Sechstel am WAV einer Synchronisation; ein Video und FLAC schrumpfen kaum.

Automatisches Speichern und Backups

• Projektdatei automatisch speichernSchreibt Ihre .usfx selbst, wie Speichern, auf dieselbe sichere Weise. Für ein als USFX gespeichertes Projekt.
• Automatische BackupsEine vollständige .usfx im Backup-Ordner von Subtitld, getrennt von Ihrer eigenen Datei, benannt <project>_<YYYYMMDDHHMMSS>.usfx, wenn es Änderungen zu bewahren gibt. Jenseits von Höchstens behalten, 20, sofern Sie nichts anderes wählen, werden die ältesten gelöscht.

In Dateimanagern

Die Miniaturansicht ist eine Karte im Stil von Subtitld: das Bild des Videos, bei dem das Projekt verlassen wurde, der Untertitel darauf, und darunter die zwölf Sekunden der Zeitleiste um den Abspielkopf, die Wellenform und die Untertitel in den Farben ihrer Sprecher. 4:3 bei 512 × 384, damit sie die quadratische Zelle eines Dateimanagers besser füllt als ein breites Bild. Ohne Video steht das Zeichen von Subtitld für das Bild.

Per Doppelklick öffnet sich ein Projekt auf allen vier in Subtitld. Beide Thumbnailer lesen nur thumbnail.png, lehnen eines über 8 MiB ab und nehmen nichts, was nicht mit der Signatur von PNG beginnt, 89 50 4E 47 0D 0A 1A 0A. Der für Windows nimmt es nur unkomprimiert, so wie Subtitld es schreibt. Der für Linux kommt allein mit der Standardbibliothek von Python aus, da Dateimanager Thumbnailer abgeschottet und viele gleichzeitig ausführen.

Eine .usfx selbst lesen

Nichts in einem Projekt gehört Subtitld allein. Um hineinzuschauen:

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

Um seine Untertitel in jeder Sprache zu lesen, mit der Standardbibliothek von 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))

Bei einem Projekt von jemand anderem parsen Sie mit defusedxml statt xml.etree, wie bei jedem XML, das Sie nicht selbst geschrieben haben.

Eine erstellen

Das kleinste Projekt, das Subtitld öffnet, ist ein ZIP mit einer subtitles.usf. Ohne Manifest fragt Subtitld nach dem Video. Um eines zu erstellen, das auch Dateimanager kennen, folgen Sie dem, was Subtitld schreibt:

• zuerst subtitles.usf, dann manifest.xml;
• jeder Eintrag mit Deflate komprimiert, außer thumbnail.png, unkomprimiert gespeichert;
• Synchronisationen unter assets/dubs/, im Dokument über ihren Pfad im Paket benannt;
• überall UTF-8.

Im Vergleich

USFX ist so aufgebaut wie die Dokumentpakete von Office-Suiten und E-Books: ein ZIP, ein Hauptdokument in XML, ein Inventar, die Medien daneben.

Das Hauptdokument ist ein eigenständiges offenes Format: Nehmen Sie die subtitles.usf aus einer .usfx heraus, und sie ist eine USF-Datei, ein Format mit öffentlicher Spezifikation seit 2002.

Wissenswertes