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 밖의 글자는 그대로 남고, 이름은 APPNOTE가 요구하는 대로 UTF-8로 쓰이며 그렇다는 표시(ZIP 헤더의 비트 11)가 붙습니다.

첫 바이트

모든 프로젝트는 똑같이 시작합니다. 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

구성원이 압축되어도 이름은 절대 압축되지 않습니다. 그래서 이름이 시그니처가 됩니다. 바이트 30의 이름이 subtitles.usf인 ZIP은 Subtitld 프로젝트입니다. Haiku의 Tracker는 바로 이 규칙 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml")으로 프로젝트를 다른 압축 파일과 구분하며, 이 규칙을 일반 ZIP 규칙보다 우선합니다. ODF와 EPUB도 mimetype이라는 이름의 첫 구성원으로 같은 일을 합니다.

영상은 ZIP 원래의 한계인 4 GiB보다 클 수 있습니다. 2 GiB부터 Subtitld는 Zip64의 추가 필드와 끝 레코드(APPNOTE 4.5절)를 기록하며, 구성원이 65,535개를 넘을 때도 마찬가지입니다. Subtitld, 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는 범용 자막 형식 파일(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에서는 화자의 그림과 더빙의 오디오를 <avatar>와 <data>에 base64로 넣어 XML 안에 담을 수 있습니다. .usfx는 절대 그렇게 하지 않습니다. 그것들은 각각 독립된 구성원이 되어 base64보다 4분의 1 작고, XML을 파싱하지 않고도 읽힙니다.

시간

자막의 start와 stop은 USF 시간이며, 가장 가까운 밀리초로 반올림됩니다. 더빙의 시간은 생략 없이 적은 평범한 초 18.01579117916244입니다. 같은 64비트 숫자로 다시 읽히는 가장 짧은 십진수이므로, 끌어서 놓은 클립이 정확히 원래 자리로 돌아옵니다.

이전 버전의 Subtitld는 시간을 1밀리초 이르게 기록했고, 0에서의 시작을 23:59:59.999로 썼습니다. Subtitld는 그 값을 0으로 읽고, 밀리초는 그대로 둡니다.

테이크와 서브클립

자막 하나는 여러 테이크를 가질 수 있습니다. 첫 번째 <dubbing>이 재생되는 것이고, 나머지는 대안입니다. 고르기 전까지는 소리가 나지 않으며, 고른 테이크가 맨 앞으로 옮겨집니다.

나누거나 늘인 테이크는 오디오 편집기의 클립처럼 배치된 <subclip> 목록을 가집니다.

서브클립은 테이크의 start에 offset을 더한 위치부터 end 빼기 start초 동안 재생됩니다. 빈틈은 무음이고, 겹치는 부분은 섞입니다. 원본은 절대 바뀌지 않으므로 모든 나누기와 늘이기를 되돌릴 수 있으며, 늘이기는 항상 raw_path에서 다시 만들어지고 늘인 것을 다시 늘이는 일은 없습니다.

번역

언어마다 자기 <subtitles> 블록이 있으며, ISO 639-2 코드와 요소 안의 언어 이름으로 구분합니다. 언어 이름 덕분에 브라질 포르투갈어와 포르투갈 포르투갈어를 구별할 수 있습니다. 모든 블록은 모든 자막을 같은 시간에 담고, 더빙은 첫 블록에만 있습니다. Subtitld는 번역을 시작 시간으로, 또는 가장 많이 겹치는 자막으로 짝지으므로, 다른 도구가 쓴 블록이 딱 맞지 않아도 됩니다.

프로젝트 열기

큰 프로젝트도 바로 열립니다. Subtitld는 편집기에 필요한 것을 먼저 읽고, 나머지는 작업하는 동안 읽습니다.

구성원은 프로젝트 옆이 아니라 Subtitld 전용 폴더에 추출됩니다. 문서, 얼굴, 더빙은 프로젝트 경로의 MD5를 이름으로 한 캐시 폴더에 들어갑니다. 작업 중에 들어오는 것은 1 MiB씩 임시 파일로 흘려 넣고, 다 받은 뒤에 제자리 이름으로 바꾸므로, 중간에 비정상 종료되어도 반쯤 쓰인 파일은 남지 않습니다. 다음에 같은 프로젝트를 열 때, 이미 있는 파일은 크기가 구성원과 정확히 같을 때만 다시 쓰고, 그렇지 않으면 다시 추출합니다.

영상은 다음 순서로 찾습니다.

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를 약 6분의 1 줄이지만, 영상과 FLAC은 거의 줄지 않습니다.

자동 저장과 백업

• 프로젝트 파일 자동 저장저장과 같은 안전한 방식으로 .usfx 자체에 기록합니다. USFX로 저장한 프로젝트가 대상입니다.
• 자동 백업남길 변경 사항이 있을 때, 사용자의 파일과 따로 Subtitld 백업 폴더에 완전한 .usfx를 <project>_<YYYYMMDDHHMMSS>.usfx라는 이름으로 만듭니다. 최대 보관(따로 정하지 않으면 20)을 넘으면 가장 오래된 것부터 삭제됩니다.

파일 관리자에서

썸네일은 Subtitld 모양의 카드입니다. 프로젝트를 멈춘 영상 프레임과 그 위의 자막, 그 아래로 재생 헤드 주변 12초의 타임라인, 파형, 화자 색으로 칠한 자막이 놓입니다. 4:3 비율의 512 × 384이므로, 넓은 프레임보다 파일 관리자의 정사각형 칸을 더 잘 채웁니다. 영상이 없으면 프레임 대신 Subtitld 마크가 들어갑니다.

네 시스템 모두에서 더블클릭하면 프로젝트가 Subtitld에서 열립니다. 두 썸네일 생성기 모두 thumbnail.png만 읽고, 8 MiB가 넘는 것은 거부하며, 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))

다른 사람에게서 받은 프로젝트는, 직접 쓰지 않은 모든 XML과 마찬가지로 xml.etree 대신 defusedxml로 파싱하세요.

직접 만들기

Subtitld가 여는 가장 작은 프로젝트는 subtitles.usf 하나를 담은 ZIP입니다. 매니페스트가 없으면 Subtitld가 영상을 묻습니다. 파일 관리자도 알아보는 프로젝트를 만들려면 Subtitld가 쓰는 방식을 따르세요.

• subtitles.usf를 먼저, 그다음 manifest.xml;
• 모든 구성원은 Deflate로 압축하되, thumbnail.png는 무압축으로 저장;
• 더빙은 assets/dubs/ 아래에 두고, 문서에서는 패키지 안의 경로로 가리킴;
• 어디서나 UTF-8.

다른 형식과의 비교

USFX는 오피스 제품군과 전자책의 문서 패키지와 같은 방식으로 만들어졌습니다. ZIP, XML로 된 주 문서, 목록, 그리고 그 옆의 미디어입니다.

주 문서는 그 자체로 개방형 형식입니다. .usfx에서 subtitles.usf를 꺼내면 그것은 2002년부터 공개 사양이 있는 형식인 USF 파일입니다.

알아두면 좋은 사실