Skip to article
HB CodeDocs
Get the app

HandbookBundled tools

Dictation and vocabulary

Desktop dictation runs on your own OpenAI or Gemini key with hint vocabularies per project. Phones transcribe through HB Code services. The error classes tell you which layer failed.

Checked against the source on 5 October 2026

On this page

Set up dictation

Only phone dictation goes through HB Code’s regional server
Only phone dictation goes through HB Code’s regional serverDesktop dictation records in the desktop runtime and sends the audio with your API key and vocabulary straight to OpenAI or Gemini, and the transcript comes back into the composer. Over 25,000,000 bytes the desktop refuses before uploading to OpenAI. Phone dictation first borrows the desktop’s vocabulary prompt over the relay, then uploads the audio with its HB Code JWT to the regional server, which transcribes it with OpenAI under HB Code’s key and charges your credits. The server accepts up to 100 MiB, but its OpenAI call stops at 25 MiB.
Desktoprecords in the runtime
OpenAI or Geminigpt-4o-transcribe · gemini-flash-latest
audio, your API key, your vocabulary
transcript
over 25,000,000 bytes: refused before the OpenAI upload
vocabulary prompt, via the relay
PhoneiPhone or Android
Regional server/api/audio/transcriptions
OpenAIopenai/gpt-4o-transcribe
audio + JWT
transcript
HB Code’s key
transcript
the server takes up to 100 MiB, but its OpenAI call stops at 25 MiB
  • Your keytranscribe_with_provider

    The desktop calls OpenAI or Gemini directly with the key saved under Settings → API Keys. HB Code’s servers see neither the audio nor the key.

  • HB Code’s key/api/audio/transcriptions

    Phones upload with their HB Code JWT and ask for openai/gpt-4o-transcribe. The server refuses the upload without a positive credit balance and charges the transcription to your account.

  • Borrowed vocabularysystem.voiceTranscriptionContext

    Before uploading, the phone asks the desktop over the relay for its vocabulary prompt. Without an answer it uploads without one, and the server builds its own default prompt.

  1. Open Settings → API Keys.
  2. Save a personal OpenAI or Gemini API key.
  3. Open Settings → Voice.
  4. In the Voice Dictation card, select OpenAI or Gemini as the dictation service.
  5. Click Save.
  6. When the operating system asks for microphone access, allow it.

Dictation uses your own API key and is separate from the ChatGPT or Claude sign-in that runs the agent. The only accepted model IDs are gpt-4o-transcribe and gemini-flash-latest. Before the first recording the desktop sends a synthetic preflight WAV to the real provider endpoint and caches the result per provider and model for 15 minutes after a success and 5 minutes after a failure, or until you save settings again. OpenAI requests time out after 120 seconds.

Review Mode recordings go through the regional server to Gemini with POST /api/llm/video/analyze. On iPhone each capture’s narration is transcribed first. Review Mode in the iOS and Android media chapters has the details.

Dictation on iOS

Recording, retries, and the vocabulary prompt from the desktop.

Dictation on Android

The microphone foreground service and the upload.

Add your words to the vocabulary

OpenAI gives your vocabulary 265 of 1,000 bytes and cuts the project list first
OpenAI gives your vocabulary 265 of 1,000 bytes and cuts the project list firstThe OpenAI transcription prompt is limited to 1,000 bytes, drawn to scale. The escaped rules with their tags take 683 bytes, and a newline and the vocabulary tags take 52, so your vocabulary text gets the last 265 bytes. The global list comes first, so the project list is the part that gets cut. Gemini’s limit is 1,000,000 bytes: drawn at the same width, its full 1,836-byte rules are a thin line and the rest holds about a megabyte of vocabulary. A phone uses the same prompt when the desktop builds it for OpenAI.
OpenAI prompt, 1,000 bytes to scale
your vocabulary, 265 bytes
rules, 683 bytes
global
project
rest of the project list, cut
Gemini prompt, 1,000,000 bytes at the same width
room for about a megabyte of vocabulary
the whole OpenAI prompt would be 0.6 px here
A phone uses this same prompt when the desktop builds it for OpenAI.
  • Rulestranscription_system_prompt

    The compact rules for OpenAI take 622 bytes after XML escaping and 683 with their tags. The budget lets them use up to 720 bytes and keeps 280 for vocabulary.

  • Your vocabularypersonal_vocabulary_kb

    After the rules, a newline and 51 bytes of tags leave 265 bytes of text. The global list goes first, then the project list, both XML-escaped and cut at the limit, mid-word if need be. The split drawn here is an example.

  • Geminitranscription_prompt_max_bytes

    Gemini gets the full rules, 1,836 bytes with tags, and room for about a megabyte of vocabulary, so nothing you are likely to type is cut.

Voice settings hold a global vocabulary and a per-project vocabulary. Put terms you use everywhere in the global list and repository-specific names in the project list. They travel as an XML-escaped spelling reference inside the transcription prompt with an explicit rule never to insert them. On OpenAI they get 265 bytes of text after the rules and tags, global list first.

Error classes

Visible problemCheck
Microphone unavailableMake sure that the operating system gives HB Code access to the microphone. Dictation also needs a working audio input.
Provider not configuredMake sure that Settings → API Keys has a key for the dictation service. Make sure that Settings → Voice shows the saved dictation service.
Quota or rate limitOpenAI only, classified from its 429 code and never from free text. Quota codes such as insufficient_quota, credit_balance_exhausted, and the spend or usage limits link to billing. Any other 429, such as rate_limit_exceeded or slow_down, is a rate limit that passes with time. A Gemini failure reads as a key problem and blocks Gemini dictation for 5 minutes, or until you save Voice settings.
Recording too largeThe desktop refuses an OpenAI upload of more than 25,000,000 bytes. Record a shorter clip, or use Gemini.