Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

tooling: full documentation screenshot sweep definitions - detail, speakers/tags, settings/admin, recording/upload, and mobile shot files covering all 49 gallery images

Murtaza Nasir6bac79e3ff7f
diff --git a/scripts/screenshots/shots/detail.mjs b/scripts/screenshots/shots/detail.mjs
new file mode 100644
index 00000000..62695b8f
--- /dev/null
+++ b/scripts/screenshots/shots/detail.mjs
@@ -0,0 +1,422 @@
+// Recording-detail shots: video dock, the audio player + summary, transcript
+// auto-follow, the transcript editor, the floating/docked chat, per-user token
+// usage, and the two summary shots (next steps + regeneration dialog).
+//
+// See docs/screenshots.md for the captions these serve. Recordings are chosen
+// so the sidebar always frames a tag/folder-rich region of the library rather
+// than the untagged scratch recordings at the top of the list.
+
+import { go, settle, openRecordingByTitle, anchorSidebar, clickVisible } from '../helpers.mjs';
+
+/* ------------------------------------------------------------------ *
+ * Small building blocks
+ * ------------------------------------------------------------------ */
+
+/**
+ * Park the sidebar so `title` is its first visible row. anchorSidebar() loads
+ * enough of the infinite-scroll list and gets close; the rect-based pass after
+ * it lands the row exactly on the top edge of the list viewport.
+ */
+async function frameSidebar(page, title) {
+ await anchorSidebar(page, title);
+ await page.evaluate((wanted) => {
+ const h = [...document.querySelectorAll('h4')]
+ .find((el) => el.textContent.includes(wanted) && el.closest('.overflow-y-auto'));
+ if (!h) return;
+ const list = h.closest('.overflow-y-auto');
+ const row = h.closest('[class*="border-b"]') || h.parentElement;
+ list.scrollTop += row.getBoundingClientRect().top - list.getBoundingClientRect().top;
+ }, title);
+ await page.waitForTimeout(400);
+}
+
+/** Open a recording and park the sidebar so `anchor` is its first row. */
+async function openWithSidebar(page, title, anchor) {
+ await openRecordingByTitle(page, title);
+ await frameSidebar(page, anchor || title);
+ await settle(page, 400);
+}
+
+/** Wait until the main <audio>/<video> element has metadata. */
+async function waitForMedia(page) {
+ await page.waitForFunction(() => {
+ const m = document.getElementById('mainPlayerMedia');
+ return m && m.readyState >= 1 && Number.isFinite(m.duration);
+ }, { timeout: 30000 });
+}
+
+/**
+ * Put the player at a fixed position: play briefly (a real user gesture, so
+ * the browser allows it), then pause and seek to an exact second. Pausing
+ * keeps the shot deterministic — a still-playing clock would differ between
+ * runs — while the filled progress bar still reads as a session in progress.
+ */
+async function playToTime(page, seconds) {
+ await waitForMedia(page);
+ await clickVisible(page, 'button[title="Play"], button[title="Pause"]');
+ await page.waitForTimeout(700);
+ await page.evaluate(async (t) => {
+ const m = document.getElementById('mainPlayerMedia');
+ m.pause();
+ m.currentTime = t;
+ }, seconds);
+ await page.waitForFunction((t) => {
+ const m = document.getElementById('mainPlayerMedia');
+ return m && !m.seeking && Math.abs(m.currentTime - t) < 1.5;
+ }, seconds, { timeout: 30000 });
+ await settle(page, 800);
+}
+
+/** Scroll the summary pane so the given heading is at the top of the rail. */
+async function scrollSummaryToHeading(page, heading) {
+ const ok = await page.evaluate((text) => {
+ const pane = document.querySelector('.prose-flush');
+ if (!pane) return false;
+ const h = [...pane.querySelectorAll('h1, h2, h3, h4, strong')]
+ .find((e) => e.textContent.trim().toLowerCase().startsWith(text.toLowerCase()));
+ if (!h) return false;
+ let s = h.parentElement;
+ while (s && s.scrollHeight <= s.clientHeight + 4) s = s.parentElement;
+ if (!s) return true; // the whole summary already fits
+ const offset = h.getBoundingClientRect().top - s.getBoundingClientRect().top + s.scrollTop;
+ s.scrollTop = Math.min(Math.max(offset - 12, 0), s.scrollHeight - s.clientHeight);
+ return true;
+ }, heading);
+ if (!ok) throw new Error(`Summary heading "${heading}" not found`);
+ await page.waitForTimeout(400);
+}
+
+/** Open the floating chat panel from its collapsed FAB. */
+async function openChat(page) {
+ if (!(await clickVisible(page, '.floating-chat-fab'))) {
+ throw new Error('Chat FAB not found');
+ }
+ await page.waitForSelector('.floating-chat-panel', { state: 'visible' });
+ await settle(page, 400);
+}
+
+/** Drag the floating panel's SE corner handle until it is w x h. */
+async function resizeChatPanel(page, w, h) {
+ const handle = page.locator('.floating-chat-resize-handle').first();
+ const grip = await handle.boundingBox();
+ const panel = await page.locator('.floating-chat-panel').first().boundingBox();
+ if (!grip || !panel) throw new Error('Chat panel resize handle not visible');
+ await page.mouse.move(grip.x + grip.width / 2, grip.y + grip.height / 2);
+ await page.mouse.down();
+ await page.mouse.move(
+ grip.x + grip.width / 2 + (w - panel.width),
+ grip.y + grip.height / 2 + (h - panel.height),
+ { steps: 12 },
+ );
+ await page.mouse.up();
+ await page.waitForTimeout(300);
+}
+
+/**
+ * Scroll the chat log so the last question sits at the top of the panel — the
+ * exchange should read question-then-answer rather than opening mid-answer.
+ */
+async function frameChat(page) {
+ await page.evaluate(() => {
+ const log = document.querySelector('.floating-chat-messages');
+ if (!log) return;
+ const asked = [...log.querySelectorAll('.user-message')].pop();
+ if (!asked) return;
+ log.scrollTop = Math.max(
+ 0,
+ Math.min(
+ asked.getBoundingClientRect().top - log.getBoundingClientRect().top + log.scrollTop - 12,
+ log.scrollHeight - log.clientHeight,
+ ),
+ );
+ });
+ await page.waitForTimeout(300);
+}
+
+/** Drag the floating chat panel by its header so its top-left lands at x,y. */
+async function moveChatPanel(page, x, y) {
+ const header = page.locator('.floating-chat-header').first();
+ const box = await header.boundingBox();
+ if (!box) throw new Error('Chat panel header not visible');
+ const panel = await page.locator('.floating-chat-panel').first().boundingBox();
+ await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2);
+ await page.mouse.down();
+ await page.mouse.move(
+ box.x + box.width / 2 + (x - panel.x),
+ box.y + box.height / 2 + (y - panel.y),
+ { steps: 12 },
+ );
+ await page.mouse.up();
+ await page.waitForTimeout(300);
+}
+
+/**
+ * Ask the per-recording chat a question and wait for the streamed answer to
+ * finish: the "thinking" row gone, no spinners, and the answer text stable.
+ * Chat history is client-side only, so nothing is left behind on the server.
+ */
+async function askChat(page, question, timeoutMs = 150000) {
+ const box = page.locator('.floating-chat-input textarea').first();
+ await box.click();
+ await box.fill(question);
+ await page.keyboard.press('Enter');
+
+ const deadline = Date.now() + timeoutMs;
+ let previous = -1;
+ let stable = 0;
+ while (Date.now() < deadline) {
+ const state = await page.evaluate(() => {
+ const visible = (el) => !!el.offsetParent;
+ const msgs = [...document.querySelectorAll('.floating-chat-messages .ai-message')].filter(visible);
+ const last = msgs[msgs.length - 1];
+ return {
+ busy: [...document.querySelectorAll('.floating-chat-messages .spinner')].filter(visible).length > 0,
+ answers: msgs.length,
+ length: last ? last.innerText.length : 0,
+ };
+ });
+ if (!state.busy && state.answers > 0 && state.length > 0) {
+ stable = state.length === previous ? stable + 1 : 0;
+ previous = state.length;
+ if (stable >= 2) {
+ await page.waitForTimeout(600);
+ return;
+ }
+ } else {
+ stable = 0;
+ previous = state.length;
+ }
+ await page.waitForTimeout(1200);
+ }
+ throw new Error('Chat answer did not finish in time');
+}
+
+/**
+ * The header usage meter only renders for accounts that have a monthly token
+ * budget. If the account already has one, use it untouched; otherwise set one
+ * for the duration of the shot and put the account back exactly as it was.
+ * The meter is loaded once at boot, so it stays on screen for the screenshot
+ * even after the budget has been removed again.
+ */
+async function withTokenBudget(page, fallbackBudget, body) {
+ const email = (process.env.SPEAKR_EMAIL || '').toLowerCase();
+ const account = () => page.evaluate(async (who) => {
+ const users = await (await fetch('/admin/users')).json();
+ const me = users.find((u) => (u.email || '').toLowerCase() === who);
+ if (!me) throw new Error(`account ${who} not found in /admin/users`);
+ return { id: me.id, budget: me.monthly_token_budget };
+ }, email);
+ const setBudget = (id, value) => page.evaluate(async ([userId, v]) => {
+ const csrf = document.querySelector('meta[name="csrf-token"]')?.content || '';
+ const res = await fetch(`/admin/users/${userId}`, {
+ method: 'PUT',
+ headers: { 'Content-Type': 'application/json', 'X-CSRFToken': csrf },
+ body: JSON.stringify({ monthly_token_budget: v }),
+ });
+ if (!res.ok) throw new Error(`token budget update failed: ${res.status}`);
+ }, [id, value]);
+
+ const before = await account();
+ if (before.budget) {
+ await body(); // real budget already configured
+ return;
+ }
+ await setBudget(before.id, fallbackBudget);
+ try {
+ await body();
+ } finally {
+ await setBudget(before.id, null); // restore; the meter is already drawn
+ }
+}
+
+/* ------------------------------------------------------------------ *
+ * Recordings used, and where to park the sidebar for each
+ * ------------------------------------------------------------------ */
+
+const R = {
+ // Chromium ships without the proprietary H.264/AAC decoders, so the video
+ // shot has to use one of the library's WebM recordings.
+ video: 'SEC/Data Science Team Updates and Announcements',
+ player: 'Attempting a Michelin Star Dish Challenge',
+ follow: 'Job Cuts, Internet Regulations, and Apple Subscriptions',
+ edit: 'Fortnightly Team Meeting at ABC Manufacturing',
+ chat: 'Job Cuts, Internet Regulations, and Apple Subscriptions',
+ tokens: 'Road Trip Reflections and Future Research Plans',
+ nextSteps: 'Fortnightly Team Meeting at ABC Manufacturing',
+ reprocess: 'SEC Disgorgement Limits and Investor Harm',
+};
+
+const ANCHOR = {
+ learning: 'German Listening Practice: Meeting New People',
+ interviews: 'Art, Jiu-Jitsu, and Creative Processes',
+ work: 'Collaborative Approaches in Team Management',
+ sec: 'SEC/Data Science Team Updates and Announcements',
+};
+
+export default [
+ {
+ name: 'main-view-video',
+ description: 'Video playback synced to the transcript',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ // Park the video dock at the top of the transcript column, where
+ // it sits directly above the transcript it is synced to.
+ await page.addInitScript(() => {
+ try {
+ localStorage.setItem('videoDockPosition', 'left-top');
+ localStorage.setItem('videoDockHeight', '380');
+ } catch (_) {}
+ });
+ await go(page, '/');
+ await openWithSidebar(page, R.video, R.video);
+ if (!(await clickVisible(page, 'button[title="Show video"]'))) {
+ throw new Error('Show video button not found (not a video recording?)');
+ }
+ await settle(page, 600);
+ await playToTime(page, 620);
+ // The docked video is a muted follower kept in step by
+ // syncDockVideo(); wait until it actually has a frame decoded.
+ await page.waitForFunction(() => {
+ const v = document.getElementById('dockVideoElement');
+ return v && v.readyState >= 2;
+ }, { timeout: 30000 });
+ await settle(page, 800);
+ },
+ },
+ {
+ name: 'main-view-player',
+ description: 'Audio player with the generated summary',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.player, ANCHOR.learning);
+ await playToTime(page, 615);
+ },
+ },
+ {
+ name: 'transcript-auto-follow',
+ description: 'The transcript auto-scrolls to follow playback',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.follow, ANCHOR.learning);
+ if (!(await clickVisible(page, 'button[title*="Enable auto-scroll"]'))) {
+ throw new Error('Auto-scroll toggle not found');
+ }
+ await settle(page, 400);
+ await playToTime(page, 11558);
+ // The follow handler scrolls the segment for the current time into
+ // view; wait for it to actually be highlighted and on screen.
+ await page.waitForSelector('.active-playing-segment', { state: 'visible', timeout: 20000 });
+ await settle(page, 800);
+ },
+ },
+ {
+ name: 'edit-transcript-modal',
+ description: 'Editing the transcript',
+ theme: { dark: true, scheme: 'teal' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.edit, ANCHOR.interviews);
+ if (!(await clickVisible(page, 'button[title="Edit transcript"]'))) {
+ throw new Error('Edit transcript button not found');
+ }
+ await page.waitForSelector('.modal-overlay', { state: 'visible' });
+ await settle(page, 1000);
+ // Nudge past the intro so the segment table shows several of the
+ // named speakers rather than a run of the same one, landing on a
+ // row boundary so the first row is not sliced in half.
+ await page.evaluate(() => {
+ const list = document.querySelector('[class*="flex-grow"].overflow-y-auto');
+ const row = list && list.querySelector('tbody tr');
+ if (!list || !row) return;
+ const h = row.getBoundingClientRect().height || 42;
+ list.scrollTop = Math.round(240 / h) * h;
+ });
+ await settle(page, 500);
+ },
+ },
+ {
+ name: 'main-view-chat-notes',
+ description: 'Floating chat and notes over the transcript',
+ theme: { dark: true, scheme: 'purple' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.chat, ANCHOR.learning);
+ await clickVisible(page, '.tab:has-text("Notes")');
+ await settle(page, 400);
+ await openChat(page);
+ await resizeChatPanel(page, 600, 540);
+ await moveChatPanel(page, 348, 460);
+ await askChat(page, 'In two or three sentences, what did the hosts say about Apple charging $240 a year for device insurance?');
+ await moveChatPanel(page, 348, 460);
+ await frameChat(page);
+ },
+ },
+ {
+ name: 'chat-docked',
+ description: 'The chat panel docked into the layout',
+ theme: { dark: true, scheme: 'rose' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.chat, ANCHOR.learning);
+ await openChat(page);
+ await askChat(page, 'Give me three short bullets on the topics in this episode that are not about technology.');
+ if (!(await clickVisible(page, 'button[title="Dock right"]'))) {
+ throw new Error('Dock right button not found');
+ }
+ await settle(page, 800);
+ await frameChat(page);
+ },
+ },
+ {
+ name: 'main-view-token-usage',
+ description: 'LLM token usage shown per recording',
+ theme: { dark: true, scheme: 'amber' },
+ run: async (page) => {
+ await go(page, '/');
+ await withTokenBudget(page, 1000000, async () => {
+ await go(page, '/');
+ await openWithSidebar(page, R.tokens, ANCHOR.work);
+ await page.waitForSelector('.fa-coins', { state: 'visible', timeout: 10000 });
+ });
+ await settle(page, 400);
+ },
+ },
+ {
+ name: 'summary-next-steps',
+ description: 'A summary with action items and next steps',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ // Give the summary rail the wider half of the split (the column
+ // divider is user-draggable and the split is remembered), so the
+ // action-item table reads as a table instead of three word-wrapped
+ // slivers.
+ await page.addInitScript(() => {
+ try {
+ localStorage.setItem('transcriptColumnWidth', '45');
+ localStorage.setItem('summaryColumnWidth', '55');
+ } catch (_) {}
+ });
+ await go(page, '/');
+ await openWithSidebar(page, R.nextSteps, ANCHOR.interviews);
+ await scrollSummaryToHeading(page, 'Next Steps');
+ },
+ },
+ {
+ name: 'summary-reprocess',
+ description: 'Regenerating a summary with a new prompt',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await go(page, '/');
+ await openWithSidebar(page, R.reprocess, ANCHOR.sec);
+ // Opens the confirmation dialog only — reprocessing is never
+ // started, so no LLM call is made and no data changes.
+ if (!(await clickVisible(page, 'button[title="Reprocess summary"]'))) {
+ throw new Error('Reprocess summary button not found');
+ }
+ await page.waitForSelector('.modal-overlay', { state: 'visible' });
+ await settle(page, 800);
+ },
+ },
+];
diff --git a/scripts/screenshots/shots/mobile.mjs b/scripts/screenshots/shots/mobile.mjs
new file mode 100644
index 00000000..17e62c00
--- /dev/null
+++ b/scripts/screenshots/shots/mobile.mjs
@@ -0,0 +1,349 @@
+// Mobile (phone) documentation shots.
+//
+// Every shot in this file renders at the 390x844 @3x phone viewport, where
+// the app has a genuinely different shape from the desktop layout: it opens
+// on the recordings list (a full-height drawer), opening a recording takes
+// you to a detail screen with bottom tab navigation, and most per-recording
+// actions live behind the chevron in the mobile detail header.
+//
+// Two rules that apply to nearly everything here:
+// * The desktop templates stay in the DOM on mobile, so a text locator
+// matches hidden duplicates — always resolve elements through the
+// viewport-filtering helpers below, never with a bare page.click().
+// * Escape does not close the app's popovers/sheets; backdrop taps do.
+
+import { go, settle, loadSidebarUntil } from '../helpers.mjs';
+
+const MOBILE_WIDTH = 390;
+
+/** The scrolling container of the recordings list (the mobile drawer). */
+const LIST_SCROLLER = '.flex-1.overflow-y-auto.pb-3';
+
+/** A sample file that exists in the repo; queued but never uploaded. */
+const SAMPLE_FILE = '/home/murtaza/whispertranscribe/temp/german_sample.mp3';
+
+/**
+ * True when the element is actually laid out inside the phone viewport.
+ * The hidden desktop duplicates either have no box at all or sit outside
+ * the 390px column, so this is what separates them.
+ */
+async function inViewport(locator) {
+ const box = await locator.boundingBox().catch(() => null);
+ if (!box) return false;
+ return box.width > 0 && box.height > 0 && box.x >= 0 && box.x < MOBILE_WIDTH && box.y >= 0;
+}
+
+/** Tap the first element matching `selector` that is really on the phone screen. */
+async function tap(page, selector, { required = true } = {}) {
+ const cands = page.locator(selector);
+ const n = await cands.count();
+ for (let i = 0; i < n; i++) {
+ const el = cands.nth(i);
+ if (await inViewport(el)) {
+ await el.click();
+ return true;
+ }
+ }
+ if (required) throw new Error(`No on-screen element matched ${selector}`);
+ return false;
+}
+
+/**
+ * Park the recordings list so the row titled `title` is the first one under
+ * the search bar. Measured against the scroller's own box rather than
+ * offsetTop, because the rows' offsetParent is not the scroller.
+ */
+async function anchorList(page, title) {
+ await loadSidebarUntil(page, title);
+ const ok = await page.evaluate(([sel, wanted]) => {
+ const list = document.querySelector(sel);
+ if (!list) return false;
+ const h = [...list.querySelectorAll('h4')].find((e) => e.textContent.includes(wanted));
+ if (!h) return false;
+ const row = h.closest('li') || h.parentElement.parentElement;
+ list.scrollTop += row.getBoundingClientRect().top - list.getBoundingClientRect().top - 1;
+ return true;
+ }, [LIST_SCROLLER, title]);
+ if (!ok) throw new Error(`Could not anchor the mobile list on ${title}`);
+ await settle(page, 500);
+}
+
+/** Open a recording from the mobile list. */
+async function openRecording(page, title) {
+ await anchorList(page, title);
+ const cands = page.locator(`h4:has-text(${JSON.stringify(title)})`);
+ const n = await cands.count();
+ for (let i = 0; i < n; i++) {
+ const el = cands.nth(i);
+ if (await inViewport(el)) {
+ await el.click();
+ await settle(page, 1500);
+ return;
+ }
+ }
+ throw new Error(`Recording titled ${title} not tappable in the mobile list`);
+}
+
+/** Icons the bottom tab bar uses, keyed by the tab they switch to. */
+const TAB_ICONS = {
+ summary: 'fa-file-alt',
+ transcript: 'fa-align-left',
+ chat: 'fa-comments',
+ notes: 'fa-sticky-note',
+};
+
+/** Switch the detail screen's bottom tab bar to a tab. */
+async function selectTab(page, tab) {
+ await tap(page, `[data-mobile-bottom-nav] button:has(i.${TAB_ICONS[tab]})`);
+ await settle(page, 800);
+}
+
+/** Expand the collapsible metadata panel in the mobile detail header. */
+async function expandMetadata(page) {
+ await tap(page, 'button:has(i.fa-chevron-down)');
+ await settle(page, 600);
+}
+
+/** Re-open the recordings drawer over the detail screen. */
+async function openListDrawer(page) {
+ await tap(page, 'header button:has(i.fa-bars)');
+ await settle(page, 700);
+}
+
+/** True while the list drawer is open (it covers the header on a phone). */
+function drawerIsOpen(page) {
+ return page.evaluate(() => {
+ const aside = document.querySelector('aside.sidebar');
+ return !!aside && !aside.classList.contains('collapsed');
+ });
+}
+
+/**
+ * Open the "New Recording" sheet and wait for the bottom sheet to be on
+ * screen. The + button is taken from whichever bar is on top: the drawer
+ * covers the app header while the list is showing, so the header's own +
+ * is present but unclickable there.
+ */
+async function openUploadSheet(page) {
+ await tap(page, await drawerIsOpen(page)
+ ? 'aside button:has(i.fa-plus)'
+ : 'header button:has(i.fa-plus)');
+ await page.waitForSelector('.modal-panel--bottom-sheet', { state: 'visible' });
+ await settle(page, 800);
+}
+
+/**
+ * Dismiss the processing-queue pill. Queuing a file makes it appear, and on
+ * a phone it parks itself over the sheet's sticky Upload footer.
+ */
+async function dismissQueuePill(page) {
+ await tap(page, '.progress-popup__close', { required: false });
+ await settle(page, 400);
+}
+
+/**
+ * Replace getUserMedia with a synthesised oscillator stream so a real
+ * microphone recording can run headlessly. Must be installed before the
+ * record button is tapped.
+ */
+async function installFakeMicrophone(page) {
+ await page.addInitScript(() => {
+ const make = () => {
+ const ctx = new (window.AudioContext || window.webkitAudioContext)();
+ const osc = ctx.createOscillator();
+ const gain = ctx.createGain();
+ const dest = ctx.createMediaStreamDestination();
+ osc.type = 'sine';
+ osc.frequency.value = 220;
+ gain.gain.value = 0.25;
+ osc.connect(gain).connect(dest);
+ osc.start();
+ return dest.stream;
+ };
+ const md = navigator.mediaDevices || {};
+ md.getUserMedia = async () => make();
+ md.enumerateDevices = async () => ([
+ { deviceId: 'default', kind: 'audioinput', label: 'Built-in Microphone', groupId: 'g' },
+ ]);
+ try {
+ Object.defineProperty(navigator, 'mediaDevices', { value: md, configurable: true });
+ } catch (_) { /* already writable */ }
+ });
+}
+
+/**
+ * Throw away everything the in-progress recording put on the server, while
+ * leaving the live recorder on screen for the shot.
+ *
+ * The harness screenshots the page as `run` returns, so the recorder has to
+ * still be running in the final frame — which rules out driving the app's
+ * own Stop + Discard buttons, since Discard navigates straight back to the
+ * upload sheet. Closing the context kills the client half of the recording
+ * (MediaRecorder, blobs, IndexedDB session) by itself, but this instance
+ * also streams chunks to the server (ENABLE_SERVER_RECORDING_CHUNKS) and
+ * those would sit on disk until the expiry sweep. So:
+ * 1. issue exactly the DELETE that discardRecording() issues, against the
+ * session id the client stashed in localStorage — nothing was ever
+ * finalized, so no recording is created; then
+ * 2. swallow any further chunk POST, which would otherwise 404 against
+ * the deleted session and put a sync-failure banner in the frame.
+ */
+async function discardServerRecordingSession(page) {
+ const result = await page.evaluate(async () => {
+ const realFetch = window.fetch.bind(window);
+ let outcome = 'no server session';
+ try {
+ const stashed = JSON.parse(localStorage.getItem('speakr.serverRecordingSession') || 'null');
+ if (stashed && stashed.session_id) {
+ const csrf = document.querySelector('meta[name="csrf-token"]');
+ const resp = await realFetch(`/upload/session/${encodeURIComponent(stashed.session_id)}`, {
+ method: 'DELETE',
+ credentials: 'same-origin',
+ headers: { 'X-CSRFToken': csrf ? csrf.getAttribute('content') : '' },
+ });
+ outcome = resp.status === 204 || resp.status === 404
+ ? 'aborted' : `abort failed: HTTP ${resp.status}`;
+ localStorage.removeItem('speakr.serverRecordingSession');
+ }
+ } catch (e) {
+ outcome = `abort failed: ${e.message}`;
+ }
+ window.fetch = (input, init) => {
+ const url = typeof input === 'string' ? input : (input && input.url) || '';
+ if (url.includes('/upload/session/')) {
+ return Promise.resolve(new Response('{"ok":true}', {
+ status: 200, headers: { 'Content-Type': 'application/json' },
+ }));
+ }
+ return realFetch(input, init);
+ };
+ return outcome;
+ });
+ if (result.startsWith('abort failed')) throw new Error(`Recording session left behind (${result})`);
+ return result;
+}
+
+export default [
+ {
+ name: 'mobile-main',
+ description: 'The main view on mobile',
+ theme: { dark: true, scheme: 'blue' },
+ mobile: true,
+ run: async (page) => {
+ await go(page, '/');
+ // The list is a drawer over the detail screen, so open a
+ // recording first: the sliver of screen beside the drawer then
+ // shows a real note instead of the empty-state placeholder.
+ await openRecording(page, 'Attempting a Michelin Star Dish Challenge');
+ await openListDrawer(page);
+ // Park the list on a stretch of real, tagged recordings rather
+ // than on whatever happens to be newest.
+ await anchorList(page, 'Manager Introductions at Sihai Meeting');
+ },
+ },
+ {
+ name: 'mobile-summary',
+ description: 'Summary tab with bottom navigation',
+ theme: { dark: true, scheme: 'emerald' },
+ mobile: true,
+ run: async (page) => {
+ await go(page, '/');
+ await openRecording(page, 'Attempting a Michelin Star Dish Challenge');
+ await selectTab(page, 'summary');
+ },
+ },
+ {
+ name: 'mobile-transcript',
+ description: 'Transcript in bubble view',
+ theme: { dark: true, scheme: 'purple' },
+ mobile: true,
+ run: async (page) => {
+ await go(page, '/');
+ await openRecording(page, 'Job Cuts, Internet Regulations, and Apple Subscriptions');
+ await selectTab(page, 'transcript');
+ // The view-mode toggle lives in the header's contextual toolbar,
+ // which only carries it while the transcript tab is active.
+ await tap(page, 'button[title*="Bubble"]');
+ await settle(page, 900);
+ },
+ },
+ {
+ name: 'mobile-speaker-id',
+ description: 'Identifying speakers on mobile',
+ theme: { dark: true, scheme: 'teal' },
+ mobile: true,
+ run: async (page) => {
+ await go(page, '/');
+ // A Supreme Court argument: some voices already carry real
+ // names while the rest are still raw diarization labels, which
+ // is exactly the state this modal exists to resolve.
+ await openRecording(page, 'SEC Disgorgement Limits and Investor Harm');
+ // The Identify Speakers action only exists in the expanded
+ // metadata panel's action toolbar.
+ await expandMetadata(page);
+ await tap(page, 'button:has(i.fa-user-tag)');
+ await page.waitForSelector('.modal-panel', { state: 'visible' });
+ await settle(page, 1200);
+ // Type one name to show the form in use. Nothing is saved: the
+ // shot ends here and the context is thrown away.
+ const blank = page.locator('.modal-panel input[placeholder^="Enter name for SPEAKER"]:visible').first();
+ if (await blank.count()) {
+ await blank.fill('Justice Breyer');
+ await settle(page, 400);
+ }
+ },
+ },
+ {
+ name: 'mobile-upload',
+ description: 'The upload sheet on mobile',
+ theme: { dark: true, scheme: 'rose' },
+ mobile: true,
+ run: async (page) => {
+ await go(page, '/');
+ // Open a recording first so the sheet rises over real content
+ // instead of the empty-state screen.
+ await openRecording(page, 'Attempting a Michelin Star Dish Challenge');
+ await openUploadSheet(page);
+ await page.setInputFiles('input[type=file]', SAMPLE_FILE);
+ // Wait for the queue row to show the probed size/duration.
+ await page.waitForFunction(
+ () => /\(\d[\d.]* MB, /.test(document.body.innerText),
+ { timeout: 20000 },
+ ).catch(() => {});
+ await dismissQueuePill(page);
+ await settle(page, 800);
+ },
+ },
+ {
+ name: 'mobile-recording',
+ description: 'Recording with notes on mobile',
+ theme: { dark: true, scheme: 'amber' },
+ mobile: true,
+ run: async (page) => {
+ await installFakeMicrophone(page);
+ await go(page, '/');
+ await openUploadSheet(page);
+ await tap(page, '.modal-panel--bottom-sheet button:has(i.fa-microphone)');
+ await settle(page, 700);
+ // The instance shows a consent disclaimer between the tap and
+ // the recorder; accept it if it is configured.
+ await tap(page, '.modal-footer button:has-text("Start Recording")', { required: false });
+ await page.waitForSelector('.recording-notes-editor .CodeMirror', { state: 'visible', timeout: 25000 });
+ await settle(page, 1500);
+
+ // The notes field is an EasyMDE editor, so the underlying
+ // <textarea> is hidden — type into CodeMirror instead. Its
+ // markdown list continuation supplies the second "- ".
+ await page.locator('.recording-notes-editor .CodeMirror').first().click();
+ await page.keyboard.type('## Kickoff');
+ await page.keyboard.press('Enter');
+ await page.keyboard.type('- ship the mobile docs shots');
+ await page.keyboard.press('Enter');
+ await page.keyboard.type('follow up on **speaker names**');
+ // Let the clock run on (and any wake-lock toast expire) so the
+ // frame shows a recording under way rather than one just begun.
+ await settle(page, 6000);
+ await discardServerRecordingSession(page);
+ },
+ },
+];
diff --git a/scripts/screenshots/shots/recording-upload.mjs b/scripts/screenshots/shots/recording-upload.mjs
new file mode 100644
index 00000000..b9c83788
--- /dev/null
+++ b/scripts/screenshots/shots/recording-upload.mjs
@@ -0,0 +1,482 @@
+// Recording and upload shots.
+//
+// Covers the two ways audio gets into Speakr — recording it in the browser
+// and uploading files — plus the modals that hang off those flows: the
+// per-upload options group, multi-file queueing, the duplicate indicator,
+// reprocessing, the system-audio setup guide, and the input-device picker.
+//
+// Everything here is non-destructive: files are queued but never uploaded,
+// the reprocess modal is never confirmed, and the live recording used by
+// `recording-live-notes` has its server-side chunk session aborted (the
+// same DELETE the in-app Discard button issues) before the shot ends, so
+// no recording and no orphaned session is left behind.
+
+import { copyFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { go, settle, clickVisible, anchorSidebar, openRecordingByTitle } from '../helpers.mjs';
+
+/** A sample file that exists in the repo; queued but never uploaded. */
+const SAMPLE_FILE = '/home/murtaza/whispertranscribe/temp/german_sample.mp3';
+
+/** Sidebar rows framed behind the modals — tagged, foldered, real-looking. */
+const BACKDROP_RECORDING = 'Attempting a Michelin Star Dish';
+const SIDEBAR_ANCHOR = 'Railroad Tax on Stock Compensation Remuneration';
+
+/** Recording that genuinely has other copies of the same audio on file. */
+const DUPLICATE_RECORDING_ID = 2302; // "Manager Introductions at Sihai Meeting"
+
+/** Markdown typed into the notes pane while the recording runs. */
+const LIVE_NOTES = `## Weekly product sync — 12 Aug
+
+- **Ana** — onboarding rewrite is in review, ships Thursday
+- **Raj** — billing migration is blocked on the vendor sandbox
+
+### Decisions
+1. Hold the pricing page redesign until after launch week
+2. Move the retro to Friday, 10:00
+
+*Follow up:* ask Priya for the churn numbers before Monday.`;
+
+/**
+ * Replace getUserMedia with an oscillator-backed MediaStream so a real
+ * recording can run headless: MediaRecorder, the Web Audio analyser and
+ * the visualiser all see a genuine live audio track. A slow LFO on the
+ * gain keeps the visualiser bars moving instead of drawing a flat line.
+ */
+async function installFakeMicrophone(page) {
+ await page.addInitScript(() => {
+ const makeStream = () => {
+ const ctx = new (window.AudioContext || window.webkitAudioContext)();
+ if (ctx.state === 'suspended') ctx.resume().catch(() => {});
+ const dest = ctx.createMediaStreamDestination();
+ // Two voices an octave apart give the FFT visualiser something
+ // with structure to draw rather than a single spike.
+ [180, 420].forEach((hz, i) => {
+ const osc = ctx.createOscillator();
+ osc.type = i ? 'triangle' : 'sine';
+ osc.frequency.value = hz;
+ const gain = ctx.createGain();
+ gain.gain.value = 0.18;
+ const lfo = ctx.createOscillator();
+ lfo.frequency.value = 0.7 + i * 0.35;
+ const lfoGain = ctx.createGain();
+ lfoGain.gain.value = 0.12;
+ lfo.connect(lfoGain);
+ lfoGain.connect(gain.gain);
+ osc.connect(gain);
+ gain.connect(dest);
+ osc.start();
+ lfo.start();
+ });
+ window.__shotAudioCtx = ctx;
+ return dest.stream;
+ };
+ Object.defineProperty(MediaDevices.prototype, 'getUserMedia', {
+ configurable: true,
+ writable: true,
+ value: async () => makeStream(),
+ });
+ });
+}
+
+/**
+ * Present a fixed pair of audio inputs to the page. Device labels are
+ * empty until a microphone permission is granted, so without this the
+ * input-device picker can only render its "grant permission" prompt.
+ */
+async function installFakeInputDevices(page, devices) {
+ await page.addInitScript((list) => {
+ Object.defineProperty(MediaDevices.prototype, 'enumerateDevices', {
+ configurable: true,
+ writable: true,
+ value: async () => list.map((d) => ({
+ ...d,
+ kind: 'audioinput',
+ toJSON() { return { ...d, kind: 'audioinput' }; },
+ })),
+ });
+ }, devices);
+}
+
+/**
+ * Make platform detection report a specific OS. The system-audio guide
+ * and its capability banner are entirely platform-driven, so this is how
+ * the Windows / macOS pages get captured as the user of that OS sees
+ * them rather than as a Linux capture host sees them.
+ */
+async function spoofPlatform(page, platform) {
+ await page.addInitScript((p) => {
+ Object.defineProperty(navigator, 'platform', { configurable: true, get: () => p });
+ try {
+ Object.defineProperty(navigator, 'userAgentData', { configurable: true, get: () => undefined });
+ } catch (_) { /* not present on every build */ }
+ }, platform);
+}
+
+/** Seed a localStorage value before the app boots. */
+async function seedStorage(page, entries) {
+ await page.addInitScript((kv) => {
+ try {
+ for (const [k, v] of Object.entries(kv)) localStorage.setItem(k, v);
+ } catch (_) { /* private mode */ }
+ }, entries);
+}
+
+/**
+ * Load the main view with a presentable recording open and the sidebar
+ * parked on a tagged, foldered stretch of the library — so whatever modal
+ * sits on top of it has a real backdrop rather than the untagged test
+ * recordings that happen to be newest.
+ */
+async function openBackdrop(page) {
+ await go(page, '/');
+ await openRecordingByTitle(page, BACKDROP_RECORDING);
+ await parkSidebar(page, SIDEBAR_ANCHOR);
+}
+
+/**
+ * anchorSidebar() gets the right region of the list into view but lands a
+ * row or two off, which leaves a sliced row along the top edge. Follow it
+ * with an exact row-top alignment so the list starts on a whole row.
+ */
+async function parkSidebar(page, title) {
+ await anchorSidebar(page, title);
+ await page.evaluate((wanted) => {
+ const h = [...document.querySelectorAll('h4')].find(
+ (el) => el.textContent.includes(wanted) && el.closest('.overflow-y-auto'),
+ );
+ if (!h) return;
+ const list = h.closest('.overflow-y-auto');
+ const row = h.closest('.recording-row') || h.parentElement;
+ list.scrollTop += row.getBoundingClientRect().top - list.getBoundingClientRect().top;
+ }, title);
+ await page.waitForTimeout(400);
+}
+
+/** Open the New Recording / Upload Audio modal from the header. */
+async function openUploadModal(page) {
+ if (!(await clickVisible(page, 'button:has-text("New Recording")'))) {
+ throw new Error('New Recording button not found');
+ }
+ await page.waitForSelector('.modal-panel:has-text("Upload Audio")', { state: 'visible' });
+ await settle(page, 600);
+}
+
+/** Queue files into the upload modal without starting the upload. */
+async function queueFiles(page, files) {
+ await page.setInputFiles('input[type=file]', files);
+ // Wait for the async duration probe so rows show size AND duration.
+ await page.waitForFunction(
+ (n) => (document.body.innerText.match(/\(\d[\d.]* MB, /g) || []).length >= n,
+ files.length,
+ { timeout: 25000 },
+ ).catch(() => {});
+ await settle(page, 600);
+}
+
+/** Expand the collapsed "Options" progressive-disclosure group. */
+async function expandUploadOptions(page) {
+ await page.evaluate(() => {
+ document.querySelectorAll('details.upload-options-group').forEach((d) => { d.open = true; });
+ });
+ await page.waitForTimeout(400);
+}
+
+/** Scroll an element inside the modal body into a comfortable position. */
+async function scrollModalTo(page, selector, pad = 24) {
+ await page.evaluate(([sel, p]) => {
+ const target = document.querySelector(sel);
+ const body = document.querySelector('.modal-body');
+ if (!target || !body) return;
+ const offset = target.getBoundingClientRect().top - body.getBoundingClientRect().top + body.scrollTop;
+ body.scrollTop = Math.min(Math.max(offset - p, 0), body.scrollHeight - body.clientHeight);
+ }, [selector, pad]);
+ await page.waitForTimeout(400);
+}
+
+/**
+ * Pick tags in the upload modal's tag grid by name. The grid holds one
+ * button per unselected tag; clicking moves it into the selected strip.
+ */
+async function selectUploadTags(page, names) {
+ for (const name of names) {
+ const ok = await page.evaluate((n) => {
+ const grid = [...document.querySelectorAll('.upload-options-body .grid.grid-cols-2')]
+ .find((g) => g.offsetParent);
+ if (!grid) return false;
+ const btn = [...grid.querySelectorAll('button')].find(
+ (b) => b.innerText.trim() === n,
+ );
+ if (!btn) return false;
+ btn.click();
+ return true;
+ }, name);
+ if (!ok) throw new Error(`Tag "${name}" not offered in the upload tag grid`);
+ await page.waitForTimeout(300);
+ }
+ await settle(page, 400);
+}
+
+/**
+ * Choose a folder in the upload modal's folder <select> by visible name.
+ * The page carries offscreen copies of the modal markup, so the on-screen
+ * select is picked explicitly rather than by document order.
+ */
+async function selectUploadFolder(page, name) {
+ const ok = await page.evaluate((n) => {
+ const sel = [...document.querySelectorAll('.upload-options-body select')]
+ .find((s) => s.offsetParent);
+ if (!sel) return false;
+ const opt = [...sel.options].find((o) => o.textContent.trim() === n);
+ if (!opt) return false;
+ sel.value = opt.value;
+ sel.dispatchEvent(new Event('change', { bubbles: true }));
+ return true;
+ }, name);
+ if (!ok) throw new Error(`Folder "${name}" not found in the upload folder picker`);
+ await settle(page, 400);
+}
+
+/**
+ * Open the "Capturing system audio" guide and switch to one OS tab.
+ * The inline link only renders on platforms without native system-audio
+ * capture, so on Windows the modal is opened through the app's own
+ * state flag instead.
+ */
+async function openSystemAudioHelp(page, osTab) {
+ const viaLink = await clickVisible(page, 'button:has-text("how to enable full system audio")');
+ if (!viaLink) {
+ await page.evaluate(() => {
+ const app = document.getElementById('app');
+ const state = app && app.__vue_app__ && app.__vue_app__._instance
+ ? app.__vue_app__._instance.setupState : null;
+ if (!state) throw new Error('Vue setup state unavailable');
+ state.showSystemAudioHelp = true;
+ });
+ }
+ await page.waitForSelector('.modal-panel:has-text("Capturing system audio")', { state: 'visible' });
+ await settle(page, 500);
+ await page.evaluate((os) => {
+ const panel = [...document.querySelectorAll('.modal-panel')].find(
+ (p) => p.innerText.includes('Capturing system audio'),
+ );
+ const tab = [...panel.querySelectorAll('.tab')].find((b) => b.innerText.trim() === os);
+ if (!tab) throw new Error(`OS tab ${os} not found`);
+ tab.click();
+ }, osTab);
+ await settle(page, 500);
+ // Guides are long; start each one at the top of its body.
+ await page.evaluate(() => {
+ const body = document.querySelector('.modal-panel .modal-body');
+ if (body) body.scrollTop = 0;
+ });
+ await page.waitForTimeout(200);
+}
+
+/**
+ * Abort the server-side chunk session opened by the live recording.
+ *
+ * The harness screenshots after run() returns, so the in-app Stop →
+ * Discard buttons cannot be clicked before the frame is taken without
+ * losing the state being documented. This issues exactly the request
+ * discardRecording() issues (DELETE /upload/session/<id>), which marks
+ * the session aborted and deletes its chunk directory — so the shot
+ * leaves precisely what pressing Discard leaves, and nothing more. No
+ * Recording row is ever created; that only happens on upload, which
+ * this shot never performs.
+ */
+async function abandonLiveRecording(page) {
+ await page.evaluate(async () => {
+ let id = null;
+ try {
+ const raw = localStorage.getItem('speakr.serverRecordingSession');
+ if (raw) id = JSON.parse(raw).session_id;
+ } catch (_) { /* nothing stored */ }
+ if (!id) return;
+ const meta = document.querySelector('meta[name="csrf-token"]');
+ await fetch(`/upload/session/${encodeURIComponent(id)}`, {
+ method: 'DELETE',
+ credentials: 'same-origin',
+ headers: { 'X-CSRFToken': meta ? meta.getAttribute('content') : '' },
+ }).catch(() => {});
+ localStorage.removeItem('speakr.serverRecordingSession');
+ });
+}
+
+/** Copy the sample audio to plausible per-file names for the queue shot. */
+function makeMultiFileSet() {
+ const dir = path.join(tmpdir(), 'speakr-shots');
+ mkdirSync(dir, { recursive: true });
+ return [
+ 'team-standup-aug-12.mp3',
+ 'client-call-notes.mp3',
+ 'product-review.mp3',
+ ].map((name) => {
+ const dest = path.join(dir, name);
+ copyFileSync(SAMPLE_FILE, dest);
+ return dest;
+ });
+}
+
+export default [
+ {
+ name: 'recording-live-notes',
+ description: 'Recording live, with markdown notes alongside',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await installFakeMicrophone(page);
+ await openBackdrop(page);
+ await openUploadModal(page);
+
+ await clickVisible(page, 'button:has-text("Microphone")');
+ // Instances can gate recording behind a disclaimer modal
+ // ("Recording Notice"); accept it when it shows up. Matched by
+ // exact on-screen text because the page also carries offscreen
+ // buttons with the same label.
+ await page.waitForTimeout(1000);
+ await page.evaluate(() => {
+ const btn = [...document.querySelectorAll('.modal-overlay button')].find(
+ (b) => b.offsetParent && b.innerText.trim() === 'Start Recording',
+ );
+ if (btn) btn.click();
+ });
+
+ await page.waitForSelector('.recording-notes-editor .CodeMirror', { timeout: 30000 });
+ await settle(page, 800);
+
+ // The notes pane is an EasyMDE editor mounted over the textarea,
+ // so the text goes in through CodeMirror; its change handler is
+ // what syncs the value back into the app's recordingNotes state.
+ const typed = await page.evaluate((md) => {
+ const host = document.querySelector('.recording-notes-editor .CodeMirror');
+ if (!host || !host.CodeMirror) return false;
+ host.CodeMirror.setValue(md);
+ return true;
+ }, LIVE_NOTES);
+ if (!typed) throw new Error('Recording notes editor did not mount');
+ await page.waitForTimeout(500);
+
+ // Let the timer reach a plausible reading and the visualiser fill.
+ await page.waitForFunction(
+ () => /0:(2[0-9]|[3-9][0-9])/.test(document.body.innerText),
+ { timeout: 60000 },
+ ).catch(() => {});
+ await settle(page, 400);
+ await abandonLiveRecording(page);
+ },
+ },
+ {
+ name: 'upload-options',
+ description: 'Upload options: tags, folder, and language',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await queueFiles(page, [SAMPLE_FILE]);
+ await expandUploadOptions(page);
+ await selectUploadFolder(page, 'Learning');
+ await selectUploadTags(page, ['Interview', 'Important']);
+ await scrollModalTo(page, '.upload-options-group', 8);
+ },
+ },
+ {
+ name: 'upload-multi-file',
+ description: 'Uploading several files at once',
+ theme: { dark: true, scheme: 'teal' },
+ run: async (page) => {
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await queueFiles(page, makeMultiFileSet());
+ },
+ },
+ {
+ name: 'upload-duplicate-detection',
+ description: 'Duplicate files are detected before upload',
+ theme: { dark: true, scheme: 'purple' },
+ // Duplicate detection is a server-side SHA-256 match, so the UI for
+ // it is the copies indicator the match produces: an amber "N copies"
+ // chip on every recording sharing that hash, opening the list of
+ // copies. There is no client-side pre-upload check to capture, and
+ // the post-upload toast would need a throwaway upload to exist.
+ run: async (page) => {
+ await go(page, `/recordings/${DUPLICATE_RECORDING_ID}`, 1200);
+ await parkSidebar(page, SIDEBAR_ANCHOR);
+ await clickVisible(page, 'button.chip-meta--warn');
+ await page.waitForSelector('.modal-panel:has-text("copies")', { state: 'visible' });
+ await settle(page, 500);
+ },
+ },
+ {
+ name: 'recording-reprocess',
+ description: 'Reprocessing a recording end to end',
+ theme: { dark: true, scheme: 'rose' },
+ run: async (page) => {
+ await openBackdrop(page);
+ if (!(await clickVisible(page, 'button:has(i.fa-redo-alt)'))) {
+ throw new Error('Reprocess transcription button not found');
+ }
+ await page.waitForSelector('.modal-panel:has-text("Advanced ASR Options")', { state: 'visible' });
+ await settle(page, 600);
+ },
+ },
+ {
+ name: 'system-audio-help-windows',
+ description: 'Windows: the Share system audio checkbox',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await spoofPlatform(page, 'Win32');
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await openSystemAudioHelp(page, 'Windows');
+ },
+ },
+ {
+ name: 'system-audio-help-macos',
+ description: 'macOS: routing system audio through a virtual device',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await spoofPlatform(page, 'MacIntel');
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await openSystemAudioHelp(page, 'macOS');
+ },
+ },
+ {
+ name: 'system-audio-help-linux',
+ description: 'Linux: exposing a virtual source Chrome will list',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await openSystemAudioHelp(page, 'Linux');
+ },
+ },
+ {
+ name: 'recording-input-device-picker',
+ description: 'Mixing a microphone with a second input device',
+ theme: { dark: true, scheme: 'amber' },
+ run: async (page) => {
+ await spoofPlatform(page, 'MacIntel');
+ await installFakeInputDevices(page, [
+ { deviceId: 'default', groupId: 'grp-builtin', label: 'Default — MacBook Pro Microphone' },
+ { deviceId: 'mic-builtin', groupId: 'grp-builtin', label: 'MacBook Pro Microphone' },
+ { deviceId: 'blackhole-2ch', groupId: 'grp-virtual', label: 'BlackHole 2ch' },
+ ]);
+ await seedStorage(page, {
+ selectedMicDeviceId: 'mic-builtin',
+ selectedSecondaryDeviceId: 'blackhole-2ch',
+ });
+ await openBackdrop(page);
+ await openUploadModal(page);
+ await page.evaluate(() => {
+ const d = [...document.querySelectorAll('.modal-body details.disclosure-card')]
+ .find((x) => x.innerText.includes('Input'));
+ if (d) d.open = true;
+ });
+ await settle(page, 600);
+ await scrollModalTo(page, '.modal-body details.disclosure-card', 40);
+ },
+ },
+];
diff --git a/scripts/screenshots/shots/settings-admin.mjs b/scripts/screenshots/shots/settings-admin.mjs
new file mode 100644
index 00000000..f540dd9e
--- /dev/null
+++ b/scripts/screenshots/shots/settings-admin.mjs
@@ -0,0 +1,223 @@
+// Account settings and admin dashboard shots.
+//
+// Two classic server-rendered pages rather than the SPA: /account (tabbed,
+// each tab a `#content-*` panel with its own `.tab-scroll` scroller) and
+// /admin (a small Vue app whose tabs are driven by `activeTab`).
+
+import { go, settle, clickVisible, openRecordingByTitle } from '../helpers.mjs';
+
+/** A recording carrying tags, used for the localized interface shots. */
+const TAGGED_RECORDING = 'SEC/Data Science Team Updates and Announcements';
+
+/** Switch the /account page to a tab by its nav id ("prompts", "tokens", ...). */
+async function accountTab(page, name) {
+ await page.click(`#tab-${name}`);
+ await settle(page, 900);
+}
+
+/**
+ * Scroll the active tab's `.tab-scroll` container so the first VISIBLE element
+ * matching `selector` (optionally also containing `text`) sits near the top.
+ * Both pages render every tab's markup, so hidden duplicates must be skipped.
+ */
+async function scrollTabTo(page, selector, margin = 24, text = null) {
+ const found = await page.evaluate(([sel, m, txt]) => {
+ const target = [...document.querySelectorAll(sel)].find(
+ (el) => el.getBoundingClientRect().height > 0 && (!txt || el.textContent.includes(txt)),
+ );
+ if (!target) return false;
+ const scroller = target.closest('.tab-scroll');
+ if (!scroller) return false;
+ const offset = target.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop;
+ scroller.scrollTop = Math.min(Math.max(offset - m, 0), scroller.scrollHeight - scroller.clientHeight);
+ return true;
+ }, [selector, margin, text]);
+ if (!found) throw new Error(`Nothing visible to scroll to for ${selector}${text ? ` / ${text}` : ''}`);
+ await page.waitForTimeout(400);
+}
+
+/** Switch the /admin Vue dashboard to one of its tabs by label text. */
+async function adminTab(page, label) {
+ const ok = await clickVisible(page, `nav.tabs button:has-text(${JSON.stringify(label)})`);
+ if (!ok) throw new Error(`Admin tab ${label} not found`);
+ await settle(page, 1500);
+}
+
+/**
+ * Make sure a personal API token with this name exists, creating it through
+ * the real dialog on the first run only (so re-runs don't pile up tokens).
+ */
+async function ensureApiToken(page, name) {
+ const exists = await page.evaluate(async (n) => {
+ const res = await fetch('/api/tokens');
+ const body = await res.json();
+ return (body.tokens || []).some((t) => t.name === n && !t.revoked);
+ }, name);
+ if (exists) return;
+ await page.click('#createTokenBtn');
+ await page.waitForSelector('#createTokenModal:not(.hidden)');
+ await page.fill('#tokenNameInput', name);
+ await page.selectOption('#tokenExpirationSelect', '365');
+ await page.click('#submitCreateTokenBtn');
+ await page.waitForSelector('#tokenSecretModal:not(.hidden)', { timeout: 15000 });
+ await page.click('#closeTokenSecretModal');
+ await settle(page, 600);
+}
+
+/**
+ * Render the interface in another language WITHOUT touching the account's
+ * stored `ui_language`. Both the SPA bootstrap (templates/index.html) and
+ * i18n.init() read `localStorage.preferredLanguage` in preference to the
+ * server-rendered value, and the browser context is thrown away after the
+ * shot, so nothing about the account changes.
+ */
+async function useLanguage(page, locale) {
+ await page.context().addInitScript((l) => {
+ try { localStorage.setItem('preferredLanguage', l); } catch (_) {}
+ }, locale);
+}
+
+/** Fail loudly if the locale file did not actually take effect. */
+async function assertLocale(page, locale) {
+ const active = await page.evaluate(() => (window.i18n && window.i18n.currentLocale) || null);
+ if (active !== locale) throw new Error(`Interface locale is ${active}, expected ${locale}`);
+}
+
+export default [
+ {
+ name: 'custom-summary-prompt',
+ description: 'Customising the summary prompt',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await go(page, '/account');
+ await accountTab(page, 'prompts');
+ // Frame the whole "Summary Generation Prompt" card: the user's own
+ // prompt, and the admin default it overrides.
+ await scrollTabTo(page, '[data-i18n="customPrompts.summaryGeneration"]', 32);
+ },
+ },
+ {
+ name: 'settings-templates',
+ description: 'Export templates for transcripts and titles',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await go(page, '/account');
+ await accountTab(page, 'templates');
+ // Open one template so the editor shows a real body and the
+ // variable reference instead of the "select a template" placeholder.
+ if (!(await clickVisible(page, '#templatesList h4:has-text("Meeting Minutes")'))) {
+ throw new Error('Meeting Minutes template row not found');
+ }
+ await settle(page, 600);
+ },
+ },
+ {
+ name: 'settings-api-tokens',
+ description: 'Personal access tokens for the REST API',
+ theme: { dark: true, scheme: 'teal' },
+ run: async (page) => {
+ await go(page, '/account');
+ await accountTab(page, 'tokens');
+ // The reveal dialog dims the whole page behind it, so the shot
+ // shows the token list itself; the sample token is created (once)
+ // through that dialog so the list has a plausible entry.
+ await ensureApiToken(page, 'n8n automation');
+ },
+ },
+ {
+ name: 'settings-webhooks',
+ description: 'Outbound webhooks on recording events',
+ theme: { dark: true, scheme: 'purple' },
+ run: async (page) => {
+ await go(page, '/account');
+ await accountTab(page, 'webhooks');
+ // Expand the delivery log of the first endpoint so the shot shows
+ // the event history, not just the endpoint list.
+ await page.click('#webhook-list > div:first-child [data-action="deliveries"]');
+ await page.waitForFunction(
+ () => !/Loading/.test(document.querySelector('#webhook-list [data-deliveries-list]').innerText),
+ { timeout: 15000 },
+ );
+ await settle(page, 600);
+ },
+ },
+ {
+ name: 'admin-user-management',
+ description: 'Managing users',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ },
+ },
+ {
+ name: 'admin-group-management',
+ description: 'Managing groups',
+ theme: { dark: true, scheme: 'rose' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ await adminTab(page, 'Groups');
+ },
+ },
+ {
+ name: 'admin-system-settings',
+ description: 'System settings',
+ theme: { dark: true, scheme: 'amber' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ await adminTab(page, 'System Settings');
+ },
+ },
+ {
+ name: 'admin-default-prompt',
+ description: 'The default summarization prompt',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ await adminTab(page, 'Default Prompts');
+ },
+ },
+ {
+ name: 'admin-token-budgets',
+ description: 'Per-user monthly token budgets',
+ theme: { dark: true, scheme: 'teal' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ await adminTab(page, 'System Statistics');
+ // The budgets live below the instance-wide counters; the negative
+ // margin parks the section heading just above the frame so the
+ // whole per-user budget panel fits.
+ await scrollTabTo(page, 'h4', -60, 'Token Usage Statistics');
+ },
+ },
+ {
+ name: 'admin-vector-store',
+ description: 'Vector store status for semantic search',
+ theme: { dark: true, scheme: 'purple' },
+ run: async (page) => {
+ await go(page, '/admin', 1500);
+ await adminTab(page, 'Vector Store');
+ },
+ },
+ {
+ name: 'ui-german',
+ description: 'The full interface in German',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await useLanguage(page, 'de');
+ await go(page, '/');
+ await assertLocale(page, 'de');
+ await openRecordingByTitle(page, TAGGED_RECORDING);
+ },
+ },
+ {
+ name: 'ui-chinese',
+ description: 'The full interface in Chinese',
+ theme: { dark: true, scheme: 'purple' },
+ run: async (page) => {
+ await useLanguage(page, 'zh');
+ await go(page, '/');
+ await assertLocale(page, 'zh');
+ await openRecordingByTitle(page, TAGGED_RECORDING);
+ },
+ },
+];
diff --git a/scripts/screenshots/shots/speakers-tags.mjs b/scripts/screenshots/shots/speakers-tags.mjs
new file mode 100644
index 00000000..36be2a9c
--- /dev/null
+++ b/scripts/screenshots/shots/speakers-tags.mjs
@@ -0,0 +1,298 @@
+// Speaker identification, sharing, and per-tag settings.
+//
+// Seven shots: the Identify Speakers modal with voice-profile matches, the
+// same modal after the LLM has read the names out of the transcript, the
+// share dialog, and four views of the tag editor on the account page
+// (transcription defaults, summary prompt + title template, a real recipe
+// prompt, and the group auto-share options).
+
+import { go, settle, clickVisible, anchorSidebar } from '../helpers.mjs';
+
+/**
+ * Recordings are addressed by id via the /recordings/<id> deep link rather
+ * than by sidebar title: two recordings in the library share a title, and
+ * the deep link also removes the infinite-scroll dance from every shot.
+ */
+const REC = {
+ // Podcast panel, tagged AI. Four speakers are already named and the rest
+ // still carry diarization labels, three of which match a saved voice
+ // profile — so the modal shows named rows AND suggestion pills together.
+ voiceProfiles: 2279,
+ // Round of manager introductions, tagged Important. Every speaker is
+ // still a raw diarization label and each one says their own name in the
+ // transcript, which is exactly what Auto Identify reads — so the shot
+ // shows names arriving rather than contradicting existing labels.
+ autoIdentify: 2302,
+ // Tech podcast, tagged AI. This one already carries a public share link,
+ // so the dialog shows a real link instead of an empty state and the shot
+ // needs no share to be created.
+ share: 2296,
+};
+
+/** Sidebar row the list is parked on so the backdrop shows tagged rows. */
+const SIDEBAR_ANCHOR = 'Tiredness and Google Maps Scraping Insights';
+
+/**
+ * Park the sidebar list on a curated, tag-rich region: anchorSidebar loads
+ * the row into the (infinite-scroll) list, then the row is aligned to the top
+ * of the scroller by measured position — the app scrolls the list to the
+ * selected recording on load, which otherwise decides the framing.
+ */
+async function parkSidebar(page, title) {
+ await anchorSidebar(page, title);
+ await page.evaluate((wanted) => {
+ const h = [...document.querySelectorAll('h4')]
+ .find((el) => el.textContent.includes(wanted) && el.getBoundingClientRect().height > 0);
+ if (!h) return;
+ const list = h.closest('.overflow-y-auto');
+ const row = h.closest('[class*="border-b"]') || h.parentElement;
+ if (!list || !row) return;
+ list.scrollTop += row.getBoundingClientRect().top - list.getBoundingClientRect().top - 4;
+ }, title);
+ await page.waitForTimeout(400);
+}
+
+/** Wait until every toast has dismissed itself (they cover the top-right). */
+async function waitForToasts(page, timeoutMs = 20000) {
+ await page.waitForFunction(() => {
+ const c = document.getElementById('toastContainer');
+ return !c || c.children.length === 0;
+ }, { timeout: timeoutMs }).catch(() => {});
+ await page.waitForTimeout(300);
+}
+
+/** Open a recording by id and settle. */
+async function openRecording(page, id) {
+ await go(page, `/recordings/${id}`, 1500);
+ await page.waitForFunction(
+ () => !!document.querySelector('button[title="Share recording"]'),
+ { timeout: 20000 },
+ );
+ await settle(page, 600);
+}
+
+/** Open the Identify Speakers modal and wait for the speaker rows to render. */
+async function openSpeakerModal(page) {
+ if (!(await clickVisible(page, 'button[title="Identify speakers"]'))) {
+ throw new Error('Identify speakers button not found');
+ }
+ await page.waitForSelector('.modal-panel:has-text("Identify Speakers")', { state: 'visible' });
+ await page.waitForFunction(
+ () => document.querySelectorAll('.modal-panel input[type="text"]').length > 0,
+ { timeout: 20000 },
+ );
+ // Video recordings mount a player that is a black rectangle until it is
+ // played; collapse it to the audio-only view so the transcript fills the
+ // pane instead.
+ await clickVisible(page, 'button[title="Hide video (audio-only view)"]');
+ // Park the pointer on the modal header. Left where the click put it, it
+ // ends up over a transcript row and reveals that row's hover buttons.
+ await page.mouse.move(700, 60);
+ await settle(page, 800);
+}
+
+/** The scrolling left-hand column of speaker rows inside the modal. */
+const SPEAKER_COLUMN = '.modal-panel .lg\\:w-1\\/3';
+
+/**
+ * Wait for the voice-profile lookup to come back and park the speaker column
+ * so the rows carrying suggestion pills are on screen.
+ */
+async function showVoiceSuggestions(page) {
+ await page.waitForFunction(
+ () => [...document.querySelectorAll('.modal-panel button')]
+ .some((b) => /%$/.test(b.textContent.trim())),
+ { timeout: 30000 },
+ );
+ await page.waitForTimeout(500);
+ await page.evaluate((sel) => {
+ const col = document.querySelector(sel);
+ if (!col) return;
+ const pill = [...col.querySelectorAll('button')]
+ .find((b) => /%$/.test(b.textContent.trim()));
+ if (!pill) return;
+ const row = pill.closest('.space-y-2') || pill.parentElement;
+ const target = row.offsetTop - col.offsetTop - 12;
+ col.scrollTop = Math.max(0, Math.min(target, col.scrollHeight - col.clientHeight));
+ }, SPEAKER_COLUMN);
+ await page.waitForTimeout(400);
+}
+
+/**
+ * Run Auto Identify (a real LLM call) and wait until the names have landed
+ * in the fields and the progress toasts have gone.
+ */
+async function runAutoIdentify(page, timeoutMs = 180000) {
+ const before = await page.evaluate(() => [...document.querySelectorAll('.modal-panel input[type="text"]')]
+ .filter((i) => i.value.trim()).length);
+ if (!(await clickVisible(page, '.modal-footer button:has-text("Auto Identify")'))) {
+ throw new Error('Auto Identify button not found');
+ }
+ await page.waitForFunction(
+ (n) => {
+ const busy = [...document.querySelectorAll('.modal-footer .fa-spin')].length > 0;
+ const filled = [...document.querySelectorAll('.modal-panel input[type="text"]')]
+ .filter((i) => i.value.trim()).length;
+ return !busy && filled > n;
+ },
+ before,
+ { timeout: timeoutMs },
+ );
+ await waitForToasts(page);
+ await page.mouse.move(700, 60);
+ // Park the column at the top so the newly filled names read in order.
+ await page.evaluate((sel) => {
+ const col = document.querySelector(sel);
+ if (col) col.scrollTop = 0;
+ }, SPEAKER_COLUMN);
+ await settle(page, 600);
+}
+
+/**
+ * Open the tag editor on the account page for a tag by (partial) name and
+ * switch to one of its tabs. Nothing is ever saved — the values typed for
+ * the screenshots live only in the form.
+ */
+async function openTagEditor(page, tagName, tab) {
+ await go(page, '/account#tags', 1200);
+ await page.waitForFunction(
+ () => document.querySelectorAll('#tagsGrid .edit-tag-btn').length > 0,
+ { timeout: 20000 },
+ );
+ const found = await page.evaluate((name) => {
+ const card = [...document.querySelectorAll('#tagsGrid > div')]
+ .find((c) => c.querySelector('h3')?.textContent.trim().endsWith(name));
+ const btn = card?.querySelector('.edit-tag-btn');
+ if (!btn) return false;
+ btn.click();
+ return true;
+ }, tagName);
+ if (!found) throw new Error(`Tag card for ${tagName} not found`);
+ await page.waitForFunction(
+ () => !document.getElementById('tagModal').classList.contains('hidden'),
+ { timeout: 10000 },
+ );
+ await page.click(`#tagModalTabs [data-tab="${tab}"]`);
+ // Off the tab strip, so no control is left in its hover state.
+ await page.mouse.move(720, 1050);
+ await settle(page, 500);
+}
+
+/**
+ * Grow a textarea to its content height (the same thing the drag handle in
+ * its corner does) so a long prompt is readable instead of clipped mid-line,
+ * and drop focus so no field shows a focus ring in the shot.
+ */
+async function fitAndBlur(page, selector) {
+ await page.evaluate((sel) => {
+ const el = document.querySelector(sel);
+ if (el) {
+ el.style.height = 'auto';
+ el.style.height = `${el.scrollHeight + 2}px`;
+ }
+ document.activeElement?.blur();
+ }, selector);
+ await page.waitForTimeout(300);
+}
+
+export default [
+ {
+ name: 'speaker-id-voice-profiles',
+ description: 'Identifying speakers by their voice profile',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await openRecording(page, REC.voiceProfiles);
+ await parkSidebar(page, SIDEBAR_ANCHOR);
+ await openSpeakerModal(page);
+ await showVoiceSuggestions(page);
+ },
+ },
+ {
+ name: 'auto-name-recognition',
+ description: 'Speaker names recognised from the transcript',
+ theme: { dark: true, scheme: 'teal' },
+ run: async (page) => {
+ await openRecording(page, REC.autoIdentify);
+ await parkSidebar(page, SIDEBAR_ANCHOR);
+ await openSpeakerModal(page);
+ await runAutoIdentify(page);
+ },
+ },
+ {
+ name: 'share-modal',
+ description: 'Sharing a recording with users or a public link',
+ theme: { dark: true, scheme: 'purple' },
+ run: async (page) => {
+ await openRecording(page, REC.share);
+ await parkSidebar(page, SIDEBAR_ANCHOR);
+ if (!(await clickVisible(page, 'button[title="Share recording"]'))) {
+ throw new Error('Share recording button not found');
+ }
+ await page.waitForSelector('.modal-panel:has-text("Share Recording")', { state: 'visible' });
+ await settle(page, 1200);
+ },
+ },
+ {
+ name: 'tag-transcription-options',
+ description: 'Per-tag transcription and ASR settings',
+ theme: { dark: true, scheme: 'emerald' },
+ run: async (page) => {
+ await openTagEditor(page, 'Interview', 'tagTabTranscription');
+ // Example values only — the form is never submitted.
+ await page.fill('#tagLanguage', 'en');
+ await page.fill('#tagMinSpeakers', '2');
+ await page.fill('#tagMaxSpeakers', '4');
+ await page.fill('#tagHotwords', 'Speakr, WhisperX, PyAnnote, diarization');
+ await page.fill('#tagInitialPrompt', 'A recorded one-on-one interview between a host and a guest.');
+ await fitAndBlur(page, '#tagInitialPrompt');
+ await settle(page, 500);
+ },
+ },
+ {
+ name: 'tag-summary-template-options',
+ description: 'Per-tag summary prompt and title template',
+ theme: { dark: true, scheme: 'rose' },
+ run: async (page) => {
+ await openTagEditor(page, 'Interview', 'tagTabSummary');
+ await page.fill(
+ '#tagCustomPrompt',
+ 'Summarise this interview for a reader who did not attend. Open with a short '
+ + 'paragraph on who the guest is and why they were interviewed, then list the '
+ + 'main themes discussed with the guest’s own claims under each, and close '
+ + 'with any commitments, recommendations or follow-up questions raised.',
+ );
+ // Pick a real naming template so the title-template row shows a value.
+ await page.evaluate(() => {
+ const sel = document.getElementById('tagNamingTemplate');
+ const opt = [...sel.options].find((o) => /Date Prefix/i.test(o.textContent));
+ if (opt) {
+ sel.value = opt.value;
+ sel.dispatchEvent(new Event('change', { bubbles: true }));
+ }
+ });
+ await fitAndBlur(page, '#tagCustomPrompt');
+ await settle(page, 500);
+ },
+ },
+ {
+ name: 'tag-prompt-recipe-example',
+ description: 'A Recipe tag turning cooking narration into a formatted recipe',
+ theme: { dark: true, scheme: 'amber' },
+ run: async (page) => {
+ // The Cooking tag already carries a recipe prompt — nothing is typed
+ // and nothing is saved.
+ await openTagEditor(page, 'Cooking', 'tagTabSummary');
+ await fitAndBlur(page, '#tagCustomPrompt');
+ await settle(page, 400);
+ },
+ },
+ {
+ name: 'tag-sharing-options',
+ description: 'Group tags that auto-share to every member',
+ theme: { dark: true, scheme: 'blue' },
+ run: async (page) => {
+ await openTagEditor(page, 'Family', 'tagTabSharing');
+ await settle(page, 400);
+ },
+ },
+];