README.md

Payload Video Cover Plugin

Automatically generates cover images for video uploads in specified collections. This feature was written in a linux environment, before the payload video component (that has a cover image as well) It can extract any frame from the video for the cover image (payload component takes the first frame), and can be used to extract many frame for any purpose. This feature was implemented in the flowing way:

Setup

1. Install the Plugin

npm add @shefing/cover-image

2. Payload Config (payload.config.ts)

  plugins: [
    videoCoverPlugin({
      collections: ['media', 'videos'], // Collections to process
      framePosition: 'middle',          // 'start' | 'middle' | number (seconds)
      imageFormat: 'webp',              // 'webp' | 'jpg' | 'png'
    })
  ]

or for default values

  plugins: [
    videoCoverPlugin({})
  ]

---

Configuration

1. Next.js Config (next.config.mjs)

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    serverSourceMaps: true,
  },
  serverExternalPackages: [
    "ffmpeg-static",
    "fluent-ffmpeg"
  ],
};

export default withPayload(nextConfig);

2. Docker Setup (Dockerfile)

# Copy ffmpeg-static binaries
COPY --from=builder /app/node_modules/ffmpeg-static/ ./node_modules/ffmpeg-static/

3. Install Dependencies

 npm install fluent-ffmpeg@2.1.2 ffmpeg-static@5.1.0

---

How It Works

1. When a video is uploaded to a configured collection:

   • Extracts a frame at the specified framePosition
   • Generates a cover image in the chosen imageFormat
   • Stores the image in your media collection

2. Auto-adds fields to your collections:

   {
     coverImage: string | Media;  // Reference to the generated image
     thumbnailURL: string;        // Direct URL to the thumbnail
     startPosition: number;       // Actual frame position used
   }

---

Features

• 🎥 Automatic thumbnail generation for video uploads
• ⚙️ Configurable frame capture position (start, middle, or custom seconds)
• 🖼️ Multiple image formats (WebP, JPEG, PNG)
• 🐳 Docker-ready configuration
• 🛠️ Auto-adds required fields (coverImage, thumbnailURL, startPosition)

---

Troubleshooting

Error: "FFmpeg not found"

• Fix on Ubuntu/Debian:

  sudo apt-get install ffmpeg

• Fix on MacOS:

  brew install ffmpeg

• Docker Build Fix:
  Ensure your Dockerfile includes:

  RUN apt-get update && apt-get install -y ffmpeg
  COPY --from=builder /app/node_modules/ffmpeg-static/ ./node_modules/ffmpeg-static/

---

Roadmap

See the consolidated ROADMAP.md at the repo root and the live RoadMap issues for Cover Image.

P0

• Cross-platform support — detect ffmpeg from process.env.FFMPEG_PATH first, fall back to ffmpeg-static; document macOS/Windows/Docker setup.
• Multiple frames / sprite sheet — frames: number | number[] for hover previews & chapter thumbnails.
• Async / background generation via a Payload job/queue.

P1

• Auto-poster + GIF preview outputs.
• Image processing options (target size, quality, blur, watermark overlay).
• Regenerate action available on each video document.

P2

• Pluggable extractor (extractor: 'ffmpeg' | 'cloudinary' | custom).
• Deprecation guide once Payload's native video cover covers all use-cases.

License

MIT © Shefing