id3dev 26.01 An ID3 metadata library

Loading...
Searching...
No Matches
id3v2.h File Reference

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

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

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 *filename, Id3v2Tag *tag)
| Writes an ID3v2 tag to a file, creating, prepending, or replacing as needed.

## Detailed Description

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

Author
  Ewan Jones

Version
  2.0

Date
  2023-12-13 - 2026-01-25

Copyright
  Copyright (c) 2023 - 2026

Definition in file id3v2.h.

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