@jackgreen2018/youtube-thumbnail-score

A browser-compatible JavaScript library that scores YouTube thumbnails on six criteria and optionally emits a PDF score report. Target: solo YouTubers under 10K subs who want TubeBuddy-style feedback without a Chrome extension.

Money rule incumbent: TubeBuddy at $9.99/mo.

Install

npm install @jackgreen2018/youtube-thumbnail-score

Usage

Node.js

import { scanThumbnail, scoreThumbnail, generateScoreReport } from '@jackgreen2018/youtube-thumbnail-score';
import { readFileSync } from 'fs';

const imageBytes = readFileSync('thumbnail.jpg');

// Step 1: Scan pixel data
const scan = await scanThumbnail(imageBytes);

// Step 2: Score
const score = scoreThumbnail(scan);
console.log(score.total); // 0-100
console.log(score.recommendations); // string[]

// Step 3: PDF report
const pdfBytes = await generateScoreReport(score, { title: 'My Thumbnail Audit' });
// pdfBytes is a Uint8Array with %PDF header

Browser

<script type="module">
  import { scanThumbnail, scoreThumbnail, generateScoreReport } from 'https://cdn.jsdelivr.net/npm/@jackgreen2018/[email protected]/dist/index.js';

  const response = await fetch('thumbnail.jpg');
  const bytes = new Uint8Array(await response.arrayBuffer());
  const scan = await scanThumbnail(bytes);
  const score = scoreThumbnail(scan);
  console.log('Score:', score.total);
</script>

API

scanThumbnail(imageBytes: Uint8Array): Promise<ScanResult>

Decodes image bytes and extracts pixel statistics:

• palette — top-5 dominant colors {r, g, b, count}
• contrastPairs — WCAG contrast ratios between palette colors
• edgeDensity — ratio of edge pixels (Sobel 3x3) to total
• saturation — average saturation across all pixels
• warmRatio — fraction of warm-colored pixels
• luminanceCenter — average luminance at center quarter
• luminanceOverall — global average luminance

scoreThumbnail(scan: ScanResult): ThumbnailScore

Returns scores on 6 criteria (0-100 total):

• colorContrast (0-25) — WCAG AA contrast pair ratio
• textClarity (0-25) — edge density + background clarity
• composition (0-20) — luminance center vs overall focal point
• emotionalAppeal (0-15) — warm ratio + saturation
• clickPotential (0-15) — saturation + contrast
• brandConsistency (0-10) — palette color wheel harmony
• total (0-100)
• recommendations — actionable string array

generateScoreReport(score: ThumbnailScore, options?: { title?: string; includePalette?: boolean }): Promise<Uint8Array>

Generates a PDF scorecard with gauge, criterion bars, and recommendations.

Benchmark

| Image Type | Avg (ms) | Min (ms) | Max (ms) | Size (bytes) | Total Score | |---|---|---|---|---|---| | gradient | 117.61 | 108.72 | 151.14 | 146037 | 34 | | text-on-background | 113.31 | 104.31 | 142.90 | 16420 | 49 | | noisy | 39.29 | 35.82 | 48.33 | 725794 | 49 | | solid-color | 116.50 | 98.07 | 384.24 | 5328 | 42 |

Benchmark run on Node v22.23.2, 100 iterations per image.

Build

npm run build

Test

npm test