stevezzau/media_preview_generator

Media Preview Generator

GPU加速的视频预览缩略图生成工具，适用于Plex、Emby和Jellyfin。仅提供Web UI——无命令行界面。

此前名为Plex Generate Previews，镜像地址为stevezzau/plex_generate_vid_previews。该镜像将持续同步更新至2026年10月29日；之后，仅通过本仓库（stevezzau/media_preview_generator）发布。建议适时将您的compose配置更新为新名称——设置和卷挂载可无缝迁移。

问题背景

不同媒体服务器的内置预览生成功能存在不足：

• Plex：仅使用CPU单线程生成缩略图（不支持GPU）。
• Emby：完全不支持GPU加速的缩略图生成。
• Jellyfin：虽支持硬件加速的 trickplay，但与播放功能共享CPU/GPU资源——在繁忙服务器上，这些资源更应用于媒体播放。

解决方案

本工具可在您选择的设备上独立于媒体服务器运行预览生成，利用所有可用GPU，并行处理文件。当多个服务器包含相同文件时，FFmpeg仅运行一次——结果将以各服务器预期格式输出。

核心功能与特性

一次处理，多服务器适配

支持同时指向Plex、Emby、Jellyfin（任意组合、任意数量），单次生成运行即可为各服务器写入正确的输出格式（Plex BIF文件包、Emby侧载BIF、Jellyfin trickplay瓦片）。

自动化工作流

支持Radarr/Sonarr/Tdarr/FileFlows webhook、Plex直接集成（需Plex Pass）、最近添加内容轮询、定时任务与间隔调度——所有触发方式共享一个通用入站URL，自动检测来源。5步退避重试机制（30秒→2分钟→5分钟→15分钟→60分钟）可处理服务器尚未索引的文件。基于源的去重机制在文件替换时（如Sonarr/Radarr质量升级）自动重新运行，文件未变更时则跳过。

充分利用现有硬件

支持NVIDIA、AMD、Intel GPU——可配置每GPU工作进程数和FFmpeg线程数，当GPU编解码失败时自动使用CPU重试，支持HDR/杜比视界色调映射（包括通过libplacebo支持Profile 5）。各服务器的预览就绪状态面板可审计影响预览显示的所有标志，并提供一键切换和破坏性操作的类型确认。

快速开始

bash
docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  -p 8080:8080 \
  --device /dev/dri:/dev/dri \
  -e PUID=1000 \
  -e PGID=1000 \
  -v /path/to/media:/media:ro \
  -v /path/to/plex/config:/plex:rw \
  -v /path/to/app/config:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

将/path/to/media、/path/to/plex/config和/path/to/app/config替换为实际路径。

时区设置：挂载/etc/localtime可确保日志时间戳和计划任务使用本地时间。也可使用-e TZ=America/New_York（替换为您的时区）。

然后打开http://YOUR_IP:8080，从容器日志中获取认证令牌，完成设置向导。所有设置（Plex连接、GPU配置、处理选项）均在Web UI的设置页面中配置。

镜像标签

版本历史和每个版本的发布说明见https://github.com/stevezau/media_preview_generator/releases%E3%80%82

卷挂载

Docker Compose配置

GPU支持（Intel / AMD / NVIDIA）

yaml
services:
  plex-previews:
    image: stevezzau/media_preview_generator:latest
    container_name: media-preview-generator
    restart: unless-stopped
    ports:
      - "8080:8080"
    # Intel / AMD GPU (VAAPI)
    devices:
      - /dev/dri:/dev/dri
    # NVIDIA: 移除上方'devices'，取消下方注释
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]
    environment:
      # NVIDIA专用（使用NVIDIA时取消注释）：
      # - NVIDIA_VISIBLE_DEVICES=all
      # 使用'all'以注入NVIDIA Vulkan驱动；'graphics'是
      # 杜比视界Profile 5 libplacebo色调映射所必需的。
      # - NVIDIA_DRIVER_CAPABILITIES=all
      - PUID=1000
      - PGID=1000
    volumes:
      - /path/to/your/media:/media:ro
      - /path/to/plex/config:/plex:rw
      - /path/to/app/config:/config:rw
      - /etc/localtime:/etc/localtime:ro

仅CPU模式

在Web UI设置中将GPU工作进程数设为0，根据需要配置CPU工作进程数。

yaml
services:
  plex-previews:
    image: stevezzau/media_preview_generator:latest
    container_name: media-preview-generator
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - PUID=1000
      - PGID=1000
    volumes:
      - /path/to/your/media:/media:ro
      - /path/to/plex/config:/plex:rw
      - /path/to/app/config:/config:rw
      - /etc/localtime:/etc/localtime:ro

GPU支持

"仅原生运行" 指GPU加速需在对应平台上从源码运行应用。Windows（WSL2）和macOS上的Docker运行Linux虚拟机——Docker内部无法使用D3D11VA和VideoToolbox。这些平台上的Docker将仅使用CPU处理。Apple Silicon用户可受益于原生ARM64 Docker镜像（无Rosetta开销）。

NVIDIA GPU配置

前提条件：安装NVIDIA驱动和NVIDIA Container Toolkit。

bash
docker run -d \
  --gpus all \
  -e NVIDIA_VISIBLE_DEVICES=all \
  -e NVIDIA_DRIVER_CAPABILITIES=all \
  -e PUID=1000 \
  -e PGID=1000 \
  -p 8080:8080 \
  -v /path/to/media:/media:ro \
  -v /path/to/plex/config:/plex:rw \
  -v /path/to/app/config:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

GPU与CPU fallback

CPU fallback为自动机制。若文件在GPU上处理失败（不支持的编解码器、驱动崩溃等），同一工作进程会自动在CPU上重试，仪表盘将显示黄色"CPU fallback"标记。无需单独配置CPU工作池——仅当有大量内容无法在GPU上解码，且希望这些文件直接由专用CPU工作进程处理时，才需将CPU工作进程数设为大于0的值。

环境变量

所有应用设置（Plex、GPU、处理选项）均在Web UI设置页面中配置。/config目录下的settings.json为唯一配置源。仅以下基础架构环境变量持续有效：

应用级环境变量（如PLEX_URL、PLEX_TOKEN、CPU_THREADS等）仅在首次启动时作为初始值，之后会迁移至settings.json，settings.json将成为配置源。

Unraid配置

在Community Applications中搜索"media-preview-generator"，或手动运行：

bash
docker run -d \
  --name media-preview-generator \
  --restart unless-stopped \
  -p 8080:8080 \
  --device /dev/dri:/dev/dri \
  -e PUID=99 \
  -e PGID=100 \
  -v /mnt/user/data/plex:/data/plex:ro \
  -v "/mnt/cache/appdata/plex/Library/Application Support/Plex Media Server":/plex:rw \
  -v /mnt/user/appdata/media-preview-generator:/config:rw \
  -v /etc/localtime:/etc/localtime:ro \
  stevezzau/media_preview_generator:latest

性能调优

在Web UI的设置中，按GPU配置GPU和CPU工作进程数。

重要注意事项

• **不要添加init: true**到docker-compose文件——容器内部管理自身进程，init: true会导致冲突。
• 使用主机IP连接Plex——容器无法访问主机的localhost。使用http://192.168.1.100:32400，而非http://localhost:32400。
• 推荐Plex设置——在Plex设置中将"生成视频预览缩略图"设为从不。本工具将以GPU加速处理替代该功能。

文档

完整文档见GitHub：

• https://github.com/stevezau/media_preview_generator/blob/main/docs/getting-started.md%E2%80%94%E2%80%94Docker%E3%80%81GPU%E3%80%81Unraid%E3%80%81%E7%BD%91%E7%BB%9C%E9%85%8D%E7%BD%AE
• https://github.com/stevezau/media_preview_generator/blob/main/docs/guides.md%E2%80%94%E2%80%94Web UI、计划任务、Webhook、HDR、故障排除
• https://github.com/stevezau/media_preview_generator/blob/main/docs/reference.md%E2%80%94%E2%80%94%E6%89%80%E6%9C%89%E8%AE%BE%E7%BD%AE%E3%80%81%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E5%92%8CREST API
• https://github.com/stevezau/media_preview_generator/blob/main/docs/faq.md%E2%80%94%E2%80%94%E5%85%B3%E4%BA%8E%E8%AE%BE%E7%BD%AE%E3%80%81%E6%80%A7%E8%83%BD%E5%92%8C%E5%85%BC%E5%AE%B9%E6%80%A7%E7%9A%84%E5%B8%B8%E8%A7%81%E9%97%AE%E9%A2%98

支持

• https://github.com/stevezau/media_preview_generator/issues/new?labels=bug
• https://github.com/stevezau/media_preview_generator/issues/new?labels=enhancement
• https://github.com/stevezau/media_preview_generator

许可证

MIT许可证。详见https://github.com/stevezau/media_preview_generator/blob/main/LICENSE%E3%80%82