metadata_audio 0.9.6

A Dart-native audio metadata parser library that provides comprehensive metadata extraction for various audio formats including MP3, FLAC, Ogg, MP4, WAV, AIFF, APE, ASF, Matroska, and more. Ported f [...]

0.9.6

• Fixed: Fixed MP4/M4B chapter extraction when uniform sample size (stsz with sampleSize > 0) chapter tracks group multiple samples per chunk via stsc (sampleToChunkTable). All chapter samples are now correctly expanded across chunk offsets and extracted.
• Fixed: Fixed chapter end timestamp calculation fallback when the chapter track duration ends at or before the chapter's start timestamp to fall back to the overall container duration.
• Fixed: Improved network probe resilience in URL integration test suite to gracefully skip when external storage hosts return HTTP 500 errors.

0.9.5

• Feat: Mapped MP4/iTunes ©pub to publisher and ©des / desc to description in Mp4TagMapper so audiobook synopses and publishers are extracted into CommonTags.
• Feat: Extracted MP4/M4B chapters are packaged into standard standalone .m4a containers (audio/mp4) by default in ChapterDownloader.downloadChapter, enabling playback and seeking across Chromecast, ExoPlayer, AVPlayer, and web audio players.
• Feat: Added AudioMetadataCache to cache parsed MP4/M4B structures and sample tables in temporary storage, preventing duplicate container parsing on successive chapter downloads.
• Fixed: Added HTTP 429 resilience with exponential backoff and retry support across HTTP tokenizers and chapter downloads.

0.9.4-beta.2

• Feat: Added AudioMetadataCache to store parsed MP4/M4B audio track structures and sample tables in the OS temporary directory (Directory.systemTemp), preventing duplicate container parsing and network calls on subsequent chapter downloads.
• Feat: Added manual cache management methods: ChapterDownloader.clearCache(), ChapterDownloader.getCacheSize(), AudioMetadataCache.clearCache(), and AudioMetadataCache.evict(url).
• Fixed: Added HTTP 429 (Too Many Requests) resilience with exponential backoff, Retry-After header support, staggered parallel chunk starts, and automatic sequential download fallback across ChapterDownloader and HTTP tokenizers.

0.9.4-beta.1

• Feat: ChapterDownloader.downloadChapter now packages extracted MP4/M4B chapters directly into standard standalone .m4a containers (audio/mp4) by default, enabling playback and seeking on Chromecast, ExoPlayer, AVPlayer, and web audio receivers (legacy raw .aac ADTS format remains available when .aac extension is explicitly specified).

0.9.3

• Feat: Added MOV container support (.mov, video/quicktime) and QuickTime chapter extraction from video and audio tracks (tref/chap).
• Fixed: Ensure QuickTime track reference chapters are preserved without being overwritten by Nero chpl atoms, and support multiple media tracks referencing the chapter track simultaneously.
• Improved: Chapter end-time calculations respect the chapter track's own timescale and duration when available.

0.9.2

• Feat: Extended ChapterDownloader.downloadChapter to support downloading and extracting specific time ranges (chapters) from MP3/MPEG files, allowing partial downloading/slicing of files without embedded chapters using external timestamps.
• Fixed: Skips the VBR Xing/Info header frame when downloading MP3 slices starting at the beginning of the file, preventing player decoders from incorrectly reading the original total duration and stream size.
• Fixed: Added asynchronous prefetchRange calls inside MP3 parser offset and frame synchronization loops, resolving TokenizerException ("Use prefetchRange() before reading") when downloading MP3 ranges over remote URLs.
• Fixed: Resolved a race condition where a single-chunk download (numChunks <= 1) returned the download future without awaiting it, causing the client to close prematurely in the finally block and throwing Bad state: Client is closed.
• Example App: Updated the example Flutter app to enable chapter downloading for all remote files (regardless of embedded chapter metadata) and added a new Custom Range Downloader sidebar widget to quickly download any timestamp region from MP3 or M4A/AAC URLs with preset buttons.

0.9.1

• Fixed: MP4 parsing now reads the esds (Elementary Stream Descriptor) box to extract the correct channel configuration (e.g. mono vs stereo) and sample rate from the raw AudioSpecificConfig, overriding legacy stsd defaults.
• Fixed: ChapterDownloader.downloadChapter now correctly downloads the entire byte range (including interleaved non-audio track data/gaps) and extracts raw audio frames using relative offsets, resolving playback/decoding issues on audiobooks with interleaved metadata (like QuickTime text chapter tracks).

0.9.0

• Breaking Change: Removed sampleOffset property from Chapter class.
• Feat: Added byteOffset and endByteOffset properties to Chapter class.
• Feat: Implemented MP4 sample-to-byte offset mapping so that MP4/M4B chapters expose their exact start and end byte positions in the file.
• Feat: Updated ID3v2, FLAC, Ogg, and Wave parsers to align with the new unified chapter byte offset properties.
• Feat: Added ChapterDownloader utility class (lib/src/utils/chapter_downloader.dart) for extracting individual audiobook chapters as standalone playable ADTS AAC files.

0.8.0

• Fixed: MP4 stsz parsing now correctly handles uniform sample sizes without reading a non-existent per-sample table.
• Fixed: MP4 chapter extraction now expands per-sample chapter offsets from stsc + stco/co64 + stsz, restoring chapter parsing for audiobook files where multiple chapter samples share a single chunk.

0.7.2

• Feat: Enhanced MP4 parsing for large files by adding HTTP prefetching for atom headers and chapter data.

0.7.1

• Fixed: MP4 chapter extraction now supports co64 chunk offset tables (64-bit offsets), restoring chapter parsing for large M4B/audiobook files.
• Fixed: MP4 track parsing now correctly reads tkhd version-1 track IDs, enabling chapter-track linkage in files that use v1 tkhd atoms.
• Fixed: Post-parse chapter fallback now resolves chapter tracks by absolute offsets after atom traversal, improving reliability when chapter tables are finalized later in the file.
• Improved: URL strategy detection and parsing now degrade gracefully to full download when HEAD/range probing is unreliable, reducing false failures on flaky remote hosts.

0.7.0

• Fixed: Chrome/web builds now compile and run against the package without JS-incompatible 64-bit integer literals in Matroska, Musepack, MP4, DSF, and DSDIFF parsing paths.
• Fixed: Matroska chapter timing now preserves large EBML integer values in browser builds, restoring the expected chapter end time behavior.
• Fixed: DSF and DSDIFF test fixtures now use browser-safe 64-bit byte encoders instead of ByteData.setInt64, so the parser suites run in Chrome.
• Verified: Chrome test coverage now passes for MP4, Matroska, Musepack, DSF, and DSDIFF parser suites.

0.6.2

• Fixed: MP4/M4B parsing now handles version-1 mvhd atoms with large 64-bit timestamps without crashing, including the audiobook URL regression case that previously overflowed DateTime conversion on some platforms.

0.6.1

• Fixed: MP3 URL parsing now routes through the MPEG parser instead of the tag-only ID3 loader, restoring duration and bitrate extraction for real-world app usage.
• Fixed: Malformed ID3v2.3 frame headers now trigger MPEG resync/fallback instead of leaving MP3 metadata stuck at null.
• Fixed: MP3 duration now falls back to file-size plus sampled bitrate even when parsing stops before the EOF frame-count heuristic completes, improving URL parsing for malformed or tag-heavy files on mobile.

0.6.0

• Fixed: RangeTokenizer.hasCompleteData now reports true when the entire remote file fits inside the initial header fetch.
• Fixed: ProbingRangeTokenizer now aligns mp4Optimized tail fetches to chunk boundaries, preventing chunk-cache misindexing near the end of large MP4/M4A files.
• Added: Real URL integration coverage for MP3, FLAC, OGG, M4B, plus 600+ MB FLAC and WAV files.
• Added: Lower-level tokenizer smoke tests for FLAC, AIFF, M4A, and WAV sample files.

0.5.1

• Fixed: ProbingRangeTokenizer now correctly splits fetched data into 64KB chunks, fixing metadata parsing failures for MP3 files with large ID3v2 headers when using ParseStrategy.probe.
• Fixed: ID3v1 parser now gracefully handles missing tail data (e.g., with partial HTTP range requests), preventing crashes when probing MP3 files.

0.5.0

• Feat: Added MetadataObserver support for incremental metadata updates during parsing.
• Feat: Observer events now emit typed format and common IDs using Dart extension types, with support for ad hoc unknown IDs.
• Feat: Added live observer coverage for file-backed parsing, including optional chapter-event verification for local audiobook samples.

0.4.0

• Fixed: MP4 chpl (Nero chapter list) parsing now supports audiobook chapter extraction from files that expose chapter timing via chapter time base metadata.
• Fixed: Chapter timestamp conversion now infers time base from file timing data instead of relying on a hardcoded scale, restoring full chapter lists (e.g. 73 chapters) for affected M4B files.
• Fixed: MP4 parser now reads chpl atoms under udta and emits normalized chapter ranges (start/end) in milliseconds.
• Fixed: 64-bit MP4 integer parsing overflow guard for large files / version-1 atom fields.
• Improved: URL-based MP4 parsing reliability for large files by expanding tail prefetch windows for moov discovery in HTTP tokenizers.

0.3.0

• Fixed: MP4 chapter extraction now works reliably with URL-based tokenizers by prefetching the entire moov atom when it exceeds the initial prefetch window.
• Feat: Implemented consolidated HTTP range requests in HttpBasedTokenizer, reducing the number of network requests by up to 90% for large metadata blocks.
• Feat: Added retry logic with exponential backoff to HTTP tokenizers to handle transient network errors.
• Fixed: Improved MP4 chapter timing accuracy by using the chapter track's own Time-to-Sample (STTS) table instead of approximate byte-offset correlation.

0.2.0

• Fixed: Auto-initialize parser factory to prevent "Field '_parserFactory' has not been initialized" error
• Added: createDefaultParserFactory() function for creating a factory with all format loaders
• Added: Exports for all format loaders (MpegLoader, FlacLoader, etc.) for custom configurations
• Docs: Added initialization section to README documenting auto-init and custom setup

0.1.0

• Initial stable release with comprehensive audio metadata support
• Multi-format support: MP3, FLAC, Ogg Vorbis, MP4, WAV, AIFF, APE, ASF, Matroska, Musepack, WavPack, DSF, DSDIFF
• Full ID3 support: ID3v1, ID3v2.2, ID3v2.3, ID3v2.4
• Chapter/track boundary extraction for audiobooks and podcasts
• Smart URL parsing with automatic strategy selection
• Streaming support for remote files