unified-video-framework 1.0.0

package/packages/core/src/interfaces/IVideoPlayer.ts

@@ -0,0 +1,184 @@
+/**
+ * Core video player interface that all platform implementations must follow
+ */
+
+export interface VideoSource {
+  url: string;
+  type?: 'mp4' | 'hls' | 'dash' | 'webm' | 'auto';
+  drm?: DRMConfig;
+  subtitles?: SubtitleTrack[];
+  metadata?: VideoMetadata;
+}
+
+export interface DRMConfig {
+  licenseUrl: string;
+  certificateUrl?: string;
+  headers?: Record<string, string>;
+  type: 'widevine' | 'playready' | 'fairplay' | 'clearkey';
+}
+
+export interface SubtitleTrack {
+  url: string;
+  language: string;
+  label: string;
+  kind: 'subtitles' | 'captions' | 'descriptions';
+  default?: boolean;
+}
+
+export interface VideoMetadata {
+  id?: string;
+  title?: string;
+  description?: string;
+  duration?: number;
+  thumbnailUrl?: string;
+  posterUrl?: string;
+}
+
+export interface Quality {
+  height: number;
+  width: number;
+  bitrate: number;
+  label: string;
+  index: number;
+}
+
+export interface PlayerState {
+  isPlaying: boolean;
+  isPaused: boolean;
+  isBuffering: boolean;
+  isEnded: boolean;
+  isError: boolean;
+  currentTime: number;
+  duration: number;
+  bufferedPercentage: number;
+  volume: number;
+  isMuted: boolean;
+  playbackRate: number;
+  currentQuality?: Quality;
+  availableQualities: Quality[];
+}
+
+export interface PlayerEvents {
+  onReady?: () => void;
+  onPlay?: () => void;
+  onPause?: () => void;
+  onEnded?: () => void;
+  onTimeUpdate?: (time: number) => void;
+  onBuffering?: (isBuffering: boolean) => void;
+  onError?: (error: PlayerError) => void;
+  onQualityChanged?: (quality: Quality) => void;
+  onVolumeChanged?: (volume: number) => void;
+  onFullscreenChanged?: (isFullscreen: boolean) => void;
+  onProgress?: (buffered: number) => void;
+  onSeeking?: () => void;
+  onSeeked?: () => void;
+  onLoadedMetadata?: (metadata: VideoMetadata) => void;
+  // Fired exactly once when free preview duration is reached and playback is blocked
+  onFreePreviewEnded?: () => void;
+}
+
+export interface PlayerError {
+  code: string;
+  message: string;
+  type: 'network' | 'media' | 'drm' | 'unknown';
+  fatal: boolean;
+  details?: any;
+}
+
+export interface PaywallConfig {
+  enabled: boolean;
+  apiBase: string;          // e.g., http://localhost:3100
+  userId: string;
+  videoId: string;
+  gateways: Array<'stripe' | 'cashfree'>;
+  branding?: { title?: string; description?: string; logoUrl?: string; theme?: any };
+  popup?: { width?: number; height?: number };
+}
+
+export interface PlayerConfig {
+  autoPlay?: boolean;
+  muted?: boolean;
+  volume?: number;
+  controls?: boolean;
+  loop?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  playsInline?: boolean;
+  defaultQuality?: number;
+  enableAdaptiveBitrate?: boolean;
+  debug?: boolean;
+
+  // Free preview
+  freeDuration?: number; // seconds of free playback before paywall
+
+  // Optional paywall for dynamic rental flow
+  paywall?: PaywallConfig;
+}
+
+/**
+ * Main video player interface
+ */
+export interface IVideoPlayer {
+  // Lifecycle methods
+  initialize(container: HTMLElement | string, config?: PlayerConfig): Promise<void>;
+  destroy(): Promise<void>;
+
+  // Media control
+  load(source: VideoSource): Promise<void>;
+  play(): Promise<void>;
+  pause(): void;
+  stop(): void;
+  seek(time: number): void;
+
+  // Volume control
+  setVolume(level: number): void;
+  mute(): void;
+  unmute(): void;
+  toggleMute(): void;
+
+  // Quality control
+  getQualities(): Quality[];
+  getCurrentQuality(): Quality | null;
+  setQuality(index: number): void;
+  setAutoQuality(enabled: boolean): void;
+
+  // Playback control
+  setPlaybackRate(rate: number): void;
+  getPlaybackRate(): number;
+
+  // State queries
+  getCurrentTime(): number;
+  getDuration(): number;
+  getBufferedPercentage(): number;
+  getState(): PlayerState;
+  isPlaying(): boolean;
+  isPaused(): boolean;
+  isEnded(): boolean;
+
+  // Display control
+  enterFullscreen(): Promise<void>;
+  exitFullscreen(): Promise<void>;
+  toggleFullscreen(): Promise<void>;
+  enterPictureInPicture(): Promise<void>;
+  exitPictureInPicture(): Promise<void>;
+
+  // Event handling
+  on(event: keyof PlayerEvents, handler: Function): void;
+  off(event: keyof PlayerEvents, handler?: Function): void;
+  once(event: keyof PlayerEvents, handler: Function): void;
+
+  // Subtitle control
+  getSubtitles(): SubtitleTrack[];
+  setSubtitleTrack(index: number): void;
+  disableSubtitles(): void;
+
+  // Advanced features
+  setAudioTrack?(index: number): void;
+  getAudioTracks?(): any[];
+  getThumbnail?(time: number): string;
+  getStats?(): any;
+
+  // Free preview runtime controls (optional)
+  setFreeDuration?(seconds: number): void;
+  resetFreePreviewGate?(): void;
+}

package/packages/core/src/interfaces.ts

@@ -0,0 +1,240 @@
+// Core TypeScript interfaces for the unified video framework
+
+export enum PlatformType {
+  IOS = 'ios',
+  ANDROID = 'android',
+  TIZEN = 'tizen',
+  WEBOS = 'webos',
+  ROKU = 'roku',
+  ANDROID_TV = 'androidtv',
+  APPLE_TV = 'appletv',
+  WEB = 'web',
+  WINDOWS = 'windows'
+}
+
+export enum PlayerState {
+  IDLE = 'idle',
+  LOADING = 'loading',
+  READY = 'ready',
+  PLAYING = 'playing',
+  PAUSED = 'paused',
+  BUFFERING = 'buffering',
+  ENDED = 'ended',
+  ERROR = 'error'
+}
+
+export enum DRMType {
+  FAIRPLAY = 'fairplay',
+  WIDEVINE = 'widevine',
+  PLAYREADY = 'playready',
+  CLEARKEY = 'clearkey'
+}
+
+export interface VideoSource {
+  url: string;
+  type?: string;
+  title?: string;
+  description?: string;
+  thumbnail?: string;
+  duration?: number;
+  drm?: DRMConfig;
+  subtitles?: SubtitleTrack[];
+  metadata?: Record<string, any>;
+}
+
+export interface DRMConfig {
+  type: DRMType;
+  licenseUrl: string;
+  certificateUrl?: string;
+  headers?: Record<string, string>;
+  customData?: string;
+  fairplayOptions?: {
+    certificateUrl: string;
+    licenseUrl: string;
+  };
+  widevineOptions?: {
+    licenseUrl: string;
+    serverCertificate?: ArrayBuffer;
+  };
+  playreadyOptions?: {
+    licenseUrl: string;
+    customData?: string;
+  };
+}
+
+export interface SubtitleTrack {
+  id: string;
+  label: string;
+  language: string;
+  url?: string;
+  kind?: 'subtitles' | 'captions' | 'descriptions';
+  default?: boolean;
+}
+
+export interface AudioTrack {
+  id: string;
+  label: string;
+  language: string;
+  channels?: number;
+  bitrate?: number;
+  codec?: string;
+}
+
+export interface Quality {
+  id: string;
+  label: string;
+  height: number;
+  width: number;
+  bitrate: number;
+  frameRate?: number;
+  codec?: string;
+}
+
+export interface AdaptiveBitrateConfig {
+  minBitrate?: number;
+  maxBitrate?: number;
+  startBitrate?: number;
+  autoLevelEnabled?: boolean;
+  startLevel?: number;
+}
+
+export interface VideoPlayerConfig {
+  autoPlay?: boolean;
+  muted?: boolean;
+  controls?: boolean;
+  loop?: boolean;
+  preload?: 'none' | 'metadata' | 'auto';
+  crossOrigin?: 'anonymous' | 'use-credentials';
+  playsInline?: boolean;
+  pictureInPicture?: boolean;
+  adaptiveBitrate?: AdaptiveBitrateConfig;
+  drm?: DRMConfig;
+  analytics?: AnalyticsConfig;
+  ads?: AdsConfig;
+  cast?: CastConfig;
+  offline?: OfflineConfig;
+}
+
+export interface AnalyticsConfig {
+  enabled: boolean;
+  providers: AnalyticsProvider[];
+  trackingInterval?: number;
+  customDimensions?: Record<string, any>;
+}
+
+export interface AnalyticsProvider {
+  name: string;
+  config: Record<string, any>;
+  track: (event: string, data: any) => void;
+}
+
+export interface AdsConfig {
+  enabled: boolean;
+  adTagUrl?: string;
+  adsManager?: any;
+  midrollPositions?: number[];
+  companionAds?: {
+    width: number;
+    height: number;
+    container: HTMLElement;
+  };
+}
+
+export interface CastConfig {
+  enabled: boolean;
+  receiverApplicationId?: string;
+  autoJoinPolicy?: 'ORIGIN_SCOPED' | 'TAB_AND_ORIGIN_SCOPED' | 'PAGE_SCOPED';
+}
+
+export interface OfflineConfig {
+  enabled: boolean;
+  storageLimit?: number;
+  downloadQuality?: 'auto' | 'high' | 'medium' | 'low';
+}
+
+export interface PlayerMetrics {
+  sessionId: string;
+  playbackStarted?: number;
+  totalPlayTime: number;
+  bufferingCount: number;
+  bufferingDuration: number;
+  averageBitrate: number;
+  qualityChanges: number;
+  errors: PlayerError[];
+  bandwidth?: number;
+  droppedFrames?: number;
+  decodedFrames?: number;
+}
+
+export interface PlayerError {
+  code: string;
+  message: string;
+  timestamp: number;
+  fatal: boolean;
+  data?: any;
+}
+
+export interface ProgressEvent {
+  currentTime: number;
+  duration: number;
+  buffered: TimeRanges;
+  seekable: TimeRanges;
+  played: TimeRanges;
+}
+
+export interface TimeRanges {
+  length: number;
+  start(index: number): number;
+  end(index: number): number;
+}
+
+export interface PlatformInfo {
+  type: PlatformType;
+  os: string;
+  version: string;
+  isTV: boolean;
+  isMobile: boolean;
+  isDesktop?: boolean;
+  hasTouch?: boolean;
+  screenSize?: {
+    width: number;
+    height: number;
+  };
+}
+
+export type PlayerEvent = 
+  | 'ready'
+  | 'play'
+  | 'pause'
+  | 'ended'
+  | 'error'
+  | 'loadstart'
+  | 'loadedmetadata'
+  | 'timeupdate'
+  | 'progress'
+  | 'seeking'
+  | 'seeked'
+  | 'waiting'
+  | 'canplay'
+  | 'canplaythrough'
+  | 'volumechange'
+  | 'ratechange'
+  | 'qualitychange'
+  | 'subtitlechange'
+  | 'audiotrackchange'
+  | 'fullscreenchange'
+  | 'pictureInPicturechange'
+  | 'castStateChanged'
+  | 'adstart'
+  | 'adend'
+  | 'aderror';
+
+export type EventHandler = (data?: any) => void;
+
+export interface EventEmitter {
+  on(event: PlayerEvent, handler: EventHandler): void;
+  off(event: PlayerEvent, handler: EventHandler): void;
+  once(event: PlayerEvent, handler: EventHandler): void;
+  emit(event: PlayerEvent, data?: any): void;
+  removeAllListeners(event?: PlayerEvent): void;
+}

package/packages/core/src/utils/EventEmitter.ts

@@ -0,0 +1,66 @@
+/**
+ * Simple event emitter for handling player events
+ */
+
+type EventHandler = (...args: any[]) => void;
+
+export class EventEmitter {
+  private events: Map<string, Set<EventHandler>>;
+
+  constructor() {
+    this.events = new Map();
+  }
+
+  on(event: string, handler: EventHandler): void {
+    if (!this.events.has(event)) {
+      this.events.set(event, new Set());
+    }
+    this.events.get(event)!.add(handler);
+  }
+
+  off(event: string, handler?: EventHandler): void {
+    if (!this.events.has(event)) return;
+    
+    if (handler) {
+      this.events.get(event)!.delete(handler);
+    } else {
+      this.events.delete(event);
+    }
+  }
+
+  once(event: string, handler: EventHandler): void {
+    const onceWrapper = (...args: any[]) => {
+      handler(...args);
+      this.off(event, onceWrapper);
+    };
+    this.on(event, onceWrapper);
+  }
+
+  emit(event: string, ...args: any[]): void {
+    if (!this.events.has(event)) return;
+    
+    this.events.get(event)!.forEach(handler => {
+      try {
+        handler(...args);
+      } catch (error) {
+        console.error(`Error in event handler for ${event}:`, error);
+      }
+    });
+  }
+
+  removeAllListeners(event?: string): void {
+    if (event) {
+      this.events.delete(event);
+    } else {
+      this.events.clear();
+    }
+  }
+
+  listenerCount(event: string): number {
+    return this.events.has(event) ? this.events.get(event)!.size : 0;
+  }
+
+  eventNames(): string[] {
+    return Array.from(this.events.keys());
+  }
+}