Проєкт Subtitld

Будова файлу

.usfx — це ZIP. Його відкриває будь-який архіватор; якщо інструмент наполягає, перейменуйте файл на .zip.

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

Документ каже, що відбувається; ресурси — це те, що він відтворює. Дубляж у subtitles.usf називає свій кліп за шляхом у пакеті, assets/dubs/77a03e27.wav, тож пакет можна перенести в іншу теку, на інший диск чи комп’ютер, і він залишиться цілим.

Члени пакета

Назви в assets/ складаються з літер, цифр, -, _ і .; усе інше стає _, тож Tears of Steel.mkv зберігається як Tears_of_Steel.mkv. Літери поза ASCII зберігаються: назва записується в UTF-8 і позначається відповідним прапорцем (біт 11 заголовка ZIP), як вимагає APPNOTE.

Перші байти

Кожен проєкт починається однаково: локальний заголовок файлу ZIP, далі назва першого члена.

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

Назва ніколи не стискається, навіть коли член стиснутий. Це робить її сигнатурою: ZIP, у якого на байті 30 стоїть назва subtitles.usf, — це проєкт Subtitld. Tracker у Haiku відрізняє проєкти від інших архівів саме за цим правилом, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), яке має вищий пріоритет за звичайне правило ZIP. ODF і EPUB роблять те саме з першим членом на ім’я mimetype.

Відео може бути більшим за початкову межу ZIP у 4 ГіБ. Починаючи з 2 ГіБ, Subtitld записує додаткові поля та кінцеві записи Zip64 (APPNOTE, розділ 4.5), так само як і понад 65 535 членів; Subtitld, його обробник мініатюр для Windows і будь-який сучасний unzip їх читають.

Маніфест

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

Типи: application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg, а для форми хвилі та всього іншого — application/octet-stream.

Документ

subtitles.usf — це файл Universal Subtitle Format в UTF-8, такий, яким його записує сам Subtitld, із доданим тим, що потрібне проєкту, у стилі самого USF: елементи й атрибути там, де в USF їх немає. Читач USF, який пропускає незнайоме, прочитає його субтитри.

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

Що Subtitld додає до USF

У звичайному .usf зображення мовців і звук дубляжів можуть бути всередині XML, у base64 в <avatar> і <data>. .usfx ніколи так не робить: це окремі члени, на чверть менші, ніж у base64, і читаються без розбору XML.

Час

start і stop субтитру — це час USF, округлений до найближчої мілісекунди. Час дубляжу — це прості секунди, записані повністю, 18.01579117916244: найкоротший десятковий запис, який читається назад як те саме 64-бітне число, тож кліп, розміщений перетягуванням, повертається точно туди, де був.

Старіші версії Subtitld записували час на мілісекунду раніше, а початок у нулі — як 23:59:59.999. Subtitld читає це значення як нуль, а мілісекунду залишає як є.

Дублі та підкліпи

Субтитр може мати кілька дублів. Перший <dubbing> — той, що звучить; інші — альтернативи, які мовчать, доки ви не оберете одну з них, і тоді вона переходить на перше місце.

Дубль, який розділили чи розтягнули, зберігає список <subclip>, розміщених як кліпи в аудіоредакторі:

Підкліп звучить від start дубля плюс його offset упродовж end мінус start секунд. Проміжки — тиша; накладання змішуються. Джерела ніколи не змінюються, тож кожне розділення та розтягнення можна скасувати, а розтягнення завжди переробляється з raw_path, ніколи з розтягнення розтягнення.

Переклади

Кожна мова має власний блок <subtitles>, названий кодом ISO 639-2, а в елементі — назвою мови, яка відрізняє бразильську португальську від португальської Португалії. Кожен блок містить кожен субтитр у тому самому часі; лише перший містить дубляжі. Subtitld зіставляє переклад із субтитром за часом початку або за тим, з яким він найбільше перетинається, тож блоки, записані іншими інструментами, не мусять збігатися.

Відкриття проєкту

Великі проєкти відкриваються одразу: Subtitld спершу читає те, що потрібне редактору, а решту — поки ви працюєте.

Члени розпаковуються у власні теки Subtitld, ніколи не поруч із проєктом: документ, обличчя й дубляжі — у теку кешу, названу за MD5 шляху проєкту. Те, що надходить, поки ви працюєте, передається частинами по 1 МіБ у тимчасовий файл, який після завершення перейменовується на своє місце, тож збій посередині не залишає нічого записаного наполовину. Коли той самий проєкт відкривається наступного разу, наявний файл використовується повторно, лише якщо його розмір точно збігається з розміром члена; інакше він розпаковується знову.

Відео шукається в такому порядку:

1. відео всередині пакета, в assets/video/;
2. шлях у <source path>, якщо файл досі там;
3. файл із назвою з <source basename> у теці проєкту;
4. інакше Subtitld просить вказати його.

Файл, який не є ZIP, обрізаний або не проходить перевірку CRC, нічого не відкриває: Subtitld повідомляє про це і прибирає його зі списку нещодавніх. Відкриваються й давніші проєкти: без маніфесту або з USF під іншою назвою в корені ZIP.

Збереження проєкту

Зберегти ніколи не ставить під загрозу проєкт, який у вас є.

1. Знімок. Проєкт копіюється таким, яким він є в момент збереження, тож ви можете редагувати далі, поки він записується. Збереження, автозбереження та резервні копії чергуються: одночасно пише лише одне.
2. Новий файл. Пакет записується в <project>.usfx.tmp поруч із проєктом.
3. Нічого не бракує. Дубляж, звуку якого ще немає в кеші, бо він досі надходить або його очищено, копіюється з файлу, який от-от буде замінено. Проєкт, збережений без відео, зберігає зображення, яке мав.
4. Перевірено. Новий файл відкривається знову, і CRC-32 кожного члена перевіряється.
5. Замінено. Лише тоді він замінює проєкт одним перейменуванням (os.replace): під назвою проєкту ніколи не лежить половина проєкту.

Якщо будь-який крок не вдається, тимчасовий файл видаляється, на диску лишається той проєкт, що у вас був, а ваші зміни досі відкриті в Subtitld. Поки дубляжі проєкту ще надходять, Зберегти на них чекає.

Що потрапляє всередину

Загальні налаштування, далі USFX, визначає, що ще несе проєкт, для кожного проєкту, який ви зберігаєте:

• Портрети мовцівОбличчя мовців. Увімкнено.
• Кеш форми хвилі шкали часуФорма хвилі, щоб проєкт відкрився на іншому комп’ютері без її повторного обчислення. Вимкнено.
• Оригінальна звукова доріжкаЗвук відео, у FLAC. Вимкнено.
• Оброблене аудіо (вокал + фон)Звук, розділений на голоси та решту, у FLAC, щоб розділення не довелося запускати знову. Вимкнено.
• Оригінальний відеофайлСаме відео: один файл з усім, завбільшки як відео і ще трохи. Вимкнено.

Кожен пункт потрапляє всередину, коли Subtitld має що покласти: відокремлений звук, наприклад, лише після того, як розділення відбулося. Субтитри, переклади, мовці, голоси та кожен дубляж завжди всередині. Deflate зменшує WAV дубляжу приблизно на шосту частину; відео та FLAC майже не стискаються.

Автозбереження та резервні копії

• Автоматично зберігати файл проєктуЗаписує сам ваш .usfx, як Зберегти, тим самим безпечним способом. Для проєкту, збереженого як USFX.
• Автоматичні резервні копіїПовний .usfx у теці резервних копій Subtitld, окремо від вашого файлу, з назвою <project>_<YYYYMMDDHHMMSS>.usfx, коли є зміни, які варто зберегти. Понад Зберігати не більше, тобто 20, якщо ви не оберете інше, найстаріші видаляються.

У файлових менеджерах

Мініатюра — це картка в стилі Subtitld: кадр відео, де проєкт залишили, субтитр на ньому, а під ним дванадцять секунд шкали часу довкола курсора відтворення, форма хвилі та субтитри в кольорах їхніх мовців. 4:3 при 512 × 384, тож вона заповнює квадратну клітинку файлового менеджера краще за широкий кадр. Без відео замість кадру стоїть знак Subtitld.

Подвійним клацанням проєкт відкривається в Subtitld у всіх чотирьох. Обидва генератори мініатюр читають лише thumbnail.png, відхиляють файл понад 8 МіБ і не беруть нічого, що не починається сигнатурою PNG, 89 50 4E 47 0D 0A 1A 0A. Windows-генератор бере його лише нестиснутим, як його записує Subtitld. Linux-генератор використовує тільки стандартну бібліотеку Python, бо файлові менеджери запускають генератори мініатюр в ізольованому середовищі й багато одночасно.

Читання .usfx власноруч

Ніщо в проєкті не належить лише Subtitld. Щоб зазирнути всередину:

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

Щоб прочитати субтитри всіма мовами стандартною бібліотекою 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))

Проєкт від когось іншого розбирайте за допомогою defusedxml замість xml.etree, як і будь-який XML, який писали не ви.

Як створити власний

Найменший проєкт, який відкриває Subtitld, — це ZIP із файлом subtitles.usf. Без маніфесту Subtitld просить вказати відео. Щоб створити такий, який розпізнають і файлові менеджери, наслідуйте те, що записує Subtitld:

• спершу subtitles.usf, потім manifest.xml;
• кожен член стиснутий Deflate, крім thumbnail.png, який зберігається без стиснення;
• дубляжі в assets/dubs/, названі в документі за шляхом у пакеті;
• UTF-8 усюди.

Порівняння

USFX побудований так само, як пакети документів офісних пакетів і електронних книжок: ZIP, основний документ в XML, опис вмісту та медіа поруч.

Основний документ — самостійний відкритий формат: витягніть subtitles.usf із .usfx, і це файл USF, формату з публічною специфікацією від 2002 року.

Цікаве