Add WCX title detection

README.md

@@ -11,3 +11,55 @@ File operations must be conservative. Any functionality that renames, moves, or
 `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:
+
+```bash
+scripts/detect_wcx_title.py \
+  /storage/disk1/X \
+  --batch \
+  --ending mp4
+```
+
+Search recursively for multiple video extensions:
+
+```bash
+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.