By Hakim Team6 min read

Getting names right: custom vocabulary for Arabic speech-to-text

How to use realtime vocabulary for brands, names and short words that are easy to mishear, and the mistakes that quietly stop it working.

EngineeringProduct

Every transcription system has words it gets wrong for you in particular: your product name, your customers' names, the acronym your support team says a hundred times a day. In Arabic, with dialects and frequent switching into English, that list is longer. Custom vocabulary is how you tell Hakim about those words before the call starts.

The shape of it

Vocabulary goes in the first session.update of a realtime speech-to-text session:

ws.send(
  JSON.stringify({
    type: 'session.update',
    session: {
      model: 'hakim-arab-v2',
      language: 'ar',
      trim_leading_silence: true,
      vocabulary: {
        terms: ['حكيم', 'Hakim', 'Saree', 'GPU'],
        notes: 'A product demo call about the Hakim realtime Arabic speech API.',
        hints: [{ key: 'topic', value: 'sales demo' }],
      },
    },
  }),
);
  • terms lists the rare words, names, acronyms and brands to favour.
  • notes is a short paragraph describing what the call is about.
  • hints carries structured { key, value } context such as speaker roles or a topic.

Every field is optional. All of them share one budget of 10,000 characters.

Three patterns that work

Names, brands and acronyms: terms alone. This is the common case and needs nothing else. If people say a name in both scripts, list both, as with حكيم and Hakim above.

Short everyday words that get misheard: terms plus notes. A short common word is hard to bias with a list alone, because the model has strong expectations about it. A sentence in notes that describes the situation gives it the context it needs. For example, on a support call where the customer confirms their identity with the single word "speaking", put speaking in terms and explain that moment in notes.

Mixed Arabic and English calls: set the language. Send language, or language_hints for mixed speech, instead of leaving it on auto. Vocabulary is applied far more reliably when the language is known.

Four mistakes that quietly stop it working

  1. Sending it late. Vocabulary is handed to the recognizer when the stream starts. A change sent after audio has begun is not applied. To change it, open a new session and send it again there.
  2. Leaving the language on auto. See above.
  3. Long silence at the start of the stream. Biasing becomes unreliable when a stream opens with half a second or more of silence or quiet background. Start sending when speech starts, or set trim_leading_silence: true and we drop the lead for you. Billing is unchanged.
  4. A misnamed field. Only vocabulary is read. Fields named context or custom_vocabulary are ignored without an error, which looks exactly like vocabulary that does not work.

Two more things worth knowing: keep the list short and specific, because a handful of words that matter beats a long glossary, and vocabulary applies to realtime sessions only, not the batch transcription endpoint.

Pauses are fine

A session with no incoming audio stays open for up to five minutes, and the vocabulary keeps applying when the speaker comes back. You do not need to resend it after a long hold.

The streaming guide has the full field limits and a worked example.

Read next