🎬 VCSI Batch Preview Generator

A fully automated video contact sheet generator for Windows using FFmpeg + VCSI.

This tool:

• Generates 5×5 preview grids
• Extracts video metadata automatically
• Handles MKV files seamlessly (auto-remux → preview → cleanup)
• Supports batch processing
• Outputs clean previews into a dedicated previews/ folder

---

🚀 Features

• ✅ Batch processing (folder support)
• ✅ Automatic MKV → MP4 remux (no quality loss)
• ✅ Preserves original .mkv filename in preview
• ✅ Skips already processed files
• ✅ Clean metadata header (custom template)
• ✅ Timestamped thumbnails
• ✅ Organized output (/previews folder)

---

📁 Project Structure

project/
│
├── vcsi_batch.py
├── template.txt
├── template_mkv.txt
└── previews/ (auto-created)

---

⚙️ Requirements

🔹 Python

• Python 3.11 or 3.12 recommended

🔹 Python Packages

pip install vcsi

🔹 System Dependencies (MUST be in PATH)

• ffmpeg
• ffprobe

---

🛠️ Installation

1. Install Python 3.11

2. Install VCSI:

   py -3.11 -m pip install vcsi
   

3. Ensure FFmpeg is installed and accessible:

   ffmpeg -version
   

---

▶️ Usage

Run the script:

python vcsi_batch.py

Enter:

📌 Single file

X:\Videos\Movies\ABC.mp4

📌 Folder (batch mode)

X:\Videos\Movies

---

📤 Output

Previews are saved in:

<video_folder>/previews/

Example:

X:\Videos\Movies\ABC_preview.jpg

---

🧠 How It Works

🔹 Normal files (.mp4, .avi, etc.)

→ Direct VCSI processing

🔹 MKV files

→ Remux to temporary MP4 (no re-encoding)
→ Generate preview
→ Delete temp file

---

🖼️ Metadata Format

Example output:

ABC.mkv
Size: 5.00 GB
Duration: 02:30:45
Resolution: 1920x1080

Video: hevc 5165 kbps 30 fps
Audio: aac 162 kbps

---

⚡ Performance

Step	Time
Remux (MKV only)	~20–60 sec
Preview generation	~2–4 min
Cleanup	instant

---

⚠️ Notes

• HEVC videos may be slower due to decoding
• MKV remux is lossless and fast
• Script skips already generated previews automatically

---

🧩 Customization

Change grid size

Edit in script:

GRID = "5x5"

Change output width

WIDTH = "1800"

Change font

FONT = "C:/Windows/Fonts/arial.ttf"

---

🔧 Templates

template.txt

Used for normal files

template_mkv.txt

Ensures .mkv extension is preserved in previews

---

🚀 Future Improvements (Optional)

• Parallel processing
• GUI interface
• Drag & drop support
• EXE build (no Python needed)

---

🎯 Summary

This tool provides a clean, automated, production-ready workflow for generating video preview sheets with:

✔ Accurate metadata ✔ Consistent layout ✔ Zero manual effort

---

📜 License

Free for personal use.

---

🙌 Acknowledgements

• FFmpeg
• VCSI (Video Contact Sheet Improved)
• Jinja2 templating engine

---

Built for efficiency, automation, and clean output.