Configuration¶

Every setting has up to three spellings: a command-line flag, an environment variable, and a key in wudict.toml. The name is the same in the environment and in the file.

Priority¶

Flag beats environment. Environment beats the config file. The file beats the built-in default.

This is the answer to "I edited wudict.toml and nothing changed": something above it sets the same value. wuDict knows where each value came from, and the setup page refuses to pretend that saving to the file will take effect.

Where the config file lives¶

wuDict reads the first file it finds.

1. the --config flag, or the CONFIG_PATH environment variable
2. wudict.toml next to the executable - see portable mode
3. ~/.wudict/wudict.toml
4. /etc/wudict/wudict.toml

The first serve run creates ~/.wudict/wudict.toml, fully commented. Every start prints the file in effect.

~/.wudict/state.json holds your dictionary order and your on/off switches. That file is written by the app, not by you.

Every file wuDict owns¶

Your dictionary files are not in this list. wuDict reads them where they are and leaves them alone until you ask it not to — the only thing that touches them is Remove, which deletes what it says it deletes. DB_DIR moves the library; the rest of the table follows the config file.

Portable mode¶

Put a wudict.toml next to the executable. It then wins over every user location, and settings are saved back to it. Use this for a USB stick or a self-contained folder.

wuDict never creates that file by itself. An executable's folder usually belongs to someone else, such as ~/go/bin or /opt/homebrew/bin.

Everyday settings¶

DICT_DIR¶

Folders holding your dictionary files, scanned including every subfolder.

wudict --dict-dir ~/Dictionaries --dict-dir /Volumes/Ext/Dicts
DICT_DIR="~/Dictionaries:/Volumes/Ext/Dicts" wudict     # ";" on Windows

DICT_DIR = ["~/Dictionaries", "/Volumes/Ext/Dicts"]

The config file spells several folders as an array. The : and ; separators belong to the environment only, where they follow the convention of PATH.

A dictionary found in two folders is listed once, and the first folder wins. A missing folder is reported, and the others still work.

DB_DIR¶

The library folder: one subfolder per prepared dictionary.

It must not be the same folder as DICT_DIR. wuDict refuses to start when they are the same.

SERVER_IP and SERVER_PORT¶

127.0.0.1 is the loopback address, reachable from your machine only. Set 0.0.0.0 to accept connections from your network. Only do that on a network you trust; wuDict has no login. Deleting a dictionary is the one thing those visitors cannot do — ALLOW_REMOTE_DELETE is off unless you turn it on.

NO_BROWSER¶

Do not open a browser tab at startup.

AUTO_INDEX¶

Prepare each dictionary in the background on its first search.

off leaves every dictionary in preview, searched through its own format. Contains, full-text and media stay per-dictionary choices either way.

What preparation does

USE_CACHED¶

Also list prepared dictionaries whose original files are gone.

The setup page sets this when you click Use these dictionaries.

ALLOW_REMOTE_DELETE¶

Whether a browser on another machine may delete a dictionary.

Deleting from the machine running wuDict is always allowed — it is your library and your disk, and 🗑 Remove… in the ☰ panel is how you do it. This setting is only about the other case: a browser somewhere else on the network.

With SERVER_IP set to 0.0.0.0 anyone who can reach the port can use the page. Set ALLOW_REMOTE_DELETE = "1" if you want to allow LAN users to delete dictionaries.

VERBOSE¶

Log requests, dictionary opens, preparation and audio conversion.

--verbose works for every command, not only serve. The short -v means --version.

Audio¶

SPEEX_BACKEND¶

Which decoder converts .spx audio to WAV.

internal needs a -cgo build. A -purego build always uses the external program.

SPEEXDEC¶

Path to the external speexdec program.

wuDict prints which decoder it resolved at startup, or an install hint when it found none.

Desktop integration¶

TRAY¶

Show a tray icon on Windows, or a menu-bar icon on macOS.

Given both flags, --no-tray wins. Between two contradictory instructions, the one that changes nothing about the process is the safe reading.

Tuning¶

These change speed and memory, never results - with one marked exception. The defaults are right for a desktop. Open a section only if you want to change it.

INDEX_WORKERS¶

How many dictionaries may be prepared at once.

PREVIEW_MEMORY¶

How much RAM dictionaries that are not yet prepared may hold open.

SEARCH_MEMORY¶

How much RAM one search may claim by opening dictionaries that are not yet prepared.

MEMORY_LIMIT¶

A soft ceiling for the whole process.

NO_COMPRESS¶

Store article text plain instead of compressed.

Lemmatization¶

When you enable lemmatization for a language wuDict will be able to find inflected forms, for example search for knew will find know, fuiste will find ser, идет will find идти.

MORPH_CACHE¶

How many languages of lemma data stay in memory.

LEMMA_DIR¶

The folder where lemmatization files are stored (except English which is embedded OOTB into the binary).

kot kota    kotu    kotem   koty    kotów
pies    psa psu psem    psy psów

LEMMA_URL¶

By default wuDict installs lemmatization languages from https://github.com/wuweidict/lemmas.

wudict lemmas download -url /media/usb/lemmas/manifest.json ru pl

Access¶

BROWSER_EXTENSIONS¶

Configures browser extensions that can access the wuDict server.

BROWSER_EXTENSIONS = ["chrome-extension://abcdefghijklmnopabcdefghijklmnop"]

An extension can access three read-only endpoints: /api/dicts, /api/search and /res/. It cannot access wuDicts settings, and wuDict internal endpoints.

Firefox generates a new moz-extension:// origin per installation, so there is no stable origin to list there.

WEB_ORIGINS¶

Which web pages may look words up in this server with JavaScript.

WEB_ORIGINS = ["http://localhost:3000", "https://notes.example.com"]

Whitelisted domain only read only operations are allowed - /api/dicts, /api/search and /res/. No access to settings, library internals, or operations that modify state.

Writing an origin¶

An origin is a scheme, a host and a port. Nothing else.

WEB_ORIGINS = ["http://localhost:3000"]     # correct
WEB_ORIGINS = ["http://localhost:3000/app"] # wrong: a path is not part of an origin
WEB_ORIGINS = ["localhost:3000"]            # wrong: no scheme

http:// and https:// are the only schemes accepted. A different port is a different origin, and so is a different scheme: http://localhost:3000 does not allow https://localhost:3000. The default port may be written or left out - https://x.example and https://x.example:443 mean the same thing, because that is what the browser means by them.

The wildcard¶

WEB_ORIGINS = "*"

With * every site you visit may read every dictionary you have, when wuDict serveris running. That is useful while you are developing a page and know what is open in the browser. Only use it if know what you are doing.

The server prints the setting on every start:

  address       http://127.0.0.1:6888
  web origins   any website may read your dictionaries (WEB_ORIGINS = "*")

What this does not cover¶

Anything that is not a browser page ignores all of it. curl, a Node or Python script, an Electron main process, a native app: none of them send an Origin header, none of them enforce CORS, and all of them can already reach every endpoint. CORS is a rule browsers apply to pages, not a lock on the server. The lock is SERVER_IP, which keeps the server on the loopback address.

CONFIG_PATH¶

The config file to read, instead of searching the four locations.

This one exists as a flag and an environment variable only.

A complete example¶

DICT_DIR    = ["/data/dicts", "~/Dictionaries"]
DB_DIR      = "~/.wudict/db"
SERVER_IP   = "127.0.0.1"
SERVER_PORT = "9000"
NO_BROWSER  = "1"
AUTO_INDEX  = "on"
ALLOW_REMOTE_DELETE = "0"
WEB_ORIGINS = ["http://localhost:3000"]