Docs

Everything from first launch to answering a question you never typed.

Install

macOS — use Homebrew

1. Install Homebrew. Skip this if you already have it — check with brew --version.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

It asks for your Mac password and takes a few minutes. Homebrew is the standard package manager for macOS — it installs command line tools and applications and keeps them updated.

Homebrew's own documentation: brew.sh · docs.brew.sh · FAQ · installation guide

Useful afterwards:

Command	Does
`brew --version`	Check whether you already have it
`brew upgrade --cask souffleur`	Update Souffleur to the newest release
`brew uninstall --cask souffleur`	Remove it
`brew info --cask souffleur`	Show the installed version

2. Install Souffleur.

brew install --cask akshatgg/tap/souffleur

The app installs into Applications and opens with nothing to click through.

Do not download the disk image if you can avoid it. The build is signed but not notarised by Apple, so macOS refuses a manually downloaded copy with “Apple could not verify Souffleur is free of malware” and offers only Done and Move to Bin. Homebrew clears the download flag as part of installing, which is why the command has no such step.

If you really want the disk image

It is on the releases page. After dragging the app to Applications you have to approve it once:

Open Souffleur. macOS says it cannot verify it — click Done.
System Settings → Privacy & Security, scroll to the bottom, click Open Anyway.

Or clear the flag yourself:

xattr -dr com.apple.quarantine /Applications/Souffleur.app

Right-click → Open used to work for this and no longer does on macOS 15 and later. Notarisation would remove the step entirely — see SIGNING.md.

Then grant one permission:

System Settings → Privacy & Security → Screen & System Audio Recording → enable Souffleur.

Without it the overlay still runs, but it cannot capture your screen or hear the call — ScreenCaptureKit accepts the request and silently delivers nothing.

Windows

Run the .exe installer.

SmartScreen will say “Windows protected your PC” for the same reason: the installer is not signed by a certificate Microsoft recognises. Click More info, then Run anyway.

Everything works: the hidden overlay, screenshots, chat, call transcription and interview mode.

Call audio is captured differently on each platform, which you never see. Windows has a real loopback device, so Chromium captures the system mix directly. macOS has none, so a small ScreenCaptureKit helper does it. Both feed the same silence gate and transcription.

From source

git clone https://github.com/akshatgg/Souffleur.git
cd Souffleur
npm install
npm run build:native   # macOS only: audio tap + PDF reader
npm start

Connect a provider

You can skip this. While the free key is on, Souffleur answers with no key at all, up to a daily limit, and settings says so. A key of your own has no limit, and with it Souffleur talks to that provider directly and nothing else. There is no account either way.

Provider	Get a key
Google Gemini	aistudio.google.com/apikey
OpenAI	platform.openai.com/api-keys
Anything OpenAI-compatible	Groq, Together, OpenRouter, Ollama, LM Studio, vLLM — pick Other and give it a base URL

Open settings with the ⚙ button (on the free key, press Use my own key first), choose a provider, paste your key, then press Save.

The model list is fetched from your own key rather than hardcoded, so it shows what you can actually reach and doesn't rot when a provider retires a model. Press ↻ to refetch.

Keys are encrypted with your system keychain and stored per provider, so you can keep several and switch. The app window can never read a key back — it can only set one, or ask whether one exists.

Shortcuts

The same on macOS and Windows.

Does	Keys
Show or hide the overlay	`Shift` + `Space`
Capture your screen and ask about it	`Shift` + `S`
Start or stop listening to the call	`Shift` + `Z`
Answer the last thing they said	`Shift` + `A`
Clear the conversation	`Shift` + `K`
Close settings, stop a reply, or hide	`Esc`

Drag the title bar to move the window.

These are global shortcuts, and that has a cost. The system hands the combination to Souffleur before any other app sees it, so while it is running, Shift + those keys stop producing capital letters elsewhere — Shift + A will not type an A in your editor or in Slack.

Every shortcut is editable under Settings → Shortcuts. Adding Alt (for example Alt + Shift + A) keeps them one-handed without taking a letter away from the rest of the machine.

Asking about your screen

Press Shift + S — or the ▣ button — and whatever is on screen is captured and sent with your question. Type a question first to be specific, or send nothing and it answers “what is on my screen?”

The overlay excludes itself from that capture, so the model sees your work without seeing its own previous answer, and there's no hide-capture-show flicker to sit through.

Listening to the call

Press Shift + Z. Souffleur taps the audio coming out of your speakers — the other person's voice — transcribes it, and drops each line straight into the chat box. Press Enter to ask it.

How it decides where a sentence ends

Speech is split at pauses, not on a timer. A fixed window slices words in half and bills you for silence. Anything shorter than 0.9s is discarded as noise; anything over 20s is cut so long answers still stream.

So lines appear a second or two after someone stops talking, not while they speak.

Your own voice

Microphone capture is off by default — the point is hearing them, not you. When enabled, the two sources stay on separate channels so the transcript knows who said what, and Shift + A still answers their last line, not yours.

Nothing appearing? The status bar tells you which stage is failing: no audio arriving at all means the capture stream isn't really running, which is nearly always the Screen Recording permission. Audio arriving but below the speech threshold means the volume is too low.

Interview mode

Add up to four PDFs describing you — CV, portfolio, work history — and Souffleur answers in the first person as you, from your real background.

Settings → Documents about you → Add PDF
Turn on Interview mode
Your name is read from the first document; correct it if it's wrong
Save

Answers become spoken-length and first person, the way someone actually talks in a room, and technical questions are answered concretely.

It won't invent a history. The model is instructed to keep every claim about your experience inside the documents — no invented employers, titles, dates, clients or numbers. Asked about something not in there, it says how you'd approach it and what in your background is closest, instead of claiming it. A fabricated employer is the one thing an interviewer catches instantly.

Text is extracted once when you upload, not re-sent with every message. Scanned PDFs with no text layer are rejected — they'd need OCR.

Is it really hidden?

On macOS the overlay sets NSWindowSharingNone, which excludes it from ScreenCaptureKit — the capture path Zoom, Meet, Teams, Discord and OBS all use. On Windows it uses WDA_EXCLUDEFROMCAPTURE.

This was verified by measurement, not assumed: three windows captured through a live 30fps stream, of which the unprotected control appeared in 100% of frames and both protected windows in none of 151.

What it does not protect against

A phone camera pointed at your screen, or anyone sitting next to you
Linux — no compositor implements capture exclusion, so the overlay is visible
Windows before build 19041, where the window becomes a black box instead of being excluded
A future OS release changing this behaviour

The status bar reads the platform at runtime rather than trusting an assumption, and turns amber when protection is not actually in force. If it says hidden, that's a live check, not a promise made at build time.

Troubleshooting

The overlay isn't visible

Press Shift + Space. It hides rather than quits, and there's no Dock icon by design.

It asks for my keychain password

“Souffleur wants to access key souffleur Safe Storage in your keychain.” Click Always Allow and enter your Mac login password — not your Apple ID, and not your API key.

Your API key is encrypted with that keychain item. macOS will not hand an existing item to a binary it has not seen before, which is the check that stops other apps reading it.

Because the build is ad-hoc signed, its identity changes with every version, so the prompt returns after each update. A Developer ID certificate gives the app one stable identity and it stops asking — the same certificate that removes the launch warning. See SIGNING.md.

“No API key set”

Keys are stored per provider. If you switched from Gemini to OpenAI, the OpenAI key is a separate one. If the app was renamed or moved, a stored key may no longer decrypt — settings will say so explicitly, and you just paste it again.

A model returns nothing

Open settings and press ↻ to reload the model list from your key, then pick one from the dropdown. Providers retire models, and the error will name the real cause.

Nothing is transcribed

Check Screen Recording is granted, and that audio is actually playing through your speakers rather than a headset the tap can't see.

Privacy

No telemetry. Downloading from the site asks for a Google sign-in, which records a name and an email address; the app never asks for either.
With your own key, screenshots, audio and documents go only to the provider whose key you supplied.
On the free key they pass through Souffleur's server to Google Gemini. The server logs none of it and keeps only a daily count per install, under a hashed id, for two days.
Keys are encrypted in the system keychain; the UI can never read one back.
Transcripts live in memory and are gone when you quit.

Many employers, universities and certification bodies prohibit assistance of this kind in interviews and exams. Worth knowing which rules apply to you before you rely on it.