Add hymns MIDI gap report: 1,463 missing H–Z tune midis across 1,925 pages

docs/hymns_gap_report/README.md

@@ -0,0 +1,70 @@
+# BLB Hymns MIDI Gap Report
+
+Generated: 2026-09-05
+
+## Summary
+
+- **Hymn HTML pages scanned:** 2,749 total; **1,925 (70%)** have ≥1 dead midi reference
+- **Distinct missing midi files:** 1463
+- **Total broken midi references:** 2156
+- **Existing midi files (`hymns/hymns_mid/`):** 729 — tunes A–G only
+- **Midi tune range present:** `mid_a_*` … `mid_g_*`
+- **Midi tune range absent:** `mid_h_*` … `mid_z_*` (plus a handful of `mid_g_*`)
+
+## Root cause
+
+The `hymns/hymns_mid/` directory was ingested with **only tunes A through G** (729 files). The missing H–Z tunes (1,463 files) were **never part of the source data** — confirmed independently in:
+
+- the ingest manifest `blb_manifest.txt` (snapshot of the original WebDAV source at download time)
+- full `git log --all` history (no H–Z midi blob was ever committed)
+- the source WebDAV (`files.thecookiejar.me/www/static/BLB/`) — returns 404 for the missing files
+- the live Blue Letter Bible site (no longer serves these hymn pages) and the Internet Archive Wayback Machine (no capture)
+
+These are **not broken links** (paths are correct and resolve properly); the destination files simply do not exist anywhere reachable.
+
+## Missing files by first tune-letter
+
+| Letter | Missing .mid files |
+|---|---|
+| g | 4 |
+| h | 154 |
+| i | 80 |
+| j | 47 |
+| k | 23 |
+| l | 137 |
+| m | 136 |
+| n | 58 |
+| o | 98 |
+| p | 73 |
+| q | 4 |
+| r | 79 |
+| s | 270 |
+| t | 89 |
+| u | 8 |
+| v | 31 |
+| w | 152 |
+| x | 4 |
+| y | 9 |
+| z | 7 |
+
+## Affected pages
+
+1925 pages under `hymns/hymns_html/` reference at least one missing midi. Full page list is in `broken_pages.txt`.
+
+## Data files in this directory
+
+- `broken_pages.txt` — every page with ≥1 dead midi reference
+- `missing_midis.csv` — one row per (page, missing .mid) reference pair
+- `missing_midis_unique.csv` — one row per distinct missing .mid file
+- `missing_to_pages.csv` — each missing .mid and the pages that reference it
+- `gap_index.json` — machine-readable full dataset
+
+## Recommendation
+
+Do **not** attempt link-only fixes — there is no destination to point at. Realistic remediation paths, in order of safety:
+
+1. **Accept the gap** (documented here) until a source for the hymn-tune midis is obtained.
+2. **Synthesise/obtain** the missing public-domain hymn tunes from an external archive, then add the files under `hymns/hymns_mid/` (no HTML changes needed — the links will then resolve).
+3. **Optionally neutralise** the dead audio controls on the 1,925 affected pages (removes 404s, loses audio).
+
+*Links are `audio/midi` MIME; page HTML constructs them as `./hymns/hymns_mid/<file>.mid` relative to the BLB root (via `basepath.js`), so they resolve against `/BLB/hymns/hymns_mid/`.*