TagLibSharp2 0.1.0

TagLibSharp2

A modern .NET library for reading and writing metadata in media files.

When to Use TagLibSharp2

Choose TagLibSharp2 if you need:

• MIT license (TagLib# is LGPL)
• Async I/O for high-throughput scenarios
• Modern .NET features (nullable types, Span<T>)
• Result-based error handling (no exceptions)

Choose TagLib# if you need:

• MP4/M4A, ASF/WMA, APE, or AIFF support (not yet implemented here)
• A battle-tested library used in production for years

See the Migration Guide for detailed comparison.

Features

• Modern .NET: Built for .NET 8+ with nullable reference types, Span<T>, and async support
• MIT License: Permissive licensing for all use cases
• Performance-First: Zero-allocation parsing with Span<T> and ArrayPool<T>
• Multi-Target: Supports .NET Standard 2.0/2.1, .NET 8.0, and .NET 10.0
• Format Support:
  • Audio: MP3 (ID3v1/ID3v2), FLAC, OGG Vorbis
  • Planned: WAV, MP4, MKV, JPEG/PNG/TIFF (EXIF/XMP)

Installation

dotnet add package TagLibSharp2

Or build from source:

git clone https://github.com/decriptor/TagLibSharp2.git
cd tagsharp
dotnet build

Quick Start

using TagLibSharp2.Mpeg;
using TagLibSharp2.Xiph;
using TagLibSharp2.Ogg;

// Read MP3 tags (prefers ID3v2, falls back to ID3v1)
var result = Mp3File.ReadFromFile("song.mp3");
if (result.IsSuccess)
{
    var mp3 = result.File!;
    Console.WriteLine($"{mp3.Title} by {mp3.Artist}");

    // Modify and save
    mp3.Title = "New Title";
    mp3.SaveToFile("song.mp3", File.ReadAllBytes("song.mp3"));
}

// FLAC and Ogg Vorbis work the same way
var flac = FlacFile.ReadFromFile("song.flac").File;
var ogg = OggVorbisFile.ReadFromFile("song.ogg").File;

// Async support for high-throughput scenarios
var asyncResult = await Mp3File.ReadFromFileAsync("song.mp3");

See the examples directory for more comprehensive usage patterns.

Building

git clone https://github.com/decriptor/TagLibSharp2.git
cd tagsharp
dotnet build
dotnet test

Project Status

This is a clean-room rewrite of media tagging functionality, designed from specifications rather than existing implementations.

Phase 1: Core Infrastructure ✅

• BinaryData (immutable binary data with Span<T> support)
• BinaryDataBuilder (mutable builder with ArrayPool integration)
• Multi-framework polyfills (netstandard2.0 through net10.0)
• Tag and Picture abstract base classes
• TagReadResult for error handling

Phase 2: ID3 Support ✅

• ID3v1/v1.1 reading and writing (id3.org specification)
• ID3v2.3/2.4 reading and writing (id3.org specification)
  • Text frames (TIT2, TPE1, TALB, TYER, TDRC, TCON, TRCK, TPE2, TPOS, TCOM, TBPM, TENC, TSSE, TIT1, TIT3, TPE4, TKEY, TMOO, TMED, TLAN)
  • Involved people frames (TIPL, TMCL, IPLS) for musician credits
  • Picture frames (APIC) with multiple picture types
  • Syncsafe integer handling, multiple text encodings
  • Extended header support

Phase 3: Xiph Formats ✅

• Vorbis Comments (xiph.org specification)
• FLAC metadata blocks (xiph.org specification)
  • StreamInfo, VorbisComment, Picture block support
• Ogg container support with CRC validation

Phase 4: I/O Abstraction ✅

• File system abstraction for testability
• Async file I/O support with cancellation
• Extended metadata: Composer, BPM, AlbumArtist, DiscNumber

Phase 5: File Writing & Media Properties ✅

• FLAC file write operations with atomic saves
• Media properties (duration, bitrate, sample rate, channels)
• ID3v2 Comment (COMM) frame support

Phase 6: Extended Metadata & High-Level APIs ✅

• ID3v2 TXXX (user-defined text) frames for custom metadata
• ReplayGain tag support (ID3v2 and Vorbis Comments)
• MusicBrainz ID support (ID3v2 and Vorbis Comments)
• Mp3File high-level API for unified ID3v1/ID3v2 access
• Ogg Vorbis file write operations
• Lyrics (USLT frame) with multi-language support
• UFID (Unique File Identifier) for MusicBrainz Recording IDs
• Extended properties: Conductor, Copyright, Compilation, TotalTracks/TotalDiscs, PerformersRole
• Encoding metadata: EncodedBy, EncoderSettings
• Track info: Grouping, Subtitle, Remixer, InitialKey, Mood, Language
• Release data: MediaType, Barcode, CatalogNumber
• Sort fields: ComposerSort
• Tagging metadata: DateTagged, Description, AmazonId
• Extended MusicBrainz: WorkId, DiscId, ReleaseStatus, ReleaseType, ReleaseCountry
• TagTypes flags enum for tag format identification
• Array properties: Performers[], AlbumArtists[], Composers[], Genres[]
• IPicture interface and Pictures[] property on base Tag class

Future

• Additional formats: WAV, MP4, MKV, EXIF

Documentation

• Migration Guide - Migrating from TagLib#
• Architecture Overview - Design principles and allocation behavior
• Core Types Reference - Complete API documentation
• Building Guide - Build instructions and requirements
• Examples - Working code samples

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

License

This project is licensed under the MIT License - see the LICENSE file for details.