upnext-adapter-spotify 0.1.0

package/src/applescript.ts

@@ -0,0 +1,241 @@
+import { execFile } from 'node:child_process';
+import { SpotifyError, classifyText } from './errors.js';
+import { parseSpotifyUri, toSpotifyUri } from './uri.js';
+
+/**
+ * Talking to the Spotify desktop app through its AppleScript dictionary.
+ *
+ * The script text and the parsing are separated on purpose, and both are
+ * exported. AppleScript is a string until the moment it runs, so the part most
+ * likely to break — a field order that drifts, a property spelled wrong — is
+ * exactly the part a type checker cannot see. Keeping the parser pure means the
+ * wire format has real tests on a machine with no Spotify, no macOS and no
+ * network, which is where this package's CI runs.
+ */
+
+/** ASCII unit separator. Written as an escape because the character is
+ * invisible in an editor, and chosen over a tab or a pipe because a track title
+ * is free text — anything a person might plausibly type would split a title in
+ * half. */
+export const FIELD = '\u001F';
+
+/** How long any one script may take. A beachballing player, or a first run
+ * waiting on the macOS Automation consent prompt, must not hold a sample
+ * forever and let the next one stack behind it. */
+export const SCRIPT_TIMEOUT_MS = 5_000;
+
+/** The one dependency on the outside world, injectable so every decision this
+ * package makes is testable without a Mac, a Spotify account, or an app. */
+export type Osascript = (script: string) => Promise<string>;
+
+export function runOsascript(script: string): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      'osascript',
+      ['-e', script],
+      { timeout: SCRIPT_TIMEOUT_MS },
+      (error, stdout, stderr) => {
+        if (!error) return resolve(stdout);
+        const text = String(stderr || error.message);
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+          return reject(
+            new SpotifyError('unavailable', 'osascript is not available on this system'),
+          );
+        }
+        reject(new SpotifyError(classifyText(text), text.trim() || 'osascript failed'));
+      },
+    );
+  });
+}
+
+/**
+ * One reading of the desktop app.
+ *
+ * `running: false` is a first-class answer, not an error. Spotify not being
+ * open is the ordinary state of most machines most of the time, and a backend
+ * that treats it as a failure would fill a host's logs with news it cannot act
+ * on.
+ */
+export interface Sample {
+  running: boolean;
+  status: 'playing' | 'paused' | 'idle';
+  positionMs: number;
+  durationMs: number | null;
+  /** What Spotify says it is playing, as a `spotify:` URI. */
+  nativeUri: string | null;
+  /** 0..1, or null when the app would not say. */
+  volume: number | null;
+}
+
+/**
+ * Read the app's state without ever launching it.
+ *
+ * `if application "Spotify" is running` is the load-bearing line. A bare
+ * `tell application "Spotify"` *launches* Spotify, so a sampler running every
+ * second would boot a music player onto the machine of someone who never opened
+ * one — and would do it on a poll the user never asked for. The guard is what
+ * makes this safe to run on a timer.
+ *
+ * Every property sits behind its own `try` so that one that errors — and
+ * `current track` errors whenever nothing is loaded — costs its own field
+ * rather than the whole reading.
+ */
+export function stateScript(): string {
+  return `on run
+	set AppleScript's text item delimiters to (ASCII character 31)
+	if application "Spotify" is running then
+		tell application "Spotify"
+			set stateField to "idle"
+			set positionField to "0"
+			set trackField to ""
+			set durationField to ""
+			set volumeField to ""
+			try
+				set stateField to (player state as text)
+			end try
+			try
+				set positionField to (player position as text)
+			end try
+			try
+				set trackField to (id of current track as text)
+			end try
+			try
+				set durationField to (duration of current track as text)
+			end try
+			try
+				set volumeField to (sound volume as text)
+			end try
+			return {"running", stateField, positionField, trackField, durationField, volumeField} as text
+		end tell
+	end if
+	return ""
+end run`;
+}
+
+/**
+ * Turn a reading into a `Sample`, or `null` if the text is not one.
+ *
+ * Anything malformed answers null rather than a half-filled sample: a sample
+ * with a NaN playhead would be read as a real position and could end a track
+ * that is still playing, where a missing sample simply means this tick learned
+ * nothing and the next one will.
+ */
+export function parseSample(raw: string): Sample | null {
+  const trimmed = raw.trim();
+  // Empty is the script's own word for "Spotify is not open" — a real answer.
+  if (!trimmed) {
+    return { running: false, status: 'idle', positionMs: 0, durationMs: null, nativeUri: null, volume: null };
+  }
+
+  const fields = trimmed.split(FIELD);
+  if (fields[0] !== 'running' || fields.length < 6) return null;
+
+  const parsed = parseSpotifyUri(fields[3]);
+  const durationMs = positiveInt(fields[4]);
+  const volume = positiveFloat(fields[5]);
+
+  return {
+    running: true,
+    status: readStatus(fields[1]),
+    // Spotify reports the playhead in seconds and the track length in
+    // milliseconds. Everything above this line is milliseconds.
+    positionMs: Math.round((positiveFloat(fields[2]) ?? 0) * 1000),
+    durationMs,
+    nativeUri: parsed ? toSpotifyUri(parsed) : null,
+    volume: volume === null ? null : Math.min(1, Math.max(0, volume / 100)),
+  };
+}
+
+/** Spotify's dictionary spells the three states exactly this way. */
+function readStatus(value: string | undefined): Sample['status'] {
+  if (value === 'playing') return 'playing';
+  if (value === 'paused') return 'paused';
+  return 'idle';
+}
+
+function positiveFloat(value: string | undefined): number | null {
+  const parsed = Number.parseFloat(value ?? '');
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+function positiveInt(value: string | undefined): number | null {
+  const parsed = Number.parseInt(value ?? '', 10);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
+}
+
+// -- commands ---------------------------------------------------------------
+
+/**
+ * Start a specific track.
+ *
+ * This is the one script allowed to launch Spotify, because it only ever runs
+ * as the direct result of something asking for playback. `activate` is
+ * deliberately absent: starting a song should not take the foreground away from
+ * whatever the person is actually looking at.
+ *
+ * A start offset needs the pause. `play track` returns as soon as the command
+ * is accepted, not when the track is loaded, and moving the playhead of a track
+ * that has not loaded yet either errors or is silently discarded — so the seek
+ * is retried until it takes, which costs nothing in the common case where
+ * `startAtMs` is zero and none of this runs.
+ */
+export function playTrackScript(nativeUri: string, startAtMs = 0): string {
+  const seconds = Math.max(0, Math.round(startAtMs / 1000));
+  const seek =
+    seconds > 0
+      ? `
+		repeat 20 times
+			try
+				if player state is playing then
+					set player position to ${seconds}
+					exit repeat
+				end if
+			end try
+			delay 0.1
+		end repeat`
+      : '';
+  return `tell application "Spotify"
+		play track ${quote(nativeUri)}${seek}
+	end tell`;
+}
+
+/**
+ * Any other verb, wrapped so it cannot launch the app.
+ *
+ * There is nothing to pause, seek or re-level in an app that is not open, and
+ * launching one to tell it to be quiet would be absurd — so unlike
+ * `playTrackScript`, everything here is behind the running guard.
+ */
+export function commandScript(body: string): string {
+  return `if application "Spotify" is running then
+	tell application "Spotify"
+		${body}
+	end tell
+end if`;
+}
+
+export const commands = {
+  play: 'play',
+  /**
+   * Spotify's dictionary has no stop that does not quit the app, and quitting
+   * someone's music player because a queue moved to a different source would be
+   * far ruder than leaving it paused. `stop` therefore means pause here, and
+   * that is the honest description of what happens.
+   */
+  pause: 'pause',
+  seek: (positionMs: number) => `set player position to ${Math.max(0, Math.round(positionMs / 1000))}`,
+  volume: (volume: number) =>
+    `set sound volume to ${Math.min(100, Math.max(0, Math.round(volume * 100)))}`,
+} as const;
+
+/**
+ * A string literal AppleScript will read as one string.
+ *
+ * Only ever given a `spotify:` URI built by `toSpotifyUri` from a validated
+ * base-62 id, so there is nothing here to escape in practice — but this text
+ * becomes a program, and a quoting function that exists is cheaper than the
+ * argument about whether the caller can always be trusted.
+ */
+function quote(value: string): string {
+  return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}

package/src/desktop.ts

@@ -0,0 +1,250 @@
+import { defaultCapabilities, systemScheduler, type Scheduler } from 'upnext-core';
+import type { Adapter, AdapterEvent, Binding, Capabilities, MediaRef } from 'upnext-core';
+import {
+  commandScript,
+  commands,
+  parseSample,
+  playTrackScript,
+  runOsascript,
+  stateScript,
+  type Osascript,
+} from './applescript.js';
+import { SpotifyError } from './errors.js';
+import { embedLookup, type TrackLookup } from './metadata.js';
+import { isPlayableKind, parseSpotifyUri, toSpotifyUri } from './uri.js';
+import { BackendWatcher } from './watch.js';
+
+export interface SpotifyDesktopOptions {
+  id?: string;
+  /**
+   * How often to read the app while something is loaded.
+   *
+   * This is the resolution of every time-dependent thing the backend can tell
+   * us — the playhead, a pause someone made in the app, the end of a track.
+   * A second is comfortably below what a person notices and cheap enough to
+   * run for hours; the cost of each sample is one short-lived `osascript`.
+   */
+  sampleIntervalMs?: number;
+  /** Injected so the whole adapter is testable off macOS. */
+  osascript?: Osascript;
+  scheduler?: Scheduler;
+  /**
+   * How a bare Spotify URI becomes a title and a cover. `null` turns it off and
+   * the queue simply shows URIs — nothing about playback depends on it.
+   */
+  lookup?: TrackLookup | null;
+  /** Overridden only by tests; a real host is on whatever it is on. */
+  platform?: string;
+}
+
+/**
+ * Drives the Spotify desktop app on macOS, with no credentials at all.
+ *
+ * There is no OAuth here, no client id, no Premium check and nothing to
+ * register: it talks to the copy of Spotify already running on the machine
+ * through the AppleScript dictionary that ships with it. If someone can play
+ * music in Spotify, this can play music in Spotify.
+ *
+ * It is also the first backend in this project that a **human can fight**, and
+ * that is the interesting part. A local file is ours alone; the Spotify app has
+ * its own transport bar, its own queue, and a person holding a phone who is
+ * fully entitled to press next. So it declares `externalControl: true`, keeps
+ * enough history to tell a natural track change from a deliberate one (see
+ * `sampler.ts`), and lets the runtime's reconciler decide who wins — which by
+ * default is the person.
+ *
+ * What it deliberately does *not* claim:
+ *
+ *   `search: false` — the dictionary cannot search the catalogue. It could be
+ *     faked by scraping something, and then every `resolve` of a title would be
+ *     a guess dressed as a lookup. An adapter that says it cannot do a thing is
+ *     correct and slightly limited; one that says it can and then does it badly
+ *     is broken. Use `SpotifyWebAdapter` when you need search.
+ *
+ *   No `poll()` — `position: 'authoritative'` would normally make the runtime's
+ *     watcher poll this adapter on an interval. It samples itself instead,
+ *     because only the adapter can compare a reading against the one before it,
+ *     and that comparison is the whole rollover-versus-takeover decision.
+ *     Offering `poll` as well would mean two timers reading the same app.
+ */
+export class SpotifyDesktopAdapter implements Adapter {
+  readonly id: string;
+
+  readonly capabilities: Capabilities = {
+    ...defaultCapabilities,
+    endOfTrack: 'event',
+    position: 'authoritative',
+    externalControl: true,
+    seek: true,
+    pause: true,
+    volume: true,
+    search: false,
+  };
+
+  #osascript: Osascript;
+  #lookup: TrackLookup | null;
+  #platform: string;
+  #watcher: BackendWatcher;
+
+  #listeners = new Set<(event: AdapterEvent) => void>();
+  #binding: Binding | null = null;
+  #startAtMs = 0;
+  /** Whether `play track` has been issued for the loaded binding. */
+  #started = false;
+
+  constructor(options: SpotifyDesktopOptions = {}) {
+    this.id = options.id ?? 'spotify-desktop';
+    this.#osascript = options.osascript ?? runOsascript;
+    this.#lookup = options.lookup === undefined ? embedLookup : options.lookup;
+    this.#platform = options.platform ?? process.platform;
+
+    const intervalMs = options.sampleIntervalMs ?? 1000;
+    this.#watcher = new BackendWatcher({
+      read: async () => parseSample(await this.#osascript(stateScript())),
+      emit: (event) => this.#emit(event),
+      scheduler: options.scheduler ?? systemScheduler,
+      intervalMs,
+      // Two intervals wide: the last reading before a track change can be a
+      // whole interval short of the end, and a window tighter than that reads
+      // every natural rollover as a human taking over.
+      rolloverWindowMs: Math.max(2000, intervalMs * 2),
+      confirmWithin: Math.max(3, Math.ceil(5000 / intervalMs)),
+    });
+  }
+
+  /**
+   * Fail here rather than at the first song.
+   *
+   * A backend whose `init` throws is excluded from selection and shows up in
+   * `getState().adapters` as `available: false` with the reason — so a host on
+   * Linux gets one clear "this backend is macOS-only" at startup instead of an
+   * agent discovering it one failed track at a time.
+   *
+   * `id of application "Spotify"` resolves the app through LaunchServices
+   * *without launching it*, which is the only way to ask "is Spotify even
+   * installed" that does not open a music player on someone's desktop.
+   */
+  async init(): Promise<void> {
+    if (this.#platform !== 'darwin') {
+      throw new SpotifyError(
+        'unavailable',
+        `${this.id} drives the macOS Spotify app and cannot run on ${this.#platform}; ` +
+          'use SpotifyWebAdapter instead',
+      );
+    }
+    try {
+      await this.#osascript('id of application "Spotify"');
+    } catch (err) {
+      throw new SpotifyError(
+        'unavailable',
+        `${this.id} could not find the Spotify desktop app: ${
+          err instanceof Error ? err.message : String(err)
+        }`,
+      );
+    }
+  }
+
+  /**
+   * Only things that already name a Spotify track.
+   *
+   * Without search there is no way to get from "Bad Habit by Steve Lacy" to a
+   * URI, so scoring anything else above zero would win the ref away from an
+   * adapter that could actually have played it.
+   */
+  match(ref: MediaRef): number {
+    const parsed = parseSpotifyUri(ref.uri);
+    return parsed && isPlayableKind(parsed.kind) ? 1 : 0;
+  }
+
+  async resolve(ref: MediaRef): Promise<Binding | null> {
+    const parsed = parseSpotifyUri(ref.uri);
+    if (!parsed || !isPlayableKind(parsed.kind)) return null;
+    const nativeUri = toSpotifyUri(parsed);
+
+    // Best-effort only, and skipped entirely when the ref already says enough.
+    // A track with no title still plays; a resolve that throws does not.
+    let extra: Partial<MediaRef> = {};
+    if (this.#lookup && !(ref.title && ref.artist)) {
+      try {
+        extra = await this.#lookup(parsed);
+      } catch {
+        extra = {};
+      }
+    }
+
+    return {
+      adapterId: this.id,
+      nativeUri,
+      // What the caller already knew wins: it came from whoever built the
+      // queue, and the lookup is only filling gaps.
+      ref: { ...extra, ...ref, uri: nativeUri },
+    };
+  }
+
+  async load(binding: Binding, opts?: { startAtMs?: number }): Promise<void> {
+    this.#watcher.stop();
+    this.#binding = binding;
+    this.#startAtMs = opts?.startAtMs ?? 0;
+    this.#started = false;
+  }
+
+  async play(): Promise<void> {
+    const binding = this.#binding;
+    if (!binding) throw new SpotifyError('failed', `${this.id}: nothing is loaded`);
+
+    if (this.#started) {
+      // Resuming what is already loaded. `play` on its own is the dictionary's
+      // resume; re-issuing `play track` would restart the song from zero.
+      await this.#run(commandScript(commands.play));
+      return;
+    }
+
+    await this.#run(playTrackScript(binding.nativeUri, this.#startAtMs));
+    this.#started = true;
+    this.#watcher.start(binding.nativeUri);
+  }
+
+  async pause(): Promise<void> {
+    await this.#run(commandScript(commands.pause));
+  }
+
+  /**
+   * Spotify's dictionary has no stop that does not quit the app, so this
+   * pauses. Quitting somebody's music player because the queue moved on to a
+   * podcast would be a much bigger thing to do than the runtime is asking for.
+   */
+  async stop(): Promise<void> {
+    this.#watcher.stop();
+    const wasStarted = this.#started;
+    this.#binding = null;
+    this.#started = false;
+    if (wasStarted) await this.#run(commandScript(commands.pause));
+  }
+
+  async seek(positionMs: number): Promise<void> {
+    await this.#run(commandScript(commands.seek(positionMs)));
+  }
+
+  async setVolume(volume: number): Promise<void> {
+    await this.#run(commandScript(commands.volume(volume)));
+  }
+
+  subscribe(listener: (event: AdapterEvent) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async dispose(): Promise<void> {
+    this.#watcher.stop();
+    this.#listeners.clear();
+    this.#binding = null;
+  }
+
+  async #run(script: string): Promise<void> {
+    await this.#osascript(script);
+  }
+
+  #emit(event: AdapterEvent): void {
+    for (const listener of [...this.#listeners]) listener(event);
+  }
+}

package/src/errors.ts

@@ -0,0 +1,119 @@
+/**
+ * Why a Spotify call did not work, in the few shapes a caller can act on.
+ *
+ * The distinction that matters is not the status code — it is what the person
+ * holding the machine would have to *do*. "Your token expired" and "you have no
+ * speaker selected" are both a failed play, and an agent that cannot tell them
+ * apart either nags for a re-login when the real problem is a sleeping phone,
+ * or silently retries forever when the real problem is a login.
+ *
+ * Deliberately coarse: the exact wording of an upstream error is not a contract
+ * and will drift, so this keys off the few stable signals and buckets everything
+ * else as `failed`.
+ */
+export type SpotifyFailure =
+  /** No usable session. The host must get a fresh token, or the user must log in. */
+  | 'unauthorized'
+  /** Authenticated, but Spotify will not let this account control playback. */
+  | 'premium-required'
+  /** Nothing to play *on*: no active device, or the desktop app is not running. */
+  | 'no-device'
+  /** Too many calls. Back off; `retryAfterMs` says how long if Spotify said. */
+  | 'rate-limited'
+  /** Spotify does not have this track, or not in this market. */
+  | 'not-found'
+  /** This backend cannot run here at all — wrong platform, app not installed. */
+  | 'unavailable'
+  /** Something else. Renders as "try again", the safe default when unsure. */
+  | 'failed';
+
+export class SpotifyError extends Error {
+  readonly reason: SpotifyFailure;
+  readonly status?: number;
+  readonly retryAfterMs?: number;
+
+  constructor(
+    reason: SpotifyFailure,
+    message: string,
+    extra: { status?: number; retryAfterMs?: number } = {},
+  ) {
+    super(message);
+    this.name = 'SpotifyError';
+    this.reason = reason;
+    if (extra.status !== undefined) this.status = extra.status;
+    if (extra.retryAfterMs !== undefined) this.retryAfterMs = extra.retryAfterMs;
+  }
+}
+
+/**
+ * Map an HTTP status, plus Spotify's own `reason` when it sends one, onto a
+ * bucket.
+ *
+ * Two statuses are genuinely ambiguous and the body is what settles them:
+ * a 403 is a scope problem *or* a free account, and a 404 from the player
+ * endpoints is a missing track *or* the well-known `NO_ACTIVE_DEVICE`. Both
+ * distinctions change what a host should tell the user, so both are read.
+ */
+export function classifyStatus(status: number, body?: unknown): SpotifyFailure {
+  const reason = errorReason(body);
+  if (status === 429) return 'rate-limited';
+  if (status === 401) return 'unauthorized';
+  if (status === 403) {
+    return reason === 'PREMIUM_REQUIRED' ? 'premium-required' : 'unauthorized';
+  }
+  if (status === 404) {
+    return reason === 'NO_ACTIVE_DEVICE' ? 'no-device' : 'not-found';
+  }
+  return 'failed';
+}
+
+/** Spotify's player errors carry `{ error: { status, message, reason } }`. */
+function errorReason(body: unknown): string | null {
+  if (!body || typeof body !== 'object') return null;
+  const error = (body as { error?: unknown }).error;
+  if (!error || typeof error !== 'object') return null;
+  const reason = (error as { reason?: unknown }).reason;
+  return typeof reason === 'string' ? reason : null;
+}
+
+/** Spotify's error body carries a human message worth passing through. */
+export function errorMessage(body: unknown, fallback: string): string {
+  if (!body || typeof body !== 'object') return fallback;
+  const error = (body as { error?: unknown }).error;
+  if (typeof error === 'string') return error;
+  if (error && typeof error === 'object') {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string' && message.trim()) return message.trim();
+  }
+  return fallback;
+}
+
+/**
+ * The same classification against free text, for the backend that has no status
+ * codes — osascript writes prose to stderr and nothing else.
+ *
+ * The ordering matters: rate limiting is tested first because a throttling
+ * message can contain the word "user" and must not be mistaken for the auth
+ * case below it.
+ */
+export function classifyText(text: string): SpotifyFailure {
+  const lower = text.toLowerCase();
+  if (/rate limit|too many|429/.test(lower)) return 'rate-limited';
+  if (/not authorized|not authorised|-1743|assistive access/.test(lower)) {
+    // macOS Automation consent was declined. Not a Spotify login problem, but
+    // it is the same shape of problem: a permission the user has to grant.
+    return 'unauthorized';
+  }
+  if (/(-600|-609)|isn't running|is not running|application isn't/.test(lower)) {
+    return 'no-device';
+  }
+  if (/can't get|cant get|-1728/.test(lower)) return 'not-found';
+  return 'failed';
+}
+
+/** Seconds in a `Retry-After` header, in milliseconds. */
+export function retryAfterMs(header: string | null): number | undefined {
+  if (!header) return undefined;
+  const seconds = Number.parseInt(header, 10);
+  return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}