User guide4 min read

MP3 Karaoke File Format Specification (.mp3) & ID3 Embedded Lyrics

Complete technical guide for MP3 karaoke format, ID3v2 header parsing, TXXX/TEXT frame extraction, TIS-620 decoding, and HTML5 Audio timing synchronization.

1. Overview of MP3 Karaoke Specification

MP3 Karaoke combines high-definition studio audio recording (MPEG-1 Layer III) with embedded ID3v2 metadata frames containing word-level KLyr XML lyrics. This allows audio playback of real vocals/instruments while maintaining full real-time lyric color wiping and metadata display within a single .mp3 file.

2. ID3v2 Tag Header Parsing & TIS-620 Decoding

The parser examines the first 10 bytes of the MP3 file buffer for the ID3 magic identifier. It reads the synchsafe integer size and parses text frames with TIS-620/Windows-874 fallback decoding:

Standard ID3 Frames Extracted

Title Frame

TIT2 Frame

Contains official song title string. Automatically decoded via TIS-620/Windows-874 fallback if Thai characters are detected.

Artist Frame

TPE1 Frame

Contains lead artist or band name.

Album Frame

TALB Frame

Contains album or collection name.

3. Embedded KLyr XML Payload Extraction from TXXX / TEXT Frames

Karaoke lyrics are embedded inside custom ID3 text frames (such as TEXT, TXXX_TEXT, or TXXX_Lyricist) prefixed with the LyrHdr string identifier. The extraction workflow functions as follows:

ID3 Lyric Extraction Pipeline

1
1. Frame Scanning: Scan ID3 text frames for LyrHdr1 string prefix.
2
2. Payload Clean & Base64 Decoding: Strip the LyrHdr1 prefix and convert Base64 string payload into Uint8Array bytes.
3
3. zlib Inflation: Decompress binary payload with pako.inflate() to recover raw XML bytes.
4
4. XML Parsing & Audio Duration Syncing: Parse <INFO> and <LYRIC><WORD> elements. Calculate audio duration via HTML5 Audio metadata for millisecond-level lyric color wiping.