The FastAPI backend kept one analysis session shared by every visitor and
spooled each upload to the server's /tmp, and the browser copied audio into
persistent OPFS storage. None of that fits a tool for unreleased masters, so
the web UI is now a static site that decodes and analyses in the tab:
- web/decode.js: WAV/AIFF PCM and float read directly with libsndfile's
scaling (bit-identical to librosa.load; Chromium's WAV decoder scales
positive int16 by 1/32767), other formats via decodeAudioData on an
OfflineAudioContext at the header-sniffed native rate. ID3 song names.
- web/dsp.js: ports of every Metric.compute with the same numerics
(pyloudnorm K-weighting via lfilter's DF2T recurrence, BS.1770 gating,
EBU LRA, resample_poly's Kaiser filter for true peak, librosa.stft and
amplitude_to_db), streaming passes with no signal-length intermediates.
- web/metrics.js: build_spec ports producing the existing plot payload.
- web/analysis-worker.js + app.js: per-tab track list and result cache, a
worker job queue where the visible metric jumps background prefetch, and
the renderer, which now also draws the metrics' own reference lines.
Deployment is nginx-unprivileged serving web/ read-only with
Content-Security-Policy connect-src 'none', so the page cannot make network
requests at all, and no access log. No secure context is needed, so plain
http on a LAN works. The Python web backend, its smoke test, the web extra
and the OPFS store are removed; the desktop app is unchanged.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UXA39Sh9coAx4FhRkd8R2
Multi-stage image built from the `web` extra only, so it carries no Qt: the
whole web path (webapp, web_session, metrics_json, and the shared analysis
modules) imports no Qt, pyqtgraph or matplotlib canvas. The build stage has the
compiler scipy/numba need; the runtime layer installs the built wheel, so the
same image works from a checkout or a release tarball.
Compose declares no audio volume on purpose. The app keeps no audio, so there is
nothing to persist: `read_only` plus a /tmp tmpfs means request spools are
memory-backed and never reach a disk. Publishing is loopback-only because the
tool has no authentication, and BLAS thread pools are pinned because analysis is
CPU-bound.
Fix three packaging bugs the build surfaced, each of which broke the image:
- `pip install --extra web` is not valid for a source tree; uv wants `.[web]`
and failed with "Requesting extras requires a pylock.toml".
- The wheel shipped no static assets at all. `package-data` keys match
*packages*, and the app modules are top-level `py-modules`, so the `"*"` key
matched nothing - verified by inspecting the built wheel: 14 .py files, zero
HTML/JS/CSS. An installed `ujm-web` would have 404'd every asset. `static/` is
now declared a package (hence its packaging-shim `__init__.py`) so the assets
install next to the modules, which is where `webapp.py` looks for them.
- The Dockerfile's curated COPY list omitted modules that `py-modules` requires,
failing the build with "file <module>.py not found". It copies the checkout,
filtered by .dockerignore.
Move PyQt5/pyqtgraph into a `desktop` extra so the web install is genuinely
Qt-free. Verified: `find` for Qt in a web-only venv now returns nothing, and the
desktop path still resolves and imports.
Add scripts/make_fixtures.py so the smoke suite has no network or ffmpeg
dependency (the tagged MP3 is optional and its assertions skip when absent), and
make the suite tolerate that. Verified against the *installed package* running
the container's own command line, from a directory with no source tree:
61/61 passing.
Also correct README claims that had gone stale: BPM (removed), the matplotlib
canvas (replaced by pyqtgraph), and font_control_widget.py (deleted).
Reuses the analysis backend unchanged. metrics.py already split compute()
from build_spec(), and plotspec.PlotSpec is backend-agnostic, so the web UI
reimplements only the renderer: uPlot for curves/bands, a canvas for the
spectrogram heatmap. No PyQt5, pyqtgraph or matplotlib on the web path.
Uploaded audio is never persisted on the host. The browser copies each file
into Origin Private File System (sandboxed browser storage) and streams the
bytes to the server per request; the server spools each body to a temp file,
decodes, computes, and unlinks it in a finally before responding. There is no
upload directory, no cache of audio, and no session state keyed on a path:
file_id is the SHA-256 of the audio, so re-sending a master for another metric
reuses the first decode. Verified: a spool is observable mid-request and gone
after the response.
Being precise: the bytes do have to reach the server, since librosa decodes
from a path and the analysis is CPU-bound numpy/scipy. The claim is that
running this does not accumulate masters on the host, not that audio is never
on the machine mid-request.
New:
metrics_json.py PlotSpec/metric data -> JSON (the renderer seam)
web_session.py headless analysis session, content-addressed tracks
webapp.py FastAPI routes, raw-body analysis, ujm-web entry point
static/ browser front end + test suite
scripts/webapi_smoke.py 61 end-to-end assertions against a running server
Also fixes a bug the direct-uvicorn dev loop had hidden: the CLI advertises
logger_setup's WARN level but passed it straight to uvicorn, which only knows
'warning' -- `ujm-web --log-level WARN` died with KeyError: 'warn'.
Removes an earlier /api/collect debug route that served every source module
over HTTP.
pyproject: 'web' extra (fastapi, uvicorn, python-multipart), package-data for
static/, Apache-2.0 licence.
- Replace LICENSE with properly filled Apache-2.0 (Mikkeli Matlock 2026)
- Add license field to pyproject.toml
- Add SPDX-License-Identifier headers to all .py source files
Reference lines:
- Kept per metric (dict keyed by metric_id) so switching metrics and coming back
preserves them, instead of clearing on every switch
- Spectrogram lines read/edit/drag in Hz: the renderer installs Hz<->row-index
transforms (the heatmap y-axis is a row index), so value, label, the edit
dialog, and the new-line default all speak frequency. Curve metrics stay
identity. Round-trip verified (1000 Hz -> row -> 1000 Hz)
- Line label and drag-readback always in the metric's natural units
Controls:
- Relative-time abs/rel is now a checkbox toggle, not a dropdown
- Removed the font control panel; UI font is locked to M PLUS 1 Code @ 10pt via
font_manager.apply_fixed_font (system-default fallback). Deleted
font_control_widget.py
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reference lines:
- Side-panel cluster (ref_line_widget.py): list of lines with Add/Edit/Remove/
Clear and a properties dialog (value, colour, line style, tag)
- Lines own their state as RefLineProps (held by MainWindow), drawn with a
triangle drag-handle; dragging writes the value back and refreshes the list
- Replaces the old centre-only add-and-drag-the-whole-line approach
Comparison:
- Time-axis mode selector: Absolute (seconds) vs Relative (% of each track's own
length), so a long track and a short one line up by song position. Pure view
transform (plotspec.apply_x_mode), no recompute
- Overlaid different-length tracks now autorange their x union in absolute mode
instead of clipping to the first track's span
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Introduce a Metric ABC (compute on worker thread, render on GUI thread)
with a METRICS registry, and refactor the analysis pipeline around it.
RMS power (ported), raw waveform, and BS.1770 LUFS (via pyloudnorm) ship
as the initial three; new metrics drop in by appending to METRICS.
- metrics.py: Metric ABC + RMSPowerMetric, WaveformMetric (locked to
+/-1.1 y-range for float headroom), LUFSMetric (short-term 3 s window
+ integrated value, with streaming-target reference line).
- plot_control_widget.py: metric selector dropdown + Refresh Plot button
(moved out of FontControlWidget).
- analysis_results_manager.py: AnalysisResult caches the AudioFile and a
per-metric data dict; new MetricComputeWorker runs metric switches off
the GUI thread via metricComputeStarted/metricReady/metricComputeError
signals, so LUFS on a 12-minute track no longer stalls the UI.
- main.py: all redraw paths funnel through one _render_or_request helper;
stale-result guards keep slow computes from overwriting fresh selections.
- plotting_engine.py removed (metadata text moved onto AnalysisResult;
figure construction lives in each Metric).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
mikkeli
irene
Mikkeli Matlock