@obipascal/player 1.0.7 → 1.0.9

package/README.md

@@ -34,6 +34,7 @@ A modern, feature-rich HLS video player SDK for educational platforms with Cloud
 - ⚛️ **React Support**: Component, Hook, and Context Provider patterns
 - 🔧 **TypeScript**: Full TypeScript support with comprehensive type definitions
 - 📊 **Analytics & QoE**: Built-in analytics tracking and Quality of Experience metrics
+- 🔌 **Real-time Analytics**: Native WebSocket and Socket.IO support for live analytics streaming
 - 🎯 **25 Events**: Complete event system compatible with Mux Player
 - 📱 **Responsive**: Mobile-friendly with touch support
 - 🎬 **Quality Selector**: Automatic quality switching with manual override
@@ -50,6 +51,12 @@ Or with yarn:
 yarn add @obipascal/player hls.js
 ```
 
+**Optional:** For Socket.IO real-time analytics support:
+
+```bash
+npm install socket.io-client
+```
+
 ## 🚀 Quick Start
 
 ### Vanilla JavaScript
@@ -691,7 +698,19 @@ Modern vertical volume slider with popup interface - hover over volume button to
 
 ## 📊 Analytics
 
-Track video engagement and quality metrics:
+Track video engagement and quality metrics with HTTP endpoints or real-time WebSocket/Socket.IO streaming:
+
+**Features:**
+
+- ✅ HTTP endpoint support for traditional analytics
+- ✅ Native WebSocket support for real-time streaming
+- ✅ Socket.IO support with full TypeScript types
+- ✅ Dual streaming (HTTP + Socket simultaneously)
+- ✅ Event transformation and filtering
+- ✅ Auto-reconnection with configurable delays
+- ✅ Quality of Experience (QoE) metrics included in every event
+
+### HTTP Analytics
 
 ```typescript
 const player = new WontumPlayer({
@@ -720,6 +739,206 @@ console.log(metrics)
 // }
 ```
 
+### WebSocket Real-Time Analytics
+
+Stream analytics events in real-time using native WebSocket for live dashboards and monitoring:
+
+```typescript
+const player = new WontumPlayer({
+	src: "https://example.com/video.m3u8",
+	container: "#player",
+	analytics: {
+		enabled: true,
+		userId: "user_456",
+		videoId: "video_789",
+		// Native WebSocket configuration
+		webSocket: {
+			type: "websocket", // Specify native WebSocket
+			connection: "wss://analytics.example.com/stream",
+			// Optional: Transform events before sending
+			transform: (event) => ({
+				type: event.eventType,
+				video_id: event.videoId,
+				user_id: event.userId,
+				timestamp: event.timestamp,
+				metrics: event.data,
+			}),
+			// Optional: Handle errors
+			onError: (error) => {
+				console.error("Analytics WebSocket error:", error)
+			},
+			// Optional: Connection opened
+			onOpen: (event) => {
+				console.log("Analytics WebSocket connected")
+			},
+			// Optional: Connection closed
+			onClose: (event) => {
+				console.log("Analytics WebSocket disconnected")
+			},
+			// Auto-reconnect on disconnect (default: true)
+			autoReconnect: true,
+			// Reconnect delay in milliseconds (default: 3000)
+			reconnectDelay: 3000,
+		},
+	},
+})
+```
+
+### Socket.IO Real-Time Analytics
+
+For Socket.IO-based real-time analytics (requires `socket.io-client` to be loaded):
+
+```typescript
+// Option 1: Let the SDK create the Socket.IO connection
+const player = new WontumPlayer({
+	src: "https://example.com/video.m3u8",
+	container: "#player",
+	analytics: {
+		enabled: true,
+		userId: "user_456",
+		videoId: "video_789",
+		webSocket: {
+			type: "socket.io",
+			connection: "https://analytics.example.com", // Socket.IO server URL
+			options: {
+				path: "/socket.io/",
+				transports: ["websocket", "polling"],
+				auth: {
+					token: "your-auth-token",
+				},
+				reconnection: true,
+				reconnectionDelay: 1000,
+			},
+			eventName: "video_analytics", // Event name to emit (default: "analytics")
+			transform: (event) => ({
+				event: event.eventType,
+				video: event.videoId,
+				user: event.userId,
+				data: event.data,
+			}),
+			onConnect: () => {
+				console.log("Socket.IO connected")
+			},
+			onDisconnect: (reason) => {
+				console.log("Socket.IO disconnected:", reason)
+			},
+			onError: (error) => {
+				console.error("Socket.IO error:", error)
+			},
+		},
+	},
+})
+```
+
+```typescript
+// Option 2: Use existing Socket.IO connection
+import { io } from "socket.io-client"
+
+const socket = io("https://analytics.example.com", {
+	auth: {
+		token: "your-auth-token",
+	},
+})
+
+const player = new WontumPlayer({
+	src: "https://example.com/video.m3u8",
+	container: "#player",
+	analytics: {
+		enabled: true,
+		userId: "user_456",
+		videoId: "video_789",
+		webSocket: {
+			type: "socket.io",
+			connection: socket, // Use existing Socket.IO instance
+			eventName: "analytics",
+		},
+	},
+})
+```
+
+### Using Existing WebSocket Connection
+
+```typescript
+// Create your own WebSocket connection
+const ws = new WebSocket("wss://analytics.example.com/stream")
+
+// Configure authentication or custom headers before connecting
+ws.addEventListener("open", () => {
+	// Send authentication message
+	ws.send(
+		JSON.stringify({
+			type: "auth",
+			token: "your-auth-token",
+		}),
+	)
+})
+
+const player = new WontumPlayer({
+	src: "https://example.com/video.m3u8",
+	container: "#player",
+	analytics: {
+		enabled: true,
+		userId: "user_456",
+		videoId: "video_789",
+		webSocket: {
+			type: "websocket",
+			connection: ws, // Use existing connection
+			transform: (event) => ({
+				// Custom format for your backend
+				action: "video_event",
+				payload: {
+					event: event.eventType,
+					data: event.data,
+				},
+			}),
+		},
+	},
+})
+```
+
+### Dual Analytics (HTTP + WebSocket/Socket.IO)
+
+Send analytics to both HTTP endpoint and real-time socket simultaneously:
+
+```typescript
+const player = new WontumPlayer({
+	src: "https://example.com/video.m3u8",
+	container: "#player",
+	analytics: {
+		enabled: true,
+		endpoint: "https://api.example.com/analytics", // HTTP fallback/storage
+		webSocket: {
+			type: "socket.io",
+			connection: "https://realtime.example.com", // Real-time monitoring
+			eventName: "video_analytics",
+		},
+		userId: "user_456",
+		videoId: "video_789",
+	},
+})
+```
+
+### Analytics Events Tracked
+
+The SDK automatically tracks these events:
+
+- **Session**: `session_start`, `session_end`
+- **Playback**: `play`, `pause`, `ended`, `playing`
+- **Buffering**: `buffering_start`, `buffering_end`, `waiting`, `stalled`
+- **Seeking**: `seeking`, `seeked`
+- **Quality**: `qualitychange`, `renditionchange`
+- **Errors**: `error`
+- **User Actions**: Volume changes, fullscreen, playback rate changes
+
+Each event includes Quality of Experience (QoE) metrics:
+
+- `sessionDuration` - Total session time
+- `totalPlayTime` - Actual video play time
+- `totalBufferTime` - Time spent buffering
+- `bufferingRatio` - Buffer time / play time ratio
+- `rebufferCount` - Number of rebuffer events
+- `seekCount` - Number of seek operations
+
 ## API Reference
 
 ### WontumPlayer
@@ -750,6 +969,39 @@ interface S3Config {
 	region?: string // S3 region
 	endpoint?: string // Custom S3 endpoint
 }
+
+interface AnalyticsConfig {
+	enabled?: boolean // Enable analytics tracking
+	endpoint?: string // HTTP endpoint for analytics events
+	webSocket?: WebSocketAnalyticsHandler | SocketIOAnalyticsHandler // Real-time streaming
+	sessionId?: string // Session identifier
+	userId?: string // User identifier
+	videoId?: string // Video identifier
+}
+
+// Native WebSocket Configuration
+interface WebSocketAnalyticsHandler {
+	type: "websocket"
+	connection: WebSocket | string // WebSocket instance or URL
+	transform?: (event: AnalyticsEvent) => any // Transform before sending
+	onError?: (error: Event) => void
+	onOpen?: (event: Event) => void
+	onClose?: (event: CloseEvent) => void
+	autoReconnect?: boolean // Default: true
+	reconnectDelay?: number // Default: 3000ms
+}
+
+// Socket.IO Configuration
+interface SocketIOAnalyticsHandler {
+	type: "socket.io"
+	connection: Socket | string // Socket.IO instance or URL
+	options?: Partial<ManagerOptions & SocketOptions> // Socket.IO options
+	eventName?: string // Event name to emit (default: "analytics")
+	transform?: (event: AnalyticsEvent) => any
+	onError?: (error: Error) => void
+	onConnect?: () => void
+	onDisconnect?: (reason: string) => void
+}
 ```
 
 #### Methods
@@ -1134,6 +1386,92 @@ pipButton.addEventListener("click", async () => {
 
 **Note:** Picture-in-Picture is supported in most modern browsers. The player includes a built-in PiP button in the controls.
 
+### File Information Utility
+
+The SDK includes a `WontumFileInfo` utility class to extract metadata from video files before uploading or processing them.
+
+```typescript
+import { WontumFileInfo } from "@obipascal/player"
+
+// Example: File input handling
+const fileInput = document.querySelector<HTMLInputElement>("#video-upload")
+
+fileInput.addEventListener("change", async (event) => {
+	const file = event.target.files?.[0]
+	if (!file) return
+
+	try {
+		// Create instance (validates it's a video file)
+		const videoInfo = new WontumFileInfo(file)
+
+		// Extract metadata
+		await videoInfo.extract()
+
+		// Access properties
+		console.log("Video Information:")
+		console.log("- Width:", videoInfo.width) // e.g., 1920
+		console.log("- Height:", videoInfo.height) // e.g., 1080
+		console.log("- Aspect Ratio:", videoInfo.aspectRatio) // e.g., "16:9"
+		console.log("- Quality:", videoInfo.quality) // e.g., "Full HD (1080p)"
+		console.log("- Duration (raw):", videoInfo.durationInSeconds, "seconds") // e.g., 125.5
+		console.log("- Formatted Duration:", videoInfo.durationFormatted) // e.g., "02:05"
+		console.log("- File Size (raw):", videoInfo.sizeInBytes, "bytes") // e.g., 52428800
+		console.log("- Formatted Size:", videoInfo.sizeFormatted) // e.g., "50 MB"
+		console.log("- MIME Type:", videoInfo.mimeType) // e.g., "video/mp4"
+		console.log("- File Name:", videoInfo.fileName) // e.g., "my-video.mp4"
+		console.log("- Extension:", videoInfo.fileExtension) // e.g., ".mp4"
+		console.log("- Bitrate:", videoInfo.bitrate, "kbps") // e.g., 3500
+
+		// Get all info as object
+		const allInfo = videoInfo.getInfo()
+		console.log(allInfo)
+
+		// Clean up when done
+		videoInfo.destroy()
+	} catch (error) {
+		console.error("Error extracting video info:", error.message)
+		// Throws error if file is not a video
+	}
+})
+```
+
+#### WontumFileInfo API
+
+**Constructor:**
+
+```typescript
+new WontumFileInfo(file: File)
+```
+
+Throws an error if the file is not a valid video file.
+
+**Methods:**
+
+- `extract(): Promise<VideoFileInfo>` - Extracts metadata from the video file
+- `getInfo(): VideoFileInfo | null` - Returns the extracted information object
+- `destroy(): void` - Cleans up resources
+
+**Properties (available after calling `extract()`):**
+
+- `width: number` - Video width in pixels
+- `height: number` - Video height in pixels
+- `aspectRatio: string` - Aspect ratio (e.g., "16:9", "4:3", "21:9")
+- `quality: string` - Quality description (e.g., "4K (2160p)", "Full HD (1080p)")
+- `size: number` - File size in bytes (raw value for computation)
+- `sizeInBytes: number` - Alias for size (raw value for computation)
+- `sizeFormatted: string` - Human-readable size (e.g., "50 MB")
+- `duration: number` - Duration in seconds (raw value for computation)
+- `durationInSeconds: number` - Alias for duration (raw value for computation)
+- `durationFormatted: string` - Formatted duration (e.g., "01:23:45")
+- `mimeType: string` - MIME type (e.g., "video/mp4")
+- `fileName: string` - Original file name
+- `fileExtension: string` - File extension (e.g., ".mp4")
+- `bitrate: number | undefined` - Estimated bitrate in kbps
+
+**Supported Video Formats:**
+
+`.mp4`, `.webm`, `.ogg`, `.mov`, `.avi`, `.mkv`, `.flv`, `.wmv`, `.m4v`, `.3gp`, `.ts`, `.m3u8`
+
 ## 📋 Complete API Reference
 
 For detailed API documentation including all methods, events, types, and configuration options, see **[API-REFERENCE.md](./API-REFERENCE.md)**.

package/dist/src/analytics.d.ts

@@ -14,6 +14,10 @@ export declare class Analytics {
     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;
@@ -22,6 +26,10 @@ export declare class Analytics {
     private getConnectionInfo;
     private sendEvent;
     private generateSessionId;
+    private initializeSocketIO;
+    private sendToSocketIO;
+    private initializeWebSocket;
+    private sendToWebSocket;
     getEvents(): AnalyticsEvent[];
     getMetrics(): Record<string, any>;
     destroy(): void;

package/dist/src/file-info.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Video file information extractor
+ * Extracts metadata from video files (width, height, duration, size, etc.)
+ */
+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;
+    videoCodec?: string;
+    audioCodec?: string;
+}
+export declare class WontumFileInfo {
+    private file;
+    private videoElement;
+    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;
+    /**
+     * 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 quality(): string;
+    /**
+     * Get all information as object
+     */
+    getInfo(): VideoFileInfo | null;
+    /**
+     * Clean up resources
+     */
+    destroy(): void;
+}

package/dist/src/index.d.ts

@@ -2,6 +2,8 @@ export { WontumPlayer } from './player';
 export { Analytics } from './analytics';
 export { S3Handler } from './s3-handler';
 export { UIController } from './ui-controller';
+export { WontumFileInfo } from './file-info';
 export { WontumPlayerReact, useWontumPlayer, WontumPlayerProvider, useWontumPlayerContext } from './react';
-export type { WontumPlayerConfig, PlayerTheme, S3Config, AnalyticsConfig, PlayerState, PlayerEvent, PlayerEventType, AnalyticsEvent, QualityLevel } from './types';
+export type { WontumPlayerConfig, PlayerTheme, S3Config, AnalyticsConfig, WebSocketAnalyticsHandler, SocketIOAnalyticsHandler, PlayerState, PlayerEvent, PlayerEventType, AnalyticsEvent, QualityLevel, } from './types';
+export type { VideoFileInfo } from './file-info';
 export type { WontumPlayerReactProps } from './react';

package/dist/src/types.d.ts

@@ -1,3 +1,5 @@
+import { Socket } from 'socket.io-client';
+
 /**
  * Player configuration options
  */
@@ -55,8 +57,10 @@ export interface S3Config {
 export interface AnalyticsConfig {
     /** Enable analytics */
     enabled?: boolean;
-    /** Custom analytics endpoint */
+    /** 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 */
@@ -64,6 +68,48 @@ export interface AnalyticsConfig {
     /** 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
  */