youtube-heatmap

Easily retrieve data about “most replayed” graph for videos on Youtube.

Description

YouTube's player draws the “most replayed” graph as an SVG path on the watch page. In the current player the curve data lives in path.ytp-modern-heat-map (inside svg.ytp-heat-map-svg, 1000x100); the older .ytp-heat-map-path element still exists in the DOM but only as a permanently empty stub. This library matches both, waits until one of them actually contains data, and returns the raw path string(s).

The path is defined with cubic Bézier curves (a C followed by three x,y pairs).

Every third x,y parameter after a C, where x ends with 5.0, is a usable data point:

x is the time stamp in percent. Just compute (x-5)/1000 for a value from 0 to 1.

y is the heat value for this time period. Just compute (100-y)/100 for a value from 0 to 1.

Usage

This is an ES module ("type": "module"), so use import — require() is not supported.

import { getHeatMap } from 'youtube-heatmap';

const heatMap = await getHeatMap('https://www.youtube.com/watch?v=dQw4w9WgXcQ');
console.log(heatMap);

A TypeScript definition file is included so that youtube-heatmap can be used easily from TypeScript with the same API.

Options

Internally puppeteer is used. An optional second parameter is forwarded to puppeteer's wait for the heat map data, e.g. to adjust the timeout (default 30 seconds):

const heatMap = await getHeatMap(url, { timeout: 60000 });

If the video has no heat map (or YouTube changes its player markup again), the promise rejects — either with a timeout or with a "not found or is empty" error — rather than resolving with empty data.

Testing

npm test          # fast, deterministic suite against synthetic markup (no network)
npm run test:live # end-to-end fetch of a real video's heat map

npm run test:live accepts an optional video URL argument. If the live test fails while npm test passes, YouTube has likely changed its player markup — check the heat map element's class name first.