;
+ private root: HTMLDivElement | null = null;
+ private canvas: HTMLCanvasElement | null = null;
+ private ctx: CanvasRenderingContext2D | null = null;
+ private timeEl: HTMLElement | null = null;
+ private freqEl: HTMLElement | null = null;
+ private recorder: LiveRecorder | null = null;
+ private raf = 0;
+ private drawnPx = 0;
+ private lut: Uint8ClampedArray | null = null;
+ private lutScheme = '';
+ private spectrum: Float32Array | null = null;
+ private resizeObserver: ResizeObserver | null = null;
+
+ constructor(host: HTMLElement, opts: LiveSpectrogramViewOptions = {}) {
+ super();
+ this.host = host;
+ this.opts = {
+ spanSeconds: opts.spanSeconds ?? 20,
+ getColorScheme: opts.getColorScheme ?? (() => 'inferno'),
+ getMaxFreq: opts.getMaxFreq ?? (() => 0),
+ minDb: opts.minDb ?? -110,
+ maxDb: opts.maxDb ?? -30,
+ };
+ }
+
+ get attached(): boolean { return !!this.recorder; }
+
+ attach(recorder: LiveRecorder): void {
+ this.detach();
+ this.recorder = recorder;
+ const root = document.createElement('div');
+ root.className = 'live-view';
+ root.innerHTML = `
+
+ REC
+ 0:00
+ ■ Stop
+
`;
+ this.host.appendChild(root);
+ this.root = root;
+ this.canvas = root.querySelector('canvas');
+ this.ctx = this.canvas!.getContext('2d');
+ this.timeEl = root.querySelector('.live-view-time');
+ this.freqEl = root.querySelector('.live-view-freq');
+ root.querySelector('.live-view-stop')!.addEventListener('click', (e) => {
+ e.stopPropagation();
+ this.dispatchEvent(new CustomEvent('stoprequest'));
+ });
+ // Keep pointer input away from the player below.
+ root.addEventListener('pointerdown', (e) => e.stopPropagation());
+ this.resizeObserver = new ResizeObserver(() => this.resize());
+ this.resizeObserver.observe(root);
+ this.resize();
+ this.drawnPx = 0;
+ const loop = () => {
+ this.frame();
+ this.raf = requestAnimationFrame(loop);
+ };
+ this.raf = requestAnimationFrame(loop);
+ }
+
+ detach(): void {
+ cancelAnimationFrame(this.raf);
+ this.raf = 0;
+ this.resizeObserver?.disconnect();
+ this.resizeObserver = null;
+ this.root?.remove();
+ this.root = null;
+ this.canvas = null;
+ this.ctx = null;
+ this.recorder = null;
+ this.spectrum = null;
+ }
+
+ private resize(): void {
+ const c = this.canvas, root = this.root;
+ if (!c || !root) return;
+ const w = Math.max(1, Math.floor(root.clientWidth));
+ const h = Math.max(1, Math.floor(root.clientHeight));
+ if (c.width === w && c.height === h) return;
+ // The view always spans the same seconds: scale what is drawn to the new size
+ // and continue from the current time at the new pixels per second.
+ const old = c.width > 1 && c.height > 1 ? this.snapshot(c) : null;
+ c.width = w;
+ c.height = h;
+ const ctx = this.ctx!;
+ ctx.fillStyle = this.color(0);
+ ctx.fillRect(0, 0, w, h);
+ if (old) ctx.drawImage(old, 0, 0, w, h);
+ if (this.recorder) this.drawnPx = Math.floor(this.recorder.elapsed * w / this.opts.spanSeconds);
+ }
+
+ private snapshot(c: HTMLCanvasElement): HTMLCanvasElement {
+ const s = document.createElement('canvas');
+ s.width = c.width; s.height = c.height;
+ s.getContext('2d')?.drawImage(c, 0, 0);
+ return s;
+ }
+
+ private ensureLut(): Uint8ClampedArray {
+ const scheme = this.opts.getColorScheme();
+ if (this.lut && this.lutScheme === scheme) return this.lut;
+ const lut = new Uint8ClampedArray(256 * 3);
+ for (let i = 0; i < 256; i++) {
+ const { r, g, b } = getSpectrogramColor(i / 255, scheme);
+ lut[i * 3] = r; lut[i * 3 + 1] = g; lut[i * 3 + 2] = b;
+ }
+ this.lut = lut;
+ this.lutScheme = scheme;
+ return lut;
+ }
+
+ private color(v: number): string {
+ const lut = this.ensureLut();
+ const i = Math.max(0, Math.min(255, Math.round(v * 255))) * 3;
+ return `rgb(${lut[i]},${lut[i + 1]},${lut[i + 2]})`;
+ }
+
+ private frame(): void {
+ const rec = this.recorder, c = this.canvas, ctx = this.ctx;
+ if (!rec || !c || !ctx) return;
+ const elapsed = rec.elapsed;
+ if (this.timeEl) this.timeEl.textContent = `${formatTime(elapsed)} / ${formatTime(rec.maxSeconds)}`;
+ const an = rec.analyser;
+ if (!an || !rec.recording) return;
+ const nyquist = rec.sampleRate / 2;
+ const maxFreq = Math.min(nyquist, this.opts.getMaxFreq() || nyquist);
+ if (this.freqEl) this.freqEl.textContent = `0–${(maxFreq / 1000).toFixed(maxFreq < 10000 ? 1 : 0)} kHz`;
+
+ const pxPerSec = c.width / this.opts.spanSeconds;
+ const target = Math.floor(elapsed * pxPerSec);
+ let n = target - this.drawnPx;
+ if (n <= 0) return;
+ if (n > c.width) { this.drawnPx = target - c.width; n = c.width; }
+ this.drawnPx += n;
+
+ const bins = an.frequencyBinCount;
+ if (!this.spectrum || this.spectrum.length !== bins) this.spectrum = new Float32Array(bins);
+ an.getFloatFrequencyData(this.spectrum as Float32Array);
+
+ const h = c.height;
+ const lut = this.ensureLut();
+ const { minDb, maxDb } = this.opts;
+ const col = ctx.createImageData(1, h);
+ const px = col.data;
+ for (let y = 0; y < h; y++) {
+ const f = (1 - (y + 0.5) / h) * maxFreq;
+ const bin = Math.min(bins - 1, Math.max(0, Math.round(f / nyquist * bins)));
+ const v = (this.spectrum[bin] - minDb) / (maxDb - minDb);
+ const i = Math.max(0, Math.min(255, Math.round((Number.isFinite(v) ? v : 0) * 255))) * 3;
+ const o = y * 4;
+ px[o] = lut[i]; px[o + 1] = lut[i + 1]; px[o + 2] = lut[i + 2]; px[o + 3] = 255;
+ }
+ // Move the image left by n pixels, then fill the new columns with the newest spectrum.
+ ctx.drawImage(c, n, 0, c.width - n, h, 0, 0, c.width - n, h);
+ for (let x = c.width - n; x < c.width; x++) ctx.putImageData(col, x, 0);
+ }
+}
diff --git a/src/ui/components/waveform/waveform.ts b/src/ui/components/waveform/waveform.ts
index 0db714e3..90b9aa9a 100644
--- a/src/ui/components/waveform/waveform.ts
+++ b/src/ui/components/waveform/waveform.ts
@@ -307,10 +307,38 @@ export function renderOverviewWaveform({
installThemeObserver(overviewCanvas, () => {
const s = (overviewCanvas as any)._aw_lastRender;
- if (s) requestAnimationFrame(() => { try { renderOverviewWaveform(s); } catch {} });
+ if (s) requestAnimationFrame(() => {
+ // A spectrogram image drawn meanwhile clears the saved state: keep it.
+ if ((overviewCanvas as any)._aw_lastRender !== s) return;
+ try { renderOverviewWaveform(s); } catch {}
+ });
});
}
+/**
+ * Draws a whole-file spectrogram image into the overview strip (overview
+ * mode 'spectrogram'). Clears the waveform's theme re-render so a theme
+ * change does not paint the waveform over it.
+ */
+export function renderOverviewImage({
+ image,
+ overviewCanvas,
+ overviewContainer,
+}: {
+ image: CanvasImageSource;
+ overviewCanvas: HTMLCanvasElement;
+ overviewContainer: HTMLElement;
+}) {
+ const ctx = overviewCanvas.getContext('2d');
+ if (!ctx) return;
+ (overviewCanvas as any)._aw_lastRender = null;
+ const rect = overviewContainer.getBoundingClientRect();
+ overviewCanvas.width = Math.max(1, Math.floor(rect.width));
+ overviewCanvas.height = Math.max(1, Math.floor(rect.height));
+ ctx.imageSmoothingEnabled = true;
+ ctx.drawImage(image, 0, 0, overviewCanvas.width, overviewCanvas.height);
+}
+
// ─── Frequency Labels ───────────────────────────────────────────────
export function renderFrequencyLabels({ labelsElement, coords }: { labelsElement: HTMLElement; coords: any }) {
diff --git a/src/ui/template.ts b/src/ui/template.ts
index ed763028..464e6ff1 100644
--- a/src/ui/template.ts
+++ b/src/ui/template.ts
@@ -17,6 +17,7 @@ export const DEFAULT_OPTIONS = {
showDisplayGain: true, // Floor / Ceil / AC sliders
showStatusbar: true, // Bottom status bar
showOverview: true, // Bottom overview navigator
+ overviewMode: 'waveform', // waveform | spectrogram (whole file, max-pooled)
viewMode: 'both', // both | waveform | spectrogram
transportStyle: 'default', // default | hero
transportOverlay: false, // Overlay mode: centered play button without toolbar height
diff --git a/tests/live-recorder.test.mjs b/tests/live-recorder.test.mjs
new file mode 100644
index 00000000..958b4f34
--- /dev/null
+++ b/tests/live-recorder.test.mjs
@@ -0,0 +1,54 @@
+// live-recorder.test.mjs — WAV of a microphone recording carries its start time
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { encodeWav, recordingFileName } from '../src/infrastructure/audio/LiveRecorder.ts';
+import { readRecordingStart } from '../src/domain/recordingTime.ts';
+
+test('encodeWav writes mono 16-bit PCM with an INFO start time', async () => {
+ const chunks = [Float32Array.from([0, 0.5, -0.5]), Float32Array.from([1, -1])];
+ const blob = encodeWav(chunks, 48000, { ICRD: '2026-11-15T14:30:12+01:00', ISFT: 'SignaVis' });
+ const buf = new Uint8Array(await blob.arrayBuffer());
+ const v = new DataView(buf.buffer);
+ const tag = (o) => String.fromCharCode(...buf.subarray(o, o + 4));
+ assert.equal(tag(0), 'RIFF');
+ assert.equal(v.getUint32(4, true), buf.length - 8);
+ assert.equal(v.getUint16(22, true), 1);
+ assert.equal(v.getUint32(24, true), 48000);
+ const dataAt = buf.length - 10 - 8;
+ assert.equal(tag(dataAt), 'data');
+ assert.equal(v.getUint32(dataAt + 4, true), 10);
+ assert.deepEqual([...new Int16Array(buf.slice(dataAt + 8).buffer)], [0, 16383, -16384, 32767, -32768]);
+
+ const start = readRecordingStart(buf.buffer, 'Recording.wav');
+ assert.equal(start.source, 'WAV INFO');
+ assert.equal(start.tz, 60);
+ assert.equal(start.ms, Date.UTC(2026, 10, 15, 14, 30, 12));
+});
+
+test('recordingFileName uses the local date and time', () => {
+ assert.equal(recordingFileName(new Date(2026, 0, 2, 3, 4, 5)), 'Recording_20260102_030405.wav');
+});
+
+test('a recorder stopped before start() never opens the microphone', async () => {
+ const { LiveRecorder } = await import('../src/infrastructure/audio/LiveRecorder.ts');
+ let asked = 0, stopped = 0;
+ const g = globalThis;
+ const saved = { nav: Object.getOwnPropertyDescriptor(g, 'navigator'), ac: g.AudioContext };
+ let grant;
+ Object.defineProperty(g, 'navigator', { configurable: true, value: { mediaDevices: { getUserMedia: () => { asked++; return new Promise((r) => { grant = r; }); } } } });
+ g.AudioContext = class { constructor() { throw new Error('graph must not be built'); } };
+ try {
+ const rec = new LiveRecorder();
+ const starting = rec.start();
+ await new Promise((r) => setTimeout(r, 0));
+ assert.equal(await rec.stop(), null); // cancelled while permission is pending
+ grant({ getTracks: () => [{ stop: () => { stopped++; } }] });
+ await assert.rejects(starting, /cancelled/);
+ assert.equal(asked, 1);
+ assert.equal(stopped, 1); // the late stream is released
+ assert.equal(rec.recording, false);
+ } finally {
+ if (saved.nav) Object.defineProperty(g, 'navigator', saved.nav); else delete g.navigator;
+ g.AudioContext = saved.ac;
+ }
+});
diff --git a/tests/overview-spectrogram.test.mjs b/tests/overview-spectrogram.test.mjs
new file mode 100644
index 00000000..b1b95fb9
--- /dev/null
+++ b/tests/overview-spectrogram.test.mjs
@@ -0,0 +1,34 @@
+// overview-spectrogram.test.mjs — max-pooled whole-file overview
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { poolFramesMax } from '../src/domain/spectrogram.ts';
+
+test('poolFramesMax keeps each bin maximum per column', () => {
+ // 6 frames × 2 bins, frame-major; a short "call" in frame 4, bin 1
+ const data = Float32Array.from([
+ 0, 1, 0, 1, 0, 1,
+ 0, 1, 0, 9, 2, 1,
+ ]);
+ const { data: out, frames } = poolFramesMax(data, 6, 2, 3);
+ assert.equal(frames, 3);
+ assert.deepEqual([...out], [0, 1, 0, 1, 2, 9]);
+});
+
+test('poolFramesMax passes short data through', () => {
+ const data = Float32Array.from([1, 2, 3, 4]);
+ const { data: out, frames } = poolFramesMax(data, 2, 2, 10);
+ assert.equal(frames, 2);
+ assert.deepEqual([...out], [1, 2, 3, 4]);
+});
+
+test('poolFramesMax covers uneven splits without gaps', () => {
+ const data = Float32Array.from([5, 1, 1, 1, 7]); // 5 frames × 1 bin
+ const { data: out } = poolFramesMax(data, 5, 1, 2);
+ assert.deepEqual([...out], [5, 7]);
+});
+
+test('poolFramesMax samples phase instead of taking the largest angle', () => {
+ const data = Float32Array.from([-3, 3, -3, 3, -3, 3]); // 6 frames × 1 bin
+ const { data: out } = poolFramesMax(data, 6, 1, 2, 'sample');
+ assert.deepEqual([...out], [3, -3]); // frames 1 and 4 (column centres)
+});
diff --git a/tests/recording-time.test.mjs b/tests/recording-time.test.mjs
new file mode 100644
index 00000000..e49211c5
--- /dev/null
+++ b/tests/recording-time.test.mjs
@@ -0,0 +1,84 @@
+// recording-time.test.mjs — recording start from metadata and file names
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readRecordingStart, recordingStartFromFileName, isoClockTime, ravenClock, utcLabel } from '../src/domain/recordingTime.ts';
+import { buildRavenSelectionTable } from '../src/infrastructure/export/ravenSelectionTable.ts';
+
+function riff(chunks) {
+ const parts = chunks.map(([id, body]) => {
+ const b = typeof body === 'string' ? new TextEncoder().encode(body) : body;
+ const out = new Uint8Array(8 + b.length + (b.length & 1));
+ out.set(new TextEncoder().encode(id), 0);
+ new DataView(out.buffer).setUint32(4, b.length, true);
+ out.set(b, 8);
+ return out;
+ });
+ const size = parts.reduce((n, p) => n + p.length, 4);
+ const out = new Uint8Array(8 + size);
+ out.set(new TextEncoder().encode('RIFF'), 0);
+ new DataView(out.buffer).setUint32(4, size, true);
+ out.set(new TextEncoder().encode('WAVE'), 8);
+ let o = 12;
+ for (const p of parts) { out.set(p, o); o += p.length; }
+ return out.buffer;
+}
+
+function info(sub, value) {
+ const v = new TextEncoder().encode(value + '\0');
+ const b = new Uint8Array(4 + 8 + v.length + (v.length & 1));
+ b.set(new TextEncoder().encode('INFO'), 0);
+ b.set(new TextEncoder().encode(sub), 4);
+ new DataView(b.buffer).setUint32(8, v.length, true);
+ b.set(v, 12);
+ return b;
+}
+
+test('AudioMoth comment with time zone', () => {
+ const buf = riff([['fmt ', new Uint8Array(16)], ['LIST', info('ICMT', 'Recorded at 19:00:00 12/05/2023 (UTC+1) by AudioMoth 24A04F0000000000')], ['data', new Uint8Array(4)]]);
+ const s = readRecordingStart(buf, 'x.wav');
+ assert.equal(s.source, 'AudioMoth');
+ assert.equal(s.tz, 60);
+ assert.equal(isoClockTime(s, 3.5), '2023-05-12T19:00:03.500+01:00');
+});
+
+test('GUANO timestamp wins over the file name', () => {
+ const buf = riff([['data', new Uint8Array(4)], ['guan', 'GUANO|Version: 1.0\nTimestamp: 2022-08-01T22:15:30Z\n']]);
+ const s = readRecordingStart(buf, '20200101_000000.wav');
+ assert.equal(s.source, 'GUANO');
+ assert.equal(s.tz, 0);
+ assert.equal(isoClockTime(s), '2022-08-01T22:15:30.000Z');
+});
+
+test('BWF bext origination date and time', () => {
+ const b = new Uint8Array(400);
+ b.set(new TextEncoder().encode('2021-03-04'), 320);
+ b.set(new TextEncoder().encode('05:06:07'), 330);
+ const s = readRecordingStart(riff([['bext', b]]), 'x.wav');
+ assert.equal(s.source, 'BWF');
+ assert.equal(s.tz, null);
+ assert.deepEqual(ravenClock(s, 1, 2), ['2021-03-04', '05:06:08.000', '05:06:09.000']);
+});
+
+test('file names', () => {
+ assert.equal(recordingStartFromFileName('SMA01234_20230512_190000.wav').ms, Date.UTC(2023, 4, 12, 19, 0, 0));
+ assert.equal(recordingStartFromFileName('2023-05-12 19-00-00.flac').ms, Date.UTC(2023, 4, 12, 19, 0, 0));
+ assert.equal(recordingStartFromFileName('20230431_190000.wav'), null); // 31 April
+ assert.equal(recordingStartFromFileName('birdsong.wav'), null);
+ assert.equal(readRecordingStart(new ArrayBuffer(4), 'folder/20230512T190000.mp3').source, 'fileName');
+});
+
+test('utcLabel', () => {
+ assert.equal(utcLabel(null), '');
+ assert.equal(utcLabel(0), 'UTC');
+ assert.equal(utcLabel(330), 'UTC+5:30');
+ assert.equal(utcLabel(-300), 'UTC-5');
+});
+
+test('Raven table gets clock-time columns only with a known start', () => {
+ const labels = [{ start: 1, end: 2, label: 'x' }];
+ assert.ok(!buildRavenSelectionTable(labels).includes('Begin Clock Time'));
+ const t = buildRavenSelectionTable(labels, { recordingStart: { ms: Date.UTC(2023, 0, 1, 6, 0, 0), tz: null, source: 'fileName' } });
+ const [head, row] = t.trim().split('\n').map((l) => l.split('\t'));
+ assert.deepEqual(head.slice(-3), ['Begin Date', 'Begin Clock Time', 'End Clock Time']);
+ assert.deepEqual(row.slice(-3), ['2023-01-01', '06:00:01.000', '06:00:02.000']);
+});