From 98d2d7085d39bc7bb6753fd9403286077cfe0179 Mon Sep 17 00:00:00 2001
From: jonathan <webmaster@jonathan859.com>
Date: Fri, 12 Jun 2026 08:35:31 +0200
Subject: [PATCH] feat: auto-advance radio, J/K decoupled from highlights, U/I
 ranked stepping

- J/K and Prev/Next now always step the clip queue in time order; the old
  "Highlights only" checkbox could silently change what J/K did.
- Auto-advance is a three-way radio: don't auto-advance / auto-advance
  (next in time) / auto-advance highlights only (next by loudness). It
  only affects what plays when a clip ends.
- The "Top" highlight-count input is gone. U/I (and highlights-only
  auto-advance) walk the full loudest-first ranking from scoreOrder()
  with no top-N cutoff - review simply stops when the user stops.
- In-player U/I (full-file playback) step the same ranking, anchored on
  the section under the playhead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md  |   2 +-
 README.md  |   6 +--
 webui.html | 115 ++++++++++++++++++++++++++++++-----------------------
 3 files changed, 70 insertions(+), 53 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index d3a1383..0840ae1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,7 +40,7 @@ Dependencies: `requests` (streams), `numpy` + `soundfile` (FLAC output and FLAC
 `webui.html` (one `<script>` block):
 - Clip review: `clipQueue`/`clipCursor` globals, `playClip()`, `playFileSection()`, `hideClipBar()`; markup is the `#clip-bar` div. The clip label shows the wall-clock occurrence time + queue position (`03:46:20 to 03:46:22 (73 / 187)`): queue entries carry `absStart` (epoch s), derived from `fileStartEpoch(f.date)` — the filename clock — with in-file offsets as fallback for non-standard names; filename/score live in the label tooltip.
 - Day review: `dayHighlights()` builds `dayActiveSections` (chronological); `jumpToDaySection()` arms the queue. The day timeline positions files by `fileStartEpoch(f.date)` (filename clock), mtime−duration only as fallback. 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`.
-- 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). U/I (and the `#clip-hl-only` checkbox, which also affects J/K, Prev/Next, and auto-advance) restrict stepping to highlights: the top `#clip-top` (default 50) sections by score, computed on demand by `topScoreSet()`; `stepClip()` is the shared queue-stepping path.
+- 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), `cachedParamsMatch()` (autoload guard).
 
 ## Verifying changes
diff --git a/README.md b/README.md
index 6c38c31..2b3637c 100644
--- a/README.md
+++ b/README.md
@@ -154,12 +154,12 @@ The browser UI (HTML/CSS/JS) lives in `webui.html`, which `web.py` loads at star
 Shows recordings grouped by day with collapsible sections. Features:
 
 - **Day groups** — recordings are grouped under a collapsible day heading showing date, file count, total duration, and total size. The most recent day is expanded by default; older days start collapsed. Expanded state is preserved across filter changes.
-- **Day highlights** — click **Highlights** on any day heading to run loudness analysis across all WAV/FLAC files in that day and display a combined activity timeline SVG. The button is a toggle: clicking again collapses the panel, and re-expanding it reuses the already-computed results (they are only recomputed when the analysis parameters change). A **· analysed** suffix on the button marks days where every file already has a cached analysis for the current parameters, i.e. highlights open instantly. Orange segments show when loud sections occurred relative to the day's time span; blue shows the file extents. The labels under the timeline are the wall-clock start of the first recording, the timeline midpoint, and the end of the last recording. When a day has more sections than fit as chips, the chips show the top 50 by score (loudest-above-background first) so the most promising events are reviewed first; J/K still steps through all sections in time order, and U/I steps through only the top-scored highlights.
+- **Day highlights** — click **Highlights** on any day heading to run loudness analysis across all WAV/FLAC files in that day and display a combined activity timeline SVG. The button is a toggle: clicking again collapses the panel, and re-expanding it reuses the already-computed results (they are only recomputed when the analysis parameters change). A **· analysed** suffix on the button marks days where every file already has a cached analysis for the current parameters, i.e. highlights open instantly. Orange segments show when loud sections occurred relative to the day's time span; blue shows the file extents. The labels under the timeline are the wall-clock start of the first recording, the timeline midpoint, and the end of the last recording. When a day has more sections than fit as chips, the chips show the top 50 by score (loudest-above-background first) so the most promising events are reviewed first; J/K still steps through all sections in time order, and U/I steps through them by loudness.
 - **Inline playback** — collapsible `Play` button per row; audio loads lazily via a seekable `/stream/` endpoint with HTTP Range support. Metadata is fetched immediately so the duration is visible without pressing play.
 - **Waveform analysis** — on demand per file; computes RMS per 100 ms window and marks sections that stand out above the background. 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) and its position in the queue, e.g. `03:46:20 to 03:46:22 (73 / 187)`; the filename and score are in the label's hover tooltip. **J** / **K** (or the **Prev** / **Next** buttons) step through the queued sections — one file's, or a whole day's after **Highlights** — and **Auto-advance** plays the next section when one ends, turning a day's detections into a continuous review reel. **U** / **I** step through *highlights only*: the top-scored sections of the queue (count set by the **Top** input in the player bar, default 50). Ticking **Highlights only** makes J/K, Prev/Next, and Auto-advance skip non-highlights too, so a day with thousands of detections can be reviewed as a short reel of just the loudest events. The same keys work during full-file playback, seeking the open recording between (highlight) sections. **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) and its position in the queue, e.g. `03:46:20 to 03:46:22 (73 / 187)`; the filename and score 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**. **U** / **I** step through the same queue by loudness instead: **I** plays the next-loudest section, **U** goes back up the ranking, so a day with thousands of detections is reviewed loudest-first for as long as it stays interesting — there is no top-N cutoff, just stop when it gets boring. 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. 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.
@@ -172,7 +172,7 @@ Shows recordings grouped by day with collapsible sections. Features:
 
 The detector is purely energy-based: anything that rises *margin* dB above the rolling background floor for at least *min duration* seconds is flagged. In a quiet environment the floor sits very low, so even modest sounds — a gust, a distant car, rustling — clear the margin, and an outdoor day can easily produce over a thousand sections. What to adjust, in rough order of preference:
 
-1. **Review by rank instead of thinning the list** — tick **Highlights only** (or use **U**/**I**) to step through just the top-scored sections. Scores favour sharp onsets, so slow ambience swells sort themselves to the bottom automatically. Nothing is discarded — quieter events are still there if the top of the list comes up empty.
+1. **Review by rank instead of thinning the list** — use **U**/**I** (or **Auto-advance highlights only**) to step through the sections loudest-first. Scores favour sharp onsets, so slow ambience swells sort themselves to the bottom automatically. Nothing is discarded and there is no cutoff — just stop when the events stop being interesting.
 2. **Raise the grace period** (2 → 15–30 s) — merges clusters of related noise (a rain burst, one long conversation) into a single section. Cuts the count heavily without dropping any audio from review.
 3. **Raise the margin** (12 → 15–18 dB) — demands more prominence above the background. The quietest events disappear first, so move in small steps.
 4. **Raise min duration** (0.5 → 1–2 s) — drops short rustles and pops, but beware: single bangs or knocks are themselves short.
diff --git a/webui.html b/webui.html
index d917228..36b2cd5 100644
--- a/webui.html
+++ b/webui.html
@@ -133,9 +133,9 @@ svg.day-timeline{display:block;width:100%;height:22px}
 #clip-bar audio{flex:1 1 240px;min-width:180px;height:32px}
 #clip-label{font-size:12px;color:var(--muted);font-family:ui-monospace,monospace;
   white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:38%}
-#clip-auto-label,#clip-hl-label,#clip-top-label{font-size:12px;color:var(--muted);
+#clip-adv{display:flex;align-items:center;gap:10px}
+#clip-adv label{font-size:12px;color:var(--muted);
   display:flex;align-items:center;gap:4px;white-space:nowrap;cursor:pointer}
-#clip-top{width:52px}
 body.clip-open{padding-bottom:70px}
 </style>
 </head>
@@ -184,9 +184,11 @@ body.clip-open{padding-bottom:70px}
   <button id="clip-next" aria-label="Next section (K)">Next</button>
   <span id="clip-label"></span>
   <audio id="clip-audio" controls preload="auto" aria-label="Section clip playback"></audio>
-  <label id="clip-auto-label"><input type="checkbox" id="clip-auto" checked> Auto-advance</label>
-  <label id="clip-hl-label" title="J/K, Prev/Next and auto-advance skip everything outside the top sections"><input type="checkbox" id="clip-hl-only"> Highlights only</label>
-  <label id="clip-top-label" title="How many top-scored sections count as highlights">Top <input type="number" id="clip-top" min="1" step="1" value="50" aria-label="Number of top-scored sections treated as highlights"></label>
+  <span id="clip-adv" role="radiogroup" aria-label="Auto-advance mode">
+    <label><input type="radio" name="clip-adv" value="off"> Don't auto-advance</label>
+    <label><input type="radio" name="clip-adv" value="all" checked> Auto-advance</label>
+    <label title="When a clip ends, play the next-loudest section instead of the next in time"><input type="radio" name="clip-adv" value="hl"> Auto-advance highlights only</label>
+  </span>
   <button id="clip-context" title="Open the full recording at this position (O)" aria-label="Open in file (O)">Open in file</button>
   <button id="clip-close" aria-label="Close clip player">&times;</button>
 </div>
@@ -383,8 +385,9 @@ function seekToSection(idx, filename, startSec, endSec, sectionIdx) {
 // Sections play as small server-rendered WAV clips (/api/clip) in the bottom
 // bar instead of seeking the full recording, which is slow for big FLACs.
 // clipQueue holds the active review list (one file's sections, or a whole
-// day's); J/K and the Prev/Next buttons step through it, U/I (or the
-// "Highlights only" toggle) restrict stepping to the top-N entries by score.
+// 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.
 let clipQueue = [];
 let clipCursor = -1;
 
@@ -432,37 +435,42 @@ function playFileSection(idx, filename, si) {
   playClip(si);
 }
 
-// Highlights = the top-N entries of a section list by score (N from the
-// clip-bar "Top" input). Returns the indices into the original list.
-function topScoreSet(secs) {
-  const n = Math.max(1, parseInt(document.getElementById('clip-top').value, 10) || 50);
-  return new Set(secs.map((s, i) => ({i, score: s.score || 0}))
+// Highlight order = section indices sorted loudest-first. U/I (and
+// auto-advance in "highlights only" mode) walk this ranking, so a review
+// runs from the most to the least interesting event until the user stops —
+// no top-N cutoff.
+function scoreOrder(secs) {
+  return secs.map((s, i) => ({i, score: s.score || 0}))
     .sort((a, b) => b.score - a.score)
-    .slice(0, n)
-    .map(r => r.i));
+    .map(r => r.i);
 }
 
-function highlightsOnly() {
-  return document.getElementById('clip-hl-only').checked;
-}
+const advanceMode = () =>
+  document.querySelector('input[name="clip-adv"]:checked')?.value || 'off';
 
-// Step the clip queue by dir (±1); with hlOnly, skip non-highlight entries.
-function stepClip(dir, hlOnly) {
+// Step the clip queue by dir (±1): in time order, or with byScore down/up
+// the loudest-first ranking (next = next quieter).
+function stepClip(dir, byScore) {
   if (!clipQueue.length) return;
-  const hs = hlOnly ? topScoreSet(clipQueue) : null;
-  const word = hlOnly ? 'highlights' : 'sections';
-  for (let i = clipCursor + dir; i >= 0 && i < clipQueue.length; i += dir) {
-    if (!hs || hs.has(i)) { playClip(i); return; }
+  if (byScore) {
+    const order = scoreOrder(clipQueue);
+    const pos   = order.indexOf(clipCursor);        // -1: nothing played yet
+    const next  = pos === -1 ? (dir > 0 ? 0 : -1) : pos + dir;
+    if (next >= 0 && next < order.length) playClip(order[next]);
+    else announce(dir < 0 ? 'Loudest highlight reached' : 'End of highlights');
+    return;
   }
-  announce(dir < 0 ? `Beginning of ${word}` : `End of ${word}`);
+  const i = clipCursor + dir;
+  if (i >= 0 && i < clipQueue.length) playClip(i);
+  else announce(dir < 0 ? 'Beginning of sections' : 'End of sections');
 }
 
-document.getElementById('clip-prev').addEventListener('click', () => stepClip(-1, highlightsOnly()));
-document.getElementById('clip-next').addEventListener('click', () => stepClip(1, highlightsOnly()));
+document.getElementById('clip-prev').addEventListener('click', () => stepClip(-1, false));
+document.getElementById('clip-next').addEventListener('click', () => stepClip(1, false));
 document.getElementById('clip-close').addEventListener('click', hideClipBar);
 document.getElementById('clip-audio').addEventListener('ended', () => {
-  if (document.getElementById('clip-auto').checked)
-    stepClip(1, highlightsOnly());
+  const mode = advanceMode();
+  if (mode !== 'off') stepClip(1, mode === 'hl');
 });
 // "Open in file": switch from the current clip to the full recording at the
 // same position. Bound to the clip-bar button and the O key.
@@ -531,7 +539,7 @@ async function analyse(idx, filename, cell, btn, force = false) {
     const chips = document.createElement('div');
     chips.className='chips';
     chips.setAttribute('role','group');
-    chips.setAttribute('aria-label','Loud sections — click to jump, J/K to step, U/I for highlights only');
+    chips.setAttribute('aria-label','Loud sections — click to jump, J/K to step in time order, U/I by loudness');
     if (d.sections && d.sections.length) {
       sectionMap.set(idx, d.sections);
       d.sections.forEach((s, si) => {
@@ -564,9 +572,8 @@ async function analyse(idx, filename, cell, btn, force = false) {
   }
 }
 
-// J/K = previous/next section, U/I = previous/next highlight (top-N by score),
-// O = open the current clip in the full file.
-// With "Highlights only" checked, J/K behave like U/I.
+// J/K = previous/next section in time order, U/I = up/down the loudest-first
+// ranking, O = open the current clip in the full file.
 // Only when focus is not in an input.
 document.addEventListener('keydown', e => {
   if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
@@ -575,12 +582,12 @@ document.addEventListener('keydown', e => {
   if (key !== 'j' && key !== 'k' && key !== 'u' && key !== 'i' && key !== 'o') return;
   e.preventDefault();
   if (key === 'o') { openClipInFile(); return; }
-  const dir    = (key === 'j' || key === 'u') ? -1 : 1;
-  const hlOnly = key === 'u' || key === 'i' || highlightsOnly();
+  const dir     = (key === 'j' || key === 'u') ? -1 : 1;
+  const byScore = key === 'u' || key === 'i';
 
   // Clip queue navigation (a chip was clicked or day highlights are loaded)
   if (clipQueue.length) {
-    stepClip(dir, hlOnly);
+    stepClip(dir, byScore);
     return;
   }
 
@@ -590,29 +597,39 @@ document.addEventListener('keydown', e => {
   if (!all.length) return;
   const audio = document.getElementById('aud-'+activePlayerIdx);
   if (!audio) return;
-  const hs = hlOnly ? topScoreSet(all) : null;
-  const sections = all.filter((s, i) => !hs || hs.has(i));
-  if (!sections.length) return;
   const preroll = getPreroll();
   const cur  = audio.currentTime;
-  const word = hlOnly ? 'Highlight' : 'Section';
 
-  const jumpTo = (s, i) => {
+  const jumpTo = (s, i, n, word) => {
     audio.currentTime = Math.max(0, s.start - preroll);
     setCutFields(activePlayerIdx, s.start, s.end);
-    announce(`${word} ${i + 1} of ${sections.length}: ${fmtDur(s.start)} to ${fmtDur(s.end)}`);
+    announce(`${word} ${i + 1} of ${n}: ${fmtDur(s.start)} to ${fmtDur(s.end)}`);
   };
 
+  if (byScore) {
+    // U/I walk the ranking; the anchor is the section the playhead sits in
+    // (incl. its preroll lead-in). Anywhere else, I starts at the loudest.
+    const order  = scoreOrder(all);
+    const curIdx = all.findIndex(s => cur >= s.start - preroll - 0.5 && cur <= s.end + 0.5);
+    const pos    = curIdx === -1 ? -1 : order.indexOf(curIdx);
+    const next   = pos === -1 ? (dir > 0 ? 0 : -1) : pos + dir;
+    if (next >= 0 && next < order.length)
+      jumpTo(all[order[next]], next, order.length, 'Highlight');
+    else
+      announce(dir < 0 ? 'Loudest highlight reached' : 'End of highlights');
+    return;
+  }
+
   if (dir < 0) {
-    for (let i = sections.length - 1; i >= 0; i--) {
-      if (sections[i].start < cur - 1) { jumpTo(sections[i], i); return; }
+    for (let i = all.length - 1; i >= 0; i--) {
+      if (all[i].start < cur - 1) { jumpTo(all[i], i, all.length, 'Section'); return; }
     }
-    announce(`Beginning of ${word.toLowerCase()}s`);
+    announce('Beginning of sections');
   } else {
-    for (let i = 0; i < sections.length; i++) {
-      if (sections[i].start > cur + preroll) { jumpTo(sections[i], i); return; }
+    for (let i = 0; i < all.length; i++) {
+      if (all[i].start > cur + preroll) { jumpTo(all[i], i, all.length, 'Section'); return; }
     }
-    announce(`End of ${word.toLowerCase()}s`);
+    announce('End of sections');
   }
 });
 
@@ -1094,13 +1111,13 @@ async function dayHighlights(dayId, analyzableFiles) {
       const note = document.createElement('p');
       note.className = 'quiet';
       note.style.marginTop = '6px';
-      note.textContent = `${dayActiveSections.length} sections — chips show the top ${MAX_DAY_CHIPS} by loudness; J / K steps through all in time order, U / I through highlights only`;
+      note.textContent = `${dayActiveSections.length} sections — chips show the top ${MAX_DAY_CHIPS} by loudness; J / K steps through all in time order, U / I by loudness (loudest first)`;
       box.appendChild(note);
     }
     const chips = document.createElement('div');
     chips.className = 'chips';
     chips.setAttribute('role', 'group');
-    chips.setAttribute('aria-label', 'Day loud sections — click to jump, J/K to step across files, U/I for highlights only');
+    chips.setAttribute('aria-label', 'Day loud sections — click to jump, J/K to step across files in time order, U/I by loudness');
     chipList.forEach(({sec, si}) => {
       const c = document.createElement('button');
       c.className = 'chip';