Install, the helper, the dictionary.

Install the unsigned pkg

Quit Logic first. The download is an unsigned macOS package from the latest GitHub Release. Gatekeeper will warn. There is no Developer ID signature and no notarization yet.

1. Open the pkg. If Gatekeeper blocks it, the release page is still the place to get the file. Right-click Open when macOS offers that for the unsigned installer or the unsigned helper.
2. The package lays down the AU at /Library/Audio/Plug-Ins/Components/punch2pen.component and the VST3 at /Library/Audio/Plug-Ins/VST3/punch2pen.vst3.
3. The engine app lands at /Applications/Punch2Pen/punch2penEngine.app. A second copy is nested at Contents/Helpers/punch2penEngine.app inside both the AU and the VST3.
4. Postinstall strips quarantine, ad-hoc signs those engine apps, and mirrors the AU and VST3 into ~/Library/Audio/Plug-Ins so an older copy in your home folder cannot hide the nested helper.
5. Postinstall downloads ~/.punch2pen/models/ggml-base.bin when that Whisper model is missing. Offline, place the file there yourself. The model is not baked into the pkg.
6. Postinstall registers a RunAtLoad LaunchAgent at /Library/LaunchAgents/com.doctaaa.punch2pen.engine.plist and starts the engine, so 127.0.0.1:7483 is up before the editor opens.
7. Insert punch2pen on an audio track in Logic. The editor leaves WAIT after the handshake. Identity check, on a Mac you trust: auval -strict -v aufx P2pn Dcta.

If the editor stays on WAIT: confirm ggml-base.bin is in place, do not use a leftover ~/punch2pen/bin/punch2penEngine from an old build, and right-click Open /Applications/Punch2Pen/punch2penEngine.app once if Gatekeeper still blocks the helper. Engine logs go to ~/.punch2pen/engine.log. Plugin launch attempts go to ~/.punch2pen/plugin-ipc.log.

To stop the login helper before a local engine smoke test: launchctl bootout "gui/$(id -u)" /Library/LaunchAgents/com.doctaaa.punch2pen.engine.plist.

The nested engine helper

The helper is punch2penEngine, the local transcription process. It is not a second plugin. It loads whisper.cpp, binds 127.0.0.1:7483, and takes audio and corrections from the plugin. The free utility never points it at the profile API.

Logic’s AU sandbox must not inherit onto that process. The plugin starts the helper with Launch Services (open -g -n) so the engine is its own app. If open fails, the plugin posix-spawns Contents/MacOS/punch2penEngine inside the app bundle.

Lookup order:

1. PUNCH2PEN_ENGINE, if you set it.
2. /Applications/Punch2Pen/punch2penEngine.app
3. Contents/Helpers/punch2penEngine.app nested in the AU or VST3 you loaded.
4. A bare /Applications/Punch2Pen/punch2penEngine binary, last.

Leftover ~/punch2pen/bin/punch2penEngine is ignored. Those old binaries still carry a build-machine library path and die on launch. The plugin retries every few seconds until the socket handshakes. Two engines cannot share port 7483.

Corrections and the dictionary

The only edit is in the plugin. Click a word in the Living Transcript. A sheet docks at the bottom of the transcript with the word you clicked. Apply replaces every exact, case-sensitive match in the take and sends the pair to the engine. Cancel or Esc closes the sheet and sends nothing. Leading and trailing punctuation on a token stays put; the dictionary matches the word itself.

The engine keeps that pair in a dictionary: a case-sensitive map from the mis-heard token to the spelling you typed, plus a short vocabulary list (capped, ranked by how often you correct it and how recent it is) that biases the next whisper pass. There is no list editor, no import, and no screen for rewriting the dictionary by hand. You teach it by correcting words in the take.

Free / local session. The dictionary is in memory for this engine run. Nothing is written to disk. Nothing is sent. Restart, or a sign-out if you had been signed in, drops it.

Signed-in seat. Apply still starts in the plugin. The pair is then written to that profile’s cache at ~/.punch2pen/profiles/<id>.json and synced to the profile API. A pair that has not been acknowledged yet stays pending, including across a refresh, so an offline correction is not thrown away. The account file next to it is ~/.punch2pen/account.json (mode 0600) and holds the session, not the words.

Only the person signed in on that seat can read or write that dictionary. A workspace owner can add or revoke seats and does not get the pairs. The bar, the beat, and the playhead sample stay in the plugin, locked to the DAW clock. The dictionary stores the correction pair, not the timeline.

Sign-in for that seat is email plus a six-digit code, and it is not available in this build until mail delivery is configured.