Build Granola

The build, in order

1. 1

   Audio capture, proven as a CLI first

   hideshow

   Before any UI exists, prove you can record system audio and the mic into a WAV that whisper-cli accepts. This is the phase that kills the project if skipped.

   1. 1.1Create an Xcode project with two targets: a command-line tool and the menu bar app

      The CLI target is for this phase; the app target waits until Phase 5. Both share a Swift package with the capture code.

      Files MeetingNotes.xcodeprojSources/Capture/

   2. 1.2Capture system audio with ScreenCaptureKit

      Build an SCStreamConfiguration with capturesAudio true. SCStream still requires a screen output to be added even for audio only: add one and set minimumFrameInterval to a very large value so no real frames are processed. On macOS 14.2+ you may instead use Core Audio process taps (AudioHardwareCreateProcessTap) for genuine audio-only capture; pick one and say which in a comment.

   3. 1.3Capture the microphone with AVAudioEngine, separately

      Do not use SCStreamConfiguration's microphone capture; it has known output-corruption reports. Tap the input node and collect buffers.

   4. 1.4Mix both taps and write 16 kHz mono 16-bit PCM WAV

      Resample explicitly with AVAudioConverter. Not 44.1 kHz, not float, not stereo. whisper-cli accepts 16-bit WAV only; every hour lost to this project is lost here.

   5. 1.5Run the CLI for 30 seconds while music plays and you speak
      terminalcopy

      swift run capture-cli --seconds 30 --out /tmp/test.wav
      afinfo /tmp/test.wav
      /path/to/whisper-cli -m /path/to/ggml-medium.en.bin -f /tmp/test.wav

   done when · tick each as it passes

   • afinfo reports 16000 Hz, 1 channel, 16-bit for the WAV
   • Playing the WAV back you hear both the music and your voice
   • whisper-cli accepts the file without a format error and prints text
   • Denying Screen Recording produces a clear error naming the System Settings pane, not a silent empty file

   watch out

   • Do not tell the user to install BlackHole or Loopback. ScreenCaptureKit delivers system audio under the screen-recording grant with no driver.
   • The permission prompt appears once per launch. If it is dismissed the app must be relaunched; detect the denied state and say so.

   next phase
2. 2

   Transcription

   hideshow

   A transcript from a WAV, local by default, with progress you can see and a hosted fast path when a key exists.

   1. 2.1Shell out to whisper-cli with -otxt

      Process with WHISPER_BIN, WHISPER_MODEL and the audio path. Read the .txt it writes. Capture stderr for progress lines.

      terminalcopy

      whisper-cli -m $WHISPER_MODEL -f audio.wav -otxt -of transcript

   2. 2.2Report progress

      A 45-minute meeting on the medium model is minutes of CPU. Parse whisper's progress output into a percentage; a UI that looks frozen will be assumed broken.

   3. 2.3Add the hosted path behind TRANSCRIBE_MODE

      When hosted and a Groq or OpenAI key exists, post the WAV to the Whisper endpoint. Local remains the default: the recording should not leave the machine unless asked.

   4. 2.4Make it resumable

      Write the transcript to a temp name and rename on completion. Killing the app mid-transcription must leave the audio intact and no half-written transcript.

   done when · tick each as it passes

   • A 5-minute recording produces a transcript whose first and last sentences are recognisably correct
   • Progress moves during transcription
   • Killing the app mid-transcription leaves audio.wav intact and no transcript.txt
   • With TRANSCRIBE_MODE=hosted and a key, the same file transcribes via the API

   next phase
3. 3

   Summarization

   hideshow

   A fixed prompt turns the transcript and your jotted notes into a 5-bullet summary, decisions and action items with owners, and long meetings are chunked rather than truncated.

   1. 3.1Write the provider interface and one implementation

      summarize(transcript, notes) returning structured text. Anthropic first; OpenAI as a second implementation selected by which key exists.

   2. 3.2Chunk transcripts that exceed the context window

      Split on paragraph boundaries into chunks under the model's limit, summarize each, then summarize the summaries. Never silently truncate: that produces confident notes about the first third of a meeting.

   3. 3.3Pass the user's rough notes alongside the transcript

      This is the actual Granola idea: your jottings steer what the summary emphasises.

   done when · tick each as it passes

   • A transcript with three clear decisions and two assigned tasks yields notes naming all five
   • A 90-minute transcript summarizes without an API error
   • With no key present the step is skipped with a clear note in the output, not an error

   next phase
4. 4

   Notes on disk

   hideshow

   One folder per meeting, plain Markdown with frontmatter, never overwriting.

   1. 4.1Write NOTES_DIR/YYYY-MM-DD-HHMM-<slug>/ with audio.wav, transcript.txt and notes.md

      notes.md: YAML frontmatter (title, date, duration, participants, model), the summary, a divider, then the full transcript.

   2. 4.2Derive the title from the summary and never overwrite

      If the folder exists, suffix a counter. Two meetings in the same minute must produce two folders.

   done when · tick each as it passes

   • Two meetings started in the same minute produce two folders
   • notes.md opens correctly in a plain Markdown editor with no app running
   • The audio file is kept next to the notes

   next phase
5. 5

   Menu bar app

   hideshow

   Start and stop from the menu bar, jot notes while recording, see recent meetings, and get told exactly what to do when a permission is missing.

   1. 5.1Build the MenuBarExtra with Start/Stop and elapsed time

      A recording indicator that is unmistakable. Wire the capture code from Phase 1.

   2. 5.2Add the live jot-notes field

      Text typed during the meeting is passed to the summarizer in Phase 3.

   3. 5.3List recent meetings with Reveal in Finder

      Read NOTES_DIR; newest first.

   4. 5.4Handle permissions explicitly

      If Screen Recording or Microphone is denied, show which System Settings pane to open and the relaunch caveat, instead of failing silently.

   done when · tick each as it passes

   • A full meeting runs start to notes without touching a terminal
   • First launch on a machine that has never granted permission explains itself
   • The jotted notes visibly influence the summary

   next phase
6. 6

   Offline, packaging, README

   hideshow

   Works with the network off when the model is present, signed for your own machine, documented.

   1. 6.1Test with Wi-Fi off and no LLM key

      Transcript saved; summary skipped with an honest note in notes.md.

   2. 6.2Sign locally and document the Gatekeeper first-run step

      Sign with your development certificate for your own use. Right-click > Open the first time.

   3. 6.3Write the README

      Permissions and where to grant them, model download size, disk cost per hour of audio, and a plain warning that recording a meeting can require consent from everyone in it depending on where they are.

      Files README.md

   done when · tick each as it passes

   • Airplane mode produces a complete transcript and a note saying the summary was skipped
   • A fresh Mac goes from clone to first recording using only the README

   next phase