Formato das tags ID3

Formato das tags ID3

O que o agente grava

O agente que alimenta o SongV (server.py) salva os MP3 com o mutagen em ID3v2.3, com texto em UTF-8:

Frame	Conteúdo
TIT2	título
TPE1	artista
TALB / TPE2	álbum / artista do álbum (opcionais)
TRCK / TPOS	número da faixa / do disco ("3/12" → 3)
TYER ou TDRC	ano ("2019-05-01" → 2019)
APIC	capa, tipo 3 ("cover front")
SYLT	letra sincronizada, tempo em milissegundos (formato 2)
USLT	letra simples (quando não há sincronizada)

Por que um parser próprio

Bibliotecas prontas (ex.: mp3agic) leem USLT, mas não leem SYLT. O Id3Parser lê os bytes direto e cobre o que costuma quebrar parsers caseiros:

• v2.2, v2.3 e v2.4 — incluindo os IDs de 3 letras da v2.2 (TT2, TP1, PIC, SLT, ULT…);
• tamanho de frame sync-safe (v2.4) vs. inteiro de 32 bits (v2.3);
• cabeçalho estendido;
• unsynchronisation na tag inteira (v2.2/v2.3) e por frame (v2.4);
• frames comprimidos (zlib), com indicador de tamanho e id de grupo;
• encodings ISO-8859-1, UTF-16 com BOM, UTF-16BE e UTF-8, e vários valores num frame de texto ("A\0B" → "A, B");
• várias imagens: prefere a capa frontal.

Estruturas

SYLT

encoding(1) idioma(3) formato_tempo(1) tipo_conteúdo(1) descrição\0
[ texto\0  tempo(4 bytes, big-endian) ] × N

Só o formato de tempo 2 (ms) é aceito — o formato 1 (frames MPEG) dependeria do bitrate. Textos vazios são preservados como trechos instrumentais.

USLT

encoding(1) idioma(3) descrição\0 texto

Se o texto tiver cara de LRC (duas ou mais linhas começando com [mm:ss), ele é lido como letra sincronizada.

APIC

encoding(1) mime\0 tipo(1) descrição\0 dados

(Na v2.2, PIC tem um formato de 3 letras — JPG/PNG — no lugar do mime.)

Testes

Os testes em app/src/test/java/com/songv/app/id3/Id3ParserTest.kt montam tags byte a byte — v2.2, v2.3, v2.4, unsynchronisation, várias capas — e conferem o resultado:

./gradlew testDebugUnitTest