nsry123 / UniSwitch

# Universal Switch
Universal Switch is a local acoustic control system that learns user-defined
labels for the surface or location of knocks, such as `desk` or `wall`. It also
counts threshold-qualified knocks within each captured window. By default, a
frozen Microsoft BEATs Iter3+ AS2M encoder creates 768-D audio embeddings and an
incremental classifier learns the user's labels. Audio classification runs
locally without a cloud service.
Successful classifications can be published to smart-home platforms through an
optional connector layer. Home Assistant is currently supported; without a
connector configuration, the application retains its terminal-only behavior.
## Setup
Python 3.11 is supported. Use the project Conda environment; FFmpeg is included
so Librosa can decode AAC/M4A recordings and PortAudio supports PyAudio.
 [code] 
To update an existing environment:
 [code] 
`requirements.txt` contains runtime dependencies and `requirements-dev.txt`
adds test, lint, and type-check tools. On systems where PyAudio is installed by
pip, PortAudio development headers must already be available.
## BEATs checkpoint
The default application requires the official pretraining-only
`BEATs_iter3+ (AS2M)` checkpoint from the
Microsoft BEATs release.
The model is not committed and is never downloaded automatically. Obtain the
official file and its SHA-256 digest through a trusted channel, then install it:
 [code] 
The installer verifies the source before atomically writing
`models/BEATs_iter3_plus_AS2M.pt` and its `.sha256` sidecar. Runtime verification
uses that sidecar and strict checkpoint loading. The vendored encoder source is
pinned to Microsoft UNILM revision
`833df7e7832e5064a281131ee64a481afa8e5b95`.
PANN remains available as an alternative. Its official checkpoint downloader is
unchanged:
 [code] 
## Run and register labels
List devices without starting capture:
 [code] 
Start the listener, selecting the correct input device index:
 [code] 
The application opens a localhost microphone monitor in your browser. Its live
charts show the latest waveform, RMS energy, and the labeled trigger threshold,
making it easier to tune `--energy-threshold`. Use `--monitor-port 9000` to
select another local port or `--no-monitor` to run without the dashboard. The
same energy threshold is used to count knocks inside each capture. A counted
knock must fall below 70% of the threshold before another knock can register,
which prevents table ringing and threshold chatter from inflating the count.
At the prompt, enter `register desk`. Each threshold-triggered capture window is
one registration example, even if energy detection finds multiple knocks inside
that window. Tap counting still examines the complete capture, but BEATs refines
the first threshold-qualified onset and extracts features from a fixed 580 ms
window beginning 200 ms before it and retaining 380 ms afterward. Later knocks
therefore do not alter the surface embedding. Immediately before BEATs feature
extract