@oddin-gg/havik-player 2.6.4 → 2.8.0

package/README.md

@@ -61,7 +61,7 @@ import { createPlayer } from '@oddin-gg/havik-player';
 
 const player = await createPlayer({
   video: document.querySelector('video')!,
-  baseUrl: 'https://feed-dev.oddin-video.gg',
+  env: 'integration', // or 'production'
   matchUrn: 'od:match:1234',
   credential: { apiKey: 'pk_test_…' },
   autoplay: true,
@@ -81,6 +81,39 @@ player.destroy();
 The managed player handles `425 TOO_EARLY` retries (honoring `Retry-After`),
 buffering recovery, and silent DRM **license-URL refresh** for long sessions.
 
+### Choosing an environment
+
+`env` names the stack: `integration` is the shared pre-production environment,
+`production` is the production one. They are separate deployments, not
+aliases. Prefer `env` over a hand-written `baseUrl`. The API host is then
+correct by construction, and so is every host derived from it, including the
+QoE beacons endpoint.
+
+Pass `baseUrl` instead when the named environments do not cover your
+deployment:
+
+- your own CDN or gateway in front of the streams API
+- the CN plane, whose host is not under this domain
+- a pinned build that has to outlive a domain change
+
+`baseUrl` is not deprecated and is not going away. Pass exactly one of the
+two. In TypeScript, passing both or neither is a compile error. In JavaScript
+it throws at `createPlayer`, because the two disagreeing is the
+misconfiguration worth refusing.
+
+Modes B and C still take a `baseUrl`. Use `baseUrlForEnv` there rather than
+copying a hostname into your own config:
+
+```ts
+import { baseUrlForEnv, resolveStream } from '@oddin-gg/havik-player';
+
+const stream = await resolveStream({
+  baseUrl: baseUrlForEnv('production'),
+  matchUrn: 'od:match:1234',
+  credential: { apiKey: 'pk_live_…' },
+});
+```
+
 ### Controls & skinning
 
 By default, Mode A renders a **branded, fully skinnable control bar**. It covers
@@ -279,8 +312,15 @@ are correlated with CDN logs via a server-minted CMCD session id (`sid`). The
 `sid` lives **only in JS memory**, never in storage or cookies, and dies with the
 player. Opt out or
 redirect with the `analytics` option on `createPlayer`
-(`analytics: false | { endpoint?: string }`); without a server-minted `sid` the
-emitter is inert.
+(`analytics: false | { endpoint?: string; idleMs?: number }`); without a
+server-minted `sid` the emitter is inert.
+
+A session closes itself
+(`END_REASON_IDLE`) after `idleMs` of sitting paused. The default is 10
+minutes, and `0` disables it. The same close happens when the page was
+suspended (OS sleep, a frozen tab) for that long. The suspension gap never
+goes below five minutes, whatever `idleMs` is. The next `play()` reloads the
+stream as a fresh session.
 
 ## Privacy