Skip to content

Read a directory scan without retaining audio payloads - #120

Merged
decriptor merged 9 commits into
mainfrom
perf/scan-without-audio
Nov 18, 2026
Merged

decriptor merged 9 commits into
mainfrom
perf/scan-without-audio

Conversation

@decriptor

@decriptor decriptor commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Summary

A MediaFile.Read(path) / ReadAsync(path) scan no longer keeps the audio or video payload. After the call returns, the file object holds tags, metadata pictures, and small headers (plus, for AIFF, the offset and length of each skipped SSND). Sample bytes stay on disk.

Windowed formats, in addition to the MP3, FLAC, and WAV reads already on main:

  • MP4/M4A/M4B/M4V skips mdat (the span parser no longer copies that box either). stco / co64 / tfhd / tfra / saio / iloc still move when moov changes size.
  • Matroska/WebM seeks over known-size Clusters and does not copy them. An unknown-size cluster stops the walk; save still fails closed instead of scanning media to resync.
  • Ogg Vorbis and Ogg Opus read header/comment pages and the last page (for the granule). Ogg FLAC reads header pages and stops at the first audio page. Duration comes from the last granule or, for Ogg FLAC, STREAMINFO.
  • AIFF skips SSND. WavPack, Monkey's Audio, and Musepack read the header and the trailing APE tag. DSF reads the DSD/fmt/data headers and the ID3 tag at the metadata offset. DFF reads every chunk except DSD / DST payloads. ASF reads the header object and skips the data object.

Save rewrites tags and copies the original payload bytes unchanged. A path opened file reloads those bytes from SourcePath through fileSystem ?? the filesystem stored at read time, and the same filesystem is what the write uses. A save with no source path and no loaded payload fails without replacing the file. Read(byte[]) still keeps one copy where an in-memory render has no other source (APE-style files, ASF, DSF, DFF, Ogg FLAC, and AIFF opened from a buffer).

Fixes #20

Comparison with TagLib# 2.3.0

Warm read of a local library of 4,668 MP3s, about 29 GB. Both calls open the file, read the title, the duration, and the picture count, then dispose it. .NET 8.

TagLibSharp2 TagLib# 2.3.0
Files read 4,662 4,660
Whole library 210 ms 417 ms
Median 26.1 μs 64.1 μs
95th percentile 119 μs 179 μs
Allocated per file 130 KB 177 KB

TagLib# 2.3.0 is the latest release on NuGet. Six empty files fail in both. TagLib# also rejects two files that contain no MPEG audio frame.

Tests

dotnet test tests/TagLibSharp2.Tests/TagLibSharp2.Tests.csproj -c Debug -f net8.0 -p:WarningsNotAsErrors=CA2027

Passed: 4315, Failed: 0, Skipped: 10, Total: 4325

dotnet format TagLibSharp2.slnx --verify-no-changes --severity warn is clean.

@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 91.22007% with 154 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.06%. Comparing base (58d38f1) to head (5142a2c).

Files with missing lines Patch % Lines
tests/TagLibSharp2.Tests/Core/WindowedEdgeTests.cs 92.83% 20 Missing and 2 partials ⚠️
src/TagLibSharp2/Aiff/AiffFile.cs 81.05% 8 Missing and 10 partials ⚠️
src/TagLibSharp2/Matroska/MatroskaFile.cs 80.45% 8 Missing and 9 partials ⚠️
src/TagLibSharp2/Ogg/OggWindow.cs 86.45% 6 Missing and 7 partials ⚠️
src/TagLibSharp2/Core/MediaFile.cs 84.21% 0 Missing and 12 partials ⚠️
src/TagLibSharp2/Musepack/MusepackFile.cs 87.01% 6 Missing and 4 partials ⚠️
src/TagLibSharp2/WavPack/WavPackFile.cs 88.23% 5 Missing and 5 partials ⚠️
src/TagLibSharp2/Mp4/Mp4File.cs 88.31% 4 Missing and 5 partials ⚠️
src/TagLibSharp2/Ape/MonkeysAudioFile.cs 87.87% 5 Missing and 3 partials ⚠️
src/TagLibSharp2/Dff/DffFile.cs 91.66% 5 Missing and 2 partials ⚠️
... and 7 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main     #120      +/-   ##
==========================================
+ Coverage   93.01%   93.06%   +0.05%     
==========================================
  Files         283      287       +4     
  Lines       54782    56456    +1674     
  Branches     5028     5370     +342     
==========================================
+ Hits        50953    52540    +1587     
- Misses       2280     2294      +14     
- Partials     1549     1622      +73     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Path and stream reads keep tags, pictures, and small headers. Media payloads stay on disk and are copied back from the source path when a save rewrites the tags.
MemoryStream has no span write on that target, and IsNullOrEmpty does not
narrow a source path there. Both broke the Release build in CI.
Add a BenchmarkDotNet project so a directory scan can be remeasured.
The suite reads MP3, WAV, and FLAC through MediaFile.Read and reports
allocations with MemoryDiagnoser.
BenchmarkDotNet 0.16.0-preview.2 is required for a net11 job.
The benchmark project targets net11 only when the SDK is 11 or newer,
so CI stays on the 8.0 and 10.0 SDKs.
MediaFile.Read opens the path directly. Format detection reads 32
bytes so the file buffer can satisfy the parser, and the MP3 window
fills one array instead of copying its audio probe.
LAME stores that count as the stream size, including bytes before the
first audio frame. A count past the end of the file still walks the
frames that are present. The tag and the audio probe are read into one
buffer.
@decriptor
decriptor force-pushed the perf/scan-without-audio branch from 9361587 to 8c53708 Compare November 18, 2026 07:17
@decriptor
decriptor merged commit fcd4314 into main Nov 18, 2026
8 checks passed
@decriptor
decriptor deleted the perf/scan-without-audio branch November 18, 2026 07:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: MediaFile.Read causes severe memory leak when scanning many audio files

1 participant