From 89c95a70a237bfc808c8d610c7a73db0e241da83 Mon Sep 17 00:00:00 2001
From: jonathan <webmaster@jonathan859.com>
Date: Sat, 13 Jun 2026 10:28:52 +0200
Subject: [PATCH] feat: loudness walk (U/I) keeps its own cursor, independent
 of J/K
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The clip bar had one shared cursor, so pressing U/I re-derived the
loudness rank from wherever you currently were. A J/K detour to review
clips around an interesting spot therefore hijacked the loudness walk:
returning to U/I continued from the J/K position, not from where the
ranking left off.

Add a separate scoreCursor that only U/I (and "highlights only" auto-
advance) move; J/K never touches it. So: U/I to a loud moment, J/K to
review the time-adjacent clips, U/I again resumes the ranking exactly
where you left it. scoreCursor resets to -1 on every explicit jump /
queue re-arm (hideClipBar, chip clicks, day-highlights arm) so the next
U/I re-anchors on the selected section.

Also label the position count "by time" (J/K) or "by loudness" (U/I) so
the blind user can hear which dimension the count is in — the two looked
identical before and switched meaning silently when changing keys.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 CLAUDE.md  |  2 +-
 README.md  |  2 +-
 webui.html | 42 +++++++++++++++++++++++++++++++++---------
 3 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c4a156f..765601d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,7 +38,7 @@ Dependencies: `requests` (streams), `numpy` + `soundfile` (FLAC output and FLAC
 - Serving: `_stream()` (Range support), `_copy_to_response()`, `_safe_path()` (path traversal guard).
 
 `webui.html` (one `<script>` block):
-- Clip review: `clipQueue`/`clipCursor` globals, `playClip()`, `playFileSection()`, `hideClipBar()`; markup is the `#clip-bar` div. The clip label shows wall-clock occurrence time + dB prominence + position (`17:09:56 to 17:09:57 · +30 dB (30 / 426)`): queue entries carry `absStart` (epoch s), derived from `fileStartEpoch(f.date)` — the filename clock — with in-file offsets as fallback for non-standard names; only the filename/in-file offset lives in the tooltip now. **`playClip()` builds one `text` string used for both `label.textContent` and the `announce()` aria-live message** — they must never diverge (a past bug had the announcement read `Clip N of M: …` while the label read the wall-clock form). `playClip(i, byScore)`: when `byScore` (a U/I or "highlights only" loudness walk), the position shown is the rank in `scoreOrder()` ("3rd loudest of 426"), not the time-order index `i`; `stepClip`'s by-score branch passes `true`, every other caller (chip click, J/K, Prev/Next) leaves it false for the time-order index.
+- Clip review: `clipQueue`/`clipCursor`/`scoreCursor` globals, `playClip()`, `playFileSection()`, `hideClipBar()`; markup is the `#clip-bar` div. The clip label shows wall-clock occurrence time + dB prominence + position (`17:09:56 to 17:09:57 · +30 dB (30 / 426 by time)`): queue entries carry `absStart` (epoch s), derived from `fileStartEpoch(f.date)` — the filename clock — with in-file offsets as fallback for non-standard names; only the filename/in-file offset lives in the tooltip now. **`playClip()` builds one `text` string used for both `label.textContent` and the `announce()` aria-live message** — they must never diverge (a past bug had the announcement read `Clip N of M: …` while the label read the wall-clock form). **Two cursors, deliberately independent:** `clipCursor` is the time-order position and follows every play; `scoreCursor` is the loudness walk's own position in `scoreOrder()` and is moved *only* by U/I (and "highlights only" auto-advance) in `stepClip`'s by-score branch — J/K must never touch it, so a J/K detour to review nearby clips leaves the loudness walk's place intact and the next U/I resumes the ranking where it left off. `scoreCursor` resets to `-1` on every explicit jump / queue (re-)arm (`hideClipBar`, `playFileSection`, `jumpToDaySection`, both day-highlights arm points), so the next U/I re-anchors on `clipCursor` (the section just selected) else the loudest. `playClip(i, byScore)`: when `byScore` the count shows `scoreCursor` (rank, suffix "by loudness"), else `i` (time-order index, suffix "by time") — the suffix tells the blind user which dimension the count is in. `stepClip`'s by-score branch passes `byScore=true`; every other caller (chip click, J/K, Prev/Next) leaves it false.
 - Day review: `dayHighlights()` builds `dayActiveSections` (chronological); `jumpToDaySection()` arms the queue. Section `absStart` comes from `fileStartEpoch(f.date)` (filename clock), mtime−duration only as fallback. **The user is blind and uses a screen reader — there is deliberately no day-timeline SVG** (one existed and was removed on request as useless); the highlights panel is linear text/buttons: summary line → key-hint note → chips toggle → chips. Do not add decorative visualizations; any future graphic must be aria-hidden and must not be the only carrier of information. Chip lists longer than 12 are collapsed behind an `aria-expanded` toggle button (the `.chips[hidden]{display:none}` rule is required — the author-level `display:flex` on `.chips` would otherwise override the UA `[hidden]` rule). Group `aria-label`s stay short ("Day loud sections") — the J/K/U/I key explanation lives only in the visible note, per user feedback against repeating info text in labels. The Highlights button is a collapse/expand toggle (`setHlExpanded()` keeps arrow + `aria-expanded` in sync, also from the day-collapse path): a built panel is kept and re-armed from `dayHlSections` instead of recomputing, keyed by `hlRow.dataset.loaded = hlParams()` (margin|gap|minDur string) so changed params force a re-run. The `#dayhls-<dayId>` "· analysed" suffix appears when every file's `cached_analysis` passes `cachedParamsMatch()`; `fetchAnalysis()` updates `f.cached_analysis` client-side so the marker survives re-renders without refetching `/api/files`. **`aria-label` on a button replaces its visible content for screen readers** — any status text rendered inside a labelled button (like the analysed suffix) must be mirrored into the label (render path + the end of `dayHighlights()`), or the blind user never hears it. Likewise, the accessible text of a button built as `aria-hidden arrow span + text node` must not start the text node with a space (the hidden arrow drops out and the leading space reads as an indent) — keep separator spaces inside the aria-hidden span.
 - J/K/U/I/O: single document-level `keydown` listener — clip queue takes priority, in-player `currentTime` stepping is the fallback when no queue is armed; O calls `openClipInFile()` (shared with the "Open in file" button). J/K (and Prev/Next) always step in time order; U/I walk the loudest-first ranking from `scoreOrder()` — no top-N cutoff (the `#clip-top` input and `#clip-hl-only` checkbox were removed deliberately; J/K must never be affected by an auto-advance/highlights setting). Auto-advance is the `input[name="clip-adv"]` radio (off / next in time / next by loudness), read by `advanceMode()`; `stepClip(dir, byScore)` is the shared queue-stepping path. In-player U/I anchor the ranking on the section under the playhead, else start at the loudest.
 - Analysis: `fetchAnalysis()` (session `analysisCache`), `analyse()` (per-row render: meta line with section count + params, then chips — no waveform SVG, see day-review note on the blind user), `cachedParamsMatch()` (autoload guard).
diff --git a/README.md b/README.md
index ad941ca..8a453a5 100644
--- a/README.md
+++ b/README.md
@@ -159,7 +159,7 @@ Shows recordings grouped by day with collapsible sections. Features:
 - **Loudness analysis** — on demand per file; computes RMS per 100 ms window and lists sections that stand out above the background as clickable chips (no visual waveform — the UI is built for screen-reader use). Detection is **adaptive**: a rolling noise floor (20th percentile per 30 s block) is estimated across the file, and a section is flagged when the level rises at least *margin* dB (default 12) above that floor. Slow ambience changes — rain setting in, day/night traffic hum — move the floor instead of producing false positives. Each section gets a **score** used to rank it: its peak dB above the floor, capped by the sharpest rise within 0.5 s. Abrupt events — voices, impacts, barks — rise fast, so their score is their full prominence; a gradual swell (a gust, a distant approaching car) that drifts up faster than the floor can track still gets flagged, but scores near zero and sinks to the bottom of the highlight ranking. Supported for WAV and FLAC (FLAC requires `numpy` + `soundfile`). Pure-Python fallback for WAV when numpy is absent. Results are cached in `recordings/analyses/<filename>.analysis.json`; subsequent requests at the same margin, min-gap, and min-duration settings return instantly without re-reading the audio. The cache file is deleted automatically when the audio file is deleted. Orphaned cache files (audio deleted outside the UI) are pruned on startup.
 - **Grace period** — configurable in the controls bar (default 2 s). Loud sections separated by less than this gap are merged into one. Raise this (e.g. to 15–30 s) when a single event generates many timestamps due to brief quiet gaps within it.
 - **Min duration** — configurable in the controls bar (default 0.5 s). Loud sections shorter than this (after grace-period merging) are discarded, so isolated sub-second pops — a click, a single raindrop — don't flood a day with thousands of near-zero-length sections. Set to 0 to disable.
-- **Clip playback** — clicking a loud-section chip plays a short server-rendered WAV clip (`/api/clip`, pre-roll included) in a player bar at the bottom of the page. Playback starts instantly even for sections deep inside multi-hundred-MB FLACs, because the browser never has to seek the full file. The player bar labels each clip with the wall-clock time it occurred (derived from the recording's filename), its loudness above the background, and its position in the queue, e.g. `17:09:56 to 17:09:57 · +30 dB (30 / 426)` — and the exact same text is announced to screen readers, so the spoken and visible labels never differ. The filename and in-file offset are in the label's hover tooltip. **J** / **K** (or the **Prev** / **Next** buttons) always step through the queued sections in time order — one file's, or a whole day's after **Highlights** — and the position count is then the chronological index (e.g. `30 / 426` is the 30th section in time). **U** / **I** step through the same queue by loudness instead: **I** plays the next-loudest section, **U** goes back up the ranking, and the count becomes the rank in that loudness order (`1 / 426` is the loudest of all reachable sections, `2 / 426` the next-loudest, and so on) — the denominator stays the full count because U/I reaches every section, with no top-N cutoff; the chip list shown on screen is capped only for display. So a day with thousands of detections is reviewed loudest-first for as long as it stays interesting — just stop when it gets boring. Both key pairs drive one shared queue and one cursor, so you can mix them: find a loud moment with **U** / **I**, then press **J** / **K** to review the clips immediately before and after it in time (the count switches from rank back to the chronological index as you do). The auto-advance radio in the player bar picks what happens when a clip ends: **Don't auto-advance**, **Auto-advance** (next section in time), or **Auto-advance highlights only** (next section by loudness) — it never changes what J/K do. Holding **Shift** with any of these jumps to the extreme in that direction — **Shift+J**/**Shift+K** to the first/last section in time, **Shift+U**/**Shift+I** to the loudest/quietest. The same keys work during full-file playback, seeking the open recording to the next section in time (J/K) or by loudness (U/I). **Open in file** (or the **O** key) switches to the full recording at the same position for context; each chip click also pre-fills the cut panel.
+- **Clip playback** — clicking a loud-section chip plays a short server-rendered WAV clip (`/api/clip`, pre-roll included) in a player bar at the bottom of the page. Playback starts instantly even for sections deep inside multi-hundred-MB FLACs, because the browser never has to seek the full file. The player bar labels each clip with the wall-clock time it occurred (derived from the recording's filename), its loudness above the background, and its position in the queue, e.g. `17:09:56 to 17:09:57 · +30 dB (30 / 426 by time)` — and the exact same text is announced to screen readers, so the spoken and visible labels never differ. The filename and in-file offset are in the label's hover tooltip. **J** / **K** (or the **Prev** / **Next** buttons) always step through the queued sections in time order — one file's, or a whole day's after **Highlights** — and the count is then the chronological index, labelled **by time** (e.g. `30 / 426 by time` is the 30th section in time). **U** / **I** step through the same queue by loudness instead: **I** plays the next-loudest section, **U** goes back up the ranking, and the count becomes the rank in that loudness order, labelled **by loudness** (`1 / 426 by loudness` is the loudest of all reachable sections, `2 / 426 by loudness` the next-loudest, and so on) — the denominator stays the full count because U/I reaches every section, with no top-N cutoff; the chip list shown on screen is capped only for display. So a day with thousands of detections is reviewed loudest-first for as long as it stays interesting — just stop when it gets boring. The loudness walk keeps its own position **independently** of J/K: find a loud moment with **U** / **I**, press **J** / **K** to review the clips immediately before and after it in time, and pressing **U** / **I** again resumes the loudness ranking exactly where you left it — the J/K detour never moves your place in the loudest-first walk. (Clicking a chip is an explicit jump, so it re-anchors the next U / I there.) The auto-advance radio in the player bar picks what happens when a clip ends: **Don't auto-advance**, **Auto-advance** (next section in time), or **Auto-advance highlights only** (next section by loudness) — it never changes what J/K do. Holding **Shift** with any of these jumps to the extreme in that direction — **Shift+J**/**Shift+K** to the first/last section in time, **Shift+U**/**Shift+I** to the loudest/quietest. The same keys work during full-file playback, seeking the open recording to the next section in time (J/K) or by loudness (U/I). **Open in file** (or the **O** key) switches to the full recording at the same position for context; each chip click also pre-fills the cut panel.
 - **Cut & download** — `Cut` button opens the player row and reveals a cut panel. Enter start and end times in `m:ss` or `h:mm:ss` format and click **Download cut** to receive an ffmpeg-trimmed copy without re-encoding. Requires ffmpeg (included in the Docker image). The cut is named with the real wall-clock span it covers — `<YYYYMMDD>_<HH-MM-SS>_<HH-MM-SS>.<ext>`, e.g. a 22:31:30→22:32:30 slice of a recording started at 22:00:00 becomes `20260523_22-31-30_22-32-30.flac`.
 - **Filters** — live filename search and from/to date pickers above the table; applied client-side with no additional requests. Shows `N of M shown` when a filter is active.
 - **Delete** — `Delete` button per row with confirmation prompt; disabled for files currently being recorded; sends `DELETE /api/files/<name>` and re-renders the table.
diff --git a/webui.html b/webui.html
index 6381f3c..21f9deb 100644
--- a/webui.html
+++ b/webui.html
@@ -349,12 +349,20 @@ function seekToSection(idx, filename, startSec, endSec, sectionIdx) {
 // day's); J/K and the Prev/Next buttons step through it in time order, U/I
 // step through the loudest-first ranking. The auto-advance radio picks what
 // plays when a clip ends: nothing, the next in time, or the next by loudness.
+//
+// Two cursors, deliberately independent. clipCursor is the time-order position
+// and follows every play (chip click, J/K, U/I). scoreCursor is the loudness
+// walk's own position in scoreOrder(): only U/I (and "highlights only" auto-
+// advance) move it; J/K detours to review nearby clips leave it alone, so
+// coming back to U/I resumes the ranking exactly where you left it. An explicit
+// jump (chip click, new queue) resets it to -1 so the next U/I re-anchors there.
 let clipQueue = [];
 let clipCursor = -1;
+let scoreCursor = -1;
 
 // byScore: this play is part of a loudness walk (U/I or "highlights only"
-// auto-advance), so the position shown is the rank in the loudest-first
-// ranking ("3rd loudest of 426"), not the time-order index.
+// auto-advance), so the position shown is scoreCursor — the rank in the
+// loudest-first ranking, labelled "by loudness" — not the time-order index.
 function playClip(i, byScore) {
   if (i < 0 || i >= clipQueue.length) return;
   clipCursor = i;
@@ -368,13 +376,15 @@ function playClip(i, byScore) {
   // Label = wall-clock time of occurrence (absStart from the filename clock);
   // falls back to in-file offsets for non-standard filenames. The visible
   // label and the screen-reader announcement use one identical string:
-  // "17:09:56 to 17:09:57 · +30 dB (30 / 426)".
+  // "17:09:56 to 17:09:57 · +30 dB (30 / 426 by time)" — the count is the
+  // time-order index "by time" (J/K) or the loudness rank "by loudness" (U/I).
   const when = c.absStart != null
     ? `${fmtClock(c.absStart)} to ${fmtClock(c.absStart + (c.end - c.start))}`
     : `${fmtDur(c.start)} to ${fmtDur(c.end)}`;
   const score = c.score != null ? ` · +${Math.round(c.score)} dB` : '';
-  const pos   = byScore ? scoreOrder(clipQueue).indexOf(i) : i;
-  const text  = `${when}${score} (${pos + 1} / ${clipQueue.length})`;
+  const pos   = byScore ? scoreCursor : i;
+  const dim   = byScore ? 'by loudness' : 'by time';
+  const text  = `${when}${score} (${pos + 1} / ${clipQueue.length} ${dim})`;
   const label = document.getElementById('clip-label');
   label.textContent = text;
   label.title = `${c.filename} @ ${fmtDur(c.start)}–${fmtDur(c.end)}`;
@@ -392,6 +402,7 @@ function hideClipBar() {
   document.body.classList.remove('clip-open');
   clipQueue = [];
   clipCursor = -1;
+  scoreCursor = -1;
 }
 
 function playFileSection(idx, filename, si) {
@@ -400,6 +411,7 @@ function playFileSection(idx, filename, si) {
   const epoch = f ? fileStartEpoch(f.date) : null;
   clipQueue = secs.map(s => ({fileIdx: idx, filename, start: s.start, end: s.end, score: s.score,
                               absStart: epoch != null ? epoch + s.start : null}));
+  scoreCursor = -1;                 // explicit jump: next U/I re-anchors here
   playClip(si);
 }
 
@@ -422,14 +434,23 @@ const advanceMode = () =>
 function stepClip(dir, byScore, jump) {
   if (!clipQueue.length) return;
   if (byScore) {
+    // Walk scoreCursor, not the shared clipCursor: a J/K detour never moved
+    // it, so we resume the ranking where we left off. scoreCursor === -1 means
+    // the walk hasn't started since the queue was armed or an explicit jump —
+    // anchor on the section currently selected (clipCursor), else the loudest.
     const order = scoreOrder(clipQueue);
-    const pos   = order.indexOf(clipCursor);        // -1: nothing played yet
-    const next  = jump ? (dir > 0 ? order.length - 1 : 0)
-                       : pos === -1 ? (dir > 0 ? 0 : -1) : pos + dir;
-    if (next >= 0 && next < order.length) playClip(order[next], true);
+    let next;
+    if (jump) next = dir > 0 ? order.length - 1 : 0;
+    else if (scoreCursor !== -1) next = scoreCursor + dir;
+    else {
+      const anchor = clipCursor >= 0 ? order.indexOf(clipCursor) : -1;
+      next = anchor === -1 ? (dir > 0 ? 0 : -1) : anchor + dir;
+    }
+    if (next >= 0 && next < order.length) { scoreCursor = next; playClip(order[next], true); }
     else announce(dir < 0 ? 'Loudest highlight reached' : 'End of highlights');
     return;
   }
+  // J/K (time order) deliberately does NOT touch scoreCursor.
   const i = jump ? (dir > 0 ? clipQueue.length - 1 : 0) : clipCursor + dir;
   if (i >= 0 && i < clipQueue.length) playClip(i);
   else announce(dir < 0 ? 'Beginning of sections' : 'End of sections');
@@ -926,6 +947,7 @@ function renderFiles(files) {
           dayActiveId = dayId;
           clipQueue = dayActiveSections;
           clipCursor = -1;
+          scoreCursor = -1;
           return;
         }
         dayHighlights(dayId, hlFiles);
@@ -1016,6 +1038,7 @@ async function dayHighlights(dayId, analyzableFiles) {
   // Arm the clip queue so J/K steps through the day immediately
   clipQueue = dayActiveSections;
   clipCursor = -1;
+  scoreCursor = -1;
 
   const box = document.createElement('div');
   box.className = 'wbox';
@@ -1102,6 +1125,7 @@ async function dayHighlights(dayId, analyzableFiles) {
 function jumpToDaySection(si) {
   if (si < 0 || si >= dayActiveSections.length) return;
   clipQueue = dayActiveSections;
+  scoreCursor = -1;                 // explicit jump: next U/I re-anchors here
   playClip(si);
 }