Configuration

Configuration

The application reads ~/.config/microscopi.conf first; if absent, /etc/microscopi.conf. If neither exists, a default config is written to ~/.config/microscopi.conf on first run.

All values are optional — missing keys fall back to the built-in defaults shown below. Bad values are logged to stderr and the default is kept.

---

[video]

Key	Default	Description
video_backend	builtin	builtin = V4L2 h264_v4l2m2m + libavformat MKV muxer; ffmpeg = subprocess pipe
builtin_bitrate	5000000	H.264 encoding bitrate in bits/s (builtin backend only)
ffmpeg_command	(see below)	Shell command used when video_backend = ffmpeg. Substitutions: {width} {height} {fps} {output}. Raw YUV420 frames are piped to stdin.
video_dir	/home/microscopi/videos	Directory for recorded MKV files (created automatically)
stills_dir	/home/microscopi/stills	Directory for JPEG stills (created automatically)

Default ffmpeg command:

ffmpeg -f rawvideo -pix_fmt yuv420p -s {width}x{height} -r {fps} -i pipe:0 -c:v h264_v4l2m2m -b:v 5M -f matroska {output}

---

[camera]

Key	Default	Description
camera_index	0	Index of the camera to use (0 = first detected)
fps	30	Target frame rate
initial_ae_enabled	true	Autoexposure on at startup
initial_af_enabled	true	Autofocus on at startup
initial_aperture	0.0	Starting f-number; 0.0 = use camera default (shows f/-- in OSD)
crop_top	0	Pixels to trim from top of camera frame before display
crop_bottom	0	Pixels to trim from bottom
crop_left	0	Pixels to trim from left
crop_right	0	Pixels to trim from right

Crop values are in camera-frame pixels at the current camera resolution. The cropped region is scaled to fill the display. Use these to hide the physical mounting ring of the microscope.

---

[display]

Key	Default	Description
fallback_width	1280	Fallback resolution width if no EDID mode is detected
fallback_height	720	Fallback resolution height
show_crosshair	false	Whether the center guide overlay is shown at startup

---

[keys]

Rebind any action. Values are lowercase key names, optionally prefixed with shift+.

Supported key names: a–z, 0–9, up, down, left, right, space, escape, return, enter, tab, backspace.

q always acts as a secondary quit regardless of the quit binding.

Key	Default	Action
mode_cycle_fwd	t	Cycle exposure mode forward (P→A→S→M)
mode_cycle_back	shift+t	Cycle exposure mode backward
mode_p	p	Jump to Program mode
mode_a	a	Jump to Aperture priority mode
mode_s	s	Jump to Shutter priority mode
mode_m	m	Jump to Manual mode
iso_up	i	Step ISO up (exits AUTO on first press)
iso_down	shift+i	Step ISO down
shutter_up	shift+up	Step shutter speed faster (S/M modes only)
shutter_down	shift+down	Step shutter speed slower (S/M modes only)
focus_up	up	Step focus toward macro
focus_down	down	Step focus toward infinity
aperture_up	right	Aperture up (fixed-aperture lenses: cosmetic only)
aperture_down	left	Aperture down
toggle_af	shift+a	Toggle autofocus on/off
still	space	Capture a JPEG still
record	shift+r	Hold ≥ 500 ms to start/stop recording
crosshair	c	Toggle center guide overlay
quit	escape	Hold ≥ 5 s to quit (warning shown at 2.5 s)
help	h	Hold ≥ 3 s to show key binding overlay
cam_mode	v	Open/close camera mode selection list