stormcloud-video-player 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2025] [Showfer Media LLC]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+## 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.
+
+### Key goals
+
+- 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
+
+### Features (current)
+
+- 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
+
+```bash
+npm install stormcloud-video-player hls.js
+```
+
+This library targets modern browsers (ES2020) and expects a DOM environment.
+
+---
+
+## Quick start
+
+### React Usage
+
+```jsx
+import React from "react";
+import { StormcloudVideoPlayerComponent } from "stormcloud-video-player";
+
+function MyApp() {
+  return (
+    <StormcloudVideoPlayerComponent
+      src="https://example.com/live/playlist.m3u8"
+      autoplay={true}
+      muted={true}
+      allowNativeHls={false}
+      controls={true}
+      style={{ width: "640px", height: "360px" }}
+      adSchedule={{
+        lateJoinPolicy: "play_remaining",
+        breaks: [
+          {
+            startTimeMs: 60_000,
+            durationMs: 120_000,
+            vastTagUrl: "https://...",
+          },
+        ],
+      }}
+      onReady={(player) => {
+        console.log("Player ready:", player);
+      }}
+    />
+  );
+}
+```
+
+### Vanilla JavaScript 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";
+
+  const video = document.getElementById("video");
+
+  const player = new StormcloudVideoPlayer({
+    videoElement: video,
+    src: "https://example.com/live/playlist.m3u8",
+    autoplay: true,
+    muted: true,
+    allowNativeHls: false,
+    // Optional external ad schedule
+    adSchedule: {
+      lateJoinPolicy: "play_remaining",
+      breaks: [
+        { startTimeMs: 60_000, durationMs: 120_000, vastTagUrl: "https://..." },
+      ],
+    },
+  });
+
+  player.load();
+</script>
+```
+
+---
+
+## API
+
+### Class: `StormcloudVideoPlayer`
+
+```ts
+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`
+
+### Types
+
+```ts
+type LateJoinPolicy = "play_remaining" | "skip_to_content";
+
+interface AdBreak {
+  id?: string;
+  startTimeMs: number;
+  durationMs?: number;
+  vastTagUrl?: string;
+}
+
+interface AdSchedule {
+  breaks: AdBreak[];
+  lateJoinPolicy?: LateJoinPolicy;
+}
+
+interface StormcloudVideoPlayerConfig {
+  videoElement: HTMLVideoElement;
+  src: string;
+  autoplay?: boolean;
+  muted?: boolean;
+  allowNativeHls?: boolean;
+  adSchedule?: AdSchedule;
+  defaultVastTagUrl?: string;
+}
+```
+
+---
+
+## How ad alignment works
+
+- 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.
+
+---
+
+## External schedules and Airy API
+
+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.
+
+Note: Real-world APIs may require authentication or custom mapping from their JSON to `AdSchedule`. Add an adapter as needed before calling `setAdSchedule`.
+
+---
+
+## Development
+
+```bash
+npm run build   # build ESM + CJS with types
+npm run dev     # watch mode
+npm run clean   # remove dist
+```
+
+---
+
+## Limitations
+
+- 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.
+
+---
+
+## Roadmap / Remaining tasks
+
+- 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
+
+---
+
+## License
+
+MIT