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:
- 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, Ogg Opus, Ogg FLAC, WAV (RIFF INFO/ID3v2), AIFF (ID3v2), MP4/M4A (AAC/ALAC), ASF/WMA, DSF (DSD), DFF (DSDIFF), WavPack, Monkey's Audio (.ape), Musepack
| Feature | MP3 | FLAC | Ogg Vorbis | Ogg Opus | Ogg FLAC | WAV | AIFF | MP4/M4A | ASF/WMA | DSF | DFF | WavPack | APE | MPC |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Read metadata | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Write metadata | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅⁸ |
| Audio properties | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Async I/O | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Album art | ✅ | ✅ | ✅ | ✅ | ✅² | ✅¹ | ✅¹ | ✅ | ✅⁹ | ✅¹ | ✅¹ | ✅⁸ | ✅⁸ | ✅⁸ |
| ReplayGain | ✅ | ✅ | ✅ | ✅⁴ | ✅² | ✅¹ | ✅¹ | ✅⁵ | ✅⁹ | ✅¹ | ✅¹ | ✅⁸ | ✅⁸ | ✅⁸ |
| MusicBrainz IDs | ✅ | ✅ | ✅ | ✅ | ✅² | ✅¹ | ✅¹ | ✅ | ✅⁹ | ✅¹ | ✅¹ | ✅⁸ | ✅⁸ | ✅⁸ |
| Lyrics | ✅ | ✅² | ✅² | ✅² | ✅² | ✅¹ | ✅¹ | ✅ | ✅⁹ | ✅¹ | ✅¹ | ✅⁸ | ✅⁸ | ✅⁸ |
| Performer roles | ✅ | ✅ | ✅ | ✅ | ✅² | ✅¹ | ✅¹ | — | ✅⁹ | ✅¹ | ✅¹ | ✅⁸ | ✅⁸ | ✅⁸ |
| BWF broadcast metadata | — | — | — | — | — | ✅ | — | — | — | — | — | — | — | — |
| Surround sound info | — | — | — | — | — | ✅³ | — | ✅⁶ | — | ✅⁷ | ✅⁷ | — | — | — |
| DSD sample rates | — | — | — | — | — | — | — | — | — | ✅ | ✅ | — | — | — |
¹ Via embedded ID3v2 tag ² Via Vorbis Comment ³ Via WAVEFORMATEXTENSIBLE (channel mask, valid bits per sample) ⁴ Via R128 gain tags (RFC 7845) ⁵ Via iTunes ----:com.apple.iTunes:replaygain_* atoms ⁶ Via channel layout in stsd/esds ⁷ Via channel type in fmt chunk (Mono, Stereo, 5.1 surround) ⁸ Via APE tag ⁹ Via ASF Extended Content Description
| Container | Native Tag | Alternative Tags | Priority |
|---|---|---|---|
| MP3 | ID3v2 | ID3v1, APE | ID3v2 preferred |
| FLAC | Vorbis Comment | — | Native only |
| Ogg Vorbis | Vorbis Comment | — | Native only |
| Ogg Opus | Vorbis Comment | — | Native only |
| Ogg FLAC | Vorbis Comment | — | Native only |
| WAV | RIFF INFO | ID3v2, bext (BWF) | ID3v2 preferred |
| AIFF | ID3 chunk | — | Native only |
| MP4/M4A | iTunes atoms (ilst) | — | Native only |
| ASF/WMA | ASF Content Description | Extended Content Description | Native only |
| DSF | ID3v2 | — | Native only |
| DFF | ID3v2 | — | Native only |
| WavPack | APE tag | — | Native only |
| Monkey's Audio | APE tag | — | Native only |
| Musepack | APE tag | — | Native only |
dotnet add package TagLibSharp2Or build from source:
git clone https://github.com/decriptor/TagLibSharp2.git
cd tagsharp
dotnet buildusing TagLibSharp2.Core;
using TagLibSharp2.Mpeg;
using TagLibSharp2.Xiph;
using TagLibSharp2.Ogg;
using TagLibSharp2.Riff;
using TagLibSharp2.Aiff;
using TagLibSharp2.Mp4;
// Auto-detect format using MediaFile factory
var result = MediaFile.Read("song.m4a");
if (result.IsSuccess)
{
Console.WriteLine($"Format: {result.Format}");
Console.WriteLine($"{result.Tag?.Title} by {result.Tag?.Artist}");
}
// Read MP3 tags (prefers ID3v2, falls back to ID3v1)
var mp3Result = Mp3File.ReadFromFile("song.mp3");
if (mp3Result.IsSuccess)
{
var mp3 = mp3Result.File!;
Console.WriteLine($"{mp3.Title} by {mp3.Artist}");
// Modify and save
mp3.Title = "New Title";
mp3.SaveToFile("song.mp3", File.ReadAllBytes("song.mp3"));
}
// MP4/M4A files with iTunes metadata
var mp4Result = Mp4File.ReadFromFile("song.m4a");
if (mp4Result.IsSuccess)
{
var mp4 = mp4Result.File!;
Console.WriteLine($"{mp4.Title} - {mp4.Duration}");
Console.WriteLine($"Codec: {mp4.AudioCodec}, {mp4.Properties?.SampleRate}Hz");
}
// FLAC and Ogg Vorbis work the same way
var flac = FlacFile.ReadFromFile("song.flac").File;
var ogg = OggVorbisFile.ReadFromFile("song.ogg").File;
// Ogg Opus (RFC 7845) with R128 gain
var opusResult = OggOpusFile.ReadFromFile("song.opus");
var opus = opusResult.File;
Console.WriteLine($"Opus: {opus?.Properties?.Duration}, R128 gain: {opus?.Properties?.OutputGain}dB");
// WAV files support both RIFF INFO and ID3v2 tags
WavFile.TryRead(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.TryRead(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 Mp4File.ReadFromFileAsync("song.m4a");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
- OpusHead packet parsing (RFC 7845)
- R128 gain tags (output gain, album gain, track gain)
- Multi-stream support (mapping families 0, 1, 255)
- Stream/coupled count validation per RFC 7845
- ISO 14496-12 box parsing (ftyp, moov, mdat, etc.)
- iTunes-style metadata atoms (ilst with ©nam, ©ART, etc.)
- AAC audio properties via esds parsing
- ALAC audio properties via alac magic cookie
- Album art (covr atom) with JPEG/PNG detection
- MusicBrainz IDs and ReplayGain via freeform atoms
- Atomic file writing with mdat relocation
- MediaFile factory integration for format auto-detection
- DSF (DSD Stream File) format for high-resolution DSD audio
- DSD64/128/256/512 sample rate detection
- DSD/fmt/data chunk parsing
- ID3v2 metadata support at end of file
- Channel type detection (Mono, Stereo, 5.1 surround)
- APE Tag v2 support for tagging flexibility
- Text, Binary, and External item types
- Full read/write round-trip support
- Standard and extended metadata mappings
- DFF (DSDIFF) format for high-resolution DSD audio
- FRM8/DSD chunk parsing
- DSD64/128/256/512/1024 sample rate detection
- ID3v2 metadata at end of file
- Channel type detection
- Ogg FLAC format
- Ogg container with FLAC stream parsing
- STREAMINFO extraction (sample rate, channels, bits per sample)
- Vorbis Comment support with full read/write
- WavPack (.wv) format
- Block header parsing with flags
- Sample rate table lookup (15 standard rates)
- APE tag support for metadata
- Monkey's Audio (.ape) format
- Both old (≤3.97) and new (≥3.98) format versions
- STREAMINFO extraction
- APE tag support for metadata
- ASF/WMA format
- Header Object parsing with child objects
- Content Description (Title, Artist, Copyright)
- Extended Content Description (Album, Year, Genre, Track, etc.)
- Stream Properties for audio properties (bitrate, sample rate, channels)
- File Properties for duration
- Full read/write support with atomic saves
- Musepack format
- SV7 and SV8 stream version detection
- Audio properties (sample rate, channels, duration)
- APE tag support for metadata
- Speex format (Ogg container support exists)
- TrueAudio format
- 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.
