@oddin-gg/havik-player 2.19.0 → 2.21.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.
- package/README.md +12 -10
- package/dist/havik-player.global.js +18 -18
- package/dist/havik-player.global.js.map +1 -1
- package/dist/index.cjs +3 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +14 -2
- package/dist/index.d.ts +14 -2
- package/dist/index.js +464 -410
- package/dist/index.js.map +1 -1
- package/docs/API.md +70 -39
- package/embed/index.html +1 -1
- package/examples/vanilla.html +1 -1
- package/package.json +1 -1
package/docs/API.md
CHANGED
|
@@ -198,7 +198,7 @@ function createPlayer(opts: CreatePlayerOptions): Promise<Player>;
|
|
|
198
198
|
|
|
199
199
|
Resolves to a [`Player`](#player) as soon as the stream is attached (or armed, when
|
|
200
200
|
`waitForLive` is set and the match is still upcoming). Terminal errors during the
|
|
201
|
-
initial resolution (e.g. `NOT_FOUND`, `GONE`, `UNAUTHORIZED`) reject the promise; the
|
|
201
|
+
initial resolution (e.g. `NOT_FOUND`, `GEO_DENIED`, `GONE`, `UNAUTHORIZED`) reject the promise; the
|
|
202
202
|
live wait itself never blocks the promise and is surfaced through `'waiting'` events.
|
|
203
203
|
|
|
204
204
|
```ts
|
|
@@ -450,8 +450,14 @@ Picture-in-Picture, fullscreen, a buffering spinner, and **branded status cards*
|
|
|
450
450
|
for the stopped/pre-play states: _ended_ ("This stream has ended"), _fatal
|
|
451
451
|
error_ (message + Retry when retryable), _pre-play_ (poster + play CTA), and
|
|
452
452
|
_armed-waiting_ ("Starting soon…"), so a finished or failed stream never leaves
|
|
453
|
-
a frozen frame behind a dead play button.
|
|
454
|
-
|
|
453
|
+
a frozen frame behind a dead play button. A `GEO_DENIED` error (the match is
|
|
454
|
+
booked for your key but not playable in the viewer's country) gets its own copy,
|
|
455
|
+
"This match isn't available in your country (RU)", naming the country the server
|
|
456
|
+
saw, and no Retry button: a retry would be refused again. A `DRM_DEVICE_REVOKED` error
|
|
457
|
+
(the license server refuses this device's DRM client) likewise gets "This device can't
|
|
458
|
+
play protected video" and no Retry. The cards pick up `theme.logoUrl` and
|
|
459
|
+
the theme colors; customise the copy with `endedMessage`/`interruptedMessage`/`errorMessage`
|
|
460
|
+
(an `errorMessage` replaces the `GEO_DENIED` and `DRM_DEVICE_REVOKED` copy too), or set
|
|
455
461
|
`statusOverlays: false` to drive your own end/error UI from the player events.
|
|
456
462
|
It auto-hides during playback, supports keyboard shortcuts (space/`k` play-pause,
|
|
457
463
|
`m` mute, `f` fullscreen, `c` captions, `l` go-live, arrows seek/volume), and is
|
|
@@ -866,14 +872,14 @@ const watcher = watchStatus({
|
|
|
866
872
|
|
|
867
873
|
#### `WatchStatusOptions`
|
|
868
874
|
|
|
869
|
-
| Option | Type | Default | Description
|
|
870
|
-
| ------------ | --------------------------------------- | ------- |
|
|
871
|
-
| `baseUrl` | `string` | — | **Required.**
|
|
872
|
-
| `matchUrn` | `string` | — | **Required.**
|
|
873
|
-
| `credential` | [`CredentialSource`](#credentialsource) | — | **Required.**
|
|
874
|
-
| `onChange` | `(status: MatchStatus) => void` | — | **Required.** Fired on first read, then on any status, teams or start change.
|
|
875
|
-
| `onError` | `(err: PlaybackError) => void` | — | Fired on a poll error; polling continues, except on `NOT_FOUND`, `GONE` or `INVALID_URN`: the watcher stops itself and this is its last call. |
|
|
876
|
-
| `intervalMs` | `number` | `10000` | Poll interval (floored at `2000`).
|
|
875
|
+
| Option | Type | Default | Description |
|
|
876
|
+
| ------------ | --------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
877
|
+
| `baseUrl` | `string` | — | **Required.** |
|
|
878
|
+
| `matchUrn` | `string` | — | **Required.** |
|
|
879
|
+
| `credential` | [`CredentialSource`](#credentialsource) | — | **Required.** |
|
|
880
|
+
| `onChange` | `(status: MatchStatus) => void` | — | **Required.** Fired on first read, then on any status, teams or start change. |
|
|
881
|
+
| `onError` | `(err: PlaybackError) => void` | — | Fired on a poll error; polling continues, except on `NOT_FOUND`, `GEO_DENIED`, `GONE` or `INVALID_URN`: the watcher stops itself and this is its last call. |
|
|
882
|
+
| `intervalMs` | `number` | `10000` | Poll interval (floored at `2000`). |
|
|
877
883
|
|
|
878
884
|
<a id="live-state-sse"></a>
|
|
879
885
|
|
|
@@ -1103,7 +1109,7 @@ messages from any origin and posts events with target origin `*`.
|
|
|
1103
1109
|
{ type: 'oddin:tracks'; quality: QualityLevel[]; audio: AudioTrackInfo[]; text: TextTrackInfo[] }
|
|
1104
1110
|
{ type: 'oddin:qualitychange'; index } | { type: 'oddin:audiotrackchange'; id } | { type: 'oddin:texttrackchange'; id }
|
|
1105
1111
|
{ type: 'oddin:stats'; droppedFrames; latencySeconds?; bandwidthKbps?; levelHeight?; lowLatency?; isLive?; atLiveEdge? }
|
|
1106
|
-
{ type: 'oddin:error'; code: PlaybackErrorCode; message: string }
|
|
1112
|
+
{ type: 'oddin:error'; code: PlaybackErrorCode; message: string; country?: string } // country: set with GEO_DENIED
|
|
1107
1113
|
```
|
|
1108
1114
|
|
|
1109
1115
|
The `oddin:ready` event carries the embed page's `protocol` version; `mountEmbed` warns on a
|
|
@@ -1128,25 +1134,29 @@ class PlaybackError extends Error {
|
|
|
1128
1134
|
readonly httpStatus: number; // 0 for NETWORK / ABORTED; see the table notes for TIMEOUT / DRM_CLIENT
|
|
1129
1135
|
readonly retryAfterMs?: number; // set for TOO_EARLY / RATE_LIMITED / UNAVAILABLE
|
|
1130
1136
|
readonly liveStartsAtMs?: number; // epoch ms; set for TOO_EARLY when the server included `liveStartsAt`
|
|
1137
|
+
readonly country?: string; // upper-case ISO 3166-1 alpha-2; set for GEO_DENIED
|
|
1138
|
+
readonly serverCode?: string; // the server's own code, when the body carried one (e.g. 'cdm_revoked', 'license_refused')
|
|
1131
1139
|
readonly requestId?: string; // server correlation id, when present
|
|
1132
1140
|
}
|
|
1133
1141
|
```
|
|
1134
1142
|
|
|
1135
|
-
| `code`
|
|
1136
|
-
|
|
|
1137
|
-
| `INVALID_URN`
|
|
1138
|
-
| `NOT_FOUND`
|
|
1139
|
-
| `
|
|
1140
|
-
| `
|
|
1141
|
-
| `
|
|
1142
|
-
| `
|
|
1143
|
-
| `
|
|
1144
|
-
| `
|
|
1145
|
-
| `
|
|
1146
|
-
| `
|
|
1147
|
-
| `
|
|
1148
|
-
| `
|
|
1149
|
-
| `
|
|
1143
|
+
| `code` | HTTP | Meaning | Retryable |
|
|
1144
|
+
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------- |
|
|
1145
|
+
| `INVALID_URN` | 400 | Malformed match URN. | No |
|
|
1146
|
+
| `NOT_FOUND` | 404 | Unknown match **or** not entitled (indistinguishable by design). | No |
|
|
1147
|
+
| `GEO_DENIED` | 451 | The match is booked for your key, but a grant's country list excludes the viewer's country; `country` names it. A server without the 451 answers `404 NOT_FOUND` for the same case. | No |
|
|
1148
|
+
| `GONE` | 410 | Ended and past the catch‑up window. | No |
|
|
1149
|
+
| `TOO_EARLY` | 425 | Upcoming; not live yet. | Yes (via `waitForLive`) |
|
|
1150
|
+
| `UNAVAILABLE` | 503 | Should be live; origin warming up. | Yes |
|
|
1151
|
+
| `UNAUTHORIZED` | 401 | Bad/absent api‑key. | No |
|
|
1152
|
+
| `FORBIDDEN` | 403 | Origin not allowed, DRM signature rejected, or a license refused for a reason the server did not name (`serverCode: 'license_refused'`); a real server 403. | No⁴ |
|
|
1153
|
+
| `DRM_DEVICE_REVOKED` | 403 | The license server refuses this device's DRM client outright (a revoked Widevine certificate); the license 403 body carries `cdm_revoked`. The device is the problem, not the match, the key or the network. | No³ |
|
|
1154
|
+
| `DRM_CLIENT` | (lic.)² | Client‑side DRM failure: no key system usable on this platform, a CDM/EME error, or license delivery failed without a server denial. | Sometimes² |
|
|
1155
|
+
| `RATE_LIMITED` | 429 | Per‑client request limit. | Back off |
|
|
1156
|
+
| `INTERNAL` | 5xx | Unexpected server/SDK error. | No |
|
|
1157
|
+
| `NETWORK` | 0 | The network request failed (offline, CORS, DNS). | Yes (in the live‑poll loop) |
|
|
1158
|
+
| `TIMEOUT` | (last)¹ | `waitForLive` exceeded `timeoutMs`. | No |
|
|
1159
|
+
| `ABORTED` | 0 | Cancelled via `AbortSignal`. | No |
|
|
1150
1160
|
|
|
1151
1161
|
¹ `TIMEOUT.httpStatus` carries the status of the last error it was waiting on, typically
|
|
1152
1162
|
`425` while waiting for an upcoming match, `503` while an origin warms up, or `0` if the
|
|
@@ -1161,6 +1171,24 @@ play DRM. The built-in error card still offers Retry (it re-resolves and re-atta
|
|
|
1161
1171
|
which can recover a transient license failure); an unsupported device will simply fail
|
|
1162
1172
|
the same way again.
|
|
1163
1173
|
|
|
1174
|
+
³ `DRM_DEVICE_REVOKED` is read off the body of a license `403`: the DRM proxy answers
|
|
1175
|
+
`{"error":"cdm_revoked"}` when the license server refuses the device's DRM client
|
|
1176
|
+
(Widevine in practice; the FairPlay path reads the same body). Any other license `403`
|
|
1177
|
+
body (`license_refused`, a WAF page, nothing) stays `FORBIDDEN`; `serverCode` carries the
|
|
1178
|
+
body's code either way. It is terminal for that device: the built-in error card shows
|
|
1179
|
+
"This device can't play protected video" with no Retry, and the lapsed-URL recovery below
|
|
1180
|
+
is not spent on it. On the hls.js engine the body is read off the XHR hls.js attaches to
|
|
1181
|
+
its error; a caller-supplied `hlsConfig.licenseXhrSetup` does not change that. Tell the
|
|
1182
|
+
viewer to use another device or an up-to-date browser; there is nothing to fix on your side.
|
|
1183
|
+
|
|
1184
|
+
⁴ "Retryable" is whether a retry can succeed, and a `FORBIDDEN` request answered the
|
|
1185
|
+
same way will not. The built-in error card still offers Retry on `FORBIDDEN` (as it does on
|
|
1186
|
+
`DRM_CLIENT`), because one license `403` shape is recoverable: a signed URL whose `exp`
|
|
1187
|
+
lapsed is refreshed by the re-resolve Retry performs (the lapsed-URL handling below). A
|
|
1188
|
+
`403` with `serverCode: 'license_refused'` keeps that card unchanged; only
|
|
1189
|
+
`DRM_DEVICE_REVOKED` drops the Retry button, since the server named a cause no retry
|
|
1190
|
+
changes.
|
|
1191
|
+
|
|
1164
1192
|
A lapsed signed license URL is handled before it reaches you. The `licenseRefreshMs`
|
|
1165
1193
|
timer cannot run while the browser has the tab frozen (a long-hidden tab, a machine
|
|
1166
1194
|
that slept), so the URL the player holds can carry an `exp` that has already passed.
|
|
@@ -1181,6 +1209,7 @@ try {
|
|
|
1181
1209
|
await resolveStream({ baseUrl, matchUrn, credential });
|
|
1182
1210
|
} catch (e) {
|
|
1183
1211
|
if (e instanceof PlaybackError && e.code === 'NOT_FOUND') showUnavailable();
|
|
1212
|
+
if (e instanceof PlaybackError && e.code === 'GEO_DENIED') showBlockedIn(e.country); // e.g. "RU"
|
|
1184
1213
|
}
|
|
1185
1214
|
```
|
|
1186
1215
|
|
|
@@ -1463,18 +1492,20 @@ whose `baseUrl` you serve.
|
|
|
1463
1492
|
|
|
1464
1493
|
## Troubleshooting
|
|
1465
1494
|
|
|
1466
|
-
| Symptom | Likely cause
|
|
1467
|
-
| ---------------------------------------------------------- |
|
|
1468
|
-
| `NETWORK` error on every call; preflight fails in devtools | Your origin isn't on the key's allowed‑origins / DRM CORS allow‑list. See [Onboarding](#onboarding--cors).
|
|
1469
|
-
| `UNAUTHORIZED` (401) | Wrong/expired api‑key, or wrong `baseUrl` environment (test vs prod key).
|
|
1470
|
-
| `FORBIDDEN` (403) on license requests | The license URL was modified, or a different api‑key was used for the license than for playback. POST the URL verbatim with the same key.
|
|
1471
|
-
| `
|
|
1472
|
-
| `
|
|
1473
|
-
|
|
|
1474
|
-
|
|
|
1475
|
-
|
|
|
1476
|
-
|
|
|
1477
|
-
| Black video
|
|
1495
|
+
| Symptom | Likely cause |
|
|
1496
|
+
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
1497
|
+
| `NETWORK` error on every call; preflight fails in devtools | Your origin isn't on the key's allowed‑origins / DRM CORS allow‑list. See [Onboarding](#onboarding--cors). |
|
|
1498
|
+
| `UNAUTHORIZED` (401) | Wrong/expired api‑key, or wrong `baseUrl` environment (test vs prod key). |
|
|
1499
|
+
| `FORBIDDEN` (403) on license requests | The license URL was modified, or a different api‑key was used for the license than for playback. POST the URL verbatim with the same key. With `serverCode: 'license_refused'`, the license server refused the request for a reason it did not name; include `requestId` when asking support. |
|
|
1500
|
+
| `DRM_DEVICE_REVOKED` (403) on license requests | The license server refuses this device's DRM client (a revoked Widevine certificate, typically an old browser build or a modified device). Nothing on your side or ours changes it; the viewer needs another device or an up-to-date browser. The built-in card says so and offers no Retry. |
|
|
1501
|
+
| `DRM_CLIENT` | The device/browser can't play this DRM (no usable key system, CDM/EME error), or license delivery failed without a server denial. Check the console for the EME/CDM detail; call `detectDrmSupport()` to pre‑flight and message the viewer. |
|
|
1502
|
+
| `NOT_FOUND` (404) for a match you can see | The key isn't entitled to that tournament (404 is intentionally indistinguishable from "unknown"). |
|
|
1503
|
+
| `GEO_DENIED` (451) for a match you can see | The key's grant for that match carries a country list that excludes the viewer's country (`e.country`). The viewer sees a card naming the country; the listings never show such a match to that viewer, so this only happens on a direct URN. |
|
|
1504
|
+
| Player stays in `waiting` forever | The match hasn't gone live yet; the SDK is polling. Set `waitForLive.timeoutMs` to bound it. |
|
|
1505
|
+
| Autoplay doesn't start | Browser sound policy: set `muted: true` for autoplay, or start playback from a user gesture. |
|
|
1506
|
+
| Black video on Safari with DRM | Check the console for an EME/CDM error; verify the origin is on the DRM CORS allow‑list. On very old Safari the native fallback plays only OS‑trusted passthrough. |
|
|
1507
|
+
| Black video in Chrome/Firefox/Edge **on iOS** | iOS has no Widevine CDM, and FairPlay availability outside Safari varies by WebKit build. Call `detectDrmSupport()`: on `no-cdm`, tell the viewer this browser can't play protected streams. |
|
|
1508
|
+
| Black video, `levelHeight`/`droppedFrames` stuck | Check the browser console for an EME/CDM error and verify DRM CORS onboarding. |
|
|
1478
1509
|
|
|
1479
1510
|
Include `PlaybackError.requestId` (when present) when contacting support; it correlates
|
|
1480
1511
|
to server‑side logs.
|
package/embed/index.html
CHANGED
|
@@ -28,7 +28,7 @@
|
|
|
28
28
|
beacons endpoint can be derived and QoE analytics is silently off.
|
|
29
29
|
`analytics` is honoured from the injected config only, never the query.
|
|
30
30
|
-->
|
|
31
|
-
<script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.
|
|
31
|
+
<script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.21.0/dist/havik-player.global.js" integrity="sha384-KGq+XypxWv0FVoUTM6e/yelF8vOuAmx2dJbIj3E/Ee2E6Ky8bTHorPnRapaKqfY+" crossorigin="anonymous"></script>
|
|
32
32
|
<script>
|
|
33
33
|
HavikPlayer.bootEmbed();
|
|
34
34
|
</script>
|
package/examples/vanilla.html
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
shipped in each npm release is pinned to that release with Subresource
|
|
13
13
|
Integrity, injected at publish time (scripts/inject-sri.mjs). In
|
|
14
14
|
production, always use a pinned + SRI'd tag like the released copy. -->
|
|
15
|
-
<script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.
|
|
15
|
+
<script src="https://cdn.jsdelivr.net/npm/@oddin-gg/havik-player@2.21.0/dist/havik-player.global.js" integrity="sha384-KGq+XypxWv0FVoUTM6e/yelF8vOuAmx2dJbIj3E/Ee2E6Ky8bTHorPnRapaKqfY+" crossorigin="anonymous"></script>
|
|
16
16
|
<script>
|
|
17
17
|
(async () => {
|
|
18
18
|
const player = await HavikPlayer.createPlayer({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oddin-gg/havik-player",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.21.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,
|