Services

Services

• Audio
• Brightness
• Night Light
• System Monitor
• Weather
• Idle
• Notifications

---

Audio

[audio]
enable_overdrive     = false  # allow volume sliders above 100% (up to 150%)
enable_sounds        = false  # master toggle for UI sounds
sound_volume         = 0.5    # global sound volume (0.0 - 1.0)
volume_change_sound  = ""     # empty = bundled default sounds/volume-change.wav
notification_sound   = ""     # empty = bundled default sounds/notification.wav

• enable_overdrive = false clamps Control Center output/microphone sliders to 100%; true allows up to 150%.
• enable_sounds = false disables all UI sound playback.
• sound_volume is the global playback gain for all UI sounds.
• volume_change_sound and notification_sound accept absolute paths, ~-prefixed home paths, or asset-relative paths.

---

Brightness

Brightness control uses the kernel backlight interface by default. ddcutil support is opt-in for external monitors that expose DDC/CI brightness.

[brightness]
enable_ddcutil = false
ignore_mmids   = []   # e.g. ["ACI-ROG_PG279Q-10220"] — skip in all ddcutil commands

[brightness.monitor.eDP-1]
backend = "backlight"   # auto | none | backlight | ddcutil

[brightness.monitor.DP-1]
backend = "ddcutil"

Notes:

• enable_ddcutil = true only enables DDC/CI discovery — it does not force every monitor to ddcutil.
• ignore_mmids passes --ignore-mmid to every ddcutil invocation. Run ddcutil --verbose detect to find monitor model id strings.
• Per-monitor overrides use the same connector/description matching rules as bar monitor overrides.
• backend = "auto" prefers kernel backlight when available and falls back to ddcutil.
• backend = "none" hides brightness control for the matched display.
• ddcutil is treated as best-effort — repeated DDC failures cool down that display to avoid hammering the monitor bus.

IPC

noctalia msg set-brightness 65           # current display
noctalia msg set-brightness DP-1 0.65
noctalia msg set-brightness * 40%        # all displays

noctalia msg raise-brightness            # current display, default 5% step
noctalia msg raise-brightness DP-1 10
noctalia msg lower-brightness * 5%       # all displays

Targets: current, all/*, a display id (eDP-1, DP-1), or a monitor selector token (same matching rules as monitor overrides). current resolves from the active/focused output, falling back to the last interactive output.

Values and steps accept normalized (0.0–1.0) or percentage-style (65, 65%, 5%) values. raise-brightness / lower-brightness target current with a 5% step when no arguments are given.

---

Night Light

Applies color temperature shifts using the Wayland wlr-gamma-control protocol. Supported on compositors that implement gamma control (Hyprland, Sway, etc.).

[nightlight]
enabled              = false
force                = false   # force night mode from startup
use_weather_location = true    # prefer weather coordinates; requires weather auto_locate or address

temperature_day   = 6500       # Kelvin (must be > temperature_night by at least 100)
temperature_night = 4000       # Kelvin

# Option A: explicit schedule (used when weather location is off or unavailable)
start_time = "20:30"           # HH:MM — sunset / night starts
stop_time  = "07:30"           # HH:MM — sunrise / day starts

# Option B: manual geolocation schedule (fallback when start/stop are missing)
# latitude  = 52.5200
# longitude = 13.4050

When use_weather_location = true, Night Light uses WeatherService coordinates for sunrise/sunset once weather has a configured location ([weather].auto_locate = true or [weather].address). While weather coordinates are unavailable, and whenever use_weather_location = false, Night Light uses start_time + stop_time, then falls back to explicit latitude/longitude. If only one coordinate is provided, Night Light refuses to start.

IPC

noctalia msg enable-nightlight
noctalia msg disable-nightlight
noctalia msg toggle-nightlight
noctalia msg toggle-force-nightlight

enable-nightlight / disable-nightlight / toggle-nightlight control schedule enable state. toggle-force-nightlight toggles forced-on mode regardless of schedule.

---

System Monitor

[system.monitor]
enabled = true  # sample CPU, memory, network, load, temperature, and disk statistics

When disabled, Noctalia keeps system-monitor UI available but stops the background sampling thread. System-monitor widgets and the Control Center System tab show unavailable values until the setting is enabled again.

---

Weather

[weather]
enabled         = false
auto_locate     = false         # resolve coordinates from IP address when true
address         = "Toronto, ON" # geocoded when auto_locate = false
refresh_minutes = 30
unit            = "metric"      # metric | imperial

When auto_locate = false, Noctalia geocodes address to latitude/longitude and fetches current weather plus a 6-day forecast. When auto_locate = true, the address field is ignored and location is resolved via IP.

Enabling weather adds a Weather tab to the control center. The bar weather widget type also requires weather to be enabled.

---

Idle

Idle behaviors are named entries under [idle.behavior.*]. When no config.toml exists, Noctalia uses a built-in default with the lock behavior disabled.

[idle.behavior.lock]
timeout = 660
command = "noctalia:screen-lock"
enabled = false             # explicitly disabled in the default config

[idle.behavior.screen-off]
timeout = 600
command = "noctalia:dpms-off"
resume_command = "noctalia:dpms-on"

[idle.behavior.custom]
timeout = 48
command = "notify-send 'Idle' 'Going idle'"
resume_command = "notify-send 'Idle' 'Back from idle'"

Setting	Type	Default	Description
enabled	bool	true	Enable or disable this behavior
timeout	int	0	Seconds before the behavior triggers; 0 disables this behavior
command	string	""	Shell command or noctalia: IPC subcommand
resume_command	string	""	Shell command or noctalia: IPC subcommand to run when activity resumes after this behavior triggered

For screen-off behaviors, pair command = "noctalia:dpms-off" with resume_command = "noctalia:dpms-on". Noctalia also applies this dpms-on resume action automatically for older configs that use exactly noctalia:dpms-off without an explicit resume_command, so user input does not leave monitors powered off.

noctalia: commands in idle

The noctalia: prefix runs the rest of the string through the IPC command registry — the same as noctalia msg <subcommand>. Examples:

noctalia:screen-lock
noctalia:dpms-off
noctalia:dpms-on
noctalia:caffeine-enable
noctalia:caffeine-disable
noctalia:caffeine-toggle
noctalia:panel-toggle launcher
noctalia:panel-toggle session
noctalia:panel-toggle clipboard
noctalia:panel-toggle wallpaper
noctalia:panel-toggle control-center
noctalia:media previous
noctalia:media toggle
noctalia:media next

Idle behavior uses the Wayland ext_idle_notifier_v1 protocol and respects active idle inhibitors.

---

Notifications

[notification]
enable_daemon      = true   # when false, don't claim org.freedesktop.Notifications; internal notifications still work
position           = "top_right" # top_right | top_left | top_center | bottom_right | bottom_left | bottom_center
layer              = "top"  # top | overlay
background_opacity = 0.97   # toast card background alpha; lower values let compositor blur show through
monitors           = []     # empty = all displays; otherwise connector/description selectors (e.g. ["eDP-1", "DP-1"])

• layer = "top" keeps toasts above normal app windows while respecting overlay UI from other components.
• layer = "overlay" forces toasts onto the overlay layer so they render above other layer-shell surfaces.
• monitors = [] shows notifications on all displays (default).
• When monitors is non-empty, toasts are only created on matching outputs.
• Selector matching follows monitor override rules: exact connector name (eDP-1) or a word-boundary token in output description.