The reference database is owned by a separate project and must only be opened with SQLite mode=ro. This repository must not store reference metadata or write local file state to that database.

movie.id is the stable external identity for references to movies in the reference database. The initial implementation requires an explicit --database argument and must not assume a default database location.

File operations must be conservative. Any functionality that renames, moves, or removes files should normally support or require a dry run before applying changes.

scripts/match_filenames.py matches local video files against the external reference database. scripts/diagnose_duration_match.py is a manual diagnostic tool that compares one local file with current and historical durations for a specified movie.id; it is not an automated test.

Both scripts require an explicit --database argument and open the reference database strictly read-only with SQLite mode=ro.

WCX title detection

scripts/detect_wcx_title.py identifies local video files that probably belong to WCX by analyzing the layout of the typical WCX title screen near the beginning of each video. It samples frames at 8, 10, and 12 seconds, normalizes them to 640x360 without changing their proportions, and measures black background areas, red and bright text areas, and the edge layout. The best-matching frame receives a score from 0 to 8:

8/8: wcx
6-7/8: uncertain
0-5/8: not_wcx

The detector is completely non-destructive: it does not rename, move, or delete video files. Batch mode also creates no PNG files.

Run it on MP4 files directly in a directory:

scripts/detect_wcx_title.py \
  /storage/disk1/X \
  --batch \
  --ending mp4

Search recursively for multiple video extensions:

scripts/detect_wcx_title.py \
  /storage/disk1/X \
  --batch \
  --recursive \
  --ending mp4,avi

Batch output contains one line per file with its classification, score, best timestamp, and full file path. A summary after the run reports the number processed and the totals for wcx, uncertain, not_wcx, and errors.

In one verified test run, 62 files were analyzed: 41 were classified as wcx, 21 as not_wcx, none as uncertain, and no files produced errors. All 62 classifications were checked manually and were correct for that test material.

This is a heuristic detector, not a guaranteed source of truth. Heavily edited or unusual files may require manual handling. Its goal is useful accuracy with low complexity and reasonable runtime.

For detailed inspection of one video, use --diagnose-layout together with the required --output-dir; this mode saves normalized diagnostic images and prints the measurements for all three timestamps.