@oddin-gg/havik-player 2.9.3 → 2.11.0

package/docs/API.md

@@ -247,6 +247,7 @@ player.on('error', (e) => console.error(e.code, e.httpStatus, e.message));
 | `maxBitrate`          | `number`                                | —                                | Cap ABR to renditions at/below this bitrate (bps).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
 | `liveLatencyTarget`   | `number`                                | `2`                              | Target live‑edge latency in seconds (hls.js `liveSyncDuration`). The player derives a matching latency **ceiling** internally and catches up at 1.5×, so this is the only live‑latency knob you need. Lower = closer to live but more rebuffer‑prone. Live/LL only.                                                                                                                                                                                                                                                                                                               |
 | `snapToLiveOnRefocus` | `boolean`                               | `true`                           | Snap to the live edge when a backgrounded tab is refocused while far behind. Live/LL only.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `mediaDuringKey`      | `boolean`                               | `true`                           | DRM cold start: download the first init segment and parts while the first key is still being acquired, instead of after it. Bytes reach hls.js only when it asks for them; only the network time moves off the critical path (~0.5 s on Widevine LL-HLS). Ignored on clear streams and when `hlsConfig.fLoader` is set. Pass `false` to opt out.                                                                                                                                                                                                                                  |
 | `liveStateEvents`     | `boolean`                               | `true`                           | Use the push-based **live-state SSE** channel for go-live and end-of-stream (see [Live state](#live-state-sse)). Graceful: falls back to polling if the endpoint is unreachable. Set `false` to disable.                                                                                                                                                                                                                                                                                                                                                                          |
 | `rejoinOnLive`        | `boolean`                               | `true`                           | Rejoin automatically when a stream that ended comes back live. An ingest outage longer than the bridge's reconnect grace recreates the session under a **new manifest URL** (the old playlist freezes at HTTP 200), so the player keeps the live-state subscription open after `ended` (until `gone`) and re-arms on a pushed `live`. Set `false` to keep `ended` terminal. Needs `liveStateEvents`.                                                                                                                                                                              |
 | `analytics`           | `boolean \| { endpoint?: string }`      | `true`                           | QoE beacons. Active only when the playback response carries a server-minted `sid`. The beacons host is derived from `baseUrl` by hostname convention (`feed[-dev].<domain>` → `beacons[-dev].<domain>`). **If `baseUrl` is not a `feed` host nothing derives and beacons are disabled** — the SDK then logs one `console.warn` naming the host and emits a non-fatal [`warning`](#player-events) event carrying the same sentence. Recovery: pass `{ endpoint: 'https://beacons[-dev].<domain>' }`. Pass `false` to opt out deliberately (no warning).                            |
@@ -276,10 +277,11 @@ don't need to set any of the live or ABR knobs:
   on its own (its live‑sync only ever corrects being _behind_), so the stutter
   would otherwise persist for the rest of the session. Live only: VOD seeks are
   untouched, and the clamp stands down while chasing is suspended on a stale
-  playlist (there is no live edge left to protect at that point). On the custom
-  control bar the bar's right end **is** the target, so the thumb reads full at
-  the live edge. Bring‑your‑own‑player (Mode B) owns its own seek UI and needs
-  the equivalent clamp itself.
+  playlist (there is no live edge left to protect at that point). The custom
+  control bar hides its seek bar on a live stream (the Go‑live button and
+  `seekToLive()` are the way back to the edge); on VOD the bar covers the full
+  duration. Bring‑your‑own‑player (Mode B) owns its own seek UI and needs the
+  equivalent clamp itself.
 - **Audio‑hole bridge**: `maxBufferHole` is raised to **0.5 s** so the ~0.45 s
   audio "remainder" gap at each segment boundary is bridged as a sub‑perceptible
   hitch instead of a rebuffer.
@@ -392,7 +394,8 @@ Notes:
 
 The managed player ships a built-in, fully **skinnable** control bar. By default
 (`controls: 'custom'`) it wraps your `<video>` in a `.havik-player` container and
-renders the Oddin-branded UI: a center play/overlay, a seek bar, play/pause,
+renders the Oddin-branded UI: a center play/overlay, a seek bar (VOD only; a
+live stream shows none, see below), play/pause,
 volume, a live badge + go-live, quality / audio / subtitle menus,
 Picture-in-Picture, fullscreen, a buffering spinner, and **branded status cards**
 for the stopped/pre-play states: _ended_ ("This stream has ended"), _fatal
@@ -740,8 +743,9 @@ if (next.notModified) {
 function watchStatus(opts: WatchStatusOptions): StatusWatcher;
 ```
 
-Polls a single match's live status and fires `onChange` on transitions (and once on
-first read). Returns a `StatusWatcher` with `stop()`. For a **push** channel (no
+Polls a single match's live status and fires `onChange` once on first read and then
+on every change of the status, the teams (a logo resolved later) or the planned
+start; unchanged polls stay silent. Returns a `StatusWatcher` with `stop()`. For a **push** channel (no
 polling) use [`subscribeLiveState`](#subscribelivestate) instead; `watchStatus` is the
 zero-dependency polling alternative when the SSE endpoint isn't available.
 
@@ -759,14 +763,14 @@ const watcher = watchStatus({
 
 #### `WatchStatusOptions`
 
-| Option       | Type                                    | Default | Description                                |
-| ------------ | --------------------------------------- | ------- | ------------------------------------------ |
-| `baseUrl`    | `string`                                | —       | **Required.**                              |
-| `matchUrn`   | `string`                                | —       | **Required.**                              |
-| `credential` | [`CredentialSource`](#credentialsource) | —       | **Required.**                              |
-| `onChange`   | `(status: MatchStatus) => void`         | —       | **Required.** Fired on status transitions. |
-| `onError`    | `(err: PlaybackError) => void`          | —       | Fired on a poll error; polling continues.  |
-| `intervalMs` | `number`                                | `10000` | Poll interval (floored at `2000`).         |
+| Option       | Type                                    | Default | Description                                                                   |
+| ------------ | --------------------------------------- | ------- | ----------------------------------------------------------------------------- |
+| `baseUrl`    | `string`                                | —       | **Required.**                                                                 |
+| `matchUrn`   | `string`                                | —       | **Required.**                                                                 |
+| `credential` | [`CredentialSource`](#credentialsource) | —       | **Required.**                                                                 |
+| `onChange`   | `(status: MatchStatus) => void`         | —       | **Required.** Fired on first read, then on any status, teams or start change. |
+| `onError`    | `(err: PlaybackError) => void`          | —       | Fired on a poll error; polling continues.                                     |
+| `intervalMs` | `number`                                | `10000` | Poll interval (floored at `2000`).                                            |
 
 <a id="live-state-sse"></a>
 
@@ -783,12 +787,13 @@ the instant a match starts, without polling `/v1/playback`, and to detect
 end-of-stream instantly; BYO players can use it directly. `state` mirrors the
 `/v1/playback` outcome ladder:
 
-| `state`    | meaning                       | maps to `/v1/playback` |
-| ---------- | ----------------------------- | ---------------------- |
-| `live`     | serveable now, so play        | `200 OK`               |
-| `upcoming` | scheduled, not serving yet    | `425 Too Early`        |
-| `ended`    | was live; media stopped       | `503`                  |
-| `gone`     | ended past the catchup window | `410 Gone`             |
+| `state`    | meaning                                                                          | maps to `/v1/playback`                |
+| ---------- | -------------------------------------------------------------------------------- | ------------------------------------- |
+| `live`     | serveable now, so play                                                           | `200 OK`                              |
+| `upcoming` | scheduled, not serving yet                                                       | `425 Too Early` (with `liveStartsAt`) |
+| `pending`  | kickoff passed, stream being packaged — `live` follows within seconds to minutes | `425 Too Early` (no `liveStartsAt`)   |
+| `ended`    | was live; media stopped                                                          | `503`                                 |
+| `gone`     | ended past the catchup window                                                    | `410 Gone`                            |
 
 An `ended` event also carries a `reason`: `'interrupted'` (the match is still
 running; only its stream dropped, so a BYO player should show "reconnecting"
@@ -1112,7 +1117,7 @@ type CredentialSource = Credential | (() => Credential | Promise<Credential>);
 
 <a id="catalogmatch"></a>
 
-#### `Catalog`, `CatalogTournament`, `CatalogMatch`
+#### `Catalog`, `CatalogTournament`, `CatalogMatch`, `CatalogTeam`
 
 ```ts
 interface Catalog {
@@ -1140,13 +1145,37 @@ interface CatalogMatch {
   tournamentUrn: string;
   tournamentName: string;
   sport: string;
+  // The two sides, home first. Absent when no usable team survives parsing:
+  // the server sent no `teams` (an older havik-streams), or every entry
+  // lacked both a URN and a name. A team with a URN but no name IS kept.
+  // `matchName` stays the display string; this is its structured form.
+  teams?: CatalogTeam[];
+}
+interface CatalogTeam {
+  urn: string; // competitor URN, e.g. "od:competitor:26406"; "" if the server sent a name only
+  name: string;
+  isHome: boolean;
+  // An https image URL for the team logo, present only when the deployment
+  // resolves logos and this team has one (most do). Can still fail to load —
+  // always render a fallback for a missing or broken image. Logos are ~150 px
+  // on the long side. Allow cdn.oddin.gg (and cdn.runestone.gg) in img-src.
+  logoUrl?: string;
 }
 ```
 
+Parsing is tolerant: a non-array `teams` is ignored, entries with neither a
+URN nor a name are dropped, `isHome` is `true` only for a literal `true`, and a
+`logoUrl` that is not an absolute `https:` URL is dropped (an `http:` image is
+mixed content on an https page).
+
 #### `MatchStatus`, `MatchLiveStatus`
 
+`pending` is "kickoff has passed, the stream is being packaged": not playable
+yet, `live` expected within seconds to minutes. Unknown values still collapse to
+`upcoming` with the verbatim value in `statusRaw`.
+
 ```ts
-type MatchLiveStatus = 'upcoming' | 'live' | 'ended';
+type MatchLiveStatus = 'upcoming' | 'pending' | 'live' | 'ended';
 interface MatchStatus {
   matchUrn: string;
   matchName?: string;
@@ -1154,6 +1183,9 @@ interface MatchStatus {
   // The server's status string verbatim — see CatalogMatch.statusRaw.
   statusRaw?: string;
   datePlannedStart?: string;
+  // The teams as of this report (see CatalogTeam). watchStatus fires again
+  // when they change, so a logo resolved later is re-reported.
+  teams?: CatalogTeam[];
 }
 ```
 

package/embed/index.html

@@ -28,7 +28,7 @@
            beacons endpoint can be derived and QoE analytics is silently off.
            `analytics` is honoured from the injected config only, never the query.
     -->
-    <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.9.3/dist/havik-player.global.js" integrity="sha384-ucOZXRA7PYaCtY+Oj86b+BxFAiYADRwamwq1UvdjnJjmdF0uc4k6BZN08hCMDEG9" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.11.0/dist/havik-player.global.js" integrity="sha384-xQ2Ld/ji10d1Gd8JkmSFDHZpq08KH7ZcUI5CVNoSMmVhPs1tQ/xXf2JJBzIfDqxp" crossorigin="anonymous"></script>
     <script>
       HavikPlayer.bootEmbed();
     </script>

package/examples/vanilla.html

@@ -12,7 +12,7 @@
          shipped in each npm release is pinned to that release with Subresource
          Integrity, injected at publish time (scripts/inject-sri.mjs). In
          production, always use a pinned + SRI'd tag like the released copy. -->
-    <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.9.3/dist/havik-player.global.js" integrity="sha384-ucOZXRA7PYaCtY+Oj86b+BxFAiYADRwamwq1UvdjnJjmdF0uc4k6BZN08hCMDEG9" crossorigin="anonymous"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.11.0/dist/havik-player.global.js" integrity="sha384-xQ2Ld/ji10d1Gd8JkmSFDHZpq08KH7ZcUI5CVNoSMmVhPs1tQ/xXf2JJBzIfDqxp" crossorigin="anonymous"></script>
     <script>
       (async () => {
         const player = await HavikPlayer.createPlayer({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oddin-gg/havik-player",
-  "version": "2.9.3",
+  "version": "2.11.0",
   "description": "Havik HTML5 player SDK — LL-HLS + DRM playback for Oddin live streams (managed, bring-your-own-player, and iframe-embed modes).",
   "type": "module",
   "sideEffects": false,
@@ -77,6 +77,9 @@
     "sbom": "npx --yes @cyclonedx/cyclonedx-npm@2 --omit dev --output-file sbom.json",
     "prepack": "npm run build",
     "test:localqoe": "playwright test -c localqoe/playwright.config.ts",
+    "test:liveedge": "playwright test -c localqoe/liveedge.config.ts",
+    "test:drmlive": "playwright test -c localqoe/drmlive.config.ts",
+    "localqoe:pick-live": "node localqoe/drmlive-pick-live.mjs",
     "localqoe:media": "bash localqoe/make-media.sh && bash localqoe/make-live-media.sh",
     "test:blackhole": "npm run build:global && playwright test -c blackhole/playwright.config.ts",
     "blackhole:serve": "npm run build:global && node blackhole/server.mjs"