# evclack configuration

#

# evclack watches your keyboards and plays a sample on every press of a

# configured key. It does not grab anything, does not remap anything, and

# creates no virtual device: the keys reach the rest of the system exactly

# as they always did, and evclack only listens.

#

# Copy this file to ~/.config/evclack/config.yaml and edit it there; the

# daemon prefers that path over the installed copy in /usr/share.

#

# Edits apply IMMEDIATELY: the daemon watches this file and reloads itself

# when you save. `systemctl --user reload evclack` (SIGHUP) does the same on

# demand. Keys, samples, gains, devices and latency can all be changed on a

# running daemon.

#

# A config that does not parse, or that is rejected (a key bound twice, more

# than 24 distinct sounds), is reported and IGNORED - the daemon keeps

# running the last good one rather than dying on a typo.

#

# The one change that still needs a restart is creating

# ~/.config/evclack/config.yaml for the first time: until it exists the

# daemon is watching the fallback copy's directory instead.

# systemctl --user restart evclack

# Keyboards to listen to. OPTIONAL. When omitted (or set to the scalar

# "auto"), every keyboard-shaped device that carries EVERY bound key is

# opened: real keyboards only, no mice or touchpads.

#

# Virtual keyboards ARE included, deliberately. Remappers (keyd, doubletap,

# an on-screen keyboard) grab the physical board exclusively, so the real

# keystrokes exist only on the uinput device they emit - filtering those out

# would leave evclack silent on exactly the setups most likely to want it.

# There is nothing to double up either: a grabbed node yields no events to a

# passive reader, and evclack emits none of its own.

#

# To pin specific keyboards instead, list them explicitly. Use the stable

# /dev/input/by-id/* paths so the entries survive a replug

# (ls /dev/input/by-id/ and pick the *-event-kbd entry for your keyboard).

# Either way, hotplug is handled: unplugged keyboards are dropped and

# reopened when they come back.

#

# devices:

# - /dev/input/by-id/CHANGE-ME-event-kbd

# Which keys make a sound, and what they play. REQUIRED - a key that is not

# listed here is silent.

#

# Each entry is either a bare key code, or a mapping with a per-key `sample`

# and/or `gain`. Codes can be symbolic ("KEY_Z") or numeric (44); see

# /usr/include/linux/input-event-codes.h for the full list.

#

# Anything an entry leaves out comes from the `audio` block below, so the

# common case - a handful of keys, one sound - is just a list of names. The

# two blocks may appear in either order.

#

# Bindings that name the same file AND the same gain share one loaded

# sample, so pointing ten keys at one hitsound decodes it once. That is the

# only real ceiling here: 24 DISTINCT (file, gain) pairs. The number of

# bound KEYS is not limited.

keys:

- KEY_Z

- KEY_X

# - {key: KEY_C, sample: /usr/share/evclack/clack.wav}

# - {key: KEY_V, gain: 0.6}

# The sound.

#

# `sample` is the default sample and `gain` (linear, 1.0 = unity) the

# default volume, used by every binding that does not override them.

#

# Leave `sample` out entirely and the installed default click is used,

# whatever prefix evclack was built with - which is why it is commented out

# below rather than spelled as a path.

#

# Point samples at any format libsndfile reads - WAV (any bit depth,

# including float and WAVE_FORMAT_EXTENSIBLE), FLAC, OGG/Vorbis, Opus and

# MP3 - at any sample rate and channel count. An osu! skin's hitsounds work

# as they ship, with no transcoding. Everything is decoded and resampled

# once at startup so it can all share one output.

#

# EVERY sound overlaps rather than cutting off the one before it, including

# two presses of the SAME key. evclack opens a single output node and mixes

# internally: each press takes its own voice from a pool of 32 and plays out

# to its end. This matters most at speed - the shipped click is 125ms and a

# 300 BPM stream is one tap every 50ms, so anything that restarted playback

# would clip every note of a burst to 40% and thin out the sound exactly

# when you are listening hardest.

#

# `latency` is the output quantum requested from PipeWire, in frames at

# 48kHz. Without it the node inherits the graph quantum - 1024 on a stock

# PipeWire, so a click landed anywhere in a 21ms window and a burst came out

# unevenly spaced. 256 frames is 5.3ms, and a trigger is placed at the frame

# it actually fell on within that buffer, so the spacing between two taps

# survives to the speaker.

#

# Lower is not free, and the cost is not local: PipeWire runs the WHOLE

# graph at the minimum latency any node asks for, so this daemon holds the

# entire session at whatever you set here for as long as it runs. 256 is

# right for wired output; a Bluetooth headset or a loaded machine may want

# 512 or 1024 (and will crackle if you insist otherwise). Range 16..8192.

audio:

enabled: true

# sample: /usr/share/evclack/click.wav

gain: 1.0

latency: 256