Skip to content

Plugin: Key Handler

KeyHandlerPlugin (id 'key-handler') is a keyboard-binding router: one keydown listener that dispatches combo strings ('Space', 'ArrowLeft', 'm') to callbacks. It isn’t re-exported from the package’s main entry, import it from the plugins/key-handler subpath.

Options

OptionTypeDefaultPurpose
scope'document' | 'container' | HTMLElement'document'Where the listener attaches.
bindingsRecord<string, (player) => void>—Your own combo-to-callback map.
extendbooleantrueMerge bindings with the defaults instead of replacing them.
when(event: KeyboardEvent) => boolean—Extra gate, return false to suppress handling entirely.
cooldownMsnumber300Throttle window. 0 disables throttling.
disableMediaControlsbooleanfalseTurn off the hardware MediaX key bindings specifically.

Rules & restrictions

  • Default bindings: Space toggles playback, ArrowLeft/ArrowRight seek ±5s, ArrowUp/ArrowDown adjust volume, m toggles mute, plus the eight W3C hardware media keys (MediaPlay, MediaPause, and the rest).
  • Keys are silently ignored when the event target is an <input>, <textarea>, <select>, or any contenteditable element, so the player never steals keystrokes from a form on the same page.
  • disableMediaControls gates every MediaX binding individually, it doesn’t touch the non-hardware defaults (Space, arrows, m).

How to extend it

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player'; // nomercy-music-player's factory works identically
import { KeyHandlerPlugin } from '@nomercy-entertainment/nomercy-player-core/plugins/key-handler';

const player = nmplayer('player');

player.addPlugin(KeyHandlerPlugin, {
	bindings: { 'l': player => player.forward(10) }, // your own combo, merged with defaults
});
await player.ready();

const keys = player.getPlugin(KeyHandlerPlugin);
keys!.bind('k', p => p.pause());
keys!.unbind('m'); // remove just the mute default

Next steps