Configuration¶

Each setting can be given as a command-line flag, an environment variable or a key in wudict.toml. The variable and the key have the same name.

Priority¶

Highest first: command-line flag, environment variable, wudict.toml, built-in default. The setup page shows which values a flag or variable overrides.

Config file¶

wudict reads the first of:

1. --config or CONFIG_PATH
2. wudict.toml next to the executable (portable mode)
3. ~/.wudict/wudict.toml
4. /etc/wudict/wudict.toml

The first wudict serve creates ~/.wudict/wudict.toml with every setting commented out. Each start prints the file in effect. An unknown key is reported at startup and on the setup page.

Portable mode¶

A wudict.toml next to the executable takes precedence over ~/.wudict/wudict.toml and receives the settings saved from the setup page. wudict never creates it.

Files¶

Log when there is no console: macOS ~/Library/Logs/wudict.log, Linux ~/.wudict/wudict.log, Windows %LOCALAPPDATA%\wudict\wudict.log, Android logcat.

wudict does not modify dictionary files. Only 🗑 Remove… and wudict rm delete them.

Everyday settings¶

DICT_DIR¶

Folders with dictionary files, subfolders included.

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

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

In wudict.toml several folders are an array; in the environment they are separated by : (; on Windows). A dictionary found in two folders is listed once, from the first. A missing folder is reported; the others are still read.

DB_DIR¶

The library: one library folder per indexed dictionary.

Must not be a DICT_DIR folder; wudict does not start if it is.

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. Requests from the network then need the access key (AUTH), and deleting a dictionary from another host also needs ALLOW_REMOTE_DELETE.

NO_BROWSER¶

Do not open a browser tab at startup.

AUTO_INDEX¶

Index each dictionary's headwords in the background on its first search.

off: dictionaries stay not indexed and are searched through their own format. The full-text index and media pack are per-dictionary choices either way.

The library

USE_CACHED¶

Also list indexed dictionaries whose dictionary files are gone.

The setup page sets it with Use these dictionaries.

ALLOW_REMOTE_DELETE¶

Allows clients on other hosts to delete dictionaries (🗑 Remove…, DELETE /api/library).

Requests from the loopback address can always delete.

VERBOSE¶

Log requests, dictionary opens, indexing and audio conversion.

Applies to every command. -v is --version.

Audio¶

SPEEX_BACKEND¶

Which decoder converts .spx audio to WAV.

internal needs a -cgo build; a -purego build always uses external.

SPEEXDEC¶

Path to the speexdec program.

The decoder in use is printed at startup.

Desktop integration¶

TRAY¶

Tray icon (Windows) or menu-bar icon (macOS).

Given both flags, --no-tray applies.

Tuning¶

These settings change speed and memory use. Only SEARCH_MEMORY changes search results.

INDEX_WORKERS¶

How many dictionaries are indexed at the same time.

Indexing one dictionary fully uses one CPU core and a few hundred bytes of memory per headword.

PREVIEW_MEMORY¶

Memory that dictionaries not yet indexed may hold open.

An open dictionary that is not indexed holds about 350 bytes per headword. Above the limit, the least recently used are closed. Indexed dictionaries are read from disk and do not count.

SEARCH_MEMORY¶

Memory one search may use to open dictionaries that are not indexed.

Past the limit, the remaining dictionaries are reported as not searched. Indexed dictionaries and a search of one dictionary are not limited.

MEMORY_LIMIT¶

A soft memory limit for the whole process.

Near the limit, the Go runtime collects garbage more often and wudict drops its caches; the process can still exceed it.

NO_COMPRESS¶

Store article text uncompressed.

The library becomes about 3 times larger; reads are slightly faster.

COMPRESSION¶

How hard article text is compressed when a dictionary is indexed.

• fast: the quickest indexing.
• small: the library is 1 % to 2 % smaller, and indexing takes up to 1.5 times as long.

The setting applies to dictionaries indexed after the change; dictionaries already indexed keep their size. On Android, fast compresses less than on a desktop, to use less battery. With NO_COMPRESS set to 1, article text is not compressed and COMPRESSION has no effect.

COMPRESSION = "small"

Lemmatization¶

With lemma data for a language, a search for an inflected form finds the lemma: knew → know, fuiste → ser, идет → идти. See Search → Inflected words.

Lemmatization needs the dictionary's language. wudict takes the first it finds of:

1. the language the dictionary declares: Lingvo DSL (#INDEX_LANGUAGE), Babylon, ZIM, wudict markdown;
2. a language code or English language name at the start of the file name: es-en-collins.mdx, spa-eng-oxford.mdx, spanish-collins.mdx;
3. a folder inside a dictionary folder whose whole name is a language code or English language name: es/, Spanish/;
4. a language named in the dictionary's title: Dahl's Russian Dictionary, (Ru-Ru);
5. otherwise English.

English dictionaries therefore need no renaming.

MORPH_CACHE¶

How many languages of lemma data stay in memory.

A language is loaded on the first search that needs it; above the limit the least recently used is unloaded. A loaded language uses 1 MB (Persian) to 90 MB (Slovak); English 7 MB. wudict lemmas list shows each.

LEMMA_DIR¶

The folder of installed lemma data. English is built in.

Install languages with Lemmatization… (dictionary panel → folder summary) or wudict lemmas download. The folder is read at startup and after each install or removal on the Lemmatization page; a file added by hand or with wudict lemmas is read after a restart. The folder also holds .catalogue.json, the list of languages the Lemmatization page read last, which it shows before the network answers.

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

LEMMA_URL¶

The catalogue lemma data is installed from.

Used by wudict lemmas and the Lemmatization page. A local path installs without a network, e.g. from a copy of the catalogue repository:

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

Each file is checked against the SHA-256 digest in the catalogue.

The lemma data is published under the ODbL and derived from michmech/lemmatization-lists; see ATTRIBUTION.txt in the catalogue repository.

Import¶

Settings for installing dictionaries from a file or a link on the setup page.

IMPORT_KEEP¶

What happens to an archive after its dictionaries are installed.

A failed import always keeps the archive.

IMPORT_URL_HOSTS¶

The hosts an archive may be downloaded from. A host matches itself and its subdomains.

IMPORT_URL_HOSTS = ["example.org", "cloud.example.net"]

In the environment the hosts are comma-separated.

Set it when the server listens on the network: otherwise a client there can make this machine download from any address it can reach.

IMPORT_INSECURE¶

Also allow plain http:// links and hosts on the local network.

Access¶

AUTH¶

Whether a request must carry the access key.

The key is a random string stored in ~/.wudict/token, readable only by your user. wudict token prints a link that carries it (http://<address>:<port>/?k=<key>); opening the link once stores the key in that browser as a cookie. Scripts send Authorization: Bearer <key>. wudict token -rotate replaces the key, and every browser and script holding the old one must be given the new link.

The three endpoints open to browser extensions (/api/dicts, /api/search, /res/) do not need the key.

off on a network address gives anyone who can reach the port your library, your settings and your folder names.

AUTH_TOKEN¶

The access key itself, when it comes from elsewhere: a password manager, a container secret. Overrides ~/.wudict/token and is never written to it.

TRUSTED_HOSTS¶

Host names the server answers to, in addition to localhost and a host name set as SERVER_IP. Requests to an IP address are always accepted.

TRUSTED_HOSTS = ["wudict.lan"]

A request naming any other host is refused with 421 Misdirected Request. This blocks DNS rebinding: a web page that points its own domain at your machine cannot read the server through it. Set it for a reverse proxy or a host name you gave the machine; "*" turns the check off.

BROWSER_EXTENSIONS¶

Browser extensions allowed to call the server.

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

An extension can call three read-only endpoints: /api/dicts, /api/search and /res/. Firefox assigns a new moz-extension:// origin to each installation, so a list cannot name a Firefox extension in advance.

WEB_ORIGINS¶

Web page origins allowed to call the server from JavaScript.

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

A listed origin can call the same three endpoints as an extension.

An origin is a scheme (http or https), a host and a port, without a path: http://localhost:3000, not http://localhost:3000/app or localhost:3000. A different scheme or port is a different origin. A default port may be omitted: https://x.example equals https://x.example:443.

"*" allows every origin: any page you visit can read your dictionaries while the server runs. Use it only while developing; the startup output shows it:

  web origins   any website may read your dictionaries (WEB_ORIGINS = "*")

Programs outside a browser (curl, scripts, applications) are not subject to this setting. What limits them is SERVER_IP and the access key (AUTH).

Safety limits¶

These settings bound what one damaged or hostile file can make wudict use: memory for a block it unpacks, disk for an import. A real dictionary stays far below each default.

Change a limit only when a dictionary you trust does not open and the message names the limit, for example:

cluster 0: the unpacked cluster exceeds the MAX_ZIM_CLUSTER limit of 256MB

A higher limit lets a damaged or hostile file use that much memory or disk. A limit below what your dictionaries need stops them from opening. A value that is outside a key's range is moved to the nearest end of it, and a value that is not a positive size leaves the default in effect; the startup output names the key in either case. The ranges keep a typo from disabling a guard or stopping ordinary dictionaries from opening.

Each key is also a flag of wudict serve and wudict ingest: MAX_ZIM_CLUSTER is --max-zim-cluster.

MAX_ZIM_CLUSTER¶

One ZIM cluster, unpacked.

MAX_SLOB_BIN¶

One Aard 2 (.slob) bin, unpacked.

MAX_MDICT_BLOCK¶

One MDict (.mdx, .mdd) block, unpacked.

MAX_STARDICT_INDEX¶

A compressed StarDict index (.idx.gz), unpacked; 16 times the size of the file is always allowed.

MAX_BGL_BLOCK¶

One Babylon (.bgl) block.

MAX_LEMMA_SIZE¶

One lemma data file, unpacked.

MAX_IMPORT_SIZE¶

One dictionary taken out of an archive, or downloaded.

MAX_IMPORT_RATIO¶

How many times its packed size one file in an archive may unpack to.

MAX_UPLOAD_SIZE¶

One archive sent to the server from a browser or the app.

CONFIG_PATH¶

The config file to read, instead of the search order under Config file.

A flag and an environment variable only; not a key in wudict.toml.

Example¶

DICT_DIR      = ["~/Dictionaries", "/data/dicts"]
SERVER_IP     = "0.0.0.0"          # listen on the network: AUTH applies
SERVER_PORT   = "9000"
NO_BROWSER    = "1"
TRUSTED_HOSTS = ["wudict.lan"]
WEB_ORIGINS   = ["http://localhost:3000"]