id3dev 26.01 An ID3 metadata library

Loading...
Searching...
No Matches
id3dev.c File Reference

Function implementations for reading, writing, converting, and comparing ID3v1 and ID3v2 metadata tags. More...

`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include "id3dev.h"`
`#include "id3v2/id3v2.h"`
`#include "id3v1/id3v1.h"`
`#include "id3v1/id3v1Parser.h"`
`#include "id3v2/id3v2Frame.h"`
Include dependency graph for id3dev.c:

Go to the source code of this file.

## Functions
ID3 * | id3Create (Id3v2Tag *id3v2, Id3v1Tag *id3v1)
| Creates a new ID3 metadata structure containing ID3v2 and ID3v1 tags.
void | id3Destroy (ID3 **toDelete)
| Destroys an ID3 metadata structure and frees all associated memory.
bool | id3SetPreferredStandard (uint8_t standard)
| Sets the preferred ID3 standard for reading metadata from tag structures.
uint8_t | id3GetPreferredStandard (void)
| Returns the currently configured preferred ID3 standard.
ID3 * | id3FromFile (const char *filePath)
| Reads both ID3v1 and ID3v2 tags from a file into an ID3 metadata structure.
ID3 * | id3Copy (const ID3 *toCopy)
| Creates a deep copy of an ID3 metadata structure.
bool | id3Compare (const ID3 *metadata1, const ID3 *metadata2)
| Compares two ID3 metadata structures for equality.
bool | id3ConvertId3v1ToId3v2 (ID3 *metadata)
| Converts the ID3v1 tag to an ID3v2 tag within the metadata structure.
bool | id3ConvertId3v2ToId3v1 (ID3 *metadata)
| Converts the ID3v2 tag to an ID3v1 tag within the metadata structure.
char * | id3ReadTitle (const ID3 *metadata)
| Reads the title from an ID3 metadata structure using the preferred standard.
char * | id3ReadArtist (const ID3 *metadata)
| Reads the artist from an ID3 metadata structure using the preferred standard.
char * | id3ReadAlbumArtist (const ID3 *metadata)
| Reads the album artist from an ID3 metadata structure using the preferred standard.
char * | id3ReadAlbum (const ID3 *metadata)
| Reads the album from an ID3 metadata structure using the preferred standard.
char * | id3ReadYear (const ID3 *metadata)
| Reads the year from an ID3 metadata structure using the preferred standard.
char * | id3ReadGenre (const ID3 *metadata)
| Reads the genre from an ID3 metadata structure using the preferred standard.
char * | id3ReadTrack (const ID3 *metadata)
| Reads the track number from an ID3 metadata structure using the preferred standard.
char * | id3ReadComposer (const ID3 *metadata)
| Reads the composer from an ID3 metadata structure using the preferred standard.
char * | id3ReadDisc (const ID3 *metadata)
| Reads the disc number from an ID3 metadata structure using the preferred standard.
char * | id3ReadLyrics (const ID3 *metadata)
| Reads the lyrics from an ID3 metadata structure using the preferred standard.
char * | id3ReadComment (const ID3 *metadata)
| Reads the comment from an ID3 metadata structure using the preferred standard.
uint8_t * | id3ReadPicture (uint8_t type, const ID3 *metadata, size_t *dataSize)
| Reads a picture of the specified type from an ID3 metadata structure using the preferred standard.
int | id3WriteTitle (const char *title, ID3 *metadata)
| Writes a title to an ID3 metadata structure using the preferred standard.
int | id3WriteArtist (const char *artist, ID3 *metadata)
| Writes an artist to an ID3 metadata structure using the preferred standard.
int | id3WriteAlbumArtist (const char *albumArtist, ID3 *metadata)
| Writes an album artist to an ID3 metadata structure using the preferred standard.
int | id3WriteAlbum (const char *album, ID3 *metadata)
| Writes an album to an ID3 metadata structure using the preferred standard.
int | id3WriteYear (const char *year, ID3 *metadata)
| Writes a year to an ID3 metadata structure using the preferred standard.
int | id3WriteGenre (const char *genre, ID3 *metadata)
| Writes a genre to an ID3 metadata structure using the preferred standard.
int | id3WriteTrack (const char *track, ID3 *metadata)
| Writes a track number to an ID3 metadata structure using the preferred standard.
int | id3WriteDisc (const char *disc, ID3 *metadata)
| Writes a disc number to an ID3 metadata structure using the preferred standard.
int | id3WriteComposer (const char *composer, ID3 *metadata)
| Writes a composer to an ID3 metadata structure using the preferred standard.
int | id3WriteLyrics (const char *lyrics, ID3 *metadata)
| Writes lyrics to an ID3 metadata structure using the preferred standard.
int | id3WriteComment (const char *comment, ID3 *metadata)
| Writes a comment to an ID3 metadata structure using the preferred standard.
int | id3WritePicture (uint8_t *image, size_t imageSize, const char *kind, uint8_t type, ID3 *metadata)
| Writes a picture to an ID3 metadata structure using the preferred standard.
int | id3WritePictureFromFile (const char *filename, const char *kind, uint8_t type, ID3 *metadata)
| Writes a picture from a file to an ID3 metadata structure using the preferred standard.
char * | id3ToJSON (const ID3 *metadata)
| Converts an ID3 metadata structure to a JSON string.
int | id3WriteToFile (const char *filePath, const ID3 *metadata)
| Writes both ID3v1 and ID3v2 tags to a file using the given ID3 structure.

## Variables
static uint8_t | id3PreferredStandard = ID3V2_TAG_VERSION_3
| default standard for reading ID3 tags from a data structure representation.

## Detailed Description

Function implementations for reading, writing, converting, and comparing ID3v1 and ID3v2 metadata tags.

Author
  Ewan Jones

Version
  26.01

Date
  2024-04-12 - 2026-01-25

Copyright
  Copyright (c) 2024 - 2026

Definition in file id3dev.c.

## Function Documentation

## ◆ id3Compare()

bool id3Compare | ( | const ID3 * | metadata1,
|  | const ID3 * | metadata2 )

Compares two ID3 metadata structures for equality.

Compares both ID3v1 and ID3v2 tags within the structures. Two structures are considered equal if both their ID3v1 tags match (or both are NULL) AND both their ID3v2 tags match (or both are NULL). Returns false if either parameter is NULL or if the tags differ.

Parameters

  metadata1 | - First ID3 structure to compare.
  metadata2 | - Second ID3 structure to compare.

Returns
  bool - true if structures are equal, false if different or either parameter is NULL.

Definition at line 130 of file id3dev.c.

## ◆ id3ConvertId3v1ToId3v2()

bool id3ConvertId3v1ToId3v2 | ( | ID3 * | metadata | ) |

Converts the ID3v1 tag to an ID3v2 tag within the metadata structure.

Creates a new ID3v2 tag from the existing ID3v1 tag, copying all non-empty fields (title, artist, album, year, track, genre, comment). Uses the preferred standard to determine the ID3v2 version (2.2, 2.3, or 2.4), defaulting to ID3v2.3 if preferred standard is ID3v1. Numeric fields (year, track) are converted to strings. Genre is looked up from the ID3v1 genre table. If an ID3v2 tag already exists, it is destroyed and replaced. Returns false on validation failures (null metadata, null ID3v1 tag, or write errors), cleaning up all allocated memory. Does not modify the original ID3v1 tag.

Parameters

  metadata | - ID3 structure containing the ID3v1 tag to convert (id3v1 must not be NULL).

Returns
  bool - true if conversion successful and ID3v2 tag created, false on failure.

Definition at line 167 of file id3dev.c.

## ◆ id3ConvertId3v2ToId3v1()

bool id3ConvertId3v2ToId3v1 | ( | ID3 * | metadata | ) |

Converts the ID3v2 tag to an ID3v1 tag within the metadata structure.

Creates a new ID3v1 tag from the existing ID3v2 tag, reading and copying all common fields (title, artist, album, year, track, comment, genre). String fields from ID3v2 are converted to ID3v1 format: year and track are parsed as integers, with track parsing stripping leading zeros and extracting only the numeric portion before any delimiter. Genre uses the first character. Fields truncated to ID3v1 limits (30 bytes for most text fields). If an ID3v1 tag already exists, it is destroyed and replaced. Returns false on validation failures (null metadata or null ID3v2 tag). Does not modify the original ID3v2 tag. Frees all intermediate allocations.

Parameters

  metadata | - ID3 structure containing the ID3v2 tag to convert (id3v2 must not be NULL).

Returns
  bool - true if conversion successful and ID3v1 tag created, false on failure.

Definition at line 295 of file id3dev.c.

## ◆ id3Copy()

ID3 * id3Copy | ( | const ID3 * | toCopy | ) |

Creates a deep copy of an ID3 metadata structure.

Allocates a new ID3 structure and copies both ID3v1 and ID3v2 tags (if present). Returns NULL if the input is NULL. The returned copy is independent and must be freed with id3Destroy().

Parameters

  toCopy | - ID3 structure to copy, or NULL.

Returns
  ID3* - Pointer to allocated copy of the ID3 structure, or NULL if input was NULL. Caller must free with id3Destroy().

Definition at line 114 of file id3dev.c.

## ◆ id3Create()

ID3 * id3Create | ( | Id3v2Tag * | id3v2,
|  | Id3v1Tag * | id3v1 )

Creates a new ID3 metadata structure containing ID3v2 and ID3v1 tags.

Allocates and initializes an ID3 structure with the provided tag pointers. Both tags can be NULL to represent missing tags. The structure takes ownership of the provided tag pointers. Returns NULL if memory allocation fails.

Parameters

  id3v2 | - Pointer to an ID3v2 tag structure, or NULL if not present.
  id3v1 | - Pointer to an ID3v1 tag structure, or NULL if not present.

Returns
  ID3* - Pointer to allocated ID3 structure on success, NULL on allocation failure. Caller must free with id3Destroy().

Definition at line 35 of file id3dev.c.

## ◆ id3Destroy()

void id3Destroy | ( | ID3 ** | toDelete | ) |

Destroys an ID3 metadata structure and frees all associated memory.

Calls destroy functions for both ID3v2 and ID3v1 tags (if present), frees the ID3 structure itself, and sets the pointer to NULL. Safe to call with NULL pointer. After calling, the original pointer is invalidated.

Parameters

  toDelete | - Pointer to pointer to ID3 structure to destroy. Set to NULL after destruction.

Definition at line 50 of file id3dev.c.

## ◆ id3FromFile()

ID3 * id3FromFile | ( | const char * | filePath | ) |

Reads both ID3v1 and ID3v2 tags from a file into an ID3 metadata structure.

Attempts to read both ID3v2 (from file start) and ID3v1 (from file end) tags from the specified file. Always returns an ID3 structure, but individual tag pointers (id3v1, id3v2) will be NULL if not found or if read errors occur. The returned structure must be freed with id3Destroy().

Parameters

  filePath | - Null-terminated string containing the path to the file to read.

Returns
  ID3* - Pointer to allocated ID3 structure containing the read tags (tags may be NULL if not found). Caller must free with id3Destroy().

Definition at line 103 of file id3dev.c.

## ◆ id3GetPreferredStandard()

uint8_t id3GetPreferredStandard | ( | void |  | ) |

Returns the currently configured preferred ID3 standard.

Retrieves the ID3 version constant that is currently set for reading metadata from tag structures. Default value is ID3v2.3 unless changed via id3SetPreferredStandard().

Returns
  uint8_t - ID3 version constant (ID3V1_TAG_VERSION, ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4).

Definition at line 90 of file id3dev.c.

## ◆ id3ReadAlbum()

char * id3ReadAlbum | ( | const ID3 * | metadata | ) |

Reads the album from an ID3 metadata structure using the preferred standard.

Retrieves the album from either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the album field is not found.

Parameters

  metadata | - ID3 structure to read the album from.

Returns
  char* - Pointer to allocated null-terminated string containing the album, or NULL if not found. Caller must free the returned string.

Definition at line 509 of file id3dev.c.

## ◆ id3ReadAlbumArtist()

char * id3ReadAlbumArtist | ( | const ID3 * | metadata | ) |

Reads the album artist from an ID3 metadata structure using the preferred standard.

Retrieves the album artist from the ID3v2 tag only, as this field is not available in ID3v1. Returns NULL if metadata is NULL, no ID3v2 tag is present (regardless of preferred standard), or the album artist field is not found. Always returns NULL when only ID3v1 is available.

Parameters

  metadata | - ID3 structure to read the album artist from.

Returns
  char* - Pointer to allocated null-terminated string containing the album artist, or NULL if not found or ID3v2 not available. Caller must free the returned string.

Definition at line 479 of file id3dev.c.

## ◆ id3ReadArtist()

char * id3ReadArtist | ( | const ID3 * | metadata | ) |

Reads the artist from an ID3 metadata structure using the preferred standard.

Retrieves the artist from either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the artist field is not found.

Parameters

  metadata | - ID3 structure to read the artist from.

Returns
  char* - Pointer to allocated null-terminated string containing the artist, or NULL if not found. Caller must free the returned string.

Definition at line 448 of file id3dev.c.

## ◆ id3ReadComment()

char * id3ReadComment | ( | const ID3 * | metadata | ) |

Reads the comment from an ID3 metadata structure using the preferred standard.

Retrieves the comment from either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the comment field is not found.

Parameters

  metadata | - ID3 structure to read the comment from.

Returns
  char* - Pointer to allocated null-terminated string containing the comment, or NULL if not found. Caller must free the returned string.

Definition at line 760 of file id3dev.c.

## ◆ id3ReadComposer()

char * id3ReadComposer | ( | const ID3 * | metadata | ) |

Reads the composer from an ID3 metadata structure using the preferred standard.

Retrieves the composer from the ID3v2 tag only, as this field is not available in ID3v1. Returns NULL if metadata is NULL, no ID3v2 tag is present (regardless of preferred standard), or the composer field is not found. Always returns NULL when only ID3v1 is available.

Parameters

  metadata | - ID3 structure to read the composer from.

Returns
  char* - Pointer to allocated null-terminated string containing the composer, or NULL if not found or ID3v2 not available. Caller must free the returned string.

Definition at line 670 of file id3dev.c.

## ◆ id3ReadDisc()

char * id3ReadDisc | ( | const ID3 * | metadata | ) |

Reads the disc number from an ID3 metadata structure using the preferred standard.

Retrieves the disc number from the ID3v2 tag only, as this field is not available in ID3v1. Returns NULL if metadata is NULL, no ID3v2 tag is present (regardless of preferred standard), or the disc field is not found. Always returns NULL when only ID3v1 is available.

Parameters

  metadata | - ID3 structure to read the disc number from.

Returns
  char* - Pointer to allocated null-terminated string containing the disc number, or NULL if not found or ID3v2 not available. Caller must free the returned string.

Definition at line 700 of file id3dev.c.

## ◆ id3ReadGenre()

char * id3ReadGenre | ( | const ID3 * | metadata | ) |

Reads the genre from an ID3 metadata structure using the preferred standard.

Retrieves the genre from either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, looks up the genre byte in the standard genre table and returns an allocated copy of the genre string. For ID3v2, returns the genre text frame content. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the genre field is not found.

Parameters

  metadata | - ID3 structure to read the genre from.

Returns
  char* - Pointer to allocated null-terminated string containing the genre, or NULL if not found. Caller must free the returned string.

Definition at line 585 of file id3dev.c.

## ◆ id3ReadLyrics()

char * id3ReadLyrics | ( | const ID3 * | metadata | ) |

Reads the lyrics from an ID3 metadata structure using the preferred standard.

Retrieves the lyrics from the ID3v2 tag only, as this field is not available in ID3v1. Returns NULL if metadata is NULL, no ID3v2 tag is present (regardless of preferred standard), or the lyrics field is not found. Always returns NULL when only ID3v1 is available.

Parameters

  metadata | - ID3 structure to read the lyrics from.

Returns
  char* - Pointer to allocated null-terminated string containing the lyrics, or NULL if not found or ID3v2 not available. Caller must free the returned string.

Definition at line 730 of file id3dev.c.

## ◆ id3ReadPicture()

uint8_t * id3ReadPicture | ( | uint8_t | type,
|  | const ID3 * | metadata,
|  | size_t * | dataSize )

Reads a picture of the specified type from an ID3 metadata structure using the preferred standard.

Retrieves binary picture data from the ID3v2 tag only, as pictures are not available in ID3v1. Searches for a picture frame matching the specified type (e.g., 0x03 for front cover, 0x04 for back cover). Returns NULL and sets dataSize to 0 if metadata is NULL, no ID3v2 tag is present (regardless of preferred standard), or no matching picture is found. Always returns NULL when only ID3v1 is available.

Parameters

  type | - Picture type byte (0x00-0x14) to search for (e.g., 0x03 for front cover).
  metadata | - ID3 structure to read the picture from.
  dataSize | - Pointer to size_t to receive the size of the returned picture data in bytes (set to 0 on failure).

Returns
  uint8_t* - Pointer to allocated binary picture data, or NULL if not found or ID3v2 not available. Caller must free the returned buffer.

Definition at line 794 of file id3dev.c.

## ◆ id3ReadTitle()

char * id3ReadTitle | ( | const ID3 * | metadata | ) |

Reads the title from an ID3 metadata structure using the preferred standard.

Retrieves the title from either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the title field is not found.

Parameters

  metadata | - ID3 structure to read the title from.

Returns
  char* - Pointer to allocated null-terminated string containing the title, or NULL if not found. Caller must free the returned string.

Definition at line 417 of file id3dev.c.

## ◆ id3ReadTrack()

char * id3ReadTrack | ( | const ID3 * | metadata | ) |

Reads the track number from an ID3 metadata structure using the preferred standard.

Retrieves the track number from either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, converts the numeric track field to an allocated string. For ID3v2, returns the track text frame content (may include format like "track/total"). If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the track field is not found.

Parameters

  metadata | - ID3 structure to read the track number from.

Returns
  char* - Pointer to allocated null-terminated string containing the track number, or NULL if not found. Caller must free the returned string.

Definition at line 628 of file id3dev.c.

## ◆ id3ReadYear()

char * id3ReadYear | ( | const ID3 * | metadata | ) |

Reads the year from an ID3 metadata structure using the preferred standard.

Retrieves the year from either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, converts the numeric year field to an allocated string. For ID3v2, returns the year text frame content. If the preferred tag is not available, falls back to the available tag. Returns NULL if both tags are missing, metadata is NULL, or the year field is not found.

Parameters

  metadata | - ID3 structure to read the year from.

Returns
  char* - Pointer to allocated null-terminated string containing the year, or NULL if not found. Caller must free the returned string.

Definition at line 541 of file id3dev.c.

## ◆ id3SetPreferredStandard()

bool id3SetPreferredStandard | ( | uint8_t | standard | ) |

Sets the preferred ID3 standard for reading metadata from tag structures.

Configures which ID3 version to prioritize when reading metadata from structures containing both ID3v1 and ID3v2 tags. Default is ID3v2.3 (widest adoption with most features). Accepts ID3v1, ID3v2.2, ID3v2.3, or ID3v2.4 version constants. Returns false for invalid version values without changing the current preference.

Parameters

  standard | - ID3 version constant (ID3V1_TAG_VERSION, ID3V2_TAG_VERSION_2, ID3V2_TAG_VERSION_3, or ID3V2_TAG_VERSION_4).

Returns
  bool - true if standard set successfully, false if invalid standard value provided.

Definition at line 68 of file id3dev.c.

## ◆ id3ToJSON()

char * id3ToJSON | ( | const ID3 * | metadata | ) |

Converts an ID3 metadata structure to a JSON string.

Serializes both the ID3v1 and ID3v2 tags (if present) to JSON and combines them into a single JSON object. Returns "{}" if the input metadata is NULL. The returned string is dynamically allocated and must be freed by the caller.

Parameters

  metadata | - ID3 structure to serialize to JSON, or NULL.

Returns
  char* - Pointer to allocated null-terminated JSON string, or "{}" if metadata is NULL. Caller must free the returned string.

Example output:

{
"ID3v1": { ... },
"ID3v2": { ... }
}

Definition at line 1271 of file id3dev.c.

## ◆ id3WriteAlbum()

int id3WriteAlbum | ( | const char * | album,
|  | ID3 * | metadata )

Writes an album to an ID3 metadata structure using the preferred standard.

Updates the album field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  album | - Null-terminated string containing the album to write.
  metadata | - ID3 structure to write the album to (must have at least one tag present).

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

Definition at line 925 of file id3dev.c.

## ◆ id3WriteAlbumArtist()

int id3WriteAlbumArtist | ( | const char * | albumArtist,
|  | ID3 * | metadata )

Writes an album artist to an ID3 metadata structure using the preferred standard.

Updates the album artist field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

Parameters

  albumArtist | - Null-terminated string containing the album artist to write.
  metadata | - ID3 structure to write the album artist to (must have ID3v2 tag present).

Returns
  int - 1 (true) if album artist written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 894 of file id3dev.c.

## ◆ id3WriteArtist()

int id3WriteArtist | ( | const char * | artist,
|  | ID3 * | metadata )

Writes an artist to an ID3 metadata structure using the preferred standard.

Updates the artist field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  artist | - Null-terminated string containing the artist to write.
  metadata | - ID3 structure to write the artist to (must have at least one tag present).

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

Definition at line 862 of file id3dev.c.

## ◆ id3WriteComment()

int id3WriteComment | ( | const char * | comment,
|  | ID3 * | metadata )

Writes a comment to an ID3 metadata structure using the preferred standard.

Updates the comment field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  comment | - Null-terminated string containing the comment to write.
  metadata | - ID3 structure to write the comment to (must have at least one tag present).

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

Definition at line 1166 of file id3dev.c.

## ◆ id3WriteComposer()

int id3WriteComposer | ( | const char * | composer,
|  | ID3 * | metadata )

Writes a composer to an ID3 metadata structure using the preferred standard.

Updates the composer field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

Parameters

  composer | - Null-terminated string containing the composer to write.
  metadata | - ID3 structure to write the composer to (must have ID3v2 tag present).

Returns
  int - 1 (true) if composer written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 1104 of file id3dev.c.

## ◆ id3WriteDisc()

int id3WriteDisc | ( | const char * | disc,
|  | ID3 * | metadata )

Writes a disc number to an ID3 metadata structure using the preferred standard.

Updates the disc number field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

Parameters

  disc | - Null-terminated string containing the disc number to write (e.g., "1", "1/2").
  metadata | - ID3 structure to write the disc number to (must have ID3v2 tag present).

Returns
  int - 1 (true) if disc number written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 1073 of file id3dev.c.

## ◆ id3WriteGenre()

int id3WriteGenre | ( | const char * | genre,
|  | ID3 * | metadata )

Writes a genre to an ID3 metadata structure using the preferred standard.

Updates the genre field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, uses the first byte of the genre string as a genre code (0-192 per standard genre table in id3v1Types.h), clamping values above PSYBIENT_GENRE to OTHER_GENRE. For ID3v2, writes the genre string directly. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  genre | - Null-terminated string containing the genre to write (first byte used as genre code for ID3v1: 0-192).
  metadata | - ID3 structure to write the genre to (must have at least one tag present).

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

Definition at line 995 of file id3dev.c.

## ◆ id3WriteLyrics()

int id3WriteLyrics | ( | const char * | lyrics,
|  | ID3 * | metadata )

Writes lyrics to an ID3 metadata structure using the preferred standard.

Updates the lyrics field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

Parameters

  lyrics | - Null-terminated string containing the lyrics to write.
  metadata | - ID3 structure to write the lyrics to (must have ID3v2 tag present).

Returns
  int - 1 (true) if lyrics written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 1135 of file id3dev.c.

## ◆ id3WritePicture()

int id3WritePicture | ( | uint8_t * | image,
|  | size_t | imageSize,
|  | const char * | kind,
|  | uint8_t | type,
|  | ID3 * | metadata )

Writes a picture to an ID3 metadata structure using the preferred standard.

Updates the picture field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

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).
  metadata | - ID3 structure to write the picture to (must have ID3v2 tag present).

Returns
  int - 1 (true) if picture written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 1201 of file id3dev.c.

## ◆ id3WritePictureFromFile()

int id3WritePictureFromFile | ( | const char * | filename,
|  | const char * | kind,
|  | uint8_t | type,
|  | ID3 * | metadata )

Writes a picture from a file to an ID3 metadata structure using the preferred standard.

Loads binary image data from the specified file and updates the picture field in the ID3v2 tag only, as this field is not available in ID3v1. Returns false on validation failures (null parameters, no ID3v2 tag present regardless of preferred standard, file read errors, or write errors) without modifying the metadata. Always returns false when only ID3v1 is available.

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).
  metadata | - ID3 structure to write the picture to (must have ID3v2 tag present).

Returns
  int - 1 (true) if picture read and written successfully, 0 (false) on failure or ID3v2 not available.

Definition at line 1234 of file id3dev.c.

## ◆ id3WriteTitle()

int id3WriteTitle | ( | const char * | title,
|  | ID3 * | metadata )

Writes a title to an ID3 metadata structure using the preferred standard.

Updates the title field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  title | - Null-terminated string containing the title to write.
  metadata | - ID3 structure to write the title to (must have at least one tag present).

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

Definition at line 830 of file id3dev.c.

## ◆ id3WriteToFile()

int id3WriteToFile | ( | const char * | filePath,
|  | const ID3 * | metadata )

Writes both ID3v1 and ID3v2 tags to a file using the given ID3 structure.

Updates existing tags or creates new ones as needed. Writes both tags if present; if only one tag is present, only that tag is written. Returns true if at least one tag is written successfully and the other is either also written or not present. Returns false on validation failures (null parameters, both tags missing, or write errors for all tags).

Parameters

  filePath | - Null-terminated string containing the path to the file to write.
  metadata | - ID3 structure containing the tags to write (must have at least one tag present).

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

Definition at line 1305 of file id3dev.c.

## ◆ id3WriteTrack()

int id3WriteTrack | ( | const char * | track,
|  | ID3 * | metadata )

Writes a track number to an ID3 metadata structure using the preferred standard.

Updates the track number field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, converts the track string to an integer using strtol and clamps the value to 0-255 (UINT8_MAX) range. For ID3v2, writes the track string directly (may include format like "track/total"). If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  track | - Null-terminated string containing the track number to write (must be parseable as integer for ID3v1, clamped to 0-255).
  metadata | - ID3 structure to write the track number to (must have at least one tag present).

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

Definition at line 1030 of file id3dev.c.

## ◆ id3WriteYear()

int id3WriteYear | ( | const char * | year,
|  | ID3 * | metadata )

Writes a year to an ID3 metadata structure using the preferred standard.

Updates the year field in either the ID3v1 or ID3v2 tag based on the preferred standard setting. For ID3v1, converts the year string to an integer using strtol. For ID3v2, writes the string directly. If the preferred tag is not available, falls back to the available tag. Returns false on validation failures (null parameters, both tags missing, or write errors) without modifying the metadata.

Parameters

  year | - Null-terminated string containing the year to write (must be parseable as integer for ID3v1).
  metadata | - ID3 structure to write the year to (must have at least one tag present).

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

Definition at line 958 of file id3dev.c.

## Variable Documentation

## ◆ id3PreferredStandard

uint8_t id3PreferredStandard = ID3V2_TAG_VERSION_3
| static

default standard for reading ID3 tags from a data structure representation.

Definition at line 25 of file id3dev.c.