Recursively scan media libraries and generate per-folder and per-file reports of duration and size in txt, csv, or json - powered by ffprobe.

• Python 3.7+
• FFmpeg (ffmpeg.org/download.html)

FFmpeg must be installed and available in your system PATH. vidscan calls ffprobe (included with FFmpeg) to read media metadata. If ffprobe is not found, vidscan will not run.

pip install vidscan

No additional packages are installed. vidscan has zero pip dependencies. It's safe to install globally without any virtual environment.

Provide the folder path. It scans it and all subfolders recursively, and generates report in the same folder.

Windows

vidscan "D:\Media\Projects"

macOS / Linux

vidscan /media/projects

Report is saved in the scanned folder. If any files fail, a separate failed files report is saved alongside it. The default output is summary txt. Run vidscan --help to see all options.

Default summary txt report grouped by subfolders:

Video Duration (Summary)
============================================================

Folder: Commercials
  -> Videos:   8 | Duration: 02:14:33
------------------------------------------------------------
Folder: Documentaries
  -> Videos:  23 | Duration: 07:45:12
------------------------------------------------------------
Folder: Raw Footage
  -> Videos:  41 | Duration: 14:22:08
------------------------------------------------------------

TOTALS
  -> Total Folders: 3
  -> Total Videos: 72
  -> Total Duration: 24:21:53
============================================================
Generated on: 2026-04-29 14:52:07

---
[!] NOTE: Scanning failed for 2 videos and are excluded from this report.

Failed files are caught, with the reason for failure, and a separate report is generated alongside the main one. They are never silently dropped.

Four things were kept at the center of how vidscan was built.

Scans any folder structure recursively to any depth. The traversal is stack based, not recursive, so deeply nested libraries do not hit Python's call stack limit. Works on local drives, external drives, and network drives.

--extensions defines exactly which file types are included, --exclude defines which folders are skipped entirely. The default covers common video formats, but since ffprobe supports virtually any media format, vidscan can be used on audio libraries, mixed media archives, or broadcast formats such as MXF by specifying extensions.

Files are processed concurrently using multiple threads. vidscan has two built-in defaults - one for HDD, one for SSD. Both are dynamic based on system's CPU count. HDD default is used unless -w ssd is specified. Thread count can be set manually with -w <n>.

For network drives, --fast-start skips the initial directory count and begins processing immediately, avoiding the latency before starting.

ffprobe is the foundation - the industry standard for media metadata, it's the same engine used in professional media tools. Duration results are not estimated or inferred from file headers. They are read directly by ffprobe.

Failed files are caught individually. Each failure is recorded with its path, specific error reason and file size. A separate failed files report is generated alongside the main report.

--ffprobe-timeout prevents the tool from hanging on corrupt, partially written, or network stalled files. A file that exceeds the timeout is marked as failed and the scan continues.

If a scan is interrupted, results processed up to that point are preserved and written. The scan does not need to complete for the output to be useful.

Windows long paths beyond MAX_PATH are handled automatically. Symbolic links to directories are not followed, preventing symlink loops.

Terminal output adapts automatically to the environment - color, progress bar, and unicode characters adjust based on terminal capabilities. NO_COLOR (no-color.org), FORCE_COLOR, and CLICOLOR_FORCE are respected. When output is piped or redirected, formatting is stripped automatically.

Zero pip dependencies means no version conflicts and no risk of affecting an existing Python environment. vidscan is safe to install globally without any virtual environment.

Three output formats: txt, csv, and json. Use --format all to generate all three in a single scan. The txt format has two templates: summary for folder level totals and detailed for a per-file breakdown for each folder. File size can be included in txt reports with --include-size-txt.

Folders can be sorted by name, duration, file count, size, or date of the most recently modified file within the folder. Sort order is ascending by default and can be descending with --sort-order desc.

Default extensions: .mp4 .mkv .webm .mov .m4v .avi .wmv .flv .mpg .mpeg

Detailed txt report sorted by duration, longest duration folders first:

vidscan "D:\Media" -t detailed -sb duration -so desc

Scan with 16 threads, skip cache and temp folders, generate all formats:

vidscan /media/archive -w 16 -e cache temp -f all

Scan only MXF and MOV files on a network drive with 30 sec ffprobe timeout:

vidscan /mnt/nas/footage -ext mxf mov --fast-start --ffprobe-timeout 30

Include file sizes in a summary report sorted by total folder size:

vidscan "D:\Projects" --include-size-txt -sb size -so desc

One entry per-folder showing video count and total duration, with an optional size column. Totals at the end cover all folders combined. Readable as-is without any additional tooling.

Each folder lists every individual file with its duration and optional size. Useful when you need to audit specific files rather than just folder level totals.

Video Duration (Detailed)
===========================================================================

Folder: Commercials
  [ Videos:   8 | Subtotal Duration: 02:14:33 | Subtotal Size: 1.24 GB ]
    - brand_spot_v3_final.mp4 (00:00:30 | 187.32 MB)
    - corporate_intro_2024.mov (00:01:15 | 312.45 MB)
    - product_launch_cut.mp4 (00:00:45 | 156.18 MB)
    ...

Folder: Documentaries
  [ Videos:  23 | Subtotal Duration: 07:45:12 | Subtotal Size: 48.67 GB ]
    - chapter_01_rough.mkv (00:18:44 | 8.92 GB)
    - chapter_02_rough.mkv (00:22:31 | 10.14 GB)
    ...

---------------------------------------------------------------------------

GRAND TOTAL
  -> Total Folders: 3
  -> Total Videos: 72
  -> Total Duration: 24:21:53
  -> Total Videos Size: 87.43 GB
===========================================================================
Generated on: 2026-04-29 14:53:39

Shown with --include-size-txt. Without this, size columns are omitted.

One row per-file with columns: folder path, relative path, file name, duration in seconds, duration formatted, size in bytes, size formatted. Failed files appear as rows with FAILED in the duration column and the error reason in the formatted duration column. A summary block is appended at the bottom of the file. Opens directly in Excel or Google Sheets.

A structured object with three top-level keys:

• summary - total folders, video count, duration, and size across the full scan
• details - array of folder objects, each containing its video count, total duration, total size, and an array of individual video entries
• failed_videos - array of files that could not be read, each with path, error reason, and size

Generates txt (detailed template), csv, and json in a single scan.

MIT

Report bugs or request features here