Add Real Video QoE Telemetry to Your Player in an Afternoon

Starter code available on the full article - link at the bottom.

The Problem

Every video team gets asked these three questions the day after launch:

1. How long does it take for video to start playing?
2. How often does the player stall mid-playback?
3. How often does playback fail outright?

Most teams over-engineer the solution. Here's a minimal approach that actually works.

The Architecture

HLS.js Player → Fastify API (Node 22) → SQLite → Dashboard

No Kafka. No Grafana. Just three files: a React component, a Node endpoint, a SQL view.

Step 1: Set Up the Project

mkdir video-qoe-starter && cd video-qoe-starter
npm init -y
npm install hls.js fastify better-sqlite3

Step 2: Instrument the Player

The core insight: HLS.js exposes events that map directly to the three QoE metrics:

hls.on(Hls.Events.MANIFEST_PARSED, () => {
  session.startTime = performance.now();
});

video.addEventListener('waiting', () => {
  session.rebufferStart = performance.now();
});

video.addEventListener('playing', () => {
  if (session.rebufferStart) {
    const rebufferDuration = performance.now() - session.rebufferStart;
    session.totalRebuffering += rebufferDuration;
    session.rebufferStart = null;
  }
});

Step 3: Backend Endpoint

A simple Fastify endpoint that receives QoE events and writes to SQLite:

fastify.post('/api/qoe', async (req, reply) => {
  const { sessionId, metric, value } = req.body;
  db.run('INSERT INTO qoe_events VALUES (?, ?, ?, ?)',
    [sessionId, metric, value, Date.now()]);
  return { status: 'ok' };
});

Key Metrics

Metric	What It Tells You	Good Threshold
Startup Time	How long until first frame	< 2 seconds
Rebuffering Ratio	% of time spent stalled	< 1%
Failure Rate	How often playback fails	< 0.5%

Why This Matters

If you're building anything with video, tracking these three metrics from day one transforms your debugging process. Instead of "the video is slow," you can say "startup time is 4.2s for users on 3G networks."

---

Full tutorial with complete code: https://codcompass.com/add-real-video-qoe-telemetry-to-your-player-in-an-afternoon-889826

javascript #video #webdev #hls #telemetry