stormcloud-video-player 0.3.57 → 0.3.59

package/README.md

@@ -1,16 +1,18 @@
 # Stormcloud Video Player
 
-A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, custom VAST ad serving, and optional Google IMA SDK integration for seamless ad playback. Now featuring a modern, extensible architecture inspired by react-player.
+A professional video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, VMAP ad-break scheduling, custom VAST ad serving, and optional Google IMA SDK integration for seamless ad playback. Now featuring a modern, extensible architecture inspired by react-player.
 
 ## 🎯 Key Features
 
 - **Multi-Format Support**: Automatic detection and playback of HLS streams and regular video files
 - **Precision Ad Alignment**: Tight synchronization with SCTE-35 CUE-OUT signals
+- **VMAP 1.0 Support**: Schedule pre-roll, mid-roll, and post-roll ad breaks via a VMAP manifest
 - **Smart Mid-Roll Handling**: Automatic detection and playback of remaining ad portions when joining late
-- **Flexible Ad Scheduling**: Support for both SCTE-35 markers and external ad schedules
+- **Flexible Ad Scheduling**: Support for SCTE-35 markers, VMAP manifests, and external ad schedules
 - **Enhanced UI Controls**: Beautiful, adaptive video controls that work on any background color
 - **Live Mode Support**: Specialized controls for live streaming with volume adjustment
-- **Cross-Platform**: Works on desktop, mobile, tablets, and smart TVs
+- **Cross-Platform & Smart TV Ready**: Desktop, mobile, tablets, LG WebOS, Samsung Tizen, Sony BRAVIA, Android TV, Roku, Apple TV
+- **Automatic Browser Compatibility**: Built-in browser detection, polyfills, and automatic ad-player selection for legacy Smart TVs
 - **React Ready**: Multiple React components for different use cases
 - **TypeScript Support**: Full type definitions included
 - **Professional Architecture**: Modular player system with lazy loading
@@ -39,9 +41,11 @@ function MyVideoApp() {
       muted={true}
       controls={true}
       showCustomControls={true} // Enable enhanced UI controls
+      hideLoadingIndicator={false} // Hide the built-in loading spinner
       allowNativeHls={true} // Allow native HLS for better performance
       licenseKey="your_license_key_here"
       vastMode="adstorm" // Use AdStorm mode with HLS ad player
+      vmapUrl="https://your-cdn.com/ads.vmap" // Optional VMAP manifest for scheduled breaks
       style={{ width: "100%", aspectRatio: "16/9" }}
       wrapperStyle={{ borderRadius: "12px", overflow: "hidden" }}
       onReady={(player) => {
@@ -77,8 +81,10 @@ function MyVideoApp() {
       // Stormcloud-specific props
       allowNativeHls={true}
       showCustomControls={true}
+      hideLoadingIndicator={false}
       licenseKey="your_license_key_here"
       vastMode="adstorm" // Use AdStorm mode (or omit for default mode)
+      vmapUrl="https://your-cdn.com/ads.vmap" // Optional: VMAP manifest URL
       onReady={(player) => {
         console.log("Player is ready!", player);
       }}
@@ -114,9 +120,12 @@ const player = new StormcloudVideoPlayer({
   muted: true,
   allowNativeHls: true, // Enable native HLS when supported
   showCustomControls: true, // Enable enhanced UI controls
+  hideLoadingIndicator: false, // Hide built-in loading spinner
   lowLatencyMode: false, // Set to true for live streams
   driftToleranceMs: 3000, // Drift tolerance for live streams
   licenseKey: "your_license_key_here",
+  vastMode: "default", // "adstorm" | "default"
+  vmapUrl: "https://your-cdn.com/ads.vmap", // Optional VMAP manifest for scheduled ad breaks
   onVolumeToggle: () => console.log("Volume toggled"),
   onFullscreenToggle: () => console.log("Fullscreen toggled"),
 });
@@ -264,6 +273,7 @@ interface StormcloudPlayerProps {
   immediateManifestAds?: boolean;
   debugAdTiming?: boolean;
   showCustomControls?: boolean;
+  hideLoadingIndicator?: boolean; // Hide the built-in loading spinner (default: false)
   licenseKey?: string;
   adFailsafeTimeoutMs?: number;
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
@@ -271,6 +281,7 @@ interface StormcloudPlayerProps {
   // Ad player configuration
   vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (HLS player + AdStorm VAST endpoint) or 'default' (IMA SDK + /ads/web endpoint) (default: 'default')
   vastTagUrl?: string; // Custom VAST URL (used in default mode if provided; when not provided, uses /ads/web endpoint)
+  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
   adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
 
   // Event handlers
@@ -347,6 +358,7 @@ interface StormcloudVideoPlayerConfig {
   muted?: boolean; // Start muted (default: false)
   allowNativeHls?: boolean; // Use native HLS when available (default: false)
   showCustomControls?: boolean; // Enable enhanced UI controls (default: false)
+  hideLoadingIndicator?: boolean; // Hide the built-in loading spinner (default: false)
   lowLatencyMode?: boolean; // Enable low-latency mode for live streams (default: false)
   driftToleranceMs?: number; // Drift tolerance for live streams (default: 1000)
   immediateManifestAds?: boolean; // Load ads immediately from manifest (default: true)
@@ -355,10 +367,15 @@ interface StormcloudVideoPlayerConfig {
   adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
   minSegmentsBeforePlay?: number; // Number of segments to buffer before starting playback (default: 2)
 
+  // Ad break timing
+  adBreakCheckIntervalMs?: number; // Interval used to re-check an active ad break (default: 1000, min: 250)
+  maxAdBreakExtensionMs?: number; // Max time an ad break may be extended past its SCTE-35 duration when ads are still playing/queued (default: 60000)
+
   // Ad configuration
   vastMode?: 'adstorm' | 'default'; // VAST mode: 'adstorm' (uses HLS player + AdStorm VAST endpoint) or 'default' (uses Google IMA SDK + /ads/web endpoint) (default: 'default')
   vastTagUrl?: string; // Custom VAST tag URL (used in default mode if provided; when not provided, defaults to /ads/web endpoint)
-  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode if not specified)
+  vmapUrl?: string; // Optional VMAP 1.0 manifest URL used to schedule pre/mid/post-roll ad breaks
+  adPlayerType?: 'ima' | 'hls'; // Manual override for ad player type (auto-determined by vastMode/browser if not specified)
 
   onVolumeToggle?: () => void; // Callback for volume toggle
   onFullscreenToggle?: () => void; // Callback for fullscreen toggle
@@ -621,6 +638,94 @@ Final: 3 ads played (perfectly fills 120 seconds)
 - ✅ **Smart**: Improves calculation as more data is gathered (uses average of fetched durations)
 - ✅ **Self-Correcting**: Automatically adjusts if actual ad lengths differ from expectations
 
+### VMAP Ad Break Scheduling
+
+In addition to SCTE-35 markers and continuous-ad-fetch, the player supports **VMAP 1.0** manifests for scheduling ad breaks at specific positions in the timeline. This is ideal for VOD content where you want to declaratively define pre-roll, mid-roll, and post-roll breaks with explicit time offsets.
+
+#### Usage
+
+Provide a `vmapUrl` in addition to (or instead of) a VAST/AdStorm configuration:
+
+```javascript
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://your-stream.com/video.m3u8",
+  licenseKey: "your-license-key",
+
+  vastMode: 'default',
+  vmapUrl: 'https://your-cdn.com/schedule.vmap', // VMAP 1.0 manifest
+
+  debugAdTiming: true,
+});
+```
+
+Or with React:
+
+```jsx
+<StormcloudPlayer
+  src="https://your-stream.com/video.m3u8"
+  licenseKey="your-license-key"
+  vmapUrl="https://your-cdn.com/schedule.vmap"
+  playing={true}
+/>
+```
+
+#### Supported `timeOffset` Formats
+
+The VMAP parser recognizes all standard `timeOffset` values:
+
+| Value                 | Meaning                                              |
+| --------------------- | ---------------------------------------------------- |
+| `start`               | Pre-roll (playback position 0)                       |
+| `end`                 | Post-roll (resolved at runtime using media duration) |
+| `HH:MM:SS` / `HH:MM:SS.mmm` | Absolute timestamp mid-roll                    |
+| `NN%`                 | Percentage of media duration (resolved at runtime)   |
+
+#### Example VMAP Manifest
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">
+  <vmap:AdBreak timeOffset="start" breakType="linear" breakId="preroll">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=preroll]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+
+  <vmap:AdBreak timeOffset="00:05:00" breakType="linear" breakId="midroll-1">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=midroll-1]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+
+  <vmap:AdBreak timeOffset="end" breakType="linear" breakId="postroll">
+    <vmap:AdSource>
+      <vmap:AdTagURI templateType="vast3">
+        <![CDATA[https://your-ad-server.com/vast?position=postroll]]>
+      </vmap:AdTagURI>
+    </vmap:AdSource>
+  </vmap:AdBreak>
+</vmap:VMAP>
+```
+
+#### How It Works
+
+1. The player fetches the VMAP manifest on load (before playback starts).
+2. Each `<AdBreak>` is parsed into an `AdBreak` object with a resolved `startTimeMs` and the associated `vastTagUrl` from `<AdTagURI>`.
+3. During playback, the player matches the current time against each scheduled break and triggers the ad request at the correct offset.
+4. **Mid-roll join behavior**: If the viewer joins mid-stream and has already passed a scheduled break, the player will honor the configured late-join policy (e.g., play the remaining portion or skip to content).
+5. Each break is only consumed once per session to avoid replaying breaks after seeking.
+
+**Benefits:**
+- ✅ Declarative ad scheduling — no custom code needed per break
+- ✅ Works alongside `vastMode: 'adstorm'` and `vastMode: 'default'`
+- ✅ Supports pre-roll, mid-roll, percentage-based, and post-roll breaks
+- ✅ Gracefully handles malformed XML and fetch failures (logged when `debugAdTiming` is enabled)
+
 ### Manual Ad Player Override
 
 You can still manually override the ad player type if needed:
@@ -819,6 +924,52 @@ Authenticated requests are sent to:
 - **Player Tracking** (both modes):
   - Player tracking: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track` (requires `Authorization: Bearer {licenseKey}` header)
   - Heartbeat monitoring: `POST https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat` (requires `Authorization: Bearer {licenseKey}` header)
+  - Ad-detect, ad-loaded, and ad-impression events are automatically emitted during ad breaks.
+
+### Tracking Utilities
+
+The player exposes low-level tracking helpers if you want to fire events manually or build custom analytics:
+
+```javascript
+import {
+  getClientInfo,
+  getBrowserID,
+  sendInitialTracking,
+  sendHeartbeat,
+  sendAdDetectTracking,
+  sendAdLoadedTracking,
+  sendAdImpressionTracking,
+} from "stormcloud-video-player";
+
+const clientInfo = getClientInfo();
+const browserId = getBrowserID();
+
+await sendInitialTracking(licenseKey, clientInfo);
+await sendHeartbeat(licenseKey, { browserId, timestamp: new Date().toISOString() });
+
+// Ad lifecycle tracking
+await sendAdDetectTracking(licenseKey, {
+  source: "scte35",
+  durationSeconds: 30,
+  ptsSeconds: 120.5,
+  detectedAtFragmentSn: 1234,
+  timestamp: new Date().toISOString(),
+});
+
+await sendAdLoadedTracking(licenseKey, {
+  source: "ima", // 'prebid' | 'ima' | 'hls'
+  vastUrl: "https://...",
+  durationSeconds: 15,
+  timestamp: new Date().toISOString(),
+});
+
+await sendAdImpressionTracking(licenseKey, {
+  source: "ima",
+  adIndex: 0,
+  durationSeconds: 15,
+  timestamp: new Date().toISOString(),
+});
+```
 
 ## 🔧 Advanced Configuration
 
@@ -927,11 +1078,74 @@ console.log("Supports PIP:", canPIP); // true for file player
 />
 ```
 
-## 🌐 Browser Support
+## 🌐 Browser & Smart TV Support
 
 - **Desktop**: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+
 - **Mobile**: iOS Safari 12+, Chrome Mobile 60+
-- **Smart TV**: WebOS, Tizen, Android TV, Roku, Apple TV
+- **Smart TV**: LG WebOS (v2+), Samsung Tizen (v2+), Sony BRAVIA, Android TV, Roku, Apple TV, generic Smart TV user-agents
+
+### Automatic Browser Detection & Ad Player Selection
+
+The player automatically detects the runtime environment and chooses the optimal ad-player configuration. This is especially useful for Smart TVs where the Google IMA SDK may not be available on older devices.
+
+```javascript
+import {
+  detectBrowser,
+  supportsGoogleIMA,
+  getRecommendedAdPlayer,
+  supportsModernJS,
+  logBrowserInfo,
+  getBrowserConfigOverrides,
+  supportsFeature,
+} from "stormcloud-video-player";
+
+const info = detectBrowser();
+// {
+//   name: 'LG WebOS',
+//   version: '5.0',
+//   majorVersion: 5,
+//   isSmartTV: true,
+//   isLegacyTV: false,
+//   supportsIMA: true,
+//   supportsModernJS: true,
+//   recommendedAdPlayer: 'ima',
+//   webOSVersion: 5,
+//   chromeVersion: 79,
+//   ...
+// }
+
+console.log(supportsGoogleIMA());   // true | false
+console.log(getRecommendedAdPlayer()); // 'ima' | 'hls'
+console.log(supportsFeature('fetch')); // true | false
+```
+
+**What happens automatically:**
+
+- **Legacy Smart TVs** (LG NetCast, old WebOS < 3, old Tizen): `adPlayerType` is forced to `'hls'` and `allowNativeHls` is enabled.
+- **Modern Smart TVs**: `allowNativeHls` is enabled by default (TVs generally play HLS better natively).
+- **If IMA SDK is unsupported**: the player falls back to the HLS ad player automatically.
+- **Browser overrides** are merged with your config — user-provided options always take precedence.
+
+Call `logBrowserInfo(true)` (or enable `debugAdTiming`) to print a detailed compatibility report to the console.
+
+### Automatic Polyfills for Legacy Devices
+
+On older Smart TVs and browsers, `initializePolyfills()` is invoked automatically at construction time. It adds missing primitives needed for the player to run:
+
+- `URLSearchParams`
+- `TextEncoder`
+- `Promise.prototype.finally`
+- `Object.assign`
+- `Array.from`
+- `String.prototype.startsWith` / `endsWith` / `includes`
+
+You can also run it manually before bootstrapping anything else:
+
+```javascript
+import { initializePolyfills } from "stormcloud-video-player";
+
+initializePolyfills();
+```
 
 ### Format Support by Player
 
@@ -980,16 +1194,19 @@ src/
 │   ├── HlsPlayer.tsx                  # HLS stream handler
 │   └── FilePlayer.tsx                 # Regular video handler
 ├── player/
-│   └── StormcloudVideoPlayer.ts       # Core player class
+│   └── StormcloudVideoPlayer.ts       # Core player class (SCTE-35, VMAP, ad pods)
 ├── ui/
 │   └── StormcloudVideoPlayer.tsx      # Legacy React component
 ├── sdk/
-│   └── ima.ts                         # Google IMA integration
+│   ├── ima.ts                         # Google IMA integration
+│   └── hlsAdPlayer.ts                 # Native HLS ad player (AdStorm mode, legacy TVs)
 ├── utils/
-│   ├── tracking.ts                    # Analytics and tracking
-│   └── index.ts                       # Utility functions
+│   ├── tracking.ts                    # Analytics and ad tracking
+│   ├── browserCompat.ts               # Browser / Smart TV detection & auto-overrides
+│   └── polyfills.ts                   # Legacy browser polyfills
 ├── props.ts                           # Centralized props system
 ├── patterns.ts                        # URL pattern matching
+├── utils.ts                           # Shared utilities
 └── types.ts                           # TypeScript definitions
 ```
 
@@ -1102,6 +1319,22 @@ MIT License - see [LICENSE](LICENSE) file for details.
 
 Built with ❤️ by the Stormcloud team
 
+### What's New in v0.5
+
+- 🗓️ **VMAP 1.0 Support**: New `vmapUrl` config/prop loads a VMAP manifest and schedules pre-roll, mid-roll, percentage-based, and post-roll breaks automatically
+  - Supports `start`, `end`, `HH:MM:SS[.mmm]`, and `NN%` `timeOffset` values
+  - Namespaced (`vmap:AdBreak`) and non-namespaced manifests both supported
+  - Breaks are consumed-once-per-session and integrate with the existing late-join policy
+- 📺 **Smart TV First-Class Support**: New browser-compat layer auto-detects LG WebOS, Samsung Tizen, Sony BRAVIA, LG NetCast and generic Smart TV UAs
+  - Exports `detectBrowser`, `supportsGoogleIMA`, `getRecommendedAdPlayer`, `supportsModernJS`, `logBrowserInfo`, `getBrowserConfigOverrides`, `supportsFeature`
+  - Automatically forces HLS ad player on legacy TVs where IMA SDK is not available
+  - Automatically enables `allowNativeHls` on Smart TVs for more reliable playback
+- 🧩 **Automatic Polyfills**: `initializePolyfills()` runs at construction time and backfills `URLSearchParams`, `TextEncoder`, `Promise.prototype.finally`, `Object.assign`, `Array.from`, and `String.prototype.startsWith/endsWith/includes` for legacy environments
+- 📊 **Expanded Ad Tracking**: New `sendAdDetectTracking`, `sendAdLoadedTracking`, and `sendAdImpressionTracking` helpers (plus `AdDetectInfo`, `AdLoadedInfo`, `AdImpressionInfo`, and `AdTrackingSource` types) for prebid/IMA/HLS ad lifecycle events
+- ⚙️ **Ad-Break Timing Controls**: New `adBreakCheckIntervalMs` (default 1000ms, min 250ms) and `maxAdBreakExtensionMs` (default 60000ms) options give you precise control over how long the player is allowed to extend an ad break past its SCTE-35 duration when ads are still playing or queued
+- 🙈 **Hide Loading Indicator**: New `hideLoadingIndicator` prop/config hides the built-in buffering spinner when you want to render your own overlay
+- 🔌 **Expanded Public API**: `createImaController`, `createHlsAdPlayer`, and `initializePolyfills` are now exported alongside the new browser-compat utilities, making it easier to build custom integrations on top of the player core
+
 ### What's New in v0.4
 
 - 🚀 **Early Ad Prefetching**: Detects SCTE-35 markers in manifest fragments before playback reaches them, prefetching ads in advance for zero-delay ad starts