VidScan

A high-performance command-line tool to quickly analyze video libraries, calculate total durations across nested directories and generate flexible reports in text, CSV, or JSON formats.

---

Features

• High-Performance: Utilizes concurrency, scans large folders dramatically faster by processing multiple video files in parallel, taking full advantage of your CPU.
• Dual Setup Options: You choose the installation. The script works with a simple pip install (using moviepy) for convenience, or it can detect and use a system-wide ffprobe (FFmpeg) for maximum performance.
• Powerful CLI: A command-line interface to specify the target folder, exclude directories, and customize all options.
• Recursive Scanning: Automatically scans all nested subfolders.
• Flexible Output Formats: Generate reports in .txt, .csv and .json formats.
• Report Templates: Choose between a high-level summary (folder totals only) or a detailed file-by-file breakdown for your text reports.
• Advanced Sorting: Sort the results by folder name, total duration, videos (count), or date (last modified), in either ascending or descending order.

---

Installation

This script is a hybrid tool with two different ways of reading video durations. You need to follow the common steps first and then any one of the two options below.

• For the fastest performance, choose Option 1. This is the recommended method, it requires you to be comfortable installing FFmpeg and adding it to your system's PATH.
• For the simplest setup, choose Option 2. This method is a good alternative if you only plan to scan smaller folders and prefer a single pip install command.

The script will automatically detect which method you have installed. If it finds ffprobe (Option 1), it will use it. If not, it will look for moviepy (Option 2).

---

Common Steps (Required for all users)

1. Install Python (3.8+) from python.org.
2. Get the Script: Download the ZIP or clone the repository:

git clone https://github.com/ompatel100/vidscan.git

Option 1: Using ffprobe (Recommended)

1. Install FFmpeg from the official website.
2. Add the FFmpeg bin folder (which contains ffprobe.exe) to your system's PATH.

That's it! You can now run the script (see Usage section).

Option 2: Using moviepy (Slower)

1. Create a Virtual Environment (Optional but Recommended):

   cd /path/to/project/folder
   python -m venv venv
   ./venv/Scripts/activate

2. Install Dependencies: Run this command to install moviepy:

   pip install -r requirements.txt

---

Usage

You can run the script from your terminal. The only required argument is the path to the folder you want to scan.

Basic Scan

To scan a folder, simply provide the full path. If the path contains spaces, make sure to enclose it in quotes.

python vidscan.py "D:\Path\To\Your\Folder"

This command uses all the built-in defaults:

• Format: txt
• Template: summary
• Sort By: name
• Sort Order: asc

The script will save the report (e.g., Folder - Video Duration.txt) inside that same directory.

Excluding Folders

Use the -e or --exclude flag to ignore one or more folders.

# This will skip folders "Folder 1", "Folder 2"
python vidscan.py "D:\Path\To\Your\Folder" -e "Folder 1" "Folder 2"

Setting Worker Threads

Manually set the number of parallel threads with the -w or --workers flag. The default is dynamically calculated for your system

# Run the scan using a maximum of 16 threads
python vidscan.py "D:\Path\To\Your\Folder" -w 16

Changing Output Format

Use the -f or --format flag. The default is txt.

# Get a CSV file
python vidscan.py "D:\Path\To\Your\Folder" -f csv

# Get a JSON file
python vidscan.py "D:\Path\To\Your\Folder" -f json

Changing Report Template

Use the -t or --template flag to change the template for txt reports. The default is summary.

# Set template to detailed
python vidscan.py "D:\Path\To\Your\Folder" -t detailed

Sorting the Report

Use the -sb or --sort-by flag to sort the results and -so or --sort-order flag for sort order. The default is sorting by name in asc (ascending) order.

# Sort by the longest duration first
python vidscan.py "D:\Path\To\Your\Folder" -sb duration -so desc

# Sort by the highest video count first
python vidscan.py "D:\Path\To\Your\Folder" -sb videos -so desc

# Sort by the most recently modified folders first
python vidscan.py "D:\Path\To\Your\Folder" -sb date -so desc

Get Help

You can see the full list of options by running the script with the -h or --help flag:

python vidscan.py --help

This will display the following:

usage: vidscan.py [-h] [-e EXCLUDE [EXCLUDE ...]] [-w WORKERS] [-f {txt,csv,json}] [-t {summary,detailed}]
                 [-sb {name,duration,videos,date}] [-so {asc,desc}]
                 folder_path

A high-performance tool to calculate total video duration across nested directories.

positional arguments:
  folder_path           The full path to the main folder you want to scan.

options:
  -h, --help            show this help message and exit
  -e, --exclude EXCLUDE [EXCLUDE ...]
                        A space-separated list of folder names to exclude from the scan (case-sensitive).
  -w, --workers WORKERS
                        Number of parallel threads to use.
                        (default: dynamically calculated for your system)
  -f, --format {txt,csv,json}
                        Output file format (default: txt).
  -t, --template {summary,detailed}
                        Text report template (default: summary).
  -sb, --sort-by {name,duration,videos,date}
                        Criterion to sort folders by (default: name).
  -so, --sort-order {asc,desc}
                        Sort order (default: asc).

---

Example Output

Summary Report (Default)

The generated report file will look like this:

Video Duration (Summary)
========================================
Folder: Folder Name 1
  -> Videos:   7 | Duration: 01:11:28
----------------------------------------
Folder: Folder Name 2
  -> Videos:   5 | Duration: 00:54:47
----------------------------------------
                 .
                 .
                 .
----------------------------------------
Folder: Folder Name 67
  -> Videos:  12 | Duration: 02:08:15
----------------------------------------
Folder: Folder Name 68
  -> Videos:  10 | Duration: 01:45:21
----------------------------------------

TOTALS
  -> Total Folders: 68
  -> Total Videos: 493
  -> Total Duration: 98:37:44
========================================
Generated on: 1991-08-25 20:57:08

Detailed Report (-t detailed)

The detailed report shows every file within each folder:

Video Duration (Detailed)
========================================
Folder: Folder Name 1
  [ Videos:   2 | Subtotal: 0:36:31 ]
    - Video Name 1.mp4 (0:14:52)
    - Video Name 2.mp4 (0:22:39)
----------------------------------------
Folder: Folder Name 2
  [ Videos:   3 | Subtotal: 0:48:19 ]
    - Video Name 3.mp4 (0:11:43)
    - Video Name 4.mp4 (0:20:09)
    - Video Name 5.mp4 (0:16:27)             
----------------------------------------

GRAND TOTAL
  -> Total Folders: 2
  -> Total Videos: 5
  -> Total Duration: 1:24:50
========================================
Generated on: 1991-08-25 20:57:08