From 2b0403d05d40179d9d0358eeba70825ee63de3ae Mon Sep 17 00:00:00 2001
From: jonathan <webmaster@jonathan859.com>
Date: Fri, 12 Jun 2026 08:28:23 +0200
Subject: [PATCH] feat: wall-clock clip labels, collapsible day Highlights with
 analysed marker

- Clip bar label is now the wall-clock time of occurrence plus queue
  position ("03:46:20 to 03:46:22 (73 / 187)"); filename and score moved
  to the hover tooltip. Works for both per-file and day queues via an
  absStart epoch on every queue entry, derived from the filename clock
  (listing date), falling back to in-file offsets for non-standard names.
- Day Highlights button toggles the panel; re-expanding reuses the
  already-built results (re-armed J/K queue from dayHlSections) and only
  recomputes when margin/gap/min-duration changed. A "analysed" suffix
  marks days where every file has a cached analysis for the current
  params; fetchAnalysis keeps f.cached_analysis fresh client-side.
- Day timeline now positions files by the filename clock instead of
  mtime-duration, and the three axis labels (span start / midpoint /
  end) carry explanatory tooltips.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 CLAUDE.md  |   4 +-
 README.md  |   4 +-
 webui.html | 114 +++++++++++++++++++++++++++++++++++++++++++----------
 3 files changed, 98 insertions(+), 24 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 9d72034..d3a1383 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -38,8 +38,8 @@ 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.
-- Day review: `dayHighlights()` builds `dayActiveSections` (chronological); `jumpToDaySection()` arms the queue.
+- 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.
 - Analysis: `fetchAnalysis()` (session `analysisCache`), `analyse()` (per-row render), `cachedParamsMatch()` (autoload guard).
 
diff --git a/README.md b/README.md
index 043d7e2..6c38c31 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. Orange segments show when loud sections occurred relative to the day's time span; blue shows the file extents. Labels show the start, midpoint, and end times. 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 only the top-scored highlights.
 - **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. **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) 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.
 - **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 4399d5a..d917228 100644
--- a/webui.html
+++ b/webui.html
@@ -115,6 +115,8 @@ button.cut:hover:not(:disabled){background:#1e3a8a}
 button.day-hl{color:var(--green);border-color:#166534;background:#052e16;font-size:11px}
 button.day-hl:hover:not(:disabled){background:#0a3d1f}
 button.day-hl:disabled{opacity:.5;cursor:default}
+button.day-hl .day-arrow{font-size:9px}
+.day-hl-status{opacity:.75;font-weight:400}
 h2.day-heading{margin:0;font-size:inherit;font-weight:inherit;line-height:inherit;flex:1 1 auto}
 .day-hl-container{background:var(--bg);border:1px solid var(--brd);border-top:none;padding:8px 12px 12px}
 table.day-table{width:100%;border-collapse:collapse;border:1px solid var(--brd);border-top:none}
@@ -205,6 +207,17 @@ const fmtSize = b => {
   return (b/(1<<30)).toFixed(2)+' GB';
 };
 const pad = n => String(n).padStart(2,'0');
+// Epoch seconds -> local wall-clock "HH:MM:SS"
+const fmtClock = ts => {
+  const d = new Date(ts * 1000);
+  return pad(d.getHours()) + ':' + pad(d.getMinutes()) + ':' + pad(d.getSeconds());
+};
+// Listing `date` ("YYYY-MM-DD HH:MM:SS", the recording start parsed out of
+// the filename server-side) -> epoch seconds, or null for unparseable values
+const fileStartEpoch = date => {
+  const t = Date.parse(String(date).replace(' ', 'T'));
+  return isNaN(t) ? null : t / 1000;
+};
 
 function announce(msg) {
   const el = document.getElementById('sr-announce');
@@ -235,6 +248,23 @@ const dayExpanded = new Map();
 // cross-file day section list (populated by the day Highlights button)
 let dayActiveSections = [];
 let dayActiveId = null;
+// dayId -> section list of an already-built highlights panel, so collapsing
+// and re-expanding it re-arms J/K without recomputing
+const dayHlSections = new Map();
+
+// Current analysis params as one string; a highlights panel built with other
+// values is stale and gets recomputed on the next expand
+const hlParams = () =>
+  ['margin-input', 'min-gap-input', 'min-duration-input']
+    .map(id => document.getElementById(id).value).join('|');
+
+function setHlExpanded(dayId, exp) {
+  const btn = document.getElementById('dayhln-' + dayId);
+  if (!btn) return;
+  btn.setAttribute('aria-expanded', exp);
+  const arrow = btn.querySelector('.day-arrow');
+  if (arrow) arrow.textContent = exp ? '▾' : '▸';
+}
 
 function groupByDay(files) {
   const map = new Map();
@@ -368,13 +398,19 @@ function playClip(i) {
   a.src = '/api/clip?file=' + encodeURIComponent(c.filename)
         + '&start=' + cs.toFixed(1) + '&end=' + ce.toFixed(1);
   a.play().catch(() => {});
-  document.getElementById('clip-label').textContent =
-    `${i + 1}/${clipQueue.length} · ${c.filename} @ ${fmtDur(c.start)}–${fmtDur(c.end)}`
+  // Label = wall-clock time of occurrence (absStart from the filename clock);
+  // falls back to in-file offsets for non-standard filenames.
+  const when = c.absStart != null
+    ? `${fmtClock(c.absStart)} to ${fmtClock(c.absStart + (c.end - c.start))}`
+    : `${fmtDur(c.start)} to ${fmtDur(c.end)}`;
+  const label = document.getElementById('clip-label');
+  label.textContent = `${when} (${i + 1} / ${clipQueue.length})`;
+  label.title = `${c.filename} @ ${fmtDur(c.start)}–${fmtDur(c.end)}`
     + (c.score != null ? ` · +${Math.round(c.score)} dB` : '');
   document.getElementById('clip-bar').hidden = false;
   document.body.classList.add('clip-open');
   setCutFields(c.fileIdx, c.start, c.end);
-  announce(`Clip ${i + 1} of ${clipQueue.length}: ${fmtDur(c.start)} to ${fmtDur(c.end)} in ${c.filename}`);
+  announce(`Clip ${i + 1} of ${clipQueue.length}: ${when}`);
 }
 
 function hideClipBar() {
@@ -388,8 +424,11 @@ function hideClipBar() {
 }
 
 function playFileSection(idx, filename, si) {
-  const secs = sectionMap.get(idx) || [];
-  clipQueue = secs.map(s => ({fileIdx: idx, filename, start: s.start, end: s.end, score: s.score}));
+  const secs  = sectionMap.get(idx) || [];
+  const f     = allFiles.find(f => f._idx === idx);
+  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}));
   playClip(si);
 }
 
@@ -454,7 +493,13 @@ async function fetchAnalysis(filename, margin, minGap, minDur, force = false) {
     +'&min_gap='+encodeURIComponent(minGap)
     +'&min_duration='+encodeURIComponent(minDur));
   const d = await r.json();
-  if (!d.error) analysisCache.set(key, d);
+  if (!d.error) {
+    analysisCache.set(key, d);
+    // Keep the listing's cache info current so re-renders (filtering) still
+    // know the file is analysed without refetching /api/files
+    const f = allFiles.find(f => f.name === filename);
+    if (f) f.cached_analysis = {margin, min_gap: minGap, min_duration: minDur};
+  }
   return d;
 }
 
@@ -712,7 +757,11 @@ function renderFiles(files) {
 
     const totalSize = dayFiles.reduce((a, f) => a + f.size, 0);
     const totalDur  = dayFiles.reduce((a, f) => a + (f.duration || 0), 0);
-    const canHl     = dayFiles.some(f => (f.ext === 'wav' || f.ext === 'flac') && !f.recording);
+    const hlFiles   = dayFiles.filter(f => (f.ext === 'wav' || f.ext === 'flac') && !f.recording);
+    const canHl     = hlFiles.length > 0;
+    // Every analysable file already has a cached analysis for the current
+    // params -> the day's highlights are available without recomputing
+    const analysed  = canHl && hlFiles.every(f => cachedParamsMatch(f.cached_analysis));
     const durStr    = totalDur > 0 ? ' · ' + fmtDur(Math.round(totalDur)) : '';
     const sizeStr   = ' · ' + fmtSize(totalSize);
     const fileStr   = `${dayFiles.length} file${dayFiles.length !== 1 ? 's' : ''}`;
@@ -737,7 +786,10 @@ function renderFiles(files) {
         </button>
       </h2>
       ${canHl ? `<button class="day-hl" id="dayhln-${dayId}"
-        aria-label="Show day highlights for ${esc(day)}">Highlights</button>` : ''}`;
+        aria-expanded="false" aria-controls="dayhl-${dayId}"
+        aria-label="Day highlights for ${esc(day)}">
+        <span class="day-arrow" aria-hidden="true">▸</span> Highlights<span
+          class="day-hl-status" id="dayhls-${dayId}"${analysed ? '' : ' hidden'}> · analysed</span></button>` : ''}`;
     section.appendChild(headBar);
 
     // Highlights panel (hidden until button clicked)
@@ -850,6 +902,7 @@ function renderFiles(files) {
       if (!nowExp) {
         dayFiles.forEach(f => closePlayer(f._idx));
         document.getElementById('dayhl-' + dayId).hidden = true;
+        setHlExpanded(dayId, false);
         if (dayActiveId === dayId) {
           dayActiveSections = [];
           dayActiveId = null;
@@ -858,10 +911,25 @@ function renderFiles(files) {
       }
     });
 
-    // Highlights button handler
+    // Highlights button: expand/collapse the panel; only (re)compute when it
+    // has not been built yet this session or the analysis params changed
     if (canHl) {
       document.getElementById('dayhln-' + dayId)?.addEventListener('click', () => {
-        const hlFiles = dayFiles.filter(f => (f.ext === 'wav' || f.ext === 'flac') && !f.recording);
+        const hlRow = document.getElementById('dayhl-' + dayId);
+        if (!hlRow.hidden) {                       // collapse, keep the panel
+          hlRow.hidden = true;
+          setHlExpanded(dayId, false);
+          return;
+        }
+        if (hlRow.dataset.loaded === hlParams()) { // re-open and re-arm J/K
+          hlRow.hidden = false;
+          setHlExpanded(dayId, true);
+          dayActiveSections = dayHlSections.get(dayId) || [];
+          dayActiveId = dayId;
+          clipQueue = dayActiveSections;
+          clipCursor = -1;
+          return;
+        }
         dayHighlights(dayId, hlFiles);
       });
     }
@@ -874,6 +942,7 @@ async function dayHighlights(dayId, analyzableFiles) {
   const btn      = document.getElementById('dayhln-' + dayId);
 
   hlRow.hidden = false;
+  setHlExpanded(dayId, true);
   const n = analyzableFiles.length;
   if (btn) btn.disabled = true;
 
@@ -912,12 +981,14 @@ async function dayHighlights(dayId, analyzableFiles) {
     return;
   }
 
-  // Map files onto the day timeline using mtime as file-end, duration for start
+  // Map files onto the day timeline. The filename is the clock: f.date is the
+  // recording start parsed server-side; mtime (≈ file end) is only a fallback
+  // for non-standard names.
   const positioned = results.map(({ f, data }) => {
-    const fileEnd   = f.mtime;
     const fileDur   = data.duration || f.duration || 0;
-    const fileStart = fileEnd - fileDur;
-    return { f, data, fileStart, fileEnd, fileDur };
+    const startEpoch = fileStartEpoch(f.date);
+    const fileStart = startEpoch != null ? startEpoch : f.mtime - fileDur;
+    return { f, data, fileStart, fileEnd: fileStart + fileDur, fileDur };
   }).filter(r => r.fileDur > 0);
 
   if (!positioned.length) {
@@ -1005,7 +1076,9 @@ async function dayHighlights(dayId, analyzableFiles) {
 
   const labels = document.createElement('div');
   labels.className = 'day-tl-labels';
-  labels.innerHTML = `<span>${esc(fmtHM(minT))}</span><span>${esc(fmtHM((minT+maxT)/2))}</span><span>${esc(fmtHM(maxT))}</span>`;
+  labels.innerHTML = `<span title="First recording starts">${esc(fmtHM(minT))}</span>`
+    + `<span title="Timeline midpoint">${esc(fmtHM((minT+maxT)/2))}</span>`
+    + `<span title="Last recording ends">${esc(fmtHM(maxT))}</span>`;
   box.appendChild(labels);
 
   if (dayActiveSections.length) {
@@ -1032,11 +1105,7 @@ async function dayHighlights(dayId, analyzableFiles) {
       const c = document.createElement('button');
       c.className = 'chip';
       c.title = sec.filename + ' @ ' + fmtDur(sec.start);
-      const d = new Date(sec.absStart * 1000);
-      const hms = d.getHours().toString().padStart(2,'0') + ':'
-                + d.getMinutes().toString().padStart(2,'0') + ':'
-                + d.getSeconds().toString().padStart(2,'0');
-      c.textContent = hms + (sec.score != null ? ` · +${Math.round(sec.score)} dB` : '');
+      c.textContent = fmtClock(sec.absStart) + (sec.score != null ? ` · +${Math.round(sec.score)} dB` : '');
       c.addEventListener('click', () => jumpToDaySection(si));
       chips.appendChild(c);
     });
@@ -1051,6 +1120,11 @@ async function dayHighlights(dayId, analyzableFiles) {
 
   contentEl.innerHTML = '';
   contentEl.appendChild(box);
+  hlRow.dataset.loaded = hlParams();
+  dayHlSections.set(dayId, dayActiveSections);
+  // Every file is now cached with the current params
+  if (results.length === n)
+    document.getElementById('dayhls-' + dayId)?.removeAttribute('hidden');
   if (btn) btn.disabled = false;
 }