Manuel/meeting-assistant
Public Access
1
0
Fork 0
Code Issues Pull Requests 4 Actions Packages Projects Releases Wiki Activity Open in Coder

docs: refresh meeting assistant README
PR and Push Build/Test / build-and-test (push) Successful in 15m14s
Details

Browse Source
This commit is contained in:
codex
2026-06-10 09:10:35 +02:00
parent ecdd23bde7
commit 5bbfd7b3c3
1 changed files with 127 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+127 -70
View File
@@ -1,61 +1,36 @@
# Meeting Assistant
Meeting Assistant is a .NET 10 server application for capturing and enriching meetings.
Meeting Assistant is Manuel's local .NET meeting capture and knowledge service. It runs on the Windows workstation, records microphone plus system audio, writes Obsidian meeting artifacts, transcribes with speaker attribution, enriches meetings from local context, and drives summary/project agents without depending on Teams, Zoom, or another meeting-platform API for the primary flow.
Its core purpose is to work with any kind of meeting, including in-person meetings. Integrations with platforms such as Teams, Zoom, or similar tools may augment the experience later, but the system must not depend on those product APIs for its primary meeting flow.
## What This Repo Owns
The application is intended to:
This repository owns the application source, tests, OpenSpec requirements, configuration examples, local runtime documentation, and CI build/test workflow for Meeting Assistant. It does not own a homelab deployment stack, Traefik routing, Docker Compose deployment, or production image tag selection.
- create an Obsidian markdown note before transcription starts
- keep meeting metadata, user notes, detected context, and links to generated output in that note
- toggle recording/transcription mode through a configurable global hotkey
- optionally prompt to start recording when Outlook Classic shows a Teams meeting starting
- switch the active transcription profile during a meeting with a profile-specific toggle hotkey
- abort and discard an active recording through a configurable global hotkey
- show a Windows taskbar notification icon with state-aware recording controls
- capture active-window screenshots through a configurable global hotkey
- capture microphone input and computer output into one transcription stream
- transcribe meetings with speaker attribution
- use a configurable speech recognition pipeline, with local Whisper as the first version 1 fallback
- use FunASR or local Whisper plus pyannote as configurable speaker-attribution paths
- write transcript markdown files into the configured vault folder
- apply local workflow rules to meeting metadata, context, and transcript lines
- generate summaries, decisions, and next steps
- build and maintain a project knowledge base from meetings and future context sources
- use Microsoft Agent Framework-based agents to reason over meeting and project context
- give agents tools for project lookup, keyword lookup, retrieval-augmented generation, and project file updates in existing projects
The app is intentionally local-first:
## Repository Status
- Windows builds provide the tray icon, global hotkeys, NAudio capture, Outlook Classic COM enrichment, active-window screenshots, and notifications.
- Non-Windows builds keep the server/testable service surface but compile out Windows-only integrations.
- The normal runtime endpoint is local HTTP on port `5090`, with `/health` and `/recording/status` as the safe first checks.
- Behavior changes are OpenSpec-driven; current accepted requirements live under `openspec/specs`.
This repository currently contains the initial .NET 10 application skeleton, a health endpoint, and the first OpenSpec change for version 1.
## Quick Start
## Local Development
Restore, build, and test:
For a development build:
```powershell
dotnet restore MeetingAssistant.slnx
dotnet build MeetingAssistant.slnx
dotnet test MeetingAssistant.slnx
```
Run the server:
```powershell
dotnet run --project MeetingAssistant
```
## Local Autostart and Restart
For the local Windows workstation, use the snippets restart helper instead of running the app directly when you want a durable background instance:
For the durable local background instance, use the snippets restart helper:
```powershell
powershell -ExecutionPolicy Bypass -File C:\Manuel\snippets\restart-meeting-assistant.ps1
```
The restart helper publishes `MeetingAssistant\MeetingAssistant.csproj` as `net10.0-windows10.0.19041.0` into a fresh temp folder under `C:\Manuel\meeting-assistant\tmp\meeting-assistant-runtime`. Only after that publish succeeds does it stop any active Meeting Assistant instance on port `5090` and start the newly published executable detached from the script.
The detached starter writes logs and the last process id to:
The helper publishes `MeetingAssistant\MeetingAssistant.csproj` for `net10.0-windows10.0.19041.0` into timestamped folders below `C:\Manuel\meeting-assistant\tmp\meeting-assistant-runtime`. It stops the old port-`5090` instance only after publishing succeeds, starts the published `MeetingAssistant.exe`, waits for `/health`, and writes process logs plus the last PID to:
```text
%LOCALAPPDATA%\MeetingAssistant\Logs\meeting-assistant.out.log
@@ -63,49 +38,131 @@ The detached starter writes logs and the last process id to:
%LOCALAPPDATA%\MeetingAssistant\Logs\meeting-assistant.pid
```
This script is also the intended autostart target. Add a Windows Startup shortcut to `C:\Manuel\snippets\restart-meeting-assistant.ps1` when the app should rebuild and restart automatically after login.
Before restarting, always check the running process:
The initial endpoints are:
```text
GET /health
GET /recording/status
POST /recording/toggle
POST /recording/start
POST /recording/stop
POST /recording/abort
POST /asr/transcribe-file
POST /asr/diarize-file
POST /diagnostics/workflow/reload
POST /diagnostics/settings-and-logs/show
POST /meetings/current/summary/run
POST /meetings/summary/retry
GET /meetings/summary/retry?summaryPath=...
```powershell
Invoke-RestMethod http://127.0.0.1:5090/recording/status
```
Do not restart while a meeting is recording, transcribing, finalizing speaker recognition, waiting on OCR, or summarizing unless the user explicitly approves the interruption.
## Runtime Behavior
Recording can be controlled through global hotkeys, the Windows tray icon, or local HTTP endpoints. The default hotkeys are:
- `Ctrl+Alt+M`: toggle the default recording profile.
- `Ctrl+Alt+L`: toggle or switch to the configured `english` launch profile.
- `Ctrl+Alt+Z`: abort the active recording and delete that run's artifacts.
- `Ctrl+Alt+S`: capture the active window into the current meeting context.
The main local endpoints are:
- `GET /health`
- `GET /recording/status`
- `POST /recording/start`, `/recording/stop`, `/recording/toggle`, `/recording/abort`
- `POST /profiles/{launchProfile}/recording/start`, `/stop`, `/toggle`, `/abort`
- `POST /asr/transcribe-file` and `/asr/diarize-file` for diagnostic WAV checks
- `POST /diagnostics/workflow/reload`
- `POST /diagnostics/settings-and-logs/show`
- `POST /diagnostics/workflow/rules-editor/show`
- `POST /meetings/current/summary/run`
- `POST` or `GET /meetings/summary/retry`
Stopping a recording stops new audio capture but lets that run continue transcription drain, speaker processing, screenshot OCR waits, summary generation, and final artifact updates. A later recording can start while an older stopped run is still finalizing; each run keeps isolated artifact paths and options.
## Data And Side Effects
Meeting Assistant writes durable meeting knowledge to the configured Obsidian vault:
- meeting notes
- transcripts
- assistant context notes
- summary notes
- project knowledge files that agents may read or update
- optional dictation words used as speech-recognition phrase hints
It also writes local runtime state outside the vault:
- `%LOCALAPPDATA%\MeetingAssistant\Recordings`: temporary mixed WAV files during active/finalizing runs; stale files are deleted at startup and completed runs delete their temporary audio.
- `%LOCALAPPDATA%\MeetingAssistant\SpeakerIdentity\speaker-identities.db`: local SQLite speaker identity database, aliases, meeting references, and bounded voice snippets.
- `%LOCALAPPDATA%\MeetingAssistant\FunASR\models`: persistent FunASR model and hotword cache when the managed FunASR backend is enabled.
- `%LOCALAPPDATA%\MeetingAssistant\Pyannote\models`: persistent pyannote/Hugging Face/torch cache when pyannote diarization or validation is enabled.
- `%TEMP%\MeetingAssistant\Logs\meeting-assistant.log`: application-owned rotating logs; the snippets starter separately captures stdout/stderr under `%LOCALAPPDATA%`.
The repo intentionally ignores local rule files, local appsettings overrides, models, recordings, runtime caches, build output, and temporary publish folders.
## Configuration
Meeting Assistant uses normal .NET configuration under the `MeetingAssistant` section. The repository `appsettings.json` stores local paths, endpoint URLs, model names, and environment variable names; secret values should stay in environment variables referenced by `KeyEnv` settings.
Configuration is normal .NET configuration under `MeetingAssistant`; the checked-in `MeetingAssistant/appsettings.json` is the canonical example. Keep secret values out of source and use the configured environment-variable names instead.
See `docs/meeting-assistant-configuration.md` for the detailed configuration reference, including recording providers, FunASR, Whisper, Azure Speech, speaker identification, automation rules, screenshots, summary agents, and the settings/logs assistant.
Important settings:
## Spec Workflow
- `Vault`: controls the Obsidian vault root and the relative folders for notes, transcripts, summaries, assistant context, project knowledge, and dictation words.
- `Recording:TranscriptionProvider`: selects `azure-speech`, `funasr`, or `whisper-local`.
- `Recording:TemporaryRecordingsFolder`: controls temporary mixed WAV storage.
- `Recording:InactivitySafeguard`: prompts and then auto-stops forgotten silent recordings without aborting artifacts.
- `LaunchProfiles`: overlays named profile settings onto the default profile; profile hotkeys must be distinct.
- `Automation:RulesPath`: points to the local YAML workflow-rules file. The default `meeting-rules.local.yaml` is ignored by git.
- `CalendarRecordingPrompts`: enables Outlook Classic Teams-start prompts on Windows.
- `Screenshots`: controls the capture hotkey, attachment folder, and optional OCR/vision model.
- `Agent`: configures the OpenAI-compatible summary/project agent endpoint, model, retries, output limits, and compaction.
- `WorkflowRulesEditor`: optionally overrides the agent settings for the tray-launched settings/logs assistant.
This repository is OpenSpec-driven. Before changing behavior, read:
Required or commonly used secrets:
1. `README.md`
2. `openspec/config.yaml`
3. existing specs in `openspec/specs`
4. active change specs in `openspec/changes/*/specs`
- `AZURE_SPEECH_KEY` for Azure Speech live transcription and speaker matching.
- `LITELLM_API_KEY` for summary, OCR, and workflow editor agents when their effective endpoint requires an API key.
- `HF_TOKEN` for pyannote model access when pyannote diarization or validation is enabled.
The initial active change is:
See `docs/meeting-assistant-configuration.md` for the full configuration reference.
```text
openspec/changes/define-meeting-assistant-v1
```
## Integrations
Validate it with:
- **Obsidian vault**: primary durable store for notes, transcripts, summaries, assistant context, project files, and generated links.
- **Outlook Classic on Windows**: optional COM metadata lookup and scheduled Teams-meeting start prompts.
- **Azure AI Speech**: default checked-in ASR path, live diarized conversation transcription, and speaker identity matching.
- **FunASR**: optional WebSocket streaming ASR. When managed backend startup is enabled, the app pulls and runs the configured Docker image as `meeting-assistant-funasr` on port `10095`.
- **Whisper.NET plus pyannote**: optional local Whisper fallback and Docker-backed final diarization.
- **LiteLLM/OpenAI-compatible Responses endpoint**: summary generation, screenshot OCR fallback, project tools, settings/logs assistant, and retry flows.
- **Docker Desktop or compatible Docker CLI**: required only for managed FunASR and pyannote paths.
```powershell
openspec validate define-meeting-assistant-v1 --strict
```
## Workflow Rules And Agents
Meeting-specific automation lives in a local YAML file, not in committed personal rules. Rules can trigger on meeting creation, assistant-context state transitions, identified speakers, and transcript-line writes. They can add/remove attendees, set supported properties, add context, add projects, and rewrite a transcript line before persistence.
The tray menu exposes the settings/logs assistant. It can edit workflow rules with validation, inspect logs and health/status, manage speaker identities and samples, run ASR diagnostics, and read/write scoped meeting/project artifacts through explicit tools.
Detailed workflow syntax and extension guidance live in `docs/meeting-workflow-engine.md`.
## Development And CI
The repo builds against .NET 10 and targets both `net10.0` and `net10.0-windows10.0.19041.0` for the app. Tests target `net10.0`.
The Gitea workflow `.gitea/workflows/pr-push-build-and-test.yaml` runs on pull requests, pushes, and manual dispatch. It restores/builds the Windows target on an Ubuntu runner, installs Wine, downloads a matching Windows .NET SDK, and runs the test project through the Windows dotnet host under Wine.
Before behavior changes:
1. Read `AGENTS.md`, this README, `openspec/config.yaml`, and relevant specs under `openspec/specs`.
2. Add or update the OpenSpec requirement/scenario for the behavior.
3. Add a failing behavior test through the public surface.
4. Implement the smallest passing change.
5. Run the narrowest useful tests, then broader tests when the blast radius justifies it.
6. Run `openspec validate <change-id> --strict` for active spec changes.
Documentation-only README maintenance does not need a new OpenSpec change.
## Operational Notes
- Treat the app as live user work. Check `/recording/status` before restarting, killing processes, deleting runtime files, or running scripts that might take over port `5090`.
- Abort is destructive for the active run: it removes that meeting's note, transcript, assistant context, summary if present, and linked screenshot attachments, and it skips summary generation.
- Too-short or empty normal stops can also delete generated artifacts instead of producing summaries.
- Summary retry links use `Api:PublicBaseUrl`, defaulting to `http://localhost:5090`.
- The workflow reload endpoint reloads configuration for future workflow reads, but a meeting run that already captured options may continue with those captured options.
- Public hostnames and homelab ingress are intentionally out of scope for this repo.
## More Documentation
- `docs/meeting-assistant-configuration.md`: full configuration reference.
- `docs/meeting-workflow-engine.md`: workflow rules engine reference.
- `openspec/specs`: accepted behavioral requirements.
- `openspec/changes/archive`: archived change proposals and designs behind the accepted specs.