Skip to content

LiveTranscodingPlugin

LiveTranscodingPlugin is the reserved surface for server-coordinated live transcoding in the music player. The plugin gates playback until the server transcoder has produced enough buffer, and instructs the backend to pause segment fetching when the buffer is full.

This plugin is a stub in v2.0. use() throws NotImplementedError internally, but the core’s plugin registration catches that error, logs it, disables the plugin, and emits plugin:failed. No exception surfaces to your code. Do not register it in production until v2.1 ships.

TypeScript
import { LiveTranscodingPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

Plugin id: 'live-transcoding'

What it does

The plugin is responsible for two things once it is implemented. First, it holds playback at start until the transcoder has produced at least resumeAheadSeconds of buffer past time. Second, it signals the segment loader to pause when the buffer is full and resume when it drains, so the encoder does not race ahead and waste compute.

This behavior is roadmapped for v2.1 and is not active in v2.0.

Options

These fields are declared in LiveTranscodingOptions and will be read by the implemented plugin in v2.1. They are reserved now so you can write your integration code against them today.

OptionTypeDefaultDescription
wsUrlstringrequiredServer endpoint that owns the transcoding job lifecycle.
pollIntervalMsnumberundefinedOptional polling fallback for environments without WebSocket support.
resumeAheadSecondsnumberundefinedSeconds of buffer that must exist beyond time before resuming.
seekTimeoutMsnumberundefinedWhen seeking, maximum milliseconds to wait for the transcoder to reach the target position.

Events

Because the plugin is a stub in v2.0, none of the LiveTranscodingEvents are ever emitted. The table below documents the events that the base Plugin class fires; those are the only events that fire today. The LiveTranscodingEvents payload shapes are reserved for v2.1.

EventPayloadDescription
plugin:live-transcoding:enabled{ id: string }Fired by the base Plugin class when enable() is called.
plugin:live-transcoding:disabled{ id: string; reason?: string }Fired by the base Plugin class when disable() is called.

Reserved for v2.1 (not emitted today): job:started, job:progress, job:ready-to-play, job:error, job:complete, segment:ready, unsupported.

Registration

The plugin class is exported under two names: LiveTranscodingPlugin (class) and liveTranscodingPlugin (alias constant). Both work with addPlugin().

Because use() fails internally in v2.0, the core disables the plugin silently. Listen to plugin:failed or plugin:live-transcoding:failed after setup() to detect this:

TypeScript
import nmMPlayer from '@nomercy-entertainment/nomercy-music-player';
import { LiveTranscodingPlugin } from '@nomercy-entertainment/nomercy-music-player/plugins';

const player = nmMPlayer('main')
  .addPlugin(LiveTranscodingPlugin, {
    wsUrl: 'wss://your-server.example.com/transcode',
    resumeAheadSeconds: 10,
    seekTimeoutMs: 8,
  })
  .setup({
    playlist: [
      {
        id: '1',
        name: 'Intro - The Way Of Waking Up (feat. Alan Watts)',
        url: 'https://raw.githubusercontent.com/NoMercy-Entertainment/nomercy-media/master/Music/T/The%20Kyoto%20Connection/%5B2013%5D%20Wake%20Up/01%20Intro%20-%20The%20Way%20Of%20Waking%20Up%20(feat.%20Alan%20Watts).mp3',
      },
    ],
  });

player.on('plugin:live-transcoding:failed', ({ id, error }) => {
  console.warn(`${id} is not available in v2.0:`, error.message);
});

See also