videojs-rewind 0.1.0 → 0.2.3

package/README.md

@@ -1,10 +1,10 @@
 # videojs-rewind
 
-A Live DVR Rewind Plugin for video.js — full-stream seek bar, rewind-to-VOD, quality enforcement, and storyboard thumbnails for live HLS playback.
+A Live DVR Rewind Plugin for video.js — full-stream seek bar, rewind-to-VOD, quality enforcement, and storyboard thumbnails for **both live and VOD** HLS playback.
 
 ## Features
 
-- **Custom Seek Bar** — Full-width seek bar that replaces the native `ProgressControl`. Shows stream position relative to the full stream duration (not just the DVR window).
+- **Custom Seek Bar** — Full-width seek bar that replaces the native `ProgressControl`. Shows stream position relative to the full stream duration (not just the DVR window). Works on both live and finite VOD sources.
 - **Live/VOD Timer** — Displays "Live" when at the live edge, or `currentTime / totalTime` (e.g., `1:23:45 / 5:15:00`) when seeking through VOD content.
 - **Rewind-to-VOD** — When the user seeks behind the DVR window, automatically fetches a VOD HLS URL and swaps the source. Provides a "Go Live" button to return to the live stream.
 - **Quality Enforcement** — Locks the player to a user-preferred quality level (e.g., 1080p) across source swaps, with an ABR suppression window to avoid thrashing during initial ramp-up.
@@ -13,7 +13,7 @@ A Live DVR Rewind Plugin for video.js — full-stream seek bar, rewind-to-VOD, q
 ## Installation
 
 ```bash
-npm install @ashleyjackson/videojs-rewind
+npm install videojs-rewind
 ```
 
 ## Usage
@@ -22,7 +22,7 @@ npm install @ashleyjackson/videojs-rewind
 import videojs from 'video.js';
 import '@videojs/http-streaming';
 import 'videojs-contrib-quality-levels';
-import '@ashleyjackson/videojs-rewind';
+import 'videojs-rewind';
 
 const player = videojs('my-player', {
   controls: true,
@@ -36,24 +36,85 @@ const player = videojs('my-player', {
   },
   plugins: {
     rewind: {
+      channelName: 'ashley',           // host-supplied, generic (not Twitch-specific)
       preferredQuality: 1080,
       enableRewindToVod: true,
-      resolveVodUrl: async (channel, seekTime) => {
-        const vodId = await fetchVodForChannel(channel, seekTime);
+      resolveVodUrl: async (channel, seekTime, context) => {
+        // context.currentVodId is set when the host already knows the VOD.
+        // context.liveTotalElapsed is set when the seek originated from a live
+        // source (seconds the broadcast has been live), so the host can pick the
+        // VOD matching the current broadcast without re-deriving it.
+        const vodId = context?.currentVodId ?? await fetchVodForChannel(channel, seekTime, context?.liveTotalElapsed);
         const hlsUrl = await getSignedVodUrl(vodId);
         return { vodId, hlsUrl };
       },
+      resolveLiveUrl: async (channel) => {
+        // Required when enableRewindToVod is true; used to return to live after VOD playback
+        const res = await fetch(`/api/live/${channel}`);
+        const { hlsUrl } = await res.json();
+        return hlsUrl;
+      },
+      // Quality persistence: delegate to host storage instead of the plugin's
+      // own localStorage key. When set, persistQuality is ignored.
+      loadQuality: () => getSync('vjsQuality'),
+      saveQuality: (q) => setSync('vjsQuality', q),
       storyboard: {
+        // fetchInfo returns the RAW provider response (single entry, array, or null).
+        // The plugin validates it with a Zod schema and selects an entry.
         fetchInfo: async (vodId, cdnBaseUrl) => {
           const res = await fetch(`${cdnBaseUrl}/../storyboards/${vodId}-info.json`);
           return res.json();
-        }
+        },
+        // Resolve a sprite image ref (filename or URL) to a fully-qualified URL.
+        // Optional — if omitted, images entries are treated as already-qualified.
+        resolveImageUrl: (ref, _entry, cdnBaseUrl) => `${cdnBaseUrl}storyboards/${ref}`,
+        preferredQuality: 'high'        // pick this entry when info is an array
       }
     }
   }
 });
 ```
 
+> **Live and VOD sources.** The plugin auto-detects the source type on `loadedmetadata`: a non-finite duration is treated as a finite VOD (full seek bar over `[0, duration]`, "Go Live" hidden, no rewind-to-VOD swaps), while a live stream uses the DVR window and live edge. No configuration is needed to switch between them — just call `player.src()` with the new HLS URL.
+
+## Programmatic API
+
+The plugin is registered as a video.js advanced (class-based) plugin. After construction, obtain the instance via the player's plugin accessor and cast it to the exported class to reach the typed methods:
+
+```javascript
+import videojs from 'video.js';
+import RewindPlugin from 'videojs-rewind';
+
+const player = videojs('my-player', { /* ... */ });
+// plugin is constructed via the `plugins.rewind` config (see Usage) or:
+player.rewind();
+
+const plugin = player.rewind() as RewindPlugin;
+plugin.seek(120);     // seek to 120s (clamped, runs rewind-to-VOD detection)
+plugin.goLive();      // swap back to the live source
+plugin.setQuality(1080);
+plugin.getQuality();
+```
+
+- `seek(time)` — clamps to `[0, maxTime]`, runs rewind-to-VOD detection, and seeks in-place when no source swap is needed. No-op after `dispose()`.
+- `goLive()` — returns to the live source via `resolveLiveUrl` / `liveUrl`. No-op after `dispose()`.
+
+### `rewindmodechange` event
+
+When the plugin swaps the source between live and VOD (in either direction), it triggers a `rewindmodechange` event on the player **after** the new source's `loadedmetadata` fires, so the host can react once playback is actually ready. The event is not fired on an aborted transition (e.g., resolver returned `null`).
+
+```javascript
+player.on('rewindmodechange', (e) => {
+  // e.mode === 'vod' | 'live'
+  // e.vodId === '<id>'  (present only when mode === 'vod')
+  if (e.mode === 'vod') {
+    updateUrlBar(`/videos/${e.vodId}`);
+  } else {
+    updateUrlBar(`/${channel}`);
+  }
+});
+```
+
 ## Options
 
 | Option | Type | Default | Description |
@@ -61,13 +122,21 @@ const player = videojs('my-player', {
 | `customSeekBar` | `boolean` | `true` | Enable custom seek bar (replaces native ProgressControl) |
 | `showTotalTime` | `boolean` | `true` | Show total stream time in timer display |
 | `enableRewindToVod` | `boolean` | `true` | Enable rewind-to-VOD flow |
-| `resolveVodUrl` | `function` | `null` | Callback to resolve a VOD URL when seeking behind DVR window |
+| `channelName` | `string` | `undefined` | Host-supplied channel identifier, passed to `resolveVodUrl` / `resolveLiveUrl`. Required when using rewind-to-VOD with a resolver. |
+| `liveUrl` | `string` | `undefined` | Static live HLS URL used by "Go Live". Takes precedence over `resolveLiveUrl`. |
+| `cdnBaseUrl` | `string` | `undefined` | Explicit CDN base URL for storyboard `fetchInfo`. Overrides automatic capture from VHS playlist responses. |
+| `resolveVodUrl` | `function` | `null` | `(channelName, seekTime, context?) => Promise<{ vodId, hlsUrl } \| null>` — resolve a VOD URL when seeking behind the DVR window. `context.currentVodId` is set when the host already knows the VOD; `context.liveTotalElapsed` is set (seconds) when the seek originated from a live source. |
+| `resolveLiveUrl` | `function` | `null` | `(channelName) => Promise<string \| null>` — resolve the live HLS URL for "Go Live". Required when `enableRewindToVod` is `true` and `liveUrl` is not set. |
 | `preferredQuality` | `number \| "auto"` | `"auto"` | Preferred quality height (e.g., `1080`) or `"auto"` for ABR |
-| `persistQuality` | `boolean` | `true` | Persist quality preference to localStorage |
+| `persistQuality` | `boolean` | `true` | Persist quality preference to localStorage (ignored when `loadQuality`/`saveQuality` are set) |
 | `storageKeyPrefix` | `string` | `"videojs-rewind:"` | Prefix for localStorage keys |
-| `storyboard` | `object` | `null` | Storyboard configuration (`fetchInfo`, `previewWidth`, `previewHeight`) |
+| `loadQuality` | `function` | `null` | `() => number \| "auto" \| null` — host-supplied quality reader. Takes precedence over localStorage. |
+| `saveQuality` | `function` | `null` | `(quality) => void` — host-supplied quality writer. Takes precedence over localStorage. |
+| `storyboard` | `object` | `null` | Storyboard configuration (`fetchInfo`, `resolveImageUrl`, `preferredQuality`, `previewWidth`, `previewHeight`) |
 | `dvrWindowThreshold` | `number` | `120` | Seconds before rewind-to-VOD triggers |
 | `showToasts` | `boolean` | `true` | Show toast notifications |
+| `enableKeyboardSeek` | `boolean` | `true` | Wire the plugin's `ArrowLeft`/`ArrowRight` keyboard seek handler. Disable when the host supplies its own keyboard shortcuts to avoid a double-seek. Keyboard seeks route through `seek()` (so they trigger rewind-to-VOD detection). |
+| `keyboardSeekStep` | `number` | `5` | Seconds sought per `ArrowLeft`/`ArrowRight` press (when `enableKeyboardSeek` is `true`). |
 
 ## Development
 

package/dist/dom.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DOM construction helpers for videojs-rewind.
+ */
+/**
+ * Create a DOM element with attributes and optional text content.
+ *
+ * @param tag - HTML tag name (e.g. 'div', 'span', 'button')
+ * @param attrs - Attributes to set on the element
+ * @param text - Optional text content
+ */
+export declare function createEl<K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string>, text?: string): HTMLElementTagNameMap[K];