From 724cbd9727c85cea42a7479638a862d8f0bf3ad2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 15 Jan 2026 19:01:51 +0100 Subject: [PATCH 1/4] doc: Document `$device` in device themes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It identifies the theme as device theme so we should document it. Signed-off-by: Guido Günther --- README.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index dc76fb7..48fdfe1 100644 --- a/README.md +++ b/README.md @@ -178,7 +178,16 @@ the current list of device-specific themes we ship by default. Device specific themes have the same format as custom themes. They also use the `parent-name` property to chain up to the default theme and only override the events that need adjustment. However the rules -for finding the device theme in the file system differ. +for finding the device theme in the file system differ and device +themes always have the `name` property set to `$device`. The simplest +device theme, doing nothing looks like: + +```json +{ + "name" : "$device", + "parent-name": "default" +} +``` If multiple device theme files exist, the selection logic follows these steps: @@ -201,7 +210,7 @@ $ echo $XDG_DATA_DIRS /usr/local/share/:/usr/share/ ``` -The selection logic would follow these steps: +The above selection logic would look at these concrete locations: - `/usr/local/share/feedbackd/themes/pine64,pinephone-1.2.json` takes precedence over `/usr/local/share/feedbackd/themes/pine64-pinephone.json` @@ -209,7 +218,7 @@ The selection logic would follow these steps: over `/usr/share/feedbackd/themes/pine64-pinephone-1.2.json` - etc... -if you create or adjust a device theme and consider the changes +If you create or adjust a device theme and consider the changes generally useful, please submit them as merge request in the [feedbackd-device-themes][1] repository. From 6ef4e4ebfdc945ce7ae4171d844df3541a6eec99 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 15 Jan 2026 22:42:01 +0100 Subject: [PATCH 2/4] feedback-themes: Mention the profiles feedback types are used in MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guido Günther --- doc/feedback-themes.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/doc/feedback-themes.rst b/doc/feedback-themes.rst index bb9546b..a20122d 100644 --- a/doc/feedback-themes.rst +++ b/doc/feedback-themes.rst @@ -12,17 +12,19 @@ DESCRIPTION ----------- The feedback provided to the user for an event is determined by the -feedback theme. Each theme consists of up to three profiles (`full`, -`quiet` and `silent`) containing event names and their associated -feedback. +currently active feedback theme. -Events in the theme are named according to the +Each theme consists of up to three profile sections named `full`, +`quiet` and `silent` containing event names and their associated +feedback. They can reference another theme via the `parent-name` +element to avoid repetition. + +The events in the theme are named according to the `Event Naming Specifiaction `_ Feedback themes use a JSON format that can be validated with -``fbd-theme-validate(1)``. They can include other themes to avoid -repetition. +``fbd-theme-validate(1)``. For details on how to create or modify feedback themes see ``feedbackd's documentation`` at https://gitlab.freedesktop.org/agx/feedbackd#feedback-theme @@ -47,6 +49,8 @@ are described in the ``Sound theme spec`` at https://freedesktop.org/wiki/Specif - `event-name`: The sound event name to use. - `media-role`: The media role to set played audio stream. Defaults to `event`. +`Sound` feedback is usually used in the `full` profile section of the the theme only. + VibraRumble feedback ~~~~~~~~~~~~~~~~~~~~ @@ -57,6 +61,8 @@ The `VibraRumble` feedback uses a single property - `duration`: The duration of the rumble in ms. - `mangitude`: The relative magnitude of the rumble (``[0, 1]``). +`VibraRumble` feedback is usually used in the `quiet` profile section of the the theme only. + VibraPattern feedback ~~~~~~~~~~~~~~~~~~~~~ @@ -65,9 +71,10 @@ The `VibraPattern` feedback has these properties - `magnitudes`: The relative magnitude of each rumble ``[0, 1]`` as array of doubles. - `durations`: The durations of each rumble in ms as array of unsigned integers. -Both arrays must have the same length. +Both arrays must have the same length. `VibraPattern` feedback is +usually used in the `quiet` profile section of the the theme only. -LED feedback +Led feedback ~~~~~~~~~~~~ The `Led` feedback type uses two properties to specify the way a LED blinks. @@ -78,6 +85,8 @@ The `Led` feedback type uses two properties to specify the way a LED blinks. each component. E.g. `#00FFFF` corresponds to cyan color. - `frequency`: The LEDs blinkinig frequency in mHz. +`Led` feedback is usually used in the `silent` profile section of the the theme only. + See also ======== From 6596779bae1e46fadcfdd593c453d99cbd5d7b98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 15 Jan 2026 22:46:05 +0100 Subject: [PATCH 3/4] doc: Clarify event lookup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guido Günther --- README.md | 102 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 61 insertions(+), 41 deletions(-) diff --git a/README.md b/README.md index 48fdfe1..3247339 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,17 @@ # Theme based Haptic, Visual and Audio Feedback -feedbackd provides a DBus daemon (feedbackd) to act on events to provide -haptic, visual and audio feedback. It offers a library (libfeedback) and -GObject introspection bindings to ease using it from applications. +feebackd provides a DBus daemon (feebackd) to act on events to provide +haptic, visual and audio feedback. It offers a library +([libfeedback][libfeedback-api]) and GObject introspection bindings to +ease using it from applications. + +It provides a reference implementation for the [Feedback theme +specification][theme-spec] and [Event naming +specification][event-spec]. ## License -feedbackd is licensed under the GPLv3+ while the libfeedback library is +feebackd is licensed under the GPLv3+ while the libfeedback library is licensed under LGPL 2.1+. ## Getting the source @@ -34,7 +39,7 @@ For an explicit list of dependencies check the `Build-Depends` entry in the ## Building -We use the meson (and thereby Ninja) build system for feedbackd. The quickest +We use the meson (and thereby Ninja) build system for feebackd. The quickest way to get going is to do the following: ```sh @@ -70,7 +75,7 @@ To run under `gdb` use FBD_GDB=1 _build/run _build/src/feedbackd ``` -You can introspect and get the current profile with +You can introspect and get the current maximum profile with ```sh gdbus introspect --session --dest org.sigxcpu.Feedback --object-path /org/sigxcpu/Feedback @@ -80,29 +85,58 @@ To run feedback for an event, use [fbcli](#fbcli) See `examples/` for a simple python example using GObject introspection. -## How it works +## Events, Feedbacks and Profiles -Whenever an event is submitted to the daemon by a client via the DBus API *feedbackd* -looks up the corresponding feedbacks according to the current profile in the currently -active feedback theme (taking per application profile settings into account). +Whenever an event is submitted to the daemon by a client via the DBus +API *feebackd* looks up the corresponding feedbacks in the profiles +of the currently active feedback theme. Which feedbacks are actually +triggered depends on the daemon's current *feedback* *level*, per +application settings and hints provided by the client with the event. +A feedback can be a sound played, a vibra rumble or a LED blinking +with a given pattern. -Any feedback triggered by a client via an event will be stopped latest when the -client disconnects from DBus. This makes sure all feedbacks get canceled if the -app that triggered them crashes. +Any feedback triggered by a client via an event will be stopped latest +when the client disconnects from DBus. This makes sure all feedbacks +get canceled if the app that triggered them crashes. -### Feedback theme +### Profiles + +Each theme consists of up to three profile sections named `full`, +`quiet` and `silent` containing event names and their associated +feedback. feebackd's currently selected profile determines which +profiles of the current theme are being used for event lookup: + +- `full`: Use events from the `full`, `quiet` and `silent` profiles of + the current feedback theme. +- `quiet`: Use events from the `quiet` and `silent` profiles of the + current feedback theme. This usually means haptic and LED but no + sound feedback. +- `silent`: Only use the `silent` profile from the current feedback + theme. This usually means LED but no sound or vibra feedback. + +The daemon's current profile can be changed via a GSetting: + +```sh +gsettings set org.sigxcpu.feedbackd profile full +``` + +As the daemon's current profile value sets an upper limit of the used +profiles of a theme it is called the *feedback* *level*. See the +[Theme spec][theme-spec] for further details. + +### Feedback themes As devices have varying capabilities and users different needs, events are mapped to feedbacks (sound, LED, vibra) via a configurable theme. There are two types of themes: *custom* themes and *device* themes. They both use the same format but have different purpose. Custom -themes are meant to tweak feedbackd's output to the users needs while +themes are meant to tweak feebackd's output to the users needs while device themes are meant to cater for hardware differences. #### Custom themes -Feedbackd is shipped with a default theme `default.json`. You can +feebackd is shipped with a default theme `default.json`. You can replace this by your own, custom theme in multiple ways: 1. By exporting an environment variable `FEEDBACK_THEME` with a path to a @@ -113,7 +147,7 @@ replace this by your own, custom theme in multiple ways: default to `$HOME/.config` 1. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/custom.json` and - telling feedbackd to use that theme. In this custom theme you only + telling feebackd to use that theme. In this custom theme you only specify the events you want to change. Also add a `parent-name` entry to chain up to the default theme: @@ -133,7 +167,7 @@ replace this by your own, custom theme in multiple ways: [here](./tests/data/user-config/feedbackd/themes/custom.json) for an example. - Once you have the file in place, tell feedbackd to use this theme + Once you have the file in place, tell feebackd to use this theme instead of the default one: ```sh @@ -159,7 +193,7 @@ be used to avoid having to restart the daemon in case of configuration changes. ### Device themes -Feedbackd has support to pick up device specific themes +feebackd has support to pick up device specific themes automatically. This allows us to handle device differences like varying strength of haptic motors or different LED colors in an automatic way. @@ -227,23 +261,6 @@ generally useful, please submit them as merge request in the Note that the feedback theme API, including the theme file format, is not stable but considered internal to the daemon. -### Profiles - -The profile determines which parts of the theme are in use: - -- `full`: Use configured events from the `full`, `quiet` and `silent` parts of - the feedback them. -- `quiet`: Use `quiet` and `silent` part from of the feedback theme. This usually - means no audio feedback. -- `silent`: Only use the `silent` part from the feedback theme. This usually means - to not use audio or vibra. - -It can be set via a GSetting - -```sh - gsettings set org.sigxcpu.feedbackd profile full -``` - ## fbcli `fbcli` can be used to trigger feedback for different events. Here are some examples: @@ -328,20 +345,20 @@ a haptic device is found. ## Getting in Touch - Issue tracker: -- Matrix: +- Chat via Matrix: ## Code of Conduct -Note that as a project hosted on freedesktop.org, feedbackd follows its +Note that since feedbackd is hosted on freedesktop.org, feebackd follows its [Code of Conduct], based on the Contributor Covenant. Please conduct yourself in a respectful and civilized manner when communicating with community members on IRC and bug tracker. ## Documentation -- [Libfeedback API](https://feedbackd-b29738.pages.freedesktop.org/) -- [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md) -- [Feedback-theme-spec draft](./doc/Feedback-theme-spec-0.0.0.md) +- [Libfeedback API][libfeedback-api] +- [Event naming spec draft][event-spec] +- [Feedback-theme-spec draft][theme-spec] - [W3's vibration API draft](https://www.w3.org/TR/vibration/) [debian/control]: ./debian/control#L5 @@ -349,3 +366,6 @@ on IRC and bug tracker. [feedback-themes]: ./doc/feedback-themes.rst [Code of Conduct]: https://www.freedesktop.org/wiki/CodeOfConduct/ [feedbackd-themes manpage]: ./doc/feedbackd-themes.rst +[event-spec]: ./doc/Event-naming-spec-0.0.0.md +[theme-spec]: ./doc/Feedback-theme-spec-0.0.0.md +[libfeedback-api]: https://feedbackd-b29738.pages.freedesktop.org/ From de3acfb5b62e8566453da06e33a7f0227eacca3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 15 Jan 2026 22:47:14 +0100 Subject: [PATCH 4/4] doc: Mention what fbcli is MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guido Günther --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3247339..64541df 100644 --- a/README.md +++ b/README.md @@ -263,7 +263,8 @@ not stable but considered internal to the daemon. ## fbcli -`fbcli` can be used to trigger feedback for different events. Here are some examples: +`fbcli` is a command line tool that can be used to trigger feedback +for different events. Here are some examples: ### Phone call