yt-thumbnails 1.0.0

package/README.md

@@ -0,0 +1,77 @@
+# yt-thumbnails
+
+YouTube video thumbnail grid generator. Extract frames from YouTube videos and create a grid image.
+
+## Requirements
+
+- [Bun](https://bun.sh)
+- [ffmpeg](https://ffmpeg.org)
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+
+```bash
+# macOS
+brew install ffmpeg yt-dlp
+```
+
+## Installation
+
+```bash
+git clone <repo-url>
+cd yt-thumbnails
+bun install
+```
+
+## Usage
+
+### Development
+
+```bash
+bun start "<youtube-url>"
+```
+
+### Build
+
+```bash
+bun run build
+./dist/yt-thumbnails "<youtube-url>"
+```
+
+## Options
+
+| Option            | Short | Description                     | Default             |
+| ----------------- | ----- | ------------------------------- | ------------------- |
+| `--grid <n>`      | `-g`  | Grid size (NxN)                 | 4                   |
+| `--scene`         | `-s`  | Use scene detection mode        | uniform             |
+| `--threshold <n>` | `-t`  | Scene detection threshold (0-1) | 0.4                 |
+| `--output <path>` | `-o`  | Output file path                | `grid_NxN_mode.jpg` |
+
+## Examples
+
+```bash
+# Basic 4x4 grid with uniform intervals
+yt-thumbnails "https://youtube.com/watch?v=xxx"
+
+# 6x6 grid
+yt-thumbnails "https://youtube.com/watch?v=xxx" --grid 6
+
+# Scene detection mode (better for music videos)
+yt-thumbnails "https://youtube.com/watch?v=xxx" --scene
+
+# Scene detection with lower threshold
+yt-thumbnails "https://youtube.com/watch?v=xxx" --scene --threshold 0.3
+
+# Custom output path
+yt-thumbnails "https://youtube.com/watch?v=xxx" -o ~/thumbnails/video.jpg
+```
+
+## Modes
+
+### Uniform Mode (default)
+
+Extracts frames at equal time intervals throughout the video.
+
+### Scene Mode (`--scene`)
+
+Detects scene changes and extracts frames at transition points. Better for videos with distinct scenes like music videos or trailers.
+
+If no scene changes are detected, falls back to uniform mode automatically.

package/dist/index.js

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import {execSync as execSync2} from "child_process";
+import {existsSync, mkdirSync, rmSync} from "fs";
+import {join as join3} from "path";
+
+// src/args.ts
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    url: null,
+    grid: 4,
+    mode: "uniform",
+    threshold: 0.4,
+    output: null
+  };
+  for (let i = 0;i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--scene" || arg === "-s") {
+      options.mode = "scene";
+    } else if (arg === "--threshold" || arg === "-t") {
+      options.threshold = parseFloat(args[++i]);
+    } else if (arg === "--grid" || arg === "-g") {
+      options.grid = parseInt(args[++i]);
+    } else if (arg === "--output" || arg === "-o") {
+      options.output = args[++i];
+    } else if (!arg.startsWith("-")) {
+      options.url = arg;
+    }
+  }
+  return options;
+}
+function printUsage() {
+  console.log(`
+Usage: yt-thumbnails <youtube-url> [options]
+
+Options:
+  -g, --grid <n>        Grid size (default: 4 = 4x4)
+  -s, --scene           Use scene detection instead of uniform intervals
+  -t, --threshold <n>   Scene detection threshold 0-1 (default: 0.4)
+  -o, --output <path>   Output file path (default: grid_NxN_mode.jpg)
+
+Examples:
+  yt-thumbnails "https://youtube.com/watch?v=xxx"
+  yt-thumbnails "https://youtube.com/watch?v=xxx" --grid 6
+  yt-thumbnails "https://youtube.com/watch?v=xxx" --scene
+  yt-thumbnails "https://youtube.com/watch?v=xxx" -o ~/thumbnails/video.jpg
+`);
+}
+
+// src/constants.ts
+var TEMP_DIR = "./temp";
+var THUMB_SIZE = 120;
+
+// src/extract.ts
+import {exec, execSync} from "child_process";
+import {promisify} from "util";
+import {readFileSync} from "fs";
+import {join} from "path";
+function extractUniform(videoPath, totalFrames, duration) {
+  const interval = Math.max(1, Math.floor(duration / totalFrames));
+  console.log(`   \uD504\uB808\uC784 \uAC04\uACA9: ${interval}\uCD08`);
+  execSync(`ffmpeg -i "${videoPath}" -vf "fps=1/${interval}" -frames:v ${totalFrames} "${TEMP_DIR}/frame_%03d.jpg" -y -loglevel warning`, { stdio: "inherit" });
+}
+async function extractScenes(videoPath, totalFrames, threshold) {
+  console.log(`   \uC7A5\uBA74 \uAC10\uC9C0 \uC911 (threshold: ${threshold})...`);
+  const sceneFile = join(TEMP_DIR, "scenes.txt");
+  execSync(`ffmpeg -i "${videoPath}" -vf "select='gte(scene,0)',metadata=print:file=${sceneFile}" -vsync vfr -f null - 2>/dev/null`, { encoding: "utf-8" });
+  const sceneData = readFileSync(sceneFile, "utf-8");
+  const scenes = [];
+  let currentFrame = {};
+  for (const line of sceneData.split("\n")) {
+    if (line.startsWith("frame:")) {
+      const pts = line.match(/pts_time:([\d.]+)/);
+      if (pts) {
+        currentFrame.time = parseFloat(pts[1]);
+      }
+    } else if (line.includes("scene_score=")) {
+      const score = line.match(/scene_score=([\d.]+)/);
+      if (score) {
+        currentFrame.score = parseFloat(score[1]);
+        if (currentFrame.score >= threshold && currentFrame.time !== undefined) {
+          scenes.push(currentFrame);
+        }
+        currentFrame = {};
+      }
+    }
+  }
+  console.log(`   ${scenes.length}\uAC1C \uC7A5\uBA74 \uC804\uD658 \uAC10\uC9C0\uB428`);
+  if (scenes.length === 0) {
+    console.log("   \u26A0\uFE0F  \uC7A5\uBA74 \uC804\uD658 \uC5C6\uC74C, threshold \uB0AE\uCDB0\uBCF4\uC138\uC694");
+    console.log("   \u2192 \uADE0\uB4F1 \uAC04\uACA9\uC73C\uB85C \uB300\uCCB4\uD569\uB2C8\uB2E4");
+    return false;
+  }
+  const selectedTimes = [];
+  if (scenes.length <= totalFrames) {
+    selectedTimes.push(...scenes.map((s) => s.time));
+  } else {
+    const step = scenes.length / totalFrames;
+    for (let i = 0;i < totalFrames; i++) {
+      const idx = Math.floor(i * step);
+      selectedTimes.push(scenes[idx].time);
+    }
+  }
+  console.log(`   ${selectedTimes.length}\uAC1C \uD504\uB808\uC784 \uBCD1\uB82C \uCD94\uCD9C \uC911...`);
+  await Promise.all(selectedTimes.map((time, i) => {
+    const outFile = join(TEMP_DIR, `frame_${String(i + 1).padStart(3, "0")}.jpg`);
+    return execAsync(`ffmpeg -ss ${time} -i "${videoPath}" -frames:v 1 "${outFile}" -y -loglevel warning`);
+  }));
+  return true;
+}
+var execAsync = promisify(exec);
+
+// src/grid.ts
+import sharp from "sharp";
+import {readdirSync} from "fs";
+import {join as join2} from "path";
+async function createGrid(grid, outputName) {
+  const frames = readdirSync(TEMP_DIR).filter((f) => f.startsWith("frame_") && f.endsWith(".jpg")).sort().slice(0, grid * grid);
+  console.log(`\uD83D\uDCF7 ${frames.length}\uAC1C \uD504\uB808\uC784\uC73C\uB85C \uADF8\uB9AC\uB4DC \uC0DD\uC131`);
+  if (frames.length === 0) {
+    throw new Error("\uD504\uB808\uC784 \uCD94\uCD9C \uC2E4\uD328");
+  }
+  const composites = await Promise.all(frames.map(async (f, i) => ({
+    input: await sharp(join2(TEMP_DIR, f)).resize(THUMB_SIZE, THUMB_SIZE, { fit: "cover" }).toBuffer(),
+    left: i % grid * THUMB_SIZE,
+    top: Math.floor(i / grid) * THUMB_SIZE
+  })));
+  await sharp({
+    create: {
+      width: THUMB_SIZE * grid,
+      height: THUMB_SIZE * grid,
+      channels: 3,
+      background: { r: 0, g: 0, b: 0 }
+    }
+  }).composite(composites).jpeg({ quality: 90 }).toFile(outputName);
+  return outputName;
+}
+
+// src/index.ts
+async function main() {
+  const opts = parseArgs();
+  if (!opts.url) {
+    printUsage();
+    process.exit(1);
+  }
+  const totalFrames = opts.grid * opts.grid;
+  const modeLabel = opts.mode === "scene" ? "scene" : "uniform";
+  const defaultName = `grid_${opts.grid}x${opts.grid}_${modeLabel}.jpg`;
+  const outputName = opts.output ?? defaultName;
+  if (existsSync(TEMP_DIR)) {
+    rmSync(TEMP_DIR, {
+      recursive: true
+    });
+  }
+  mkdirSync(TEMP_DIR);
+  try {
+    console.log("\uD83D\uDCF9 \uC601\uC0C1 \uC815\uBCF4 \uAC00\uC838\uC624\uB294 \uC911...");
+    const duration = parseFloat(execSync2(`yt-dlp --print duration "${opts.url}"`, {
+      encoding: "utf-8"
+    }).trim());
+    console.log(`   \uAE38\uC774: ${Math.floor(duration / 60)}\uBD84 ${Math.floor(duration % 60)}\uCD08`);
+    console.log("\u2B07\uFE0F  \uC601\uC0C1 \uB2E4\uC6B4\uB85C\uB4DC \uC911...");
+    execSync2(`yt-dlp -f "best[height<=720]" -o "${TEMP_DIR}/video.mp4" "${opts.url}"`, {
+      stdio: "inherit"
+    });
+    const videoPath = join3(TEMP_DIR, "video.mp4");
+    console.log(`\uD83C\uDF9E\uFE0F  \uD504\uB808\uC784 \uCD94\uCD9C \uC911 (${opts.mode} \uBAA8\uB4DC)...`);
+    if (opts.mode === "scene") {
+      const success = await extractScenes(videoPath, totalFrames, opts.threshold);
+      if (!success) {
+        extractUniform(videoPath, totalFrames, duration);
+      }
+    } else {
+      extractUniform(videoPath, totalFrames, duration);
+    }
+    console.log("\uD83D\uDD32 \uADF8\uB9AC\uB4DC \uC0DD\uC131 \uC911...");
+    await createGrid(opts.grid, outputName);
+    console.log(`\u2705 \uC644\uB8CC: ${outputName}`);
+  } finally {
+    if (existsSync(TEMP_DIR)) {
+      rmSync(TEMP_DIR, { recursive: true });
+    }
+  }
+}
+main().catch((err) => {
+  console.error("\u274C \uC5D0\uB7EC:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "yt-thumbnails",
+  "version": "1.0.0",
+  "description": "YouTube video thumbnail grid generator - Extract frames and create beautiful grid images from YouTube videos",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "yt-thumbnails": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --external sharp",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "youtube",
+    "thumbnail",
+    "video",
+    "grid",
+    "ffmpeg",
+    "cli"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ieunsu/yt-thumbnails"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "sharp": "^0.34.5"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "bun-types": "^1.3.5",
+    "typescript": "^5.9.3"
+  }
+}