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

Write a machine-readable report without changing the terminal output:

scripts/detect_wcx_title.py \
  /storage/disk1/X \
  --batch \
  --ending mp4 \
  --json-report reports/wcx-detection.json

The JSON report contains every selected file with its classification, score, best timestamp, or error details, followed by the same aggregate summary as the terminal output.

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.

Detection-assisted filename matching

detect_wcx_title.py identifies files that probably belong to WCX. match_filenames.py can read its JSON report as a filter and sends only entries with classification == "wcx" to the existing name and duration matching.

Step 1: create the detection report:

scripts/detect_wcx_title.py \
  /storage/disk1/X \
  --batch \
  --ending mp4 \
  --json-report reports/wcx-detection.json

Step 2: match the detected WCX files:

scripts/match_filenames.py \
  /storage/disk1/X \
  --database /storage/disk1/WCX/database/wcx.db \
  --ending mp4 \
  --detection-report reports/wcx-detection.json

match_filenames.py first performs its normal inventory using the input directory, --recursive, --ending, operating-system junk-file filtering, and --limit. The limit is applied before the report filter. The script then takes the intersection of the normally inventoried files and report entries classified as wcx.

For example:

detection_report: /absolute/path/to/wcx-detection.json
inventoried_files: 5
report_wcx_files: 41
selected_files: 3

This means --limit selected the first five normally inventoried files and three of those were classified as wcx. Report entries classified as uncertain, not_wcx, or error are not matched. A reported wcx file outside the current inventory is also ignored. The report must use schema_version: 1.

The report is read-only, video files are not changed, and the reference database remains strict read-only. match_filenames.py does not run detect_wcx_title.py automatically and performs no renames or file moves.

In one verified run, the report contained 41 WCX files and match_filenames.py analyzed exactly those 41 files: 36 were matched, one was ambiguous, four were unmatched, and there were no ffprobe failures. Ambiguous and unmatched files still require separate review or handling.