How to use Koe

Koe lives in your Mac’s menu bar. This guide takes you from installing it to your first transcript, then covers everything else.

What you need

• A Mac with Apple Silicon (M1 or later)
• macOS 15 or later
• 655 MB of free space for the speech models, plus room for your recordings (about 60 MB per hour at the default quality)

Install Koe

1. Download Koe and open the DMG file.
2. Drag Koe onto Applications.
3. Open Koe from Applications or Spotlight. It has no Dock icon: look for the ring in the menu bar, at the top right of the screen.
4. Eject the “Koe” disk and delete the DMG.

Koe updates itself after that.

First run

The first time Koe starts, a setup window takes you through eight short steps. You can skip any of them.

1. Welcome What Koe does.
2. Microphone macOS asks for permission. A bar moves when you speak.
3. Sound from other apps The Screen & System Audio Recording permission, so Koe can hear the other people on a call. It records sound only, never your screen.
4. Notifications For “Transcript ready” and “Looks like a call started”.
5. Transcripts folder ~/Documents/Koe unless you pick another one.
6. Your name How your microphone is labeled in transcripts (“Me” by default).
7. Speech models A one-time download of 655 MB. Continue in Background lets you close the window while it runs.
8. Done Choose whether Koe opens at login.

To go through setup again: Settings → Help → Set Up Again…

Record your first call

1. Click the ring in the menu bar. A panel opens.
2. Press Start recording. The ring fills with moving water and the button turns red.
3. Have your call.
4. Press Stop recording.
5. Wait for the Transcript ready notification, and click it to open the folder.

Transcription takes about 1 second per minute of speech on a MacBook Air M2, so an hour-long call takes about a minute.

If you’d rather not think about it, Koe can offer to record when a call starts. When an app holds the microphone for more than a few seconds, you get a “Looks like a call started” notification with a Record button.

Choose what to record

The panel has tabs for each source. Turn off what you don’t need.

Koe remembers your choice between launches. You can’t change it during a recording.

Record a Zoom call on your Mac

Keep both tracks on and press Start recording. If other apps are making sound, open the System audio tab and tick Zoom, and Koe records only its sound.

Record a Google Meet call on your Mac

Google Meet runs in the browser, so tick your browser under System audio, or leave it on All apps.

Record a Telegram call on your Mac

Keep both tracks on. To leave out other apps, tick Telegram under System audio.

Record system audio without BlackHole

Koe records your Mac’s system audio without a virtual audio driver. In the Microphone tab, switch off Record the microphone if you want only the sound of your apps. In the System audio tab, pick All apps or tick the ones you need.

Record several microphones

You don’t need a sound card. Tick two or more microphones in the Microphone tab, and each one gets its own track and its own name in the transcript. For a podcast, choose Lossless in the Format tab. If you do have a sound card with several inputs, choose Each channel separately in its Input channels menu.

All tracks run on one clock, so they stay in sync for hours. With two microphones in one room, a line both of them heard stays only on the track where it was louder.

Pick the sound quality

Open the Format tab.

Name the speakers

Koe splits the system audio track by voice and labels people Speaker 1, Speaker 2 and so on, in the order they first spoke. Each microphone is one person.

To add real names:

1. Open Settings → Transcripts → Names and pick a recording.
2. Type a name next to each track. The ▶ button plays about 5 seconds of that person’s speech.
3. Click Save. The transcript updates in a few seconds, with no new transcription.

If one person got two labels, give both rows the same name.

Fix words Koe gets wrong

List product names and terms under Settings → Transcription → Vocabulary, one per line. It works for words in Latin letters only, makes transcription about three times slower, and downloads a helper model of about 100 MB once.

Find your transcripts

Each recording gets its own folder in ~/Documents/Koe, with the transcript in transcript.md and the sound in audio/. The Transcripts button in the panel opens the folder.

If you edit a transcript and later transcribe that recording again, your version is saved next to the new one.

What the menu bar icon means

Common problems

The other people’s voices are missing Koe needs permission to record other apps’ sound: System Settings → Privacy & Security → Screen & System Audio Recording → Koe.

“No sound came from Zoom” The apps ticked under System audio made no sound during the recording, because the call was really in another app, such as a browser. Tick that app or pick All apps.

Koe can’t use the microphone System Settings → Privacy & Security → Microphone → Koe.

“Waiting for the speech models” Koe couldn’t download them, and the message says why. Your recordings are saved and wait in the queue. Koe tries again by itself.

No notifications System Settings → Notifications → Koe → Allow notifications.

Two people got one label, or one person got two Move Settings → Transcription → Telling voices apart toward more people or fewer people, then transcribe the recording again.

A recording couldn’t be transcribed Open the Transcription tab to see the reason and click Try Again.

Your Mac went to sleep during a recording The recording stops properly when the lid closes, and what was recorded gets transcribed. Your Mac won’t fall asleep on its own while recording or transcribing.

Remove Koe completely

1. Stop any recording, turn off Open at login in Settings → General → Other, and click Quit in the panel.

2. Drag /Applications/Koe.app to the Trash.

3. In Finder, press ⇧⌘G, paste each path and move it to the Trash:

   • ~/Library/Application Support/com.tsarionov.koe
   • ~/Library/Caches/com.tsarionov.koe
   • ~/Library/Logs/com.tsarionov.koe
   • ~/Library/HTTPStorages/com.tsarionov.koe
   • ~/Library/Preferences/com.tsarionov.koe.plist

4. Optional: to make macOS forget Koe’s permissions, run this in Terminal:

   tccutil reset All com.tsarionov.koe

Your transcripts and recordings in ~/Documents/Koe stay. Delete them yourself if you don’t need them.