e621-thumbnailer

Generate image and animated thumbnails from e621 videos.

Note: thumbnail generation takes 5–20 seconds depending on input size and type. Pre-generate in bulk rather than on demand.

Requirements

• Node.js ≥ 20.19.0
• ffmpeg and ffprobe — either install ffmpeg-static and ffprobe-static as dependencies, or ensure the binaries are in PATH
• gifsicle in PATH — optional, enables GIF optimisation

Installation

npm install e621-thumbnailer

# optional: bundled ffmpeg/ffprobe (no system install required)
npm install ffmpeg-static ffprobe-static

Library usage

import thumbnail from "e621-thumbnailer";

The default export is an async function:

thumbnail(input: string | number, options?: ThumbnailOptions): Promise<Thumbnail>

input accepts:

Value	Resolved as
Number	e621 post ID — fetched via the API
32-char hex string	MD5 hash — post resolved via the API
String starting with http:// or https://	Direct URL, downloaded
Any other string	Local file path

The returned Thumbnail object has three methods:

// Copy the file to a permanent location
await thumb.save("./out.png");

// Get the raw bytes without saving to disk
const buf: Buffer = await thumb.toBuffer();

// Delete the underlying temp file (called automatically on process exit)
await thumb.delete();

Examples

import thumbnail from "e621-thumbnailer";

// PNG from a post ID
const thumb = await thumbnail(4505261);
await thumb.save("thumb.png");
await thumb.delete();

// JPEG from an MD5 hash
const thumb = await thumbnail("a51d55b12e7a16a37253783e52c4ec21", { format: "jpg" });
const buf = await thumb.toBuffer(); // use as buffer instead of saving

// Animated GIF from a URL
const thumb = await thumbnail("https://static1.e621.net/data/3c/6c/3c6c18c18c096b5a7ff2fa3bdecf3a63.webm", {
    type: "animated",
    length: 3,
    gifOptimizationLevel: 2,
});
await thumb.save("clip.gif");
await thumb.delete();

// Animated WebP from a local file
const thumb = await thumbnail("./video.webm", {
    type: "animated",
    format: "webp",
});
await thumb.save("clip.webp");
await thumb.delete();

Options

Image options (type?: "image")

Option	Type	Default	Description
format	"png" | "jpg" | "webp"	"png"	Output format
width	number	0	Scale width in pixels; 0 = original size
jpegQuality	number	2	JPEG quality (1–31, lower = better)
webpQuality	number	85	WebP quality (0–100)

Animated options (type: "animated")

Option	Type	Default	Description
format	"gif" | "webp"	"gif"	Output format
length	number	2.5	Clip duration in seconds
fps	number	15	Frames per second
width	number	480	Output width in pixels
colors	number	128	GIF palette size (2–256)
gifOptimizationLevel	0 | 1 | 2 | 3	0	Gifsicle optimisation level; 0 = disabled
quality	number	75	WebP quality (0–100)

Shared options (both types)

Option	Type	Default	Description
ffmpegPath	string	auto	Path to ffmpeg binary
ffprobePath	string	auto	Path to ffprobe binary

CLI usage

e621-thumbnailer <input> [options]

input accepts the same values as the library function (post ID, MD5, URL, or file path).

# PNG thumbnail for post 4505261 → ./thumbnail.png
e621-thumbnailer 4505261

# Animated GIF with optimisation
e621-thumbnailer 4505261 -t animated --gif-optimize 2 -o clip.gif

# Animated WebP from an MD5 hash
e621-thumbnailer a51d55b12e7a16a37253783e52c4ec21 -t animated -f webp -o clip.webp

# JPEG from a local file at a specific width
e621-thumbnailer ./video.webm -f jpg -w 640 -o thumb.jpg

# Write PNG to stdout and pipe into another tool
e621-thumbnailer 4505261 -o - | display

CLI flags

Flag	Default	Description
-o, --output <path>	./thumbnail.<fmt>	Output file path; use - to write to stdout
-t, --type <type>	image	image or animated
-f, --format <fmt>	png / gif	Format (see options tables above)
-w, --width <px>	0 / 480	Scale width
--length <s>	2.5	Animated clip duration
--fps <n>	15	Animated fps
--colors <n>	128	GIF palette size
--quality <n>	75	Animated WebP quality
--webp-quality <n>	85	Image WebP quality
--jpeg-quality <n>	2	JPEG quality (1–31)
--gif-optimize <0-3>	0	Gifsicle optimisation level
--ffmpeg <path>	auto	Path to ffmpeg
--ffprobe <path>	auto	Path to ffprobe
-h, --help		Print help and exit

A man page is also installed: man e621-thumbnailer.

GIF file size

The default settings apply several techniques to keep GIFs small:

• Single-pass palette — palettegen and paletteuse run in one ffmpeg filtergraph, avoiding a separate palette file
• Bayer dithering with diff_mode=rectangle — only changed regions are re-encoded per frame
• 480 px width, 15 fps — reducing these two values has the largest impact on size
• 128-colour palette — half the GIF maximum of 256

A 2.5-second clip typically comes out at 3–8 MB versus 40+ MB with default ffmpeg settings. For the smallest possible output, use format: "webp" — animated WebP achieves comparable quality at roughly a quarter of the GIF size.