Static Image Gallery Generator

This project provides a single Python script, staticel, that builds a static HTML gallery from a directory tree of pictures and videos.

Features

• Static HTML output with no external dependencies
• URL-addressable fullscreen images using #image=...
• Root index.html plus generated sub-pages under one output directory
• Relative links for images, folders, breadcrumbs, and generated pages
• Optional folder thumbnail previews
• Configurable number of images in folder preview collages
• Folder collage previews using existing images, and cached video posters when thumbnail caching is enabled
• Lightbox image viewer
• Video files with AVIF or WebP poster thumbnails, optional webm hover previews, and fullscreen playback
• Images and videos share one gallery sequence, so next/previous navigation crosses between them
• Keyboard navigation in the lightbox
• Touchscreen swipe navigation in the lightbox
• Browser back button support for closing the lightbox
• Direct image open and download buttons
• Native lazy loading for gallery and folder preview images
• Optional thumbnail cache generation for AVIF posters and video hover previews
• Optional footer metadata for author and copyright

Requirements

• Python 3
• Ffmpeg for video support

Usage

Run the generator with a pictures directory as input:

python3 staticel.py /path/to/pictures

Options

python3 staticel.py /path/to/pictures \
  --output gallery-html \
  --author "Your Name" \
  --copyright "2026 Your Name" \
  --album "My Album" \
  --thumbnail-quality 45 \
  --folder-thumbnail-count 4 \
  --no-folder-thumbnails

To generate AVIF thumbnails and video hover previews inside the generated HTML subtree, add:

python3 staticel.py /path/to/pictures --thumbnails'

To use WebP instead for cached still thumbnails and video posters, add --thumbnail-format webp.

If your ffmpeg build has a hardware AV1 encoder, you can also switch the AVIF path to GPU-backed encoding. On NVIDIA systems this is typically:

python3 staticel.py /path/to/pictures --thumbnails --thumbnail-avif-encoder av1_nvenc

On AMD Radeon systems, use av1_amf if your ffmpeg build exposes it:

python3 staticel.py /path/to/pictures --thumbnails --thumbnail-avif-encoder av1_amf

The --thumbnail-ffmpeg value is a shell-style command prefix. Images are fed through stdin. Videos use a temporary seekable input file because some MOV/MP4 files do not work reliably from stdin. Cached outputs are written through temporary files inside the gallery output tree.

Available options:

• --output: name of the generated HTML directory inside the pictures root
• --author: footer author text
• --copyright: footer copyright text
• --album: custom title for the top-level gallery
• --folder-thumbnails: enable folder collage previews (default)
• --no-folder-thumbnails: disable folder previews and use plain folder tiles
• --folder-thumbnail-count: number of images to include in folder preview collages
• --thumbnails: generate cached still thumbnails in the output subtree for preview images, video posters, and video hover previews
• --thumbnail-ffmpeg: command prefix used to invoke ffmpeg for thumbnail generation
• --thumbnail-quality: quality hint for cached thumbnail stills, from 1 (smallest) to 100 (best quality); default is 55
• --thumbnail-format: choose the cached still-image format for preview images and video posters; avif by default, or webp
• --thumbnail-avif-encoder: choose the ffmpeg AV1 encoder used for AVIF thumbnails; libaom-av1 by default, av1_nvenc on supported NVIDIA systems, or av1_amf on supported AMD Radeon systems

Output Layout

Given a source tree like this:

pictures/
├── holiday/
│   ├── beach.jpg
│   └── sunset.png
├── family/
│   └── portrait.webp
└── cover.jpg

The generated output looks like this:

pictures/
├── index.html
├── gallery-html/
│   ├── holiday/
│   │   └── index.html
│   └── family/
│       └── index.html
├── holiday/
│   ├── beach.jpg
│   └── sunset.png
├── family/
│   └── portrait.webp
└── cover.jpg

This keeps the original picture tree untouched except for the generated gallery files: index.html and gallery-html directory.

How It Works

Each directory becomes a gallery page:

• images in the current directory are shown as gallery items
• subdirectories are shown as folder links
• breadcrumbs provide navigation back toward the root gallery

When folder thumbnails are enabled, folder links display a collage built from a configurable number of existing images found in that folder tree. If thumbnail caching is enabled, the collage can also include cached video posters. The default is three. No resized images or cache files are created unless --thumbnails is enabled.

When thumbnail caching is enabled, the generator writes cached AVIF or WebP posters, plus webm hover previews, under gallery-html/thumbnails/ for faster browsing.

When a gallery image is opened:

• it opens in an in-page lightbox
• the URL hash changes to #image=filename
• the browser back button returns to the gallery view
• the same URL can be shared to open that image directly

Images and videos share the same lightbox navigation, so arrow keys, touch swipes, and the on-screen previous/next buttons move through the full mixed-media set.

The lightbox also includes a fullscreen button. On browsers that do not support native fullscreen on the lightbox container, the viewer falls back to an expanded in-page fullscreen mode.

Notes

• Supported image extensions include: .jpg, .jpeg, .png, .gif, .webp, .avif, .bmp, .svg
• Supported video extensions include: .mp4, .mov, .webm, .m4v, .ogv, .ogg
• Lazy loading uses the browser's native loading="lazy" behavior
• Folder preview selection is recursive within each album folder
• The generated HTML directory is excluded from folder listings so it is not treated as an album

File

• Main script: staticel.py