Plugin: Tab Leader

TabLeaderPlugin (id 'tab-leader') uses the Web Locks API to elect one browser tab as the “leader” allowed to play, so opening the same page in two tabs doesn’t play audio in both. Not re-exported from the main entry, import it from the plugins/tab-leader subpath.

Options

Option	Type	Default	Purpose
`onLost`	`'pause' \| 'mute'`	`'pause'`	What happens when this tab loses leadership.
`handoffOnVisible`	`boolean`	`true`	Re-request the lock automatically when the tab becomes visible again.
`getLockKey`	`() => string`	fixed key `'nomercy-player-leader'`	Scope the lock to a specific player/session instead of the whole origin.

Events

leader-acquired, leader-released, unsupported.

Rules & restrictions

Built on the Web Locks API: Safari 15.4+, Chrome 69+, Firefox 96+. Where navigator.locks is absent, the plugin emits unsupported and becomes a no-op, playback is unaffected, it just doesn’t coordinate across tabs.
The default lock key is global to the entire origin: with no getLockKey override, only one tab across your whole site plays at a time, not one per player instance. Supply getLockKey to scope it (e.g. per media item or per logical session) if that global default isn’t what you want.

How to extend it

TypeScript

import nmplayer from '@nomercy-entertainment/nomercy-video-player'; // nomercy-music-player's factory works identically
import { TabLeaderPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/tab-leader';

const player = nmplayer('player');

player.addPlugin(TabLeaderPlugin, {
	onLost: 'pause',
	getLockKey: () => `nomercy-player-${player.id}`, // scope per player instance instead of per origin
});
await player.ready();

console.log(player.getPlugin(TabLeaderPlugin)?.isLeader());

Next steps

Adapter: Storage: the first of the ten swappable adapter ports, purpose, defaults, and how to extend each.