Player Contract

Player Contract

Contract Purpose

The manager interacts with players only through a normalized contract.

This prevents manager behavior from depending on any specific player SDK.

Required Methods

interface VideoTrimPlayerContract {
  play(): void | Promise<void>;
  pause(): void | Promise<void>;
  seek(timeSeconds: number): void | Promise<void>;
  getCurrentTime(): number;
  getDuration(): number;
  subscribeToTimeUpdates(callback: (timeSeconds: number) => void): () => void;
}

Behavioral Expectations

1. getDuration() returns a positive finite number when manager initializes.
2. seek(time) accepts seconds and should clamp/handle out-of-range safely at adapter boundary.
3. subscribeToTimeUpdates() must return an unsubscribe function.
4. Time update callback values must be seconds.

Adapter Strategy

Current v1.1 strategy uses one concrete adapter path.

Hook entrypoint: useTrimPlayerAdapter

Expected responsibility:

Player SDK instance
  ↓
Adapter
  ↓
VideoTrimPlayerContract

Adapter Example (HTMLVideoElement)

const contract: VideoTrimPlayerContract = {
  play: () => video.play(),
  pause: () => video.pause(),
  seek: (timeSeconds) => {
    video.currentTime = Math.max(0, timeSeconds);
  },
  getCurrentTime: () => video.currentTime,
  getDuration: () => video.duration,
  subscribeToTimeUpdates: (callback) => {
    const onTime = () => callback(video.currentTime);
    video.addEventListener('timeupdate', onTime);
    return () => video.removeEventListener('timeupdate', onTime);
  },
};