feat(spotify): implement milestone M4 importers

2026-04-12 02:00:50 -05:00
parent d8570edcf0
commit 141488c0f2
12 changed files with 521 additions and 14 deletions
@@ -0,0 +1,24 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { ParsedTrackRef } from "../types.js";
+import { dedupeTrackRefs, isAudioFile, parseArtistTitle } from "./importer-utils.js";
+
+async function walkAudioFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkAudioFiles(path));
+    } else if (entry.isFile() && isAudioFile(entry.name)) {
+      files.push(path);
+    }
+  }
+  return files.sort();
+}
+
+export async function readFolder(path: string): Promise<ParsedTrackRef[]> {
+  const files = await walkAudioFiles(path);
+  return dedupeTrackRefs(files.flatMap(parseArtistTitle));
+}
@@ -0,0 +1,90 @@
+import { basename, extname } from "node:path";
+
+import type { ParsedTrackRef } from "../types.js";
+
+const audioExtensions = new Set([".aac", ".aiff", ".alac", ".flac", ".m4a", ".mp3", ".ogg", ".opus", ".wav", ".wma"]);
+
+export function normalizeText(value: string): string {
+  return value.normalize("NFKC").replace(/[_\t]+/g, " ").replace(/\s+/g, " ").trim();
+}
+
+export function stripAudioExtension(filename: string): string {
+  const extension = extname(filename).toLowerCase();
+  const base = basename(filename);
+  return audioExtensions.has(extension) ? base.slice(0, -extension.length) : base;
+}
+
+export function isAudioFile(filename: string): boolean {
+  return audioExtensions.has(extname(filename).toLowerCase());
+}
+
+export function stripTrackNumberPrefix(value: string): string {
+  return normalizeText(value)
+    .replace(/^\d{1,3}\s*[-._)]\s*/u, "")
+    .replace(/^\d{1,3}\s+/u, "");
+}
+
+function ref(source: string, artist: string | undefined, title: string | undefined, query?: string): ParsedTrackRef {
+  const cleanedArtist = artist ? normalizeText(artist) : undefined;
+  const cleanedTitle = title ? normalizeText(title) : undefined;
+  return {
+    source,
+    query: normalizeText(query ?? [cleanedArtist, cleanedTitle].filter(Boolean).join(" ")),
+    ...(cleanedArtist ? { artist: cleanedArtist } : {}),
+    ...(cleanedTitle ? { title: cleanedTitle } : {})
+  };
+}
+
+export function parseArtistTitle(value: string): ParsedTrackRef[] {
+  const source = normalizeText(stripTrackNumberPrefix(stripAudioExtension(value)));
+  if (!source) {
+    return [];
+  }
+
+  const colon = source.match(/^(.+?)\s*:\s*(.+)$/u);
+  if (colon) {
+    return [ref(source, colon[1], colon[2])];
+  }
+
+  const dash = source.match(/^(.+?)\s+-\s+(.+)$/u);
+  if (dash) {
+    return [ref(source, dash[1], dash[2]), ref(source, dash[2], dash[1])];
+  }
+
+  const underscore = value.match(/^(.+?)_(.+)$/u);
+  if (underscore) {
+    return [ref(source, underscore[1], underscore[2])];
+  }
+
+  return [ref(source, undefined, source, source)];
+}
+
+export function dedupeTrackRefs(refs: ParsedTrackRef[]): ParsedTrackRef[] {
+  const seen = new Set<string>();
+  const output: ParsedTrackRef[] = [];
+  for (const item of refs) {
+    const key = `${normalizeText(item.artist ?? "").toLowerCase()}|${normalizeText(item.title ?? item.query).toLowerCase()}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    output.push(item);
+  }
+  return output;
+}
+
+export function buildSearchQueries(ref: ParsedTrackRef): string[] {
+  const queries = new Set<string>();
+  if (ref.artist && ref.title) {
+    queries.add(`${ref.artist} ${ref.title}`);
+    queries.add(`track:${ref.title} artist:${ref.artist}`);
+  }
+  queries.add(ref.query);
+  return Array.from(queries).map(normalizeText).filter(Boolean);
+}
+
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export const DEFAULT_IMPORT_SEARCH_DELAY_MS = 100;
@@ -0,0 +1,108 @@
+import { stat } from "node:fs/promises";
+import { extname } from "node:path";
+
+import { createSpotifyApiClient, type SpotifyApiClient } from "../api-client.js";
+import type { CliDeps, ParsedCli } from "../cli.js";
+import type { ImportResult, ParsedTrackRef, SpotifyTrack } from "../types.js";
+import { DEFAULT_IMPORT_SEARCH_DELAY_MS, buildSearchQueries, sleep as defaultSleep } from "./importer-utils.js";
+import { readFolder } from "./folder.js";
+import { readM3u } from "./m3u.js";
+import { readTextList } from "./text-list.js";
+
+type ImportClient = Pick<SpotifyApiClient, "searchTracks" | "createPlaylist" | "addItemsToPlaylist">;
+
+export interface ImportOptions {
+  playlist?: string;
+  playlistId?: string;
+  public?: boolean;
+  delayMs?: number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export async function readImportSource(path: string): Promise<ParsedTrackRef[]> {
+  const info = await stat(path);
+  if (info.isDirectory()) {
+    return readFolder(path);
+  }
+  const extension = extname(path).toLowerCase();
+  if (extension === ".m3u" || extension === ".m3u8") {
+    return readM3u(path);
+  }
+  return readTextList(path);
+}
+
+async function findTrack(ref: ParsedTrackRef, client: Pick<ImportClient, "searchTracks">): Promise<SpotifyTrack | undefined> {
+  for (const query of buildSearchQueries(ref)) {
+    const tracks = await client.searchTracks(query, 1);
+    if (tracks[0]) {
+      return tracks[0];
+    }
+  }
+  return undefined;
+}
+
+export async function importTracks(
+  path: string,
+  options: ImportOptions,
+  client: ImportClient = createSpotifyApiClient()
+): Promise<ImportResult> {
+  if (Boolean(options.playlist) === Boolean(options.playlistId)) {
+    throw new Error("Specify exactly one of --playlist or --playlist-id.");
+  }
+
+  const refs = await readImportSource(path);
+  const wait = options.sleep ?? defaultSleep;
+  const found: ImportResult["found"] = [];
+  const missed: ImportResult["missed"] = [];
+  const foundUris = new Set<string>();
+
+  for (const [index, ref] of refs.entries()) {
+    const track = await findTrack(ref, client);
+    if (!track) {
+      missed.push({ ...ref, reason: "No Spotify match found" });
+    } else if (!foundUris.has(track.uri)) {
+      foundUris.add(track.uri);
+      found.push({ ...ref, uri: track.uri, matchedName: track.name, matchedArtists: track.artists.map((artist) => artist.name) });
+    }
+    if (options.delayMs !== 0 && index < refs.length - 1) {
+      await wait(options.delayMs ?? DEFAULT_IMPORT_SEARCH_DELAY_MS);
+    }
+  }
+
+  const playlistId = options.playlistId ?? (await client.createPlaylist(options.playlist ?? "", { public: Boolean(options.public) })).id;
+  const mutationResults = found.length > 0
+    ? await client.addItemsToPlaylist(playlistId, found.map((item) => item.uri))
+    : [];
+
+  return {
+    found,
+    missed,
+    added: {
+      playlistId,
+      count: found.length,
+      snapshotIds: mutationResults.map((result) => result.snapshot_id).filter((id): id is string => Boolean(id))
+    }
+  };
+}
+
+export async function runImportCommand(
+  args: ParsedCli,
+  deps: CliDeps,
+  client: ImportClient = createSpotifyApiClient()
+): Promise<number> {
+  const [path] = args.positional;
+  if (!path) {
+    throw new Error("Missing import path.");
+  }
+  const result = await importTracks(path, {
+    playlist: args.playlist,
+    playlistId: args.playlistId,
+    public: args.public
+  }, client);
+  if (args.json) {
+    deps.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } else {
+    deps.stdout.write(`Imported ${result.found.length} track(s); missed ${result.missed.length}; playlist ${result.added?.playlistId}.\n`);
+  }
+  return 0;
+}
@@ -0,0 +1,38 @@
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+import type { ParsedTrackRef } from "../types.js";
+import { dedupeTrackRefs, parseArtistTitle } from "./importer-utils.js";
+
+function parseExtInf(line: string): string | undefined {
+  const comma = line.indexOf(",");
+  if (comma === -1 || comma === line.length - 1) {
+    return undefined;
+  }
+  return line.slice(comma + 1).trim();
+}
+
+export function parseM3u(content: string): ParsedTrackRef[] {
+  const refs: ParsedTrackRef[] = [];
+  let pendingExtInf: string | undefined;
+  for (const rawLine of content.split(/\r?\n/u)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    if (line.startsWith("#EXTINF:")) {
+      pendingExtInf = parseExtInf(line);
+      continue;
+    }
+    if (line.startsWith("#")) {
+      continue;
+    }
+    refs.push(...parseArtistTitle(pendingExtInf ?? basename(line)));
+    pendingExtInf = undefined;
+  }
+  return dedupeTrackRefs(refs);
+}
+
+export async function readM3u(path: string): Promise<ParsedTrackRef[]> {
+  return parseM3u(await readFile(path, "utf8"));
+}
@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+
+import type { ParsedTrackRef } from "../types.js";
+import { dedupeTrackRefs, parseArtistTitle } from "./importer-utils.js";
+
+export function parseTextList(content: string): ParsedTrackRef[] {
+  const refs = content
+    .split(/\r?\n/u)
+    .map((line) => line.trim())
+    .filter((line) => line && !line.startsWith("#") && !line.startsWith("//"))
+    .flatMap(parseArtistTitle);
+  return dedupeTrackRefs(refs);
+}
+
+export async function readTextList(path: string): Promise<ParsedTrackRef[]> {
+  return parseTextList(await readFile(path, "utf8"));
+}