Custom dictionary, corrections and post-processing

Set it up

1. 1

   Open the Custom Dictionary page

   Open Settings from the tray menu and choose Custom Dictionary in the sidebar.

2. 2

   Add custom terms

   Switch on Use custom terms, type a name or term into the Add a term field and click Add term. Or point Terms file at an existing UTF-8 file.

3. 3

   Add transcript corrections

   Under Transcript corrections, enter what the engine writes (for example super base) and what you want instead (for example Supabase), then click Add correction.

4. 4

   Optionally set a post-processing script

   Open the Post-Processing page, enter the path to an executable script in Script Path or click Browse…, and leave the field empty to turn it off.

5. 5

   Dictate

   Both dictionary files are re-read before each completed segment, so changes apply to your next dictation without a restart.

Custom terms file

Terms live in ~/.config/vocalinux/dictionary.txt by default: UTF-8, one term per line. Blank lines and lines starting with # are skipped, and duplicates are ignored regardless of case. The plain line format is deliberate, so accessibility tools and scripts can maintain the same file.

# ~/.config/vocalinux/dictionary.txt
Supabase
Kubernetes
PipeWire
Okonkwo

Limits and engine support

• Bias applies to Whisper, whisper.cpp and Faster Whisper. On whisper.cpp the terms are appended after anything in Advanced → Initial Prompt, so your own prompt is kept.
• Up to 200 terms are used by default (dictionary.max_words in config.json), and the combined prompt stops at 2,000 characters.
• The editor rejects a single term longer than 200 characters. A file larger than 1 MiB is read only up to its last complete line inside that limit.

Session-only terms file

To try a different list without touching saved settings, start Vocalinux with:

user@linux:~$ vocalinux --dictionary-file /path/to/dictionary.txt

The custom terms controls are disabled for that session. Transcript corrections still apply.

Transcript corrections file

Corrections are stored separately in ~/.config/vocalinux/custom-dictionary-corrections.json, always in the config directory, whatever terms file you use. The format is versioned:

{
  "version": 1,
  "corrections": [
    { "heard": "super base", "replacement": "Supabase" },
    { "heard": "pipe wire", "replacement": "PipeWire" }
  ]
}

• heard matches case-insensitively, only as a whole word or phrase.
• replacement is inserted with exactly the spelling you typed.
• Longer phrases win over shorter ones. For a repeated heard phrase, the first wins.
• Up to 500 corrections, each side up to 500 characters.
• Settings refuses to edit a hand-written file with extra fields or entries it would have to change. Fix the JSON, or edit it only by hand.

The post-processing script hook

The path is saved as post_processing.script_path (empty means off). For each completed segment, Vocalinux runs the file like this:

Example: uppercase everything

The example from the Vocalinux user guide. Make it executable with chmod +x before setting the path.

#!/bin/bash
tr '[:lower:]' '[:upper:]'

Example: typographic apostrophes in Python

Reads everything from stdin and writes it back without adding a newline. Any exception exits non-zero, so Vocalinux falls back to the original text.

#!/usr/bin/env python3
import sys

text = sys.stdin.read()
sys.stdout.write(text.replace("'", "\u2019"))

Before pointing Vocalinux at a script, pipe a sample sentence into it from a terminal and check that it prints the text back. Output is not written to the log, but anything your script does with the text (files, network calls) is up to the script.

FAQ