Speakr is a personal, self-hosted web application designed for transcribing audio recordings
Python
tooling: reproducible documentation screenshot harness (fixed 4:3 viewport, theme via localStorage, frozen animations) with pilot shot definitions for core, inquire and upload views
Murtaza Nasirff32d6a125ce
diff --git a/scripts/screenshots/.gitignore b/scripts/screenshots/.gitignorenew file mode 100644index 00000000..5c84fedf--- /dev/null+++ b/scripts/screenshots/.gitignore@@ -0,0 +1,4 @@+node_modules/+out/+.auth/+.envdiff --git a/scripts/screenshots/README.md b/scripts/screenshots/README.mdnew file mode 100644index 00000000..91a4832a--- /dev/null+++ b/scripts/screenshots/README.md@@ -0,0 +1,56 @@+# Documentation screenshots++Reproducible screenshot harness for the docs (`docs/screenshots.md`, README,+user guide pages). Every shot is defined as code, so after a UI change the+whole gallery can be regenerated identically.++## Standards++- Desktop: 1440x1080 viewport (exact 4:3), device scale 1.+- Mobile: 390x844 viewport at 3x.+- Dark mode by default, with the color scheme varied across shots+ (`blue`, `emerald`, `purple`, `rose`, `amber`, `teal`) to show the themes.+- Fixed locale (en-US) and timezone (America/Chicago); animations frozen.++## Usage++```bash+cd scripts/screenshots+# Node 20+ required (nvm use 22)+npm install && npx playwright install chromium # once+export SPEAKR_URL=https://your-dev-instance # defaults to spdev+export SPEAKR_EMAIL=... SPEAKR_PASSWORD=...+node capture.mjs --list # see all defined shots+node capture.mjs --file=shots/core.mjs # one area+node capture.mjs --only=main-view,upload-modal # specific shots+node capture.mjs --out=docs # write into docs/ (publish)+```++Without `--out=docs`, images land in `./out/` for review.++## Adding shots++Add an entry to a file in `shots/` (or a new file there):++```js+export default [+ {+ name: 'main-view', // output filename (no extension)+ description: 'The main view: recordings list, transcript, and summary',+ theme: { dark: true, scheme: 'blue' },+ // mobile: true, // phone viewport instead+ run: async (page) => { // drive the page into the state+ await go(page, '/');+ await openRecordingByTitle(page, 'Some Recording');+ },+ },+];+```++Helpers in `helpers.mjs`: `go(page, path)`, `openRecordingByTitle(page, title)`,+`clickVisible(page, selector)`, `settle(page)`. Text locators match hidden+template duplicates in this app — always use the visibility-filtering helpers.++Content on screen comes from the dev instance's data; pick recordings whose+titles/content look presentable (see existing captions in docs/screenshots.md+for the intent of each image).diff --git a/scripts/screenshots/capture.mjs b/scripts/screenshots/capture.mjsnew file mode 100644index 00000000..9cc4219a--- /dev/null+++ b/scripts/screenshots/capture.mjs@@ -0,0 +1,94 @@+#!/usr/bin/env node+// Reproducible documentation screenshots for Speakr.+//+// Usage:+// SPEAKR_EMAIL=... SPEAKR_PASSWORD=... node capture.mjs [--file=shots/core.mjs] [--only=name1,name2] [--out=docs] [--list]+//+// Every shot renders at a fixed 1440x1080 (exact 4:3) desktop viewport+// (mobile shots: 390x844 @3x), with the theme set via localStorage before+// the app boots, animations frozen, and a fixed locale/timezone — so a+// re-run after a UI change produces directly comparable images.+//+// Output goes to ./out/ by default (review before publishing); pass+// --out=docs to write straight into docs/assets/images/screenshots/.++import { chromium } from 'playwright';+import { readdir } from 'node:fs/promises';+import { mkdirSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';+import { makeContext, login, freezePage } from './helpers.mjs';++const HERE = path.dirname(fileURLToPath(import.meta.url));+const DOCS_OUT = path.resolve(HERE, '../../docs/assets/images/screenshots');++const args = Object.fromEntries(process.argv.slice(2).map((a) => {+ const m = a.match(/^--([^=]+)(?:=(.*))?$/);+ return m ? [m[1], m[2] ?? true] : [a, true];+}));++async function loadShots() {+ const dir = path.join(HERE, 'shots');+ const files = args.file+ ? [path.resolve(HERE, String(args.file).replace(/^shots\//, 'shots/'))]+ : (await readdir(dir)).filter((f) => f.endsWith('.mjs')).map((f) => path.join(dir, f));+ const shots = [];+ for (const file of files) {+ const mod = await import(pathToFileURL(file).href);+ for (const shot of mod.default || []) {+ shots.push({ ...shot, sourceFile: path.basename(file) });+ }+ }+ return shots;+}++async function main() {+ let shots = await loadShots();+ if (args.list) {+ for (const s of shots) console.log(`${s.sourceFile}: ${s.name} — ${s.description || ''}`);+ return;+ }+ if (args.only) {+ const wanted = String(args.only).split(',').map((s) => s.trim());+ shots = shots.filter((s) => wanted.includes(s.name));+ }+ if (!shots.length) {+ console.error('No shots selected.');+ process.exit(1);+ }++ const outDir = args.out === 'docs' ? DOCS_OUT : path.join(HERE, 'out');+ mkdirSync(outDir, { recursive: true });++ const browser = await chromium.launch();+ console.log('Logging in...');+ const storageState = await login(browser);++ let failed = 0;+ for (const shot of shots) {+ const label = `${shot.name} [dark=${shot.theme?.dark !== false} scheme=${shot.theme?.scheme || 'blue'}]`;+ process.stdout.write(`Capturing ${label} ... `);+ const context = await makeContext(browser, { ...(shot.theme || {}), mobile: !!shot.mobile, storageState });+ const page = await context.newPage();+ try {+ await shot.run(page);+ await freezePage(page);+ await page.waitForTimeout(300);+ const file = path.join(outDir, `${shot.name}.png`);+ await page.screenshot({ path: file, animations: 'disabled' });+ console.log(`ok -> ${path.relative(process.cwd(), file)}`);+ } catch (e) {+ failed++;+ console.log(`FAILED: ${e.message}`);+ } finally {+ await context.close();+ }+ }+ await browser.close();+ if (failed) {+ console.error(`${failed} shot(s) failed.`);+ process.exit(1);+ }+}++main().catch((e) => { console.error(e); process.exit(1); });diff --git a/scripts/screenshots/helpers.mjs b/scripts/screenshots/helpers.mjsnew file mode 100644index 00000000..80e91815--- /dev/null+++ b/scripts/screenshots/helpers.mjs@@ -0,0 +1,121 @@+// Shared helpers for reproducible Speakr documentation screenshots.++export const BASE_URL = process.env.SPEAKR_URL || 'https://spdev.murtaza.cc';++/** Exact 4:3 desktop viewport used for every documentation screenshot. */+export const VIEWPORT = { width: 1440, height: 1080 };+/** Phone viewport for mobile shots (portrait, 3x for crispness). */+export const MOBILE_VIEWPORT = { width: 390, height: 844 };++/**+ * Create a browser context pre-configured for a deterministic shot.+ * theme: { dark: true, scheme: 'blue'|'emerald'|'purple'|'rose'|'amber'|'teal' }+ */+export async function makeContext(browser, { dark = true, scheme = 'blue', mobile = false, storageState } = {}) {+ const context = await browser.newContext({+ viewport: mobile ? MOBILE_VIEWPORT : VIEWPORT,+ deviceScaleFactor: mobile ? 3 : 1,+ locale: 'en-US',+ timezoneId: 'America/Chicago',+ colorScheme: dark ? 'dark' : 'light',+ reducedMotion: 'reduce',+ storageState,+ ...(mobile ? { isMobile: true, hasTouch: true } : {}),+ });+ // Theme is decided BEFORE the app boots so there is no flash and no+ // dependency on UI interaction order.+ await context.addInitScript(([d, s]) => {+ try {+ localStorage.setItem('darkMode', d ? 'true' : 'false');+ if (s && s !== 'blue') localStorage.setItem('colorScheme', s);+ else localStorage.removeItem('colorScheme');+ } catch (_) {}+ }, [dark, scheme]);+ return context;+}++/** Kill animations/transitions and hide carets so pixels are stable. */+export async function freezePage(page) {+ await page.addStyleTag({+ content: `+ *, *::before, *::after {+ transition: none !important;+ animation-duration: 0.001s !important;+ animation-iteration-count: 1 !important;+ caret-color: transparent !important;+ }+ `,+ });+}++/** Wait for the SPA to be genuinely settled (loader gone, fonts in, net idle). */+export async function settle(page, extraMs = 800) {+ await page.waitForLoadState('networkidle').catch(() => {});+ await page.waitForFunction(() => {+ const l = document.getElementById('loading-overlay') || document.querySelector('.loading-overlay');+ return !l || l.offsetParent === null;+ }, { timeout: 15000 }).catch(() => {});+ await page.evaluate(() => document.fonts && document.fonts.ready).catch(() => {});+ await page.waitForTimeout(extraMs);+}++/** Log in and return a storageState the runner reuses for every shot. */+export async function login(browser) {+ const email = process.env.SPEAKR_EMAIL;+ const password = process.env.SPEAKR_PASSWORD;+ if (!email || !password) {+ throw new Error('Set SPEAKR_EMAIL and SPEAKR_PASSWORD in the environment');+ }+ const context = await browser.newContext({ viewport: VIEWPORT });+ const page = await context.newPage();+ await page.goto(`${BASE_URL}/login`, { waitUntil: 'networkidle' });+ await page.locator('input[name="email"]:visible').first().fill(email);+ await page.locator('input[name="password"]:visible').first().fill(password);+ const form = page.locator('form:has(input[name="password"]:visible)').first();+ await Promise.all([+ page.waitForURL((u) => !String(u).includes('/login'), { timeout: 20000 }),+ form.locator('button[type="submit"], input[type="submit"]').first().click(),+ ]);+ const state = await context.storageState();+ await context.close();+ return state;+}++/** Navigate to a path and settle. */+export async function go(page, path, extraMs) {+ await page.goto(`${BASE_URL}${path}`, { waitUntil: 'domcontentloaded' });+ await settle(page, extraMs);+ await freezePage(page);+}++/**+ * Open a recording by (partial) title via the sidebar list. Text locators+ * match hidden template duplicates, so filter by on-screen position.+ */+export async function openRecordingByTitle(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 box = await cands.nth(i).boundingBox();+ if (box && box.y >= 0 && box.x >= 0) {+ await cands.nth(i).click();+ await settle(page, 1000);+ return;+ }+ }+ throw new Error(`Recording titled ${title} not visible in the sidebar`);+}++/** Click the first VISIBLE element matching a locator (skip hidden dupes). */+export async function clickVisible(page, selector) {+ const cands = page.locator(selector);+ const n = await cands.count();+ for (let i = 0; i < n; i++) {+ const box = await cands.nth(i).boundingBox();+ if (box) {+ await cands.nth(i).click();+ return true;+ }+ }+ return false;+}diff --git a/scripts/screenshots/package.json b/scripts/screenshots/package.jsonnew file mode 100644index 00000000..70e13742--- /dev/null+++ b/scripts/screenshots/package.json@@ -0,0 +1,12 @@+{+ "name": "speakr-screenshots",+ "private": true,+ "type": "module",+ "description": "Reproducible documentation screenshots for Speakr",+ "scripts": {+ "capture": "node capture.mjs"+ },+ "dependencies": {+ "playwright": "^1.47.2"+ }+}diff --git a/scripts/screenshots/shots/_smoke.mjs b/scripts/screenshots/shots/_smoke.mjsnew file mode 100644index 00000000..9108938e--- /dev/null+++ b/scripts/screenshots/shots/_smoke.mjs@@ -0,0 +1,13 @@+// Harness smoke test: one trivial shot. Not part of the documentation set.+import { go } from '../helpers.mjs';++export default [+ {+ name: 'smoke-main',+ description: 'Harness smoke test: the main library view after login',+ theme: { dark: true, scheme: 'blue' },+ run: async (page) => {+ await go(page, '/');+ },+ },+];diff --git a/scripts/screenshots/shots/core.mjs b/scripts/screenshots/shots/core.mjsnew file mode 100644index 00000000..19e95df6--- /dev/null+++ b/scripts/screenshots/shots/core.mjs@@ -0,0 +1,130 @@+// Core documentation shots: the main view, per-recording stats, and the+// sidebar filter panel. See docs/screenshots.md for the captions these serve.++import { go, settle, openRecordingByTitle, clickVisible } from '../helpers.mjs';++/** The scrolling container of the sidebar recordings list. */+const SIDEBAR_SCROLLER = '.flex-1.overflow-y-auto.pb-3';++/**+ * The sidebar list is paginated by infinite scroll, so a recording further+ * down the library is not in the DOM until the list has been scrolled.+ * Scroll to the bottom repeatedly until the title shows up.+ */+async function loadSidebarUntil(page, title, maxPages = 20) {+ let lastHeight = -1;+ for (let i = 0; i < maxPages; i++) {+ const found = await page.evaluate(+ (t) => [...document.querySelectorAll('h4')].some(+ (h) => h.textContent.includes(t) && h.getBoundingClientRect().height > 0,+ ),+ title,+ );+ if (found) return;+ const height = await page.evaluate((sel) => {+ const s = document.querySelector(sel);+ if (!s) return -1;+ s.scrollTop = s.scrollHeight;+ return s.scrollHeight;+ }, SIDEBAR_SCROLLER);+ if (height === lastHeight || height < 0) break; // whole library loaded+ lastHeight = height;+ await page.waitForTimeout(900);+ }+ throw new Error(`Recording titled ${title} never appeared in the sidebar list`);+}++/**+ * Open a recording, loading more of the list first if needed, then park the+ * sidebar so the selected row sits in the middle of the list (stable framing+ * regardless of how far down the library the recording lives).+ */+async function openRecording(page, title) {+ await loadSidebarUntil(page, title);+ await openRecordingByTitle(page, title);+ await page.evaluate((t) => {+ const h = [...document.querySelectorAll('h4')].find(+ (x) => x.textContent.includes(t) && x.getBoundingClientRect().height > 0,+ );+ if (h) h.scrollIntoView({ block: 'center', behavior: 'instant' });+ }, title);+ await settle(page, 500);+}++/** Open the collapsed filter panel above the recordings list. */+async function openFilterPanel(page) {+ await clickVisible(page, 'button:has-text("Search recordings...")');+ await page.waitForSelector('text=Filter by tag', { state: 'visible' });+ await settle(page, 400);+}++/**+ * Click a tag chip inside the filter panel. Recording rows carry same-named+ * tag chips of their own, so scope the click to the panel's "Filter by tag"+ * card via a temporary marker attribute.+ */+async function applyTagFilter(page, tag) {+ const marked = await page.evaluate((t) => {+ const label = [...document.querySelectorAll('label')].find(+ (e) => e.textContent.trim() === 'Filter by tag',+ );+ if (!label) return false;+ const card = label.closest('div').parentElement;+ const chip = [...card.querySelectorAll('button')].find(+ (b) => b.textContent.trim() === t,+ );+ if (!chip) return false;+ chip.setAttribute('data-shot-target', 'tag-filter');+ return true;+ }, tag);+ if (!marked) throw new Error(`Tag filter chip for ${tag} not found in the filter panel`);+ await page.click('[data-shot-target="tag-filter"]');+ await settle(page, 900);+ await page.evaluate((sel) => {+ const el = document.querySelector('[data-shot-target="tag-filter"]');+ if (el) el.removeAttribute('data-shot-target');+ // Show the filtered results from the top rather than wherever the+ // unfiltered list happened to be parked.+ const s = document.querySelector(sel);+ if (s) s.scrollTop = 0;+ }, SIDEBAR_SCROLLER);+ await settle(page, 400);+}++export default [+ {+ name: 'main-view',+ description: 'The main view: recordings list, transcript, and summary',+ theme: { dark: true, scheme: 'blue' },+ run: async (page) => {+ await go(page, '/');+ await openRecording(page, 'Railroad Tax on Stock Compensation Remuneration');+ },+ },+ {+ name: 'main-view-stats',+ description: 'Per-recording stats and speaker breakdown',+ theme: { dark: true, scheme: 'teal' },+ run: async (page) => {+ await go(page, '/');+ await openRecording(page, 'SEC/Data Science Team Updates and Announcements');+ await clickVisible(page, '.tab:has-text("Stats")');+ await settle(page, 600);+ // The per-speaker table needs the full width to show every column,+ // so collapse the sidebar for this one shot.+ await clickVisible(page, 'button[title="Hide sidebar"]');+ await settle(page, 600);+ },+ },+ {+ name: 'sidebar-filtering',+ description: 'Advanced filtering in the sidebar',+ theme: { dark: true, scheme: 'amber' },+ run: async (page) => {+ await go(page, '/');+ await openRecording(page, 'SEC/Data Science Team Updates and Announcements');+ await openFilterPanel(page);+ await applyTagFilter(page, 'AI');+ },+ },+];diff --git a/scripts/screenshots/shots/inquire.mjs b/scripts/screenshots/shots/inquire.mjsnew file mode 100644index 00000000..883b70ca--- /dev/null+++ b/scripts/screenshots/shots/inquire.mjs@@ -0,0 +1,155 @@+// Inquire mode and the upload dialog.+//+// Three shots: the agentic Inquire answer (activity line + citation chips ++// sources), the upload dialog with a queued file, and the same dialog with+// the per-upload transcription/diarization options expanded.++import { go, settle, clickVisible, 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';++/** Recording opened behind the upload dialog so the backdrop isn't empty. */+const BACKDROP_RECORDING = 'Ford Recalls Engineers';++/** The question asked in the Inquire shot — fixed, so re-runs are comparable. */+const QUESTION = 'What did we discuss about the MR rate within SEC? Cite where.';++/**+ * Ask the Inquire agent a question and wait for the finished answer: the+ * agent runs live tool steps, so this polls until the loading card and every+ * spinner are gone, the sources footer has been rendered, and the answer text+ * has stopped growing.+ */+async function askInquire(page, question, timeoutMs = 180000) {+ const box = page.locator('textarea:visible').first();+ await box.click();+ await box.fill(question);+ await page.keyboard.press('Enter');++ const deadline = Date.now() + timeoutMs;+ let previous = null;+ let stableFor = 0;+ while (Date.now() < deadline) {+ const state = await page.evaluate(() => {+ const visible = (el) => !!el.offsetParent;+ const answers = [...document.querySelectorAll('.chat-message.ai-message')].filter(visible);+ const last = answers[answers.length - 1];+ return {+ busy: [...document.querySelectorAll('.spinner, .fa-spin')].filter(visible).length > 0,+ sources: !!document.querySelector('.citation-refs'),+ activity: !!document.querySelector('.chat-message .fa-list-check'),+ length: last ? last.innerText.length : 0,+ };+ });+ if (!state.busy && state.sources && state.activity && state.length > 0) {+ stableFor = state.length === previous ? stableFor + 1 : 0;+ previous = state.length;+ if (stableFor >= 2) return;+ } else {+ stableFor = 0;+ previous = state.length;+ }+ await page.waitForTimeout(1500);+ }+ throw new Error('Inquire answer did not finish in time');+}++/**+ * Frame the latest answer in the message pane: top-aligned when it fits,+ * otherwise scrolled to the end so the sources footer stays visible.+ */+async function frameLatestAnswer(page) {+ await page.evaluate(() => {+ const answers = [...document.querySelectorAll('.chat-message.ai-message')];+ const msg = answers[answers.length - 1];+ if (!msg) return;+ let scroller = msg.parentElement;+ while (scroller && scroller.scrollHeight <= scroller.clientHeight + 4) scroller = scroller.parentElement;+ if (!scroller) return; // everything already fits on screen+ const offset = msg.getBoundingClientRect().top - scroller.getBoundingClientRect().top + scroller.scrollTop;+ const max = scroller.scrollHeight - scroller.clientHeight;+ scroller.scrollTop = msg.offsetHeight > scroller.clientHeight ? max : Math.min(Math.max(offset - 24, 0), max);+ });+ await page.waitForTimeout(400);+}++/** Open the upload dialog from the header and queue a file without uploading. */+async function openUploadDialogWithFile(page) {+ await go(page, '/');+ await openRecordingByTitle(page, BACKDROP_RECORDING);+ if (!(await clickVisible(page, 'button:has-text("New Recording")'))) {+ throw new Error('New Recording button not found');+ }+ await settle(page, 800);+ await page.setInputFiles('input[type=file]', SAMPLE_FILE);+ // Wait for the queue row to show the probed size/duration, not just the name.+ await page.waitForFunction(+ () => /\(\d[\d.]* MB, /.test(document.body.innerText),+ { timeout: 20000 },+ ).catch(() => {});+ await settle(page, 600);+}++/** Scroll an element inside the modal body into a comfortable position. */+async function scrollModalTo(page, selector) {+ await page.evaluate((sel) => {+ 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 - 24, 0), body.scrollHeight - body.clientHeight);+ }, selector);+ await page.waitForTimeout(400);+}++export default [+ {+ name: 'inquire-semantic-search',+ description: 'Inquire Mode: ask questions across all your recordings, filtered by tag, speaker, or date',+ theme: { dark: true, scheme: 'purple' },+ run: async (page) => {+ await go(page, '/inquire');+ await askInquire(page, QUESTION);+ await settle(page, 800);+ await frameLatestAnswer(page);+ },+ },+ {+ name: 'upload-modal',+ description: 'Uploading a file',+ theme: { dark: true, scheme: 'emerald' },+ run: async (page) => {+ await openUploadDialogWithFile(page);+ },+ },+ {+ name: 'upload-asr-options',+ description: 'Per-upload transcription and diarization options',+ theme: { dark: true, scheme: 'rose' },+ run: async (page) => {+ await openUploadDialogWithFile(page);+ // Expand the "Options" progressive-disclosure group, then the+ // "Transcription Options" panel inside it.+ await page.evaluate(() => {+ document.querySelectorAll('details.upload-options-group').forEach((d) => { d.open = true; });+ });+ await page.waitForTimeout(400);+ if (!(await clickVisible(page, 'button:has-text("Transcription Options")'))) {+ throw new Error('Transcription Options disclosure not found');+ }+ await settle(page, 800);+ // Fill the fields so the panel shows real values rather than+ // placeholders (these are per-upload only, nothing is saved).+ const prompt = page.locator('.disclosure-panel textarea:visible').first();+ await prompt.fill('This is a SEC/Data Science team meeting about merge request throughput.');+ const hotwords = page.locator('.disclosure-panel input[type="text"]:visible').first();+ await hotwords.fill('Speakr, WhisperX, diarization');+ const numbers = page.locator('.disclosure-panel input[type="number"]:visible');+ await numbers.nth(0).fill('2');+ await numbers.nth(1).fill('5');+ await settle(page, 500);+ await scrollModalTo(page, '.disclosure-panel');+ },+ },+];