@reckerp/yt-most-replayed

A TypeScript library to fetch YouTube's "Most Replayed" heatmap data.

Installation

bun add @reckerp/yt-most-replayed

npm install @reckerp/yt-most-replayed

pnpm add @reckerp/yt-most-replayed

Usage

Basic Example

import { getMostReplayed, formatTime } from "@reckerp/yt-most-replayed";

const data = await getMostReplayed("dQw4w9WgXcQ");

if (data) {
  console.log(`Video has ${data.markers.length} heatmap segments`);
  console.log(`Peak moment at ${formatTime(data.peakSegment?.startMillis ?? 0)}`);
  console.log(`Average intensity: ${(data.averageIntensity * 100).toFixed(1)}%`);
} else {
  console.log("No most replayed data available");
}

Using URLs

import { getMostReplayed } from "@reckerp/yt-most-replayed";

// All these formats work:
await getMostReplayed("dQw4w9WgXcQ");
await getMostReplayed("https://www.youtube.com/watch?v=dQw4w9WgXcQ");
await getMostReplayed("https://youtu.be/dQw4w9WgXcQ");
await getMostReplayed("https://www.youtube.com/shorts/VIDEO_ID");

Finding Top Moments

import {
  getMostReplayed,
  getTopSegments,
  formatTime,
  generateTimestampUrl,
} from "@reckerp/yt-most-replayed";

const data = await getMostReplayed("dQw4w9WgXcQ");

if (data) {
  const top5 = getTopSegments(data, 5);
  
  top5.forEach((segment, i) => {
    console.log(`#${i + 1}: ${formatTime(segment.startMillis)}`);
    console.log(`    Intensity: ${(segment.intensityScoreNormalized * 100).toFixed(1)}%`);
    console.log(`    URL: ${generateTimestampUrl("dQw4w9WgXcQ", segment.startMillis)}`);
  });
}

Filtering by Intensity

import { getMostReplayed, filterByIntensity } from "@reckerp/yt-most-replayed";

const data = await getMostReplayed("dQw4w9WgXcQ");

if (data) {
  // Get only "hot" segments (above 50% intensity)
  const hotSegments = filterByIntensity(data, 0.5);
  console.log(`Found ${hotSegments.length} hot segments`);
}

Error Handling

import {
  getMostReplayed,
  MostReplayedError,
  MostReplayedErrorCode,
} from "@reckerp/yt-most-replayed";

try {
  const data = await getMostReplayed("invalid-id");
} catch (error) {
  if (error instanceof MostReplayedError) {
    switch (error.code) {
      case MostReplayedErrorCode.INVALID_VIDEO_ID:
        console.error("Invalid video ID or URL");
        break;
      case MostReplayedErrorCode.FETCH_FAILED:
        console.error("Failed to fetch video page");
        break;
      case MostReplayedErrorCode.PARSE_FAILED:
        console.error("Failed to parse video data");
        break;
      case MostReplayedErrorCode.TIMEOUT:
        console.error("Request timed out");
        break;
    }
  }
}

Custom Fetch Options

import { getMostReplayed } from "@reckerp/yt-most-replayed";

const data = await getMostReplayed("dQw4w9WgXcQ", {
  timeout: 15000, // 15 second timeout
  userAgent: "MyApp/1.0",
});

API Reference

getMostReplayed(videoIdOrUrl, options?)

Fetches the most replayed data for a YouTube video.

Parameters:

• videoIdOrUrl (string) - A YouTube video ID or URL
• options (FetchOptions) - Optional configuration
  • timeout (number) - Request timeout in ms (default: 10000)
  • userAgent (string) - Custom user agent
  • fetch (function) - Custom fetch implementation

Returns: Promise<MostReplayedData | null>

MostReplayedData

interface MostReplayedData {
  markers: HeatmapMarker[];           // Heatmap segments
  timedMarkerDecorations: TimedMarkerDecoration[] | null;
  videoDurationMillis: number;        // Estimated video duration
  peakSegment: HeatmapMarker | null;  // Highest intensity segment
  averageIntensity: number;           // Average intensity (0-1)
}

interface HeatmapMarker {
  startMillis: number;                // Start time in milliseconds
  intensityScoreNormalized: number;   // Intensity (0-1)
}

Utility Functions

| Function | Description | |----------|-------------| | formatTime(millis) | Format milliseconds as "MM:SS" or "HH:MM:SS" | | getTopSegments(data, count) | Get N most replayed segments | | getSegmentAtTime(data, millis) | Find segment at specific time | | filterByIntensity(data, threshold) | Filter segments by intensity | | generateTimestampUrl(videoId, millis) | Generate YouTube URL with timestamp | | isValidVideoId(id) | Check if string is valid video ID | | extractVideoId(urlOrId) | Extract video ID from URL or validate ID |

Running the Example

bun run example.ts dQw4w9WgXcQ

Development

# Install dependencies
bun install

# Run type checking
bun run typecheck

# Build the library
bun run build

# Format and lint
bun run format
bun run lint

License

MIT