@oddin-gg/havik-player 1.0.5 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +8 -1
  2. package/dist/havik-player.global.js +2 -2
  3. package/dist/havik-player.global.js.map +1 -1
  4. package/dist/index.cjs +2 -2
  5. package/dist/index.cjs.map +1 -1
  6. package/dist/index.d.cts +11 -0
  7. package/dist/index.d.ts +11 -0
  8. package/dist/index.js +81 -73
  9. package/dist/index.js.map +1 -1
  10. package/docs/API.md +40 -27
  11. package/embed/index.html +1 -1
  12. package/package.json +1 -1
package/docs/API.md CHANGED
@@ -202,33 +202,34 @@ player.on('error', (e) => console.error(e.code, e.httpStatus, e.message));
202
202
 
203
203
  #### `CreatePlayerOptions`
204
204
 
205
- | Option | Type | Default | Description |
206
- | --------------------- | --------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207
- | `video` | `HTMLVideoElement` | — | **Required.** The element the SDK will control. |
208
- | `baseUrl` | `string` | — | **Required.** API base URL, e.g. `https://streams.oddin.gg`. |
209
- | `matchUrn` | `string` | — | **Required.** The match to play, e.g. `od:match:1234`. |
210
- | `credential` | [`CredentialSource`](#credentialsource) | — | **Required.** Your api‑key (or a function returning one). |
211
- | `autoplay` | `boolean` | `true` | Start playback once ready. |
212
- | `muted` | `boolean` | `false` | Mute the element. Set `true` for reliable autoplay under browser sound policies. |
213
- | `controls` | `'custom' \| 'native' \| 'none'` | `'custom'` | Which controls to render. See [Controls & theming](#controls--theming). |
214
- | `theme` | [`Partial<HavikTheme>`](#haviktheme) | Oddin brand | Re-skin the custom control bar (ignored unless `controls: 'custom'`). See [Controls & theming](#controls--theming). |
215
- | `statusOverlays` | `boolean` | `true` | Branded full-bleed cards for the stopped/pre-play states (ended, fatal error, pre-play, armed-waiting) instead of a frozen frame + a dead play button. Themed via the control-bar tokens + `theme.logoUrl`. Set `false` to render your own UI from the `ended`/`error` events. Ignored unless `controls: 'custom'`. |
216
- | `endedMessage` | `string` | "This stream has ended" | Message on the end-of-stream card. |
217
- | `errorMessage` | `string` | the error's message | Message on the fatal-error card (otherwise the error's own message). |
218
- | `waitForLive` | [`WaitForLive`](#waitforlive) | — | Arm on an upcoming match and auto‑attach at go‑live. |
219
- | `lowLatency` | `'auto' \| boolean` | `'auto'` | `'auto'` lets the player decide from the manifest. |
220
- | `engine` | `'auto' \| 'hls' \| 'native'` | `'auto'` | `'auto'` picks native HLS on Safari, hls.js elsewhere. |
221
- | `userId` | `string` | — | Optional viewer id (sent as `X-User-Id` on license requests). |
222
- | `hlsConfig` | `Partial<HlsConfig>` | — | Escape hatch for advanced hls.js tuning. |
223
- | `statsIntervalMs` | `number` | `2000` | How often `'stats'` is emitted. |
224
- | `licenseRefreshMs` | `number` | `480000` (8 min) | Silent DRM license‑URL refresh interval for long sessions. `0` disables. |
225
- | `poster` | `string` | — | Poster image shown before playback starts. |
226
- | `startLevel` | `number` | `-1` | Initial rendition index (`-1` = auto). With auto, ABR starts on a conservative, sustainable rendition (~360p) and ramps up as bandwidth allows — see [Low‑latency & adaptive bitrate](#low-latency--adaptive-bitrate). |
227
- | `maxBitrate` | `number` | — | Cap ABR to renditions at/below this bitrate (bps). |
228
- | `liveLatencyTarget` | `number` | `3` | 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. |
229
- | `snapToLiveOnRefocus` | `boolean` | `true` | Snap to the live edge when a backgrounded tab is refocused while far behind. Live/LL only. |
230
- | `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. |
231
- | `eventsBaseUrl` | `string` | derived | Override the SSE endpoint base. Default: `baseUrl` with the host prefixed by `events.` (e.g. `feed.<d>` → `events.<d>`). |
205
+ | Option | Type | Default | Description |
206
+ | --------------------- | --------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
207
+ | `video` | `HTMLVideoElement` | — | **Required.** The element the SDK will control. |
208
+ | `baseUrl` | `string` | — | **Required.** API base URL, e.g. `https://streams.oddin.gg`. |
209
+ | `matchUrn` | `string` | — | **Required.** The match to play, e.g. `od:match:1234`. |
210
+ | `credential` | [`CredentialSource`](#credentialsource) | — | **Required.** Your api‑key (or a function returning one). |
211
+ | `autoplay` | `boolean` | `true` | Start playback once ready. |
212
+ | `muted` | `boolean` | `false` | Mute the element. Set `true` for reliable autoplay under browser sound policies. |
213
+ | `controls` | `'custom' \| 'native' \| 'none'` | `'custom'` | Which controls to render. See [Controls & theming](#controls--theming). |
214
+ | `theme` | [`Partial<HavikTheme>`](#haviktheme) | Oddin brand | Re-skin the custom control bar (ignored unless `controls: 'custom'`). See [Controls & theming](#controls--theming). |
215
+ | `statusOverlays` | `boolean` | `true` | Branded full-bleed cards for the stopped/pre-play states (ended, fatal error, pre-play, armed-waiting) instead of a frozen frame + a dead play button. Themed via the control-bar tokens + `theme.logoUrl`. Set `false` to render your own UI from the `ended`/`error` events. Ignored unless `controls: 'custom'`. |
216
+ | `endedMessage` | `string` | "This stream has ended" | Message on the end-of-stream card. |
217
+ | `errorMessage` | `string` | the error's message | Message on the fatal-error card (otherwise the error's own message). |
218
+ | `waitForLive` | [`WaitForLive`](#waitforlive) | — | Arm on an upcoming match and auto‑attach at go‑live. |
219
+ | `lowLatency` | `'auto' \| boolean` | `'auto'` | `'auto'` lets the player decide from the manifest. |
220
+ | `engine` | `'auto' \| 'hls' \| 'native'` | `'auto'` | `'auto'` picks native HLS on Safari, hls.js elsewhere. |
221
+ | `userId` | `string` | — | Optional viewer id (sent as `X-User-Id` on license requests). |
222
+ | `debug` | `boolean` | `false` | Turn on hls.js's internal console logging — fragment/part scheduling, ABR switches, EME key sessions and license traffic. For diagnosing a playback problem with Oddin support; leave it off in production (it logs on every fragment, and the EME lines include license request/response metadata). hls.js engine only. `hlsConfig.debug` still wins if you set both. |
223
+ | `hlsConfig` | `Partial<HlsConfig>` | — | Escape hatch for advanced hls.js tuning. |
224
+ | `statsIntervalMs` | `number` | `2000` | How often `'stats'` is emitted. |
225
+ | `licenseRefreshMs` | `number` | `480000` (8 min) | Silent DRM license‑URL refresh interval for long sessions. `0` disables. |
226
+ | `poster` | `string` | — | Poster image shown before playback starts. |
227
+ | `startLevel` | `number` | `-1` | Initial rendition index (`-1` = auto). With auto, ABR starts on a conservative, sustainable rendition (~360p) and ramps up as bandwidth allows — see [Low‑latency & adaptive bitrate](#low-latency--adaptive-bitrate). |
228
+ | `maxBitrate` | `number` | — | Cap ABR to renditions at/below this bitrate (bps). |
229
+ | `liveLatencyTarget` | `number` | `3` | 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. |
230
+ | `snapToLiveOnRefocus` | `boolean` | `true` | Snap to the live edge when a backgrounded tab is refocused while far behind. Live/LL only. |
231
+ | `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. |
232
+ | `eventsBaseUrl` | `string` | derived | Override the SSE endpoint base. Default: `baseUrl` with the host prefixed by `events.` (e.g. `feed.<d>` → `events.<d>`). |
232
233
 
233
234
  ### Low‑latency & adaptive bitrate
234
235
 
@@ -246,6 +247,18 @@ don't need to set any of the live or ABR knobs:
246
247
  internal **ceiling (~12 s, derived as `liveLatencyTarget + 9`)**. This is what
247
248
  stops latency from snowballing to tens of seconds after buffering. The ceiling
248
249
  is internal and always kept above your `liveLatencyTarget`.
250
+ - **Over‑seek clamp** — the drift ceiling's counterpart on the _near_ side. A seek
251
+ that lands closer to live than `liveLatencyTarget` is pulled back onto it, so
252
+ dragging the scrub bar to its far right means **"go live"** rather than landing
253
+ on the bleeding edge — where latency reads under a second and playback stutters
254
+ frame‑by‑frame on an empty forward buffer. hls.js can't recover from that state
255
+ on its own (its live‑sync only ever corrects being _behind_), so the stutter
256
+ would otherwise persist for the rest of the session. Live only — VOD seeks are
257
+ untouched, and the clamp stands down while chasing is suspended on a stale
258
+ playlist (there is no live edge left to protect at that point). On the custom
259
+ control bar the bar's right end **is** the target, so the thumb reads full at
260
+ the live edge. Bring‑your‑own‑player (Mode B) owns its own seek UI and needs
261
+ the equivalent clamp itself.
249
262
  - **Audio‑hole bridge** — `maxBufferHole` is raised to **0.5 s** so the ~0.45 s
250
263
  audio "remainder" gap at each segment boundary is bridged as a sub‑perceptible
251
264
  hitch instead of a rebuffer.
package/embed/index.html CHANGED
@@ -18,7 +18,7 @@
18
18
  apiKey, parentOrigin). When injected, the URL query string is IGNORED for
19
19
  security; the api-key must NOT travel in the query in production.
20
20
  -->
21
- <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@1.0.5/dist/havik-player.global.js" integrity="sha384-ZhL2TIt6Hi3Wh+YvC+t9eZywXpCATO2YFHjo0TWmf35O+SoxGy9p5pr/AqSI1UwQ" crossorigin="anonymous"></script>
21
+ <script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@1.1.0/dist/havik-player.global.js" integrity="sha384-BpHvAuoGIE+4dqbqLV3IX24RWeMcb1S8cedCn4v+Xh02hPlkXuwx6leR8ou0LQYN" crossorigin="anonymous"></script>
22
22
  <script>
23
23
  HavikPlayer.bootEmbed();
24
24
  </script>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oddin-gg/havik-player",
3
- "version": "1.0.5",
3
+ "version": "1.1.0",
4
4
  "description": "Havik HTML5 player SDK — LL-HLS + DRM playback for Oddin live streams (managed, bring-your-own-player, and iframe-embed modes).",
5
5
  "type": "module",
6
6
  "sideEffects": false,