# sfc-gh-jiyan/macwhisper architecture

> Architecture diagram of the GitHub repository sfc-gh-jiyan/macwhisper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sfc-gh-jiyan/macwhisper
- Repository: https://github.com/sfc-gh-jiyan/macwhisper

## Overview

MacWhisper is a local macOS menu-bar transcription and translation app. Its main workflow captures speech, runs on-device Whisper inference, and presents or exports the resulting text: hold-to-record ends in transcription and paste, while Live Subtitles and Meeting Mode provide continuous paths. Meeting Mode adds microphone/system-audio capture, speech detection, segmentation, and transcript exports. The graph preserves documented capabilities even where app.py’s full routing was not excerpted; those links are cited to the README rather than implying unseen calls.

Main entry points: [`app.py`](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py) (Menu-bar app), [`meeting.py`](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/meeting.py) (Meeting session), [`online_processor.py`](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/online_processor.py) (Streaming processor), [`subtitle_export.py`](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/subtitle_export.py) (Meeting exports)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["App interaction"]
  node_menu_app["Menu-bar app<br/>[app.py]"]
  node_hotkeys["Hotkeys and modes<br/>[app.py]"]
  node_settings["Persistent settings<br/>[app.py]"]
  node_live_overlay["Live subtitles<br/>[overlay.py]"]
  node_paste["Auto-paste<br/>[app.py]"]
end

subgraph group_capture["Audio capture"]
  node_audio_input["Microphone capture<br/>[audio_capture.py]"]
  node_system_capture["System audio helper<br/>[main.swift]"]
  node_vad["Voice activity detection<br/>[vad.py]"]
end

subgraph group_recognition["Speech recognition"]
  node_online_asr["Streaming processor"]
  node_asr["MLX Whisper backend<br/>[asr_backend.py]"]
  node_text_cleanup["Text cleanup<br/>[text_utils.py]"]
end

subgraph group_meeting["Meeting and output"]
  node_meeting_session["Meeting session<br/>[meeting.py]"]
  node_exports["Meeting exports<br/>[subtitle_export.py]"]
  node_local_store[("Transcript history<br/>[subtitle_export.py]")]
end

node_user(("User"))
node_mac_user(("macOS user"))

node_user -->|"uses"| node_menu_app
node_menu_app -->|"handles modes"| node_hotkeys
node_menu_app -->|"loads and saves"| node_settings
node_menu_app -.->|"captures speech"| node_audio_input
node_menu_app -->|"streams audio"| node_online_asr
node_online_asr -->|"transcribes"| node_asr
node_online_asr -->|"filters text"| node_text_cleanup
node_menu_app -->|"pastes result"| node_paste
node_menu_app -->|"updates subtitles"| node_live_overlay
node_menu_app -->|"starts session"| node_meeting_session
node_meeting_session -->|"starts capture"| node_audio_input
node_meeting_session -.->|"captures system audio"| node_system_capture
node_meeting_session -->|"filters silence"| node_vad
node_meeting_session -->|"processes audio"| node_online_asr
node_meeting_session -->|"sends updates"| node_live_overlay
node_meeting_session -->|"exports transcript"| node_exports
node_exports -->|"saves history"| node_local_store
node_mac_user -->|"views subtitles"| node_live_overlay
node_mac_user -->|"chooses export"| node_exports

click node_menu_app "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py"
click node_hotkeys "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py"
click node_settings "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py"
click node_audio_input "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/audio_capture.py"
click node_system_capture "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/swift/SystemAudioHelper/Sources/main.swift"
click node_vad "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/vad.py"
click node_meeting_session "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/meeting.py"
click node_online_asr "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/online_processor.py"
click node_asr "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/asr_backend.py"
click node_text_cleanup "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/text_utils.py"
click node_live_overlay "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/overlay.py"
click node_paste "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py"
click node_exports "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/subtitle_export.py"
click node_local_store "https://github.com/sfc-gh-jiyan/macwhisper/blob/main/subtitle_export.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_menu_app,node_hotkeys,node_settings,node_live_overlay,node_paste,node_user,node_mac_user toneBlue
class node_audio_input,node_system_capture,node_vad toneAmber
class node_online_asr,node_asr,node_text_cleanup toneMint
class node_meeting_session,node_exports,node_local_store toneRose
```

## Components

### App interaction

- [Menu-bar app](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py): `app.py`
- [Hotkeys and modes](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py): `app.py`
- [Persistent settings](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py): `app.py`
- [Live subtitles](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/overlay.py): `overlay.py`
- [Auto-paste](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/app.py): `app.py`

### Audio capture

- [Microphone capture](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/audio_capture.py): `audio_capture.py`
- [System audio helper](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/swift/SystemAudioHelper/Sources/main.swift): `swift/SystemAudioHelper/Sources/main.swift`
- [Voice activity detection](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/vad.py): `vad.py`

### Speech recognition

- [Streaming processor](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/online_processor.py): `online_processor.py`
- [MLX Whisper backend](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/asr_backend.py): `asr_backend.py`
- [Text cleanup](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/text_utils.py): `text_utils.py`

### Meeting and output

- [Meeting session](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/meeting.py): `meeting.py`
- [Meeting exports](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/subtitle_export.py): `subtitle_export.py`
- [Transcript history](https://github.com/sfc-gh-jiyan/macwhisper/blob/main/subtitle_export.py): `subtitle_export.py`

### Other components

- **User**
- **macOS user**

## Connections

- User → Menu-bar app: uses (evidence: `README.md`)
- Menu-bar app → Hotkeys and modes: handles modes (evidence: `README.md`)
- Menu-bar app → Persistent settings: loads and saves (evidence: `README.md`)
- Menu-bar app → Microphone capture: captures speech
- Menu-bar app → Streaming processor: streams audio (evidence: `app.py`)
- Streaming processor → MLX Whisper backend: transcribes (evidence: `online_processor.py`)
- Streaming processor → Text cleanup: filters text (evidence: `online_processor.py`)
- Menu-bar app → Auto-paste: pastes result (evidence: `README.md`)
- Menu-bar app → Live subtitles: updates subtitles (evidence: `app.py`)
- Menu-bar app → Meeting session: starts session (evidence: `README.md`)
- Meeting session → Microphone capture: starts capture (evidence: `meeting.py`)
- Meeting session → System audio helper: captures system audio
- Meeting session → Voice activity detection: filters silence (evidence: `meeting.py`)
- Meeting session → Streaming processor: processes audio (evidence: `meeting.py`)
- Meeting session → Live subtitles: sends updates (evidence: `meeting.py`)
- Meeting session → Meeting exports: exports transcript (evidence: `README.md`)
- Meeting exports → Transcript history: saves history (evidence: `subtitle_export.py`)
- macOS user → Live subtitles: views subtitles (evidence: `README.md`)
- macOS user → Meeting exports: chooses export (evidence: `README.md`)