@obipascal/player 1.0.15 → 1.0.16

package/dist/analytics.d.ts

@@ -0,0 +1,36 @@
+import { AnalyticsConfig, AnalyticsEvent } from './types';
+
+/**
+ * Analytics - Tracks player events and quality metrics
+ */
+export declare class Analytics {
+    private config;
+    private sessionId;
+    private events;
+    private sessionStartTime;
+    private playbackStartTime;
+    private totalPlayTime;
+    private totalBufferTime;
+    private bufferStartTime;
+    private rebufferCount;
+    private seekCount;
+    private webSocket;
+    private socketIO;
+    private wsReconnectTimeout;
+    private isDestroyed;
+    constructor(config?: AnalyticsConfig);
+    trackEvent(eventType: string, data?: Record<string, any>): void;
+    private updateMetrics;
+    private getQoEMetrics;
+    private getSessionData;
+    private getConnectionInfo;
+    private sendEvent;
+    private generateSessionId;
+    private initializeSocketIO;
+    private sendToSocketIO;
+    private initializeWebSocket;
+    private sendToWebSocket;
+    getEvents(): AnalyticsEvent[];
+    getMetrics(): Record<string, any>;
+    destroy(): void;
+}

package/dist/file-info.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Video file information extractor
+ * Extracts metadata from video files (width, height, duration, size, etc.)
+ */
+declare global {
+    interface HTMLVideoElement {
+        mozHasAudio?: boolean;
+        webkitAudioDecodedByteCount?: number;
+        audioTracks?: {
+            length: number;
+        };
+    }
+}
+export interface VideoFileInfo {
+    width: number;
+    height: number;
+    aspectRatio: string;
+    size: number;
+    sizeInBytes: number;
+    sizeFormatted: string;
+    duration: number;
+    durationInSeconds: number;
+    durationFormatted: string;
+    mimeType: string;
+    fileName: string;
+    fileExtension: string;
+    bitrate?: number;
+    frameRate?: number;
+    audioChannels?: number;
+    videoCodec?: string;
+    audioCodec?: string;
+    hasAudio?: boolean;
+}
+export declare class WontumFileInfo {
+    private file;
+    private videoElement;
+    private audioContext;
+    private info;
+    constructor(file: File);
+    /**
+     * Check if the file is a valid video file
+     */
+    private isVideoFile;
+    /**
+     * Extract video metadata
+     */
+    extract(): Promise<VideoFileInfo>;
+    /**
+     * Calculate aspect ratio (e.g., "16:9", "4:3")
+     */
+    private calculateAspectRatio;
+    /**
+     * Detect frame rate by analyzing video playback
+     */
+    private detectFrameRate;
+    /**
+     * Detect audio channel information using Web Audio API
+     */
+    private detectAudioInfo;
+    /**
+     * Get Greatest Common Divisor
+     */
+    private getGCD;
+    /**
+     * Format bytes to human-readable size
+     */
+    private formatBytes;
+    /**
+     * Format duration to HH:MM:SS
+     */
+    private formatDuration;
+    /**
+     * Get file extension
+     */
+    private getFileExtension;
+    get width(): number;
+    get height(): number;
+    get aspectRatio(): string;
+    get size(): number;
+    get sizeInBytes(): number;
+    get sizeFormatted(): string;
+    get duration(): number;
+    get durationInSeconds(): number;
+    get durationFormatted(): string;
+    get mimeType(): string;
+    get fileName(): string;
+    get fileExtension(): string;
+    get bitrate(): number | undefined;
+    get frameRate(): number | undefined;
+    get audioChannels(): number | undefined;
+    get hasAudio(): boolean;
+    get quality(): string;
+    /**
+     * Get all information as object
+     */
+    getInfo(): VideoFileInfo | null;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/player.d.ts

@@ -0,0 +1,74 @@
+import { WontumPlayerConfig, PlayerState, PlayerEvent, PlayerEventType, QualityLevel } from './types';
+import { Analytics } from './analytics';
+
+/**
+ * WontumPlayer - A modern HLS video player for educational platforms
+ */
+export declare class WontumPlayer {
+    private container;
+    private videoElement;
+    private hls;
+    private config;
+    private eventListeners;
+    analytics: Analytics;
+    private s3Handler;
+    private uiController;
+    private qualities;
+    private state;
+    constructor(config: WontumPlayerConfig);
+    private addSubtitleTracks;
+    private createVideoElement;
+    private setupVideoListeners;
+    private loadSource;
+    private extractQualities;
+    private handleHlsError;
+    private getAnalyticsData;
+    play(): Promise<void>;
+    pause(): void;
+    seek(time: number): void;
+    skipForward(seconds?: number): void;
+    skipBackward(seconds?: number): void;
+    setVolume(volume: number): void;
+    mute(): void;
+    unmute(): void;
+    setPlaybackRate(rate: number): void;
+    setQuality(qualityIndex: number): void;
+    getQualities(): QualityLevel[];
+    enterFullscreen(): void;
+    exitFullscreen(): void;
+    enterPictureInPicture(): Promise<void>;
+    exitPictureInPicture(): Promise<void>;
+    togglePictureInPicture(): Promise<void>;
+    getState(): PlayerState;
+    getVideoElement(): HTMLVideoElement;
+    /**
+     * Enable subtitles for a specific track
+     */
+    enableSubtitles(trackIndex: number): void;
+    /**
+     * Disable all subtitles
+     */
+    disableSubtitles(): void;
+    /**
+     * Toggle subtitles on/off
+     */
+    toggleSubtitles(): boolean;
+    /**
+     * Get available subtitle tracks
+     */
+    getSubtitleTracks(): TextTrack[];
+    /**
+     * Check if subtitles are currently enabled
+     */
+    areSubtitlesEnabled(): boolean;
+    on(eventType: PlayerEventType, callback: (event: PlayerEvent) => void): void;
+    off(eventType: PlayerEventType, callback: (event: PlayerEvent) => void): void;
+    private emit;
+    /**
+     * Update video source without recreating the entire player
+     * This is more efficient than destroying and recreating the player
+     * @param src - New video source URL
+     */
+    updateSource(src: string): Promise<void>;
+    destroy(): void;
+}

package/dist/react.d.ts

@@ -0,0 +1,104 @@
+import { WontumPlayer } from './player';
+import { WontumPlayerConfig, PlayerState, AnalyticsConfig, AnalyticsEvent } from './types';
+import { VideoFileInfo } from './file-info';
+import * as React from "react";
+export interface WontumPlayerReactProps extends Omit<WontumPlayerConfig, "container"> {
+    /** Callback when player is ready */
+    onReady?: (player: WontumPlayer) => void;
+    /** Callback for player events */
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onTimeUpdate?: (currentTime: number) => void;
+    onVolumeChange?: (volume: number, muted: boolean) => void;
+    onError?: (error: any) => void;
+    onLoadedMetadata?: () => void;
+    onQualityChange?: (level: number) => void;
+    /** Container style */
+    style?: React.CSSProperties;
+    /** Container className */
+    className?: string;
+    /** Width of player */
+    width?: string | number;
+    /** Height of player */
+    height?: string | number;
+}
+/**
+ * WontumPlayerReact - React component wrapper for WontumPlayer
+ */
+export declare const WontumPlayerReact: React.FC<WontumPlayerReactProps>;
+/**
+ * useWontumPlayer - React hook for imperative player control
+ */
+export declare const useWontumPlayer: (config: Omit<WontumPlayerConfig, "container">) => {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    player: WontumPlayer | null;
+    state: PlayerState | null;
+};
+/**
+ * WontumPlayerProvider - Context provider for player instance
+ */
+interface WontumPlayerContextValue {
+    player: WontumPlayer | null;
+    state: PlayerState | null;
+}
+export declare const WontumPlayerProvider: React.FC<{
+    player: WontumPlayer;
+    children: React.ReactNode;
+}>;
+export declare const useWontumPlayerContext: () => WontumPlayerContextValue;
+/**
+ * Hook for extracting video file information
+ * @param file - The video file to analyze (File object or null)
+ * @returns Object containing loading state, error, and video info
+ */
+export interface UseVideoFileInfoResult {
+    /** Video file information (null if not loaded or error occurred) */
+    info: VideoFileInfo | null;
+    /** Whether extraction is in progress */
+    loading: boolean;
+    /** Error message if extraction failed */
+    error: string | null;
+    /** Re-extract file info (useful for retry after error) */
+    refetch: () => Promise<void>;
+}
+export declare const useVideoFileInfo: (file: File | null | undefined) => UseVideoFileInfoResult;
+/**
+ * Result type for useAnalytics hook
+ */
+export interface UseAnalyticsResult {
+    /** Track a custom event */
+    trackEvent: (eventType: string, data?: Record<string, any>) => void;
+    /** Get all tracked events */
+    getEvents: () => AnalyticsEvent[];
+    /** Get analytics metrics (session duration, buffer time, etc.) */
+    getMetrics: () => Record<string, any>;
+    /** WebSocket connection status (for websocket/socket.io analytics) */
+    connected: boolean;
+    /** Session ID for this analytics instance */
+    sessionId: string;
+}
+/**
+ * React hook for analytics tracking
+ * Automatically handles lifecycle management and cleanup
+ *
+ * @example
+ * ```tsx
+ * const { trackEvent, getMetrics, connected } = useAnalytics({
+ *   enabled: true,
+ *   endpoint: "https://api.example.com/analytics",
+ *   videoId: "video-123",
+ *   userId: "user-456",
+ *   webSocket: {
+ *     type: "socket.io",
+ *     url: "https://analytics.example.com",
+ *     auth: { token: "your-token" }
+ *   }
+ * })
+ *
+ * // Track custom events
+ * trackEvent("button_clicked", { buttonName: "share" })
+ * ```
+ */
+export declare const useAnalytics: (config?: AnalyticsConfig) => UseAnalyticsResult;
+export {};

package/dist/s3-handler.d.ts

@@ -0,0 +1,95 @@
+import { S3Config } from './types';
+
+/**
+ * S3Handler - Manages S3/CloudFront URLs and signed cookie authentication
+ */
+export declare class S3Handler {
+    private config;
+    private urlCache;
+    private signedUrls;
+    constructor(config?: S3Config);
+    /**
+     * Process a URL - sign with CloudFront cookies or generate presigned URL for S3
+     */
+    processUrl(url: string): Promise<string>;
+    /**
+     * Check if URL is a CloudFront URL that needs signing
+     */
+    private isCloudFrontUrl;
+    /**
+     * Check if URL is an S3 URL
+     */
+    private isS3Url;
+    /**
+     * Sign CloudFront URL by calling the signing endpoint
+     * The endpoint should set signed cookies and return the URL
+     */
+    private signCloudFrontUrl;
+    /**
+     * Extract S3 key from URL
+     */
+    private extractS3Key;
+    /**
+     * Get presigned URL from cache or generate new one
+     */
+    private getPresignedUrl;
+    /**
+     * Helper to construct S3 URL from bucket and key
+     */
+    static constructS3Url(bucket: string, key: string, region?: string): string;
+    /**
+     * Helper to parse S3 URI (s3://bucket/key)
+     */
+    static parseS3Uri(uri: string): {
+        bucket: string;
+        key: string;
+    } | null;
+    /**
+     * Clear URL cache and signed URLs
+     */
+    clearCache(): void;
+}
+/**
+ * Example CloudFront signed cookie implementation:
+ *
+ * async function signUrl(url: string): Promise<string> {
+ *   const response = await fetch('/api/cloudfront/sign', {
+ *     method: 'POST',
+ *     headers: { 'Content-Type': 'application/json' },
+ *     body: JSON.stringify({ url }),
+ *     credentials: 'include' // Important: include cookies in request
+ *   });
+ *
+ *   const data = await response.json();
+ *   // Backend sets CloudFront signed cookies in response
+ *   // and returns the original URL
+ *   return data.url;
+ * }
+ *
+ * const player = new WontumPlayer({
+ *   src: 'https://media.domain.com/path/to/video/index.m3u8',
+ *   container: '#player',
+ *   s3Config: {
+ *     signUrl,
+ *     cloudFrontDomains: ['media.domain.com']
+ *   }
+ * });
+ *
+ * ---
+ *
+ * Legacy S3 presigned URL example:
+ *
+ * import { S3Client, GetObjectCommand } from '@aws-sdk/client-s3';
+ * import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+ *
+ * const s3Client = new S3Client({ region: 'us-east-1' });
+ *
+ * async function getPresignedUrl(key: string): Promise<string> {
+ *   const command = new GetObjectCommand({
+ *     Bucket: 'your-bucket-name',
+ *     Key: key,
+ *   });
+ *
+ *   return getSignedUrl(s3Client, command, { expiresIn: 3600 });
+ * }
+ */

package/dist/types.d.ts

@@ -0,0 +1,161 @@
+import { Socket } from 'socket.io-client';
+
+/**
+ * Player configuration options
+ */
+export interface WontumPlayerConfig {
+    /** The S3 URL or HLS manifest URL */
+    src: string;
+    /** Container element or selector */
+    container: HTMLElement | string;
+    /** Autoplay video (subject to browser policies) */
+    autoplay?: boolean;
+    /** Start muted */
+    muted?: boolean;
+    /** Show player controls */
+    controls?: boolean;
+    /** Video poster image URL */
+    poster?: string;
+    /** Preload strategy: 'none' | 'metadata' | 'auto' */
+    preload?: "none" | "metadata" | "auto";
+    /** Custom player theme */
+    theme?: PlayerTheme;
+    /** S3 configuration for presigned URLs */
+    s3Config?: S3Config;
+    /** Analytics configuration */
+    analytics?: AnalyticsConfig;
+    /** HLS.js configuration override */
+    hlsConfig?: Partial<any>;
+    /** Subtitle tracks */
+    subtitles?: SubtitleTrack[];
+    /** Keep controls always visible (sticky) */
+    stickyControls?: boolean;
+}
+export interface PlayerTheme {
+    primaryColor?: string;
+    accentColor?: string;
+    fontFamily?: string;
+    controlsBackground?: string;
+    buttonHoverBg?: string;
+    progressHeight?: string;
+    borderRadius?: string;
+}
+export interface S3Config {
+    /** Function to sign URL and set CloudFront cookies (returns the original URL after setting cookies) */
+    signUrl?: (url: string) => Promise<string>;
+    /** Legacy: Function to generate presigned URL (for S3 direct access) */
+    getPresignedUrl?: (key: string) => Promise<string>;
+    /** CloudFront domain patterns to match (e.g., ['media.domain.com']) */
+    cloudFrontDomains?: string[];
+    /** Enable credentials (cookies) for HLS requests - required for CloudFront signed cookies */
+    withCredentials?: boolean;
+    /** S3 bucket region */
+    region?: string;
+    /** Custom S3 endpoint */
+    endpoint?: string;
+}
+export interface AnalyticsConfig {
+    /** Enable analytics */
+    enabled?: boolean;
+    /** Custom analytics endpoint (HTTP/HTTPS) */
+    endpoint?: string;
+    /** WebSocket handler for real-time analytics streaming (supports both native WebSocket and Socket.IO) */
+    webSocket?: WebSocketAnalyticsHandler | SocketIOAnalyticsHandler;
+    /** Session identifier */
+    sessionId?: string;
+    /** User identifier */
+    userId?: string;
+    /** Video identifier */
+    videoId?: string;
+}
+/**
+ * Native WebSocket handler for real-time analytics
+ */
+export interface WebSocketAnalyticsHandler {
+    /** Type identifier for native WebSocket */
+    type: "websocket";
+    /** WebSocket connection instance or URL to connect to */
+    connection: WebSocket | string;
+    /** Optional: Transform event before sending (allows filtering, formatting, etc.) */
+    transform?: (event: AnalyticsEvent) => any;
+    /** Optional: Error handler for WebSocket errors */
+    onError?: (error: Event) => void;
+    /** Optional: Handler for when WebSocket connection opens */
+    onOpen?: (event: Event) => void;
+    /** Optional: Handler for when WebSocket connection closes */
+    onClose?: (event: CloseEvent) => void;
+    /** Optional: Reconnect automatically on disconnect (default: true) */
+    autoReconnect?: boolean;
+    /** Optional: Reconnect delay in milliseconds (default: 3000) */
+    reconnectDelay?: number;
+}
+/**
+ * Socket.IO handler for real-time analytics
+ */
+export interface SocketIOAnalyticsHandler {
+    /** Type identifier for Socket.IO */
+    type: "socket.io";
+    /** Socket.IO client instance or URL to connect to */
+    connection: typeof Socket | string;
+    /** Optional: Socket.IO connection options (used when connection is a URL) */
+    options?: Record<string, any>;
+    /** Optional: Event name to emit (default: "analytics") */
+    eventName?: string;
+    /** Optional: Transform event before sending (allows filtering, formatting, etc.) */
+    transform?: (event: AnalyticsEvent) => any;
+    /** Optional: Error handler */
+    onError?: (error: Error) => void;
+    /** Optional: Handler for when connection is established */
+    onConnect?: () => void;
+    /** Optional: Handler for when connection is lost */
+    onDisconnect?: (reason: string) => void;
+}
+/**
+ * Player state
+ */
+export interface PlayerState {
+    playing: boolean;
+    paused: boolean;
+    ended: boolean;
+    buffering: boolean;
+    currentTime: number;
+    duration: number;
+    volume: number;
+    muted: boolean;
+    playbackRate: number;
+    quality: string;
+    availableQualities: string[];
+    fullscreen: boolean;
+}
+/**
+ * Player events (compatible with Mux Player and HTML5 MediaElement events)
+ */
+export type PlayerEventType = "play" | "pause" | "playing" | "ended" | "timeupdate" | "volumechange" | "ratechange" | "seeked" | "seeking" | "waiting" | "loadstart" | "loadeddata" | "loadedmetadata" | "canplay" | "canplaythrough" | "durationchange" | "progress" | "error" | "abort" | "emptied" | "stalled" | "suspend" | "qualitychange" | "fullscreenchange" | "pictureinpictureenter" | "pictureinpictureexit" | "resize" | "sourcechange";
+export interface PlayerEvent {
+    type: PlayerEventType;
+    data?: any;
+    timestamp: number;
+}
+/**
+ * Analytics event types
+ */
+export interface AnalyticsEvent {
+    eventType: string;
+    timestamp: number;
+    sessionId: string;
+    videoId?: string;
+    userId?: string;
+    data: Record<string, any>;
+}
+export interface QualityLevel {
+    height: number;
+    width: number;
+    bitrate: number;
+    name: string;
+}
+export interface SubtitleTrack {
+    label: string;
+    src: string;
+    srclang: string;
+    default?: boolean;
+}

package/dist/ui-controller.d.ts

@@ -0,0 +1,49 @@
+import { WontumPlayer } from './player';
+
+/**
+ * UI Controller - Manages player controls and interface
+ */
+export declare class UIController {
+    private container;
+    private player;
+    private controlsContainer;
+    private progressContainer;
+    private progressBar;
+    private playButton;
+    private skipBackwardButton;
+    private skipForwardButton;
+    private volumeButton;
+    private volumeContainer;
+    private fullscreenButton;
+    private pipButton;
+    private settingsButton;
+    private volumeSlider;
+    private progressInput;
+    private hideControlsTimeout;
+    private stickyControls;
+    private isVolumeSliderActive;
+    constructor(container: HTMLElement, player: WontumPlayer);
+    private injectStyles;
+    private createProgressBar;
+    private createControls;
+    private setupEventListeners;
+    private setupPlayerEventListeners;
+    private updateSubtitleMenu;
+    private updateSpeedMenu;
+    private updateSettingsMenu;
+    private updateQualityMenu;
+    private showControls;
+    private hideControls;
+    private resetHideControlsTimeout;
+    private formatTime;
+    private getPlayIcon;
+    private getPauseIcon;
+    private getVolumeIcon;
+    private getMutedIcon;
+    private getFullscreenIcon;
+    private getPipIcon;
+    private getSkipBackwardIcon;
+    private getSkipForwardIcon;
+    private getSettingsIcon;
+    destroy(): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@obipascal/player",
-	"version": "1.0.15",
+	"version": "1.0.16",
 	"description": "A modern HLS video player SDK for educational platforms with S3 integration",
 	"main": "dist/wontum-player.cjs.js",
 	"module": "dist/wontum-player.esm.js",
@@ -8,10 +8,7 @@
 	"files": [
 		"dist/wontum-player.esm.js",
 		"dist/wontum-player.cjs.js",
-		"dist/index.d.ts",
-		"dist/src/**/*.d.ts",
-		"!dist/src/test-app.d.ts",
-		"!dist/examples"
+		"dist/*.d.ts"
 	],
 	"scripts": {
 		"dev": "vite",