Function implementation of ID3v2 tag operations including reading/writing metadata frames, tag serialization, and file I/O. More...

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "id3dependencies/ByteStream/include/byteStream.h"
#include "id3dependencies/ByteStream/include/byteUnicode.h"
#include "id3dependencies/ByteStream/include/byteInt.h"
#include "id3v2/id3v2.h"
#include "id3v2/id3v2Frame.h"
#include "id3v2/id3v2Parser.h"
#include "id3v2/id3v2Context.h"
#include "id3v2/id3v2TagIdentity.h"

Include dependency graph for id3v2.c:

Go to the source code of this file.

Functions
Id3v2Tag *	id3v2TagFromFile (const char *filename)
	Reads and parses an ID3v2 tag from a file.
Id3v2Tag *	id3v2CopyTag (const Id3v2Tag *toCopy)
	Creates a deep copy of an ID3v2 tag structure.
bool	id3v2CompareTag (Id3v2Tag tag1, Id3v2Tag tag2)
	Performs deep structural comparison of two ID3v2 tags for equality.
Id3v2Frame *	id3v2ReadFrameByID (const char id[ID3V2_FRAME_ID_MAX_SIZE], Id3v2Tag *tag)
	Searches for and returns a copy of the first frame matching the given ID.
int	id3v2RemoveFrameByID (const char id, Id3v2Tag tag)
	Locates and removes the first frame matching the given ID from a tag.
int	id3v2InsertTextFrame (const char id[ID3V2_FRAME_ID_MAX_SIZE], const uint8_t encoding, const char string, Id3v2Tag tag)
	Creates and inserts a new text frame with the specified encoding into a tag.
int	id3v2ReadTagVersion (const Id3v2Tag *tag)
	Retrieves the major version number from an ID3v2 tag.
char *	id3v2ReadTextFrameContent (const char id[ID3V2_FRAME_ID_MAX_SIZE], Id3v2Tag *tag)
	Extracts the text content from a text frame with the specified ID.
char *	id3v2ReadTitle (Id3v2Tag *tag)
	Extracts the title/song name from an ID3v2 tag.
char *	id3v2ReadArtist (Id3v2Tag *tag)
	Extracts the lead artist/performer from an ID3v2 tag.
char *	id3v2ReadAlbumArtist (Id3v2Tag *tag)
	Extracts the album artist/band/orchestra from an ID3v2 tag.
char *	id3v2ReadAlbum (Id3v2Tag *tag)
	Extracts the album name from an ID3v2 tag.
char *	id3v2ReadYear (Id3v2Tag *tag)
	Extracts the year from an ID3v2 tag.
char *	id3v2ReadGenre (Id3v2Tag *tag)
	Extracts the genre/content type from an ID3v2 tag.
char *	id3v2ReadTrack (Id3v2Tag *tag)
	Extracts the track number/position from an ID3v2 tag.
char *	id3v2ReadComposer (Id3v2Tag *tag)
	Extracts the composer from an ID3v2 tag.
char *	id3v2ReadDisc (Id3v2Tag *tag)
	Extracts the disc number/position from an ID3v2 tag.
char *	id3v2ReadLyrics (Id3v2Tag *tag)
	Extracts unsynchronised lyrics/text transcription from an ID3v2 tag.
char *	id3v2ReadComment (Id3v2Tag *tag)
	Extracts the comment text from an ID3v2 tag.
uint8_t *	id3v2ReadPicture (uint8_t type, const Id3v2Tag tag, size_t dataSize)
	Extracts picture/artwork data of a specific type from an ID3v2 tag.
int	id3v2WriteTextFrameContent (const char id[ID3V2_FRAME_ID_MAX_SIZE], const char string, Id3v2Tag tag)
	Writes UTF-8 text content to a text frame, creating it if necessary.
int	id3v2WriteTitle (const char title, Id3v2Tag tag)
	Writes the title/song name to an ID3v2 tag.
int	id3v2WriteArtist (const char artist, Id3v2Tag tag)
	Writes the lead artist/performer to an ID3v2 tag.
int	id3v2WriteAlbumArtist (const char albumArtist, Id3v2Tag tag)
	Writes the album artist/band/orchestra to an ID3v2 tag.
int	id3v2WriteAlbum (const char album, Id3v2Tag tag)
	Writes the album name to an ID3v2 tag.
int	id3v2WriteYear (const char year, Id3v2Tag tag)
	Writes the year to an ID3v2 tag.
int	id3v2WriteGenre (const char genre, Id3v2Tag tag)
	Writes the genre/content type to an ID3v2 tag.
int	id3v2WriteTrack (const char track, Id3v2Tag tag)
	Writes the track number/position to an ID3v2 tag.
int	id3v2WriteDisc (const char disc, Id3v2Tag tag)
	Writes a disc number to the appropriate disc number frame in a tag.
int	id3v2WriteComposer (const char composer, Id3v2Tag tag)
	Writes a composer name to the appropriate composer frame in a tag.
int	id3v2WriteLyrics (const char lyrics, Id3v2Tag tag)
	Writes lyrics to the appropriate unsynchronized lyrics frame in a tag.
int	id3v2WriteComment (const char comment, Id3v2Tag tag)
	Writes a comment to the appropriate comment frame in a tag.
int	id3v2WritePicture (uint8_t image, size_t imageSize, const char kind, uint8_t type, Id3v2Tag *tag)
	Writes a picture to the appropriate attached picture frame in a tag.
int	id3v2WritePictureFromFile (const char filename, const char kind, uint8_t type, Id3v2Tag *tag)
	Reads a picture from a file and writes it to the appropriate attached picture frame in a tag.
uint8_t *	id3v2TagSerialize (Id3v2Tag tag, size_t outl)
	Serializes an ID3v2 tag structure to its binary representation.
char *	id3v2TagToJSON (Id3v2Tag *tag)
	Serializes an ID3v2 tag structure to JSON format.
int	id3v2WriteTagToFile (const char filePath, Id3v2Tag tag)
	Writes an ID3v2 tag to a file, creating, prepending, or replacing as needed.

Detailed Description

Function implementation of ID3v2 tag operations including reading/writing metadata frames, tag serialization, and file I/O.

Author: Ewan Jones

Version: 26.01

Date: 2024-04-11 - 2026-01-25

Copyright: Copyright (c) 2024 - 2026

Definition in file id3v2.c.

Function Documentation

◆ id3v2CompareTag()

bool id3v2CompareTag	(	Id3v2Tag *	tag1,
		Id3v2Tag *	tag2 )

Performs deep structural comparison of two ID3v2 tags for equality.

Compares tag headers (version, flags), extended headers (if present), and frames in order. Returns false if tags differ in structure, metadata, or frame content/ordering.

Parameters

tag1	- First tag to compare.
tag2	- Second tag to compare.

Returns: true if tags are structurally identical, false if they differ or either is NULL.

Definition at line 89 of file id3v2.c.

◆ id3v2CopyTag()

Id3v2Tag * id3v2CopyTag ( const Id3v2Tag * toCopy )

Creates a deep copy of an ID3v2 tag structure.

Recursively duplicates the tag header, extended header (if present), and all frames. Returns NULL if the source tag or its header is invalid.

Parameters

toCopy - Source tag to duplicate.

Returns: Id3v2Tag* - Newly allocated deep copy on success, NULL if source is invalid. Caller must free with id3v2DestroyTag.

Definition at line 57 of file id3v2.c.

◆ id3v2InsertTextFrame()

int id3v2InsertTextFrame	(	const char	id[ID3V2_FRAME_ID_MAX_SIZE],
		const uint8_t	encoding,
		const char *	string,
		Id3v2Tag *	tag )

Creates and inserts a new text frame with the specified encoding into a tag.

Converts the input UTF-8 string to the target encoding, prepends BOM if needed, and adds appropriate padding for UTF-16. Returns false on validation failures, encoding conversion errors, or memory allocation failures without modifying the tag.

Parameters

id	- Frame ID string (max ID3V2_FRAME_ID_MAX_SIZE bytes).
encoding	- Target text encoding (0-3: ISO-8859-1, UTF-16, UTF-16BE, UTF-8).
string	- Null-terminated UTF-8 string to encode and insert.
tag	- Tag to insert the frame into.

Returns: int - 1 (true) if frame created and inserted successfully, 0 (false) on failure.

Definition at line 235 of file id3v2.c.

◆ id3v2ReadAlbum()

char * id3v2ReadAlbum ( Id3v2Tag * tag )

Extracts the album name from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TAL for v2.x, TALB for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no album frame exists.

Parameters

tag	- Tag to read the album from.

Returns: char* - Newly allocated album string on success, NULL if not found or invalid. Caller must free.

Definition at line 483 of file id3v2.c.

◆ id3v2ReadAlbumArtist()

char * id3v2ReadAlbumArtist ( Id3v2Tag * tag )

Extracts the album artist/band/orchestra from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TP2 for v2.x, TPE2 for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no album artist frame exists.

Parameters

tag	- Tag to read the album artist from.

Returns: char* - Newly allocated album artist string on success, NULL if not found or invalid. Caller must free.

Definition at line 454 of file id3v2.c.

◆ id3v2ReadArtist()

char * id3v2ReadArtist ( Id3v2Tag * tag )

Extracts the lead artist/performer from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TP1 for v2.x, TPE1 for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no artist frame exists.

Parameters

tag	- Tag to read the artist from.

Returns: char* - Newly allocated artist string on success, NULL if not found or invalid. Caller must free.

Definition at line 425 of file id3v2.c.

◆ id3v2ReadComment()

char * id3v2ReadComment ( Id3v2Tag * tag )

Extracts the comment text from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (COM for v2.x, COMM for v3.x/v4.x). Validates frame structure (4 contexts/entries: encoding, language, short description, comment text) and extracts the comment content. Returns NULL if the tag is invalid, version is unsupported, frame not found, or structure is invalid.

Parameters

tag	- Tag to read the comment from.

Returns: char* - Newly allocated comment string on success, NULL if not found or invalid. Caller must free.

Definition at line 727 of file id3v2.c.

◆ id3v2ReadComposer()

char * id3v2ReadComposer ( Id3v2Tag * tag )

Extracts the composer from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TCM for v2.x, TCOM for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no composer frame exists.

Parameters

tag	- Tag to read the composer from.

Returns: char* - Newly allocated composer string on success, NULL if not found or invalid. Caller must free.

Definition at line 599 of file id3v2.c.

◆ id3v2ReadDisc()

char * id3v2ReadDisc ( Id3v2Tag * tag )

Extracts the disc number/position from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TPA for v2.x, TPOS for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no disc frame exists.

Parameters

tag	- Tag to read the disc number from.

Returns: char* - Newly allocated disc string on success, NULL if not found or invalid. Caller must free.

Definition at line 628 of file id3v2.c.

◆ id3v2ReadFrameByID()

Id3v2Frame * id3v2ReadFrameByID	(	const char	id[ID3V2_FRAME_ID_MAX_SIZE],
		Id3v2Tag *	tag )

Searches for and returns a copy of the first frame matching the given ID.

Traverses frames in order, comparing IDs up to the null terminator or ID3V2_FRAME_ID_MAX_SIZE. Returns NULL if no matching frame exists or inputs are invalid.

Parameters

id	- Frame ID string to search for (max ID3V2_FRAME_ID_MAX_SIZE bytes).
tag	- Tag to search within.

Returns: Id3v2Frame* - Deep copy of first matching frame on success, NULL if not found. Caller must free with id3v2DestroyFrame.

Definition at line 173 of file id3v2.c.

◆ id3v2ReadGenre()

char * id3v2ReadGenre ( Id3v2Tag * tag )

Extracts the genre/content type from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TCO for v2.x, TCON for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no genre frame exists.

Parameters

tag	- Tag to read the genre from.

Returns: char* - Newly allocated genre string on success, NULL if not found or invalid. Caller must free.

Definition at line 541 of file id3v2.c.

◆ id3v2ReadLyrics()

char * id3v2ReadLyrics ( Id3v2Tag * tag )

Extracts unsynchronised lyrics/text transcription from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (ULT for v2.x, USLT for v3.x/v4.x). Validates frame structure (4 contexts/entries: encoding, language, content descriptor, lyrics text) and extracts the lyrics content. Returns NULL if the tag is invalid, version is unsupported, frame not found, or frame structure is invalid.

Parameters

tag	- Tag to read the lyrics from.

Returns: char* - Newly allocated lyrics string on success, NULL if not found or invalid. Caller must free.

Definition at line 658 of file id3v2.c.

◆ id3v2ReadPicture()

uint8_t * id3v2ReadPicture	(	uint8_t	type,
		const Id3v2Tag *	tag,
		size_t *	dataSize )

Extracts picture/artwork data of a specific type from an ID3v2 tag.

Searches for picture frames (PIC/APIC) matching the requested picture type, traversing all frames until a match is found. Clamps invalid type values to 0x00 (Other). Returns NULL if no matching picture exists or tag is invalid.

Parameters

type	- Picture type to search for.
tag	- Tag to search for picture data.
dataSize	- Output parameter receiving the size of the picture data in bytes, set to 0 on failure.

Returns: uint8_t* - Newly allocated binary picture data on success, NULL if not found. Caller must free.

Definition at line 797 of file id3v2.c.

◆ id3v2ReadTagVersion()

int id3v2ReadTagVersion ( const Id3v2Tag * tag )

Retrieves the major version number from an ID3v2 tag.

Extracts the major version field from the tag header (e.g., 3 for ID3v2.3, 4 for ID3v2.4). Returns -1 if the tag or header is invalid.

Parameters

tag	- Tag to query for version information.

Returns: int - Major version number (2-4) on success, -1 if tag or header is NULL.

Definition at line 316 of file id3v2.c.

◆ id3v2ReadTextFrameContent()

char * id3v2ReadTextFrameContent	(	const char	id[ID3V2_FRAME_ID_MAX_SIZE],
		Id3v2Tag *	tag )

Extracts the text content from a text frame with the specified ID.

Locates the frame, validates its structure (2 contexts/entries: numeric encoding + encoded string), decodes the text content, and returns it as a newly allocated string. Returns NULL if frame is not found, has invalid structure, or is not a text frame type.

Parameters

id	- Frame ID string to search for (max ID3V2_FRAME_ID_MAX_SIZE bytes).
tag	- Tag to search within.

Returns: char* - Newly allocated decoded text content on success, NULL if frame not found or invalid. Caller must free.

Definition at line 337 of file id3v2.c.

◆ id3v2ReadTitle()

char * id3v2ReadTitle ( Id3v2Tag * tag )

Extracts the title/song name from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TT2 for v2.x, TIT2 for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no title frame exists.

Parameters

tag	- Tag to read the title from.

Returns: char* - Newly allocated title string on success, NULL if not found or invalid. Caller must free.

Definition at line 396 of file id3v2.c.

◆ id3v2ReadTrack()

char * id3v2ReadTrack ( Id3v2Tag * tag )

Extracts the track number/position from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TRK for v2.x, TRCK for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no track frame exists.

Parameters

tag	- Tag to read the track number from.

Returns: char* - Newly allocated track string on success, NULL if not found or invalid. Caller must free.

Definition at line 570 of file id3v2.c.

◆ id3v2ReadYear()

char * id3v2ReadYear ( Id3v2Tag * tag )

Extracts the year from an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TYE for v2.x, TYER for v3.x/v4.x). Returns NULL if the tag is invalid, version is unsupported, or no year frame exists.

Parameters

tag	- Tag to read the year from.

Returns: char* - Newly allocated year string on success, NULL if not found or invalid. Caller must free.

Definition at line 512 of file id3v2.c.

◆ id3v2RemoveFrameByID()

int id3v2RemoveFrameByID	(	const char *	id,
		Id3v2Tag *	tag )

Locates and removes the first frame matching the given ID from a tag.

Searches for a frame with the specified ID, detaches it from the tag's frame list, and frees associated memory. Only removes the first occurrence if multiple frames share the same ID.

Parameters

id	- Frame ID string to search for.
tag	- Tag to remove the frame from.

Returns: int - 1 if a frame was found and removed, 0 if no matching frame exists.

Definition at line 208 of file id3v2.c.

◆ id3v2TagFromFile()

Id3v2Tag * id3v2TagFromFile ( const char * filename )

Reads and parses an ID3v2 tag from a file.

Loads file contents into memory, parses the ID3v2 tag structure, and cleans up temporary resources. Returns NULL on any failure (invalid filename, file I/O error, or parse error).

Parameters

filename - Path to the file containing an ID3v2 tag.

Returns: Id3v2Tag* - Newly allocated tag on success, NULL on failure. Caller must free with id3v2DestroyTag.

Definition at line 31 of file id3v2.c.

◆ id3v2TagSerialize()

uint8_t * id3v2TagSerialize	(	Id3v2Tag *	tag,
		size_t *	outl )

Serializes an ID3v2 tag structure to its binary representation.

Converts the tag back to raw bytes by serializing all frames, applying unsynchronization if enabled, encoding the header and optional footer, calculating total size (including padding from extended header), and combining all components into a single binary buffer. For ID3v2.4 tags with footer indicator set, generates a footer (10-byte header copy with "3DI" identifier). Unsynchronization doubles buffer size to accommodate potential expansion. Size fields are encoded as synchsafe integers. Returns NULL on validation failures (null tag/header/frames, frame serialization errors, or header serialization errors) and sets outl to 0 without allocating memory.

Parameters

tag	- Tag structure to serialize.
outl	- Pointer to size_t to receive the output buffer size in bytes.

Returns: uint8_t* - Pointer to allocated binary data on success, NULL on failure. Caller must free the returned buffer.

Definition at line 1984 of file id3v2.c.

◆ id3v2TagToJSON()

char * id3v2TagToJSON ( Id3v2Tag * tag )

Serializes an ID3v2 tag structure to JSON format.

Converts the tag header and all frames to JSON representation. Returns "{}" for invalid tags (null parameters, null frames/header, or unsupported version > ID3v2.4). For valid tags, serializes the header and each frame, concatenates frame JSON with commas, and constructs a JSON object with "header" and "content" array. Allocates and returns a null-terminated JSON string. Frees all intermediate allocations on both success and failure paths.

Parameters

tag	- Tag structure to serialize to JSON.

Returns: char* - Pointer to allocated null-terminated JSON string. Caller must free the returned buffer.

Example output:

{
  "header": {
     ...
  },
  "content": [
     ...
  ]
}

Invalid tag returns:

{}

Definition at line 2184 of file id3v2.c.

◆ id3v2WriteAlbum()

int id3v2WriteAlbum	(	const char *	album,
		Id3v2Tag *	tag )

Writes the album name to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TAL for v2.x, TALB for v3.x/v4.x). Creates a new album frame if none exists, or updates existing frame content.

Parameters

album	- Null-terminated UTF-8 album string to write.
tag	- Tag to write the album into.

Returns: int - 1 (true) if album written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 1025 of file id3v2.c.

◆ id3v2WriteAlbumArtist()

int id3v2WriteAlbumArtist	(	const char *	albumArtist,
		Id3v2Tag *	tag )

Writes the album artist/band/orchestra to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TP2 for v2.x, TPE2 for v3.x/v4.x). Creates a new album artist frame if none exists, or updates existing frame content.

Parameters

albumArtist	- Null-terminated UTF-8 album artist string to write.
tag	- Tag to write the album artist into.

Returns: int - 1 (true) if album artist written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 999 of file id3v2.c.

◆ id3v2WriteArtist()

int id3v2WriteArtist	(	const char *	artist,
		Id3v2Tag *	tag )

Writes the lead artist/performer to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TP1 for v2.x, TPE1 for v3.x/v4.x). Creates a new artist frame if none exists, or updates existing frame content.

Parameters

artist	- Null-terminated UTF-8 artist string to write.
tag	- Tag to write the artist into.

Returns: int - 1 (true) if artist written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 973 of file id3v2.c.

◆ id3v2WriteComment()

int id3v2WriteComment	(	const char *	comment,
		Id3v2Tag *	tag )

Writes a comment to the appropriate comment frame in a tag.

Updates the first comment frame (COM for ID3v2.2, COMM for ID3v2.3/2.4) with the provided comment string. If no comment frame exists, creates a new UTF-16LE frame with language code "zxx" (unknown language) and empty description. If a frame exists, validates its structure (4 contexts/entries with correct types), converts the UTF-8 input to the frame's encoding, prepends BOM if needed, and adds padding for UTF-16. Returns false on validation failures (null parameters, empty string, invalid frame structure, encoding conversion errors, or memory allocation failures) without modifying the tag.

Parameters

comment	- Null-terminated UTF-8 string containing the comment text (must not be empty).
tag	- Tag to update with the comment.

Returns: int - 1 (true) if comment written successfully, 0 (false) on failure.

Definition at line 1553 of file id3v2.c.

◆ id3v2WriteComposer()

int id3v2WriteComposer	(	const char *	composer,
		Id3v2Tag *	tag )

Writes a composer name to the appropriate composer frame in a tag.

Updates the first composer frame (TCM for ID3v2.2, TCOM for ID3v2.3/2.4) with the provided composer string. Returns false on validation failures (null parameters or unsupported tag version) without modifying the tag.

Parameters

composer	- Null-terminated string containing the composer name.
tag	- Tag to update with the composer name.

Returns: int - 1 (true) if composer written successfully, 0 (false) on failure.

Definition at line 1155 of file id3v2.c.

◆ id3v2WriteDisc()

int id3v2WriteDisc	(	const char *	disc,
		Id3v2Tag *	tag )

Writes a disc number to the appropriate disc number frame in a tag.

Updates the first disc number frame (TPA for ID3v2.2, TPOS for ID3v2.3/2.4) with the provided disc string. Returns false on validation failures (null parameters or unsupported tag version) without modifying the tag.

Parameters

disc	- Null-terminated string containing the disc number (e.g., "1", "1/2").
tag	- Tag to update with the disc number.

Returns: int - 1 (true) if disc number written successfully, 0 (false) on failure.

Definition at line 1129 of file id3v2.c.

◆ id3v2WriteGenre()

int id3v2WriteGenre	(	const char *	genre,
		Id3v2Tag *	tag )

Writes the genre/content type to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TCO for v2.x, TCON for v3.x/v4.x). Creates a new genre frame if none exists, or updates existing frame content.

Parameters

genre	- Null-terminated UTF-8 genre string to write.
tag	- Tag to write the genre into.

Returns: int - 1 (true) if genre written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 1077 of file id3v2.c.

◆ id3v2WriteLyrics()

int id3v2WriteLyrics	(	const char *	lyrics,
		Id3v2Tag *	tag )

Writes lyrics to the appropriate unsynchronized lyrics frame in a tag.

Updates the first unsynchronized lyrics frame (ULT for ID3v2.2, USLT for ID3v2.3/2.4) with the provided lyrics string. If no lyrics frame exists, creates a new UTF-16LE frame. If a frame exists, validates its structure (4 contexts/entries with correct types), converts the UTF-8 input to the frame's encoding, prepends BOM if needed, and adds padding for UTF-16. Returns false on validation failures (null parameters, empty string, invalid frame structure, encoding conversion errors, or memory allocation failures) without modifying the tag.

Parameters

lyrics	- Null-terminated UTF-8 string containing the lyrics text (must not be empty).
tag	- Tag to update with the lyrics.

Returns: int - 1 (true) if lyrics written successfully, 0 (false) on failure.

Definition at line 1290 of file id3v2.c.

◆ id3v2WritePicture()

int id3v2WritePicture	(	uint8_t *	image,
		size_t	imageSize,
		const char *	kind,
		uint8_t	type,
		Id3v2Tag *	tag )

Writes a picture to the appropriate attached picture frame in a tag.

Updates the first picture frame (PIC for ID3v2.2, APIC for ID3v2.3/2.4) that matches the specified picture type. If no matching frame exists, creates a new UTF-16LE frame with type 0. For ID3v2.2, writes up to 3 characters of kind as the image format; for ID3v2.3/2.4, prepends "image/" to kind as the MIME type. Validates frame structure (5 contexts/entries with correct types). Picture type values are clamped to the valid range (0x00-0x14). Returns false on validation failures (null parameters, zero imageSize, empty kind string, invalid frame structure, or write errors) without modifying the tag.

Parameters

image	- Pointer to the binary image data to write.
imageSize	- Size of the image data in bytes (must be greater than 0).
kind	- Null-terminated string specifying image format (e.g., "jpeg", "png") used as MIME type suffix (must not be empty).
type	- Picture type value (0x00-0x14, values above 0x14 are clamped to 0x00).
tag	- Tag to update with the picture.

Returns: int - 1 (true) if picture written successfully, 0 (false) on failure.

Definition at line 1794 of file id3v2.c.

◆ id3v2WritePictureFromFile()

int id3v2WritePictureFromFile	(	const char *	filename,
		const char *	kind,
		uint8_t	type,
		Id3v2Tag *	tag )

Reads a picture from a file and writes it to the appropriate attached picture frame in a tag.

Loads binary image data from the specified file and delegates to id3v2WritePicture to update the first picture frame (PIC for ID3v2.2, APIC for ID3v2.3/2.4) matching the specified picture type. If no matching frame exists, creates a new UTF-16LE frame with type 0. For ID3v2.2, writes up to 3 characters of kind as the image format; for ID3v2.3/2.4, prepends "image/" to kind as the MIME type. Returns false on validation failures (null parameters, empty strings, file open/read errors, or frame write errors) without modifying the tag. Frees allocated memory on all paths.

Parameters

filename	- Null-terminated string containing the path to the image file to read (must not be empty).
kind	- Null-terminated string specifying image format (e.g., "jpeg", "png") used as MIME type suffix (must not be empty).
type	- Picture type value (0x00-0x14, values above 0x14 are clamped to 0x00).
tag	- Tag to update with the picture.

Returns: int - 1 (true) if picture read and written successfully, 0 (false) on failure.

Definition at line 1932 of file id3v2.c.

◆ id3v2WriteTagToFile()

int id3v2WriteTagToFile	(	const char *	filePath,
		Id3v2Tag *	tag )

Writes an ID3v2 tag to a file, creating, prepending, or replacing as needed.

Serializes the tag and handles three scenarios: (1) If file doesn't exist, creates it and writes the tag; (2) If file exists without a tag or with the update flag set in the extended header, prepends the new tag to the file; (3) If file exists with a tag and no update flag, replaces the old tag by reading existing tag size, writing new tag at file start, and appending remaining file data. Accounts for footer (10 bytes for ID3v2.4) and padding from extended header when calculating offsets. Returns false on validation failures (null parameters, serialization errors, file open/read/write errors, or memory allocation failures) without modifying the file. Frees all allocated memory on both success and failure paths.

Parameters

filePath	- Null-terminated string containing the path to the file to write.
tag	- Tag structure to write to the file.

Returns: int - 1 (true) if tag written successfully, 0 (false) on failure.

Definition at line 2317 of file id3v2.c.

◆ id3v2WriteTextFrameContent()

int id3v2WriteTextFrameContent	(	const char	id[ID3V2_FRAME_ID_MAX_SIZE],
		const char *	string,
		Id3v2Tag *	tag )

Writes UTF-8 text content to a text frame, creating it if necessary.

Searches for an existing text frame with the specified ID. If found, converts the input string to the frame's existing encoding and updates the content. If not found, creates a new text frame with UTF16LE encoding. Handles BOM prepending and UTF-16 padding automatically. Returns false on validation failures, conversion errors, or write failures.

Parameters

id	- Frame ID string to write to (max ID3V2_FRAME_ID_MAX_SIZE bytes).
string	- Null-terminated UTF-8 string to write.
tag	- Tag to write the frame content into.

Returns: int - 1 (true) if content written successfully, 0 (false) on failure.

Definition at line 836 of file id3v2.c.

◆ id3v2WriteTitle()

int id3v2WriteTitle	(	const char *	title,
		Id3v2Tag *	tag )

Writes the title/song name to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TT2 for v2.x, TIT2 for v3.x/v4.x). Creates a new title frame if none exists, or updates existing frame content.

Parameters

title	- Null-terminated UTF-8 title string to write.
tag	- Tag to write the title into.

Returns: int - 1 (true) if title written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 947 of file id3v2.c.

◆ id3v2WriteTrack()

int id3v2WriteTrack	(	const char *	track,
		Id3v2Tag *	tag )

Writes the track number/position to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TRK for v2.x, TRCK for v3.x/v4.x). Creates a new track frame if none exists, or updates existing frame content.

Parameters

track	- Null-terminated UTF-8 track string to write.
tag	- Tag to write the track number into.

Returns: int - 1 (true) if track written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 1103 of file id3v2.c.

◆ id3v2WriteYear()

int id3v2WriteYear	(	const char *	year,
		Id3v2Tag *	tag )

Writes the year to an ID3v2 tag.

Automatically selects the appropriate frame ID based on tag version (TYE for v2.x, TYER for v3.x/v4.x). Creates a new year frame if none exists, or updates existing frame content.

Parameters

year	- Null-terminated UTF-8 year string to write.
tag	- Tag to write the year into.

Returns: int - 1 (true) if year written successfully, 0 (false) if inputs invalid or version unsupported.

Definition at line 1051 of file id3v2.c.

Functions

Detailed Description

Function Documentation

◆ id3v2CompareTag()

◆ id3v2CopyTag()

◆ id3v2InsertTextFrame()

◆ id3v2ReadAlbum()

◆ id3v2ReadAlbumArtist()

◆ id3v2ReadArtist()

◆ id3v2ReadComment()

◆ id3v2ReadComposer()

◆ id3v2ReadDisc()

◆ id3v2ReadFrameByID()

◆ id3v2ReadGenre()

◆ id3v2ReadLyrics()

◆ id3v2ReadPicture()

◆ id3v2ReadTagVersion()

◆ id3v2ReadTextFrameContent()

◆ id3v2ReadTitle()

◆ id3v2ReadTrack()

◆ id3v2ReadYear()

◆ id3v2RemoveFrameByID()

◆ id3v2TagFromFile()

◆ id3v2TagSerialize()

◆ id3v2TagToJSON()

◆ id3v2WriteAlbum()

◆ id3v2WriteAlbumArtist()

◆ id3v2WriteArtist()

◆ id3v2WriteComment()

◆ id3v2WriteComposer()

◆ id3v2WriteDisc()

◆ id3v2WriteGenre()

◆ id3v2WriteLyrics()

◆ id3v2WritePicture()

◆ id3v2WritePictureFromFile()

◆ id3v2WriteTagToFile()

◆ id3v2WriteTextFrameContent()

◆ id3v2WriteTitle()

◆ id3v2WriteTrack()

◆ id3v2WriteYear()