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"
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.
- Version
- 26.01
- Date
- 2024-04-12 - 2026-01-25
- Copyright
- Copyright (c) 2024 - 2026
Definition in file id3dev.c.
Function Documentation
◆ id3Compare()
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.
- Returns
- bool - true if structures are equal, false if different or either parameter is NULL.
◆ 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.
◆ 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.
◆ id3Copy()
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().
◆ id3Create()
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().
◆ 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.
◆ 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().
◆ 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).
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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:
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
◆ 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.
Variable Documentation
◆ id3PreferredStandard
|
static |
