id3dev 26.01
An ID3 metadata library
Loading...
Searching...
No Matches
id3v2Parser.h File Reference

Definitions for binary parsing of ID3v2 tags, headers, frames, and complete tag structures from byte buffers. More...

#include "id3v2Types.h"
Include dependency graph for id3v2Parser.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

uint32_t id3v2ParseExtendedTagHeader (uint8_t *in, size_t inl, uint8_t version, Id3v2ExtendedTagHeader **extendedTagHeader)
 Parses an ID3v2 extended tag header from a byte buffer.
uint32_t id3v2ParseTagHeader (uint8_t *in, size_t inl, Id3v2TagHeader **tagHeader, uint32_t *tagSize)
 Parses an ID3v2 tag header from a byte buffer (excluding extended header).
uint32_t id3v2ParseFrameHeader (uint8_t *in, size_t inl, uint8_t version, Id3v2FrameHeader **frameHeader, uint32_t *frameSize)
 Parses an ID3v2 frame header from a byte buffer.
uint32_t id3v2ParseFrame (uint8_t *in, size_t inl, List *context, uint8_t version, Id3v2Frame **frame)
 Parses an ID3v2 frame (header + content) from a byte buffer using context-driven interpretation.
Id3v2Tag * id3v2ParseTagFromBuffer (uint8_t *in, size_t inl, HashTable *userPairs)
 Parses a complete ID3v2 tag from a byte buffer, including header, optional extended header, and all frames.

Detailed Description

Definitions for binary parsing of ID3v2 tags, headers, frames, and complete tag structures from byte buffers.

Author
Ewan Jones
Version
26.01
Date
2024-01-19 - 2026-01-13
Copyright
Copyright (c) 2024 - 2026

Definition in file id3v2Parser.h.

Function Documentation

◆ id3v2ParseExtendedTagHeader()

uint32_t id3v2ParseExtendedTagHeader ( uint8_t * in,
size_t inl,
uint8_t version,
Id3v2ExtendedTagHeader ** extendedTagHeader )

Parses an ID3v2 extended tag header from a byte buffer.

Extracts and decodes extended header fields from binary data according to the ID3v2 specification. Returns the number of bytes consumed during parsing and creates a heap-allocated extended header structure. Supports version-specific parsing:

  • ID3v2.3: Reads size (4 bytes), CRC flag (bit 7), 2 reserved bytes, padding size (4 bytes), and optional CRC-32 (4 bytes if flag set).
  • ID3v2.4: Reads extended size (4 bytes), flag bytes count (1 byte), flags byte (update at bit 6, CRC at bit 5, restrictions at bit 4), optional syncsafe CRC-32 (5 bytes), and optional restrictions byte (8 bits for tag/text/image limitations).

ID3v2.2 and unsupported versions return 0 with NULL extendedTagHeader. On success, caller must free the returned structure with id3v2DestroyExtendedTagHeader.

Parameters
in- Pointer to byte buffer containing extended header data.
inl- Size of input buffer in bytes.
version- ID3v2 version (ID3V2_TAG_VERSION_3 or ID3V2_TAG_VERSION_4).
extendedTagHeader- Output parameter receiving pointer to heap-allocated extended header structure, or NULL on failure.
Returns
uint32_t - Number of bytes read from buffer on success, 0 on failure or unsupported version.

Definition at line 72 of file id3v2Parser.c.

◆ id3v2ParseFrame()

uint32_t id3v2ParseFrame ( uint8_t * in,
size_t inl,
List * context,
uint8_t version,
Id3v2Frame ** frame )

Parses an ID3v2 frame (header + content) from a byte buffer using context-driven interpretation.

Extracts a complete frame by first parsing the header, then interpreting frame content according to a context list that provides "hints" about data types and structure. The context-driven approach allows flexible parsing of the diverse frame types in the ID3v2 specification.

Encrypted/Compressed Frame Handling: Frames with encryptionSymbol or decompressionSize set are parsed as raw binary using a generic context. The caller must decrypt/decompress and reparse to access structured content.

Context Types Supported:

  • encodedString_context: Null-terminated strings with encoding determined by prior "encoding" byte (ISO-8859-1, UTF-8, UTF-16BE/LE)
  • latin1Encoding_context: Null-terminated Latin-1 (ISO-8859-1) strings only
  • binary_context/noEncoding_context/precision_context/numeric_context: Fixed-size raw binary/numeric data
  • bit_context: Bit-level extraction (WARNING: incorrect implementation as of jan 13 2026)
  • iter_context: Loop control marker for repeated field groups
  • adjustment_context: Variable-length data where size comes from previously parsed "adjustment" field
  • unknown_context: Skip remaining content

The function creates heap-allocated content entries for each parsed field and assembles them into a complete frame structure. On success, caller must free with id3v2DestroyFrame.

Parameters
in- Pointer to byte buffer containing complete frame data.
inl- Size of input buffer in bytes.
context- List of Id3v2ContentContext structures defining frame structure and data types.
version- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4).
frame- Output parameter receiving pointer to heap-allocated frame structure, or NULL on failure.
Returns
uint32_t - Total bytes consumed on success, header size on partial success, or 0 on complete failure.

Definition at line 565 of file id3v2Parser.c.

◆ id3v2ParseFrameHeader()

uint32_t id3v2ParseFrameHeader ( uint8_t * in,
size_t inl,
uint8_t version,
Id3v2FrameHeader ** frameHeader,
uint32_t * frameSize )

Parses an ID3v2 frame header from a byte buffer.

Extracts and decodes frame header fields from binary data according to the ID3v2 specification. Returns the number of bytes consumed during parsing and creates a heap-allocated frame header structure. Supports version-specific parsing:

  • ID3v2.2: Reads 3-byte frame ID + 3-byte size with no flag bytes.
  • ID3v2.3: Reads 4-byte frame ID + 4-byte size + 2-byte flags. Status flags: tag alter preservation, file alter preservation, read-only. Format flags: compression (+4 bytes decompression size), encryption (+1 byte symbol), grouping (+1 byte identifier).
  • ID3v2.4: Reads 4-byte frame ID + 4-byte syncsafe size + 2-byte flags. Status flags: tag alter, file alter, read-only. Format flags: grouping (+1 byte), encryption (+1 byte), unsynchronisation, compression/data length (+syncsafe size).

The frameSize output represents the frame content size (excluding header). On success, caller must free the returned structure with id3v2DestroyFrameHeader. Returns 0 with NULL on complete failure, or partial byte count with appropriate NULL/non-NULL outputs on partial parsing success.

Parameters
in- Pointer to byte buffer containing frame header data.
inl- Size of input buffer in bytes.
version- ID3v2 version (ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4).
frameHeader- Output parameter receiving pointer to heap-allocated frame header structure, or NULL on failure.
frameSize- Output parameter receiving frame content size in bytes (excluding header), or 0 on failure.
Returns
uint32_t - Number of bytes read from buffer on success, 0 on complete failure, or partial byte count on partial success.

Definition at line 351 of file id3v2Parser.c.

◆ id3v2ParseTagFromBuffer()

Id3v2Tag * id3v2ParseTagFromBuffer ( uint8_t * in,
size_t inl,
HashTable * userPairs )

Parses a complete ID3v2 tag from a byte buffer, including header, optional extended header, and all frames.

Orchestrates the full tag parsing workflow by locating the "ID3" identifier, parsing headers, processing unsynchronisation if present, and iteratively parsing all frames using a multi-pass context resolution strategy. Returns a heap-allocated tag structure containing all successfully parsed components.

Parsing Process:

  1. Scans buffer to locate "ID3" magic number identifier
  2. Parses tag header (version, flags, size)
  3. If unsynchronisation flag set: strips $00 bytes following $FF
  4. If extended header flag set: parses version-specific extended header
  5. Iterates through frame data, parsing each frame using 4-pass context lookup

Frame Context Resolution (4-Pass System):

  • Pass 1: Exact frame ID match in default context mappings (e.g., "TIT2", "APIC")
  • Pass 2: Exact frame ID match in user-supplied custom mappings (userPairs parameter)
  • Pass 3: Generic frame type patterns - 'T' prefix (text frames), 'W' prefix (URL frames)
  • Pass 4: Fallback to generic binary context ('?') for unknown frame types

Parsing continues until all frames are extracted or an unrecoverable error occurs. On partial failure, returns a tag structure with successfully parsed frames. Returns NULL only on complete failure. Caller must free returned structure with id3v2DestroyTag.

Parameters
in- Pointer to byte buffer containing ID3v2 tag data (may include non-tag data before/after).
inl- Size of input buffer in bytes.
userPairs- Optional hash table mapping frame IDs to custom context lists (NULL for default mappings only).
Returns
Id3v2Tag* - Heap-allocated complete tag structure on success, partial tag on partial failure, or NULL on complete failure.

Definition at line 1001 of file id3v2Parser.c.

◆ id3v2ParseTagHeader()

uint32_t id3v2ParseTagHeader ( uint8_t * in,
size_t inl,
Id3v2TagHeader ** tagHeader,
uint32_t * tagSize )

Parses an ID3v2 tag header from a byte buffer (excluding extended header).

Extracts and validates the 10-byte tag header structure from binary data according to the ID3v2 specification. Verifies the "ID3" identifier and decodes version, flags, and tag size fields. Returns the number of bytes consumed and creates a heap-allocated tag header structure. The extended header is not parsed by this function - the returned structure has extendedHeader set to NULL.

Header format (10 bytes): "ID3" identifier (3 bytes) + major version (1) + minor version (1) + flags (1) + syncsafe tag size (4).

The tagSize output represents the total size of tag content (frames + extended header if present) excluding the 10-byte header itself. On success, caller must free the returned structure with id3v2DestroyTagHeader. Returns 0 with NULL tagHeader on complete failure. Returns ID3V2_TAG_ID_SIZE (3) with NULL tagHeader if magic number is invalid, indicating the buffer doesn't contain a valid ID3v2 tag.

Parameters
in- Pointer to byte buffer containing tag header data.
inl- Size of input buffer in bytes.
tagHeader- Output parameter receiving pointer to heap-allocated tag header structure, or NULL on failure.
tagSize- Output parameter receiving tag content size in bytes (excluding 10-byte header), or 0 on failure.
Returns
uint32_t - Number of bytes read on success, or 0 on complete failure.

Definition at line 250 of file id3v2Parser.c.