CUE Parser

A TypeScript library for parsing CUE sheet files according to the CUE Sheet specification.

🌐 Live Demo - Try the CUE parser online! 📦 npm: @maxmellon/cue-parser

Features

• 🎵 Complete CUE sheet parsing support
• 📝 TypeScript type definitions
• ⏱️ MSF (Minutes:Seconds:Frames) time format utilities
• 🚨 Comprehensive error handling and validation
• 📊 Detailed parse results with errors and warnings
• 🎯 Support for all standard CUE sheet commands

Installation

npm install @maxmellon/cue-parser

CLI Usage

After installation, you can use the cue-parser command directly. To run it without installing, use npx @maxmellon/cue-parser album.cue.

# Parse and display a CUE file
cue-parser album.cue

# Output as JSON
cue-parser album.cue --json

# Output as CUE sheet format
cue-parser album.cue --cue

# Output minimal CUE sheet
cue-parser album.cue --cue --minimal

# Validate only (no output)
cue-parser album.cue --validate

# Show parsing statistics
cue-parser album.cue --stats

# Quiet mode (errors only)
cue-parser album.cue --quiet

# Show help
cue-parser --help

# Show version
cue-parser --version

CLI Options

• -h, --help - Show help message
• -v, --version - Show version
• -j, --json - Output as JSON
• -c, --cue - Output as CUE sheet format
• --minimal - Output minimal CUE sheet (use with --cue)
• -q, --quiet - Only show errors
• --validate - Only validate, don't output parsed content
• --stats - Show parsing statistics

CLI Examples

Basic parsing:

$ cue-parser album.cue

📀 CUE Sheet Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Title:     My Album
Artist:    My Artist
Catalog:   1234567890123

🎵 Tracks (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[01] Track One
     Mode: AUDIO
     File: audio.wav (WAVE)
     Indexes:
       01: 00:00:00 (0.00s)

JSON output:

$ cue-parser album.cue --json
{
  "global": {
    "title": "My Album",
    "performer": "My Artist"
  },
  "tracks": [...]
}

CUE format output:

$ cue-parser album.cue --cue
TITLE "My Album"
PERFORMER "My Artist"

FILE "audio.wav" WAVE
  TRACK 01 AUDIO
    TITLE "Track One"
    INDEX 01 00:00:00

Minimal CUE format:

$ cue-parser album.cue --cue --minimal
TITLE "My Album"
PERFORMER "My Artist"
FILE "audio.wav" WAVE
  TRACK 01 AUDIO
    TITLE "Track One"
    INDEX 01 00:00:00

Validation with statistics:

$ cue-parser album.cue --validate --stats

✅ Validation successful

📊 Parsing Statistics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Successfully parsed
   Tracks: 3
   Indexes: 5
   Files referenced: 2

Library Usage

Basic Parsing

import { parseCueSheet } from '@maxmellon/cue-parser';

const cueContent = `
TITLE "Example Album"
PERFORMER "Example Artist"
FILE "audio.wav" WAVE
  TRACK 01 AUDIO
    TITLE "Track 1"
    INDEX 01 00:00:00
`;

const result = parseCueSheet(cueContent);

if (result.cueSheet) {
  console.log(result.cueSheet.global.title); // "Example Album"
  console.log(result.cueSheet.tracks[0].title); // "Track 1"
} else {
  console.error('Parse errors:', result.errors);
}

Using the Parser Class

import { CueParser } from '@maxmellon/cue-parser';

const parser = new CueParser();
const result = parser.parse(cueContent);

// Check for errors and warnings
if (result.errors.length > 0) {
  result.errors.forEach(error => {
    console.error(`Line ${error.line}: ${error.message}`);
  });
}

if (result.warnings.length > 0) {
  result.warnings.forEach(warning => {
    console.warn(`Line ${warning.line}: ${warning.message}`);
  });
}

Working with MSF Time Format

import { parseHMSTime, formatHMSTime, hmsToSeconds } from '@maxmellon/cue-parser';

// Parse MSF time string
const time = parseHMSTime('1:30:45'); // { hour: 1, minute: 30, second: 45 }

// Format MSF time back to string
const timeStr = formatHMSTime(time); // "01:30:45"

// Convert to seconds
const totalSeconds = hmsToSeconds(time); // 5445 seconds

Serializing CUE Sheets

import { parseCueSheet, serializeCueSheet, formatCueSheet, createMinimalCueSheet } from '@maxmellon/cue-parser';

const result = parseCueSheet(cueContent);

if (result.cueSheet) {
  // Basic serialization
  const cueString = serializeCueSheet(result.cueSheet);

  // Formatted with spacing
  const formatted = formatCueSheet(result.cueSheet, { trackSpacing: true });

  // Minimal version (essential fields only)
  const minimal = createMinimalCueSheet(result.cueSheet);

  console.log(cueString);
}

Supported CUE Sheet Commands

Global Commands

• CATALOG - Sets the catalog number of the CD
• CDTEXTFILE - Sets an external file for CD-TEXT data
• TITLE - Title of the album
• PERFORMER - Name(s) of the performer(s)
• SONGWRITER - Name(s) of the songwriter(s)
• COMPOSER - Name(s) of the composer(s)
• ARRANGER - Name(s) of the arranger(s)
• MESSAGE - Message from the content provider and/or artist
• DISC_ID - Disc identification information
• GENRE - Genre identification
• UPC_EAN - UPC/EAN code of the album
• REM - Comment lines

Track Commands

• FILE - Sets a new input file
• TRACK - Starts a new track
• INDEX - Sets a track index
• PREGAP - Sets track pregap
• POSTGAP - Sets track postgap
• FLAGS - Sets track flags (PRE, DCP, 4CH, SCMS)
• ISRC - Sets track ISRC number
• TITLE - Track title
• PERFORMER - Track performer
• SONGWRITER - Track songwriter
• COMPOSER - Track composer
• ARRANGER - Track arranger
• MESSAGE - Track message

Supported File Formats

• BINARY
• MOTOROLA
• AIFF
• WAVE
• MP3

Supported Track Modes

• AUDIO
• CDG
• MODE1/2048
• MODE1/2352
• MODE2/2336
• MODE2/2352
• CDI/2336
• CDI/2352

API Reference

Types

CueSheet

The main interface representing a parsed CUE sheet.

interface CueSheet {
  global: CueGlobal;
  tracks: Track[];
}

ParseResult

The result of parsing a CUE sheet.

interface ParseResult {
  cueSheet?: CueSheet;
  errors: ParseError[];
  warnings: ParseError[];
}

MSFTime

Represents time in Minutes:Seconds:Frames format.

interface MSFTime {
  minutes: number;
  seconds: number;
  frames: number; // 0-74 (1/75 of a second)
}

Functions

parseCueSheet(content: string): ParseResult

Parses a CUE sheet from string content.

parseHMSTime(timeString: string): HMSTime

Parses an HMS time string (e.g., "1:30:45") into an HMSTime object.

formatHMSTime(time: HMSTime, zeroPad?: boolean): string

Formats an HMSTime object back to string format.

hmsToSeconds(time: HMSTime): number

Converts HMS time to total seconds.

secondsToHMS(seconds: number): HMSTime

Converts seconds to HMS time format.

serializeCueSheet(cueSheet: CueSheet): string

Serializes a CueSheet object back to CUE sheet format string.

formatCueSheet(cueSheet: CueSheet, options?: object): string

Formats a CueSheet with proper indentation and spacing options.

createMinimalCueSheet(cueSheet: CueSheet): string

Creates a minimal CUE sheet with only essential information.

Error Handling

The parser provides detailed error information including line numbers and descriptions:

const result = parseCueSheet(invalidContent);

if (result.errors.length > 0) {
  result.errors.forEach(error => {
    console.error(`Parse error on line ${error.line}: ${error.message}`);
    console.error(`Raw line: ${error.rawLine}`);
  });
}

Examples

See the examples/ directory for sample CUE files and usage examples.

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.