Run, Customize, Extend

Self-hosting the Web App

The web app is a normal Next.js project. Clone, install, and run:

git clone https://github.com/mianaz/jargonslayer.git
cd jargonslayer
npm install
npm run dev
# open http://localhost:3000

For a production-like local run, build and start instead of using the dev server:

npm run build
npm start

Before committing changes, run the same checks CI runs:

npm run typecheck
npm test
npm run build

Server-side provider keys go in .env.local and are never shipped to the browser:

ANTHROPIC_API_KEY=sk-ant-...

Deploy tiers

The default build is the full local-first build — every feature is available, gated only by what the visitor configures. Setting NEXT_PUBLIC_DEPLOY_TIER=preview switches to the hosted-preview tier: sidecar-dependent features (local Whisper, tab audio through the sidecar, video URL import, subscription-direct) show disabled/greyed with an explanation instead of failing, and zero-key AI use is backed by the preview server's own configured model path — see AI Modes in the User Guide for what that means for privacy.

PWA install

The web app installs as a Progressive Web App off its existing manifest and icons — no separate build. From Chrome/Edge desktop it installs as a windowed app; from Safari on iOS/iPadOS it adds to the home screen.

Local Whisper Sidecar

Local Whisper, tab audio, and sidecar-based recording/URL import on the web app all go through one Python process, sidecar/whisper_server.py. On the desktop app this is provisioned and self-managed by the first-run wizard — nothing below is needed there unless you're pointing it at an external sidecar (see sidecarMode below). For the web app, set it up by hand:

cd sidecar
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python whisper_server.py --model small

It serves live realtime transcription over ws://127.0.0.1:8765 and a local HTTP job API for recording and video-URL imports, built on faster-whisper, energy-based VAD, optional local audio saving, and pyannote for diarization when configured.

Model choices

--model accepts tiny, base, small, medium, large-v3, large-v3-turbo, and parakeet-tdt-0.6b-v3 (MLX-accelerated, English-priority — the manual-sidecar counterpart to desktop's 英文加速 engine). small is a reasonable daily-use default for this manual path. The desktop wizard's own curated picker is narrower and macOS-specific: small / medium / large-v3 / large-v3-turbo plus an available Parakeet entry, with medium pre-selected.

Speaker diarization

Configure a Hugging Face token (hfToken in Settings, or pasted during desktop's first-run onboarding — see Desktop App in the User Guide) after accepting the usage terms for pyannote's segmentation and speaker-diarization models on Hugging Face. Batch imports diarize the whole recording. Realtime diarization is beta: the sidecar re-runs pyannote on a recent tail window, matches speakers against a stable registry, and pushes label updates back to the UI without blocking transcription.

Moved-directory gotcha

Python virtual environments bake in absolute paths. If you move or rename the repository, the venv breaks silently; rebuild it (rm -rf sidecar/.venv, then repeat the setup above).

sidecarMode (desktop)

The desktop build's sidecarMode setting is managed (default — the app installs, starts, and restarts its own bundled sidecar) or external (point it at a sidecar you started yourself, same as the web build). The web build is always effectively external.

Subscription-direct Agent Sidecar (experimental)

sidecar/agent_server.py is experimental and local-only. It drives your own already-authenticated claude or codex CLI login for detect/define only — translation and summary/reports always go through the normal app routes, in every build.

• Default loopback host: http://127.0.0.1:8767.
• Endpoints: GET /agent/health, POST /agent/detect, POST /agent/define.
• Detect/define calls require a loopback Origin plus a one-time connection code printed on sidecar startup, copied by hand into Settings.
• Feature gate: NEXT_PUBLIC_ENABLE_SUBSCRIPTION_DIRECT=1 at build time — unset, the whole UI section and call branch don't exist in the built bundle.
• If the sidecar is unreachable, not logged in, or quota-limited, the app falls back to dictionary detection instead of failing.

Settings Reference

One settings object controls transcription, model routing, detection, translation, display, and integrations. As of v0.7.3, LLM provider keys are stored and sent per-provider, never as one shared key; as of v0.7.4, 设置 → 密钥 is the single UI home for every key and token in the table below.

Transcription

AI routing

Detection

Translation

Display

Integrations

Model Routing

Per-task models

Advanced settings can point detection, translation, and reports at different providers or models via taskLlm (see Settings Reference above). The normal split is a fast/cheap model for live detection and a stronger model for post-meeting reports; define always rides detect's configuration.

Provider presets

设置 → AI 检测 ships eight presets:

• Anthropic 官方 — api.anthropic.com, native provider.
• OpenAI — api.openai.com/v1.
• DeepSeek — api.deepseek.com.
• 通义千问 — dashscope.aliyuncs.com/compatible-mode/v1.
• OpenRouter — openrouter.ai/api/v1, also reachable via one-click OAuth.
• Poe 订阅 — api.poe.com/v1, a Poe subscription driving any OpenAI-compatible client.
• Ollama 本地 — localhost:11434/v1, fully local inference.
• 自定义 — any other OpenAI-compatible endpoint.

Every preset besides Anthropic maps to the shared openai-compat provider type with a different base URL. Each preset's key is stored and sent in isolation — a v0.7.3 fix so switching providers never sends the previous provider's key to the new one's host.

BYOK key handling paths

proxyUrl (desktop only) is a manual escape hatch for reaching a BYOK endpoint when the OS-level auto-detection can't see the route — an env-var-only proxy setup, or a PAC-only network the app can't execute a script against.

Theming

Every theme — built-in or custom — is a flat token-to-hex map plus a scheme flag. Every value must match strict hex, #RGB or #RRGGBB — rgb(), hsl(), named colors, and CSS variables are all rejected outright — and values are injected as CSS custom properties rather than raw strings. Every theme is checked against WCAG AA contrast. scheme (dark or light) is a separate structural field, not an 18th token — it drives native form-control/scrollbar chrome and the in-UI icon swap.

The 17 tokens

ink, panel, panel2, panel3, edge, edge2, fg, mut, mut2, lab-red, lab-orange, lab-yellow, lab-green, lab-purple, lab-cyan, act, warn-soft.

Editor behavior

• The theme grid's 新建 tile creates a theme from scratch or duplicates any theme, built-in or custom.
• A live preview applies as you edit each token and reverts to the saved theme if you cancel.
• Contrast hints flag tokens that fall below the AA/UI-contrast bars as you go — they warn, they never block saving.
• Export to a JSON file, or import by pasting or picking a file; an imported theme is re-validated and its id is re-minted on import, so an imported file can never shadow or overwrite a built-in.
• Deleting a theme asks for confirmation; deleting the active theme falls back to the terminal default.

Example custom theme

{
  "id": "custom-1737421200000",
  "label": "深海蓝调",
  "scheme": "dark",
  "tokens": {
    "ink": "#050b14",
    "panel": "#0d1620",
    "panel2": "#14202c",
    "panel3": "#1b2c3a",
    "edge": "#25384a",
    "edge2": "#37516a",
    "fg": "#e8f1fb",
    "mut": "#93a9bd",
    "mut2": "#5c7186",
    "lab-red": "#ff6b6b",
    "lab-orange": "#ffa552",
    "lab-yellow": "#f4d35e",
    "lab-green": "#4ade80",
    "lab-purple": "#b895ff",
    "lab-cyan": "#41d1e0",
    "act": "#2fd0e8",
    "warn-soft": "#ffcf7a"
  }
}

Dictionary Pack Authoring

Remote packs are JSON manifests, validated and normalized into an in-memory registry, then shown in Settings alongside the built-in packs. Publish one at a GitHub raw URL or a jsDelivr URL and install it by pasting that URL, or share the file directly for file import.

Manifest format

{
  "id": "biotech-terms",
  "name": "Biotech Terms",
  "version": "1.2.0",
  "terms": [{
    "term": "IND",
    "type": "acronym",
    "gloss_en": "Investigational New Drug application",
    "gloss_zh": "美国 FDA 新药临床试验申请"
  }],
  "expressions": [{
    "expression": "go/no-go",
    "category": "phrase",
    "meaning": "a decision point to proceed or stop a program",
    "chinese_explanation": "继续或终止（项目决策点）",
    "plain_english": "decide whether to continue or stop",
    "tone": "neutral, common in R&D governance"
  }]
}

id, name, and version are required at the manifest root; terms and expressions are both optional arrays. Acronyms are just terms entries with "type": "acronym" — there is no separate acronym shape.

Validation behavior

• Malformed entries are dropped individually with a warning; the whole pack only fails to install when the manifest itself is unusable.
• An entry-level pack field is ignored and overwritten with the manifest's own id — an entry can't spoof another pack's id.
• Changing version is enough to trigger an update; installed packs auto-check for a newer version once a day (packAutoUpdate).

Official catalog

Settings has a one-click browse-and-install catalog — six specialized packs (medicine, biopharma, AI/ML, law, finance, engineering; 4,300+ terms total) published at jargonslayer-dicts — alongside file or GitHub-URL import for any third-party pack.

Precedence

personal glossary > installed packs > built-ins. Personal glossary entries shadow every dictionary match. An installed pack's own definition taking precedence over a built-in one (rather than the built-in silently winning) shipped in v0.7.2.

Automation and Integrations

Auto-export folder

Settings can save every session to a folder as Markdown plus JSON on each save, named YYYY-MM-DD-HHmm-jargonslayer.md and a matching .json. This uses the File System Access API, so it's Chromium-oriented (Chrome/Edge) — built for Obsidian vaults and agent workflows, not a general cross-browser feature.

Webhook

Setting a webhook URL POSTs a meeting.saved payload after each session save:

{
  "schemaVersion": 1,
  "event": "meeting.saved",
  "exportedAt": 1735689600000,
  "session": { /* full MeetingSession */ }
}

The same URL also receives background-task lifecycle events — task.started, task.done, task.error — envelope-identical apart from carrying a task object (id, kind, label, stage, progress, status, error, sessionId, timestamps) instead of a full session; these mirror the desktop 后台任务 task registry (model downloads, diarization install, import jobs). Every call has an 8-second timeout and no retry — a slow or down receiver just misses that event, it doesn't block or requeue.

Receivers should return 200 fast and do the real work asynchronously:

app.post("/jargonslayer-webhook", (req, res) => {
  res.sendStatus(200);                   // ack immediately, before the 8s timeout
  queue.add("process-event", req.body);  // do the real work off-request
});

AnkiConnect

Enabling ankiConnect fires an addNotes call to a local AnkiConnect instance on every session save, reusing the same flashcard projection as manual Anki TSV export, with dedup so re-saving a session doesn't duplicate cards. Its default port 8765 collides with the Whisper sidecar's own websocket default, so it's independently configurable rather than hardcoded — check ankiConnect.port if both run on the same machine.

Obsidian

Markdown exports can include YAML frontmatter (exportFrontmatter) for Obsidian/Dataview — combine it with folder auto-export to build a vault that updates itself after every meeting.

Backup and restore

A full backup exports sessions, glossary, and settings together. The export dialog's 不包含 API Key option is checked by default, stripping every API key, the Hugging Face token, the subscription-direct agent token, the webhook URL, and per-task API keys from the embedded settings before download; uncheck it to keep them in the file. Restoring a backup previews its contents before writing anything, re-sanitizes those same fields regardless of how the backup was exported, and clears subscription-direct connection state so a restored backup can't silently reconnect to an old local agent sidecar.

Architecture

The repository is an npm workspace: apps/web (Next.js 15, TypeScript, Tailwind, zustand, IndexedDB, server route proxies for LLM calls) plus packages/core (the pure-TS shared core — dictionary, types), apps/desktop (the Tauri shell), and apps/extension (the Chrome MV3 side panel). The zustand store in apps/web is the shared bus for transcript segments, interim text, cards, terms, summary output, settings, and sessions.

apps/web (browser client)
  transcription engines
    demo | Web Speech | local Whisper | tab audio | appaudio (desktop)
  zustand store
    segments | cards | terms | summaries | settings | sessions
  detection
    dictionary instant floor
    LLM scheduler and dedupe
  UI
    transcript | cards | history | summary | review

Server routes
  /api/detect
  /api/define
  /api/translate
  /api/summarize

Sidecars (Python)
  whisper_server.py
  agent_server.py

apps/desktop (Tauri v2, macOS)
  Rust core: provisions an isolated Python via a pinned uv,
    manages the sidecar process, CoreAudio process-tap pipeline
  jargonslayer-audiocap: signed Swift helper (CoreAudio process taps)

apps/extension (Chrome MV3)
  side panel: Web Speech capture + built-in dictionary + on-device Translator API
  own IndexedDB database + chrome.storage.local, independent of apps/web's storage

packages/core
  shared types + built-in dictionary, consumed by web and extension

• apps/web/src/lib/types.ts (re-exporting @jargonslayer/core) owns cross-module contracts.
• apps/web/src/lib/store.ts is the app bus; STT and detection communicate through it rather than importing each other.
• apps/web/src/lib/detect/dictionary.ts is the synchronous instant floor.
• apps/web/src/lib/detect/scheduler.ts batches LLM detection and falls back to dictionary mode.
• apps/web/src/lib/detect/dedupe.ts merges repeats and upgrades dictionary hits with contextual LLM explanations.
• apps/web/src/app/api/summarize/route.ts orchestrates summary, chunked translation, and missed-item gap fill.
• apps/desktop/src-tauri/src/audiocap.rs supervises the Swift capture helper and resamples its output into the existing transcription pipeline.

Data and Storage

All app data is IndexedDB, accessed through idb-keyval — not localStorage. Legacy meetlingo:* keys are copy-migrated forward on startup and left in place for rollback safety.

Schema version 1 covers session JSON, Markdown frontmatter, webhook payloads, full backup, and remote dictionary packs.

The only true localStorage keys in the app are a theme FOUC (flash-of-unstyled-content) mirror, js-display, read synchronously before IndexedDB resolves so the very first paint already has the right theme/font-size; and an update-check ETag cache, js-update-etag-cache, that makes repeat GitHub-release checks cheap.

Behavior Specs

These are the behaviors most worth knowing when debugging a setup or extending the tool.

Detection Spec

• Every finalized segment is scanned synchronously by the dictionary when detection is enabled.
• The LLM layer batches fresh text and uses the previous context tail only for disambiguation.
• LLM results can upgrade dictionary cards in place; they do not retract dictionary hits.
• Repeated expressions are merged by normalized key, with count and last-seen metadata.
• Personal glossary entries shadow built-in dictionary matches and are never overwritten by the AI.
• All-caps acronyms use stricter matching to avoid false positives; ordinary mixed-case terms are matched more flexibly.

Translation Spec

• Live bilingual transcript translates finalized segments in small batches keyed by segment id.
• Toggling bilingual transcript on mid-meeting backfills the most recent untranslated finalized segments.
• If a segment is manually edited, its stale translation is invalidated and re-queued while the meeting is live.
• No-key pauses are self-healing: once a key is added, new translation work can resume without restarting the meeting.
• Repeated 429s pause and eventually skip the oldest stuck batch so newer segments are not starved forever.
• Post-meeting report translation is separate: it chunks the full transcript by segment index and repairs missing indices where possible.

Import Spec

Failure and Recovery Spec

• No API key: detection falls back to dictionary; live translation pauses; report generation asks for a key.
• Rate limits: detection retries once with jitter for 429; translation pauses and avoids starving newer work indefinitely.
• Sidecar unreachable: local Whisper, sidecar import, URL import, diarization, and subscription-direct cannot run; browser-local import still works for supported files.
• Meeting changed: async results carry meetingGen; stale results from an old meeting are dropped.
• Background tab: browsers throttle timers, so detection also flushes on segment arrival and visibility changes.
• Post-stop late results: detection and translation can land after stop; the store schedules a save top-up so history is not missing tail results.

Glossary and Learning Spec

• Personal glossary entries are the durable learning home today; meeting sessions stay immutable archives.
• Entries can be manual, AI-defined from selected text, or collected from a meeting's cards.
• Each entry stores headword, variants, explanation, example, original context, user note, source, timestamps, and review state.
• Expression entries may store category, meaning, plain-English rewrite, and tone. Term entries may store term type and English gloss.
• Review state includes mastered, review count, and last reviewed time — a true learn-set and due-review loop (SM-2-lite scheduling) since v0.3.0.

Async Delegation Design

The product should feel like one calm foreground process with specialized background workers. The foreground owns listening, transcript editing, user focus, and saved session state. Expensive work runs as asynchronous delegates and reports back when results are ready.

{
  "id": "job_x",
  "kind": "translate | detect | search | diarize",
  "meetingGen": 12,
  "segmentIds": ["seg_1", "seg_2"],
  "textHash": "...",
  "priority": 2,
  "status": "queued | running | done | failed | stale",
  "attempts": 0
}

Results should apply only when the meeting generation still matches, target segments still exist, and the source text hash is still current. A result should patch the relevant field; it should never replace the foreground transcript or steal the user's focus.

Realtime search fits this model naturally: a card can request background search using the current expression plus recent context, keep showing the local explanation immediately, then attach references or disambiguation notes when the search delegate returns. Search should be triggered by ambiguity, user request, or explicit pack/card action, not every card by default; results should attach to the card as references or context notes, not replace the local explanation; search jobs should stay lower priority than live transcription, dictionary scan, and visible-card detection; and privacy settings should clearly distinguish local dictionary, provider AI, and web search calls.

Testing

Web App

npm run typecheck
npm test
npm run build

Sidecar

sidecar/.venv/bin/python sidecar/test_agent_json.py
sidecar/.venv/bin/python sidecar/test_agent_postfilter.py
sidecar/.venv/bin/python sidecar/test_agent_server.py
sidecar/.venv/bin/python sidecar/test_download.py
sidecar/.venv/bin/python sidecar/test_ingest_url.py
sidecar/.venv/bin/python sidecar/test_lazy_load.py
sidecar/.venv/bin/python sidecar/test_model_registry.py
sidecar/.venv/bin/python sidecar/test_parakeet_backend.py
sidecar/.venv/bin/python sidecar/test_realtime_diar.py
sidecar/.venv/bin/python sidecar/test_whisper_protocol.py

Sidecar tests are plain-assert scripts and assume dependencies from sidecar/requirements.txt. The local Whisper and agent sidecars are independent processes, so test the one you changed.

Desktop (Rust + Swift)

cd apps/desktop/src-tauri && cargo test
cd apps/desktop/src-tauri/audiocap-helper && swift test

The Rust core (process supervision, resampling, the CoreAudio framing protocol) and the signed Swift capture helper each have their own suite; CI has no live CoreAudio session, so the audio-capture tests are designed around fakes/seams rather than a real tap.

Extension

npm test -w apps/extension