A modern .NET library for reading and writing metadata in media files.
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, or APE support (not yet implemented here)
- A battle-tested library used in production for years
See the Migration Guide for detailed comparison.
- 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>andArrayPool<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, WAV (RIFF INFO/ID3v2), AIFF (ID3v2)
- Planned: MP4/M4A, ASF/WMA, APE, Opus, DSF
| Feature | MP3 | FLAC | Ogg Vorbis | WAV | AIFF |
|---|---|---|---|---|---|
| Read metadata | ✅ | ✅ | ✅ | ✅ | ✅ |
| Write metadata | ✅ | ✅ | ✅ | ✅ | ✅ |
| Audio properties | ✅ | ✅ | ✅ | ✅ | ✅ |
| Async I/O | ✅ | ✅ | ✅ | ✅ | ✅ |
| Album art | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
| ReplayGain | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
| MusicBrainz IDs | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
| Lyrics | ✅ | ✅² | ✅² | ✅¹ | ✅¹ |
| Performer roles | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
| BWF broadcast metadata | — | — | — | ✅ | — |
| Surround sound info | — | — | — | ✅³ | — |
¹ Via embedded ID3v2 tag ² Via Vorbis Comment LYRICS field ³ Via WAVEFORMATEXTENSIBLE (channel mask, valid bits per sample)
| Container | Native Tag | Alternative Tags | Priority |
|---|---|---|---|
| MP3 | ID3v2 | ID3v1 | ID3v2 preferred |
| FLAC | Vorbis Comment | — | Native only |
| Ogg Vorbis | Vorbis Comment | — | Native only |
| WAV | RIFF INFO | ID3v2, bext (BWF) | ID3v2 preferred |
| AIFF | ID3 chunk | — | Native only |
dotnet add package TagLibSharp2Or build from source:
git clone https://github.com/decriptor/TagLibSharp2.git
cd tagsharp
dotnet buildusing TagLibSharp2.Mpeg;
using TagLibSharp2.Xiph;
using TagLibSharp2.Ogg;
using TagLibSharp2.Riff;
using TagLibSharp2.Aiff;
// 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;
// WAV files support both RIFF INFO and ID3v2 tags
WavFile.TryParse(new BinaryData(File.ReadAllBytes("song.wav")), out var wav);
Console.WriteLine($"WAV: {wav.Title} - {wav.AudioProperties?.Duration}");
// AIFF files (read and write, includes audio properties)
AiffFile.TryParse(new BinaryData(File.ReadAllBytes("song.aiff")), out var aiff);
Console.WriteLine($"AIFF: {aiff.AudioProperties?.SampleRate}Hz");
aiff.Tag = new Id3v2Tag { Title = "Updated Title" };
aiff.SaveToFile("song.aiff");
// Async support for high-throughput scenarios
var asyncResult = await Mp3File.ReadFromFileAsync("song.mp3");See the examples directory for more comprehensive usage patterns.
git clone https://github.com/decriptor/TagLibSharp2.git
cd tagsharp
dotnet build
dotnet testThis is a clean-room rewrite of media tagging functionality, designed from specifications rather than existing implementations.
- BinaryData (immutable binary data with Span 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
- 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
- Vorbis Comments (xiph.org specification)
- FLAC metadata blocks (xiph.org specification)
- StreamInfo, VorbisComment, Picture block support
- Ogg container support with CRC validation
- File system abstraction for testability
- Async file I/O support with cancellation
- Extended metadata: Composer, BPM, AlbumArtist, DiscNumber
- FLAC file write operations with atomic saves
- Media properties (duration, bitrate, sample rate, channels)
- ID3v2 Comment (COMM) frame support
- 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
- RIFF container parsing with chunk navigation
- WAV format chunk (fmt) for audio properties
- RIFF INFO tags (INAM, IART, IPRD, etc.)
- ID3v2 chunk support in WAV files
- WAV file write operations
- FORM container parsing (IFF-style, big-endian)
- COMM chunk with 80-bit extended float sample rate
- SSND chunk detection
- ID3 chunk support for metadata
- AIFC (compressed) format detection
- ExtendedFloat utility for 80-bit IEEE 754
- AIFF file write operations with ID3v2 support
- FLAC metadata block preservation (SEEKTABLE, APPLICATION blocks)
- WAV chunk preservation (fact, cue, smpl and other chunks)
- All formats preserve unknown/unrecognized data during round-trip
- MP4/M4A (AAC/ALAC) with iTunes atoms
- Opus audio format
- DSF (DSD) format
- ASF/WMA format
- APE tags for WavPack/Musepack
- 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
Contributions are welcome! Please read the contributing guidelines before submitting PRs.
This project is licensed under the MIT License - see the LICENSE file for details.