ID3Handler 1.0.0

ID3Handler

A fully-featured .NET library for reading and writing ID3 tags in MP3 files. Supports ID3v1, ID3v1.1, ID3v2.2, ID3v2.3, and ID3v2.4 tag formats.

Features

• Read and write ID3v1 and ID3v1.1 tags
• Read and write ID3v2.2, ID3v2.3, and ID3v2.4 tags
• Support for common metadata: Title, Artist, Album, Year, Genre, Comment, Track Number
• Extended ID3v2 properties: Album Artist, Composer, Disc Number, Total Tracks, Total Discs, Lyrics
• Album artwork support with multiple image formats (JPEG, PNG, GIF, BMP, WebP)
• UTF-16 BOM handling for international characters
• Safe file operations using temporary files
• Flexible tag version control (upgrade, downgrade, or use both)
• Compatible with .NET Standard 2.0+ (.NET Framework 4.6.1+, .NET Core 2.0+, .NET 5+)

Installation

Install via NuGet Package Manager:

dotnet add package ID3Handler

Or via Package Manager Console:

Install-Package ID3Handler

Quick Start

Reading Tags

using ID3Handler;

// Load an MP3 file
var handler = new ID3TagsHandler("path/to/song.mp3");

// Read basic properties
Console.WriteLine($"Title: {handler.Title}");
Console.WriteLine($"Artist: {handler.Artist}");
Console.WriteLine($"Album: {handler.Album}");
Console.WriteLine($"Year: {handler.Year}");
Console.WriteLine($"Genre: {handler.Genre}");
Console.WriteLine($"Track: {handler.TrackNumber}");

// Check which tag versions are present
Console.WriteLine($"Has ID3v1: {handler.HasID3v1}");
Console.WriteLine($"Has ID3v2: {handler.HasID3v2}");
Console.WriteLine($"Version: {handler.Version}");

Writing Tags

using ID3Handler;

var handler = new ID3TagsHandler("path/to/song.mp3");

// Update basic properties
handler.Title = "New Title";
handler.Artist = "New Artist";
handler.Album = "New Album";
handler.Year = "2025";
handler.Genre = "Rock";
handler.TrackNumber = 5;

// Update extended ID3v2 properties
handler.AlbumArtist = "Various Artists";
handler.Composer = "John Doe";
handler.TotalTracks = 12;
handler.DiscNumber = 1;
handler.TotalDiscs = 2;
handler.Lyrics = "These are the lyrics...";

// Save changes
handler.Save();

Working with Album Art

using ID3Handler;

var handler = new ID3TagsHandler("path/to/song.mp3");

// Add album art from file (MIME type auto-detected)
handler.SetAlbumArtFromFile("path/to/cover.jpg");

// Or set album art manually
handler.AlbumArt = File.ReadAllBytes("path/to/cover.png");
handler.AlbumArtMimeType = "image/png";

// Save changes
handler.Save();

// Read album art
if (handler.AlbumArt != null)
{
    File.WriteAllBytes("extracted-cover.jpg", handler.AlbumArt);
    Console.WriteLine($"Album art MIME type: {handler.AlbumArtMimeType}");
}

Advanced Usage

Tag Version Control

var handler = new ID3TagsHandler("path/to/song.mp3");

// Upgrade to ID3v2 only (removes ID3v1)
handler.UpgradeToID3v2();
handler.Save();

// Downgrade to ID3v1 only (loses extended metadata!)
handler.DowngradeToID3v1();
handler.Save();

// Keep both versions in sync
handler.UseBothVersions();
handler.Save();

// Custom control over which versions to write
handler.SetWriteOptions(writeID3v2: true, writeID3v1: false);
handler.Save();

Batch Processing

using ID3Handler;

var musicFolder = @"C:\Music";
var files = Directory.GetFiles(musicFolder, "*.mp3", SearchOption.AllDirectories);

foreach (var file in files)
{
    try
    {
        var handler = new ID3TagsHandler(file);
        
        // Update all files in folder
        handler.AlbumArtist = "Various Artists";
        handler.Year = "2025";
        
        handler.Save();
        Console.WriteLine($"Updated: {Path.GetFileName(file)}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Error processing {file}: {ex.Message}");
    }
}

Remove All Tags

var handler = new ID3TagsHandler("path/to/song.mp3");

// Remove all ID3 tags
handler.RemoveAllTags();
handler.Save();

Supported Properties

Common Properties (ID3v1 and ID3v2)

• Title - Song title
• Artist - Artist name
• Album - Album name
• Year - Release year
• Genre - Music genre
• Comment - Comment text
• TrackNumber - Track number

Extended Properties (ID3v2 only)

• AlbumArtist - Album artist (for compilations)
• Composer - Song composer
• TotalTracks - Total tracks on album
• DiscNumber - Disc number (for multi-disc sets)
• TotalDiscs - Total discs in set
• Lyrics - Song lyrics
• AlbumArt - Album artwork (byte array)
• AlbumArtMimeType - MIME type of artwork

Tag Version Details

ID3v1 / ID3v1.1

• Fixed-length fields (30 bytes for Title/Artist/Album)
• Limited to ASCII/Latin-1 encoding
• 80 predefined genres
• ID3v1.1 adds track number support

ID3v2.2 / ID3v2.3 / ID3v2.4

• Variable-length frames
• Full Unicode support (UTF-16, UTF-8)
• Extended metadata support
• Binary data support (album art)
• ID3v2.4 uses synchsafe integers

Note: The library automatically handles version detection and uses the appropriate format for reading/writing.

Important Notes

File Safety: The library uses temporary files during save operations to prevent data loss. Original files are only replaced after successful write operations.

Data Loss Warning: Downgrading from ID3v2 to ID3v1 will truncate long text fields and lose extended metadata (album artist, composer, lyrics, album art, etc.).

Encoding: ID3v1 tags are limited to Latin-1 encoding. Use ID3v2 for international characters and full Unicode support.

Error Handling

try
{
    var handler = new ID3TagsHandler("path/to/song.mp3");
    handler.Title = "New Title";
    handler.Save();
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"File not found: {ex.Message}");
}
catch (IOException ex)
{
    Console.WriteLine($"IO error: {ex.Message}");
}
catch (Exception ex)
{
    Console.WriteLine($"Unexpected error: {ex.Message}");
}

Requirements

• .NET Standard 2.0 or higher
• Compatible with:
  • .NET Framework 4.6.1+
  • .NET Core 2.0+
  • .NET 5+
  • .NET 6+
  • .NET 7+
  • .NET 8+

License

MIT License - See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For bug reports and feature requests, please use the GitHub issue tracker.