@obipascal/player 1.0.8 → 1.0.10

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
@@ -1169,11 +1421,20 @@ fileInput.addEventListener("change", async (event) => {
 		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
+		console.log("- Frame Rate:", videoInfo.frameRate, "fps") // e.g., 30 or 60
+		console.log("- Has Audio:", videoInfo.hasAudio) // e.g., true
+		console.log("- Audio Channels:", videoInfo.audioChannels) // e.g., 2 (stereo)
 
 		// Get all info as object
 		const allInfo = videoInfo.getInfo()
 		console.log(allInfo)
 
+		// Validate against platform requirements
+		const isValid = validateVideo(videoInfo)
+		if (!isValid.valid) {
+			console.error("Validation errors:", isValid.errors)
+		}
+
 		// Clean up when done
 		videoInfo.destroy()
 	} catch (error) {
@@ -1181,6 +1442,56 @@ fileInput.addEventListener("change", async (event) => {
 		// Throws error if file is not a video
 	}
 })
+
+// Example validation function for educational platform
+function validateVideo(info: VideoFileInfo) {
+	const errors: string[] = []
+
+	// Aspect Ratio: 16:9 required
+	if (info.aspectRatio !== "16:9") {
+		errors.push(`Aspect ratio must be 16:9, got ${info.aspectRatio}`)
+	}
+
+	// Resolution: Minimum 1280×720
+	if (info.height < 720 || info.width < 1280) {
+		errors.push(`Minimum resolution is 1280×720, got ${info.width}×${info.height}`)
+	}
+
+	// File Format: .MP4 or .MOV
+	if (![".mp4", ".mov"].includes(info.fileExtension.toLowerCase())) {
+		errors.push(`File format must be MP4 or MOV, got ${info.fileExtension}`)
+	}
+
+	// Bitrate: 5-10 Mbps
+	if (info.bitrate && (info.bitrate < 5000 || info.bitrate > 10000)) {
+		errors.push(`Bitrate should be 5-10 Mbps, got ${info.bitrate} kbps`)
+	}
+
+	// Audio: Must be stereo (2 channels)
+	if (!info.hasAudio) {
+		errors.push("Video must have audio track")
+	} else if (info.audioChannels && info.audioChannels !== 2) {
+		errors.push(`Audio must be stereo (2 channels), got ${info.audioChannels}`)
+	}
+
+	// File Size: ≤4.0 GB
+	const maxSize = 4 * 1024 * 1024 * 1024 // 4GB in bytes
+	if (info.sizeInBytes > maxSize) {
+		errors.push(`File size must be ≤4GB, got ${info.sizeFormatted}`)
+	}
+
+	// Duration: 2 minutes to 2 hours
+	if (info.durationInSeconds < 120 || info.durationInSeconds > 7200) {
+		errors.push(`Duration must be 2min-2hrs, got ${info.durationFormatted}`)
+	}
+
+	// Frame Rate: 30 or 60 fps
+	if (info.frameRate && ![30, 60].includes(info.frameRate)) {
+		errors.push(`Frame rate should be 30 or 60 fps, got ${info.frameRate}`)
+	}
+
+	return { valid: errors.length === 0, errors }
+}
 ```
 
 #### WontumFileInfo API
@@ -1215,6 +1526,13 @@ Throws an error if the file is not a valid video file.
 - `fileName: string` - Original file name
 - `fileExtension: string` - File extension (e.g., ".mp4")
 - `bitrate: number | undefined` - Estimated bitrate in kbps
+- `frameRate: number | undefined` - Frame rate in fps (30, 60, etc.)
+- `hasAudio: boolean` - Whether video has an audio track
+- `audioChannels: number | undefined` - Number of audio channels (1=mono, 2=stereo)
+
+**Validation Use Case:**
+
+Perfect for validating videos against platform requirements (aspect ratio, resolution, format, bitrate, audio channels, file size, duration, frame rate).
 
 **Supported Video Formats:**
 

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

@@ -2,6 +2,15 @@
  * 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;
@@ -17,12 +26,15 @@ export interface VideoFileInfo {
     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);
     /**
@@ -37,6 +49,14 @@ export declare class WontumFileInfo {
      * 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
      */
@@ -66,6 +86,9 @@ export declare class WontumFileInfo {
     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

package/dist/src/index.d.ts

@@ -4,6 +4,6 @@ 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
  */