Subtitld-project

Opbouw van een bestand

Een .usfx is een ZIP. Elk archiefprogramma opent hem, hernoemd naar .zip als het programma daarop staat.

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

Het document zegt wat er gebeurt; de assets zijn wat het afspeelt. Een nasynchronisatie in subtitles.usf noemt haar clip bij haar pad in het pakket, assets/dubs/77a03e27.wav, zodat het pakket naar een andere map, schijf of computer kan en toch compleet blijft.

De onderdelen

Namen in assets/ bestaan uit letters, cijfers, -, _ en .; al het andere wordt _, dus Tears of Steel.mkv wordt opgeslagen als Tears_of_Steel.mkv. Letters buiten ASCII blijven behouden, de naam geschreven in UTF-8 en als zodanig gemarkeerd (bit 11 van de ZIP-kop), zoals APPNOTE vraagt.

De eerste bytes

Elk project begint op dezelfde manier: een lokale ZIP-bestandskop, dan de naam van het eerste onderdeel.

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

De naam wordt nooit gecomprimeerd, ook niet als het onderdeel dat wel is. Dat maakt hem tot een handtekening: een ZIP met subtitles.usf als naam op byte 30 is een Subtitld-project. Tracker van Haiku onderscheidt projecten van andere archieven met precies die regel, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), hoger gerangschikt dan de gewone ZIP-regel. ODF en EPUB doen hetzelfde met een eerste onderdeel genaamd mimetype.

Een video kan groter zijn dan de oorspronkelijke ZIP-limiet van 4 GiB. Vanaf 2 GiB schrijft Subtitld de extra velden en eindrecords van Zip64 (APPNOTE sectie 4.5), net als boven 65.535 onderdelen; Subtitld, zijn Windows-thumbnailhandler en elke actuele unzip lezen ze.

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

De types zijn application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg, en application/octet-stream voor de golfvorm en al het andere.

Het document

subtitles.usf is een Universal Subtitle Format-bestand, UTF-8, zoals Subtitld het op zichzelf schrijft, met wat een project nodig heeft toegevoegd in de eigen stijl van USF: elementen en attributen waar USF er geen heeft. Een USF-lezer die overslaat wat hij niet kent, leest de ondertitels.

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

Wat Subtitld aan USF toevoegt

In een gewone .usf kunnen afbeeldingen van sprekers en het geluid van nasynchronisaties in de XML meereizen, als base64 in <avatar> en <data>. Een .usfx doet dat nooit: het zijn eigen onderdelen, een kwart kleiner dan in base64, en gelezen zonder de XML te parsen.

Tijden

De start en stop van een ondertitel zijn USF-tijden, afgerond op de dichtstbijzijnde milliseconde. De tijden van een nasynchronisatie zijn gewone seconden, voluit geschreven, 18.01579117916244: het kortste decimale getal dat terug wordt gelezen als hetzelfde 64-bits getal, zodat een clip die met slepen is geplaatst precies terugkomt waar hij was.

Oudere versies van Subtitld schreven tijden een milliseconde te vroeg, en een start op nul als 23:59:59.999. Subtitld leest die waarde als nul, en laat de milliseconde zoals ze is.

Takes en subclips

Een ondertitel kan meerdere takes hebben. De eerste <dubbing> is degene die speelt; de andere zijn alternatieven, stil tot je er een kiest, die dan naar voren schuift.

Een take die gesplitst of uitgerekt is, houdt een lijst <subclip>s bij, geplaatst zoals clips in een audio-editor:

Een subclip speelt vanaf de start van de take plus zijn offset, gedurende end min start seconden. Gaten zijn stilte; overlappingen worden gemengd. De bronnen worden nooit veranderd, dus elke splitsing en uitrekking kan ongedaan worden gemaakt, en een uitrekking wordt altijd opnieuw gemaakt vanuit raw_path, nooit uit een uitrekking van een uitrekking.

Vertalingen

Elke taal heeft een eigen <subtitles>-blok, met haar ISO 639-2-code en, in het element, de naam van de taal, die Braziliaans Portugees van dat van Portugal onderscheidt. Elk blok bevat elke ondertitel op dezelfde tijden; alleen het eerste bevat nasynchronisaties. Subtitld koppelt een vertaling aan haar ondertitel op begintijd, of aan degene waarmee ze het meest overlapt, zodat blokken van andere programma's niet precies hoeven te kloppen.

Een project openen

Grote projecten gaan meteen open: Subtitld leest eerst wat de editor nodig heeft, en de rest terwijl je werkt.

Onderdelen worden uitgepakt in de eigen mappen van Subtitld, nooit naast het project: het document, de gezichten en de nasynchronisaties in een cachemap genoemd naar de MD5 van het pad van het project. Wat binnenkomt terwijl je werkt, stroomt in blokken van 1 MiB naar een tijdelijk bestand, dat na voltooiing op zijn plaats wordt hernoemd, zodat een crash halverwege niets half geschreven achterlaat. De volgende keer dat hetzelfde project opengaat, wordt een bestand dat er al staat alleen hergebruikt als het precies zo groot is als het onderdeel; anders wordt het opnieuw uitgepakt.

De video wordt in deze volgorde gezocht:

1. een video in het pakket, in assets/video/;
2. het pad in <source path>, als het er nog is;
3. een bestand met de naam uit <source basename>, in de map van het project;
4. anders vraagt Subtitld erom.

Een bestand dat geen ZIP is, afgebroken is of een CRC-controle niet doorstaat, opent niets: Subtitld meldt het en haalt het van de lijst met recente bestanden. Oudere projecten gaan ook open: een zonder manifest, of met de USF onder een andere naam in de hoofdmap van de ZIP.

Een project opslaan

Opslaan brengt het project dat je hebt nooit in gevaar.

1. Een momentopname. Het project wordt gekopieerd zoals het is wanneer je opslaat, zodat je kunt blijven bewerken terwijl het wordt geschreven. Opslaan, automatisch opslaan en back-ups wachten op hun beurt: er schrijft er één tegelijk.
2. Een nieuw bestand. Het pakket wordt geschreven naar <project>.usfx.tmp naast het project.
3. Niets ontbreekt. Een nasynchronisatie waarvan het geluid nog niet in de cache staat, nog binnenstromend of gewist, wordt gekopieerd uit het bestand dat op het punt staat vervangen te worden. Een project dat zonder video wordt opgeslagen, houdt de afbeelding die het had.
4. Gecontroleerd. Het nieuwe bestand wordt opnieuw geopend en de CRC-32 van elk onderdeel geverifieerd.
5. Verwisseld. Pas dan vervangt het het project, in één hernoeming (os.replace): de naam van het project bevat nooit een half project.

Als een stap mislukt, wordt het tijdelijke bestand verwijderd, is het project op schijf het project dat je had, en staan je wijzigingen nog open in Subtitld. Zolang de nasynchronisaties van een project nog binnenstromen, wacht Opslaan erop.

Wat erin gaat

Algemene instellingen, dan USFX, bepaalt wat een project verder meeneemt, voor elk project dat je opslaat:

• Portretafbeeldingen van sprekersDe gezichten van de sprekers. Aan.
• Golfvormcache van de tijdlijnDe golfvorm, zodat een project op een andere computer opengaat zonder hem opnieuw te berekenen. Uit.
• Oorspronkelijk audiospoorHet geluid van de video, als FLAC. Uit.
• Bewerkte audio (stem + achtergrond)Het geluid gescheiden in stemmen en de rest, als FLAC, zodat de scheiding niet opnieuw hoeft. Uit.
• Oorspronkelijk videobestandDe video zelf: één bestand met alles, zo groot als de video en meer. Uit.

Elk gaat erin als Subtitld er een heeft om erin te stoppen: het gescheiden geluid bijvoorbeeld pas nadat de scheiding heeft gedraaid. De ondertitels, vertalingen, sprekers, stemmen en elke nasynchronisatie zitten er altijd in. Deflate haalt ongeveer een zesde van de WAV van een nasynchronisatie af; een video en FLAC krimpen nauwelijks.

Automatisch opslaan en back-ups

• Het projectbestand automatisch opslaanSchrijft je .usfx zelf, zoals Opslaan doet, op dezelfde veilige manier. Voor een project dat als USFX is opgeslagen.
• Automatische back-upsEen volledige .usfx in de back-upmap van Subtitld, los van je eigen bestand, genaamd <project>_<YYYYMMDDHHMMSS>.usfx, als er wijzigingen te bewaren zijn. Boven Maximaal bewaren, 20 tenzij je anders kiest, worden de oudste verwijderd.

In bestandsbeheerders

De miniatuur is een kaart in de stijl van Subtitld: het beeld van de video waar het project was gebleven, de ondertitel erop, en eronder de twaalf seconden tijdlijn rond de afspeelkop, de golfvorm en de ondertitels in de kleuren van hun sprekers. 4:3 op 512 × 384, zodat hij het vierkante vak van een bestandsbeheerder beter vult dan een breed beeld. Zonder video staat het logo van Subtitld in plaats van het beeld.

Dubbelgeklikt opent een project op alle vier in Subtitld. Beide thumbnailers lezen alleen thumbnail.png, weigeren er een boven 8 MiB, en nemen niets aan dat niet begint met de handtekening van PNG, 89 50 4E 47 0D 0A 1A 0A. Die van Windows neemt hem alleen opgeslagen aan, zoals Subtitld hem schrijft. Die van Linux gebruikt alleen de standaardbibliotheek van Python, omdat bestandsbeheerders thumbnailers in een sandbox en met vele tegelijk draaien.

Zelf een .usfx lezen

Niets in een project is alleen van Subtitld. Om erin te kijken:

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

Om de ondertitels te lezen, in elke taal, met de standaardbibliotheek van 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 null:
        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))

Parse een project van iemand anders met defusedxml in plaats van xml.etree, zoals bij elke XML die je niet zelf schreef.

Er zelf een maken

Het kleinste project dat Subtitld opent, is een ZIP met een subtitles.usf. Zonder manifest vraagt Subtitld om de video. Om er een te maken die ook bestandsbeheerders herkennen, volg je wat Subtitld schrijft:

• subtitles.usf eerst, dan manifest.xml;
• elk onderdeel gecomprimeerd met Deflate, behalve thumbnail.png, opgeslagen;
• nasynchronisaties onder assets/dubs/, in het document genoemd bij hun pad in het pakket;
• overal UTF-8.

Hoe het zich verhoudt

USFX is opgebouwd zoals de documentpakketten van kantoorsuites en e-books: een ZIP, een hoofddocument in XML, een inventaris, de media ernaast.

Het hoofddocument is op zichzelf een open formaat: haal de subtitles.usf uit een .usfx en het is een USF-bestand, een formaat met een openbare specificatie sinds 2002.

Wetenswaardigheden