Bring your own player
Mode B: you keep your own player stack, whether that is hls.js, Shaka, or a wrapper you already ship. The SDK does the Havik-specific work: authenticated stream resolution, DRM license wiring and live-state discovery.
Resolve a stream
import { resolveStream } from '@oddin-gg/havik-player';
const baseUrl = 'https://feed-dev.oddin-video.gg';
const matchUrn = 'od:match:1234';
const cred = { apiKey: 'pk_test_…' };
const stream = await resolveStream({
baseUrl,
matchUrn,
credential: cred,
waitForLive: true,
});
// stream = { manifestUrl, drmEnabled, drm: { widevine: { licenseUrl } }, … }Feed stream.manifestUrl to your player. For DRM streams, wire the license request yourself:
import { licenseRequestHeaders } from '@oddin-gg/havik-player';
const headers = licenseRequestHeaders(stream, cred);
// { 'x-api-key', 'X-Match-Urn', 'X-Device-Id', 'Content-Type' }With hls.js, attach them in licenseXhrSetup, not xhrSetup. EME license requests route through licenseXhrSetup. Open the request against a variable that holds the current license URL, so a refresh takes effect:
let licenseUrl = stream.drm.widevine.licenseUrl;
const hls = new Hls({
emeEnabled: true,
drmSystems: { 'com.widevine.alpha': { licenseUrl } },
licenseXhrSetup: (xhr) => {
// hls.js keeps the URL it was created with. Open against the current one.
xhr.open('POST', licenseUrl, true);
for (const [k, v] of Object.entries(headers)) xhr.setRequestHeader(k, v);
},
});Post the license URL unchanged
POST to drm.widevine.licenseUrl verbatim: its signed query string is the token. Never rewrite or normalize the URL, and use the same api-key on playback and license requests, or the license request 403s.
Refresh the license URL
The signed license URL is valid for 10 minutes. The license that the CDM gets with it is valid for 4 hours by default. Your player makes a new license request at start, and again whenever it rebuilds its DRM session, for example after an error recovery. A request with an expired URL gets 403.
The managed player refreshes the URL every 8 minutes. In Mode B, do it yourself: resolve again and swap the URL. Don't reload the manifest or the player.
const timer = setInterval(
async () => {
try {
const fresh = await resolveStream({ baseUrl, matchUrn, credential: cred });
if (fresh.drm?.widevine?.licenseUrl) licenseUrl = fresh.drm.widevine.licenseUrl;
} catch {
// Keep the current URL. A 410 or 503 here means the stream ended or dropped.
}
},
8 * 60 * 1000,
);
// clearInterval(timer) when playback stops.On Safari, swap drm.fairplay.licenseUrl in the same way. A refresh can't extend a license that the CDM already holds. See License URL lifetime for the details.
Live-edge behavior is yours
The managed player's latency target, drift ceiling and over-seek clamp don't come with Mode B, because your player owns seeking. Clamp any seek that lands closer to live than your sync target. Without that clamp, a scrub to the far right strands playback on the bleeding edge, where the newest parts aren't reliably published yet. See Low-latency & ABR for what the managed mode does, as a spec to replicate.
Tuning your own player
The managed player carries tuning that we measured on Havik streams. Your player gets none of it. The values below are the managed player's hls.js settings, as a starting point. Measure on your own player before you ship.
Startup time
On a DRM stream, a default player does its startup steps one after the other: DRM setup, then the license, then the first media. Run them in parallel:
- Start DRM setup at load. Request key-system access and create
MediaKeyswhile the master playlist loads. You know the key system from the playback response, so you don't need the manifest for this. - Download media while the first license loads. hls.js doesn't request an encrypted segment until its key is usable. A segment needs the key only to decrypt, not to download. On our integration stream, this cut manifest-to-play from 1.5 to 6.5 seconds down to about 1.1 seconds.
- Start at a modest quality. A high first rendition stalls on a weak link before ABR can drop. The managed player seeds the bandwidth estimate at 1 Mbps (
abrEwmaDefaultEstimate: 1_000_000) and ramps up within seconds.
Latency
| Setting | Managed player | Why |
|---|---|---|
lowLatencyMode | true on LL-HLS streams | Loads partial segments |
liveSyncDuration | 3 seconds, stepped up by 0.5 to 3.5 while the session's own part fetches run slow (adaptiveHoldBack) | The target distance behind live; a far viewer gets more buffer instead of a stall |
liveMaxLatencyDuration | target + 9, at least 12 seconds | Past this, the player jumps back to the target |
maxLiveSyncPlaybackRate | 1.5 | Catches up by playing faster, without a jump |
Without a catch-up rate and a ceiling, latency only grows. After each stall the player falls further behind, and we have seen 90 seconds in the field.
Buffering
| Setting | Managed player | Why |
|---|---|---|
maxBufferHole | 0.5 | Our audio has gaps of about 0.45 s at segment boundaries |
maxStarvationDelay | half the initial latency target | ABR must decide while there is still media to play |
maxLoadingDelay | the initial latency target, 1 to 4 | A load that takes the whole buffer is already too slow |
abrEwmaFastLive | half the target, 1 to 3 | The estimate has to react inside the buffer you have |
backBufferLength | 90 | Keeps memory flat on long sessions |
capLevelToPlayerSize | false | The SDK caps to the box itself, with headroom below 2× DPR |
enableWorker | false on LL-HLS streams | hls.js 1.6 fails appends of partial segments with the worker on |
With the default maxBufferHole of 0.1 seconds, the player stalls on each audio gap, every few seconds.
DRM compatibility
Some browsers report that they can decode HEVC, but Widevine then refuses encrypted HEVC. Segments download and no frame shows. Before you play, ask Widevine which codecs it plays at your robustness level, and remove the other renditions. The managed player asks for SW_SECURE_DECODE video, SW_SECURE_CRYPTO audio and the cbcs scheme.
End of stream
The playlist of an ended stream gets no #EXT-X-ENDLIST tag. It stops changing, and a default player waits for more media. Listen to the live-state events for the end. As a fallback, treat a playlist that has not advanced for about 12 seconds as ended. If the match comes back live, resolve again: the new stream often has a new manifest URL.
Discovery: catalog & status
There is no push channel for the catalog, so poll it:
import { fetchCatalog, watchStatus, subscribeLiveState } from '@oddin-gg/havik-player';
// tournaments → matches (metadata only)
const catalog = await fetchCatalog({ baseUrl, credential: cred });
// poll one match's status
const watcher = watchStatus({
baseUrl,
matchUrn,
credential: cred,
onChange: (m) => console.log(m.status),
});
// watcher.stop();For go-live and end-of-stream, subscribeLiveState exposes the same push channel (SSE) the managed player uses. See the API reference.
Teams and logos
A catalog match may carry teams, home side first. The field is optional: a server older than havik-streams 0.10 sends none, so always check for it. Each entry has a urn, a name, an isHome flag and, when the server has one, a logoUrl. Use it to build a fixture layout instead of parsing matchName.
import { fetchCatalog, flattenMatches } from '@oddin-gg/havik-player';
const catalog = await fetchCatalog({ baseUrl, credential: cred });
for (const m of flattenMatches(catalog)) {
const [home, away] = m.teams ?? [];
if (!home) continue; // no teams on this match: fall back to m.matchName
renderFixture(home.name, home.logoUrl, away?.name, away?.logoUrl);
}Three rules to follow:
- Treat
teamsas optional. Servers older than havik-streams 0.10 send none. - Always render a fallback, such as initials on a coloured disc. A
logoUrlcan be absent, and the CDN does not have every file, so an image can fail to load. - Logos are
httpsURLs oncdn.oddin.gg. Allow that host, andcdn.runestone.gg, in your CSPimg-src. The SDK drops any logo that is not an absolutehttpsURL.
watchStatus reports teams too, when the server sends it, as of the last status change. It does not report a logo that arrives later on its own. This field needs SDK 2.11.0 or later; see CatalogTeam.
Device identity
License requests carry a stable per-browser device id (X-Device-Id), generated and persisted by the SDK. getDeviceId() and clearDeviceId() expose it, which is useful for support tickets and for honoring "reset this device" flows.
When to prefer Mode A
Mode B leaves the hard parts to you: live-edge seeking policy, retry ladders, license refresh on long sessions and autoplay policy. If you aren't already committed to a player of your own, use the managed player. It does all of that, and it is still skinnable down to CSS variables.
To go one step further and drop the SDK too, see the HTTP API. You then also own the work that resolveStream and licenseRequestHeaders do.