Projekt Subtitldu

Stavba souboru

Soubor .usfx je ZIP. Otevře ho jakýkoli archivační nástroj, případně po přejmenování na .zip, pokud na tom nástroj trvá.

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

Dokument říká, co se děje; přílohy jsou to, co přehrává. Dabing v subtitles.usf odkazuje na svůj klip cestou v balíčku, assets/dubs/77a03e27.wav, takže balíček lze přesunout do jiné složky, na jiný disk nebo jiný počítač a zůstane celý.

Položky

Názvy v assets/ se skládají z písmen, číslic, -, _ a .; cokoli jiného se změní na _, takže Tears of Steel.mkv se uloží jako Tears_of_Steel.mkv. Písmena mimo ASCII zůstávají, název se zapíše v UTF-8 a takto označí (bit 11 hlavičky ZIP), jak žádá APPNOTE.

První bajty

Každý projekt začíná stejně: místní hlavičkou souboru ZIP a pak názvem své první položky.

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

Název se nikdy nekomprimuje, ani když položka ano. Díky tomu je signaturou: ZIP, jehož název na bajtu 30 je subtitles.usf, je projekt Subtitldu. Tracker v Haiku rozlišuje projekty od jiných archivů právě tímto pravidlem, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), s vyšší prioritou než pravidlo pro obyčejný ZIP. ODF a EPUB dělají totéž s první položkou jménem mimetype.

Video může být větší než původní limit ZIP, 4 GiB. Od 2 GiB zapisuje Subtitld doplňková pole a koncové záznamy Zip64 (APPNOTE, oddíl 4.5), stejně jako nad 65 535 položek; Subtitld, jeho obslužná rutina náhledů pro Windows i každý současný unzip je přečtou.

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>

Typy jsou application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg a application/octet-stream pro zvukovou křivku a vše ostatní.

Dokument

subtitles.usf je soubor ve formátu Universal Subtitle Format, v UTF-8, tak jak ho Subtitld zapisuje i samostatně, doplněný o to, co projekt potřebuje, ve stylu USF: prvky a atributy tam, kde USF žádné nemá. Čtečka USF, která přeskakuje, co nezná, jeho titulky přečte.

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

Co Subtitld přidává k USF

V obyčejném .usf mohou obrázky mluvčích a zvuk dabingů cestovat uvnitř XML, jako base64 v <avatar> a <data>. Soubor .usfx to nikdy nedělá: jsou to samostatné položky, o čtvrtinu menší než v base64, a čtou se bez parsování XML.

Časy

start a stop titulku jsou časy USF, zaokrouhlené na nejbližší milisekundu. Časy dabingu jsou prosté sekundy vypsané celé, 18.01579117916244: nejkratší desetinné číslo, které se přečte zpět jako stejné 64bitové číslo, takže klip umístěný přetažením se vrátí přesně tam, kde byl.

Starší verze Subtitldu zapisovaly časy o milisekundu dříve, a začátek v nule jako 23:59:59.999. Subtitld tuto hodnotu čte jako nulu a milisekundu nechává, jak je.

Záběry a dílčí klipy

Titulek může mít několik záběrů. První <dubbing> je ten, který hraje; ostatní jsou alternativy, tiché, dokud jednu nevyberete, a ta se pak přesune dopředu.

Rozdělený nebo natažený záběr si drží seznam prvků <subclip>, umístěných jako klipy ve zvukovém editoru:

Dílčí klip hraje od start záběru plus jeho offset, po dobu end minus start sekund. Mezery jsou ticho; překryvy se smíchají. Zdroje se nikdy nemění, takže každé rozdělení i natažení lze vrátit zpět, a natažení se vždy znovu vytváří z raw_path, nikdy z natažení natažení.

Překlady

Každý jazyk má vlastní blok <subtitles>, označený kódem ISO 639-2 a v prvku názvem jazyka, který odliší brazilskou portugalštinu od portugalské. Každý blok obsahuje všechny titulky ve stejných časech; dabingy obsahuje jen první. Subtitld přiřadí překlad k titulku podle času začátku, nebo k tomu, se kterým se nejvíce překrývá, takže bloky zapsané jinými nástroji nemusí lícovat.

Otevření projektu

Velké projekty se otevřou hned: Subtitld nejdřív přečte, co potřebuje editor, a zbytek, zatímco pracujete.

Položky se rozbalují do vlastních složek Subtitldu, nikdy vedle projektu: dokument, tváře a dabingy do složky mezipaměti pojmenované podle MD5 cesty k projektu. Co přichází během práce, se zapisuje po blocích 1 MiB do dočasného souboru, který se po dokončení přejmenuje na své místo, takže pád uprostřed nezanechá nic napůl zapsaného. Když se stejný projekt otevře příště, soubor, který už existuje, se použije znovu jen tehdy, má-li přesně velikost položky; jinak se rozbalí znovu.

Video se hledá v tomto pořadí:

1. video uvnitř balíčku, v assets/video/;
2. cesta v <source path>, pokud tam stále je;
3. soubor pojmenovaný jako v <source basename>, ve složce projektu;
4. jinak se na něj Subtitld zeptá.

Soubor, který není ZIP, je zkrácený nebo neprojde kontrolou CRC, neotevře nic: Subtitld to oznámí a odebere ho ze seznamu nedávných. Otevřou se i starší projekty: projekt bez manifestu, nebo s USF pod jiným názvem v kořeni ZIP.

Uložení projektu

Uložit nikdy neohrozí projekt, který máte.

1. Snímek. Projekt se zkopíruje tak, jak je v okamžiku uložení, takže můžete upravovat dál, zatímco se zapisuje. Uložení, automatická uložení a zálohy se střídají: zapisuje vždy jen jedno.
2. Nový soubor. Balíček se zapíše do <project>.usfx.tmp vedle projektu.
3. Nic nechybí. Dabing, jehož zvuk ještě není v mezipaměti, protože stále přichází nebo byl vymazán, se zkopíruje ze souboru, který bude nahrazen. Projekt uložený bez videa si ponechá obrázek, který měl.
4. Zkontrolováno. Nový soubor se znovu otevře a ověří se CRC-32 každé položky.
5. Vyměněno. Teprve pak nahradí projekt, jediným přejmenováním (os.replace): pod názvem projektu nikdy neleží půl projektu.

Pokud některý krok selže, dočasný soubor se smaže, projekt na disku je ten, který jste měli, a vaše úpravy jsou v Subtitldu stále otevřené. Dokud dabingy projektu ještě přicházejí, Uložit na ně počká.

Co je uvnitř

Globální nastavení, pak USFX, určuje, co dalšího si projekt nese, pro každý projekt, který uložíte:

• Portréty mluvčíchTváře mluvčích. Zapnuto.
• Cache zvukové křivky časové osyZvuková křivka, aby se projekt otevřel na jiném počítači bez nového výpočtu. Vypnuto.
• Původní zvuková stopaZvuk videa, jako FLAC. Vypnuto.
• Zpracovaný zvuk (hlas + pozadí)Zvuk rozdělený na hlasy a zbytek, jako FLAC, aby se oddělení nemuselo spouštět znovu. Vypnuto.
• Původní soubor videaSamotné video: jeden soubor se vším, velký jako video a ještě víc. Vypnuto.

Každá položka se přidá, když ji Subtitld má: oddělený zvuk například až poté, co oddělení proběhlo. Titulky, překlady, mluvčí, hlasy a každý dabing jsou uvnitř vždy. Deflate ubere z WAV dabingu zhruba šestinu; video a FLAC se téměř nezmenší.

Automatické ukládání a zálohy

• Automaticky ukládat soubor projektuZapisuje přímo váš .usfx, stejně jako Uložit, stejně bezpečně. Pro projekt uložený jako USFX.
• Automatické zálohyÚplný .usfx ve složce záloh Subtitldu, odděleně od vašeho souboru, pojmenovaný <project>_<YYYYMMDDHHMMSS>.usfx, když jsou změny k uchování. Nad hodnotu Uchovat nejvýše, 20, pokud nezvolíte jinak, se nejstarší mažou.

Ve správcích souborů

Náhled je karta ve vzhledu Subtitldu: snímek videa, kde byl projekt opuštěn, titulek na něm a pod ním dvanáct sekund časové osy kolem přehrávací hlavy, zvuková křivka a titulky v barvách svých mluvčích. Poměr 4:3 při 512 × 384, aby lépe vyplnil čtvercovou buňku správce souborů než široký snímek. Bez videa zastoupí snímek značka Subtitldu.

Dvojklikem se projekt na všech čtyřech otevře v Subtitldu. Oba generátory náhledů čtou jen thumbnail.png, odmítnou obrázek nad 8 MiB a nepřijmou nic, co nezačíná signaturou PNG, 89 50 4E 47 0D 0A 1A 0A. Ten pro Windows ho přijme jen bez komprese, tak jak ho Subtitld zapisuje. Ten pro Linux používá pouze standardní knihovnu Pythonu, protože správci souborů spouštějí generátory náhledů v izolaci a mnoho najednou.

Čtení .usfx vlastními silami

Nic v projektu nepatří jen Subtitldu. Chcete-li se podívat dovnitř:

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

Chcete-li přečíst jeho titulky ve všech jazycích, se standardní knihovnou Pythonu:

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

U projektu od někoho jiného parsujte pomocí defusedxml místo xml.etree, jako u každého XML, které jste nenapsali sami.

Vytvoření projektu

Nejmenší projekt, který Subtitld otevře, je ZIP obsahující subtitles.usf. Bez manifestu se Subtitld zeptá na video. Chcete-li vytvořit projekt, který poznají i správci souborů, řiďte se tím, co zapisuje Subtitld:

• nejprve subtitles.usf, pak manifest.xml;
• každá položka komprimovaná metodou Deflate, kromě thumbnail.png, uloženého bez komprese;
• dabingy v assets/dubs/, v dokumentu uvedené cestou v balíčku;
• všude UTF-8.

Srovnání

USFX je postaven jako balíčky dokumentů kancelářských balíků a e-knih: ZIP, hlavní dokument v XML, soupis a média vedle nich.

Hlavní dokument je samostatný otevřený formát: vyjměte subtitles.usf z .usfx a máte soubor USF, formát s veřejnou specifikací od roku 2002.

Zajímavosti