Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions ACKNOWLEDGEMENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Acknowledgements

Klicky began as a Linux-focused evolution of [Sauhard74/klicky](https://github.com/Sauhard74/klicky), created by Sauhard Gupta.
I started Klicky after seeing [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky) running on a Mac and wanting it on my Omarchy machine.

The original project established the core ideas that remain central here:

Expand All @@ -16,7 +16,7 @@ This repository preserves the original Git history and MIT license. The original

## Linux and cross-platform work

The current repository adds and maintains:
I expanded it to Linux and Windows, with help from contributors. The main additions include:

- Direct Linux `evdev` input
- Wayland and X11 independence
Expand All @@ -26,8 +26,9 @@ The current repository adds and maintains:
- Configurable low-latency buffer fallbacks
- Capped per-key loudness normalization
- Linux udev and systemd integration
- Omarchy Quickshell integration
- Linux and macOS CI
- Native Windows input, audio and tray controls
- macOS menu controls and Omarchy Klicky Bar
- Cross-platform installers, packages and CI
- Hardware-backed Linux benchmarks and documentation

## Related projects
Expand All @@ -45,7 +46,7 @@ Contributors adding or replacing sounds must provide a clear source and redistri

## Visual identity and typography

The Klicky mascot identity and selected cozy keyboard artwork establish the project's visual direction. The public asset library contains selected final illustrations and simplified application marks; private reference boards are not distributed.
The Klicky mascot identity and selected cozy keyboard artwork establish the project's visual direction. The [asset library](assets/branding) contains the final illustrations and application marks.

The website and outlined wordmarks use Nunito by The Nunito Project Authors. The typeface and web subset retain the [SIL Open Font License](assets/website/fonts/OFL.txt), separately from Klicky's MIT-licensed application code.

Expand Down
4 changes: 2 additions & 2 deletions CODE_OF_CONDUCT.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ We agree to restrict the following behaviors in our community. Instances, threat

Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.

When an incident does occur, it is important to report it promptly. To report a possible violation, **email Muneer Alam at [muneer.alam320@gmail.com](mailto:muneer.alam320@gmail.com). Please include relevant links, what happened and how you can be contacted. Keep reports out of public issues and discussions.**
When an incident does occur, it is important to report it promptly. To report a possible violation, **email me at [muneer.alam320@gmail.com](mailto:muneer.alam320@gmail.com). Please include relevant links, what happened and how you can be contacted. Keep reports out of public issues and discussions.**

Project Maintainers take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Project Maintainers will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.

Expand Down Expand Up @@ -77,7 +77,7 @@ If an investigation by the Project Maintainers finds that this Code of Conduct h
This enforcement ladder is intended as a guideline. It does not limit the ability of Project Maintainers to use their discretion and judgment, in keeping with the best interests of our community.


For Klicky, Muneer Alam handles reports and moderation. Reports are handled privately, with information shared only as needed to investigate and respond. Please use [private security reporting](https://github.com/Muneer320/klicky/security/advisories/new) for software vulnerabilities.
I handle reports and moderation for Klicky. Reports are handled privately, with information shared only as needed to investigate and respond. Please use [private security reporting](https://github.com/Muneer320/klicky/security/advisories/new) for software vulnerabilities.

## Scope

Expand Down
21 changes: 2 additions & 19 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

Thank you for helping improve Klicky. Small, focused changes are easier to test across input stacks and operating systems than broad rewrites.

New to the product? Start with the [field guide](https://klicky.muneer320.tech/guide.html). For presentation work, use the [character story](docs/CHARACTER.md) and [brand asset guide](docs/BRANDING.md); keep instructions technically clear and the mascot recognizable.
New to the product? Start with the [field guide](https://klicky.muneer320.tech/guide.html). For presentation work, use the [character story](docs/CHARACTER.md) and [artwork and export instructions](docs/WEBSITE.md#artwork); keep instructions technically clear and the mascot recognizable.

For usage questions, try [Discussions Q&A](https://github.com/Muneer320/klicky/discussions/categories/q-a). Use [Ideas](https://github.com/Muneer320/klicky/discussions/categories/ideas) to discuss a proposal before turning it into an implementation issue. The [wiki](https://github.com/Muneer320/klicky/wiki) links to the maintained platform guides.

Expand Down Expand Up @@ -128,24 +128,7 @@ same direct `swiftc` build as the menu installer, without installing or running
the app. The workflow verifies that `KlickyMenu.swift` is in the extracted source
archive and retains SARIF results as short-lived CI artifacts.

Until the repository variable `CODEQL_ADVANCED_ENABLED` is `true`, analysis runs
without uploading results; the existing default setup continues to publish its
scans. Do not enable uploads while default setup is active.

For maintainers switching to advanced setup:

1. Review the workflow and verify successful extraction/analysis for all five
languages on the intended commit. Keep default setup active during validation.
2. After merging, switch CodeQL from default to advanced setup, set
`CODEQL_ADVANCED_ENABLED=true`, and run **CodeQL advanced** on `master`.
3. Verify all five uploaded language results and a PR comparison, including a
Dependabot update. Check that existing alert dispositions are preserved. Only
then retire obsolete default configurations or change required-check names.
4. To roll back, set the variable to `false` before restoring default setup with
its previous language selection. Keep normal CI and scanning requirements in
place throughout the transition.

GitHub [rejects advanced CodeQL uploads while default setup is enabled](https://docs.github.com/en/code-security/reference/code-scanning/sarif-files/troubleshoot-sarif-uploads/default-setup-enabled).
CodeQL uses the advanced workflow. `CODEQL_ADVANCED_ENABLED` controls SARIF uploads; keep a single active upload configuration. GitHub [rejects advanced uploads while default setup is enabled](https://docs.github.com/en/code-security/reference/code-scanning/sarif-files/troubleshoot-sarif-uploads/default-setup-enabled).

## Commits

Expand Down
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -223,12 +223,13 @@ Klicky uses native keyboard input on each OS and prepares audio before you type.
| I want to… | Start here |
|---|---|
| Install, configure or troubleshoot | [The website field guide](https://klicky.muneer320.tech/guide.html) |
| Browse all guides | [Documentation index](docs/README.md) |
| Look up commands or configuration | [CLI](docs/CLI.md) · [Configuration](docs/CONFIGURATION.md) |
| Add recordings or desktop integration | [Sound packs](docs/SOUND_PACKS.md) · [Omarchy](docs/OMARCHY.md) |
| Understand or contribute code | [Build, test and contribute](CONTRIBUTING.md) · [Open issues](https://github.com/Muneer320/klicky/issues) |
| Explore the character or use artwork | [Klicky's story](docs/CHARACTER.md) · [Brand assets](docs/BRANDING.md) |
| Explore the character or use artwork | [Klicky's story](docs/CHARACTER.md) · [Artwork](assets/branding) |
| Check releases and project history | [Releases](https://github.com/Muneer320/klicky/releases) · [Changelog](CHANGELOG.md) |

Klicky grew from [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky). After seeing it on a Mac, [Muneer Alam](https://muneer320.tech/) wanted it on his Omarchy machine, adapted it for Linux, and kept going until Windows joined in. [Read the development story.](https://muneer320.tech/projects/klicky/)
I first saw [Sauhard Gupta's original macOS project](https://github.com/Sauhard74/klicky) running on a Mac and wanted it on my Omarchy machine. So I adapted it for Linux, then kept going until Windows joined in. [Read the development story.](https://muneer320.tech/projects/klicky/) · [About me](https://muneer320.tech/)

[MIT license](LICENSE) · [Acknowledgements and third-party credits](ACKNOWLEDGEMENTS.md). Third-party notices are included with packaged downloads.
4 changes: 1 addition & 3 deletions docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,9 +185,7 @@ Windows EXE/ZIP installations store configuration/custom packs under `%LOCALAPPD
- Linux input devices are discovered at daemon startup. A newly added keyboard requires a daemon restart, while a lost reader causes a systemd-managed process to restart and rediscover devices.
- Linux/macOS physical audio-device replacement and suspend/resume need additional runtime testing after the Rodio 0.22 migration. Windows implements recovery, with its hardware matrix still under qualification.
- Benchmark mode measures input callback to mixer dispatch, not microphone-observed audible latency.
- Windows support targets Windows 11 x64 interactive desktops. Windows 10, ARM64, remote sessions and secure desktops are outside the initial support scope. See the [measurement guide](BENCHMARKS.md) for the distinction between internal timing and audible latency.

These constraints are intentionally explicit. They should become focused issues rather than hidden claims of universal support.
- Windows support targets Windows 11 x64 interactive desktops. Windows 10, ARM64, remote sessions and secure desktops are outside the supported desktop scope. See the [measurement guide](BENCHMARKS.md) for the distinction between internal timing and audible latency.

## Further reading

Expand Down
16 changes: 2 additions & 14 deletions docs/BENCHMARKS.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,9 @@ klicky start --benchmark

On Linux/macOS, each mapped keypress prints the elapsed time between the platform input callback and the call that adds the cached audio source to the persistent mixer. Windows prints aggregate diagnostics at exit without key names. Neither mode measures physical key actuation, device scheduling, DAC or speaker onset.

Windows has no calibrated physical-to-audible result established by these figures. Preserve matched keyboard/output/measurement conditions when comparing platforms; requested buffer sizes, dispatch timings and subjective listening are separate evidence. Qualification tooling is documented in [the bounded harness guide](../tools/windows-qualification/USAGE.md).
To measure physical-to-audible latency, record the key impact and generated sound on the same timeline, with matched hardware and output routes. The [bounded qualification harness](../tools/windows-qualification/USAGE.md) supports this work; its internal dispatch counters are a separate measurement.

## Current Linux result
## Recorded Linux run

Test environment:

Expand Down Expand Up @@ -81,18 +81,6 @@ The original `eg-oreo` key slices were much quieter than several Cherry MX packs

For comparison, `cherrymx-blue-pbt` KeyA measured -30.7 dB mean and -6.7 dB peak. Klicky now normalizes each quiet key slice once at startup, targeting an 85 percent peak with a maximum 6x gain. A real-hardware listening test confirmed improved volume without audible clipping.

## What these numbers do not prove

Input-to-dispatch timing excludes:

- Kernel and hardware time before the callback
- Audio buffer duration
- PipeWire or CoreAudio scheduling
- DAC conversion
- Speaker propagation

A rigorous physical-to-audible test requires an external microphone or loopback setup that records the physical key impact and generated sound on one timeline. Until that test exists, Klicky reports dispatch and negotiated buffer measurements separately.

## Reproducing the dispatch test

1. Install and start Klicky normally once.
Expand Down
65 changes: 0 additions & 65 deletions docs/BRANDING.md

This file was deleted.

4 changes: 1 addition & 3 deletions docs/CHARACTER.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@ And when you stop? Klicky settles down. A little quiet is good, too.

Klicky is curious, cheerful, affectionate and a little mischievous. It is never needy: no guilt for taking breaks, no demand to keep typing. Its species, age, origins and wider world stay deliberately unexplained.

The visual anchors are its warm cream body, broad violet ears carrying sound bars, three little forehead keycaps and curled antenna. Those features should remain recognizable in a detailed illustration or a simple monochrome icon.

The mascot is a fictional brand character. The app is a local Rust keyboard-sound utility, with no AI companion, virtual-pet simulation, streaks or rewards.

For the actual software, start with the [field guide](https://klicky.muneer320.tech/guide.html). For artwork and visual consistency, see the [brand guide](BRANDING.md).
For the actual software, start with the [field guide](https://klicky.muneer320.tech/guide.html). For artwork, browse the [asset library](../assets/branding).
Loading
Loading