stormcloud-video-player 0.1.7 → 0.1.9

package/README.md

@@ -1,259 +1,291 @@
-## stormcloud-video-player
+# Stormcloud Video Player
 
-Ad-first HLS player module for the web with tight ad break alignment. It uses the HTML5 video element with hls.js, parses SCTE-35 signals from HLS tags and ID3 timed metadata, and integrates Google IMA for VAST/VPAID ad playback.
+A professional HLS video player with advanced ad integration for web applications. Built with precision ad break alignment, SCTE-35 signal parsing, and Google IMA SDK integration for seamless VAST/VPAID ad playback.
 
-### Key goals
+## 🎯 Key Features
 
-- Precise ad start alignment on SCTE-35 CUE-OUT
-- Mid-ad join synchronization (play remaining portion if you tune in late)
-- Flexible fallback for feeds without SCTE-35 via external schedules
+- **Precision Ad Alignment**: Tight synchronization with SCTE-35 CUE-OUT signals
+- **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
+- **Cross-Platform**: Works on desktop, mobile, tablets, and smart TVs
+- **React Ready**: Includes React component for easy integration
+- **TypeScript Support**: Full type definitions included
 
-### Features (current)
+## 🚀 Quick Start
 
-- HLS playback via hls.js with native HLS fallback
-- SCTE-35 parsing from HLS tags: `#EXT-X-CUE-OUT`, `#EXT-X-CUE-OUT-CONT`, `#EXT-X-CUE-IN`, `#EXT-X-DATERANGE`
-- SCTE-35/markers parsing from ID3 text payloads
-- IMA SDK integration with pause/resume/error handling
-- Remaining-duration countdown and auto-stop when CUE-IN is absent
-- External schedule ingestion helpers and default VAST tag support
-
----
-
-## Install
+### Installation
 
 ```bash
 npm install stormcloud-video-player hls.js
 ```
 
-This library targets modern browsers (ES2020) and expects a DOM environment.
-
-### CDN Usage
-
-You can also use the library directly from CDN without npm:
-
-```html
-<!-- Use latest version (recommended for development) -->
-<script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
-
-<script>
-  // The library is available as window.StormcloudVideoPlayer
-  const { StormcloudVideoPlayer } = window.StormcloudVideoPlayer;
-
-  const video = document.getElementById("video");
-  const player = new StormcloudVideoPlayer({
-    videoElement: video,
-    src: "https://example.com/live/playlist.m3u8",
-    autoplay: true,
-    muted: true,
-    allowNativeHls: false,
-  });
-
-  player.load();
-</script>
-```
-
----
-
-## Quick start
-
-### React Usage
+### React Integration
 
 ```jsx
 import React from "react";
 import { StormcloudVideoPlayerComponent } from "stormcloud-video-player";
 
-function MyApp() {
+function MyVideoApp() {
   return (
     <StormcloudVideoPlayerComponent
-      src="https://example.com/live/playlist.m3u8"
+      src="https://your-stream.com/playlist.m3u8"
       autoplay={true}
       muted={true}
-      allowNativeHls={false}
       controls={true}
       licenseKey="your_license_key_here"
-      style={{ width: "640px", height: "360px" }}
-      adSchedule={{
-        lateJoinPolicy: "play_remaining",
-        breaks: [
-          {
-            startTimeMs: 60_000,
-            durationMs: 120_000,
-            vastTagUrl: "https://...",
-          },
-        ],
-      }}
+      style={{ width: "100%", aspectRatio: "16/9" }}
       onReady={(player) => {
-        console.log("Player ready:", player);
+        console.log("Player is ready!", player);
       }}
     />
   );
 }
 ```
 
-### Vanilla JavaScript Usage
+### Vanilla JavaScript
+
+```javascript
+import { StormcloudVideoPlayer } from "stormcloud-video-player";
+
+const video = document.getElementById("my-video");
+
+const player = new StormcloudVideoPlayer({
+  videoElement: video,
+  src: "https://your-stream.com/playlist.m3u8",
+  autoplay: true,
+  muted: true,
+  allowNativeHls: false,
+  licenseKey: "your_license_key_here",
+});
+
+await player.load();
+```
+
+### CDN Usage
 
 ```html
-<div id="player" style="position:relative;width:640px;height:360px;">
-  <video
-    id="video"
-    playsinline
-    muted
-    controls
-    style="width:100%;height:100%;"
-  ></video>
-</div>
-<script type="module">
-  import { StormcloudVideoPlayer } from "stormcloud-video-player";
+<script src="https://cdn.jsdelivr.net/npm/stormcloud-video-player/dist/stormcloud-vp.min.js"></script>
 
-  const video = document.getElementById("video");
+<script>
+  const { StormcloudVideoPlayer } = window.StormcloudVideoPlayer;
 
+  const video = document.getElementById("video");
   const player = new StormcloudVideoPlayer({
     videoElement: video,
-    src: "https://example.com/live/playlist.m3u8",
+    src: "https://your-stream.com/playlist.m3u8",
     autoplay: true,
     muted: true,
-    allowNativeHls: false,
-    licenseKey: "your_license_key_here", // Optional
-    // Optional external ad schedule
-    adSchedule: {
-      lateJoinPolicy: "play_remaining",
-      breaks: [
-        { startTimeMs: 60_000, durationMs: 120_000, vastTagUrl: "https://..." },
-      ],
-    },
   });
 
   player.load();
 </script>
 ```
 
----
+## 📖 API Reference
 
-## API
+### StormcloudVideoPlayer Class
 
-### Class: `StormcloudVideoPlayer`
+#### Constructor
 
-```ts
+```typescript
 new StormcloudVideoPlayer(config: StormcloudVideoPlayerConfig)
 ```
 
-- `load(): Promise<void>`: Attach and start playback for the configured source
-- `destroy(): void`: Cleanup player and ad resources
-- `setAdSchedule(schedule?: AdSchedule): void`: Provide/replace ad schedule
-- `loadAdScheduleFromUrl(url: string): Promise<void>`: Fetch and set JSON schedule
-- `loadDefaultVastFromAiry(url: string, params?: Record<string, string>): Promise<void>`: Fetch ad tag from Airy-like API and set `defaultVastTagUrl`
+#### Methods
 
-### Types
+| Method                                     | Description                                   | Returns         |
+| ------------------------------------------ | --------------------------------------------- | --------------- |
+| `load()`                                   | Initialize and start video playback           | `Promise<void>` |
+| `destroy()`                                | Clean up player resources and event listeners | `void`          |
+| `toggleMute()`                             | Toggle video mute state                       | `void`          |
+| `toggleFullscreen()`                       | Enter/exit fullscreen mode                    | `Promise<void>` |
+| `isMuted()`                                | Check if video is currently muted             | `boolean`       |
+| `isFullscreen()`                           | Check if player is in fullscreen mode         | `boolean`       |
+| `loadDefaultVastFromAdstorm(url, params?)` | Load VAST tags from Adstorm API               | `Promise<void>` |
 
-```ts
-type LateJoinPolicy = "play_remaining" | "skip_to_content";
-
-interface AdBreak {
-  id?: string;
-  startTimeMs: number;
-  durationMs?: number;
-  vastTagUrl?: string;
-}
-
-interface AdSchedule {
-  breaks: AdBreak[];
-  lateJoinPolicy?: LateJoinPolicy;
-}
+#### Configuration Options
 
+```typescript
 interface StormcloudVideoPlayerConfig {
-  videoElement: HTMLVideoElement;
-  src: string;
-  autoplay?: boolean;
-  muted?: boolean;
-  allowNativeHls?: boolean;
-  adSchedule?: AdSchedule;
-  defaultVastTagUrl?: string;
-  licenseKey?: string;
+  videoElement: HTMLVideoElement; // Target video element
+  src: string; // HLS stream URL
+  autoplay?: boolean; // Auto-start playback (default: false)
+  muted?: boolean; // Start muted (default: false)
+  allowNativeHls?: boolean; // Use native HLS when available (default: true)
+  licenseKey?: string; // API authentication key
+  debugAdTiming?: boolean; // Enable debug logging (default: false)
+  adFailsafeTimeoutMs?: number; // Ad timeout in milliseconds (default: 10000)
 }
 ```
 
----
+## 🎬 Ad Integration
+
+### SCTE-35 Support
+
+The player automatically detects and responds to SCTE-35 signals embedded in HLS streams:
+
+- **CUE-OUT**: Triggers ad break start
+- **CUE-OUT-CONT**: Handles mid-roll continuation
+- **CUE-IN**: Resumes content playback
+- **DATERANGE**: Processes time-based ad markers
 
-## License Key Authentication
+### Supported HLS Tags
 
-The player supports license key authentication for API calls. When a `licenseKey` is provided, it will be included as a `Bearer` token in the `Authorization` header for all API requests to:
+- `#EXT-X-CUE-OUT`
+- `#EXT-X-CUE-OUT-CONT`
+- `#EXT-X-CUE-IN`
+- `#EXT-X-DATERANGE`
+- ID3 timed metadata
 
-- Ad configuration endpoint: `https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
-- Initial tracking: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track`
-- Heartbeat tracking: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat`
+### Late Join Behavior
 
-### Usage
+When viewers join during an ad break:
+
+- **play_remaining**: Plays the remaining portion of the current ad
+- **skip_to_content**: Skips to main content (configurable via API)
+
+## 🔐 Authentication
+
+The player supports license key authentication for enhanced features:
 
 ```javascript
-// Vanilla JavaScript
 const player = new StormcloudVideoPlayer({
-  videoElement: video,
-  src: "https://example.com/stream.m3u8",
-  licenseKey: "your_license_key_here" // Optional
+  // ... other config
+  licenseKey: "ADSTORM-YOUR-LICENSE-KEY-HERE",
 });
-
-// React Component
-<StormcloudVideoPlayerComponent
-  src="https://example.com/stream.m3u8"
-  licenseKey="your_license_key_here" // Optional
-/>
 ```
 
-The license key is optional and the player will work without it, but some API features may be limited or unavailable.
+Authenticated requests are sent to:
 
----
+- Ad configuration: `https://adstorm.co/api-adstorm-dev/adstorm/ads/web`
+- Player tracking: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/track`
+- Heartbeat monitoring: `https://adstorm.co/api-adstorm-dev/adstorm/player-tracking/heartbeat`
 
-## How ad alignment works
+## 🔧 Advanced Configuration
 
-- On `CUE-OUT`/`DATERANGE` start: request IMA ads and start playback immediately; if duration is known, a countdown is scheduled to auto-stop if `CUE-IN` is missing.
-- On `CUE-OUT-CONT` (progress): if not already playing, and policy is `play_remaining`, request ads and start; countdown is updated based on elapsed/duration.
-- On `CUE-IN`: stop ads and resume content immediately.
-- Without markers: provide `adSchedule` or a `defaultVastTagUrl` to still serve ads based on wall-clock content time.
+### Custom Styling
 
----
+```css
+.stormcloud-video-player {
+  width: 100%;
+  height: 100%;
+  background: #000;
+}
 
-## External schedules and Airy API
+.stormcloud-video-player video {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+```
 
-You can set an `AdSchedule` directly via `setAdSchedule` or load a JSON schedule from a URL with `loadAdScheduleFromUrl`. For Airy-like APIs (`https://api.airy.tv/api/v2.1.7/ads/web`), use `loadDefaultVastFromAiry(airyApiUrl, params)` to set the default VAST tag returned by the service.
+### Event Handling
 
-Note: Real-world APIs may require authentication or custom mapping from their JSON to `AdSchedule`. Add an adapter as needed before calling `setAdSchedule`.
+```javascript
+player.on("adStart", (event) => {
+  console.log("Ad started:", event.ad);
+});
 
----
+player.on("adComplete", (event) => {
+  console.log("Ad completed:", event.ad);
+});
+
+player.on("contentResumed", () => {
+  console.log("Content playback resumed");
+});
+```
 
-## Development
+## 🌐 Browser 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
+
+## 🏗️ Development
+
+### Build Commands
 
 ```bash
-npm run build   # build ESM + CJS with types
-npm run dev     # watch mode
-npm run clean   # remove dist
+npm run build      # Build production bundle
+npm run dev        # Development watch mode
+npm run clean      # Clean build artifacts
+npm run test       # Run test suite
+npm run lint       # Lint codebase
 ```
 
----
+### Project Structure
+
+```
+src/
+├── index.ts                    # Main exports
+├── player/
+│   └── StormcloudVideoPlayer.ts   # Core player class
+├── ui/
+│   └── StormcloudVideoPlayer.tsx  # React component
+├── sdk/
+│   └── ima.ts                     # Google IMA integration
+├── utils/
+│   └── tracking.ts                # Analytics and tracking
+└── types.ts                       # TypeScript definitions
+```
 
-## Limitations
+## 🎯 Use Cases
 
-- This module targets browsers (DOM required). SSR/Node-only not supported.
-- SCTE-35 parsing relies on HLS tags and ID3 text; binary splice parsing is not implemented yet.
-- Multi-ad pod stitching and competitive separation are left to the ad server/IMA.
+- **Live Streaming**: Sports, news, and event broadcasts
+- **VOD Platforms**: Movie and series streaming services
+- **Educational Content**: E-learning and training platforms
+- **Corporate Communications**: Internal and external video content
+- **Digital Signage**: Retail and public display systems
 
----
+## ⚠️ Known Limitations
 
-## Roadmap / Remaining tasks
+- Requires DOM environment (browser-only)
+- SCTE-35 binary splice parsing not yet implemented
+- Multi-ad pod competitive separation handled by ad server
+- Low-latency HLS (LL-HLS) optimizations in development
 
-- Robust SCTE-35 binary parsing (splice_info_section) and richer marker mapping
-- Stronger late-join logic: handle partial pods, skip-to-content policy
-- Low-Latency HLS (LL-HLS) tuning to reduce ad-start drift further
-- Better drift correction between PTS and wall-clock; tolerance config
-- Ad pod management: sequencing multiple ads per break if provided
-- UI overlays: optional countdown/"Ad" badge and simple debug HUD
-- Retry/backoff and error telemetry for both HLS and IMA flows
-- Analytics events (start/firstQuartile/midpoint/thirdQuartile/complete)
-- Example app and demo page with real streams and test tags
-- Type definitions for IMA surface (remove `any`) and stronger public types
-- CI, unit tests (ID3/daterange parsers), and integration tests
+## 🗺️ Roadmap
 
----
+### Upcoming Features
+
+- **Enhanced SCTE-35**: Full binary splice_info_section parsing
+- **Advanced Late Join**: Improved partial pod handling
+- **LL-HLS Support**: Low-latency streaming optimizations
+- **Rich Analytics**: Comprehensive event tracking and reporting
+- **UI Components**: Built-in countdown timers and ad indicators
+- **Error Recovery**: Advanced retry logic and failover handling
+
+### Performance Improvements
+
+- Drift correction between PTS and wall-clock timing
+- Memory optimization for long-running sessions
+- Network bandwidth adaptation
+- Smart preloading strategies
 
-## License
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+```bash
+git clone https://github.com/your-org/stormcloud-video-player.git
+cd stormcloud-video-player
+npm install
+npm run dev
+```
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- **Documentation**: [Full API Docs](https://docs.stormcloud.tv)
+- **Issues**: [GitHub Issues](https://github.com/your-org/stormcloud-video-player/issues)
+- **Discord**: [Community Chat](https://discord.gg/stormcloud)
+- **Email**: support@stormcloud.tv
+
+---
 
-MIT
+Built with ❤️ by the Stormcloud team