Skip to content

AGENTS.md

Latest commit

 

History

History
43 lines (37 loc) · 1.64 KB

AGENTS.md

File metadata and controls

43 lines (37 loc) · 1.64 KB
Raw

MP3 Parser API - Agent Context

Overview

REST API that accepts MP3 file uploads and returns the frame count. Built with Bun runtime and Elysia framework.

Tech Stack

  • Runtime: Bun
  • Framework: Elysia
  • Language: TypeScript (strict mode)
  • Testing: Bun's native test runner
  • Linting/Formatting: Biome

Project Structure

  • src/index.ts - API server, /file-upload POST endpoint
  • src/parser/ - MP3 parsing module
    • mp3-parser.ts - Core parser class, countFrames() returns number directly
    • constants.ts - MPEG1 Layer3 bitrates, sample rates, sync patterns, bit masks
    • types.ts - TypeScript interfaces (FrameHeader)
    • errors.ts - Custom error classes
  • tests/ - Test files (separate from source)
    • index.test.ts - API integration tests
    • parser/mp3-parser.test.ts - Parser unit tests

MP3 Parsing Approach

  1. Skip ID3v2 metadata tags (detected by "ID3" magic bytes)
  2. Scan for frame sync pattern (0xFF followed by 0xE0 mask)
  3. Parse 4-byte frame header to extract version, layer, bitrate, sample rate
  4. Only count MPEG Version 1 Layer 3 frames (by design requirement)
  5. Calculate frame size: floor((144 * bitrate * 1000) / sampleRate) + padding
  6. Skip Xing/Info VBR header frames (metadata, not audio)

Commands

  • bun run dev - Start dev server with hot reload
  • bun test - Run test suite
  • bun run lint - Lint code
  • bun run format - Format code
  • bun run check - Lint + format check

API

  • Endpoint: POST /file-upload
  • Request: multipart/form-data with file field
  • Success Response: { "frameCount": number } (200)
  • Error Response: { "error": string } (400/500)