fletchto99/preview-maid

Preview Maid

!https://github.com/fletchto99/preview-maid/actions/workflows/ghcr.yml/badge.svg !https://github.com/fletchto99/preview-maid/actions/workflows/docker.yml/badge.svg !Docker Pulls

镜像概述和主要用途

Preview Maid是一款用于维护Plex媒体库完整性的工具，主要功能是扫描媒体库项目，检测缺失的预览缩略图，还可选择检测缺失的语音活动分析数据及标记数据（如片头、片尾、广告标记）。该工具支持配置为每日定时任务（可自定义时间）或一次性运行，帮助Plex用户确保媒体内容的预览数据完整。

核心功能和特性

• 多类型数据检测：可检测缺失的预览缩略图、语音活动分析数据、片头标记、片尾标记及广告标记
• 灵活运行模式：支持定时任务（自定义运行时间）或一次性运行
• 可配置排除规则：可指定跳过特定类型或名称的媒体库
• 日志管理：支持日志文件挂载，实现日志持久化和轮转（保留最近5次重启的日志）
• 调试模式：可启用调试日志，便于问题排查

使用场景和适用范围

• Plex服务器管理员需要定期维护媒体库预览数据完整性
• 拥有大量媒体文件的用户，需要自动化检测和处理缺失的预览数据
• 希望优化Plex媒体浏览体验，确保预览缩略图和标记数据完整的用户
• 需要自定义扫描规则（如排除特定库）的高级用户

使用方法和配置说明

环境变量配置

可选卷挂载

注意：如果挂载了日志卷，控制台输出仅显示运行统计信息，详细的受影响文件信息需查看日志文件。

生成缺失数据的方法

若检测到缺失的预览缩略图、语音活动分析数据或标记数据，可尝试以下方法生成：

1. 使用Plex库的分析选项强制创建缺失数据
2. 若库级别的分析选项无效，可尝试对单个媒体项目使用分析选项
3. 若预览缩略图生成失败，可在Plex高级设置中将GenerateBIFKeyframesOnly设置为0

   注意：此设置会增加预览缩略图生成时间，并显著提高CPU负载

Docker部署示例

基本运行（一次性检测）

bash
docker run --rm \
  -e PLEX_URL="http://your-plex-server:32400" \
  -e PLEX_TOKEN="your-plex-token" \
  -e RUN_ONCE="true" \
  fletchto99/preview-maid

定时任务模式（每日凌晨2点运行，带日志挂载）

bash
docker run -d \
  --name preview-maid \
  -e PLEX_URL="http://your-plex-server:32400" \
  -e PLEX_TOKEN="your-plex-token" \
  -e RUN_TIME="02:00" \
  -e FIND_MISSING_INTRO_MARKERS="true" \
  -e SKIP_LIBRARY_TYPES="photo" \
  -v /path/on/host/logs:/app/logs \
  fletchto99/preview-maid

Docker Compose配置

yaml
version: '3'
services:
  preview-maid:
    image: fletchto99/preview-maid
    container_name: preview-maid
    environment:
      - PLEX_URL=[***]
      - PLEX_TOKEN=your-plex-token
      - RUN_TIME=03:30
      - FIND_MISSING_THUMBNAIL_PREVIEWS=true
      - FIND_MISSING_VOICE_ACTIVITY=true
      - SKIP_LIBRARY_NAMES=Kids Movies,Home Videos
      - DEBUG=false
    volumes:
      - /path/on/host/logs:/app/logs
    restart: unless-stopped