137 lines
5.1 KiB
Markdown
137 lines
5.1 KiB
Markdown
# 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.
|