From ad17493f5fd8fd617076231a42740693c29eeb78 Mon Sep 17 00:00:00 2001 From: Felitendo Date: Mon, 21 Sep 2026 14:00:02 +0200 Subject: [PATCH] docs: add claude.md and avoid dashes --- CLAUDE.md | 7 +++++++ README.md | 8 ++++---- bt-volume-step | 12 ++++++------ 3 files changed, 17 insertions(+), 10 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..0d672eb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,7 @@ +# CLAUDE.md + +## Style + +- Use simple English: short sentences, common words. +- Avoid em dashes (—). Do not just swap them for "-" either. Rewrite the sentence instead, for + example with a comma, a colon, brackets or two sentences. diff --git a/README.md b/README.md index eedb30f..46c7cfd 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ only 16 AVRCP steps, so every swipe on the stem moves the system volume by instead of clean multiples of five. A speaker's volume buttons do the same thing with whatever grid that speaker happens to use. -This is not a desktop misconfiguration — KDE's own volume step is already +This is not a desktop misconfiguration. KDE's own volume step is already exactly 5 %. The grid lives in the device firmware, and it cannot be changed: the device sends *absolute* volume values over AVRCP, not increments. @@ -68,7 +68,7 @@ control. ## Calibration The daemon measures each device's grid on its own. **While a device's grid is -unknown it does not intervene at all** — it only watches. Once the same jump +unknown it does not intervene at all**, it only watches. Once the same jump has repeated three times, that jump is accepted as the device step and remembered, and corrections start from then on. In practice: press volume-up three or four times on a new device and it is set up. @@ -104,7 +104,7 @@ configuration cascade applies). Changes take effect within two seconds, with no restart. On other desktops, or without `kreadconfig6`, it falls back to 5 %. -Everything can be overridden through the environment — put these in a drop-in +Everything can be overridden through the environment. Put these in a drop-in (`systemctl --user edit bt-volume-step`): | Variable | Effect | @@ -121,7 +121,7 @@ and calibration per device. Messages follow `LC_ALL` / `LC_MESSAGES` / `LANG`. English and German are included; other languages fall back to English. To add one, extend -`TRANSLATIONS` in the script — English strings are the keys. +`TRANSLATIONS` in the script. English strings are the keys. ## Limitations diff --git a/bt-volume-step b/bt-volume-step index a953f2c..5f61cf7 100755 --- a/bt-volume-step +++ b/bt-volume-step @@ -1,7 +1,7 @@ #!/usr/bin/env python3 # SPDX-License-Identifier: BSD-3-Clause # Copyright (c) 2026, Felitendo -"""bt-volume-step - fixed volume steps for Bluetooth audio devices. +"""bt-volume-step: fixed volume steps for Bluetooth audio devices. Many Bluetooth devices carry a coarse internal volume grid. AirPods Pro, for example, expose only 16 AVRCP steps, so every swipe on the stem moves the @@ -72,8 +72,8 @@ TRANSLATIONS = { "known device steps:": "bekannte Gerätestufen:", "watching {device} at {volume:.1f} %": "beobachte {device} bei {volume:.1f} %", - "{device}: measured device step = {step:.2f} % ({count} steps) - active from now on": - "{device}: Gerätestufe gemessen = {step:.2f} % ({count} Stufen) – ab jetzt aktiv", + "{device}: measured device step = {step:.2f} % ({count} steps), active from now on": + "{device}: Gerätestufe gemessen = {step:.2f} % ({count} Stufen), ab jetzt aktiv", "{device}: {last:.1f} % -> device reported {cur:.1f} % -> set {target:.1f} %": "{device}: {last:.1f} % -> Gerät meldete {cur:.1f} % -> gesetzt {target:.1f} %", "file: {path}": "Datei: {path}", @@ -141,7 +141,7 @@ def log(msg): def half_up(x): """Round half away from zero instead of Python's round-half-to-even. - Otherwise snap(65, 10) would be 60 while snap(75, 10) is 80 - that is, + Otherwise snap(65, 10) would be 60 while snap(75, 10) is 80. That is unpredictable for values sitting exactly between two grid points. """ return math.floor(x + 0.5) @@ -284,7 +284,7 @@ def calibrate(delta, samples, plasma_step): A volume button press on the device always produces the same jump. Deltas that match the desktop's own step size most likely come from the keyboard - and are skipped - otherwise the daemon would calibrate itself onto them. + and are skipped. Otherwise the daemon would calibrate itself onto them. """ mag = abs(delta) if not DEV_MIN <= mag <= DEV_MAX: @@ -387,7 +387,7 @@ def run(): entry["step"] = round(found, 3) save_store(store) log(_("{device}: measured device step = {step:.2f} % " - "({count} steps) - active from now on") + "({count} steps), active from now on") .format(device=device, step=found, count=round(100 / found))) st["last"] = cur