mix-id 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scott Bell
+
+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,121 @@
+# mix-id
+
+Identify every track in a DJ mix — from a local file or streaming URL.
+
+```
+$ npx mix-id https://soundcloud.com/dj/my-set
+
+📥 Downloading...
+✅ my-set.mp3 (142.3 MB)
+
+🎵 mix-id
+──────────────────────────────────────────────────
+File:     my-set.mp3
+Duration: 1:30:12
+Settings: 30s step, 18s sample
+──────────────────────────────────────────────────
+
+[00:00] 1% ✅ The Orb — Little Fluffy Clouds
+[00:30] 1% ↩️  The Orb — Little Fluffy Clouds
+[01:00] 2% ✅ Surface — Falling in Love
+...
+
+──────────────────────────────────────────────────
+🎧 TRACKLIST — my-set.mp3
+──────────────────────────────────────────────────
+ 1. [00:00] The Orb — Little Fluffy Clouds
+ 2. [01:00] Surface — Falling in Love
+ 3. [04:30] Madonna — Vogue
+──────────────────────────────────────────────────
+
+💾 Output:
+   my-set_tracklist.txt
+   my-set.cue
+   my-set_tracklist.json
+```
+
+## Install
+
+```bash
+npm install -g mix-id
+```
+
+Or run directly:
+
+```bash
+npx mix-id my-mix.mp3
+```
+
+### Requirements
+
+- **Node.js** 18+
+- **ffmpeg** — audio processing (`brew install ffmpeg`)
+- **yt-dlp** — URL downloads (`brew install yt-dlp`) — only needed for URLs
+
+## Usage
+
+```bash
+# Local file
+mix-id my-mix.mp3
+
+# SoundCloud
+mix-id https://soundcloud.com/dj/set-name
+
+# Mixcloud
+mix-id https://www.mixcloud.com/dj/show-name
+
+# YouTube
+mix-id https://www.youtube.com/watch?v=...
+
+# Custom scan settings
+mix-id my-mix.mp3 --step 60 --segment 20
+
+# Resume from a specific position
+mix-id my-mix.mp3 --start 3600
+```
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--step` | `30` | Seconds between scan points |
+| `--segment` | `18` | Sample length for recognition |
+| `--start` | `0` | Skip to this position (seconds) |
+| `--help` | | Show help |
+
+## Output
+
+mix-id generates three files:
+
+- **`_tracklist.txt`** — Paste-friendly format for Mixcloud, etc.
+- **`.cue`** — CUE sheet with track markers and timestamps
+- **`_tracklist.json`** — Structured data with full metadata
+
+## How it works
+
+1. Downloads audio from URL (if given) using yt-dlp
+2. Splits the audio into overlapping segments
+3. Fingerprints each segment via Shazam's recognition API
+4. Deduplicates consecutive matches (handles DJ transitions)
+5. Outputs clean tracklist in multiple formats
+
+## Supported sources
+
+Any URL that [yt-dlp](https://github.com/yt-dlp/yt-dlp) supports — that's **1000+ sites** including:
+
+- SoundCloud
+- Mixcloud
+- YouTube
+- Bandcamp
+- And many more
+
+## Tips
+
+- **Longer mixes?** The default 30s step works well. Use `--step 60` to scan faster at the cost of precision.
+- **Transitions fuzzy?** Shazam sometimes bounces between two tracks during a mix. mix-id deduplicates these automatically.
+- **No API key needed.** mix-id uses Shazam's public recognition endpoint.
+- **Rate limited?** mix-id waits 2s between requests to be respectful. A 2-hour mix takes ~8 minutes to scan.
+
+## License
+
+MIT

package/cli.mjs

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * mix-id — Identify tracks in any DJ mix.
+ *
+ * Usage:
+ *   mix-id <file-or-url> [options]
+ *
+ * Examples:
+ *   mix-id my-mix.mp3
+ *   mix-id https://soundcloud.com/dj/set-name
+ *   mix-id https://www.mixcloud.com/dj/show-name
+ *   mix-id https://youtube.com/watch?v=... --step 60
+ */
+
+import { existsSync } from 'fs';
+import { basename } from 'path';
+import { scan } from './lib/scanner.mjs';
+import { dedupe, formatTime, writeTXT, writeCUE, writeJSON } from './lib/format.mjs';
+import { downloadURL, fileSize, hasCommand } from './lib/audio.mjs';
+
+// --- Parse args ---
+
+const args = process.argv.slice(2);
+const flags = {};
+const positional = [];
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i].startsWith('--')) {
+    const key = args[i].slice(2);
+    flags[key] = args[i + 1] || true;
+    i++;
+  } else {
+    positional.push(args[i]);
+  }
+}
+
+const input = positional[0];
+const step = parseInt(flags.step || '30');
+const segment = parseInt(flags.segment || '18');
+const start = parseInt(flags.start || '0');
+
+if (!input || flags.help) {
+  console.log(`
+  mix-id — Identify tracks in any DJ mix.
+
+  Usage:
+    mix-id <file-or-url> [options]
+
+  Options:
+    --step <sec>      Time between scan points (default: 30)
+    --segment <sec>   Sample length for recognition (default: 18)
+    --start <sec>     Skip to position before scanning (default: 0)
+    --help            Show this help
+
+  Examples:
+    mix-id my-mix.mp3
+    mix-id https://soundcloud.com/dj/set-name
+    mix-id mix.wav --step 60 --segment 20
+
+  Requirements:
+    ffmpeg    Audio processing (brew install ffmpeg)
+    yt-dlp    URL downloads (brew install yt-dlp)
+  `);
+  process.exit(input ? 0 : 1);
+}
+
+// --- Preflight checks ---
+
+if (!hasCommand('ffmpeg') || !hasCommand('ffprobe')) {
+  console.error('❌ ffmpeg is required. Install: brew install ffmpeg');
+  process.exit(1);
+}
+
+// --- Resolve input ---
+
+const isURL = /^https?:\/\//i.test(input);
+let file;
+
+if (isURL) {
+  console.log(`\n📥 Downloading...`);
+  console.log(`   ${input}\n`);
+  file = downloadURL(input, process.cwd());
+  console.log(`✅ ${basename(file)} (${fileSize(file)})\n`);
+} else {
+  file = input;
+}
+
+if (!existsSync(file)) {
+  console.error(`❌ File not found: ${file}`);
+  process.exit(1);
+}
+
+// --- Scan ---
+
+const result = await scan(file, { step, segment, start });
+
+// --- Dedupe & output ---
+
+const tracks = dedupe(result.tracks);
+
+if (tracks.length === 0) {
+  console.log('\n❌ No tracks identified.');
+  process.exit(0);
+}
+
+// Print tracklist
+console.log('\n' + '─'.repeat(50));
+console.log(`🎧 TRACKLIST — ${basename(file)}`);
+console.log('─'.repeat(50));
+tracks.forEach((t, i) => {
+  const num = String(i + 1).padStart(2);
+  const album = t.album ? ` [${t.album}]` : '';
+  console.log(`${num}. [${t.timestamp}] ${t.artist} — ${t.title}${album}`);
+});
+const removed = result.tracks.length - tracks.length;
+if (removed > 0) console.log(`\n🔄 ${removed} duplicate(s) removed`);
+console.log('─'.repeat(50));
+
+// Write files
+const base = file.replace(/\.[^.]+$/, '');
+const audioFilename = basename(file);
+
+writeTXT(tracks, base + '_tracklist.txt');
+writeCUE(tracks, base + '.cue', audioFilename);
+writeJSON(tracks, base + '_tracklist.json', {
+  source: audioFilename,
+  duration: result.duration,
+  segments_scanned: result.segmentsScanned,
+});
+
+console.log(`\n💾 Output:`);
+console.log(`   ${base}_tracklist.txt`);
+console.log(`   ${base}.cue`);
+console.log(`   ${base}_tracklist.json`);

package/lib/audio.mjs

@@ -0,0 +1,84 @@
+/**
+ * Audio utilities — download, probe, and extract segments.
+ */
+
+import { execSync, spawnSync } from 'child_process';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, basename } from 'path';
+
+/** Check if a command exists on PATH. */
+export function hasCommand(cmd) {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Get audio duration in seconds via ffprobe. */
+export function getDuration(file) {
+  const out = execSync(
+    `ffprobe -v quiet -print_format json -show_format "${file}"`,
+    { encoding: 'utf8' }
+  );
+  return parseFloat(JSON.parse(out).format.duration);
+}
+
+/** Extract a segment as raw s16le mono 16kHz PCM for Shazam. */
+export function extractSegment(file, startSec, durationSec, outPath) {
+  try {
+    execSync(
+      `ffmpeg -y -ss ${startSec} -t ${durationSec} ` +
+      `-i "${file}" -ac 1 -ar 16000 -f s16le -acodec pcm_s16le "${outPath}" 2>/dev/null`
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Download audio from a URL using yt-dlp. Returns path to downloaded file. */
+export function downloadURL(url, outputDir) {
+  if (!hasCommand('yt-dlp')) {
+    throw new Error('yt-dlp is required for URL downloads. Install: brew install yt-dlp');
+  }
+
+  // Get title for filename
+  const info = spawnSync('yt-dlp', ['--print', 'title', '--no-download', url], {
+    encoding: 'utf8',
+    timeout: 30_000,
+  });
+
+  const title = (info.status === 0 && info.stdout.trim())
+    ? info.stdout.trim().replace(/[^a-zA-Z0-9\s\-_]/g, '').replace(/\s+/g, '-').toLowerCase().slice(0, 80)
+    : 'downloaded-mix';
+
+  const outTemplate = join(outputDir, `${title}.%(ext)s`);
+
+  const dl = spawnSync('yt-dlp', [
+    '-x', '--audio-format', 'mp3', '--audio-quality', '0',
+    '-o', outTemplate, '--no-playlist', '--progress', url,
+  ], {
+    encoding: 'utf8',
+    timeout: 600_000,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+
+  // Find the output file
+  const mp3Path = join(outputDir, `${title}.mp3`);
+  if (existsSync(mp3Path)) return mp3Path;
+
+  for (const ext of ['webm', 'opus', 'm4a', 'ogg', 'wav']) {
+    const alt = join(outputDir, `${title}.${ext}`);
+    if (existsSync(alt)) return alt;
+  }
+
+  const errMsg = [dl.stdout, dl.stderr].filter(Boolean).join('\n');
+  throw new Error(`Download failed:\n${errMsg}`);
+}
+
+/** Format file size for display. */
+export function fileSize(path) {
+  return (statSync(path).size / 1024 / 1024).toFixed(1) + ' MB';
+}

package/lib/format.mjs

@@ -0,0 +1,56 @@
+/**
+ * Output formatting — TXT, CUE, and JSON.
+ */
+
+import { writeFileSync } from 'fs';
+import { basename } from 'path';
+
+/** Format seconds as H:MM:SS or MM:SS. */
+export function formatTime(sec) {
+  const h = Math.floor(sec / 3600);
+  const m = Math.floor((sec % 3600) / 60);
+  const s = Math.floor(sec % 60);
+  const mm = String(m).padStart(2, '0');
+  const ss = String(s).padStart(2, '0');
+  return h > 0 ? `${h}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+
+/** Remove consecutive duplicate tracks (handles transition bouncing). */
+export function dedupe(tracks) {
+  const result = [];
+  for (const t of tracks) {
+    const prev = result[result.length - 1];
+    if (prev && prev.title === t.title && prev.artist === t.artist) continue;
+    result.push(t);
+  }
+  return result;
+}
+
+/** Write paste-friendly tracklist. */
+export function writeTXT(tracks, outPath) {
+  const lines = tracks.map(t => `${t.artist} - ${t.title} ${t.timestamp}`);
+  writeFileSync(outPath, lines.join('\n') + '\n');
+}
+
+/** Write CUE sheet. */
+export function writeCUE(tracks, outPath, audioFilename) {
+  const title = basename(outPath, '.cue').replace(/[-_]/g, ' ');
+  let cue = `REM GENRE DJ Mix\nTITLE "${title}"\nFILE "${audioFilename}" MP3\n`;
+
+  tracks.forEach((t, i) => {
+    const num = String(i + 1).padStart(2, '0');
+    const mm = String(Math.floor(t.position_sec / 60)).padStart(2, '0');
+    const ss = String(t.position_sec % 60).padStart(2, '0');
+    cue += `  TRACK ${num} AUDIO\n`;
+    cue += `    TITLE "${t.title}"\n`;
+    cue += `    PERFORMER "${t.artist}"\n`;
+    cue += `    INDEX 01 ${mm}:${ss}:00\n`;
+  });
+
+  writeFileSync(outPath, cue);
+}
+
+/** Write JSON tracklist with metadata. */
+export function writeJSON(tracks, outPath, meta = {}) {
+  writeFileSync(outPath, JSON.stringify({ ...meta, tracks }, null, 2));
+}

package/lib/recognize.mjs

@@ -0,0 +1,27 @@
+/**
+ * Track recognition via Shazam.
+ */
+
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+const { Shazam, s16LEToSamplesArray } = require('shazam-api');
+
+const shazam = new Shazam();
+
+/**
+ * Recognize a track from raw s16le PCM audio data.
+ * Returns { title, artist, album, year } or null.
+ */
+export async function recognize(pcmBuffer) {
+  const samples = s16LEToSamplesArray(pcmBuffer);
+  const result = await shazam.recognizeSong(samples);
+
+  if (!result) return null;
+
+  return {
+    title: result.title || 'Unknown',
+    artist: result.artist || 'Unknown',
+    album: result.album || '',
+    year: result.year || '',
+  };
+}

package/lib/scanner.mjs

@@ -0,0 +1,94 @@
+/**
+ * Core scanner — splits audio into segments and identifies tracks.
+ */
+
+import { mkdtempSync, readFileSync, unlinkSync } from 'fs';
+import { join, basename } from 'path';
+import { tmpdir } from 'os';
+import { getDuration, extractSegment } from './audio.mjs';
+import { recognize } from './recognize.mjs';
+import { formatTime } from './format.mjs';
+
+const RATE_LIMIT_MS = 2000; // Be polite to Shazam
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+/**
+ * Scan an audio file and identify tracks.
+ *
+ * @param {string} file       - Path to audio file
+ * @param {object} opts
+ * @param {number} opts.step     - Seconds between scan points (default: 30)
+ * @param {number} opts.segment  - Seconds per sample (default: 18)
+ * @param {number} opts.start    - Start position in seconds (default: 0)
+ * @param {boolean} opts.quiet   - Suppress progress output
+ * @returns {Promise<{ tracks: Array, duration: number, segmentsScanned: number }>}
+ */
+export async function scan(file, opts = {}) {
+  const step = opts.step ?? 30;
+  const segment = opts.segment ?? 18;
+  const start = opts.start ?? 0;
+  const quiet = opts.quiet ?? false;
+
+  const duration = getDuration(file);
+  const totalSegs = Math.floor((duration - segment) / step) + 1;
+  const tmpDir = mkdtempSync(join(tmpdir(), 'mix-id-'));
+
+  const log = quiet ? () => {} : (msg) => process.stdout.write(msg);
+
+  if (!quiet) {
+    console.log(`\n🎵 mix-id`);
+    console.log('─'.repeat(50));
+    console.log(`File:     ${basename(file)}`);
+    console.log(`Duration: ${formatTime(duration)}`);
+    console.log(`Settings: ${step}s step, ${segment}s sample`);
+    console.log('─'.repeat(50) + '\n');
+  }
+
+  const tracks = [];
+  let lastTrack = null;
+  let segNum = 0;
+
+  for (let pos = start; pos + segment <= duration; pos += step) {
+    segNum++;
+    const ts = formatTime(pos);
+    const pct = Math.round((segNum / totalSegs) * 100);
+    log(`[${ts}] ${pct}% `);
+
+    const segPath = join(tmpDir, `seg.raw`);
+
+    if (!extractSegment(file, pos, segment, segPath)) {
+      log('⚠️  skip\n');
+      continue;
+    }
+
+    try {
+      const pcm = readFileSync(segPath);
+      const match = await recognize(pcm);
+
+      if (match) {
+        const same = lastTrack
+          && lastTrack.title === match.title
+          && lastTrack.artist === match.artist;
+
+        if (same) {
+          log(`↩️  ${match.artist} — ${match.title}\n`);
+        } else {
+          log(`✅ ${match.artist} — ${match.title}\n`);
+          tracks.push({ timestamp: ts, position_sec: pos, ...match });
+          lastTrack = match;
+        }
+      } else {
+        log('❓\n');
+        lastTrack = null;
+      }
+    } catch (err) {
+      log(`⚠️  ${err.message}\n`);
+      lastTrack = null;
+    }
+
+    try { unlinkSync(segPath); } catch {}
+    await sleep(RATE_LIMIT_MS);
+  }
+
+  return { tracks, duration, segmentsScanned: segNum };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "mix-id",
+  "version": "1.0.0",
+  "description": "Identify tracks in any DJ mix — from a file or URL. Outputs tracklists as TXT, CUE, and JSON.",
+  "type": "module",
+  "bin": {
+    "mix-id": "./cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "lib/"
+  ],
+  "keywords": [
+    "dj",
+    "tracklist",
+    "shazam",
+    "music",
+    "recognition",
+    "mix",
+    "cue",
+    "mixcloud",
+    "soundcloud",
+    "audio",
+    "fingerprint"
+  ],
+  "author": "Scott Bell",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/skip5this/mix-id"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "shazam-api": "^0.3.0"
+  }
+}