Skip to content

About

TypeScript MP3 frame analysis API

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

104 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

MP3 frame analyzer

A small, streaming TypeScript API that logically counts MPEG-1 Audio Layer III frames, without invoking an audio decoder or third-party MP3 parsing package. It answers an MP3 file analysis assessment, kept in this repository as the original brief.

Downloaded a release archive? Start with its RUNTIME.md, also available in the runtime guide. The steps below are for a source checkout.

Quick start

Requirements: Node.js 24 LTS (Node.js 26 is also tested) and npm 11.9 or later within major 11. Development and release CI use npm 11.19.0, recorded in packageManager; the verified bootstrap selects that exact bundle by SHA-512 without a global install. Dependencies are locked in package-lock.json; use npm ci for reproducible installation. The repository .npmrc deliberately disables automatic dependency/root lifecycle scripts, matching CI; native platform packages remain installed from the exact lock. Hooks are opt-in with npm run hooks:install, not installed by dependency postinstall.

npm ci
npm run build
npm start

Default server: http://127.0.0.1:3000. Set HOST and PORT to override; for example HOST=0.0.0.0 PORT=8080 npm start.

Upload-size configuration

Set MAX_UPLOAD_BYTES to override the 50 MiB (52,428,800 bytes) default for the server started by npm start or npm run dev. For example, to allow 100 MiB per file:

MAX_UPLOAD_BYTES=104857600 npm start

The value must contain only decimal digits and represent a positive safe integer from 1 through 9007199254740991 bytes. Leading zeros are decimal, not octal. An absent variable uses the default; an empty value, whitespace, signs, fractions, exponents, units, unsafe integers, or unlimited fail startup before listening. The same inclusive limit applies to raw uploads (declared length and streamed bytes, including chunked transfer) and multipart file bytes, not multipart envelope overhead. Requests over the limit return 413 file-too-large when the size violation is observed; an earlier malformed-file error can still win.

Multipart requests also have an aggregate body budget: MAX_MULTIPART_BYTES, by default the configured file limit plus 64 KiB (saturated at the maximum safe integer). It counts transfer-decoded HTTP body bytes, including multipart headers, preamble, epilogue and discarded bytes, not just the accepted file. It uses the same positive-decimal validation and can be lower than the file limit; then the envelope leaves less room for file bytes. Declared or observed excess closes the connection and returns 413 request-too-large unless an earlier response was already chosen. That earlier status and body are preserved, but the background drain stops and the connection still closes. This is not a wire-byte cap: a delivered chunk and transport buffers can contain excess data.

This is a deployment resource policy, not an MPEG format restriction. Raising it does not change request timeouts, parser behavior, or streaming memory bounds. For public deployment, configure reverse-proxy aggregate body, concurrency and rate limits separately. Embedded callers can continue to use buildApp({ maxUploadBytes }); buildApp() itself does not read the environment.

Per-instance upload admission

MAX_ACTIVE_UPLOADS defaults to 8 and accepts only decimal integers from 1 through 1024; there is no unlimited mode. Embedded callers use buildApp({ maxActiveUploads }). This is a conservative project default, not a promise that every deployment can sustain eight maximum-sized uploads or that 1024 is a safe setting. Measure your workload before tuning the runtime limits.

A slot stays occupied until its response and request transport finish and all upload-owned consumers, multipart iterators and background drains settle. Success, malformed input, abort, timeout and shutdown share this lifecycle. Overload sends 503 without reading/draining an attacker-controlled remainder, then closes that connection after the JSON response. Retry-After: 1 is a retry hint, not a guarantee of capacity; clients should use bounded backoff with jitter. There is no priority or per-client fairness guarantee. The cap is per app/server instance (normally one process), not shared across replicas, and does not bound all idle TCP connections. Public ingress still needs its own connection/rate policy.

Upload an MP3 as multipart/form-data:

curl -i -X POST http://127.0.0.1:3000/file-upload \
  -F 'file=@tests/fixtures/cbr.mp3;type=audio/mpeg'

Expected successful result for the bundled CBR fixture:

{ "frameCount": 32 }

The same endpoint also accepts a raw binary MP3 stream:

curl -i -X POST http://127.0.0.1:3000/file-upload \
  -H 'Content-Type: audio/mpeg' --data-binary @tests/fixtures/cbr.mp3

Both upload modes exclude one recognized initial Xing/Info or VBRI metadata frame by default. Explicit ?includeVbrHeaderFrame=false has the same behavior; append ?includeVbrHeaderFrame=true to count all physical MPEG frames. Files without a recognized initial metadata frame retain their full count. LAME data is recognized through its Xing/Info header, not as a separate frame.

This is an owner-approved change to the HTTP default and a breaking API contract change from the previous physical-frame default. The low-level countMp3Frames() function still counts physical frames unless its caller explicitly passes { includeVbrHeaderFrame: false }. The HTTP adapter always passes its selected policy.

The response uses Content-Type: application/json. For multipart uploads, the file field must be a single part. Supported MIME types are audio/mpeg, audio/mp3, and application/octet-stream; MIME is checked only as a preliminary filter, and the file contents must also contain valid MPEG-1 Layer III headers.

API

Situation HTTP status Error code / behavior
Valid raw or multipart MPEG-1 Layer III 200 {"frameCount":32} (bundled CBR fixture, default policy)
Observed missing/incomplete/malformed multipart, or invalid query 400 missing-file, invalid-upload, invalid-option
Empty raw or multipart file 400 empty-file
Invalid HTTP body framing / length 400 invalid-request when the connection remains writable
MP3 file exceeds per-file limit 413 file-too-large
Multipart body exceeds its separate aggregate budget 413 request-too-large unless an earlier response was chosen; connection closes in either case
Extra multipart file / form field / part 413 too-many-files, unexpected-fields, or too-many-parts, depending on the first limit reached
Other framework size limit 413 request-too-large
Unsupported MIME or MPEG format 415 unsupported-media-type or unsupported-format
Invalid, malformed, or truncated MP3 content 422 invalid-mp3 or truncated-mp3
Unknown route 404 not-found
Wrong method on /file-upload 405 method-not-allowed with Allow: POST
Upload admission exhausted 503 server-busy, Retry-After: 1, connection closes
Unexpected application failure 500 internal-error (sanitized)

Reserved MPEG version/layer identifiers and forbidden ID3 version/revision 0xff are malformed (422), not an identified unsupported format (415). Unknown ID3 major versions remain unsupported. See the source-backed input/error matrix for classification, precedence and the distinction between declared unsupported MIME types and mislabeled unknown bytes.

All application-generated error bodies use JSON with error and message strings. Limits apply to both raw and multipart uploads. Error classification follows the first observable failure: a malformed MPEG header can be rejected before a later size-limit violation or incomplete multipart ending is observable. An explicit oversized raw Content-Length is rejected early. Thus a later 413 or multipart 400 does not replace an already reported 422.

A rejected raw upload sends its JSON error with Connection: close rather than draining arbitrary additional bytes. Multipart consumer errors may drain for keep-alive reuse, but only if the complete body stays within the aggregate multipart budget and transport timeouts. A multipart-provider failure with unread body bytes closes after its error response because its drain is no longer guaranteed. Client disconnects, aborted/incomplete HTTP bodies, and native Node request-header timeouts may prevent any application JSON response; a client should not expect an HTTP response from a broken connection. An exhausted per-instance admission cap returns sanitized 503 server-busy, Retry-After: 1 and Connection: close before reading the upload body. No request waits in an application queue. 429 is not configured: this is concurrency admission, not rate limiting.

Frame-count convention

The endpoint traverses complete MPEG-1 Layer III frames and, by default, excludes a structurally recognized initial Xing/Info/VBRI metadata frame. The included CBR and VBR fixtures each contain 33 physical frames and return 32 by default, matching FFprobe's decoder-facing count for those files. With ?includeVbrHeaderFrame=true, both return 33. The count comes from traversal; encoder-declared frame counts are never used as the result.

The evaluator confirmed on 2026-10-26 that the assessment counts audio frames and expects 6089 for the supplied sample, with MediaInfo recommended as a sanity check. The existing API default returns 6089; explicit physical counting returns 6090. This structural policy does not decode audio and does not promise agreement with every decoder or metadata tool. The evidence, exact policies and compatibility implications are in the frame-count contract.

Implementation

  • src/mp3/frame-header.ts: pure MPEG-1 Layer III header decoder: indexed, free-format, unsupported or invalid, with the indexed frame-span formula.
  • src/mp3/frame-spans.ts: resolves each physical frame's span, discovering and locking a free-format stream's base length.
  • src/mp3/id3.ts: skips boundary-aligned ID3v2.2/2.3/2.4 tags and final ID3v1 by their encoded lengths, enforcing where each may appear.
  • src/mp3/byte-reader.ts: incremental lookahead and skipping over any AsyncIterable<Uint8Array>.
  • src/mp3/count-frames.ts: sequential frame traversal with no full-file buffering.
  • src/upload.ts: raw and multipart uploads, file limits and consumer cleanup; src/multipart-budget.ts bounds the complete multipart body, including background drains.
  • src/error-response.ts: one pure mapping from any failure to a stable, sanitized JSON error response.
  • src/app.ts: Fastify route, query option, response schemas, and error-handler wiring.
  • src/server.ts: configurable server bootstrap and graceful signal handling.

Complexity: O(n) time and O(max upstream chunk size) additional memory. Frame headers require only four bytes of lookahead, and metadata content is streamed past rather than accumulated.

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; 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. 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 remain explicit; this is not full bitstream or padding-schedule validation.

Verification

npm run check              # format + ESLint + strict typecheck + coverage tests + build
npm test                   # unit / property / integration / real HTTP E2E
npm run test:coverage
npm run test:fuzz          # builds first, then deterministic mutation smoke (2,000 inputs)
FUZZ_CASES=10000 npm run test:fuzz
npm run fuzz:regression    # replay tracked and generated Jazzer cases
npm run fuzz:coverage      # 8 seconds per target, coverage-guided
npm run fuzz:extended      # 120 seconds per target, on-demand
npm run test:memory        # distinct chunks, independent 8/32/128 MiB processes
npm run test:performance   # two local 32 MiB uploads plus small-upload probes
npm run bench              # Vitest Bench microbenchmark
npm run mutation           # Full parser; native same-input result reuse
npm run mutation:full      # Force every mutant to execute; 100% adjusted gate

tests/ includes deterministic binary fixtures, structured property testing with fast-check, actual FFmpeg-encoded MP3s, HTTP injection tests, and a real TCP upload test. The mutation smoke harness is separate from the coverage-guided Jazzer.js 4 targets. A raw-byte target detects crashes and chunk-dependent results; an independent structured-frame generator detects incorrect positive counts. Their seeds, regression corpus, minimizer, and limits are documented in Fuzzing.

For manual FFprobe comparison:

ffprobe -v error -select_streams a:0 -count_frames \
  -show_entries stream=nb_read_frames \
  -of default=noprint_wrappers=1:nokey=1 tests/fixtures/cbr.mp3

The expected FFprobe output for this fixture is 32, matching the default HTTP response. Its physical frame count is 33. See MP3 counting semantics.

Optional HTTP load test with k6:

npm run build && npm start
# In another terminal:
k6 run bench/upload.k6.js

Developer workflow / security

  • Node 24, native TypeScript 7 with the TypeScript 6 API compatibility alias, strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, ESM.
  • ESLint + type-aware typescript-eslint, maintained Node security rules for application code, JS/MJS linting for build/fuzz/benchmark scripts, enforced production cyclomatic complexity limits (errors above 10), advisory test complexity warnings above 16, and Prettier. See code quality limits.
  • Vitest/V8 coverage with enforced thresholds; fast-check properties; mutation smoke, Jazzer.js coverage-guided fuzzing, and replayable crash regressions.
  • Lefthook optional local hooks: npm run hooks:install. Pre-commit uses the installed locked Prettier CLI (no npx acquisition fallback) for staged formatting and Betterleaks staged secrets (v1.9.0). Pre-push runs npm run check.
  • GitHub Actions CI checks Node 24 and 26, a clean npm 11.9 installation, build/test/type/lint, focused mutation testing, bounded fuzzing, memory scaling, local HTTP measurements, complete and production dependency audits, workflow validation, Git-history secret scanning, fixed-config runtime architecture SAST, and an unpacked release artifact. Weekly dependency audits catch newly published advisories.
  • GitHub Actions are pinned to commit SHAs; validation jobs have read-only repository permissions and checkouts do not persist credentials. Dependabot monitors npm and Actions dependencies. Release automation has separate, narrowly scoped write permissions.

The staged secrets hook needs Betterleaks installed locally; the hook fails closed if Betterleaks is unavailable after you opt in. Before submission, run npm ci, npm run format:check, and npm run check from a clean checkout. The application itself has no credentials, database, cloud dependencies, or deployment secrets. See Security model.

Versions and releases

Release Please derives version bumps and a changelog from Conventional Commit PR titles, preserved with Squash and merge. fix: / perf: increment the patch version, feat: increments the minor version, and ! marks a breaking change. Labels do not decide versions. The generated release PR updates the package, lockfile, version manifest, and changelog; a maintainer reviews and merges it to approve a release.

Release CI validates the exact tagged commit and publishes a runtime archive containing compiled JavaScript, a lockfile for production dependency installation, checksums, release metadata, and a production SBOM. It installs and runs the unpacked archive before those same bytes can be attached to the GitHub Release. No npm registry publication or production deployment is configured.

npm run check
npm run package:release    # packages the existing dist/ build; also creates SBOM/checksums
npm run test:artifact      # fresh production install, real upload, graceful shutdown

See Releasing and repository settings for the enforced GitHub settings, the release approval, permissions, artifact verification, provenance availability, and recovery of an interrupted release.

Authoritative format specifications and AI agent context

The documents distinguish actual ISO/IETF requirements, ID3 informal standards, de facto encoder conventions and deliberate assessment implementation limits. They are concise original summaries with links to original publishers, not a copy of the ISO standard or a claim of full MPEG audio-decoder conformance.

More detail

Native TypeScript 7 and API compatibility

The build and typecheck use TypeScript 7.0.2's native tsc, while typescript-eslint uses the TypeScript 6 compiler API exposed by the typescript npm alias to @typescript/typescript6. tsc6 runs a secondary compatibility check. This is Microsoft's official side-by-side transition guidance; install with npm ci, without --legacy-peer-deps.

TODO.md tracks removal of the second compiler with a December 15, 2026 review target, conditional on stable tooling support.

Verify the supplied sample

The supplied assessment MP3 is intentionally not redistributed in this repository. Set its location and execute:

npm run verify:sample -- /path/to/assessment_sample.mp3
ASSESSMENT_SAMPLE_PATH=/path/to/assessment_sample.mp3 npm run test:coverage

The sample SHA-256 is 97707a18a58ba75122b1668f5ed738f090121343432d9172a6409ddfa4fc5ab3. The API returns {"frameCount":6089} by default and with ?includeVbrHeaderFrame=false; ?includeVbrHeaderFrame=true returns 6090. These expectations apply to both raw and multipart uploads. The first MPEG frame carries the Xing header. FFprobe and MediaInfo also report 6089 for this file. The evaluator's dated clarification confirms the audio-frame requirement and sample result 6089. See the frame-count contract.

The parser modules have 100% coverage across statements, branches, functions and lines using actual edge-case tests. The HTTP adapter retains defensive branches without manufacturing test-only faults to obtain 100% overall coverage. See Testing for mutation testing and security verification.

Full-parser mutation gate

npm run mutation now tests every parser TypeScript module under src/mp3/**/*.ts. The raw Stryker JSON report is preserved unchanged. A separate fail-closed audit requires 100% detection after narrowly reviewed behaviorally equivalent mutations. Exceptions match source hashes, exact expressions, mutation operators and replacements in mutation-equivalents.json, never whole source lines or mutation families. Native Vitest per-test coverage avoids repeatedly running unrelated tests. Compatible PRs can reuse native results from an authenticated successful main baseline. Changed declared source/test/helper/resource/config inputs or a missing compatible baseline fall back to full; releases and weekly verification always run full. Fresh and reused results are counted separately. Audit design and cache safety/verification.

About

TypeScript MP3 frame analysis API

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages