A few steps.
Then, your voice.

Before you start

• macOS 13 (Ventura) or later on an Apple Silicon Mac.
• Xcode or Apple’s Command Line Tools, including Swift and Git.
• Your own OpenAI API key, Azure OpenAI deployment, or compatible transcription server.
• A microphone and a text field to try it in.

koe is MIT-licensed. Your transcription provider charges separately for API usage. The developer does not supply a key, credits, or a shared service.

To install Command Line Tools, run xcode-select --install, then complete Apple’s installation dialog. You do not need the full Xcode app.

Build & install

Open Terminal and run the following commands. Read them first: they clone the public source, create a local development signing certificate, build the app, and copy it to Applications.

git clone https://github.com/YIPG/koe.git
cd koe
make signing-cert
make install
open /Applications/koe.app

make signing-cert creates a local self-signed identity so permissions can persist across rebuilds. It is not Apple notarization. Do not disable Gatekeeper globally to run this preview.

The app appears in your menu bar, not the Dock. To install only for your user account, use make install INSTALL_DIR=~/Applications and open that copy instead.

To update later, quit koe, run git pull --ff-only from a clean checkout, then repeat make install and open the installed app.

Connect your service

Open koe → Settings → Connection. Choose a provider and enter your own details. Click Save & Use to activate them. Simply changing the provider picker does not switch the active connection.

OpenAI

Create an API key in your own OpenAI account and configure API billing. A ChatGPT subscription and API billing are separate.

Provider

OpenAI

API key

Your personal API key, saved in macOS Keychain.

Model ID

gpt-transcribe is the current OpenAI file-transcription recommendation. Use a model available to your account.

See the official model guide and current API pricing. koe does not silently upgrade your selected model.

Azure OpenAI

You need your own Azure resource and a deployed file-transcription model. A deployment name is not necessarily the same as its model ID.

Resource URL

https://your-resource.openai.azure.com, without an API path.

Deployment

The name of your deployment in Azure.

Model ID

The model behind it, such as gpt-transcribe.

API key

Your own resource’s key.

API compatibility

Use the deployment API. 2025-03-01-preview has been verified with gpt-transcribe. A new model does not automatically need a new API route.

Azure’s v1 transcription route is an explicit option, but it may not work on every resource. Check Azure model availability and your quota. Visual Studio/MSDN credits are for development and testing, not production.

OpenAI-compatible server

Enter the base URL (including /v1 if the server requires it), model ID, and a key if required. The server must support POST /audio/transcriptions with multipart audio and a JSON response containing text. Chat API compatibility alone is not enough.

Use HTTPS for remote servers. HTTP is accepted only for loopback servers such as http://127.0.0.1:8080/v1. For custom model aliases, select the appropriate language-hint format under API compatibility.

Never paste your API key into this website. Configure it inside the Mac app. Settings are checked locally when saved; the provider checks credentials, model access, and quota when you transcribe.

Give koe permission

In Settings → Privacy, enable the permissions you need.

• Microphone: required to capture your voice during dictation.
• Accessibility: needed to paste text into another app automatically. Without it, koe leaves the text on your clipboard for manual paste.

You can review or revoke either permission in System Settings → Privacy & Security. The website itself never requests microphone access.

Your first dictation

1. Open a text field and place your cursor where the words should go.
2. Press ⌃ ⌥ Space, or your configured shortcut.
3. Speak. The floating indicator shows that koe is listening.
4. Press the same shortcut again to stop and transcribe.
5. Keep the target app focused while the text is being processed.

Choose Japanese, English, or automatic language detection in Settings → Dictation. You can also change the shortcut there.

If something feels off

Nothing is inserted

Check Accessibility permission and make sure your cursor is in an editable field. If koe reports that Accessibility is missing, use ⌘ V to paste the result. Automatic insertion is not guaranteed in every app or protected field.

AirPods sound different while recording

Using a Bluetooth headset’s microphone can change its audio mode and reduce playback quality. In macOS Sound settings, keep AirPods as the output and select another microphone as the input. Apple explains this behavior.

The service reports an error

• 401 / 403: check the key and your account’s access.
• 404: check the endpoint, deployment, model, and API route. On Azure, try the deployment API rather than v1.
• 429: your provider’s rate limit or quota was reached. Check billing and retry later.
• Recording too large: use a shorter recording. The upload limit is 25,000,000 bytes.

Do not post keys or private recordings when reporting a problem.

Know the preview’s limits

• No notarized installer or App Store release.
• No transcription history, recovery queue, or built-in local model.
• Current clipboard restoration preserves text, not copied images or files.
• Text is pasted into the focused app when processing finishes. Avoid switching apps while waiting.
• No built-in recording cancel action or recording-duration limit.
• Provider fees, availability, latency, and transcription accuracy vary.

Use short, non-sensitive recordings while getting familiar with the app. This is a personal utility preview, not a managed transcription service.