Overview
copyparty generates thumbnails for images, videos, and audio files (spectrograms/waveforms). Thumbnails are cached for performance and can be customized per-volume.
Thumbnail Generation
Backend Options
Pillow (Recommended)
pyvips (Fastest)
FFmpeg
Features:
- Image thumbnails (JPG, PNG, GIF, WebP, BMP, TIFF)
- Fast performance
- Low memory usage
- WebP output support (if Pillow compiled with it)
Speed: ⭐⭐⭐⭐ (baseline) Features:
- 3x faster than Pillow
- Lower memory usage for large images
- Better RAW format support
- HEIF/HEIC support (if libvips compiled with it)
Speed: ⭐⭐⭐⭐⭐ (3x faster than Pillow)May use more RAM than Pillow for the thumbnail cache.
# Debian/Ubuntu
apt install ffmpeg
# macOS
brew install ffmpeg
- Video thumbnails
- Audio spectrograms/waveforms
- Image thumbnails (fallback)
- Widest format support
Speed: ⭐⭐ (3x slower than Pillow for images)Security consideration: FFmpeg processes arbitrary files and may have vulnerabilities. Use --no-thumb on untrusted uploads.
- JPG, PNG, GIF, WebP, BMP, TIFF, ICO
- RAW formats (with pyvips + rawpy): CR2, NEF, ARW, DNG, etc.
- HEIF/HEIC (with pyvips on supported systems)
Video:
- MP4, WebM, MKV, AVI, MOV, FLV, MPG, MPEG, M4V, 3GP, WMV
- Requires FFmpeg
Audio:
- Spectrograms or waveforms for all audio formats
- Requires FFmpeg
Legal restrictions: Docker images and some builds cannot support HEIF/HEIC images or H.265/HEVC video due to patent licensing. See bad-codecs.md. Configuration
Global Settings
# Disable all thumbnails
copyparty --no-thumb
# Disable only video thumbnails
copyparty --no-vthumb
# Disable audio spectrograms
copyparty --no-athumb
# Custom thumbnail resolution
copyparty --th-size 400x400
# Thumbnail quality (10-90)
copyparty --th-q 85
Per-Volume Configuration
[/public]
/srv/public
flags:
dthumb # disable ALL thumbnails
[/videos]
/srv/videos
flags:
dvthumb # disable video thumbnails only
dathumb # disable audio spectrograms
dithumb # disable image thumbnails
[/photos]
/srv/photos
flags:
thsize: 800x600 # custom resolution
th_qv: 90 # WebP/JPG quality
th_qvx: 85 # JXL quality
Thumbnail Types
Image Thumbnails
Generated using Pillow, pyvips, or FFmpeg (in that priority order).
Format priority:
- WebP (if supported and
--th-webp)
- JPEG (default)
- PNG (for transparency)
# Force WebP thumbnails
copyparty --th-webp
# JPEG-XL thumbnails (future format)
copyparty --th-jxl
Video Thumbnails
Extracted from video files using FFmpeg.
# Disable video thumbnails (security/performance)
copyparty --no-vthumb
# Fix issues on some FFmpeg versions (macOS, some Linux)
copyparty --th-ff-jpg
- First frame extraction is usually fast
- Large/long videos may take time
- Thumbnails cached after first generation
Audio Spectrograms
Generated using FFmpeg showing frequency spectrum over time.
Default audio thumbnail - shows frequency content.copyparty # spectrograms by default
- Identifying songs visually
- Seeing audio quality/bitrate
- Detecting silence/clipping
Shows amplitude over time.Or via URL parameter: ?p for PNG waveforms # Disable audio thumbnails
copyparty --no-athumb
# Fix spectrogram issues on some FFmpeg versions
copyparty --th-ff-swr
# Compress waveforms better (requires pngquant)
copyparty -v /music::r:c,pngquant
Folder Thumbnails
copyparty automatically selects folder thumbnails based on file naming:
Default Cover Names
folder.png / folder.jpgcover.png / cover.jpg.folder.png / .folder.jpg (dotfiles)- First image in folder (with
-e2dsa)
- Embedded album art from audio files (with
-e2dsa -e2ts)
Custom Cover Names
copyparty --th-covers folder.jpg,albumart.png,front.jpg
flags:
th_covers: folder.jpg,cover.jpg,albumart.png
Custom Thumbnails by Extension
Assign specific icons/images to file extensions:
copyparty --ext-th exe=/icons/exe.png --ext-th pdf=/icons/pdf.svg
[/downloads]
/srv/downloads
flags:
ext_th: exe=/icons/exe.png
ext_th: pdf=/icons/pdf.svg
ext_th: iso=/icons/disc.webp
SVG limitation: Chrome crashes with 250+ unique SVG files on one page. Reusing the same SVG thousands of times is fine.
Thumbnail Cache
Storage Location
Thumbnails stored in .hist/ subdirectory:
[global]
hist: /fast/ssd/thumbs # put cache on SSD
[/photos]
/slow/nas/photos
flags:
hist: - # use volume's .hist/ instead
Putting thumbnail cache on an SSD dramatically improves gallery browsing performance.
Cache Management
# Delete thumbnails older than 30 days
copyparty --th-maxage 2592000
# Never clean thumbnails
copyparty --th-clean 0
# Manual cleanup interval (seconds)
copyparty --th-clean 86400
[global]
th-maxage: 2592000 # 30 days in seconds
th-clean: 86400 # check daily
Pregenerate Thumbnails
Generate thumbnails in advance:
# Download folder as tar with thumbnails/spectrograms
curl 'http://localhost:3923/music/?tar&j' > /dev/null
# For images -> JPEG thumbnails
curl 'http://localhost:3923/photos/?tar&w' > /dev/null
# For images -> WebP thumbnails
curl 'http://localhost:3923/photos/?tar&j' > /dev/null
--th-maxage=9999999 or --th-clean=0 to keep forever.
Grid View
Press g or click 田 to toggle grid view (thumbnail gallery).
Grid Features
- Multiselect mode (click to select multiple)
- Zoom with
Shift+A/D
- Click thumbnails to open viewer
- Right-click for context menu
Enable by Default
[/photos]
/srv/photos
flags:
grid # default to grid view
gsel # better selection mode for desktop
?imgs to enable, ?imgs=0 to disable
Thumbnail Resolution
# Smaller = faster generation, less bandwidth, lower quality
copyparty --th-size 300x300
# Larger = slower generation, more bandwidth, better quality
copyparty --th-size 600x600
Quality Settings
# Lower quality = smaller files, faster transfer
copyparty --th-q 70
# Higher quality = larger files, better appearance
copyparty --th-q 95
Backend Selection
# Force specific backend
copyparty --th-pil # use Pillow only
copyparty --th-vips # use pyvips only
copyparty --th-ff # use FFmpeg only
Troubleshooting
Broken Thumbnails
Colorful square with filetype:
- FFmpeg or Pillow not installed
- Install with:
apt install ffmpeg python3-pillow
Blank box or broken image:
- Reverse proxy stripping
?th=w query parameters
- CDN/proxy ignoring query strings in cache
- Privacy browser extensions blocking requests
iPhone/Video thumbnails broken:
- HEIF/HEIC or H.265/HEVC not supported in your build
- Legal restrictions in Docker images
- See bad-codecs.md
Fix Video Thumbnails
# Try these flags if video thumbnails broken
copyparty --th-ff-jpg
copyparty --th-ff-swr
Fix RAW Images
# Install rawpy for RAW format support
pip install rawpy
# Or use FFmpeg
apt install ffmpeg
Security Considerations
Untrusted uploads: Thumbnail generation processes potentially malicious files. Consider:
--no-thumb to disable all thumbnails--no-vthumb to disable video processing only- Running in a sandbox (prisonparty)
Example Configurations
Photo Gallery
[global]
th-size: 600x600
th-webp
th-q: 85
th-maxage: 7776000 # 90 days
hist: /fast/ssd/cache
[/photos]
/mnt/nas/photos
accs:
r: *
flags:
grid # default to grid view
gsel # better selection
th_covers: folder.jpg,cover.jpg
Video Library
[/videos]
/mnt/videos
accs:
r: family
flags:
dvthumb # disable video thumbs (performance)
ext_th: mkv=/icons/mkv.png
ext_th: mp4=/icons/mp4.png
High Security
[/uploads]
/srv/uploads
accs:
w: *
flags:
dthumb # no thumbnail generation
nosub # flat structure only