videojs-rewind 0.1.0

package/dist/plugin.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Core plugin class for videojs-rewind.
+ *
+ * Extends video.js's advanced plugin pattern (class-based).
+ * Manages lifecycle, state, custom DOM injection, and coordinates
+ * all sub-components: seek bar, rewind-to-VOD, quality, storyboard,
+ * hover tooltips, toast notifications, and keyboard seek.
+ */
+import type { RewindPluginOptions, RewindState, PluginDomElements } from './types.js';
+declare const RewindPlugin_base: new (...args: any[]) => any;
+/**
+ * @class RewindPlugin
+ * @extends Plugin
+ */
+declare class RewindPlugin extends RewindPlugin_base {
+    options: RewindPluginOptions;
+    state: RewindState;
+    dom: PluginDomElements;
+    private _tickInterval;
+    private _cdns;
+    private _storyboardInfo;
+    private _spriteImages;
+    private _qualitySuppressionTimer;
+    private _toastTimer;
+    private _keydownHandler;
+    private _wasPlaying;
+    /**
+     * @param player - The video.js player instance
+     * @param options - Partial plugin options (merged with defaults via Zod)
+     */
+    constructor(player: any, options: Partial<RewindPluginOptions>);
+    /** Called once the player is ready. Sets up DOM, listeners, and VHS hooks. */
+    private _onPlayerReady;
+    /**
+     * Clean up all resources. Called when the plugin is disposed
+     * or the player is destroyed.
+     */
+    dispose(): void;
+    /** Build and inject custom DOM elements into the player's control bar. */
+    private _buildDOM;
+    /** Remove all injected DOM elements. */
+    private _removeDOM;
+    /**
+     * Create a DOM element with attributes and optional text content.
+     */
+    private _createEl;
+    private _responseHook;
+    private _wireVhsHooks;
+    private _unwireVhsHooks;
+    /**
+     * Get the CDN base URL for a given playlist URI.
+     */
+    private _getCdnBaseUrl;
+    private _wireKeyboardSeek;
+    private _onLoadedMetadata;
+    private _onLoadStart;
+    private _onDurationChange;
+    private _onSeeked;
+    private _onQualityLevelsChange;
+    private _onSeekMouseDown;
+    private _onSeekMouseMove;
+    private _onSeekMouseUp;
+    private _onGoLive;
+    private _showHoverTime;
+    private _hideHoverTime;
+    /**
+     * Show a toast notification message.
+     * @param message - The message to display
+     * @param duration - Duration in ms (default: 3000)
+     */
+    private _showToast;
+    private _startTick;
+    private _updateDisplay;
+    /**
+     * Update the seek slider fill and handle position.
+     */
+    private _updateSlider;
+    private _checkRewindToVod;
+    private _rewindToVod;
+    /**
+     * Swap back to the live source.
+     */
+    private _goLive;
+    private _applyQualityConstraint;
+    /**
+     * Start the ABR suppression window.
+     * During this window, quality constraint is not enforced to let ABR ramp up.
+     */
+    private _startQualitySuppression;
+    /**
+     * Load quality preference from localStorage.
+     */
+    private _loadQualityPreference;
+    /**
+     * Save quality preference to localStorage.
+     */
+    private _saveQualityPreference;
+    /**
+     * Set the preferred quality level.
+     * @param quality - Quality height (e.g., 1080) or 'auto'
+     */
+    setQuality(quality: number | 'auto'): void;
+    /**
+     * Get the current quality level.
+     */
+    getQuality(): number | 'auto';
+    /**
+     * Fetch storyboard metadata for a VOD and preload sprite images.
+     */
+    private _fetchStoryboardInfo;
+    /**
+     * Preload all sprite sheet images.
+     */
+    private _preloadSpriteImages;
+    /**
+     * Show storyboard canvas at the initial seek position.
+     */
+    private _showStoryboardAt;
+    /**
+     * Draw a storyboard frame on the canvas for the given seek time.
+     */
+    private _drawStoryboardFrame;
+    /**
+     * Hide the storyboard canvas.
+     */
+    private _hideStoryboard;
+    /**
+     * Format seconds into HH:MM:SS or MM:SS.
+     */
+    _formatTime(seconds: number): string;
+    /**
+     * Extract channel name from the current source URL.
+     */
+    private _getChannelName;
+}
+export default RewindPlugin;

package/dist/quality.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Quality Constraint for videojs-rewind.
+ *
+ * Enforces a user-preferred quality level across source swaps (live ↔ VOD).
+ * Integrates with videojs-contrib-quality-levels and VHS fastQualityChange_.
+ */
+/**
+ * Constrain quality levels to a preferred height.
+ * Disables all levels that don't match the preferred height.
+ * @param player - The video.js player
+ * @param preferredHeight - Target height (e.g., 1080)
+ */
+export declare function constrainQuality(player: any, preferredHeight: number): void;
+/**
+ * Suppression window duration in ms after loadstart.
+ * During this window, the quality constraint is not enforced
+ * to avoid feedback loops with the ABR ramp-up.
+ */
+export declare const SUPPRESSION_WINDOW_MS = 6000;

package/dist/rewind-to-vod.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Rewind-to-VOD Flow for videojs-rewind.
+ *
+ * Detects when the user seeks behind the DVR window and orchestrates
+ * the source swap from live HLS to VOD HLS.
+ *
+ * State machine: idle → resolving → swapping → seeking → playing
+ */
+/**
+ * Check if a seek time falls behind the DVR window.
+ * @param player - The video.js player
+ * @param seekTime - Desired seek time in seconds
+ * @param threshold - DVR window threshold in seconds
+ * @returns True if seek time is behind DVR window
+ */
+export declare function detectBehindDvr(player: any, seekTime: number, threshold: number): boolean;
+/**
+ * State machine states for rewind-to-VOD flow.
+ */
+export declare const RewindState: {
+    readonly IDLE: 'idle';
+    readonly RESOLVING: 'resolving';
+    readonly SWAPPING: 'swapping';
+    readonly SEEKING: 'seeking';
+    readonly PLAYING: 'playing';
+    readonly ERROR: 'error';
+};
+export type RewindStateValue = (typeof RewindState)[keyof typeof RewindState];

package/dist/schema.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Zod schemas for videojs-rewind options validation.
+ *
+ * Uses Zod 4 pattern for schema definitions.
+ * Provides runtime validation of plugin options with descriptive error messages.
+ */
+import { z } from 'zod';
+/** Full plugin options schema */
+export declare const RewindPluginOptionsSchema: z.ZodObject<{
+    customSeekBar: z.ZodDefault<z.ZodBoolean>;
+    showTotalTime: z.ZodDefault<z.ZodBoolean>;
+    enableRewindToVod: z.ZodDefault<z.ZodBoolean>;
+    resolveVodUrl: z.ZodDefault<z.ZodNullable<z.ZodCustom<(channelName: string, seekTime: number) => Promise<{
+        vodId: string;
+        hlsUrl: string;
+    } | null>, (channelName: string, seekTime: number) => Promise<{
+        vodId: string;
+        hlsUrl: string;
+    } | null>>>>;
+    resolveLiveUrl: z.ZodDefault<z.ZodNullable<z.ZodCustom<(channelName: string) => Promise<string | null>, (channelName: string) => Promise<string | null>>>>;
+    preferredQuality: z.ZodDefault<z.ZodUnion<readonly [z.ZodNumber, z.ZodLiteral<"auto">]>>;
+    persistQuality: z.ZodDefault<z.ZodBoolean>;
+    storageKeyPrefix: z.ZodDefault<z.ZodString>;
+    storyboard: z.ZodOptional<z.ZodObject<{
+        fetchInfo: z.ZodOptional<z.ZodCustom<(vodId: string, cdnBaseUrl: string) => Promise<Record<string, unknown> | null>, (vodId: string, cdnBaseUrl: string) => Promise<Record<string, unknown> | null>>>;
+        previewWidth: z.ZodDefault<z.ZodNumber>;
+        previewHeight: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    dvrWindowThreshold: z.ZodDefault<z.ZodNumber>;
+    showToasts: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+/** Type for the resolved options after schema parsing */
+export type ResolvedRewindPluginOptions = z.output<typeof RewindPluginOptionsSchema>;

package/dist/seek-bar.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Seek Bar Component for videojs-rewind.
+ *
+ * Pure functions for seek bar calculations:
+ *  - calculateSeekTime: map pixel offset to seek time
+ *  - sliderFillPercent: compute fill percentage for display
+ */
+/**
+ * Calculate seek time from mouse/touch position relative to seek bar.
+ * @param offsetX - Mouse X offset from seek bar left edge
+ * @param outerWidth - Total width of seek bar
+ * @param maxTime - Current max time (live edge or VOD duration)
+ * @returns Seek time in seconds, clamped to [0, maxTime]
+ */
+export declare function calculateSeekTime(offsetX: number, outerWidth: number, maxTime: number): number;
+/**
+ * Calculate slider fill percentage.
+ * @param currentTime - Current playback time
+ * @param maxTime - Max time
+ * @returns Percentage (0-100)
+ */
+export declare function sliderFillPercent(currentTime: number, maxTime: number): number;

package/dist/storyboard.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Storyboard / Seek Thumbnail for videojs-rewind.
+ *
+ * Pure functions for sprite-sheet-based seek thumbnail previews:
+ *  - calculateFrameIndex: map seek time to frame index
+ *  - calculateCellPosition: derive sprite sheet cell coordinates
+ */
+/** Sprite sheet cell position */
+export interface CellPosition {
+    sx: number;
+    sy: number;
+    sWidth: number;
+    sHeight: number;
+}
+/**
+ * Calculate the frame index for a given seek time.
+ * @param seekTime - Seek time in seconds
+ * @param interval - Seconds per frame
+ * @returns Frame index
+ */
+export declare function calculateFrameIndex(seekTime: number, interval: number): number;
+/**
+ * Calculate the sprite sheet cell position for a given frame index.
+ * @param frameIndex - Frame index
+ * @param cols - Number of columns in sprite sheet
+ * @param frameWidth - Width of each frame in pixels
+ * @param frameHeight - Height of each frame in pixels
+ * @returns Cell position and dimensions for drawImage()
+ */
+export declare function calculateCellPosition(frameIndex: number, cols: number, frameWidth: number, frameHeight: number): CellPosition;

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Type definitions for videojs-rewind.
+ */
+import type { z } from 'zod';
+import type { RewindPluginOptionsSchema } from './schema.js';
+/** Inferred plugin options type from the Zod schema */
+export type RewindPluginOptions = z.infer<typeof RewindPluginOptionsSchema>;
+/** Storyboard sprite sheet metadata */
+export interface StoryboardInfo {
+    width: number;
+    height: number;
+    cols: number;
+    rows: number;
+    interval: number;
+    count: number;
+    images: string[];
+}
+/** Resolved VOD result from the resolveVodUrl callback */
+export interface VodResult {
+    vodId: string;
+    hlsUrl: string;
+}
+/** DVR window range */
+export interface DvrWindow {
+    start: number;
+    end: number;
+}
+/** Internal plugin state */
+export interface RewindState {
+    videoMode: 'live' | 'vod';
+    maxTime: number;
+    vodMaxTime: number;
+    isTransitioning: boolean;
+    currentQuality: number | 'auto';
+    atLiveEdge: boolean;
+    dvrWindow: DvrWindow;
+}
+/** Quality level from videojs-contrib-quality-levels */
+export interface QualityLevel {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+    bitrate: number;
+    enabled: boolean;
+}
+/** DOM element references managed by the plugin */
+export interface PluginDomElements {
+    seekOuter: HTMLDivElement | null;
+    seekSlider: HTMLDivElement | null;
+    seekHandle: HTMLDivElement | null;
+    buffered: HTMLDivElement | null;
+    timer: HTMLSpanElement | null;
+    timerDivider: HTMLSpanElement | null;
+    timerEnd: HTMLSpanElement | null;
+    liveButton: HTMLButtonElement | null;
+    storyboardCanvas: HTMLCanvasElement | null;
+    hoverTime: HTMLDivElement | null;
+    toastContainer: HTMLDivElement | null;
+}

package/dist/videojs-rewind.css

@@ -0,0 +1,221 @@
+/* ==========================================================================
+   videojs-rewind — Custom DVR Seek Bar, Timer, and Storyboard Styles
+   All styles scoped under .vjs-rewind-active to avoid conflicts
+   with other plugins and skins.
+   ========================================================================== */
+
+/* ---------------------------------------------------------------------------
+   Timer Display
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-timer {
+  display: inline-block;
+  font-family: monospace;
+  font-size: 1.1em;
+  color: #fff;
+  padding: 0 0.5em;
+  line-height: 3em;
+  vertical-align: middle;
+  cursor: default;
+  user-select: none;
+}
+
+.vjs-rewind-active .vjs-rewind-timer-divider {
+  display: inline-block;
+  font-family: monospace;
+  font-size: 1.1em;
+  color: #aaa;
+  padding: 0 0.2em;
+  line-height: 3em;
+  vertical-align: middle;
+  user-select: none;
+}
+
+.vjs-rewind-active .vjs-rewind-timer-end {
+  display: inline-block;
+  font-family: monospace;
+  font-size: 1.1em;
+  color: #aaa;
+  padding: 0 0.5em 0 0;
+  line-height: 3em;
+  vertical-align: middle;
+  cursor: default;
+  user-select: none;
+}
+
+/* ---------------------------------------------------------------------------
+   Seek Bar
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-seek-outer {
+  position: relative;
+  flex: 1;
+  height: 0.5em;
+  margin: 0 0.5em;
+  background: #333;
+  border-radius: 0.25em;
+  cursor: pointer;
+  align-self: center;
+  z-index: 1;
+}
+
+.vjs-rewind-active .vjs-rewind-slider {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  background: #f60;
+  border-radius: 0.25em;
+  transition: width 0.1s linear;
+  pointer-events: none;
+}
+
+.vjs-rewind-active .vjs-rewind-handle {
+  position: absolute;
+  top: -0.3em;
+  width: 1em;
+  height: 1em;
+  background: #f60;
+  border-radius: 50%;
+  transform: translateX(-50%);
+  transition: left 0.1s linear;
+  pointer-events: none;
+  z-index: 2;
+}
+
+.vjs-rewind-active .vjs-rewind-buffered {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  background: rgba(255, 255, 255, 0.2);
+  border-radius: 0.25em;
+  pointer-events: none;
+}
+
+/* ---------------------------------------------------------------------------
+   Live Button
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-live-button {
+  display: none;
+  font-family: monospace;
+  font-size: 0.9em;
+  color: #fff;
+  background: #f60;
+  border: none;
+  border-radius: 0.25em;
+  padding: 0.25em 0.75em;
+  cursor: pointer;
+  line-height: 2em;
+  vertical-align: middle;
+  margin: 0 0.5em;
+}
+
+.vjs-rewind-active .vjs-rewind-live-button:hover {
+  background: #e55;
+}
+
+/* ---------------------------------------------------------------------------
+   Storyboard Canvas
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-storyboard {
+  position: absolute;
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  margin-bottom: 0.5em;
+  border: 2px solid #fff;
+  border-radius: 0.25em;
+  box-shadow: 0 0 0.5em rgba(0, 0, 0, 0.5);
+  background: #000;
+  pointer-events: none;
+  z-index: 10;
+}
+
+/* ---------------------------------------------------------------------------
+   State: Scrubbing (hide native controls)
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active.vjs-scrubbing .vjs-progress-control {
+  display: none;
+}
+
+/* ---------------------------------------------------------------------------
+   Responsive: Hide timer on small players
+   --------------------------------------------------------------------------- */
+
+@media (max-width: 600px) {
+  .vjs-rewind-active .vjs-rewind-timer-divider,
+  .vjs-rewind-active .vjs-rewind-timer-end {
+    display: none;
+  }
+}
+
+/* ---------------------------------------------------------------------------
+   Transitioning State
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active.vjs-rewind-transitioning .vjs-rewind-seek-outer {
+  opacity: 0.5;
+  pointer-events: none;
+}
+
+/* ---------------------------------------------------------------------------
+   Hover Time Tooltip
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-hover-time {
+  position: absolute;
+  bottom: 100%;
+  font-family: monospace;
+  font-size: 0.85em;
+  color: #fff;
+  background: rgba(0, 0, 0, 0.75);
+  padding: 0.2em 0.5em;
+  border-radius: 0.25em;
+  pointer-events: none;
+  z-index: 10;
+  white-space: nowrap;
+  margin-bottom: 0.3em;
+}
+
+/* ---------------------------------------------------------------------------
+   Toast Notifications
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active .vjs-rewind-toast-container {
+  position: absolute;
+  bottom: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  margin-bottom: 0.5em;
+  pointer-events: none;
+  z-index: 15;
+}
+
+.vjs-rewind-active .vjs-rewind-toast {
+  font-family: monospace;
+  font-size: 0.85em;
+  color: #fff;
+  background: rgba(0, 0, 0, 0.8);
+  padding: 0.3em 0.75em;
+  border-radius: 0.25em;
+  white-space: nowrap;
+  text-align: center;
+  animation: vjs-rewind-toast-fadein 0.2s ease-in;
+}
+
+@keyframes vjs-rewind-toast-fadein {
+  from { opacity: 0; transform: translateY(0.3em); }
+  to   { opacity: 1; transform: translateY(0); }
+}
+
+/* ---------------------------------------------------------------------------
+   Transitioning State
+   --------------------------------------------------------------------------- */
+
+.vjs-rewind-active.vjs-rewind-transitioning {
+  cursor: wait;
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "videojs-rewind",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Full-stream seek bar, rewind-to-VOD, and quality enforcement for live DVR playback in video.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "style": "dist/videojs-rewind.css",
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "bash scripts/build.sh",
+    "lint": "echo 'lint placeholder'",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ashleyjackson/videojs-rewind.git"
+  },
+  "keywords": [
+    "videojs",
+    "plugin",
+    "dvr",
+    "live",
+    "rewind",
+    "vod",
+    "hls",
+    "seek-bar"
+  ],
+  "author": "Ashley Jackson",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/ashleyjackson/videojs-rewind/issues"
+  },
+  "homepage": "https://github.com/ashleyjackson/videojs-rewind#readme",
+  "peerDependencies": {
+    "typescript": "^7.0.0",
+    "video.js": "^8.23.9",
+    "@videojs/http-streaming": "^3.17.5",
+    "videojs-contrib-quality-levels": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.14"
+  },
+  "dependencies": {
+    "global": "^4.4.0",
+    "zod": "^4.4.3"
+  }
+}