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

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

```bash
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:

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

Step 2: match the detected WCX files:

```bash
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:

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