📸 LiveStill

Capture one still frame from a YouTube live/video stream.

Channel → live video → stream URL → image.

✨ Features

• 🔴 Find the current live video for a YouTube channel
• 🖼️ Capture one frame as a Buffer or file
• 🧰 Use as an SDK or CLI
• 🧪 Mockable command runner for tests
• 🚫 No AI, OCR, browser automation, or scraping UI required

📦 Install

npm install livestill

LiveStill shells out to these tools:

brew install yt-dlp ffmpeg

⚡ SDK

import { writeFile } from "node:fs/promises";
import { captureYouTubeLiveFrame, findYouTubeLiveVideo } from "livestill";

const status = await findYouTubeLiveVideo({ url: "https://www.youtube.com/@marvel/" });

if (!status.isLive) {
  throw new Error("Channel is not live");
}

const frame = await captureYouTubeLiveFrame(status.video.url, { format: "jpg" });
await writeFile("frame.jpg", frame.image);

🖥️ CLI

# Find current live URL
livestill live @marvel
livestill live https://www.youtube.com/@marvel/ --json

# Capture a frame
livestill capture @marvel --out marvel.jpg
livestill capture https://www.youtube.com/watch?v=f17J3AXVK5w --out frame.jpg

🧩 API

findYouTubeLiveVideo(options)

await findYouTubeLiveVideo({ handle: "@marvel" });
await findYouTubeLiveVideo({ channelId: "UCxxxxxxxxxxxxxxxxxxxxxx" });
await findYouTubeLiveVideo({ url: "https://www.youtube.com/@marvel/" });

Returns:

type YouTubeLiveStatus =
  | { isLive: false }
  | { isLive: true; video: { videoId: string; url: string; title?: string } };

captureYouTubeLiveFrame(youtubeUrl, options?)

const frame = await captureYouTubeLiveFrame("https://www.youtube.com/watch?v=...", {
  outputPath: "frame.jpg",
});

Lower-level helpers

• resolveDirectStreamUrl(youtubeUrl, options?)
• captureFrame(streamUrl, options?)
• createYouTubeWatchUrl(videoId)

☁️ Runtime notes

| Runtime | Status | Notes | | --- | --- | --- | | Node server / container | ✅ | Install yt-dlp + ffmpeg | | AWS Lambda | ✅ | Bundle binaries in a layer/container | | Edge/browser runtimes | ❌ | No child processes/filesystem |

Direct stream URLs expire. Resolve close to capture time and keep yt-dlp updated.

🧪 Verify

pnpm run verify
pnpm run test:integration
pnpm pack

MIT