Skip to content

Commit 17ef00c

Browse files
decriptordecriptor
committed
Update documentation for v0.4.0
- Add MP4/M4A and Ogg Opus to format support matrix - Add MediaFile factory examples to quick start - Add MP4/M4A and Ogg Opus cookbook recipes - Mark MP4/M4A milestone as complete in ROADMAP and MILESTONES - Add v0.3.0 and v0.4.0 release sections to MILESTONES - Update test count to 2,318 and coverage to 88.67%
1 parent 14dab5a commit 17ef00c

5 files changed

Lines changed: 377 additions & 80 deletions

File tree

‎MILESTONES.md‎

Lines changed: 66 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,11 @@
88

99
| Metric | Value | Notes |
1010
|--------|-------|-------|
11-
| **Tests Passing** | 1,964 | Solid foundation |
12-
| **Source Files** | 70+ | Core + 6 formats |
13-
| **Formats Complete** | 6 of 22 | MP3, FLAC, OGG Vorbis, Opus, WAV, AIFF (all read+write) |
14-
| **Format Coverage** | ~27% | Significant work remaining |
15-
| **Core Infrastructure** | ✅ 100% | Tag, BinaryData, IFileSystem, Picture |
11+
| **Tests Passing** | 2,318 | Solid foundation |
12+
| **Source Files** | 100+ | Core + 7 formats |
13+
| **Formats Complete** | 7 of 22 | MP3, FLAC, OGG Vorbis, Ogg Opus, WAV, AIFF, MP4/M4A (all read+write) |
14+
| **Format Coverage** | ~32% | Significant work remaining |
15+
| **Core Infrastructure** | ✅ 100% | Tag, BinaryData, IFileSystem, Picture, MediaFile factory |
1616

1717
---
1818

@@ -23,10 +23,10 @@ Based on multi-perspective analysis, the original roadmap is reordered:
2323
| Original Priority | Revised Priority | Format | Rationale |
2424
|-------------------|------------------|--------|-----------|
2525
| P0-1 WAV | **✅ COMPLETE** | WAV | Full read/write with RIFF INFO + ID3v2 + bext (BWF) |
26-
| P0-3 MP4/M4A | **P0-1 MP4/M4A** | ⬆️ Moved UP | Apple ecosystem is massive; 25% of lossless libraries |
26+
| P0-3 MP4/M4A | **✅ COMPLETE** | MP4/M4A | Full read/write with iTunes atoms + AAC/ALAC |
2727
| P0-7 VBR Headers | **✅ COMPLETE** | VBR | Xing/VBRI header parsing for accurate MP3 duration |
2828
| P0-6 APE Tag | **P0-3 APE Tag** | Same | Blocks WavPack/Musepack/Monkey's Audio |
29-
| P0-5 Opus | **✅ COMPLETE** | Opus | Full read/write with OpusHead + OpusTags |
29+
| P0-5 Opus | **✅ COMPLETE** | Opus | Full read/write with OpusHead + OpusTags + R128 gain |
3030
| P0-2 AIFF | **✅ COMPLETE** | AIFF | Full read/write with FORM container + COMM + ID3 |
3131
| P0-4 DSF | **P0-5 DSF** | ⬇️ Demoted | DSD is vocal minority, not market size |
3232
| P1 Musepack | **SKIP** | ❌ Remove | Dead format (last release 2009) |
@@ -36,7 +36,7 @@ Based on multi-perspective analysis, the original roadmap is reordered:
3636
## Milestone Map
3737

3838
### Milestone 1: Technical Debt & Infrastructure
39-
**Duration:** 1 week | **Status:** Mostly Complete
39+
**Duration:** 1 week | **Status:** ✅ Complete
4040

4141
Fix blocking issues before new formats:
4242

@@ -46,13 +46,13 @@ Fix blocking issues before new formats:
4646
| Extract `SyncsafeInteger.cs` static class | 1h | 🔶 In Id3v2Tag (adequate for now) |
4747
| Create `ExtendedFloat.cs` (80-bit IEEE 754) | 4h | ✅ Complete |
4848
| Fix DSD duration overflow (use double) | 1h | ❌ Not started (DSF not yet implemented) |
49-
| Format detection factory | 4h | ❌ Not started |
49+
| Format detection factory | 4h | ✅ Complete (MediaFile.Open) |
5050
| Complete IDisposable pattern | 4h | ❌ Not started |
5151

5252
**Exit Criteria:**
53-
- All utility classes extracted and tested
54-
- No integer overflow on DSD files
55-
- Format detection working for existing formats
53+
- ✅ All utility classes extracted and tested
54+
- ❌ No integer overflow on DSD files (DSF not yet implemented)
55+
- ✅ Format detection working for all formats (MediaFile factory)
5656

5757
---
5858

@@ -78,29 +78,34 @@ Complete the formats we already read:
7878
---
7979

8080
### Milestone 3: MP4/M4A (Critical Path)
81-
**Duration:** 1.5-2 weeks | **Status:** Not Started | **Complexity:** 10/10
81+
**Duration:** 1.5-2 weeks | **Status:** ✅ Complete | **Complexity:** 10/10
8282

8383
Highest business value (Apple ecosystem):
8484

8585
| Task | Effort | Notes |
8686
|------|--------|-------|
87-
| Atom tree navigation | 3d | moov/udta/meta/ilst path |
88-
| Standard atoms (©nam, ©ART, ©alb, etc.) | 2d | Text atoms |
89-
| trkn/disk parsing | 1d | Track/disc number pairs |
90-
| covr atom (cover art) | 1d | JPEG/PNG images |
91-
| Freeform atoms (----/mean/name/data) | 2d | Custom fields |
92-
| Audio properties from stsd/mvhd | 1d | Duration, sample rate |
93-
| Round-trip tests | 2d | iTunes compatibility |
87+
| Atom tree navigation | 3d | ✅ moov/udta/meta/ilst path |
88+
| Standard atoms (©nam, ©ART, ©alb, etc.) | 2d | ✅ Text atoms |
89+
| trkn/disk parsing | 1d | ✅ Track/disc number pairs |
90+
| covr atom (cover art) | 1d | ✅ JPEG/PNG images |
91+
| Freeform atoms (----/mean/name/data) | 2d | ✅ Custom fields, MusicBrainz, ReplayGain |
92+
| Audio properties from stsd/mvhd | 1d | ✅ Duration, sample rate, bitrate, channels |
93+
| AAC esds parsing | 1d | ✅ Complete |
94+
| ALAC magic cookie | 1d | ✅ Complete |
95+
| Atomic file write | 1d | ✅ Complete with mdat relocation |
96+
| MediaFile factory integration | 0.5d | ✅ Complete |
97+
| Round-trip tests | 2d | ✅ iTunes compatibility verified |
9498

9599
**Exit Criteria:**
96-
- iTunes-tagged files read correctly
97-
- Write operations don't break iTunes compatibility
98-
- ALAC and AAC variants both work
100+
- ✅ iTunes-tagged files read correctly
101+
- ✅ Write operations don't break iTunes compatibility
102+
- ✅ ALAC and AAC variants both work
103+
- ✅ MediaFile.Open auto-detects MP4/M4A format
99104

100-
**Risks:**
101-
- Complex atom tree structure
102-
- Extended size atoms (>4GB files)
103-
- iTunes quirks (non-standard v2.3 sizes)
105+
**Risks Mitigated:**
106+
- ✅ Complex atom tree structure - handled
107+
- ✅ Extended size atoms (>4GB files) - supported
108+
- ✅ iTunes quirks - compatible
104109

105110
---
106111

@@ -157,6 +162,31 @@ Studio format + shared container:
157162
- Test coverage: Polyfills, OggCrc, Id3v1Genre (+51 tests)
158163
- 1,939 total tests
159164

165+
### 🎯 v0.3.0 - ✅ RELEASED 2025-12-30
166+
167+
**Added:**
168+
- Ogg Opus full support (read/write)
169+
- OpusHead parsing per RFC 7845
170+
- R128 gain tags (output gain, album gain, track gain)
171+
- Multi-stream support (mapping families 0, 1, 255)
172+
- Stream/coupled count validation
173+
- Security validation (max packet size, parameter checks)
174+
- 2,078 total tests
175+
176+
### 🎯 v0.4.0 - ✅ RELEASED 2025-12-31
177+
178+
**Added:**
179+
- **MP4/M4A full support** (read/write)
180+
- ISO 14496-12 box parsing (ftyp, moov, mdat, etc.)
181+
- iTunes-style metadata atoms (ilst)
182+
- AAC audio properties via esds parsing
183+
- ALAC audio properties via magic cookie
184+
- Album art (covr atom) with JPEG/PNG detection
185+
- MusicBrainz IDs and ReplayGain via freeform atoms
186+
- Atomic file writing with mdat relocation
187+
- **MediaFile factory** with format auto-detection
188+
- 2,318 total tests (88.67% code coverage)
189+
160190
---
161191

162192
### Milestone 5: Opus & APE Tag
@@ -168,13 +198,15 @@ Modern lossy + infrastructure for P1 formats:
168198
|------|--------|-------|
169199
| Opus OpusHead parsing | 1d | ✅ Complete |
170200
| Opus OpusTags parsing | 1d | ✅ Complete |
171-
| Opus R128 gain handling | 0.5d | ❌ Not started (OutputGain field available) |
201+
| Opus R128 gain handling | 0.5d | ✅ Complete (OutputGain, R128TrackGain, R128AlbumGain) |
202+
| Multi-stream support | 0.5d | ✅ Complete (mapping families 0, 1, 255) |
172203
| APE Tag v2 format | 3d | ❌ Not started |
173204
| APE tag in MP3 | 1d | ❌ Not started |
174205
| Round-trip tests | 1d | ✅ Opus complete |
175206

176207
**Exit Criteria:**
177208
- ✅ Opus files read correctly
209+
- ✅ R128 gain values properly exposed
178210
- ❌ APE tags read/write in isolation
179211
- ❌ MP3 with APE+ID3v2+ID3v1 handled correctly
180212

@@ -281,14 +313,15 @@ Production readiness:
281313
## Timeline Summary
282314

283315
```
284-
✅ COMPLETE: Technical Debt + MP3/FLAC Write + WAV/RIFF + AIFF
316+
✅ COMPLETE: Technical Debt + MP3/FLAC Write + WAV/RIFF + AIFF + Opus + MP4/M4A
285317
✅ v0.1.0 RELEASED: 2025-12-26 (MP3, FLAC, OGG Vorbis, WAV, AIFF)
286318
✅ v0.2.0 RELEASED: 2025-12-29 (ID3v2.2, unsync, BWF, WAVEFORMATEXTENSIBLE)
287319
✅ v0.2.1 RELEASED: 2025-12-29 (Error context, test coverage)
320+
✅ v0.3.0 RELEASED: 2025-12-30 (Ogg Opus with R128 gain)
321+
✅ v0.4.0 RELEASED: 2025-12-31 (MP4/M4A + MediaFile factory)
288322
289323
NEXT UP:
290-
- MP4/M4A Implementation (critical path - Apple ecosystem)
291-
- Opus & APE Tag
324+
- APE Tag format (unlocks WavPack/Monkey's Audio)
292325
- DSF (DSD format)
293326
>>> BETA RELEASE (v0.5.0) <<<
294327
- WMA/ASF + DFF + WavPack
@@ -348,7 +381,7 @@ NEXT UP:
348381
- ✅ Zero data loss bugs
349382

350383
### Beta Release
351-
- 8 P0 formats complete (need: MP4/M4A, Opus, DSF)
384+
- 8 P0 formats complete (have: 7, need: DSF)
352385
- Production Roon deployment (beta users)
353386
- Cross-tagger compatibility verified
354387

@@ -371,5 +404,5 @@ NEXT UP:
371404

372405
---
373406

374-
*Last Updated: 2025-12-29 (v0.2.1)*
407+
*Last Updated: 2025-12-31 (v0.4.0)*
375408
*Sources: Audiophile analysis, Dev PM analysis, Audio Product analysis, Project Management analysis*

‎README.md‎

Lines changed: 65 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ A modern .NET library for reading and writing metadata in media files.
1313
- Result-based error handling (no exceptions)
1414

1515
**Choose TagLib# if you need:**
16-
- MP4/M4A, ASF/WMA, or APE support (not yet implemented here)
16+
- ASF/WMA or APE support (not yet implemented here)
1717
- A battle-tested library used in production for years
1818

1919
See the [Migration Guide](docs/MIGRATION-FROM-TAGLIB.md) for detailed comparison.
@@ -25,28 +25,31 @@ See the [Migration Guide](docs/MIGRATION-FROM-TAGLIB.md) for detailed comparison
2525
- **Performance-First**: Zero-allocation parsing with `Span<T>` and `ArrayPool<T>`
2626
- **Multi-Target**: Supports .NET Standard 2.0/2.1, .NET 8.0, and .NET 10.0
2727
- **Format Support**:
28-
- Audio: MP3 (ID3v1/ID3v2), FLAC, OGG Vorbis, WAV (RIFF INFO/ID3v2), AIFF (ID3v2)
29-
- Planned: MP4/M4A, ASF/WMA, APE, Opus, DSF
28+
- Audio: MP3 (ID3v1/ID3v2), FLAC, OGG Vorbis, Ogg Opus, WAV (RIFF INFO/ID3v2), AIFF (ID3v2), MP4/M4A (AAC/ALAC)
29+
- Planned: ASF/WMA, APE, DSF
3030

3131
## Format Support Matrix
3232

33-
| Feature | MP3 | FLAC | Ogg Vorbis | WAV | AIFF |
34-
|---------|:---:|:----:|:----------:|:---:|:----:|
35-
| **Read metadata** | ✅ | ✅ | ✅ | ✅ | ✅ |
36-
| **Write metadata** | ✅ | ✅ | ✅ | ✅ | ✅ |
37-
| **Audio properties** | ✅ | ✅ | ✅ | ✅ | ✅ |
38-
| **Async I/O** | ✅ | ✅ | ✅ | ✅ | ✅ |
39-
| **Album art** | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
40-
| **ReplayGain** | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
41-
| **MusicBrainz IDs** | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
42-
| **Lyrics** | ✅ | ✅² | ✅² | ✅¹ | ✅¹ |
43-
| **Performer roles** | ✅ | ✅ | ✅ | ✅¹ | ✅¹ |
44-
| **BWF broadcast metadata** | — | — | — | ✅ | — |
45-
| **Surround sound info** | — | — | — | ✅³ | — |
33+
| Feature | MP3 | FLAC | Ogg Vorbis | Ogg Opus | WAV | AIFF | MP4/M4A |
34+
|---------|:---:|:----:|:----------:|:--------:|:---:|:----:|:-------:|
35+
| **Read metadata** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
36+
| **Write metadata** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
37+
| **Audio properties** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
38+
| **Async I/O** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
39+
| **Album art** | ✅ | ✅ | ✅ | ✅ | ✅¹ | ✅¹ | ✅ |
40+
| **ReplayGain** | ✅ | ✅ | ✅ | ✅⁴ | ✅¹ | ✅¹ | ✅⁵ |
41+
| **MusicBrainz IDs** | ✅ | ✅ | ✅ | ✅ | ✅¹ | ✅¹ | ✅ |
42+
| **Lyrics** | ✅ | ✅² | ✅² | ✅² | ✅¹ | ✅¹ | ✅ |
43+
| **Performer roles** | ✅ | ✅ | ✅ | ✅ | ✅¹ | ✅¹ | — |
44+
| **BWF broadcast metadata** | — | — | — | — | ✅ | — | — |
45+
| **Surround sound info** | — | — | — | — | ✅³ | — | ✅⁶ |
4646

4747
¹ Via embedded ID3v2 tag
4848
² Via Vorbis Comment LYRICS field
4949
³ Via WAVEFORMATEXTENSIBLE (channel mask, valid bits per sample)
50+
⁴ Via R128 gain tags (RFC 7845)
51+
⁵ Via iTunes ----:com.apple.iTunes:replaygain_* atoms
52+
⁶ Via channel layout in stsd/esds
5053

5154
### Tag Format by Container
5255

@@ -55,8 +58,10 @@ See the [Migration Guide](docs/MIGRATION-FROM-TAGLIB.md) for detailed comparison
5558
| MP3 | ID3v2 | ID3v1 | ID3v2 preferred |
5659
| FLAC | Vorbis Comment | — | Native only |
5760
| Ogg Vorbis | Vorbis Comment | — | Native only |
61+
| Ogg Opus | Vorbis Comment | — | Native only |
5862
| WAV | RIFF INFO | ID3v2, bext (BWF) | ID3v2 preferred |
5963
| AIFF | ID3 chunk | — | Native only |
64+
| MP4/M4A | iTunes atoms (ilst) | — | Native only |
6065

6166
## Installation
6267

@@ -75,28 +80,52 @@ dotnet build
7580
## Quick Start
7681

7782
```csharp
83+
using TagLibSharp2.Core;
7884
using TagLibSharp2.Mpeg;
7985
using TagLibSharp2.Xiph;
8086
using TagLibSharp2.Ogg;
8187
using TagLibSharp2.Riff;
8288
using TagLibSharp2.Aiff;
89+
using TagLibSharp2.Mp4;
8390

84-
// Read MP3 tags (prefers ID3v2, falls back to ID3v1)
85-
var result = Mp3File.ReadFromFile("song.mp3");
91+
// Auto-detect format using MediaFile factory
92+
var result = MediaFile.Open("song.m4a");
8693
if (result.IsSuccess)
8794
{
88-
var mp3 = result.File!;
95+
Console.WriteLine($"Format: {result.Format}");
96+
Console.WriteLine($"{result.Tag?.Title} by {result.Tag?.Artist}");
97+
}
98+
99+
// Read MP3 tags (prefers ID3v2, falls back to ID3v1)
100+
var mp3Result = Mp3File.ReadFromFile("song.mp3");
101+
if (mp3Result.IsSuccess)
102+
{
103+
var mp3 = mp3Result.File!;
89104
Console.WriteLine($"{mp3.Title} by {mp3.Artist}");
90105

91106
// Modify and save
92107
mp3.Title = "New Title";
93108
mp3.SaveToFile("song.mp3", File.ReadAllBytes("song.mp3"));
94109
}
95110

111+
// MP4/M4A files with iTunes metadata
112+
var mp4Result = Mp4File.ReadFromFile("song.m4a");
113+
if (mp4Result.IsSuccess)
114+
{
115+
var mp4 = mp4Result.File!;
116+
Console.WriteLine($"{mp4.Title} - {mp4.Duration}");
117+
Console.WriteLine($"Codec: {mp4.AudioCodec}, {mp4.Properties?.SampleRate}Hz");
118+
}
119+
96120
// FLAC and Ogg Vorbis work the same way
97121
var flac = FlacFile.ReadFromFile("song.flac").File;
98122
var ogg = OggVorbisFile.ReadFromFile("song.ogg").File;
99123

124+
// Ogg Opus (RFC 7845) with R128 gain
125+
var opusResult = OggOpusFile.ReadFromFile("song.opus");
126+
var opus = opusResult.File;
127+
Console.WriteLine($"Opus: {opus?.Properties?.Duration}, R128 gain: {opus?.Properties?.OutputGain}dB");
128+
100129
// WAV files support both RIFF INFO and ID3v2 tags
101130
WavFile.TryParse(new BinaryData(File.ReadAllBytes("song.wav")), out var wav);
102131
Console.WriteLine($"WAV: {wav.Title} - {wav.AudioProperties?.Duration}");
@@ -108,7 +137,7 @@ aiff.Tag = new Id3v2Tag { Title = "Updated Title" };
108137
aiff.SaveToFile("song.aiff");
109138

110139
// Async support for high-throughput scenarios
111-
var asyncResult = await Mp3File.ReadFromFileAsync("song.mp3");
140+
var asyncResult = await Mp4File.ReadFromFileAsync("song.m4a");
112141
```
113142

114143
See the [examples](examples/) directory for more comprehensive usage patterns.
@@ -198,9 +227,23 @@ This is a clean-room rewrite of media tagging functionality, designed from speci
198227
- [x] WAV chunk preservation (fact, cue, smpl and other chunks)
199228
- [x] All formats preserve unknown/unrecognized data during round-trip
200229

230+
### Phase 10: Ogg Opus ✅
231+
- [x] OpusHead packet parsing (RFC 7845)
232+
- [x] R128 gain tags (output gain, album gain, track gain)
233+
- [x] Multi-stream support (mapping families 0, 1, 255)
234+
- [x] Stream/coupled count validation per RFC 7845
235+
236+
### Phase 11: MP4/M4A ✅
237+
- [x] ISO 14496-12 box parsing (ftyp, moov, mdat, etc.)
238+
- [x] iTunes-style metadata atoms (ilst with ©nam, ©ART, etc.)
239+
- [x] AAC audio properties via esds parsing
240+
- [x] ALAC audio properties via alac magic cookie
241+
- [x] Album art (covr atom) with JPEG/PNG detection
242+
- [x] MusicBrainz IDs and ReplayGain via freeform atoms
243+
- [x] Atomic file writing with mdat relocation
244+
- [x] MediaFile factory integration for format auto-detection
245+
201246
### Future
202-
- [ ] MP4/M4A (AAC/ALAC) with iTunes atoms
203-
- [ ] Opus audio format
204247
- [ ] DSF (DSD) format
205248
- [ ] ASF/WMA format
206249
- [ ] APE tags for WavPack/Musepack

0 commit comments

Comments
 (0)