# WCX Collection

Tools for inventorying and matching local video files against the external WCX reference database.

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:

```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.