upnext-adapter-browser 0.1.0

package/src/remote.ts

@@ -0,0 +1,250 @@
+import { defaultCapabilities } from 'upnext-core';
+import type {
+  Adapter,
+  AdapterEvent,
+  Binding,
+  Capabilities,
+  MediaRef,
+} from 'upnext-core';
+import { MediaElementAdapter, type MediaElementLike } from './element.js';
+import { score } from './sources.js';
+
+/**
+ * Driving a media element that lives somewhere else.
+ *
+ * In an Electron app the queue runs in the main process and the only thing that
+ * can hold an `<audio>` is a renderer. In a web app the element may sit inside
+ * an iframe or a worker-owned document. Either way the adapter and the element
+ * are separated by a boundary that only passes messages.
+ *
+ * The transport is deliberately not named. A host that has `ipcMain`/`ipcRenderer`
+ * uses that; one with `postMessage` uses that; a test uses two functions and no
+ * boundary at all. This library takes a `Channel` and asks no further questions,
+ * the same way `upnext-adapter-process` takes a command and does not care what
+ * language is on the other end.
+ */
+export interface Channel {
+  send(message: unknown): void;
+  /** Returns an unsubscribe function. */
+  subscribe(listener: (message: unknown) => void): () => void;
+}
+
+interface Command {
+  id: number;
+  method: 'load' | 'play' | 'pause' | 'stop' | 'seek' | 'setVolume';
+  params?: unknown;
+}
+
+interface Reply {
+  id: number;
+  error?: string;
+}
+
+interface Pushed {
+  event: AdapterEvent;
+}
+
+/**
+ * Both ends run the same capabilities, because both ends are the same adapter —
+ * `serveMediaElement` drives a real `MediaElementAdapter`. There is no handshake
+ * to negotiate: a media element is a media element wherever it is sitting.
+ */
+const REMOTE_CAPABILITIES: Capabilities = {
+  ...defaultCapabilities,
+  endOfTrack: 'event',
+  position: 'authoritative',
+  seek: true,
+  pause: true,
+  volume: true,
+  search: false,
+  externalControl: false,
+};
+
+export interface RemoteMediaAdapterOptions {
+  id?: string;
+  channel: Channel;
+  /** How long to wait for the far side before giving up. */
+  requestTimeoutMs?: number;
+  extraExtensions?: string[];
+}
+
+/** The side that lives with the `Runtime`. */
+export class RemoteMediaAdapter implements Adapter {
+  readonly id: string;
+  readonly capabilities = REMOTE_CAPABILITIES;
+
+  #options: RemoteMediaAdapterOptions;
+  #listeners = new Set<(event: AdapterEvent) => void>();
+  #pending = new Map<number, { resolve: () => void; reject: (e: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  #unsubscribe: (() => void) | null = null;
+  #nextId = 1;
+
+  constructor(options: RemoteMediaAdapterOptions) {
+    this.id = options.id ?? 'browser';
+    this.#options = options;
+  }
+
+  async init(): Promise<void> {
+    this.#unsubscribe ??= this.#options.channel.subscribe((message) => this.#receive(message));
+  }
+
+  /**
+   * Evaluated locally, never over the wire. `match` is synchronous by contract
+   * and asking across a boundary on every resolution would be absurd — and
+   * unnecessary, since what a media element accepts is knowable from the URL.
+   */
+  match(ref: MediaRef): number {
+    return score(ref, this.#options.extraExtensions);
+  }
+
+  async resolve(ref: MediaRef): Promise<Binding | null> {
+    if (!ref.uri || this.match(ref) === 0) return null;
+    return { adapterId: this.id, nativeUri: ref.uri, ref: { ...ref } };
+  }
+
+  async load(binding: Binding, opts?: { startAtMs?: number }): Promise<void> {
+    await this.#request('load', { binding, ...opts });
+  }
+  async play(): Promise<void> {
+    await this.#request('play');
+  }
+  async pause(): Promise<void> {
+    await this.#request('pause');
+  }
+  async stop(): Promise<void> {
+    await this.#request('stop');
+  }
+  async seek(positionMs: number): Promise<void> {
+    await this.#request('seek', { positionMs });
+  }
+  async setVolume(volume: number): Promise<void> {
+    await this.#request('setVolume', { volume });
+  }
+
+  subscribe(listener: (event: AdapterEvent) => void): () => void {
+    this.#listeners.add(listener);
+    return () => this.#listeners.delete(listener);
+  }
+
+  async dispose(): Promise<void> {
+    for (const [, pending] of this.#pending) clearTimeout(pending.timer);
+    this.#pending.clear();
+    this.#unsubscribe?.();
+    this.#unsubscribe = null;
+    this.#listeners.clear();
+  }
+
+  #request(method: Command['method'], params?: unknown): Promise<void> {
+    void this.init();
+    const id = this.#nextId++;
+    const timeoutMs = this.#options.requestTimeoutMs ?? 5000;
+
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.#pending.delete(id);
+        reject(new Error(`${this.id}: ${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.#pending.set(id, { resolve, reject, timer });
+      this.#options.channel.send({ id, method, params } satisfies Command);
+    });
+  }
+
+  #receive(message: unknown): void {
+    if (!message || typeof message !== 'object') return;
+
+    if ('event' in message) {
+      const { event } = message as Pushed;
+      for (const listener of [...this.#listeners]) listener(event);
+      return;
+    }
+
+    const reply = message as Reply;
+    const pending = this.#pending.get(reply.id);
+    if (!pending) return;
+    this.#pending.delete(reply.id);
+    clearTimeout(pending.timer);
+    if (reply.error) pending.reject(new Error(`${this.id}: ${reply.error}`));
+    else pending.resolve();
+  }
+}
+
+/**
+ * The side that lives with the element. Call it once, wherever the DOM is.
+ *
+ * It drives a real `MediaElementAdapter`, so the behaviour on the far side of
+ * the boundary is not a reimplementation that can drift — it is the same class
+ * the in-process case uses.
+ */
+export function serveMediaElement(
+  element: MediaElementLike | (() => MediaElementLike),
+  channel: Channel,
+  options: { id?: string; extraExtensions?: string[] } = {},
+): () => void {
+  const adapter = new MediaElementAdapter({ element, ...options });
+  const offEvents = adapter.subscribe((event) => channel.send({ event } satisfies Pushed));
+
+  const offCommands = channel.subscribe((message) => {
+    if (!message || typeof message !== 'object' || !('method' in message)) return;
+    const command = message as Command;
+    void run(adapter, command)
+      .then(() => channel.send({ id: command.id } satisfies Reply))
+      .catch((err: unknown) =>
+        channel.send({
+          id: command.id,
+          error: err instanceof Error ? err.message : String(err),
+        } satisfies Reply),
+      );
+  });
+
+  return () => {
+    offCommands();
+    offEvents();
+    void adapter.dispose();
+  };
+}
+
+/**
+ * Apply one command, checking what came across the boundary.
+ *
+ * These arrive as `unknown` from another process — a renderer that reloaded
+ * mid-flight, a host wiring the channel to the wrong window, a future version
+ * sending a field this one has never heard of. Validating here means a bad
+ * message becomes an error reply the runtime can fail over from, rather than a
+ * `TypeError` thrown inside somebody's renderer where nothing is listening.
+ */
+async function run(adapter: MediaElementAdapter, command: Command): Promise<void> {
+  const params = (command.params ?? {}) as Record<string, unknown>;
+
+  switch (command.method) {
+    case 'load': {
+      const binding = params.binding as Binding | undefined;
+      if (!binding || typeof binding.nativeUri !== 'string') {
+        throw new Error('load requires a binding with a nativeUri');
+      }
+      const startAtMs = typeof params.startAtMs === 'number' ? params.startAtMs : undefined;
+      return adapter.load(binding, startAtMs === undefined ? undefined : { startAtMs });
+    }
+    case 'play':
+      return adapter.play();
+    case 'pause':
+      return adapter.pause();
+    case 'stop':
+      return adapter.stop();
+    case 'seek': {
+      const positionMs = params.positionMs;
+      if (typeof positionMs !== 'number' || !Number.isFinite(positionMs)) {
+        throw new Error('seek requires a finite positionMs');
+      }
+      return adapter.seek(positionMs);
+    }
+    case 'setVolume': {
+      const volume = params.volume;
+      if (typeof volume !== 'number' || !Number.isFinite(volume)) {
+        throw new Error('setVolume requires a finite volume');
+      }
+      return adapter.setVolume(volume);
+    }
+    default:
+      throw new Error(`unknown method ${String(command.method)}`);
+  }
+}

package/src/sources.ts

@@ -0,0 +1,123 @@
+import type { MediaRef } from 'upnext-core';
+
+/**
+ * What a media element can and cannot be handed.
+ *
+ * The temptation with a browser adapter is to claim the web, because "the
+ * browser can play anything" feels true. It is not. An `<audio>` element plays
+ * a *media stream*; it does not play a *page*. Handing it a YouTube watch URL
+ * gets you a lump of HTML and a decode error, and the difference matters
+ * because a queue full of things that fail at the last moment is worse than one
+ * that admitted it could not take them.
+ */
+
+/** Container and codec extensions a media element will normally accept. */
+const PLAYABLE_EXTENSIONS = new Set([
+  '.mp3', '.m4a', '.m4b', '.aac', '.wav', '.flac', '.ogg', '.oga', '.opus',
+  '.weba', '.webm', '.mp4', '.m4v', '.mov', '.aiff', '.aif', '.caf',
+  // Adaptive manifests. Native only in Safari without a library, but a host
+  // that has attached hls.js to its element makes these work, and the element
+  // is the host's to configure.
+  '.m3u8', '.mpd',
+]);
+
+/**
+ * Pages that play media *inside* them, which is not the same as being media.
+ *
+ * Listed explicitly and scored zero rather than left to fall through the
+ * extension check, because these are exactly what somebody will try first. A
+ * silent zero sends the entry to another adapter or fails it honestly; a
+ * hopeful guess plays nothing and blames the file.
+ *
+ * Making these work needs a page-level integration — YouTube's IFrame player,
+ * a SoundCloud widget, a stream extractor — which is a different adapter with
+ * different terms of service, not a smarter regex here.
+ */
+const PAGE_HOSTS = [
+  'youtube.com', 'youtu.be', 'music.youtube.com',
+  'open.spotify.com', 'music.apple.com',
+  'soundcloud.com', 'bandcamp.com', 'mixcloud.com',
+  'vimeo.com', 'twitch.tv',
+];
+
+export function canPlay(uri: string, extraExtensions?: string[]): boolean {
+  return score({ uri }, extraExtensions) > 0;
+}
+
+/**
+ * How confident this element is that it can play the ref.
+ *
+ * A direct media URL scores 1. An `http(s)` URL with no recognisable extension
+ * scores low but non-zero — podcast enclosures are routinely extensionless
+ * redirects, and "try me last" is the honest answer for those: if it fails,
+ * the binder moves to the next source, which is exactly the machinery for it.
+ */
+export function score(ref: MediaRef, extraExtensions?: string[]): number {
+  const uri = ref.uri;
+  if (!uri) return 0;
+
+  // Anything the host has already turned into bytes is certain.
+  if (uri.startsWith('blob:')) return 1;
+  if (uri.startsWith('data:audio/') || uri.startsWith('data:video/')) return 1;
+
+  const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(uri)?.[1]?.toLowerCase();
+
+  const extension = extensionOf(uri);
+  const known = extension !== null && isKnown(extension, extraExtensions);
+
+  if (scheme === 'file') {
+    // Works in an Electron renderer and in a webview; a plain web page will be
+    // refused by the browser itself. Below a direct http URL, above a guess.
+    return known ? 0.8 : 0;
+  }
+
+  if (scheme !== 'http' && scheme !== 'https') return 0;
+  if (isPage(uri)) return 0;
+  if (known) return 1;
+
+  // A URL that *names* a format we do not handle is a no, not a maybe —
+  // `.html` and `.json` are not things to try hopefully and fail on.
+  if (extension !== null) return 0;
+
+  // No extension at all. Podcast enclosures are routinely extensionless
+  // redirects, so this is worth trying once nothing better has offered.
+  return 0.2;
+}
+
+/** A short label for a URL, so a queue does not show a column of raw links. */
+export function describeSource(uri: string): string {
+  try {
+    const url = new URL(uri);
+    const last = url.pathname.split('/').filter(Boolean).pop();
+    if (last) return decodeURIComponent(last.replace(/\.[^.]+$/, ''));
+    return url.hostname;
+  } catch {
+    return uri;
+  }
+}
+
+function isPage(uri: string): boolean {
+  let host: string;
+  try {
+    host = new URL(uri).hostname.toLowerCase().replace(/^www\./, '');
+  } catch {
+    return false;
+  }
+  return PAGE_HOSTS.some((page) => host === page || host.endsWith(`.${page}`));
+}
+
+/** The extension of the last path segment, or null when there isn't one. */
+function extensionOf(uri: string): string | null {
+  // Query strings and fragments are stripped first: signed podcast URLs carry
+  // `?updated=...` after the extension and would otherwise never match.
+  const path = uri.split(/[?#]/)[0] ?? '';
+  const segment = path.slice(path.lastIndexOf('/') + 1);
+  const dot = segment.lastIndexOf('.');
+  // A leading dot is a hidden file, not an extension.
+  if (dot <= 0) return null;
+  return segment.slice(dot).toLowerCase();
+}
+
+function isKnown(extension: string, extra?: string[]): boolean {
+  return PLAYABLE_EXTENSIONS.has(extension) || (extra?.includes(extension) ?? false);
+}