video-buffer-tracker/dist/index.d.ts

Professional video buffering analytics & tracking library for monitoring video streaming performance, buffering progress, and user experience in real-time. Perfect for video platforms, e-learning apps, and media analytics.

/**
 * Core types and interfaces for VideoBufferTracker
 */
interface VideoBufferTrackerConfig {
    /** Legacy: URL to send analytics data */
    trafficEventUrl?: string;
    /** Callback function for buffer data */
    onBufferData?: (data: BufferData) => void | Promise<void>;
    /** Enable debug logging */
    debug?: boolean;
    /** Minimum time between progress updates (milliseconds) */
    progressThrottleMs?: number;
    /** Time remaining to trigger final probe (seconds) */
    finalProbeThreshold?: number;
    /** Epsilon for range merging (seconds) */
    rangeMergeEpsilon?: number;
}
interface BufferedRange {
    start: number;
    end: number;
}
interface BufferData {
    /** Estimated bytes buffered */
    file_size: number;
    /** Video URL */
    video_url?: string;
    /** Timestamp when data was collected */
    timestamp?: number;
}
interface TrackingStats {
    /** Total video file size in bytes */
    totalSize: number;
    /** Estimated downloaded bytes */
    estimatedDownloadedBytes: number;
    /** Whether full download has been submitted */
    hasSubmittedFullDownload: boolean;
    /** Current buffered ranges */
    bufferedRanges: BufferedRange[];
    /** Video duration in seconds */
    duration: number;
}
interface VideoInfo {
    /** Video URL */
    url: string;
    /** Video duration in seconds */
    duration: number;
    /** Total file size in bytes */
    totalSize: number;
    /** Video element */
    element: HTMLVideoElement;
}
type EventHandler = () => void | Promise<void>;
interface EventHandlers {
    onProgress: EventHandler;
    onTimeUpdate: EventHandler;
    onFinalize: EventHandler;
}
interface Logger {
    debug: (message: string, ...args: any[]) => void;
    info: (message: string, ...args: any[]) => void;
    warn: (message: string, ...args: any[]) => void;
    error: (message: string, ...args: any[]) => void;
}

/**
 * VideoBufferTracker - Comprehensive video buffering tracking utility
 *
 * This class provides real-time video buffering progress tracking and analytics.
 * It monitors video buffering progress, calculates downloaded bytes, and provides
 * flexible analytics integration.
 *
 * @example
 * ```typescript
 * const tracker = new VideoBufferTracker({
 *   onBufferData: (data) => {
 *     console.log('Buffer data:', data);
 *   }
 * });
 *
 * await tracker.setupVideoTracking(videoElement, videoUrl);
 * ```
 */
declare class VideoBufferTracker {
    private config;
    private logger;
    private videoSizeService;
    private bufferService;
    private analyticsService;
    private eventManager?;
    private videoInfo?;
    private estimatedDownloadedBytes;
    private submittedBytesBaseline;
    private hasSubmittedFullDownload;
    private lastProbedEnd;
    private isTracking;
    constructor(config?: VideoBufferTrackerConfig);
    /**
     * Setup video tracking for a video element
     *
     * @param video - The HTML video element to track
     * @param videoUrl - The URL of the video
     * @throws {Error} If video element or URL is invalid
     */
    setupVideoTracking(video: HTMLVideoElement, videoUrl: string): Promise<void>;
    /**
     * Get current buffer data
     */
    getBufferData(): BufferData;
    /**
     * Get current tracking statistics
     */
    getTrackingStats(): TrackingStats;
    /**
     * Stop tracking and cleanup resources
     */
    destroy(): void;
    /**
     * Check if tracking is active
     */
    isTrackingActive(): boolean;
    /**
     * Setup event handlers and attach listeners
     */
    private setupEventHandlers;
    /**
     * Create progress event handler
     */
    private createProgressHandler;
    /**
     * Create time update event handler
     */
    private createTimeUpdateHandler;
    /**
     * Create finalize event handler
     */
    private createFinalizeHandler;
    /**
     * Update progress estimate based on buffered ranges
     */
    private updateProgressEstimate;
    /**
     * Handle full download completion
     */
    private handleFullDownload;
    /**
     * Perform final probe to calculate total downloaded bytes
     */
    private performFinalProbe;
    /**
     * Update download metrics and trigger analytics
     */
    private updateDownloadMetrics;
    /**
     * Handle buffer data submission
     */
    private handleBufferData;
}

/**
 * Service for detecting video file size
 */
declare class VideoSizeService {
    private logger;
    private cache;
    constructor(logger: Logger);
    /**
     * Get video file size via HEAD request
     */
    getVideoSize(videoUrl: string): Promise<number>;
    /**
     * Clear cache
     */
    clearCache(): void;
    /**
     * Remove specific URL from cache
     */
    removeFromCache(videoUrl: string): void;
}

/**
 * Service for calculating buffer-related metrics
 */
declare class BufferCalculationService {
    private logger;
    constructor(logger: Logger);
    /**
     * Get buffered ranges from video element
     */
    getBufferedRanges(video: HTMLVideoElement): BufferedRange[];
    /**
     * Merge overlapping or adjacent ranges
     */
    mergeRanges(ranges: BufferedRange[], epsilon: number): BufferedRange[];
    /**
     * Check if video is fully downloaded
     */
    isFullyDownloaded(ranges: BufferedRange[], duration: number, epsilon: number): boolean;
    /**
     * Convert time range to byte range
     */
    timeToByteRange(startTime: number, endTime: number, duration: number, totalSize: number): {
        start: number;
        end: number;
    } | null;
    /**
     * Calculate total bytes from buffered ranges
     */
    calculateTotalBytes(ranges: BufferedRange[], duration: number, totalSize: number): number;
}

/**
 * Service for handling analytics data submission
 */
declare class AnalyticsService {
    private logger;
    private trafficEventUrl?;
    constructor(logger: Logger, trafficEventUrl?: string);
    /**
     * Send buffer data to analytics endpoint
     */
    sendBufferData(bufferData: BufferData): Promise<boolean>;
    /**
     * Call user-provided callback with buffer data
     */
    callUserCallback(callback: (data: BufferData) => void | Promise<void>, bufferData: BufferData): Promise<void>;
}

/**
 * Validation utilities for VideoBufferTracker
 */
declare class ValidationUtils {
    /**
     * Validate video element
     */
    static validateVideoElement(video: HTMLVideoElement): void;
    /**
     * Validate video URL
     */
    static validateVideoUrl(url: string): void;
    /**
     * Validate configuration
     */
    static validateConfig(config: VideoBufferTrackerConfig): void;
    /**
     * Validate video info
     */
    static validateVideoInfo(videoInfo: VideoInfo): void;
}

/**
 * Default logger implementation
 */
declare class DefaultLogger implements Logger {
    private isDebugEnabled;
    constructor(debug?: boolean);
    debug(message: string, ...args: any[]): void;
    info(message: string, ...args: any[]): void;
    warn(message: string, ...args: any[]): void;
    error(message: string, ...args: any[]): void;
}
/**
 * Silent logger for production use
 */
declare class SilentLogger implements Logger {
    debug(): void;
    info(): void;
    warn(): void;
    error(): void;
}

/**
 * Manages event listeners for video tracking
 */
declare class EventManager {
    private logger;
    private eventHandlers;
    private video;
    private isAttached;
    constructor(logger: Logger, video: HTMLVideoElement, handlers: EventHandlers);
    /**
     * Attach all event listeners
     */
    attach(): void;
    /**
     * Detach all event listeners
     */
    detach(): void;
    /**
     * Handle visibility change events
     */
    private handleVisibilityChange;
    /**
     * Check if listeners are attached
     */
    areListenersAttached(): boolean;
}

export { AnalyticsService, BufferCalculationService, BufferData, BufferedRange, DefaultLogger, EventHandler, EventHandlers, EventManager, Logger, SilentLogger, TrackingStats, ValidationUtils, VideoBufferTracker, VideoBufferTrackerConfig, VideoInfo, VideoSizeService };