Skip to content

Stretching

TypeScript
type Stretching = 'uniform' | 'fill' | 'exactfit' | 'none';

Controls how the video frame is scaled to fill the player container.

ValueBehaviour
'uniform'Letterbox/pillarbox, preserves aspect ratio, may leave bars
'fill'Stretch width and height independently to fill, ignores aspect ratio
'exactfit'Cover-crop to fill, preserving aspect ratio, may clip edges
'none'No scaling, renders at native video resolution

aspectRatio

TypeScript
player.aspectRatio(): Stretching
player.aspectRatio(value: Stretching): void

Read or set the current stretching mode. Emits 'aspectRatio' when the value changes.

TypeScript
import { Stretching } from '@nomercy-entertainment/nomercy-video-player';

const current = player.aspectRatio(); // 'uniform' | 'fill' | 'exactfit' | 'none'
player.aspectRatio('fill');

cycleAspectRatio

TypeScript
player.cycleAspectRatio(): void

Steps through ['uniform', 'fill', 'exactfit', 'none'] in order, wrapping around. Useful for remote-control and keyboard binding contexts where a menu is not practical.

TypeScript
// Bind to the 'a' key (the player has no 'keydown' event — use a DOM listener,
// or let KeyHandlerPlugin own the binding)
document.addEventListener('keydown', (event) => {
  if (event.key === 'a') player.cycleAspectRatio();
});

The KeyHandlerPlugin binds 'a' and 'BrowserFavorites' to cycleAspectRatio() by default. The TvKeyHandlerPlugin overrides this to also emit an OSD message confirming the change.

Event

TypeScript
player.on('aspectRatio', ({ value }) => {
  console.log('New stretching mode:', value);
});
EventPayload
'aspectRatio'{ value: Stretching }

Configuration

Set the initial stretching mode in VideoPlayerConfig:

TypeScript
player.setup({
  baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films',
  stretching: 'uniform',
  playlist: [
    {
      url: '/Sintel.(2010)/Sintel.(2010).NoMercy.m3u8',
    },
  ],
});

Example

TypeScript
import nmplayer from '@nomercy-entertainment/nomercy-video-player';

const player = nmplayer('player').setup({
  baseUrl: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Films',
  stretching: 'uniform',
  playlist: [
    {
      title: 'Big Buck Bunny',
      url: '/Big.Buck.Bunny.(2008)/Big.Buck.Bunny.(2008).NoMercy.m3u8',
    },
  ],
});

document.getElementById('cycle-ar')?.addEventListener('click', () => {
  player.cycleAspectRatio();
});

player.on('aspectRatio', ({ value }) => {
  document.getElementById('ar-label')!.textContent = value;
});

See also