Thumbforge

Open source · v0.1.1 · MIT

Thumbnails that look like a series.

Thumbforge turns a YouTube playlist into a matching set of spec-compliant thumbnails. Pick one hero, then batch the whole series in its style, from your terminal.

Get started View on GitHub

Version 0.1.1 is on PyPI. Install it

PART 1Start witha plan
  • PART 2Parsearguments
  • PART 3Storethe data
  • PART 4Ship it

01 How it works

One hero sets the look. The series follows it.

  1. Fetch the playlist

    Give it a playlist URL. Thumbforge stores the channel, the playlist and every video, and numbers the parts in playlist order.

    thumbforge fetch <playlist-url>

  2. Pick your hero

    Generate several candidates for one video, compare them and pick the one that sets the look of the series.

    thumbforge thumb generate <video-id> --n 4 thumbforge thumb pick <run-id> 2

  3. Batch the series

    Every other video gets a thumbnail in the hero's style, with its own title and Part N badge.

    thumbforge batch <playlist-id> --hero <run-id>

02 The split

AI paints. Pillow draws.

  1. AI-painted backgroundFrom the image provider, no text.
  2. Parsearguments
    Title (Pillow)Bundled Inter Bold, placed by the template.
  3. PART 2
    “Part N” badge (Pillow)Same size and place on every video.
  4. PART 2Parsearguments
    Final thumbnailPart 2 of the series.

Text is composited, not generated. The provider only paints the background; Pillow draws the title and the badge from the template's layout. Every thumbnail gets identical typography, and a model's spelling never decides what your thumbnail says.

03 In the terminal

A handful of commands, one series.

$ thumbforge fetch "https://www.youtube.com/playlist?list=PL…"
$ thumbforge playlist show <playlist-id> --videos
$ thumbforge playlist renumber <playlist-id> --start 1

$ thumbforge thumb generate <video-id> --template bold-title --provider antigravity --n 4
$ thumbforge thumb pick <run-id> 2
$ thumbforge batch <playlist-id> --hero <run-id> --template series-parts

  • Local-firstOne SQLite database and a folder of images on your machine.

  • ScriptableThe global --json flag prints one JSON document instead of tables.

  • No API key for metadatayt-dlp reads public playlists, videos and channels.

04 Features

Built to repeat one look.

  • Consistent by construction

    AI paints the background. Pillow draws the title and the Part N badge the same way every time.

  • Spec-compliant

    16:9, at least 1280 px wide, JPEG or PNG, under 2 MB, sRGB. Checked before an image is accepted.

  • Pluggable providers

    Providers are plugins found through the thumbforge.providers entry-point group. The Antigravity CLI comes first; a deterministic fake provider keeps tests and demos offline.

  • Local and resumable

    Channels, playlists, videos, templates, runs and assets live in SQLite; images are content-addressed on disk. An interrupted batch resumes where it stopped.

  • Templates you can read

    A template is a Jinja2 prompt plus a TOML layout: canvas, title box, badge, font, colours, safe margins. Check one with thumbforge template validate.

  • Scriptable

    --json prints one JSON document; logs go to stderr, results to stdout. Metadata comes from yt-dlp, so no API key; the YouTube Data API is an optional source.

05 Status

Where it stands.

Version 0.1.1 covers the whole flow, from fetching a playlist to a resumable batch.

Set up and inspect

  • Fetch videos, playlists and channels
  • List and show what you fetched
  • Renumber parts, leaving trailers unnumbered
  • Copy, import, validate and render templates (no provider call)
  • List, check and configure providers
  • Inspect and edit configuration
  • Manage the database

Make thumbnails

  • Hero generation and comparison
  • Pick and iterate
  • Batch a playlist, with resume and cancel
  • Compliance check on every final image
  • Built-in templates, with every version of your own stored
  • Run history and cost report

Read the roadmap

06 Who it is for

For channels that publish in parts.

Thumbforge is for YouTubers who publish in series: courses, tutorial runs, episode seasons.

If you have ever nudged ‘Part 7’ around an editor to match ‘Part 6’, this is for you.

It is not a design suite: it makes one look and repeats it.

07 Install

Install with uv.

uv tool install thumbforge
thumbforge --version

Needs uv. uv fetches Python 3.14 if you do not have it.

User guide Developers Maintainers