Projeto do Subtitld

Estrutura de um arquivo

Um .usfx é um ZIP. Qualquer programa de arquivos compactados o abre, renomeado para .zip se o programa insistir.

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

O documento diz o que acontece; os recursos são o que ele toca. Uma dublagem em subtitles.usf indica seu clipe pelo caminho no pacote, assets/dubs/77a03e27.wav, então o pacote pode ir para outra pasta, disco ou computador e continuar completo.

Os membros

Os nomes em assets/ são feitos de letras, dígitos, -, _ e .; qualquer outra coisa vira _, então Tears of Steel.mkv é guardado como Tears_of_Steel.mkv. Letras fora do ASCII são mantidas, com o nome gravado em UTF-8 e marcado como tal (bit 11 do cabeçalho ZIP), como pede o APPNOTE.

Os primeiros bytes

Todo projeto começa do mesmo jeito: um cabeçalho de arquivo local ZIP, depois o nome do primeiro 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

O nome nunca é comprimido, mesmo quando o membro é. Isso o torna uma assinatura: um ZIP cujo nome no byte 30 é subtitles.usf é um projeto do Subtitld. O Tracker do Haiku distingue projetos de outros arquivos compactados exatamente por essa regra, 0.60 ("PK\003\004") [30] ("subtitles.usf" | "manifest.xml"), classificada acima da regra do ZIP comum. ODF e EPUB fazem o mesmo com um primeiro membro chamado mimetype.

Um vídeo pode ser maior que o limite original do ZIP, de 4 GiB. A partir de 2 GiB, o Subtitld grava os campos extras e os registros finais do Zip64 (APPNOTE, seção 4.5), como faz acima de 65.535 membros; o Subtitld, seu gerador de miniaturas para Windows e qualquer unzip atual os leem.

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

Os tipos são 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 para a forma de onda e qualquer outra coisa.

O documento

subtitles.usf é um arquivo Universal Subtitle Format, em UTF-8, como o Subtitld o grava por conta própria, com o que um projeto precisa acrescentado no estilo do próprio USF: elementos e atributos onde o USF não tem nenhum. Um leitor de USF que ignora o que não conhece lê as legendas.

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

O que o Subtitld acrescenta ao USF

Em um .usf comum, as imagens dos falantes e o áudio das dublagens podem ir dentro do XML, em base64 em <avatar> e <data>. Um .usfx nunca faz isso: eles são membros próprios, um quarto menores que em base64, e lidos sem analisar o XML.

Tempos

O start e o stop de uma legenda são tempos USF, arredondados para o milissegundo mais próximo. Os tempos de uma dublagem são segundos simples escritos por inteiro, 18.01579117916244: o decimal mais curto que é lido de volta como o mesmo número de 64 bits, então um clipe posicionado arrastando volta exatamente aonde estava.

Versões mais antigas do Subtitld gravavam os tempos um milissegundo antes, e um início em zero como 23:59:59.999. O Subtitld lê esse valor como zero, e deixa o milissegundo como está.

Tomadas e subclipes

Uma legenda pode ter várias tomadas. O primeiro <dubbing> é o que toca; os outros são alternativas, mudas até você escolher uma, que então passa para a frente.

Uma tomada que foi dividida ou esticada guarda uma lista de <subclip>s, posicionados como clipes em um editor de áudio:

Um subclipe toca a partir do start da tomada mais seu offset, por end menos start segundos. Lacunas são silêncio; sobreposições são mixadas. As fontes nunca mudam, então toda divisão e todo esticamento podem ser desfeitos, e um esticamento é sempre refeito a partir de raw_path, nunca de um esticamento de um esticamento.

Traduções

Cada idioma tem seu próprio bloco <subtitles>, identificado pelo código ISO 639-2 e, no elemento, pelo nome do idioma, que distingue o português do Brasil do de Portugal. Cada bloco contém todas as legendas nos mesmos tempos; só o primeiro contém dublagens. O Subtitld associa uma tradução à sua legenda pelo tempo de início, ou àquela com que mais se sobrepõe, então blocos gravados por outras ferramentas não precisam estar alinhados.

Abrindo um projeto

Projetos grandes abrem na hora: o Subtitld lê primeiro o que o editor precisa, e o resto enquanto você trabalha.

Os membros são extraídos para as pastas do próprio Subtitld, nunca ao lado do projeto: o documento, os rostos e as dublagens para uma pasta de cache com o nome do MD5 do caminho do projeto. O que chega enquanto você trabalha vem em blocos de 1 MiB para um arquivo temporário, renomeado para o lugar certo ao terminar, então uma falha no meio do caminho não deixa nada gravado pela metade. Na próxima vez que o mesmo projeto abrir, um arquivo que já está lá só é reaproveitado se tiver exatamente o tamanho do membro; senão, é extraído de novo.

O vídeo é procurado nesta ordem:

1. um vídeo dentro do pacote, em assets/video/;
2. o caminho em <source path>, se ainda existir;
3. um arquivo com o nome de <source basename>, na pasta do projeto;
4. senão, o Subtitld pede por ele.

Um arquivo que não é ZIP, está truncado ou falha numa verificação de CRC não abre nada: o Subtitld avisa e o tira da lista de recentes. Projetos mais antigos também abrem: um sem manifesto, ou com o USF com outro nome na raiz do ZIP.

Salvando um projeto

Salvar nunca põe em risco o projeto que você tem.

1. Uma cópia instantânea. O projeto é copiado como está quando você salva, então você pode continuar editando enquanto ele é gravado. Salvamentos, salvamentos automáticos e backups se revezam: um grava de cada vez.
2. Um arquivo novo. O pacote é gravado em <project>.usfx.tmp, ao lado do projeto.
3. Nada faltando. Uma dublagem cujo áudio ainda não está no cache, ainda chegando ou apagado, é copiada do arquivo prestes a ser substituído. Um projeto salvo sem vídeo mantém a imagem que tinha.
4. Verificado. O arquivo novo é aberto de novo e o CRC-32 de cada membro é conferido.
5. Trocado. Só então ele substitui o projeto, numa única renomeação (os.replace): o nome do projeto nunca guarda meio projeto.

Se alguma etapa falhar, o arquivo temporário é apagado, o projeto no disco é o que você tinha e suas edições continuam abertas no Subtitld. Enquanto as dublagens de um projeto ainda estão chegando, Salvar espera por elas.

O que vai dentro

Configurações globais, depois USFX, escolhe o que mais um projeto leva, para todo projeto que você salva:

• Imagens de retrato dos falantesOs rostos dos falantes. Ativado.
• Cache da forma de onda da linha do tempoA forma de onda, para que um projeto abra em outro computador sem calculá-la de novo. Desativado.
• Faixa de áudio originalO som do vídeo, em FLAC. Desativado.
• Áudio processado (vozes + fundo)O som separado em vozes e o resto, em FLAC, para que a separação não precise rodar de novo. Desativado.
• Arquivo de vídeo originalO próprio vídeo: um arquivo com tudo, do tamanho do vídeo e mais. Desativado.

Cada um entra quando o Subtitld tem algo para pôr: o som separado, por exemplo, só depois que a separação rodou. As legendas, traduções, falantes, vozes e todas as dublagens estão sempre dentro. O Deflate tira cerca de um sexto do WAV de uma dublagem; um vídeo e o FLAC quase não diminuem.

Salvamento automático e backups

• Salvar o arquivo do projetoGrava o seu próprio .usfx, como o Salvar, do mesmo jeito seguro. Para um projeto salvo como USFX.
• Backups automáticosUm .usfx completo na pasta de backups do Subtitld, separado do seu arquivo, chamado <project>_<YYYYMMDDHHMMSS>.usfx, quando há alterações a guardar. Passado o Manter no máximo, 20 a menos que você escolha outro valor, os mais antigos são apagados.

Nos gerenciadores de arquivos

A miniatura é um cartão no visual do Subtitld: o quadro do vídeo onde o projeto parou, a legenda sobre ele e, embaixo, os doze segundos da linha do tempo em torno do cursor de reprodução, a forma de onda e as legendas nas cores dos falantes. 4:3 em 512 × 384, então preenche a célula quadrada de um gerenciador de arquivos melhor que um quadro largo. Sem vídeo, a marca do Subtitld aparece no lugar do quadro.

Com um clique duplo, um projeto abre no Subtitld nos quatro. Os dois geradores de miniaturas leem só thumbnail.png, recusam um acima de 8 MiB e não aceitam nada que não comece com a assinatura do PNG, 89 50 4E 47 0D 0A 1A 0A. O do Windows só o aceita armazenado, como o Subtitld o grava. O do Linux usa só a biblioteca padrão do Python, já que os gerenciadores de arquivos rodam geradores de miniaturas em sandbox e vários ao mesmo tempo.

Lendo um .usfx por conta própria

Nada em um projeto é exclusivo do Subtitld. Para olhar dentro:

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

Para ler as legendas, em todos os idiomas, com a biblioteca padrão do 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))

Para um projeto de outra pessoa, analise com defusedxml no lugar de xml.etree, como com qualquer XML que você não escreveu.

Criando um

O menor projeto que o Subtitld abre é um ZIP com um subtitles.usf. Sem manifesto, o Subtitld pede o vídeo. Para criar um que os gerenciadores de arquivos também reconheçam, siga o que o Subtitld grava:

• subtitles.usf primeiro, depois manifest.xml;
• todo membro comprimido em Deflate, menos thumbnail.png, armazenado;
• dublagens em assets/dubs/, indicadas no documento pelo caminho no pacote;
• UTF-8 em tudo.

Como ele se compara

O USFX é construído como os pacotes de documentos das suítes de escritório e dos e-books: um ZIP, um documento principal em XML, um inventário e a mídia ao lado.

O documento principal é um formato aberto por si só: tire o subtitles.usf de um .usfx e ele é um arquivo USF, um formato com especificação pública desde 2002.

Curiosidades