Skip to content

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 ​

ts
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:

ts
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:

ts
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.

ts
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 MediaKeys while 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 ​

SettingManaged playerWhy
lowLatencyModetrue on LL-HLS streamsLoads partial segments
liveSyncDuration3 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
liveMaxLatencyDurationtarget + 9, at least 12 secondsPast this, the player jumps back to the target
maxLiveSyncPlaybackRate1.5Catches 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 ​

SettingManaged playerWhy
maxBufferHole0.5Our audio has gaps of about 0.45 s at segment boundaries
maxStarvationDelayhalf the initial latency targetABR must decide while there is still media to play
maxLoadingDelaythe initial latency target, 1 to 4A load that takes the whole buffer is already too slow
abrEwmaFastLivehalf the target, 1 to 3The estimate has to react inside the buffer you have
backBufferLength90Keeps memory flat on long sessions
capLevelToPlayerSizefalseThe SDK caps to the box itself, with headroom below 2× DPR
enableWorkerfalse on LL-HLS streamshls.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:

ts
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.

ts
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 teams as optional. Servers older than havik-streams 0.10 send none.
  • Always render a fallback, such as initials on a coloured disc. A logoUrl can be absent, and the CDN does not have every file, so an image can fail to load.
  • Logos are https URLs on cdn.oddin.gg. Allow that host, and cdn.runestone.gg, in your CSP img-src. The SDK drops any logo that is not an absolute https URL.

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.

ISC licensed. Bundles hls.js (Apache-2.0).