@maxmellon/cue-parser 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MaxMEllon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,374 @@
+# CUE Parser
+
+A TypeScript library for parsing CUE sheet files according to the [CUE Sheet specification](https://wyday.com/cuesharp/specification.php).
+
+🌐 **[Live Demo](https://melocil.de/cue-parser/)** - Try the CUE parser online!
+
+## 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
+
+```bash
+npm install cue-parser
+```
+
+## CLI Usage
+
+After installation, you can use the `cue-parser` command directly:
+
+```bash
+# 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:**
+```bash
+$ 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:**
+```bash
+$ cue-parser album.cue --json
+{
+  "global": {
+    "title": "My Album",
+    "performer": "My Artist"
+  },
+  "tracks": [...]
+}
+```
+
+**CUE format output:**
+```bash
+$ 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:**
+```bash
+$ 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:**
+```bash
+$ cue-parser album.cue --validate --stats
+
+✅ Validation successful
+
+📊 Parsing Statistics
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ Successfully parsed
+   Tracks: 3
+   Indexes: 5
+   Files referenced: 2
+```
+
+## Library Usage
+
+### Basic Parsing
+
+```typescript
+import { parseCueSheet } from '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
+
+```typescript
+import { CueParser } from '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
+
+```typescript
+import { parseHMSTime, formatHMSTime, hmsToSeconds } from '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
+
+```typescript
+import { parseCueSheet, serializeCueSheet, formatCueSheet, createMinimalCueSheet } from '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.
+
+```typescript
+interface CueSheet {
+  global: CueGlobal;
+  tracks: Track[];
+}
+```
+
+#### `ParseResult`
+The result of parsing a CUE sheet.
+
+```typescript
+interface ParseResult {
+  cueSheet?: CueSheet;
+  errors: ParseError[];
+  warnings: ParseError[];
+}
+```
+
+#### `MSFTime`
+Represents time in Minutes:Seconds:Frames format.
+
+```typescript
+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:
+
+```typescript
+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
+
+```bash
+# 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](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/bin/index.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { parseCueSheet, formatHMSTime, hmsToSeconds, serializeCueSheet, formatCueSheet, createMinimalCueSheet, serializeYouTubeTimeline } from '../dist/src/index.js';
+
+/**
+ * CUE Parser CLI
+ */
+
+function showHelp() {
+  console.log(`
+CUE Parser CLI
+
+Usage:
+  cue-parser <file.cue> [options]
+
+Options:
+  -h, --help       Show this help message
+  -v, --version    Show version
+  -j, --json       Output as JSON
+  -c, --cue        Output as CUE sheet format
+  --minimal        Output minimal CUE sheet (with --cue)
+  -q, --quiet      Only show errors
+  --validate       Only validate, don't output parsed content
+  --stats          Show parsing statistics
+  --youtube        Output YouTube timeline format
+
+Examples:
+  cue-parser album.cue
+  cue-parser album.cue --json
+  cue-parser album.cue --cue
+  cue-parser album.cue --cue --minimal
+  cue-parser album.cue --validate
+  cue-parser album.cue --stats
+  cue-parser album.cue --youtube
+`);
+}
+
+function showVersion() {
+  try {
+    const packageJson = JSON.parse(readFileSync(resolve(new URL(import.meta.url).pathname, '../../package.json'), 'utf-8'));
+    console.log(`cue-parser v${packageJson.version}`);
+  } catch (error) {
+    console.log('cue-parser (version unknown)');
+  }
+}
+
+function formatTime(time) {
+  if (!time) return 'N/A';
+  const timeStr = formatHMSTime(time);
+  const seconds = msfToSeconds(time);
+  return `${timeStr} (${seconds.toFixed(2)}s)`;
+}
+
+function displayYouTubeTimeline(cueSheet) {
+  console.log(serializeYouTubeTimeline(cueSheet));
+}function displayCueSheet(cueSheet, options = {}) {
+  if (options.json) {
+    console.log(JSON.stringify(cueSheet, null, 2));
+    return;
+  }
+
+  if (options.youtube) {
+    displayYouTubeTimeline(cueSheet);
+    return;
+  }
+
+  if (options.cue) {
+    if (options.minimal) {
+      console.log(createMinimalCueSheet(cueSheet));
+    } else {
+      console.log(formatCueSheet(cueSheet, { trackSpacing: true }));
+    }
+    return;
+  }
+
+  // Display global information
+  console.log('📀 CUE Sheet Information');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  const global = cueSheet.global;
+  if (global.title) console.log(`Title:     ${global.title}`);
+  if (global.performer) console.log(`Artist:    ${global.performer}`);
+  if (global.songwriter) console.log(`Songwriter: ${global.songwriter}`);
+  if (global.composer) console.log(`Composer:  ${global.composer}`);
+  if (global.arranger) console.log(`Arranger:  ${global.arranger}`);
+  if (global.catalog) console.log(`Catalog:   ${global.catalog}`);
+  if (global.cdTextFile) console.log(`CD-TEXT:   ${global.cdTextFile}`);
+  if (global.genre) console.log(`Genre:     ${global.genre}`);
+  if (global.upcEan) console.log(`UPC/EAN:   ${global.upcEan}`);
+  if (global.message) console.log(`Message:   ${global.message}`);
+
+  console.log(`\n🎵 Tracks (${cueSheet.tracks.length})`);
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  cueSheet.tracks.forEach((track, index) => {
+    console.log(`\n[${track.number.toString().padStart(2, '0')}] ${track.title || 'Untitled'}`);
+    console.log(`     Mode: ${track.mode}`);
+
+    if (track.performer && track.performer !== global.performer) {
+      console.log(`     Artist: ${track.performer}`);
+    }
+    if (track.songwriter) console.log(`     Songwriter: ${track.songwriter}`);
+    if (track.composer) console.log(`     Composer: ${track.composer}`);
+    if (track.arranger) console.log(`     Arranger: ${track.arranger}`);
+    if (track.isrc) console.log(`     ISRC: ${track.isrc}`);
+    if (track.message) console.log(`     Message: ${track.message}`);
+
+    if (track.file) {
+      console.log(`     File: ${track.file.filename}${track.file.format ? ` (${track.file.format})` : ''}`);
+    }
+
+    if (track.flags && track.flags.length > 0) {
+      console.log(`     Flags: ${track.flags.join(', ')}`);
+    }
+
+    if (track.pregap) {
+      console.log(`     Pregap: ${formatTime(track.pregap)}`);
+    }
+
+    if (track.indexes && track.indexes.length > 0) {
+      console.log('     Indexes:');
+      track.indexes.forEach(idx => {
+        console.log(`       ${idx.number.toString().padStart(2, '0')}: ${formatTime(idx.time)}`);
+      });
+    }
+
+    if (track.postgap) {
+      console.log(`     Postgap: ${formatTime(track.postgap)}`);
+    }
+  });
+}
+
+function displayStats(result, options = {}) {
+  const { cueSheet, errors, warnings } = result;
+
+  console.log('\n📊 Parsing Statistics');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+
+  if (cueSheet) {
+    console.log(`✅ Successfully parsed`);
+    console.log(`   Tracks: ${cueSheet.tracks.length}`);
+
+    const totalIndexes = cueSheet.tracks.reduce((sum, track) =>
+      sum + (track.indexes ? track.indexes.length : 0), 0);
+    console.log(`   Indexes: ${totalIndexes}`);
+
+    const filesUsed = new Set(cueSheet.tracks
+      .map(track => track.file?.filename)
+      .filter(Boolean));
+    console.log(`   Files referenced: ${filesUsed.size}`);
+
+    // Calculate total duration if possible
+    const lastTrack = cueSheet.tracks[cueSheet.tracks.length - 1];
+    if (lastTrack?.indexes && lastTrack.indexes.length > 0) {
+      const lastIndex = lastTrack.indexes[lastTrack.indexes.length - 1];
+      if (lastIndex.time) {
+        console.log(`   Approximate duration: ${formatTime(lastIndex.time)}`);
+      }
+    }
+  } else {
+    console.log(`❌ Parsing failed`);
+  }
+
+  if (warnings.length > 0) {
+    console.log(`⚠️  Warnings: ${warnings.length}`);
+  }
+
+  if (errors.length > 0) {
+    console.log(`🚨 Errors: ${errors.length}`);
+  }
+}
+
+function displayErrors(errors, warnings, options = {}) {
+  if (warnings.length > 0 && !options.quiet) {
+    console.log('\n⚠️  Warnings:');
+    warnings.forEach(warning => {
+      console.log(`   Line ${warning.line}: ${warning.message}`);
+    });
+  }
+
+  if (errors.length > 0) {
+    console.log('\n🚨 Errors:');
+    errors.forEach(error => {
+      console.log(`   Line ${error.line}: ${error.message}`);
+      if (!options.quiet && error.rawLine.trim()) {
+        console.log(`      → ${error.rawLine.trim()}`);
+      }
+    });
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args.includes('-h') || args.includes('--help')) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args.includes('-v') || args.includes('--version')) {
+    showVersion();
+    process.exit(0);
+  }
+
+  const options = {
+    json: args.includes('-j') || args.includes('--json'),
+    cue: args.includes('-c') || args.includes('--cue'),
+    minimal: args.includes('--minimal'),
+    quiet: args.includes('-q') || args.includes('--quiet'),
+    validate: args.includes('--validate'),
+    stats: args.includes('--stats'),
+    youtube: args.includes('--youtube')
+  };
+
+  // Find the file path (first non-option argument)
+  const filePath = args.find(arg => !arg.startsWith('-'));
+
+  if (!filePath) {
+    console.error('❌ Error: No input file specified');
+    console.error('Use --help for usage information');
+    process.exit(1);
+  }
+
+  const resolvedPath = resolve(filePath);
+
+  if (!existsSync(resolvedPath)) {
+    console.error(`❌ Error: File not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+
+  try {
+    const content = readFileSync(resolvedPath, 'utf-8');
+    const result = parseCueSheet(content);
+
+    // Always show errors
+    if (result.errors.length > 0 || result.warnings.length > 0) {
+      displayErrors(result.errors, result.warnings, options);
+    }
+
+    // Exit with error code if parsing failed
+    if (result.errors.length > 0) {
+      if (options.validate) {
+        console.log('\n❌ Validation failed');
+      }
+      process.exit(1);
+    }
+
+    if (options.validate) {
+      console.log('\n✅ Validation successful');
+      if (options.stats) {
+        displayStats(result, options);
+      }
+      process.exit(0);
+    }
+
+    if (result.cueSheet) {
+      if (!options.quiet) {
+        displayCueSheet(result.cueSheet, options);
+      }
+
+      if (options.stats) {
+        displayStats(result, options);
+      }
+    }
+
+    process.exit(0);
+
+  } catch (error) {
+    console.error(`❌ Error reading file: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+// Handle unhandled promise rejections
+process.on('unhandledRejection', (error) => {
+  console.error('❌ Unhandled error:', error);
+  process.exit(1);
+});
+
+// Run the CLI
+main();

package/dist/src/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * CUE Sheet Parser
+ *
+ * A TypeScript library for parsing CUE sheet files according to the specification.
+ *
+ * @example
+ * ```typescript
+ * import { parseCueSheet, CueParser } from '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"
+ * }
+ * ```
+ */
+export type { HMSTime, TrackFlag, TrackMode, FileFormat, CDText, TrackIndex, FileInfo, Track, CueGlobal, CueSheet, ParseError, ParseResult } from './types.js';
+export { parseHMSTime, formatHMSTime, formatCueTime, hmsToSeconds, secondsToHMS, msfToFrames, framesToMSF, addHMSTime, subtractHMSTime, compareHMSTime } from './utils.js';
+export { CueParser, parseCueSheet } from './parser.js';
+export { serializeCueSheet, formatCueSheet, createMinimalCueSheet } from './serializer.js';
+export { serializeYouTubeTimeline } from './youtube-serializer.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,YAAY,EACV,OAAO,EACP,SAAS,EACT,SAAS,EACT,UAAU,EACV,MAAM,EACN,UAAU,EACV,QAAQ,EACR,KAAK,EACL,SAAS,EACT,QAAQ,EACR,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,WAAW,EACX,UAAU,EACV,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGvD,OAAO,EACL,iBAAiB,EACjB,cAAc,EACd,qBAAqB,EACtB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC"}