01 — Requirements
Each requirement has a stable ID used across the roadmap, tests, and commits. Priority:
M = must (v1), S = should, C = could (later). Each FR notes the phase that delivers it
(see 05-roadmap.md).
Functional requirements
Audio capture (CAP)
| ID |
Pri |
Phase |
Requirement |
| FR-CAP-1 |
M |
1 |
Capture system (loopback) audio on Windows via WASAPI without a meeting bot or microphone. |
| FR-CAP-2 |
M |
1 |
Write captured audio to disk continuously during recording (audio = source of truth). |
| FR-CAP-3 |
M |
1 |
Start, stop, pause, and resume recording from the UI. |
| FR-CAP-4 |
M |
1 |
Show an unambiguous "recording active" indicator (in-app banner + tray icon). |
| FR-CAP-5 |
S |
7 |
Render a live input waveform / level meter while recording. |
| FR-CAP-6 |
S |
7 |
Handle audio device changes mid-recording without losing the session. |
| FR-CAP-7 |
S |
1 |
Optionally capture the user's microphone alongside loopback, mixing it into both the live transcript and the saved recording (default ON, local-only/no egress, selectable device + "off"). |
| FR-CAP-8 |
S |
1 |
Write the retained recording as 16-bit PCM at the device's native rate/channels — roughly half the size of the 32-bit-float mix, with no material quality loss for speech. |
| FR-CAP-9 |
S |
1 |
Cancel an in-progress recording: stop capture, delete working files, and remove the meeting from the DB entirely (for one started by mistake — no finalize/transcript/sync). |
Recording retention & consent (REC) — see ADR-0009
| ID |
Pri |
Phase |
Requirement |
| FR-REC-1 |
M |
1 |
"Record this meeting" is off by default (global default + per-meeting toggle). When on, the meeting's audio is retained and saved as a .wav file; when off, working audio is deleted on finalize and only the transcript/notes persist. |
| FR-REC-2 |
M |
1 |
Before retaining a recording for the first time (and shown near the toggle thereafter), display a consent notice: recording without participants' consent may be illegal in some regions; advise checking local laws. Require a one-time acknowledgment; store it. This is a caution, not legal advice. |
| FR-REC-3 |
M |
1 |
When retention is on, the UI indicates the meeting is being saved (in addition to the "recording active" indicator, FR-CAP-4). |
| FR-REC-4 |
M |
2 |
Deleting working audio on finalize happens only after the transcript is successfully finalized; never race with crash recovery (audio stays source of truth until then). |
| FR-REC-5 |
S |
2 |
Play a meeting's retained .wav back in the app (decrypting a vault-sealed recording on demand for playback). |
Hardware acceleration (HW)
| ID |
Pri |
Phase |
Requirement |
| FR-HW-1 |
M |
3 |
Detect available compute backends at startup and on demand: NPU, NVIDIA, AMD, Intel GPU, CPU. |
| FR-HW-2 |
S |
3 |
Select the best backend by the order NPU→NVIDIA→AMD→Intel→CPU; allow a manual override. |
| FR-HW-3 |
M |
3 |
Display the active backend, model size, and estimated RTF in Settings and the recording bar. |
| FR-HW-4 |
M |
3 |
Fall back gracefully to a lower tier (down to CPU) when a backend is unavailable or fails. |
Transcription (TRX)
| ID |
Pri |
Phase |
Requirement |
| FR-TRX-1 |
M |
1 |
Transcribe audio to timestamped text segments using a Whisper-class model (CPU baseline). |
| FR-TRX-2 |
M |
1 |
Stream interim transcript segments to the UI in near real time during recording. |
| FR-TRX-3 |
S |
3 |
Offer a post-meeting batch re-transcription with a larger model for higher accuracy. |
| FR-TRX-4 |
S |
8 |
Support multiple languages via multilingual Whisper models; expose language selection/auto. |
| FR-TRX-5 |
M |
3 |
Run accelerated inference (NPU/GPU) when available; identical segment output across backends. |
Speaker diarization & naming (SPK)
| ID |
Pri |
Phase |
Requirement |
| FR-SPK-1 |
M |
4 |
Assign internal speaker IDs (S1, S2, …) to transcript segments via offline diarization. |
| FR-SPK-2 |
M |
4 |
Let the user name a speaker during recording; apply to that speaker's past & future segments. |
| FR-SPK-3 |
M |
4 |
Provide a post-meeting review to rename speakers and merge over-split speakers. |
| FR-SPK-4 |
S |
6 |
Populate the naming UI with attendees from the linked calendar event, plus "add new name". |
| FR-SPK-5 |
M |
4 |
Persist speaker→name mappings and apply them at render/export (never destructively rewrite). |
Notes & Markdown (NOTE)
| ID |
Pri |
Phase |
Requirement |
| FR-NOTE-1 |
M |
2 |
Present meeting notes as rendered Markdown with speaker-tagged dialogue sections. |
| FR-NOTE-2 |
M |
2 |
Edit notes (headings, bold/italic, lists, checkboxes) via Markdown syntax and/or a toolbar. |
| FR-NOTE-3 |
M |
2 |
Export a meeting's notes as .md. |
| FR-NOTE-4 |
S |
8 |
Export notes as PDF and/or Word via local conversion (no cloud). |
| FR-NOTE-5 |
C |
8 |
User-defined note templates by meeting type (e.g. Sales Call, 1:1, Standup). |
| FR-NOTE-6 |
S |
2 |
Show raw transcript and rendered notes side-by-side. |
Local LLM (LLM)
| ID |
Pri |
Phase |
Requirement |
| FR-LLM-1 |
M |
5 |
Configure a local LLM provider (Ollama default, custom OpenAI-compatible endpoint, or off). |
| FR-LLM-2 |
M |
5 |
Generate a summary, decisions, and action items from transcript + metadata (+ optional template). |
| FR-LLM-3 |
M |
5 |
Parse LLM output into editable action items the user confirms before they become tasks. |
| FR-LLM-4 |
S |
5 |
Stream LLM output token-by-token into the summary panel. |
| FR-LLM-5 |
S |
5 |
Detect a missing provider and offer guided install + hardware-aware model suggestions. |
| FR-LLM-6 |
M |
5 |
Validate the endpoint is local; if remote/proxying, show a clear "data leaves WA" banner. |
External AI providers (AI) — see ADR-0011 (Layer 1), ADR-0007 update
| ID |
Pri |
Phase |
Requirement |
| FR-AI-1 |
S |
10 |
Optionally configure a hosted summary provider behind the same LlmProvider model: Anthropic Messages API and an OpenAI-compatible client (OpenAI, OpenRouter, LM Studio, gateways). Off by default. |
| FR-AI-2 |
M |
10 |
Hosted providers are explicit third-party egress: off by default, labeled "data leaves your device", host added to the settings-derived allowlist, API keys in the OS credential store (never settings/DB). |
| FR-AI-3 |
S |
10 |
Per-use provider selection is allowed (e.g. local Ollama for one meeting, Claude for another); the active provider is shown wherever a summary is generated. |
MCP server — WhispAssist as a tool source (MCP) — see ADR-0011 (Layer 2)
WA exposes its own meeting context to the user's coding agents (Claude, Codex, Copilot, OpenCode,
…) via a local MCP server. This is the primary "get started right away" handoff (pull model).
| ID |
Pri |
Phase |
Requirement |
| FR-MCP-1 |
S |
10 |
WA can expose a local MCP server, off by default, bound to loopback, requiring a token; explicit enable. |
| FR-MCP-2 |
M |
10 |
Capabilities are exposed as MCP tools (not resources/prompts) for max client compatibility (Copilot cloud agent supports tools only): e.g. list_recent_meetings, get_transcript, get_action_items, get_feature_brief. |
| FR-MCP-3 |
M |
10 |
Scope control: the user chooses which meetings/artifacts are exposed; recordings (.wav) are never exposed unless explicitly allowed. |
| FR-MCP-4 |
S |
10 |
Feature brief primitive: distill a transcript (via the configured LLM) into a structured, agent-ready spec — problem, desired outcome, acceptance criteria, target repo/context, source meeting — served by get_feature_brief/create_feature_brief. |
| FR-MCP-5 |
M |
10 |
Disclosure + audit: the UI states that a connected agent may send served data to its provider's cloud (outside WA's control); WA logs what each agent read. |
| FR-MCP-6 |
S |
10 |
Support both MCP transports: stdio (thin adapter) and Streamable HTTP on loopback (/mcp). HTTP+SSE (deprecated) is not used. |
| FR-MCP-7 |
M |
all |
The MCP server is inbound on loopback and adds no WA egress; enabling it must not add any host to the egress allowlist. |
Agent push & task-tracker handoff (AGENT) — see ADR-0011 (Layer 3, later)
| ID |
Pri |
Phase |
Requirement |
| FR-AGENT-1 |
C |
10c |
Optional AgentRunner: spawn a local coding-agent CLI headless (claude -p, codex exec, opencode run, copilot) against a user-chosen repo to produce a branch/PR from a feature brief. |
| FR-AGENT-2 |
C |
10c |
Optional task-tracker handoff: create a GitHub issue from a confirmed action item / feature brief; optionally assign Copilot's cloud agent. Third-party egress: off by default, labeled, allowlisted. |
Storage & persistence (STORE)
| ID |
Pri |
Phase |
Requirement |
| FR-STORE-1 |
M |
2 |
Persist audio, transcript, notes, and metadata locally (files + SQLite index). |
| FR-STORE-2 |
S |
2 |
Configure base storage directory and a retention policy (max size and/or max age). |
| FR-STORE-3 |
M |
2 |
Single-meeting export (audio + transcript + notes) to a chosen folder. |
| FR-STORE-4 |
S |
8 |
Bulk export by date range or tag. |
| FR-STORE-5 |
M |
2 |
List, open, and delete meetings. |
Search & tagging (SEARCH)
| ID |
Pri |
Phase |
Requirement |
| FR-SEARCH-1 |
S |
8 |
Full-text search across transcripts and notes (SQLite FTS5). |
| FR-SEARCH-2 |
S |
8 |
Tag meetings (project/client/topic) and filter the list by date, tag, or participant. |
Calendar & Outlook .pst (CAL)
| ID |
Pri |
Phase |
Requirement |
| FR-CAL-1 |
S |
6 |
Read a user-selected .pst (with optional password) and extract events + attendees. |
| FR-CAL-2 |
S |
6 |
Show upcoming/recent meetings; let the user attach a recording to an event. |
| FR-CAL-3 |
S |
6 |
Display pre-meeting context: title, organizer, participants. |
| FR-CAL-4 |
C |
6 |
Link a recording to a historical event from .pst history. |
| FR-CAL-5 |
C |
8 |
Create local reminders / OS notifications for action items. |
| FR-CAL-6 |
C |
later |
Optional Microsoft Graph calendar source (explicit consent; calendar metadata only). |
Remote sync / upload (SYNC) — see ADR-0010
Sync is an explicit, user-configured export; it is the only egress for meeting content besides
the local LLM endpoint, and it is off by default. Primary targets are self-hostable.
| ID |
Pri |
Phase |
Requirement |
| FR-SYNC-1 |
M |
9 |
Sync is disabled by default. No artifact is uploaded anywhere unless the user has configured a target and explicitly enabled it (with acknowledgment). |
| FR-SYNC-2 |
M |
9 |
Configure one or more WebDAV targets covering the primary set — Nextcloud, ownCloud, Cloudreve, Seafile — and Synology (URL + username + app password; user-chosen remote base path). |
| FR-SYNC-3 |
M |
9 |
Choose, per target, what to upload (transcript, notes, summary, and — only if retained per FR-REC-1 — the .wav recording) and when (on finalize, manual "Upload now", and automatic retry). |
| FR-SYNC-4 |
M |
9 |
"Test connection" validates a target's reachability + credentials before saving. |
| FR-SYNC-5 |
M |
9 |
Durable upload queue with per-job status, exponential-backoff retry, SHA-256 skip-if-unchanged (idempotent), and resumable/chunked upload for large recordings. |
| FR-SYNC-6 |
M |
9 |
Store target credentials in the OS credential store (Windows Credential Manager / DPAPI), never in settings.json or the database. |
| FR-SYNC-7 |
M |
9 |
Require TLS; refuse plaintext http:// unless the user explicitly allows it for a LAN address, with a warning. |
| FR-SYNC-8 |
M |
9 |
Surface sync state in the UI and label targets: self-hosted/primary as "your server"; third-party clouds carry a clear "data leaves your device to a third party" banner. |
| FR-SYNC-9 |
S |
9 |
Secondary targets via provider APIs + OAuth 2.0 (PKCE, loopback redirect): OneDrive (MS Graph), Dropbox, Box. |
| FR-SYNC-10 |
C |
9 |
Optional client-side encryption of artifacts before upload (ties to FR-SEC-3): destination holds only ciphertext. |
| FR-SYNC-11 |
S |
9 |
Show live per-item upload progress while syncing (stream the upload body and report bytes sent per artifact). |
UX, accessibility, recovery (UX)
| ID |
Pri |
Phase |
Requirement |
| FR-UX-1 |
M |
7 |
Three-pane layout: meetings list · transcript/notes · summary/action-items/participants. |
| FR-UX-2 |
M |
7 |
Light/dark themes following system setting, with user override. |
| FR-UX-3 |
S |
7 |
Keyboard shortcuts for start/stop recording, view toggles, and template apply. |
| FR-UX-4 |
S |
7 |
Screen-reader-friendly labels and sufficient contrast. |
| FR-REL-1 |
M |
2 |
Crash recovery: regenerate transcript/notes from persisted audio after an unexpected exit. |
| FR-REL-2 |
M |
2 |
Auto-save transcript and notes at intervals. |
Privacy & security (SEC) — see also NFR-SEC
| ID |
Pri |
Phase |
Requirement |
| FR-SEC-1 |
M |
all |
WA originates no outbound connection for audio or transcript content except to destinations the user has explicitly configured: the LLM endpoint (local or, if chosen, a hosted AI provider — ADR-0007/0011), enabled sync targets (ADR-0010), and (Layer 3) a configured task tracker. With none configured, WA makes no content egress at all. Model downloads are the only other allowed egress and are explicit. The local MCP server is inbound on loopback and is not egress (FR-MCP-7). |
| FR-SEC-2 |
M |
7 |
A privacy panel shows current hardware backend, LLM/AI provider endpoint, every enabled sync target (self-hosted vs third-party), and MCP server state (and that connected agents may forward served data to their own provider), stating exactly what leaves the device. |
| FR-SEC-3 |
C |
8 |
Optional at-rest encryption of stored audio/transcripts; optional password-protected vault. |
| FR-MODEL-1 |
S |
3 |
Model management UI: choose Whisper size, download/remove transcription & diarization models. |
Non-functional requirements
Performance (PERF)
- NFR-PERF-1 (M): Real-time transcription latency under ~2–3 s per phrase on accelerated paths.
- NFR-PERF-2 (M): Batch transcription of a 60-min meeting completes within ≤1–2× meeting length
on CPU-only; faster on NPU/GPU.
- NFR-PERF-3 (M): Out-of-the-box defaults run acceptably on a typical Windows laptop with no
dedicated GPU/NPU (small/efficient model, conservative settings).
- NFR-PERF-4 (S): Cold start to interactive UI under ~2 s; heavy components (models) lazy-load
after the window is shown.
Resource usage (RES)
- NFR-RES-1 (M): Near-zero CPU/GPU/NPU and minimal memory/disk when idle (no recording or active
transcription) — behave like a lightweight background app; no polling timers when idle.
- NFR-RES-2 (M): During recording, prefer accelerated backends but stay responsive on CPU-only.
- NFR-RES-3 (S): A "Low overhead" preset caps model size, disables real-time summarization, and
reduces background indexing.
- NFR-RES-4 (M): Do not add WA to OS startup or run invasive background tasks without explicit
user consent.
Reliability (REL)
- NFR-REL-1 (M): Tolerate audio glitches and device changes without crashing or corrupting data.
- NFR-REL-2 (M): Graceful fallback when hardware acceleration is unavailable.
- NFR-REL-3 (M): No data loss on crash — audio persisted continuously; derived artifacts
regenerable.
Security (SEC)
- NFR-SEC-1 (M): Store data under the user profile, respecting Windows ACLs.
- NFR-SEC-2 (M): Operate without admin privileges.
- NFR-SEC-3 (S): Network egress is restricted to an allowlist derived from user configuration:
the LLM/AI-provider endpoint, enabled sync target hosts, a configured task tracker, and explicit
model downloads; nothing else. Verifiable (network test in CI / a privacy self-check). Any
connection to a host not on the derived allowlist is a defect. The MCP server is inbound and does
not add to the allowlist.
- NFR-SEC-4 (M): Sync and AI-provider credentials/keys live only in the OS credential store; TLS
is required for sync transport (plaintext only via explicit per-target LAN opt-in). See FR-SYNC-6/7,
FR-AI-2.
- NFR-SEC-5 (M): The MCP server binds to loopback only, requires a token, is off by
default, and honors the configured exposure scope; it never serves recordings unless explicitly
allowed, and logs agent reads (FR-MCP-1/3/5).
Maintainability & portability (MNT)
- NFR-MNT-1 (M): Modular services (audio, transcription, diarization, storage, llm, calendar,
hardware, notes, sync, mcp) with trait-defined boundaries enabling component replacement.
- NFR-MNT-2 (S): Engines selectable/swappable without changes to callers.
- NFR-MNT-3 (C): Architecture portable to macOS/Linux/Windows-on-ARM later without a rewrite.
- NFR-MNT-4 (M): CPU-only build always compiles; accelerated backends behind Cargo features.
Traceability
The roadmap (05-roadmap.md) tags each task with the FR/NFR it satisfies; the test strategy
(06-test-strategy.md) maps tests to the same IDs. A requirement is "done" only when its
acceptance criteria (in the roadmap) pass the tests named for it.
