Proyek Subtitld

Anatomi berkas

Sebuah .usfx adalah ZIP. Alat arsip apa pun dapat membukanya, diganti namanya menjadi .zip jika alat itu bersikeras.

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

Dokumen menyatakan apa yang terjadi; aset adalah apa yang diputarnya. Sebuah dubbing di subtitles.usf menyebut klipnya lewat jalurnya di dalam paket, assets/dubs/77a03e27.wav, sehingga paket dapat dipindahkan ke folder, disk, atau komputer lain dan tetap utuh.

Anggota paket

Nama di assets/ terdiri atas huruf, angka, -, _, dan .; karakter lain menjadi _, sehingga Tears of Steel.mkv disimpan sebagai Tears_of_Steel.mkv. Huruf di luar ASCII dipertahankan, namanya ditulis dalam UTF-8 dan ditandai demikian (bit 11 header ZIP), sebagaimana diminta APPNOTE.

Byte pertama

Setiap proyek diawali dengan cara yang sama: header berkas lokal ZIP, lalu nama anggota pertamanya.

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

Nama tidak pernah dikompresi, bahkan bila anggotanya dikompresi. Itu menjadikannya tanda tangan: ZIP yang namanya di byte 30 adalah subtitles.usf adalah proyek Subtitld. Tracker di Haiku membedakan proyek dari arsip lain dengan aturan persis itu, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), yang berperingkat di atas aturan ZIP biasa. ODF dan EPUB melakukan hal serupa dengan anggota pertama bernama mimetype.

Video bisa lebih besar daripada batas asli ZIP, 4 GiB. Mulai 2 GiB, Subtitld menulis bidang tambahan dan rekaman akhir Zip64 (APPNOTE bagian 4.5), seperti juga bila anggotanya melebihi 65.535; Subtitld, penangan thumbnail Windows-nya, dan unzip modern mana pun dapat membacanya.

Manifes

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

Tipe-tipenya adalah application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg, dan application/octet-stream untuk bentuk gelombang dan lainnya.

Dokumen

subtitles.usf adalah berkas Universal Subtitle Format, UTF-8, sebagaimana Subtitld menulisnya sendiri, ditambah apa yang dibutuhkan proyek dengan gaya USF sendiri: elemen dan atribut di tempat USF tidak memilikinya. Pembaca USF yang melewati apa yang tidak dikenalnya tetap dapat membaca subtitle-nya.

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

Tambahan Subtitld pada USF

Dalam .usf biasa, gambar pembicara dan audio dubbing dapat dibawa di dalam XML, sebagai base64 di <avatar> dan <data>. Sebuah .usfx tidak pernah melakukannya: semuanya menjadi anggota tersendiri, seperempat lebih kecil daripada dalam base64, dan dibaca tanpa mengurai XML.

Waktu

start dan stop sebuah subtitle adalah waktu USF, dibulatkan ke milidetik terdekat. Waktu dubbing adalah detik biasa yang ditulis lengkap, 18.01579117916244: desimal terpendek yang terbaca kembali sebagai angka 64-bit yang sama, sehingga klip yang ditempatkan dengan menyeret kembali persis di tempatnya semula.

Versi Subtitld yang lebih lama menulis waktu satu milidetik lebih awal, dan awal di nol sebagai 23:59:59.999. Subtitld membaca nilai itu sebagai nol, dan membiarkan milidetiknya apa adanya.

Take dan subklip

Sebuah subtitle dapat memiliki beberapa take. <dubbing> pertama adalah yang diputar; yang lain adalah alternatif, diam sampai Anda memilih salah satunya, yang lalu pindah ke depan.

Take yang dibelah atau diregangkan menyimpan daftar <subclip>, yang ditempatkan seperti klip di editor audio:

Sebuah subklip diputar mulai dari start take ditambah offset-nya, selama end dikurangi start detik. Celah adalah keheningan; tumpang tindih dicampur. Sumbernya tidak pernah diubah, sehingga setiap pembelahan dan peregangan dapat dibatalkan, dan peregangan selalu dibuat ulang dari raw_path, tidak pernah dari regangan atas regangan.

Terjemahan

Setiap bahasa memiliki blok <subtitles> sendiri, dinamai dengan kode ISO 639-2-nya dan, di dalam elemen, nama bahasanya, yang membedakan bahasa Portugis Brasil dari Portugis Portugal. Setiap blok memuat setiap subtitle pada waktu yang sama; hanya blok pertama yang memuat dubbing. Subtitld mencocokkan terjemahan dengan subtitle-nya berdasarkan waktu awal, atau dengan subtitle yang paling banyak bertumpang tindih dengannya, sehingga blok yang ditulis alat lain tidak harus sejajar.

Membuka proyek

Proyek besar langsung terbuka: Subtitld lebih dulu membaca apa yang dibutuhkan editor, dan sisanya sementara Anda bekerja.

Anggota diekstrak ke folder milik Subtitld sendiri, tidak pernah di samping proyek: dokumen, wajah, dan dubbing ke folder tembolok yang dinamai sesuai MD5 jalur proyek. Apa yang datang sementara Anda bekerja dialirkan dalam potongan 1 MiB ke berkas sementara, yang diganti namanya ke tempatnya setelah lengkap, sehingga crash di tengah jalan tidak meninggalkan apa pun yang setengah tertulis. Lain kali proyek yang sama dibuka, berkas yang sudah ada dipakai lagi hanya jika ukurannya persis sama dengan anggotanya; jika tidak, ia diekstrak ulang.

Video dicari dengan urutan ini:

1. video di dalam paket, di assets/video/;
2. jalur di <source path>, jika masih ada;
3. berkas bernama seperti di <source basename>, di folder proyek;
4. jika tidak, Subtitld memintanya.

Berkas yang bukan ZIP, terpotong, atau gagal dalam pemeriksaan CRC tidak membuka apa pun: Subtitld memberitahukannya dan menghapusnya dari daftar terbaru. Proyek lama juga dapat dibuka: yang tanpa manifes, atau yang USF-nya bernama lain di akar ZIP.

Menyimpan proyek

Simpan tidak pernah membahayakan proyek yang Anda miliki.

1. Snapshot. Proyek disalin sebagaimana adanya saat Anda menyimpan, sehingga Anda dapat terus mengedit selagi ia ditulis. Penyimpanan, penyimpanan otomatis, dan pencadangan bergiliran: hanya satu yang menulis pada satu waktu.
2. Berkas baru. Paket ditulis ke <project>.usfx.tmp di samping proyek.
3. Tidak ada yang hilang. Dubbing yang audionya belum ada di tembolok, masih dialirkan atau sudah dihapus, disalin dari berkas yang akan diganti. Proyek yang disimpan tanpa video mempertahankan gambar yang dimilikinya.
4. Diperiksa. Berkas baru dibuka lagi dan CRC-32 setiap anggota diverifikasi.
5. Ditukar. Baru setelah itu ia menggantikan proyek, dalam satu penggantian nama (os.replace): nama proyek tidak pernah memuat setengah proyek.

Jika ada langkah yang gagal, berkas sementara dihapus, proyek di disk tetap yang Anda miliki, dan suntingan Anda masih terbuka di Subtitld. Selama dubbing sebuah proyek masih dialirkan, Simpan menunggunya.

Apa yang dimasukkan

Pengaturan global, lalu USFX, menentukan apa lagi yang dibawa proyek, untuk setiap proyek yang Anda simpan:

• Gambar potret pembicaraWajah para pembicara. Aktif.
• Tembolok bentuk gelombang linimasaBentuk gelombang, sehingga proyek dapat dibuka di komputer lain tanpa menghitungnya lagi. Nonaktif.
• Trek audio asliSuara video, sebagai FLAC. Nonaktif.
• Audio terproses (vokal + latar)Suara yang dipisahkan menjadi vokal dan sisanya, sebagai FLAC, sehingga pemisahan tidak perlu dijalankan lagi. Nonaktif.
• Berkas video asliVideo itu sendiri: satu berkas berisi segalanya, sebesar video atau lebih. Nonaktif.

Masing-masing dimasukkan bila Subtitld memilikinya: suara yang dipisahkan, misalnya, hanya setelah pemisahan dijalankan. Subtitle, terjemahan, pembicara, suara, dan setiap dubbing selalu ada di dalamnya. Deflate memangkas sekitar seperenam dari WAV sebuah dubbing; video dan FLAC hampir tidak mengecil.

Penyimpanan otomatis dan cadangan

• Simpan otomatis berkas proyekMenulis .usfx Anda sendiri, seperti Simpan, dengan cara aman yang sama. Untuk proyek yang disimpan sebagai USFX.
• Pencadangan otomatisSebuah .usfx lengkap di folder cadangan Subtitld, terpisah dari berkas Anda sendiri, bernama <project>_<YYYYMMDDHHMMSS>.usfx, bila ada perubahan yang perlu disimpan. Melewati Simpan maksimal, 20 kecuali Anda memilih lain, yang tertua dihapus.

Di pengelola berkas

Thumbnail-nya adalah kartu bergaya Subtitld: bingkai video tempat proyek ditinggalkan, subtitle di atasnya, dan di bawahnya dua belas detik linimasa di sekitar kepala putar, bentuk gelombang, dan subtitle dengan warna pembicaranya. 4:3 pada 512 × 384, sehingga mengisi sel persegi pengelola berkas lebih baik daripada bingkai lebar. Tanpa video, logo Subtitld menggantikan bingkai.

Bila diklik dua kali, proyek terbuka di Subtitld pada keempatnya. Kedua pembuat thumbnail hanya membaca thumbnail.png, menolak yang lebih dari 8 MiB, dan tidak menerima apa pun yang tidak diawali tanda tangan PNG, 89 50 4E 47 0D 0A 1A 0A. Yang untuk Windows hanya menerimanya bila disimpan apa adanya, seperti yang ditulis Subtitld. Yang untuk Linux hanya memakai pustaka standar Python, karena pengelola berkas menjalankan pembuat thumbnail di dalam sandbox dan banyak sekaligus.

Membaca .usfx sendiri

Tidak ada bagian proyek yang hanya milik Subtitld. Untuk melihat isinya:

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

Untuk membaca subtitle-nya, dalam setiap bahasa, dengan pustaka standar 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))

Untuk proyek dari orang lain, uraikan dengan defusedxml sebagai pengganti xml.etree, seperti untuk XML apa pun yang tidak Anda tulis sendiri.

Membuatnya

Proyek terkecil yang dapat dibuka Subtitld adalah ZIP yang berisi subtitles.usf. Tanpa manifes, Subtitld meminta videonya. Untuk membuat proyek yang juga dikenali pengelola berkas, ikuti apa yang ditulis Subtitld:

• subtitles.usf lebih dulu, lalu manifest.xml;
• setiap anggota dikompresi dengan Deflate, kecuali thumbnail.png, yang disimpan apa adanya;
• dubbing di bawah assets/dubs/, disebut di dalam dokumen dengan jalurnya di dalam paket;
• UTF-8 di mana-mana.

Perbandingan

USFX dibangun seperti paket dokumen suite perkantoran dan buku elektronik: sebuah ZIP, dokumen utama dalam XML, inventaris, dan media di sampingnya.

Dokumen utamanya adalah format terbuka tersendiri: keluarkan subtitles.usf dari sebuah .usfx dan hasilnya adalah berkas USF, format dengan spesifikasi publik sejak 2002.

Trivia