Skip to content

Commit 97c40ff

Browse files
claudeclaude
committed
Add marketing-first intro to README
Lead with the value prop, a benefits list, a comparison table, and a visual tour (menu bar, transcript, dictation HUD, settings, speaker naming) before diving into the detailed feature spec. Existing technical content is preserved and reorganized below. Adds docs/screenshots/ as the home for README imagery, with a capture guide so future shots stay consistent.
1 parent ef1d272 commit 97c40ff

2 files changed

Lines changed: 145 additions & 20 deletions

File tree

‎README.md‎

Lines changed: 118 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,122 @@
1-
# Heard
1+
<p align="center">
2+
<img src="Resources/AppIcon.iconset/icon_256x256@2x.png" alt="Heard app icon" width="160" />
3+
</p>
24

3-
A macOS menu bar app that automatically detects Microsoft Teams meetings, records dual-track audio (app + mic), and produces on-device transcripts with speaker diarization. Also includes a real-time dictation mode that types transcribed speech into any focused text field.
5+
<h1 align="center">Heard</h1>
46

5-
No cloud, no LLM, no external APIs — everything runs on-device on Apple Silicon.
7+
<p align="center">
8+
<strong>Stop taking meeting notes. Get them automatically.</strong><br/>
9+
Heard is a quiet macOS menu bar app that auto-detects your Microsoft Teams meetings, records them, and turns them into clean, speaker-labeled Markdown transcripts — <em>fully on-device</em>.
10+
</p>
11+
12+
<p align="center">
13+
<a href="#install">Install</a> ·
14+
<a href="#why-heard">Why Heard</a> ·
15+
<a href="#a-look-inside">A look inside</a> ·
16+
<a href="#features">Features</a> ·
17+
<a href="#requirements">Requirements</a>
18+
</p>
19+
20+
<p align="center">
21+
<img src="docs/screenshots/hero.png" alt="Heard recording a Teams meeting from the macOS menu bar" width="720" />
22+
</p>
23+
24+
---
25+
26+
## Why Heard?
27+
28+
**No cloud. No subscription. No sending your meetings to anyone's servers.**
29+
Every byte of audio, every transcript, every speaker embedding lives on your Mac. Heard never makes a network call to a transcription service — because there is no transcription service. It all runs locally on Apple Silicon.
30+
31+
- **Zero‑click recording** — As soon as a Teams meeting starts, Heard starts. When the meeting ends, you have a transcript waiting in your Documents folder.
32+
- **Speaker-labeled transcripts** — Diarization separates each voice; once you name a speaker, Heard remembers them across every future meeting.
33+
- **Dual‑track audio** — Heard records the system audio (the people on the call) and your microphone as separate streams, then merges them after transcription. The result is dramatically cleaner than recording a single mixed track.
34+
- **Custom vocabulary** — Add product names, acronyms, or jargon and they'll come through correctly in both meeting transcripts and live dictation.
35+
- **Real‑time dictation, anywhere** — Press a hotkey and Heard types what you say into whatever app is focused — Notes, Slack, your IDE, anywhere.
36+
- **In‑meeting notes** — A second hotkey opens a quick composer. Your typed note is timestamped to the moment you started writing it and merged into the transcript chronologically.
37+
- **Built for macOS** — A native SwiftUI menu bar app with a calm "Paper" palette. No Electron. No tray icon misery.
38+
39+
### How it stacks up
40+
41+
| | Heard | Cloud meeting recorders |
42+
|------------------------------|-----------------------------|---------------------------------|
43+
| Audio leaves your Mac | Never | Always |
44+
| Works offline | Yes | No |
45+
| Subscription | Free, open source | $$$ / month |
46+
| Needs a meeting bot to join | No — runs on your machine | Yes |
47+
| Speaker memory across calls | Yes, on-device | Sometimes |
48+
| Transcribes in real time as you dictate | Yes | Different product |
49+
| Custom vocabulary | Yes | Sometimes |
50+
51+
---
52+
53+
## A look inside
54+
55+
### Quietly lives in your menu bar
56+
Heard sits in the top bar and changes its icon to tell you what it's doing — pulsing while recording, a waveform while transcribing, a calm tape icon while it waits for your next call.
57+
58+
<p align="center">
59+
<img src="docs/screenshots/menubar-dropdown.png" alt="Heard menu bar dropdown in the Watching state" width="320" />
60+
&nbsp;
61+
<img src="docs/screenshots/recording.png" alt="Heard menu bar dropdown in the Recording state with elapsed timer" width="320" />
62+
</p>
63+
64+
### Outputs a clean, speaker-labeled Markdown transcript
65+
Timestamps, merged speaker blocks, and your own typed notes interleaved at the moment you wrote them.
66+
67+
<p align="center">
68+
<img src="docs/screenshots/transcript.png" alt="A finished Markdown transcript with speaker labels and timestamps" width="720" />
69+
</p>
70+
71+
### Dictates into any app, in real time
72+
Hold `⌃⇧D` (or rebind it) and start talking. Words appear as soon as the sliding-window ASR confirms them, with filler words and "uhs" stripped automatically.
73+
74+
<p align="center">
75+
<img src="docs/screenshots/dictation-hud.png" alt="Floating dictation HUD with a live transcription being typed into a text field" width="720" />
76+
</p>
77+
78+
### A native settings panel built for macOS
79+
Custom vocabulary, model management, speaker library, and permission status all live in a single 880 × 600 window.
80+
81+
<p align="center">
82+
<img src="docs/screenshots/settings-general.png" alt="Settings window, General tab" width="720" />
83+
</p>
84+
85+
<p align="center">
86+
<img src="docs/screenshots/settings-models.png" alt="Settings window, Models tab" width="360" />
87+
&nbsp;
88+
<img src="docs/screenshots/settings-speakers.png" alt="Settings window, Speakers tab" width="360" />
89+
</p>
90+
91+
### Names new speakers with one playable clip each
92+
The first time Heard hears someone new, it surfaces a ~10-second sample of their clearest speech and asks you who they are. After that, it remembers them.
93+
94+
<p align="center">
95+
<img src="docs/screenshots/name-speakers.png" alt="Name Speakers window with playable audio clips per candidate" width="480" />
96+
</p>
97+
98+
---
99+
100+
## Install
101+
102+
**Homebrew (recommended):**
103+
104+
```bash
105+
brew tap execsumo/heard
106+
brew install --cask heard
107+
```
108+
109+
**Direct download:** Grab the latest `Heard-x.x.x.dmg` from [GitHub Releases](https://github.com/execsumo/Heard/releases), open it, and drag Heard to `/Applications`.
110+
111+
After launching, grant Microphone (always required) and Accessibility (required for dictation, recommended for richer meeting metadata). Heard will guide you to the right System Settings pane from inside the app.
112+
113+
## Requirements
114+
115+
- macOS 15.0+
116+
- Apple Silicon (FluidAudio CoreML/ANE models are ARM-only)
117+
- [FluidAudio](https://github.com/FluidInference/FluidAudio) 0.14.3+ (resolved automatically via SPM)
118+
119+
---
6120

7121
## Features
8122

@@ -45,23 +159,6 @@ No cloud, no LLM, no external APIs — everything runs on-device on Apple Silico
45159
- **Settings window** — 880×600, five tabs: **General** (launch at login, auto-watch, developer mode, custom vocabulary, output folder, permissions), **Dictation** (enable, push-to-talk, hotkey recorder with validation feedback, model keep-alive slider, live status, show dictation HUD checkbox), **Models** (download cards with progress, pipeline keep-alive, "Unload All Models"), **Speakers** (your name, inline rename, merge, delete, search, sort, with prompts to retroactively update all past transcripts), **About**.
46160
- **Name Speakers window** — 560×520 standalone scene with audio-clip playback per candidate, roster-suggestion hints, save/skip, and a 120 s countdown.
47161

48-
## Installation
49-
50-
**Homebrew (recommended):**
51-
52-
```bash
53-
brew tap execsumo/heard
54-
brew install --cask heard
55-
```
56-
57-
**Direct download:** Grab the latest `Heard-x.x.x.dmg` from [GitHub Releases](https://github.com/execsumo/Heard/releases), open it, and drag Heard to `/Applications`.
58-
59-
## Requirements
60-
61-
- macOS 15.0+
62-
- Apple Silicon (FluidAudio CoreML/ANE models are ARM-only)
63-
- [FluidAudio](https://github.com/FluidInference/FluidAudio) 0.14.3+ (resolved automatically via SPM)
64-
65162
## Build & Run
66163

67164
```bash
@@ -236,3 +333,4 @@ After a notarized DMG is published to GitHub Releases, update `Casks/heard.rb` i
236333
- [`handoff.md`](./handoff.md) — Current implementation status and known issues
237334
- [`ROADMAP.md`](./ROADMAP.md) — Planned improvements and stretch ideas
238335
- [`CLAUDE.md`](./CLAUDE.md) — Working rules for AI assistants
336+
- [`docs/screenshots/`](./docs/screenshots) — Where the README screenshots live, and how to capture new ones

‎docs/screenshots/README.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Screenshots
2+
3+
This folder holds the screenshots referenced from the top-level `README.md`. Replace any missing PNG with a real capture; keep the filenames exactly as listed so the README links don't break.
4+
5+
All shots should be taken on a Retina display, 2x resolution, with the app's "Paper" light palette. Crop tightly to the surface — no surrounding desktop chrome unless noted.
6+
7+
| File | What to capture | Suggested size |
8+
|---|---|---|
9+
| `hero.png` | Menu bar dropdown in `Recording` state, with the elapsed timer visible. Optional: composite over a soft Paper-palette backdrop. | ~1200 × 800 |
10+
| `menubar-dropdown.png` | Menu bar dropdown in `Watching` state, showing 2–3 Recent Meetings. | 268 × natural |
11+
| `recording.png` | Menu bar dropdown in `Recording` state with the dark `#2E3338` header strip and elapsed time. | 268 × natural |
12+
| `transcript.png` | A finished Markdown transcript open in a Markdown viewer (e.g. Obsidian, Marked 2, or VS Code preview). Speaker labels, timestamps, and at least one `[mm:ss] _**Note from …:**_` line should be visible. | ~1000 × 700 |
13+
| `dictation-hud.png` | The floating "Dictating" pill at the bottom of the screen, with a focused text field above it showing live transcribed text. | ~900 × 500 |
14+
| `settings-general.png` | Settings → General tab. Show the Behavior, Permissions, and Custom vocabulary cards. | 880 × 600 |
15+
| `settings-models.png` | Settings → Models tab with the dark hero card and a couple of model rows. | 880 × 600 |
16+
| `settings-speakers.png` | Settings → Speakers tab with a populated list, search visible. | 880 × 600 |
17+
| `name-speakers.png` | Speaker naming window with two candidate cards (one playing, one idle) and the auto-dismiss countdown. | 560 × 520 |
18+
19+
## How to capture cleanly
20+
21+
1. Launch the bundled app: `./scripts/bundle.sh && open build/Heard.app`.
22+
2. Enable Developer Mode (Settings → General) so the **Simulate Meeting** buttons appear.
23+
3. Resize the Settings window to its default 880 × 600 and snap window screenshots with `⌘⇧4 + space` then click the window.
24+
4. For the menu bar dropdown, use `⌘⇧5` → "Capture Selected Portion" and drag a rectangle around the panel.
25+
5. Save PNGs into this folder with the exact filenames above.
26+
27+
Hi-DPI PNGs render crisply on GitHub; avoid JPEG.

0 commit comments

Comments
 (0)