Voice dictation
Instructions to an agent are prose, and prose is faster spoken than typed — especially on a phone. In any attached agent session you can talk, and the transcript lands in the terminal as if you had typed it.
There are two ways to turn speech into text, and you choose per service record:
- On this device, with Apple’s speech recognition. No account, no API key, and the audio never leaves the device — not even to Apple.
- Through a service you bring yourself, with your own API key. Audio goes directly from your device to that provider — never to us. SigilTTY does not run its own speech service.
Where the microphone is
Section titled “Where the microphone is”- iPhone and iPad — a microphone key on the keyboard accessory bar, to the left of the paperclip. It appears only in attached agent sessions, so it rides along with the keyboard where the typing happens. (Before 1.6.2 this was a floating button in the corner of the terminal.)
- Mac — a floating microphone button in the bottom-right corner of the terminal.
The key only starts dictation; recording ends from the bar that appears (see Dictating). While that bar is up the microphone is ignored, so a second recording can never start on top of one still being transcribed. In a session that has ended, or during a ZMODEM transfer, the microphone does nothing.
If you tap it with no service configured, a strip asks the question directly — “No transcription service yet. Set up Apple’s on-device model or a third-party service?” — with a Set Up… button that takes you straight there.
Transcribing on this device
Section titled “Transcribing on this device”Go to Settings › Voice Input, choose Add Service, and pick Apple Speech (On-Device) — the first entry in the list, and the only one with nothing to fill in. There is no API key and no Base URL; the one setting that matters is the Language.
Apple’s recognizers handle one language at a time — there is no Auto. The editor starts from
your device’s language and you can pick another from the list (Chinese, English, Japanese, Korean,
Cantonese, Traditional Chinese) or type any other BCP-47 code, like de-DE, under Custom….
Under the language, a status row tells you whether this device can actually run it:
| Status | What it means |
|---|---|
| Checking on-device availability… | The probe is running; it settles in a moment. |
| Ready to transcribe on this device | Nothing more to do. |
| Download Language Model | The language is supported but its model is not on the device yet. Tap to download it once, with a progress bar. |
| Model download in progress… | A download is already running — including one started elsewhere on the system. |
| A warning sentence | Neither path can serve this language on this device. See troubleshooting. |
SigilTTY never downloads a model in the middle of dictation. Models run to hundreds of megabytes and you might be on cellular, so the download lives here, in the service’s settings, where you decide when it happens.
Which engine runs depends on the device: iOS 26 and macOS 26 use Apple’s newer speech models, with the explicit one-time download above. Older systems — and a few devices where the new models are unavailable — use the system dictation recognizer, which SigilTTY pins to on-device recognition: if a language cannot run locally, dictation fails with a clear message rather than quietly sending your audio to Apple’s servers. Recognition quality therefore depends on the device and the system version.
Setting up a third-party service
Section titled “Setting up a third-party service”The same Add Service menu has presets for OpenAI, Groq, SiliconFlow, Volcengine (Doubao) and iFlytek (讯飞听写), plus Custom… for any other endpoint. A service record’s type is fixed once created; everything else can be edited later.
There are three kinds of remote service:
- OpenAI-compatible — an HTTPS transcription endpoint. Set the API key, pick a model (or type your own), and optionally a Base URL for non-OpenAI hosts like Groq or SiliconFlow. The whole recording is sent when you stop speaking.
- Volcengine (Doubao) — streams audio over WSS while you speak, so the transcript comes back almost as soon as you stop. Pick a Resource (Doubao 2.0 or 1.0, hourly- or concurrency-billed) and tune Number Formatting, Punctuation and Remove Filler Words. Filler-word removal rewrites what you said, so it is off by default.
- iFlytek (讯飞听写) — also streaming, configured with the App ID, API Key and API Secret from the iFlytek console. Recordings stop at 55 seconds because one iFlytek session may not exceed 60.
Each record carries its own Language setting. OpenAI-compatible and Volcengine services offer Auto plus Chinese, English, Japanese, Korean and Cantonese (with a custom escape hatch); iFlytek offers Chinese and English and has no Auto.
You can keep several records — say, Apple Speech on your iPhone for offline work and OpenAI on your Mac. Records (keys included) sync through iCloud Keychain with credential sync, but which record is selected is a per-device choice — each device picks the service that suits its network and use.
Dictating
Section titled “Dictating”Tap the microphone and a recording bar appears along the bottom of the terminal, with a live waveform: “Transcribes when you pause.” Speak normally. Once you have said something (about a third of a second of speech), a 1.8-second pause ends the recording and sends it off — thinking silence before you start talking never triggers it. You can also end it yourself with Done, or discard it with Cancel. Recordings cap at 120 seconds (55 for iFlytek).
What gets inserted
Section titled “What gets inserted”The transcript is inserted into the terminal exactly as if you had typed it — and nothing more:
- Newlines are collapsed to spaces and whitespace is trimmed, so a stray line break in the transcript can’t submit half a thought.
- It never presses Enter for you. You read what arrived, fix anything misheard, and send it yourself. A voice pipeline should not be able to command an agent without your eyes on the text.
- An empty transcript inserts nothing — you get a short notice instead. Same if the session ended or a file transfer started while transcription was in flight.
Testing a service
Section titled “Testing a service”Settings › Voice Input has a Test section: record a short sample and it is transcribed by the selected service, showing the transcript and the round-trip time. Nothing about the test is stored.
This is the fastest way to separate a configuration problem from a terminal one — a service that fails in Test will fail in the terminal too, and one that works in Test narrows the problem to the session.
When something goes wrong
Section titled “When something goes wrong”Failures appear in the same bottom strip, with Retry next to the message. The recording stays in memory until you dismiss the strip, so retrying re-transcribes what you already said — you do not have to repeat yourself. Nothing is ever written to disk.
Permission errors
Section titled “Permission errors”Dictation needs two separate permissions, and on-device transcription is the only path that needs the second one.
| Message | What to do |
|---|---|
| Microphone access is off for SigilTTY | Tap Open Settings on the strip. On iPhone and iPad this opens SigilTTY’s own page in Settings; on Mac it opens System Settings › Privacy & Security › Microphone. |
| Speech recognition is off for SigilTTY | Same Open Settings button (Mac: Privacy & Security › Speech Recognition). This one is asked for after recording, so the audio is still held — grant it and press Retry to transcribe what you just said. |
On-device transcription errors
Section titled “On-device transcription errors”| Message | Cause and fix |
|---|---|
| The on-device model for this language is not downloaded | The newer models support this language but its model is not installed. Go to Settings › Voice Input, open the record, and use Download Language Model. Deliberately not automatic — see above. |
| On-device recognition for this language is not ready — add it as a dictation language in the system keyboard settings | The older path is in use and the system has no local dictation model for that language. On iPhone and iPad: Settings › General › Keyboard › Dictation — enable it and add the language. On Mac: System Settings › Keyboard › Dictation and add it under Languages. Then reopen the record; the status row should read Ready to transcribe on this device. |
| This language is not supported for on-device speech recognition on this device | The language code is not one this device recognizes. If you typed a Custom… code, check the format — it is BCP-47, so zh-CN, not zh_cn or zh-cn-hans. Otherwise pick a language from the list, or use a third-party service for that language. |
| Transcription failed (code …) on the on-device record | An unexpected error from the system recognizer, passed through with its real code. Retry; if it repeats, check the language row and whether the model finished downloading. |
A note on the Simulator: the newer models are unavailable there, so it always falls back to the older recognizer. Judge recognition quality on a real device.
Nothing was transcribed
Section titled “Nothing was transcribed”If the strip says the transcript was empty, the recording contained no recognizable speech. Check that the right microphone is picked up (a connected headset or an external mic on Mac), that you are not too far away, and that the record’s language matches what you actually said — a Chinese record will not do much with an English sentence.
Third-party service errors
Section titled “Third-party service errors”| Message | Cause and fix |
|---|---|
| No transcription service — add one in Settings › Voice Input | The selected record disappeared mid-flight (usually deleted on another device while you were speaking). Open Settings › Voice Input and select or add one. |
| The transcription service rejected the API key | HTTP 401/403. Re-check the key, and that it belongs to the host in Base URL. For iFlytek, a 403 is most often a device clock more than 5 minutes off — or an IP allowlist on the console — not a wrong key; the provider’s own detail is appended after the em dash, so read it. |
| Transcription failed (HTTP 404) | The endpoint or model name is wrong. Non-OpenAI hosts often need a path prefix kept in the Base URL — Groq’s is https://api.groq.com/openai. |
| Transcription failed (HTTP 429) or a 5xx | Rate limit or an outage on the provider’s side. Retry — the recording is still in memory. |
| Transcription failed (code …) | A provider-level code from a streaming service, not an HTTP status — Volcengine and iFlytek report failures inside the WebSocket. The number is the provider’s own, so look it up in their documentation: Volcengine 45000001 is a bad parameter and 55000031 a busy server; iFlytek 10165 usually means a malformed session and 10114 a session that ran too long. |
| The transcription service returned an unreadable response | The endpoint answered with something that is not a transcription result — most often a Base URL pointing at the wrong path, or a gateway/proxy page in front of the real service. |
| A network message (timeout, host not found…) | Passed through from the system. Check connectivity, and remember that Volcengine and iFlytek need WSS, not HTTPS, so a proxy that only handles HTTP will fail here. |
The transcript stops mid-sentence
Section titled “The transcript stops mid-sentence”Almost always a streaming provider closing the session early. On iFlytek, sessions cannot exceed 60 seconds and SigilTTY stops recording at 55; a long dictation will be cut there. Say it in shorter passages, or use an OpenAI-compatible or on-device record, neither of which has that limit.
The transcript never arrived in the terminal
Section titled “The transcript never arrived in the terminal”Three things stop a finished transcript from being inserted, and each shows a short notice: the transcript was empty, the session ended while transcription was in flight, or a file transfer started in the meantime. In the last two cases the text is discarded rather than typed into somewhere it does not belong.
Looking deeper
Section titled “Looking deeper”Failures are recorded in the Log Center under the App category, with the error message attached — useful when a failure is intermittent, and the right thing to include in a support request. Transcripts, audio and API keys cannot be written to the log at all.
A record shown as Needs a newer version of SigilTTY was created by a newer build on another device. It is displayed but cannot be selected or edited; update the app on this device, or add a record here instead.
Privacy
Section titled “Privacy”- On-device records send nothing anywhere. Audio and transcript stay on the device, and SigilTTY pins the recognizer to local processing — it will fail loudly rather than fall back to Apple’s servers.
- Audio is captured to memory and never written to disk — there is no recording file to clean up, on any platform.
- For third-party records, audio is sent only to the service you configured, authenticated with your key. SigilTTY has no speech servers of its own.
- Streaming services (Volcengine, iFlytek) upload audio while you speak; OpenAI-compatible services receive the finished recording when you stop.
- Canceling — or switching tabs, or backgrounding the app mid-recording — discards the audio.