Skip to content

Overview

The preload and transition system controls what happens at the boundary between two queue items. The preload strategy decides when and what to prefetch. The transition strategy decides how the handoff from outgoing to incoming item is handled.

Both are stateless, a single instance is reused across items, and swappable per player instance via BasePlayerConfig or at runtime.

PreloadStrategy

Interface

TypeScript
interface IPreloadStrategy {
  shouldPreload(context: PreloadContext): boolean;
  assetsToPreload(item: BasePlaylistItem): PreloadAsset[];
  cancel(): void;
}
MethodWhen calledPurpose
shouldPreload(context)Every time event while a next item is queuedReturn true when prefetching should begin
assetsToPreload(item)Once when shouldPreload returns trueReturn the ordered list of assets to prefetch
cancel()Cursor jump (shuffle, manual current(), early next())Abort any in-flight prefetch

PreloadContext

TypeScript
interface PreloadContext {
  currentTime: number; // seconds
  duration: number; // seconds (0 when not yet known)
  nextItem: BasePlaylistItem | null;
}

DefaultPreloadStrategy

Fires at duration - preloadLeadSeconds (config field, default 10). Returns a generic manifest URL from the next item. Per-library players (music, video) compose domain-specific asset lists on top by providing their own assetsToPreload implementations.

Custom preload strategy

TypeScript
player.setup({
  preloadStrategy: {
    shouldPreload({ currentTime, duration }) {
      return duration > 0 && duration - currentTime < 20;
    },
    assetsToPreload(item: VideoItem) {
      return [{ url: item.url, category: 'media', mode: 'metadata' }];
    },
    cancel() {
      // abort any in-flight fetch you started
    },
  },
});

TransitionStrategy

Interface

TypeScript
interface ITransitionStrategy {
  shouldTransition(context: PreloadContext): boolean;
  start(outgoing: BasePlaylistItem, incoming: BasePlaylistItem, backend: ITransitionBackend | null): void;
  tick(context: TransitionContext, backend: ITransitionBackend | null): void;
  complete(from: BasePlaylistItem, to: BasePlaylistItem): void;
  cancel(reason: string): void;
}

TransitionContext

TypeScript
interface TransitionContext {
  currentTime: number;
  duration: number;
  outgoingItem: BasePlaylistItem;
  incomingItem: BasePlaylistItem;
  fraction: number; // 0 = transition start, 1 = complete
}

ITransitionBackend

The dual-playback surface required by the transition engine. Audio backends that support crossfade implement this:

TypeScript
interface ITransitionBackend {
  supportsCrossfade(): boolean;
  loadSecondary(url: string): Promise<void>;
  primeSecondary(seekMs?: number): Promise<void>;
  crossfade(durationMs: number): Promise<void>;
  disposeSecondary(): void;
  secondaryGain(): number;
  secondaryGain(value: number): void;
}

Built-in strategies

DefaultPreloadStrategy

Standard preload, fires at duration - preloadLeadSeconds. Exported from:

TypeScript
import { DefaultPreloadStrategy } from '@nomercy-entertainment/nomercy-player-core';

GaplessTransitionStrategy

Hard-cut, no audio overlap. Default for the video player. Items are still preloaded; there is no audio crossfade.

CrossfadeTransitionStrategy

Overlap crossfade. Default for the music player. Outgoing item fades out over crossfadeTailSeconds; incoming item fades in starting crossfadeLeadSeconds before the outgoing ends.

TypeScript
import {
  DefaultPreloadStrategy,
  GaplessTransitionStrategy,
  CrossfadeTransitionStrategy,
} from '@nomercy-entertainment/nomercy-player-core';

Config fields

FieldTypeDefaultDescription
preloadLeadSecondsnumber10Seconds before end to begin prefetching
crossfadeLeadSecondsnumber3Seconds before end to begin crossfade
crossfadeTailSecondsnumber3Seconds of audio overlap during crossfade
crossfadeEnabledbooleantrue (music) / false (video)Enable crossfade transition
preloadStrategyIPreloadStrategyDefaultPreloadStrategyCustom preload strategy
transitionStrategyITransitionStrategyPer-library defaultCustom transition strategy

Preload events

EventPayloadWhen
preloadStart{ item, assets }Prefetch began for next item
preloadProgress{ item, loaded, total }Individual asset completed
preloadComplete{ item }All assets fetched
preloadError{ item, error }One or more assets failed (non-fatal)
transitionStart{ outgoing, incoming }Transition window began
transitionProgress{ outgoing, incoming, fraction }Per-frame progress
transitionComplete{ from, to }Transition done
transitionCancelled{ reason }Transition aborted

See also