Configuration Reference

Configuration Reference

Lenzu reads lenzu_config.json from the current working directory at startup. Missing fields fall back to defaults — you only need to include the fields you want to change.

The config file is not hot-reloaded; restart Lenzu after editing it.

---

Lens window

Field	Type	Default	Description
lens_size	int	400	Width and height of the lens capture square (pixels).
ui_panel_height	int	130	Height of the status/result panel below the lens (pixels).
font_size	float	13.0	Font size for OCR result text in the lens panel (pt).
hud_color_hex	string	"#00FFCC"	Hex color for the lens border and status text.
result_display_secs	int	5	Seconds to keep the lens visible after a result arrives. Set to 0 to hide immediately when Shift is released.

---

HUD overlay

Field	Type	Default	Description
overlay_enabled	bool	true	Whether to spawn the Electron HUD overlay at startup.
overlay_udp_port	int	7331	UDP port the HUD listens on. Change if 7331 is in use.
overlay_render_mode	string	"furigana"	What the HUD displays. Values: "original", "english", "furigana", "romaji", "all", "debug".

---

Translation

Field	Type	Default	Description
translate_src	string	"jpn"	Source language (ISO 639-3).
translate_dest	string	"eng"	Target language (ISO 639-3).
translate_extra_prompt	string	furigana/romaji instruction	Appended to the full-image OCR prompt. Leave empty for non-Japanese sources.
show_furigana	bool	true	Include furigana in results.
show_romaji	bool	true	Include romaji in results.

---

LLM backends

Lenzu tries backends in order: primary (local ollama) → free remote → paid remote. Each step only fires if the previous one times out or fails.

Primary (local ollama)

Field	Type	Default	Description
llm_api_endpoint	string	http://localhost:11434/v1/chat/completions	Ollama endpoint.
llm_default_model	string	"glm-ocr"	Vision model for OCR. Must be pulled in ollama first.
local_timeout_secs	int	3	Seconds before failing over to the next backend.
local_fallback_models	array	["gemma4:e2b"]	Additional local models tried after the primary.
primary_max_dimension	int	0	Resize images to this longest edge before sending. 0 = no resize.
primary_num_ctx	int|null	null	Ollama KV-cache context size. null = ollama default (4096). Reduce on low-VRAM cards.

Free remote (OpenRouter, no key required)

Field	Type	Default	Description
free_remote_endpoint	string	OpenRouter	URL for the free-tier remote backend.
free_remote_model	string	"openrouter/free"	Model on the free tier (30 req/day anonymous, 1000/day with key).
remote_timeout_secs	int	15	Timeout for the free remote tier.

Paid remote (OpenRouter, requires OPENROUTER_API_KEY)

Field	Type	Default	Description
fallback_llm_api_endpoint	string	OpenRouter	URL for the paid fallback backend.
fallback_llm_model	string	"@preset/free-dev"	Primary paid model.
extra_fallback_models	array	["google/gemma-4-31b-it:free"]	Additional paid models tried in order.
fallback_max_dimension	int	800	Resize images before paid remote calls.
paid_remote_timeout_secs	int	60	Timeout for paid remote calls.

---

Text enrichment (post local-OCR)

After manga-ocr-rs succeeds locally, a text-only LLM enriches the result with furigana, romaji, and translation — without sending an image.

Field	Type	Default	Description
enrichment_enabled	bool	true	Enable text enrichment after local OCR.
enrichment_model	string|null	"qwen2.5:3b"	Ollama text-only model for enrichment. Use a non-vision model — vision models are slow for text-only tasks.
enrichment_timeout_secs	int	30	Timeout for enrichment requests (longer than OCR timeout because ollama may need to swap models).
enrichment_prompt	string|null	null	Override the entire enrichment prompt. null = use built-in (Japanese furigana/romaji/english). Use {src} and {dest} as placeholders.
furigana_only	bool	false	Skip LLM enrichment entirely — only MeCab furigana annotations added (~5 ms). Overrides enrichment_enabled. Also available as --furigana_only CLI flag.
mecab_overwrite	bool	true	Overwrite LLM furigana with MeCab's dictionary-based readings. MeCab comparison always runs for logging; this flag controls whether it overwrites. Also --nomecab_overwrite CLI flag.

---

DBNet text detection

DBNet detects text bounding boxes in the lens image so each bubble/region is sent as a separate OCR crop instead of the full lens image.

Field	Type	Default	Description
text_detection_model	string|null	"assets/..."	Path to the DBNet ONNX file. null disables detection. Resolved against ~/.local/share/lenzu/models/ if the relative path doesn't exist.
text_detection_threshold	float	0.2	DBNet confidence threshold. Lower = more detections, more false positives.
text_detection_dilation	int	16	Morphological dilation radius (px at 640×640). Merges nearby character blobs.
text_detection_pad_x	int	32	Horizontal padding added to each bounding box (original-image px).
text_detection_pad_y	int	32	Vertical padding added to each bounding box (original-image px).
text_detection_oversample_factor	float	2.0	Capture size multiplier: max(lens_size × factor, 640). Higher = sharper input for DBNet.
text_detection_max_capture_size	int	1600	Hard cap on the oversampled capture dimension (px).
text_detection_crop_padding	int	16	Padding added around each cropped text region before OCR (px).
detection_scale_table	array	see below	Per-image-size DBNet params. Overrides the global threshold/dilation/padding for specific image size ranges.

detection_scale_table format

"detection_scale_table": [
  { "max_dimension": 800,  "dilation": 16, "threshold": 0.20, "pad_x": 32, "pad_y": 32 },
  { "max_dimension": 1280, "dilation": 10, "threshold": 0.25, "pad_x": 32, "pad_y": 32 },
  { "max_dimension": 1920, "dilation":  6, "threshold": 0.35, "pad_x": 32, "pad_y": 32 },
  { "max_dimension": 2560, "dilation":  3, "threshold": 0.45, "pad_x": 40, "pad_y": 40 },
  { "max_dimension": 4294967295, "dilation": 0, "threshold": 0.50, "pad_x": 48, "pad_y": 48 }
]

Entries must be sorted ascending by max_dimension. The first entry whose max_dimension ≥ the image's longest edge is used; the last entry is the catch-all.

---

Token spend warnings

HUD color changes when session-total paid API tokens cross these thresholds.

Field	Type	Default	Description
token_warning_threshold	int	100000	Paid tokens before HUD turns orange (~$0.01–0.04 depending on model). 0 = disable.
token_critical_threshold	int	500000	Paid tokens before HUD turns red (~$0.05–0.20). 0 = disable.

---

Local OCR quality

Field	Type	Default	Description
low_conf_max_chars	int	64	Max characters kept from a low-confidence (< 71%) manga-ocr-rs result. Truncates garbage rather than forwarding it to the LLM.

---

Minimal example config

{
  "lens_size": 400,
  "translate_src": "jpn",
  "translate_dest": "eng",
  "llm_default_model": "glm-ocr",
  "overlay_render_mode": "furigana"
}

All other fields use defaults.