blb/docs/hymns_gap_report/README.md

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