Projekt Subtitld

Budowa pliku

Plik .usfx to ZIP. Otworzy go każdy program do archiwów, po zmianie nazwy na .zip, jeśli program się upiera.

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 mówi, co się dzieje; zasoby są tym, co odtwarza. Dubbing w subtitles.usf wskazuje swój klip ścieżką w pakiecie, assets/dubs/77a03e27.wav, więc pakiet można przenieść do innego folderu, na inny dysk czy komputer, a nadal będzie kompletny.

Składniki

Nazwy w assets/ składają się z liter, cyfr, -, _ i .; wszystko inne staje się _, więc Tears of Steel.mkv zostaje zapisany jako Tears_of_Steel.mkv. Litery spoza ASCII są zachowywane, a nazwa zapisana w UTF-8 i tak oznaczona (bit 11 nagłówka ZIP), jak wymaga APPNOTE.

Pierwsze bajty

Każdy projekt zaczyna się tak samo: lokalny nagłówek pliku ZIP, a potem nazwa pierwszego składnika.

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

Nazwa nigdy nie jest kompresowana, nawet gdy składnik jest. Dzięki temu działa jak sygnatura: ZIP, którego nazwa na bajcie 30 to subtitles.usf, jest projektem Subtitld. Tracker w Haiku odróżnia projekty od innych archiwów dokładnie tą regułą, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), umieszczoną wyżej niż zwykła reguła ZIP. ODF i EPUB robią to samo z pierwszym składnikiem o nazwie mimetype.

Wideo może być większe niż pierwotny limit ZIP wynoszący 4 GiB. Od 2 GiB Subtitld zapisuje pola dodatkowe i rekordy końcowe Zip64 (APPNOTE, sekcja 4.5), tak jak powyżej 65 535 składników; Subtitld, jego moduł miniatur dla Windows i każdy współczesny unzip je odczytują.

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 to application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg oraz application/octet-stream dla przebiegu fali i wszystkiego innego.

Dokument

subtitles.usf to plik Universal Subtitle Format, w UTF-8, taki, jaki Subtitld zapisuje samodzielnie, z tym, czego potrzebuje projekt, dodanym w stylu samego USF: elementy i atrybuty tam, gdzie USF ich nie ma. Czytnik USF, który pomija to, czego nie zna, odczyta napisy.

<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 dodaje do USF

W zwykłym .usf zdjęcia mówców i dźwięk dubbingów mogą podróżować wewnątrz XML, jako base64 w <avatar> i <data>. .usfx nigdy tego nie robi: są osobnymi składnikami, o ćwierć mniejszymi niż w base64, i odczytywanymi bez parsowania XML.

Czas

start i stop napisu to czasy USF, zaokrąglone do najbliższej milisekundy. Czasy dubbingu to zwykłe sekundy zapisane w całości, 18.01579117916244: najkrótsza liczba dziesiętna, która odczytuje się z powrotem jako ta sama liczba 64-bitowa, więc klip umieszczony przeciąganiem wraca dokładnie tam, gdzie był.

Starsze wersje Subtitld zapisywały czasy o milisekundę za wcześnie, a start w zerze jako 23:59:59.999. Subtitld odczytuje tę wartość jako zero, a milisekundę zostawia, jak jest.

Ujęcia i podklipy

Napis może mieć kilka ujęć. Pierwszy <dubbing> to ten, który gra; pozostałe są alternatywami, cichymi, dopóki któregoś nie wybierzesz, a wtedy przechodzi na początek.

Ujęcie podzielone lub rozciągnięte przechowuje listę elementów <subclip>, ułożonych jak klipy w edytorze audio:

Podklip gra od start ujęcia plus jego offset, przez end minus start sekund. Przerwy to cisza; nakładające się części są miksowane. Źródła nigdy się nie zmieniają, więc każdy podział i rozciągnięcie można cofnąć, a rozciągnięcie zawsze powstaje na nowo z raw_path, nigdy z rozciągnięcia rozciągnięcia.

Tłumaczenia

Każdy język ma własny blok <subtitles>, oznaczony kodem ISO 639-2 i, w elemencie, nazwą języka, która odróżnia portugalski brazylijski od europejskiego. Każdy blok zawiera każdy napis w tych samych czasach; tylko pierwszy zawiera dubbingi. Subtitld dopasowuje tłumaczenie do napisu po czasie początku albo do tego, z którym najbardziej się nakłada, więc bloki zapisane przez inne narzędzia nie muszą się idealnie pokrywać.

Otwieranie projektu

Duże projekty otwierają się od razu: Subtitld najpierw czyta to, czego potrzebuje edytor, a resztę w trakcie pracy.

Składniki są rozpakowywane do własnych folderów Subtitld, nigdy obok projektu: dokument, twarze i dubbingi do folderu pamięci podręcznej nazwanego skrótem MD5 ścieżki projektu. To, co dociera w trakcie pracy, spływa w porcjach po 1 MiB do pliku tymczasowego, który po ukończeniu zostaje przemianowany na właściwe miejsce, więc awaria w połowie nie zostawia niczego zapisanego do połowy. Przy następnym otwarciu tego samego projektu plik, który już istnieje, jest używany ponownie tylko wtedy, gdy ma dokładnie rozmiar składnika; w przeciwnym razie zostaje rozpakowany na nowo.

Wideo jest szukane w tej kolejności:

1. wideo w pakiecie, w assets/video/;
2. ścieżka z <source path>, jeśli nadal istnieje;
3. plik o nazwie z <source basename>, w folderze projektu;
4. w przeciwnym razie Subtitld o nie prosi.

Plik, który nie jest ZIP-em, jest ucięty lub nie przechodzi kontroli CRC, niczego nie otwiera: Subtitld to zgłasza i usuwa go z listy ostatnich. Wcześniejsze projekty też się otwierają: bez manifestu albo z USF pod inną nazwą w katalogu głównym ZIP.

Zapisywanie projektu

Zapisz nigdy nie naraża projektu, który masz.

1. Migawka. Projekt jest kopiowany w stanie z chwili zapisu, więc możesz dalej edytować, gdy jest zapisywany. Zapisy, autozapisy i kopie zapasowe czekają na swoją kolej: naraz pisze tylko jeden.
2. Nowy plik. Pakiet jest zapisywany do <project>.usfx.tmp obok projektu.
3. Niczego nie brakuje. Dubbing, którego dźwięku nie ma jeszcze w pamięci podręcznej, bo wciąż spływa lub został usunięty, jest kopiowany z pliku, który ma zostać zastąpiony. Projekt zapisany bez wideo zachowuje obraz, który miał.
4. Sprawdzony. Nowy plik jest ponownie otwierany, a CRC-32 każdego składnika weryfikowane.
5. Podmieniony. Dopiero wtedy zastępuje projekt, jedną zmianą nazwy (os.replace): pod nazwą projektu nigdy nie leży pół projektu.

Jeśli któryś krok się nie powiedzie, plik tymczasowy zostaje usunięty, projekt na dysku jest tym, który miałeś, a twoje zmiany są nadal otwarte w Subtitld. Dopóki dubbingi projektu wciąż spływają, Zapisz na nie czeka.

Co trafia do środka

Ustawienia globalne, a potem USFX, decydują, co jeszcze zawiera projekt, dla każdego projektu, który zapisujesz:

• Zdjęcia mówcówTwarze mówców. Włączone.
• Pamięć podręczna przebiegu faliPrzebieg fali, aby projekt otwierał się na innym komputerze bez ponownego obliczania. Wyłączone.
• Oryginalna ścieżka dźwiękowaDźwięk wideo, jako FLAC. Wyłączone.
• Przetworzone audio (wokal + tło)Dźwięk rozdzielony na głosy i resztę, jako FLAC, aby nie trzeba było ponownie uruchamiać separacji. Wyłączone.
• Oryginalny plik wideoSamo wideo: jeden plik ze wszystkim, tak duży jak wideo i więcej. Wyłączone.

Każdy trafia do środka, gdy Subtitld ma co włożyć: rozdzielony dźwięk na przykład dopiero po przeprowadzeniu separacji. Napisy, tłumaczenia, mówcy, głosy i każdy dubbing są w środku zawsze. Deflate zmniejsza WAV dubbingu o mniej więcej jedną szóstą; wideo i FLAC prawie się nie kurczą.

Autozapis i kopie zapasowe

• Automatycznie zapisuj plik projektuZapisuje sam twój .usfx, jak Zapisz, w ten sam bezpieczny sposób. Dla projektu zapisanego jako USFX.
• Automatyczne kopie zapasowePełny .usfx w folderze kopii zapasowych Subtitld, z dala od twojego pliku, o nazwie <project>_<YYYYMMDDHHMMSS>.usfx, gdy są zmiany do zachowania. Powyżej Zachowuj najwyżej, domyślnie 20, najstarsze są usuwane.

W menedżerach plików

Miniatura to karta w stylu Subtitld: klatka wideo, na której pozostawiono projekt, napis na niej, a pod nią dwanaście sekund osi czasu wokół głowicy odtwarzania, przebieg fali i napisy w kolorach mówców. 4:3 w rozmiarze 512 × 384, więc lepiej wypełnia kwadratowe pole menedżera plików niż szeroka klatka. Bez wideo zamiast klatki pojawia się znak Subtitld.

Po dwukrotnym kliknięciu projekt otwiera się w Subtitld we wszystkich czterech. Oba generatory miniatur czytają tylko thumbnail.png, odrzucają większy niż 8 MiB i nie przyjmują niczego, co nie zaczyna się od sygnatury PNG, 89 50 4E 47 0D 0A 1A 0A. Windowsowy przyjmuje go tylko bez kompresji, tak jak zapisuje go Subtitld. Linuksowy korzysta wyłącznie ze standardowej biblioteki Pythona, bo menedżery plików uruchamiają generatory miniatur w piaskownicy i po wiele naraz.

Samodzielne czytanie .usfx

Nic w projekcie nie należy wyłącznie do Subtitld. Aby zajrzeć do środka:

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

Aby odczytać jego napisy, w każdym języku, standardową biblioteką Pythona:

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

Projekt od kogoś innego parsuj za pomocą defusedxml zamiast xml.etree, jak każdy XML, którego nie napisałeś sam.

Tworzenie własnego

Najmniejszy projekt, jaki otworzy Subtitld, to ZIP zawierający subtitles.usf. Bez manifestu Subtitld poprosi o wideo. Aby zrobić taki, który rozpoznają też menedżery plików, postępuj tak jak Subtitld:

• najpierw subtitles.usf, potem manifest.xml;
• każdy składnik skompresowany metodą Deflate, z wyjątkiem thumbnail.png, przechowywanego bez kompresji;
• dubbingi w assets/dubs/, wskazywane w dokumencie ścieżką w pakiecie;
• wszędzie UTF-8.

Porównanie

USFX jest zbudowany tak jak pakiety dokumentów pakietów biurowych i e-booków: ZIP, główny dokument w XML, spis zawartości, media obok.

Główny dokument jest samodzielnym otwartym formatem: wyjmij subtitles.usf z .usfx, a otrzymasz plik USF, format z publiczną specyfikacją od 2002 roku.

Ciekawostki