Core Adapter Ports

We provide the adapter pattern so you can change how the player behaves whenever you have a need that’s a bit unique, something that shouldn’t be the default for everyone. Every piece here, like where state gets saved, how the player talks to a server, or which clock it reads, already has a sensible default wired in. You only reach for an adapter when that default doesn’t fit you.

Say you want the player to remember resume positions and volume on your own server instead of in the browser, so they follow your users from their phone to their TV. You don’t fork anything or go digging through player internals for that. You write a small storage adapter that reads and writes against your API, hand it to setup(), and everything else carries on exactly as before. The player never knows where the bytes actually go, it just asks the port and gets an answer.

That’s really all a port is: a clearly defined slot with a default sitting in it. Swapping what’s in the slot is how you make the player yours without making it everyone’s.

This is also the line between an adapter and a plugin. If you’re changing how something the player already does works on the inside, that’s a port swap. If you’re adding something new for the player to do, like an equalizer or a skip button, that’s a plugin. Plugins and adapters covers when to reach for each.

The core ships the ports below. Libraries built on the core add ports of their own, documented with whichever library owns them.

How to wire a port

All ports are wired through setup():

import {
  LocalStorageBackend,
  MemoryStorageBackend,
} from '@nomercy-entertainment/nomercy-player-core';
import { browserPlatform } from '@nomercy-entertainment/nomercy-player-core';

player.setup({
  storage: new MemoryStorageBackend(), // swap LocalStorage for in-memory
  platform: {
    ...browserPlatform,
    wakeLock: myNativeWakeLock, // override one sub-port, keep the rest
  },
  logger: myPinoLogger, // wire a Pino adapter
});

Core adapter catalog

Core infrastructure

Auth and fetch

Platform abstraction

The platform config key accepts an IPlatform bundle. Override individual sub-ports using spread:

platform: { ...browserPlatform, wakeLock: myNativeWakeLock }

Streaming

i18n

Subtitles and cues

Realtime

Miscellaneous

Storage backends

Three implementations ship with the core:

import {
  LocalStorageBackend,
  MemoryStorageBackend,
  IndexedDBBackend,
} from '@nomercy-entertainment/nomercy-player-core';

// Default: persists across sessions, shared across tabs:
storage: new LocalStorageBackend();

// Ephemeral: ideal for tests; no persistence, no cross-tab state:
storage: new MemoryStorageBackend();

// High-capacity: for large datasets (EQ preset libraries, subtitle cache):
storage: new IndexedDBBackend({ dbName: 'my-player-db' });

All three implement IStorage:

interface IStorage {
  get(key: string): string | null | Promise<string | null>;
  set(key: string, value: string): void | Promise<void>;
  remove(key: string): void | Promise<void>;
  getJSON<T>(key: string): T | null | Promise<T | null>;
  setJSON<T>(key: string, value: T): void | Promise<void>;
}

Methods may return values or Promises so synchronous backends (LocalStorageBackend) and asynchronous ones (IndexedDBBackend, remote API) share one interface. Plugin code always uses await regardless.

Writing a custom adapter

Implement the interface and pass the instance at setup:

import type { IStorage } from '@nomercy-entertainment/nomercy-player-core';

class RemoteStorageBackend implements IStorage {
  get(key: string): string | null {
    return sessionStorage.getItem(key);
  }
  set(key: string, value: string): void {
    sessionStorage.setItem(key, value);
  }
  remove(key: string): void {
    sessionStorage.removeItem(key);
  }
  getJSON<T>(key: string): T | null {
    const raw = this.get(key);
    if (raw === null) return null;
    try { return JSON.parse(raw) as T; } catch { return null; }
  }
  setJSON<T>(key: string, value: T): void {
    this.set(key, JSON.stringify(value));
  }
}

player.setup({ storage: new RemoteStorageBackend() });

Library ports

Libraries built on the core add ports of their own. Those are documented with the library that owns them: see video configuration and music configuration.