Progetto Subtitld

Anatomia di un file

Un .usfx è uno ZIP. Qualsiasi programma di archiviazione lo apre, rinominato .zip se il programma insiste.

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

Il documento dice che cosa succede; le risorse sono ciò che riproduce. Un doppiaggio in subtitles.usf indica la sua clip con il percorso nel pacchetto, assets/dubs/77a03e27.wav, così il pacchetto può passare in un'altra cartella, su un altro disco o un altro computer e restare integro.

I membri

I nomi in assets/ sono fatti di lettere, cifre, -, _ e .; tutto il resto diventa _, quindi Tears of Steel.mkv viene salvato come Tears_of_Steel.mkv. Le lettere fuori dall'ASCII restano, con il nome scritto in UTF-8 e segnalato come tale (bit 11 dell'intestazione ZIP), come chiede APPNOTE.

I primi byte

Ogni progetto comincia allo stesso modo: un'intestazione di file locale ZIP, poi il nome del primo membro.

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

Il nome non è mai compresso, anche quando il membro lo è. Questo lo rende una firma: uno ZIP il cui nome al byte 30 è subtitles.usf è un progetto Subtitld. Il Tracker di Haiku distingue i progetti dagli altri archivi esattamente con questa regola, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), con priorità sulla regola dello ZIP semplice. ODF ed EPUB fanno lo stesso con un primo membro chiamato mimetype.

Un video può superare il limite originale dello ZIP, 4 GiB. Da 2 GiB in su, Subtitld scrive i campi extra e i record finali di Zip64 (APPNOTE, sezione 4.5), come fa oltre i 65.535 membri; Subtitld, il suo gestore di miniature per Windows e qualsiasi unzip attuale li leggono.

Il manifesto

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

I tipi sono application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg, e application/octet-stream per la forma d'onda e qualsiasi altra cosa.

Il documento

subtitles.usf è un file Universal Subtitle Format, UTF-8, come Subtitld lo scrive da solo, con ciò che serve a un progetto aggiunto nello stile di USF: elementi e attributi dove USF non ne ha. Un lettore USF che salta ciò che non conosce ne legge i sottotitoli.

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

Che cosa aggiunge Subtitld a USF

In un .usf semplice, le immagini dei parlanti e l'audio dei doppiaggi possono viaggiare dentro il XML, in base64 in <avatar> e <data>. Un .usfx non lo fa mai: sono membri a sé, un quarto più piccoli che in base64, e si leggono senza analizzare il XML.

Tempi

start e stop di un sottotitolo sono tempi USF, arrotondati al millisecondo più vicino. I tempi di un doppiaggio sono secondi semplici scritti per intero, 18.01579117916244: il decimale più breve che si rilegge come lo stesso numero a 64 bit, così una clip posizionata trascinandola torna esattamente dov'era.

Le versioni precedenti di Subtitld scrivevano i tempi un millisecondo in anticipo, e un inizio a zero come 23:59:59.999. Subtitld legge quel valore come zero, e lascia il millisecondo com'è.

Riprese e sottoclip

Un sottotitolo può avere più riprese. Il primo <dubbing> è quello che viene riprodotto; gli altri sono alternative, silenziose finché non ne scegli una, che passa allora in testa.

Una ripresa divisa o stirata conserva un elenco di <subclip>, posizionati come clip in un editor audio:

Un sottoclip viene riprodotto dallo start della ripresa più il suo offset, per end meno start secondi. I vuoti sono silenzio; le sovrapposizioni vengono mixate. Le sorgenti non vengono mai modificate, quindi ogni divisione e stiramento si può annullare, e uno stiramento viene sempre rifatto da raw_path, mai dallo stiramento di uno stiramento.

Traduzioni

Ogni lingua ha il suo blocco <subtitles>, indicato dal codice ISO 639-2 e, nell'elemento, dal nome della lingua, che distingue il portoghese del Brasile da quello del Portogallo. Ogni blocco contiene ogni sottotitolo agli stessi tempi; solo il primo contiene i doppiaggi. Subtitld abbina una traduzione al suo sottotitolo per tempo di inizio, o a quello con cui si sovrappone di più, quindi i blocchi scritti da altri strumenti non devono per forza allinearsi.

Aprire un progetto

I progetti grandi si aprono subito: Subtitld legge prima ciò che serve all'editor, e il resto mentre lavori.

I membri vengono estratti nelle cartelle di Subtitld, mai accanto al progetto: il documento, i volti e i doppiaggi in una cartella di cache chiamata come l'MD5 del percorso del progetto. Ciò che arriva mentre lavori viene trasferito a blocchi di 1 MiB in un file temporaneo, rinominato al suo posto quando è completo, così un crash a metà non lascia nulla scritto a metà. La volta successiva che lo stesso progetto si apre, un file già presente viene riusato solo se ha esattamente la dimensione del membro; altrimenti viene estratto di nuovo.

Il video viene cercato in quest'ordine:

1. un video dentro il pacchetto, in assets/video/;
2. il percorso in <source path>, se esiste ancora;
3. un file con il nome indicato in <source basename>, nella cartella del progetto;
4. altrimenti, Subtitld lo chiede.

Un file che non è uno ZIP, è troncato o non supera un controllo CRC non apre nulla: Subtitld lo segnala e lo toglie dall'elenco dei recenti. Si aprono anche i progetti precedenti: uno senza manifesto, o con il suo USF sotto un altro nome alla radice dello ZIP.

Salvare un progetto

Salva non mette mai a rischio il progetto che hai.

1. Un'istantanea. Il progetto viene copiato così com'è al momento del salvataggio, così puoi continuare a modificarlo mentre viene scritto. Salvataggi, salvataggi automatici e backup si danno il turno: ne scrive uno alla volta.
2. Un file nuovo. Il pacchetto viene scritto in <project>.usfx.tmp accanto al progetto.
3. Niente di mancante. Un doppiaggio il cui audio non è ancora nella cache, perché ancora in arrivo o eliminato, viene copiato dal file che sta per essere sostituito. Un progetto salvato senza video mantiene l'immagine che aveva.
4. Verificato. Il nuovo file viene riaperto e il CRC-32 di ogni membro controllato.
5. Scambiato. Solo allora sostituisce il progetto, con un'unica rinomina (os.replace): il nome del progetto non contiene mai mezzo progetto.

Se un passaggio fallisce, il file temporaneo viene eliminato, il progetto su disco è quello che avevi, e le tue modifiche restano aperte in Subtitld. Mentre i doppiaggi di un progetto sono ancora in arrivo, Salva li aspetta.

Che cosa va dentro

Impostazioni globali, poi USFX, sceglie che cos'altro porta un progetto, per ogni progetto che salvi:

• Ritratti dei parlantiI volti dei parlanti. Attivo.
• Cache della forma d'onda della timelineLa forma d'onda, così un progetto si apre su un altro computer senza ricalcolarla. Disattivo.
• Traccia audio originaleL'audio del video, in FLAC. Disattivo.
• Audio elaborato (voci + sfondo)L'audio separato in voci e resto, in FLAC, così la separazione non deve essere rifatta. Disattivo.
• File video originaleIl video stesso: un unico file con tutto, grande quanto il video e oltre. Disattivo.

Ciascuno entra quando Subtitld ne ha uno da inserire: l'audio separato, per esempio, solo dopo che la separazione è stata eseguita. I sottotitoli, le traduzioni, i parlanti, le voci e ogni doppiaggio ci sono sempre. Deflate riduce di circa un sesto il WAV di un doppiaggio; un video e un FLAC si riducono appena.

Salvataggio automatico e backup

• Salva automaticamente il file di progettoScrive il tuo .usfx stesso, come fa Salva, nello stesso modo sicuro. Per un progetto salvato come USFX.
• Backup automaticiUn .usfx completo nella cartella dei backup di Subtitld, separato dal tuo file, chiamato <project>_<YYYYMMDDHHMMSS>.usfx, quando ci sono modifiche da conservare. Oltre Conserva al massimo, 20 se non scegli diversamente, i più vecchi vengono eliminati.

Nei file manager

La miniatura è una scheda nello stile di Subtitld: il fotogramma del video in cui il progetto è stato lasciato, con il suo sottotitolo, e sotto i dodici secondi di timeline intorno alla testina, la forma d'onda e i sottotitoli nei colori dei loro parlanti. 4:3 a 512 × 384, così riempie la cella quadrata di un file manager meglio di un fotogramma largo. Senza video, il marchio di Subtitld prende il posto del fotogramma.

Con un doppio clic, un progetto si apre in Subtitld su tutti e quattro. Entrambi i generatori di miniature leggono solo thumbnail.png, rifiutano quelle oltre 8 MiB e non accettano nulla che non inizi con la firma del PNG, 89 50 4E 47 0D 0A 1A 0A. Quello di Windows la accetta solo non compressa, come la scrive Subtitld. Quello di Linux usa solo la libreria standard di Python, perché i file manager eseguono i generatori di miniature in sandbox e molti alla volta.

Leggere un .usfx da sé

Niente in un progetto appartiene solo a Subtitld. Per guardarci dentro:

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

Per leggerne i sottotitoli, in ogni lingua, con la libreria standard di 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))

Per un progetto di qualcun altro, analizzalo con defusedxml al posto di xml.etree, come per qualsiasi XML che non hai scritto tu.

Crearne uno

Il progetto più piccolo che Subtitld apre è uno ZIP che contiene un subtitles.usf. Senza manifesto, Subtitld chiede il video. Per crearne uno che riconoscano anche i file manager, segui ciò che scrive Subtitld:

• prima subtitles.usf, poi manifest.xml;
• ogni membro compresso in Deflate, tranne thumbnail.png, non compresso;
• i doppiaggi sotto assets/dubs/, indicati nel documento con il loro percorso nel pacchetto;
• UTF-8 ovunque.

Come si confronta

USFX è costruito come i pacchetti di documenti delle suite per ufficio e degli e-book: uno ZIP, un documento principale in XML, un inventario, i media accanto.

Il documento principale è un formato aperto a pieno titolo: estrai il subtitles.usf di un .usfx ed è un file USF, un formato con una specifica pubblica dal 2002.

Curiosità