Markdown

ott-analytics

A lightweight, framework-agnostic analytics SDK for modern OTT web players.

ott-analytics normalizes complex internal metrics from Shaka Player and Dash.js into a simple, unified data stream. It is specifically designed for monitoring Low Latency (LL-DASH) performance and live stream health.

Features

• Unified Adapter Pattern: One API for both Shaka and Dash.js.
• Low Latency First: Accurately calculates Live Edge drift and Latency to DASH (L2D) metrics.
• Plug-and-Play UI: Includes a native Web Component diagnostic overlay using Shadow DOM for total style isolation.
• Zero Dependencies: Pure TypeScript. No React, Vue, or heavy libraries required.
• Memory Safe: Built-in detach() logic to prevent memory leaks on Smart TVs.

Quick Start

1. Installation

npm install @ottbasics/ott-analytics

2. Basic Usage with Visual Overlay

Use this if you want the built-in UI for showing the analytics.

import { OTTAnalytics } from "@ottbasics/ott-analytics";

const video = document.getElementById("my-video");
const player = new shaka.Player(video);

const analytics = new OTTAnalytics({ debug: true, speedTest: { interval: 5000 } });

//If you want to enable Network Speed too (use it cautiously, e.g. interval: 10000 as it is a heavy task)
//const analytics = new OTTAnalytics({ debug: true, speedTest: { interval: 5000 } });

// Attach to the player instance
analytics.attach(player, video);

// Listen for normalized updates
analytics.onMetrics((metrics) => {
    console.log(`Latency: ${metrics.latency}s | Buffer: ${metrics.bufferLevel}s`);
});

//The parent element to which the UI overlay should be attached
const container = document.getElementById("video-container");

analytics.showOverlay(container);

Diagnostics UI

The diagnostic UI is built using native Custom Elements to ensure maximum compatibility.

• Encapsulation: Using Shadow DOM ensures your site's CSS won't break our overlay, and our styles won't leak into your application.
• Portability: The UI works automatically across all modern frameworks (React, Vue, Angular) or plain HTML without requiring specific wrappers.

Metrics Data Model

The SDK normalizes all player data into a consistent object format for easy monitoring:

| Property | Type | Description | | :-------------------- | :-------- | :----------------------------------------------------------------------------------- | | latency | number | End-to-end latency in seconds. | | manifestLiveGap | number | Distance from current playhead to manifest live edge. | | bufferLevel | number | Current forward buffer in seconds. | | resolution | string | Playback rate of the video elementCurrent playback resolution (e.g., "1920x1080"). | | isLowLatency | boolean | Whether the player is in Low Latency mode. | | playbackRate | number | Playback rate of the video element. | | playerState | string | Player state - paused or playing. | | networkSpeed | number | Network Speed in bps. |

Cleanup

To avoid memory leaks, especially on memory-constrained devices like Smart TVs, always detach the analytics when destroying the player:

// Detach the analytics instance and clean up listeners
analytics.detach();

Sample Screenshot