From 9ca1a1c1c7bf56e39b516c299b4e0d3efe59652b Mon Sep 17 00:00:00 2001
From: Alexander Kassouni <alex@kassouni.net>
Date: Tue, 8 Sep 2026 20:11:06 -0700
Subject: better docs

---
 docs/soundfont.html | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

(limited to 'docs/soundfont.html')

diff --git a/docs/soundfont.html b/docs/soundfont.html
index c07caf9..436071d 100644
--- a/docs/soundfont.html
+++ b/docs/soundfont.html
@@ -178,11 +178,13 @@ NoteToVoice(vtbl, note)                                    channel.c:354
 wtstr { smzwavetable*, tuning }  →  sample, loop, book, codec, size</pre>
 
 <p><code>ProgToVp</code> is the only consumer of the instrument number, and it is a plain
-array index bounded by <code>num_instruments</code>. This is exactly why
-<code>you</code> (instrument 118) cannot work on bank 157's 83 instruments: the bounds
-check fails, <code>audio_error_flags</code> is set to
-<code>0x03000000 + (prog &lt;&lt; 8) + inst</code>, and nothing plays — though in practice the
-sequence's dynamic table has already clamped the index before it gets there.</p>
+array index bounded by <code>num_instruments</code>: on an out-of-range instrument the
+bounds check fails, <code>audio_error_flags</code> is set to
+<code>0x03000000 + (prog &lt;&lt; 8) + inst</code>, and nothing plays. In retail data the
+guard never trips — each sequence's dynamic table only names instruments its own bank
+has. In particular <code>you</code> on bank 157 is not an error case: sequence 244 maps
+code <code>0x77</code> to instrument 82, the last instrument of the bank
+(see <a href="disc.html">the disc page</a>).</p>
 
 <p>Every voice instrument uses only the <em>normal</em> slot, so <code>NoteToVoice</code> is a
 formality here.</p>
@@ -205,7 +207,7 @@ formality here.</p>
 119 + 83 + 119 instrument slots — point into that one 4 MB wave bank.</p>
 
 <div class="note">
-<strong>Field naming.</strong> <code>../extraction.md</code> §2.2 guessed
+<strong>Field naming.</strong> Earlier working notes guessed
 <code>u8 loaded, rangeLo, rangeHi, releaseRate</code> for the instrument header. The decomp
 calls them <code>is_relocated</code>, <code>normal_range_low</code>,
 <code>normal_range_high</code>, <code>adsr_decay_idx</code>. Same layout, and
@@ -213,9 +215,9 @@ calls them <code>is_relocated</code>, <code>normal_range_low</code>,
 the file.
 </div>
 
-<p>Decoding the VADPCM frames themselves is covered in <code>../extraction.md</code> §2.3 —
-including the one easy mistake, which is convolving the decoded outputs instead of the
-scaled residuals.</p>
+<p>Decoding the VADPCM frames themselves is covered on
+<a href="disc.html">the disc page</a> — including the one easy mistake, which is
+convolving the decoded outputs instead of the scaled residuals.</p>
 
 <div class="pager">
   <span><a href="playback.html">← 5. Playback</a></span>
-- 
cgit v1.3.1