Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,12 @@ Read this file before changing parser, API, fixtures, fuzzers, or counts. This f

## Current design invariants (not additional assessment requirements)

**Scope gate:** Only requirements called out in the [assessment-only checklist](docs/assessment-brief.md#appendix-project-interpretation-not-assignment-text) are mandated by the employer. The configurable 50 MiB default limit, raw uploads, metadata-exclusion option, extended free-format range, fuzzing and release tooling are established **project choices**, not extra conditions imposed by the brief. Keep them working but never broaden unrelated scope to satisfy a reference appendix.
**Scope gate:** Only requirements called out in the [assessment-only checklist](docs/assessment-brief.md#appendix-project-interpretation-not-assignment-text) are mandated by the employer. The configurable 50 MiB default limit, raw uploads, metadata-exclusion option, fuzzing and release tooling are established **project choices**, not extra conditions imposed by the brief. Free-format candidate eligibility uses the [documented per-sample-rate 320 kbps envelope](docs/specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero); LAME's higher-rate extensions must not compete with in-scope layouts. Keep the documented behavior working but never broaden unrelated scope to satisfy a reference appendix.

- MPEG-1 is version bits `11`; Layer III is layer bits `01`. Support bitrate indices 1–14 **and free-format index 0** (bounded frame-spacing inference); reject forbidden index 15 and reserved sample rate 3. MPEG-2, MPEG-2.5, Layers I/II, ADTS/AAC and MP4 are out of assessment scope.
- Compute indexed frame lengths independently for **every frame**, including VBR/ABR, rather than multiplying the first frame length by the count or trusting a Xing/VBRI count.
- Successive in-file sample-rate configurations use the [bounded sequence policy](docs/specifications/successive-sequences.md). They are separate from multiple uploaded files; do not claim a universal ISO concatenation mandate. Same-rate mode switching remains separate.
- Free-format has no table bitrate; cache the **unpadded frame length**, then apply each frame's padding. Follow the documented EOF/metadata-anchored short inference policy; reject equally supported candidates and disclose unavoidable singleton ambiguity. Never allow unbounded lookahead, rescans or backtracking.
- Free-format has no table bitrate; cache the **unpadded frame length**, then apply each frame's padding. Bound both the base and every physical frame by its own sample rate during root/successor inference and locked traversal, independently of the fixed probe budget. At maximum base, padding exceeds the envelope at 32/48 kHz but fits at 44.1 kHz. Do not infer a minimum bitrate from the indexed table or claim full padding-schedule validation. Follow the documented EOF/metadata-anchored short inference policy; reject equally supported candidates and disclose unavoidable singleton ambiguity. Never allow unbounded lookahead, rescans or backtracking.
- **Current owner-selected policy:** HTTP omitted/`false` excludes at most one recognized _initial_ Xing/Info/VBRI encoder frame; HTTP `true` and direct parser calls with no option count complete physical MPEG frames. **ID3 frames are metadata records, not MPEG audio frames.** Exclusion must recognize the initial encoder structure, never subtract one blindly, and does not prove that every counted frame decodes to audio.
- Skip supported ID3 tags from their encoded, bounded lengths; do not interpret tag content, decompress, execute, download art, log uploaded bytes, or load entire uploads into memory.
- Preserve `AsyncIterable<Uint8Array>` parsing, bounded memory, streaming backpressure, one configurable raw/multipart per-file byte limit (50 MiB by default), typed deterministic failures, and JSON response format.
Expand Down
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,6 +142,8 @@ Complexity: **O(n)** time and **O(max upstream chunk size)** additional memory.

The parser detects free-format frame spacing using multiple consecutive compatible MPEG headers instead of a bitrate-table lookup. The parser rejects invalid data at the next required frame boundary. It does not resynchronize after corrupt frames or arbitrarily skip noise before the first header: doing so can silently turn a malformed upload into a plausible but wrong count. It supports consecutive ID3v2 tags at each MPEG boundary, including embedded tags; every appended tag must be v2.4 with a matching footer, followed by an optional final ID3v1. **Free-format MPEG-1 Layer III** (bitrate index zero) is supported with bounded inference of fixed frame spacing and per-frame padding; one-/two-frame streams can use bounded EOF or metadata-boundary evidence, while tied or conservatively ambiguous candidates return 415. Successive sample-rate configurations inside one uploaded file follow the [bounded sequence policy](docs/specifications/successive-sequences.md); competing layouts produce an explicit ambiguity error. Multiple uploaded files remain rejected. This structural heuristic cannot distinguish every truncated or extended singleton from a complete frame; see the [precise inference contract](docs/specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero). Table-defined bitrates 32–320 kbps remain supported. Other unsupported scope includes MPEG-2/2.5, Layers I/II, APE/Lyrics3 trailers, audio decoding, and CRC validation.

Free-format candidates use a per-sample-rate envelope through 320 kbps: unpadded spans up to 1,044 / 960 / 1,440 bytes at 44.1 / 48 / 32 kHz, and physical spans including padding up to 1,045 / 960 / 1,440 bytes. Thus padding at the maximum base fits only at 44.1 kHz. Larger spans are excluded from inference, including competing ancillary patterns. No eligible candidate returns 415 `unsupported-format`; a later physical overrun after span acquisition returns 422 `invalid-mp3`. The [inclusive endpoint interpretation and structural limits](docs/specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero) remain explicit; this is not full bitstream or padding-schedule validation.

## Verification

```bash
Expand Down
2 changes: 2 additions & 0 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ Every frame is parsed individually. This supports constant and variable bitrate

Free-format MPEG-1 Layer III uses bitrate index zero and a fixed unpadded span plus each frame's padding. One 8,647-byte search window evaluates bounded candidate spans, crossing validated tags only at each proposed boundary. One additional unsearched lookahead byte distinguishes its edge from actual EOF before a final ID3v1 tag can add boundary evidence. A validated tag header can anchor a body larger than the probe, which is subsequently streamed. Candidates are ranked by compatible MPEG headers and then metadata-boundary evidence; ties reject. The [sequence policy](specifications/successive-sequences.md) adds bounded changed-rate continuation and a conflicting-layout veto without giving successor headers votes for a prior span. Three-header chains remain supported; shorter chains require EOF, metadata or supported changed-rate anchoring and conservative compatible-header/plausible-metadata checks. This is structural inference, not proof of unique decoding: EOF cannot distinguish every complete singleton from a truncated or extended one. The [complete policy and source limitations](specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero) are part of the contract. Locked traversal remains strict and never rescans payload.

The probe budget is independent of candidate eligibility. Root and successor candidates require `baseLength <= floor(144 * 320000 / sampleRateHz)` and every physical span, including padding, must fit `ceil(144 * 320000 / sampleRateHz)`. Locked traversal retains the physical check. Maximum-base padding therefore fits at 44.1 kHz but exceeds the bound at 32/48 kHz. Extension-only spans cannot create ambiguity for an otherwise supported layout. The inclusive endpoint follows the [documented maximum-rate interpretation](specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero); inference does not recover an exact bitrate or validate the complete padding schedule.

This is a **structural parser**, not a full Layer III bitstream validator. New sequence evidence reads the backward offset, declared main-data lengths and spectral-pair counts for necessary side-information bounds. Full validation would additionally establish side-information semantics, actual reservoir availability, Huffman data and CRC integrity. Supporting additional tag families such as APEv2/Lyrics3, or other MPEG versions/layers, is a separate compatibility expansion—not part of those Layer III decoding checks and not added here.

## Resource model
Expand Down
8 changes: 6 additions & 2 deletions docs/assessment-brief.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,8 +207,12 @@ the policy, its change from the earlier HTTP default and verification evidence.

The brief does not prescribe a multipart field name, raw uploads, MIME aliases,
query options, exact error statuses/schema, upload caps, libraries or deployment
infrastructure. LAME free-format 321-640 kbps interoperability, arbitrary embedded
ID3, APEv2/Lyrics3 and decoder-style recovery are optional compatibility choices.
infrastructure. LAME extensions beyond the [documented 320 kbps candidate envelope](specifications/mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero)
are outside the supported scope and must not compete with supported layouts.
The inclusive endpoint follows the detailed maximum-rate rule and fixed-rate
arithmetic; the definition's wording distinction remains documented.
Arbitrary embedded ID3, APEv2/Lyrics3 and decoder-style recovery
are optional compatibility choices.
Fuzzing, mutation testing, 100% coverage, SBOMs, release automation, formal security
audits and production auth/rate limiting are likewise not evaluator mandates.

Expand Down
6 changes: 4 additions & 2 deletions docs/specifications/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ This directory is the **AI-agent and reviewer source register for this TypeScrip

## Authority classes, in order

Free-format boundary review also uses [ITU-R BS.1115-1, Appendix 2](https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.1115-1-200504-W!!PDF-E.pdf), a public primary reference describing a 320 kbps Layer III free-format maximum and per-frame padding. The inclusive endpoint follows the detailed maximum-rate rule and fixed-rate arithmetic; the wording distinction between ISO/IEC 11172-3:1993 §§2.1.67 and 2.4.3.4.4 remains documented in the [precise base and physical-span envelopes](mpeg-1-layer-iii.md#4-free-format-layer-iii-bitrate-index-zero). LAME's larger encoder range is evidence for rejection fixtures, not authority to admit extension-only candidates.

| ID | Source and scope | Authority | Applicable project decision |
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| M1 | [ISO/IEC 11172-3:1993, MPEG-1 Part 3: Audio](https://www.iso.org/standard/22412.html) | **Normative international MPEG-1 audio standard**; current edition confirmed by ISO | MPEG-1 Layer III header syntax, sampling/bitrate indices, padding, CRC protection and free-format |
Expand All @@ -15,7 +17,7 @@ This directory is the **AI-agent and reviewer source register for this TypeScrip
| I24 | [ID3v2.4.0 Main Structure](https://id3.org/id3v2.4.0-structure) | Informal format standard | Header/footer, synchsafe size, appended tag and placement |
| I1 | [ID3v1 / ID3v1.1](https://id3.org/ID3v1) | Format-author documentation | Exactly 128 trailing bytes beginning `TAG` |
| IFAQ | [ID3.org FAQ](https://id3.org/FAQ) | Maintainer guidance, subordinate to versioned specs | Rare in-stream tags and trailing ID3 placement |
| L1 | [LAME USAGE (`--freeformat`)](https://github.com/lameproject/lame/blob/1f5cc9487284d5950343aa5d4f70de433468070a/USAGE) | Original encoder documentation; **interoperability evidence, not an amendment to ISO** | Fixed free-format bitrate 8–640 kbps; ordinary MPEG-1 Layer III table still capped at 320 kbps |
| L1 | [LAME USAGE (`--freeformat`)](https://github.com/lameproject/lame/blob/1f5cc9487284d5950343aa5d4f70de433468070a/USAGE) | Original encoder documentation; **interoperability evidence, not an amendment to ISO** | Encoder range 8–640 kbps; extension output supplies rejection fixtures, not a wider parser limit |
| L2 | [LAME VbrTag.h](https://github.com/lameproject/lame/blob/1f5cc9487284d5950343aa5d4f70de433468070a/libmp3lame/VbrTag.h), [VbrTag.c](https://github.com/lameproject/lame/blob/1f5cc9487284d5950343aa5d4f70de433468070a/libmp3lame/VbrTag.c) and [LAME API](https://github.com/lameproject/lame/blob/1f5cc9487284d5950343aa5d4f70de433468070a/API) | Original encoder source for de facto Xing/Info/LAME layout | Metadata header is inside a physical MPEG frame; count field is not a reliable file-traversal oracle |
| V1 | [FFmpeg mp3 demuxer, Xing and VBRI readers](https://github.com/FFmpeg/FFmpeg/blob/c220739be57307ea821d1197ad89ff6e372180e8/libavformat/mp3dec.c) and [TagLib Xing/VBRI reader](https://github.com/taglib/taglib/blob/1ae164e382f567c463d14b7bd782b3fe10516685/taglib/mpeg/xingheader.cpp) | **Corroborating independent implementations**; no verified standalone normative VBRI specification | Conditional VBRI recognition and optional metadata-frame exclusion |
| R3003 | [RFC 3003: `audio/mpeg`](https://www.rfc-editor.org/rfc/rfc3003.html) and [IANA media registry](https://www.iana.org/assignments/media-types/) | IETF media-type definition/registration | `audio/mpeg` is canonical; MIME type does **not** imply the contained MPEG version is Layer III |
Expand All @@ -29,7 +31,7 @@ This directory is the **AI-agent and reviewer source register for this TypeScrip
1. **The assignment is narrower than generic `audio/mpeg`.** RFC 3003 can describe a stream with interspersed non-MPEG bytes; the endpoint intentionally accepts a stricter sequence: supported leading metadata, complete MPEG-1 Layer III frames and supported trailing metadata, without arbitrary junk resynchronization. That is an **application policy**, not a claim that RFC 3003 prohibits other layouts.
2. **Metadata tags are independent of the MPEG audio coding standard.** Implement only byte-boundary handling needed for accurate counts. ID3 text encodings, embedded artwork, replay gain, extended headers, ID3 frame content and CRC fields do **not** need full interpretation.
3. **Xing/Info/LAME and VBRI are de facto encoder headers, not additional MPEG layers.** They can inhabit MPEG frames. The owner selected HTTP exclusion of one recognized initial header for omitted/`false`; explicit `true` and direct parser calls with no option count physical frames. These are project policies, not ISO requirements. The evaluator confirmed audio-frame counting and sample result 6089 on 2026-10-26; implementation details beyond that clarification remain distinct. See the [count contract](../frame-count-contract.md).
4. **Free-format is not MPEG-2 or an invalid bitrate.** Index zero is a valid MPEG-1 Layer III encoding choice with no table-derived frame length. A decoder's size-search heuristic is evidence of interoperability, not the ISO text itself.
4. **Free-format is not MPEG-2 or an invalid bitrate.** Index zero is a valid MPEG-1 Layer III encoding choice with no table-derived frame length. Its per-sample-rate candidate limit is separate from the fixed observation budget. A decoder's size-search heuristic or minimum support requirement does not establish a normative upper limit; LAME extensions cannot compete with in-scope candidates.
5. **Full ISO Layer III bitstream conformance would require decoding-side checks** (side information, bit reservoir, Huffman, CRC, etc.). This assessment explicitly requests logical _frame counting_. Do not change the project into an audio decoder.

The [successive-sequence policy](successive-sequences.md) separately records ISO sequence invariants, RFC 3003 elementary-stream terminology, the MSE-specific W3C frame-combination profile and bounded project inference decisions. These are not universal unique-framing rules.
Expand Down
Loading
Loading