Dự án Subtitld

Cấu trúc tệp

Một tệp .usfx là một ZIP. Mọi công cụ nén đều mở được nó; nếu công cụ khăng khăng, hãy đổi đuôi thành .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

Tài liệu cho biết điều gì xảy ra; tài nguyên là thứ nó phát. Một lồng tiếng trong subtitles.usf gọi clip của mình bằng đường dẫn trong gói, assets/dubs/77a03e27.wav, nên gói có thể chuyển sang thư mục, ổ đĩa hay máy tính khác mà vẫn nguyên vẹn.

Các thành phần

Tên trong assets/ gồm chữ cái, chữ số, -, _ và .; mọi ký tự khác thành _, nên Tears of Steel.mkv được lưu là Tears_of_Steel.mkv. Chữ cái ngoài ASCII được giữ nguyên, tên được ghi bằng UTF-8 và gắn cờ như vậy (bit 11 của tiêu đề ZIP), đúng như APPNOTE yêu cầu.

Những byte đầu tiên

Mọi dự án đều bắt đầu như nhau: một tiêu đề tệp cục bộ của ZIP, rồi đến tên của thành phần đầu tiên.

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

Tên không bao giờ bị nén, kể cả khi thành phần được nén. Điều đó biến nó thành một chữ ký: một ZIP có tên ở byte 30 là subtitles.usf là một dự án Subtitld. Tracker của Haiku phân biệt dự án với các tệp nén khác đúng bằng quy tắc đó, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), xếp trên quy tắc ZIP thông thường. ODF và EPUB cũng làm vậy với thành phần đầu tiên tên là mimetype.

Một video có thể lớn hơn giới hạn 4 GiB ban đầu của ZIP. Từ 2 GiB trở lên, Subtitld ghi các trường phụ và bản ghi kết thúc của Zip64 (APPNOTE mục 4.5), cũng như khi vượt quá 65.535 thành phần; Subtitld, trình xử lý hình thu nhỏ trên Windows của nó và mọi unzip hiện nay đều đọc được chúng.

Bản kê khai

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

Các loại là application/x-usf+xml, image/png, audio/wav, audio/flac, audio/mpeg, video/mp4, video/x-matroska, video/quicktime, video/webm, video/ogg, và application/octet-stream cho dạng sóng và mọi thứ khác.

Tài liệu

subtitles.usf là một tệp Universal Subtitle Format, UTF-8, đúng như Subtitld tự ghi, kèm những gì một dự án cần được thêm theo phong cách riêng của USF: phần tử và thuộc tính ở những chỗ USF không có. Một trình đọc USF bỏ qua những gì nó không biết vẫn đọc được phụ đề.

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

Những gì Subtitld thêm vào USF

Trong một tệp .usf thông thường, hình ảnh người nói và âm thanh lồng tiếng có thể nằm bên trong XML, dưới dạng base64 trong <avatar> và <data>. Tệp .usfx không bao giờ làm vậy: chúng là những thành phần riêng, nhỏ hơn một phần tư so với base64, và được đọc mà không cần phân tích XML.

Thời gian

start và stop của một phụ đề là thời gian USF, làm tròn tới mili giây gần nhất. Thời gian của lồng tiếng là số giây thuần được ghi đầy đủ, 18.01579117916244: số thập phân ngắn nhất đọc lại ra đúng số 64 bit đó, nên một clip được đặt bằng cách kéo sẽ trở về đúng chỗ cũ.

Các phiên bản Subtitld cũ ghi thời gian sớm một mili giây, và ghi điểm bắt đầu ở số không thành 23:59:59.999. Subtitld đọc giá trị đó là số không, và để nguyên mili giây đó.

Bản thu và clip con

Một phụ đề có thể có nhiều bản thu. <dubbing> đầu tiên là bản được phát; các bản khác là bản thay thế, im lặng cho tới khi bạn chọn một bản, và bản đó sẽ lên đầu.

Một bản thu đã tách hoặc kéo giãn giữ một danh sách <subclip>, được đặt như các clip trong trình chỉnh sửa âm thanh:

Một clip con phát từ start của bản thu cộng với offset của nó, trong end trừ start giây. Khoảng trống là im lặng; chỗ chồng lên nhau được trộn. Nguồn không bao giờ bị thay đổi, nên mọi lần tách và kéo giãn đều có thể hoàn tác, và một lần kéo giãn luôn được làm lại từ raw_path, không bao giờ từ bản kéo giãn của một bản kéo giãn.

Bản dịch

Mỗi ngôn ngữ có khối <subtitles> riêng, đặt tên theo mã ISO 639-2 và, trong phần tử, theo tên ngôn ngữ, giúp phân biệt tiếng Bồ Đào Nha của Brazil với của Bồ Đào Nha. Mọi khối chứa mọi phụ đề ở cùng thời gian; chỉ khối đầu tiên chứa lồng tiếng. Subtitld ghép một bản dịch với phụ đề của nó theo thời gian bắt đầu, hoặc theo phụ đề mà nó chồng lấn nhiều nhất, nên các khối do công cụ khác ghi không cần phải khớp nhau.

Mở một dự án

Dự án lớn mở ngay: Subtitld đọc trước những gì trình chỉnh sửa cần, phần còn lại thì đọc trong lúc bạn làm việc.

Các thành phần được giải nén vào thư mục riêng của Subtitld, không bao giờ cạnh dự án: tài liệu, khuôn mặt và lồng tiếng vào một thư mục bộ đệm đặt tên theo MD5 của đường dẫn dự án. Những gì đến trong lúc bạn làm việc được truyền theo từng khối 1 MiB vào một tệp tạm, rồi đổi tên vào đúng chỗ khi hoàn tất, nên một sự cố giữa chừng không để lại thứ gì ghi dở. Lần sau khi cùng dự án đó được mở, một tệp đã có sẵn chỉ được dùng lại nếu nó đúng bằng kích thước của thành phần; nếu không, nó được giải nén lại.

Video được tìm theo thứ tự này:

1. một video bên trong gói, trong assets/video/;
2. đường dẫn trong <source path>, nếu tệp vẫn còn ở đó;
3. một tệp có tên như trong <source basename>, trong thư mục của dự án;
4. nếu không, Subtitld hỏi bạn.

Một tệp không phải ZIP, bị cắt cụt hoặc không qua được kiểm tra CRC sẽ không mở ra gì: Subtitld báo như vậy và gỡ nó khỏi danh sách gần đây. Các dự án cũ hơn cũng mở được: dự án không có bản kê khai, hoặc có USF mang tên khác ở gốc của ZIP.

Lưu một dự án

Lưu không bao giờ đặt dự án bạn đang có vào rủi ro.

1. Một ảnh chụp. Dự án được sao chép đúng như lúc bạn lưu, nên bạn có thể tiếp tục chỉnh sửa trong khi nó được ghi. Lưu, tự động lưu và sao lưu thay phiên nhau: mỗi lúc chỉ một thứ ghi.
2. Một tệp mới. Gói được ghi thành <project>.usfx.tmp cạnh dự án.
3. Không thiếu gì. Một lồng tiếng mà âm thanh chưa có trong bộ đệm, vì vẫn đang truyền về hoặc đã bị xóa, được sao chép từ tệp sắp bị thay thế. Một dự án được lưu mà không có video vẫn giữ hình ảnh nó từng có.
4. Được kiểm tra. Tệp mới được mở lại và CRC-32 của mọi thành phần được xác minh.
5. Được hoán đổi. Chỉ khi đó nó mới thay thế dự án, bằng một lần đổi tên (os.replace): tên của dự án không bao giờ chứa nửa dự án.

Nếu bất kỳ bước nào thất bại, tệp tạm bị xóa, dự án trên đĩa vẫn là dự án bạn đã có, và các chỉnh sửa của bạn vẫn đang mở trong Subtitld. Trong khi lồng tiếng của một dự án vẫn đang truyền về, Lưu sẽ chờ chúng.

Những gì được đưa vào bên trong

Cài đặt toàn cục, rồi USFX, chọn xem một dự án mang theo những gì khác, cho mọi dự án bạn lưu:

• Ảnh chân dung người nóiKhuôn mặt của những người nói. Bật.
• Bộ đệm dạng sóng của dòng thời gianDạng sóng, để dự án mở trên máy tính khác mà không phải tính lại nó. Tắt.
• Rãnh âm thanh gốcÂm thanh của video, dưới dạng FLAC. Tắt.
• Âm thanh đã xử lý (giọng nói + nền)Âm thanh được tách thành giọng nói và phần còn lại, dưới dạng FLAC, để không phải chạy tách lại. Tắt.
• Tệp video gốcChính video: một tệp chứa mọi thứ, lớn bằng video và hơn thế. Tắt.

Mỗi thứ được đưa vào khi Subtitld có cái để đưa: chẳng hạn âm thanh đã tách, chỉ sau khi việc tách đã chạy. Phụ đề, bản dịch, người nói, giọng và mọi lồng tiếng luôn nằm bên trong. Deflate giảm khoảng một phần sáu dung lượng WAV của một lồng tiếng; video và FLAC hầu như không nhỏ đi.

Tự động lưu và sao lưu

• Tự động lưu tệp dự ánGhi chính tệp .usfx của bạn, như Lưu, theo cùng cách an toàn đó. Dành cho dự án đã lưu dưới dạng USFX.
• Sao lưu tự độngMột tệp .usfx đầy đủ trong thư mục sao lưu của Subtitld, tách biệt với tệp của bạn, đặt tên <project>_<YYYYMMDDHHMMSS>.usfx, khi có thay đổi cần giữ. Vượt quá Giữ nhiều nhất, 20 trừ khi bạn chọn khác, các bản cũ nhất sẽ bị xóa.

Trong trình quản lý tệp

Hình thu nhỏ là một thẻ theo phong cách của Subtitld: khung hình video nơi dự án được dừng lại, phụ đề trên đó, và bên dưới là mười hai giây dòng thời gian quanh đầu phát, với dạng sóng và các phụ đề mang màu của người nói. Tỷ lệ 4:3 ở 512 × 384, nên nó lấp ô vuông của trình quản lý tệp tốt hơn một khung hình rộng. Khi không có video, biểu tượng của Subtitld thế chỗ khung hình.

Khi nhấp đúp, một dự án mở trong Subtitld trên cả bốn hệ thống. Cả hai trình tạo hình thu nhỏ chỉ đọc thumbnail.png, từ chối tệp lớn hơn 8 MiB, và không nhận thứ gì không bắt đầu bằng chữ ký của PNG, 89 50 4E 47 0D 0A 1A 0A. Trình trên Windows chỉ nhận nó khi được lưu nguyên, như Subtitld ghi. Trình trên Linux chỉ dùng thư viện chuẩn của Python, vì trình quản lý tệp chạy trình tạo hình thu nhỏ trong hộp cát và nhiều cái cùng lúc.

Tự đọc một tệp .usfx

Không có gì trong một dự án là của riêng Subtitld. Để xem bên trong:

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

Để đọc phụ đề, bằng mọi ngôn ngữ, với thư viện chuẩn của 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))

Với một dự án từ người khác, hãy phân tích bằng defusedxml thay cho xml.etree, như với mọi XML không phải do bạn viết.

Tự tạo một tệp

Dự án nhỏ nhất Subtitld mở được là một ZIP chứa một tệp subtitles.usf. Không có bản kê khai, Subtitld sẽ hỏi video. Để tạo một tệp mà trình quản lý tệp cũng nhận ra, hãy làm theo những gì Subtitld ghi:

• subtitles.usf trước, rồi manifest.xml;
• mọi thành phần được nén bằng Deflate, trừ thumbnail.png, được lưu nguyên;
• lồng tiếng nằm trong assets/dubs/, được gọi trong tài liệu bằng đường dẫn trong gói;
• UTF-8 ở mọi nơi.

So sánh

USFX được xây dựng như các gói tài liệu của bộ ứng dụng văn phòng và sách điện tử: một ZIP, một tài liệu chính bằng XML, một bản kê và phương tiện đi kèm bên cạnh.

Tài liệu chính tự nó là một định dạng mở: lấy subtitles.usf ra khỏi một tệp .usfx, bạn có một tệp USF, định dạng có đặc tả công khai từ năm 2002.

Điều thú vị