From 047f83c6b3fb514e1170f1ea59414163faad2738 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:27:12 +0200 Subject: [PATCH 1/6] doc: Fix typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gbp-Dch: Ignore Signed-off-by: Guido Günther --- doc/feedbackd.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/feedbackd.rst b/doc/feedbackd.rst index d328f48..fbe7039 100644 --- a/doc/feedbackd.rst +++ b/doc/feedbackd.rst @@ -56,7 +56,7 @@ These gsettings are used by ``feedbackd``: - `prefer-flash`: Prefer camera flash over status LED - `theme`: The feedback theme to use. This can be used to override the feedback theme picked by feedbackd based on device information. - - `max-haptic-strength`: Limits th maximum strenght used for the + - `max-haptic-strength`: Limits th maximum strength used for the haptic motor `[0.0, 1.0]`. - `org.sigxcpu.feedbackd.application` From 78d82207e509972ae9257e583e047d38f46e6f01 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:16:27 +0200 Subject: [PATCH 2/6] doc: Document missing VibraRumble properties MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes f089ad2 ("vibra-rumble: Add magnitude property") Signed-off-by: Guido Günther --- doc/feedback-themes.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/feedback-themes.rst b/doc/feedback-themes.rst index e28d79f..41c9857 100644 --- a/doc/feedback-themes.rst +++ b/doc/feedback-themes.rst @@ -41,7 +41,10 @@ VibraRumble feedback The `VibraRumble` feedback uses a single property +- `count`: The number of rumbles. +- `pause`: The pause between each rumble in ms. - `duration`: The duration of the rumble in ms. +- `mangitude`: The relative magnitude of the rumble (``[0, 1]``). VibraPattern feedback ~~~~~~~~~~~~~~~~~~~~~ From 155814035d1d66fdc8a98bb1b1b212593b1367c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:11:45 +0200 Subject: [PATCH 3/6] doc: Document Sound properties 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 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/feedback-themes.rst b/doc/feedback-themes.rst index 41c9857..bd57082 100644 --- a/doc/feedback-themes.rst +++ b/doc/feedback-themes.rst @@ -36,6 +36,8 @@ Sound feedback Sound feedbacks specify an event name from a XDG sound theme. Sound themes are described in the ``Sound theme spec`` at https://freedesktop.org/wiki/Specifications/sound-theme-spec/ +- `event-name`: The sound event name to use. + VibraRumble feedback ~~~~~~~~~~~~~~~~~~~~ From a646a3474146d4585a7feab91e90bd2e80548cee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:23:41 +0200 Subject: [PATCH 4/6] doc: Reference manpage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refer to manpage rather than to the classes in the source code. Signed-off-by: Guido Günther --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3bbe2dd..51bb9c7 100644 --- a/README.md +++ b/README.md @@ -194,8 +194,8 @@ examples: For available feeddback types see the [feedback-themes][](5) manpage. -You can check the feedback theme and the classes (prefixed with Fbd) -for available properties. Note that the feedback theme API (including +You can check the feedback theme and the [feedbackd-themes manpage][] +or available properties. Note that the feedback theme API (including the theme file format) is not stable but considered internal to the daemon. @@ -320,3 +320,4 @@ on IRC and bug tracker. [1]: https://gitlab.freedesktop.org/agx/feedbackd-device-themes [feedback-themes]: ./doc/feedback-themes.rst [Code of Conduct]: https://www.freedesktop.org/wiki/CodeOfConduct/ +[feedbackd-themes manpage]: ./doc/feedbackd-themes.rst From eb2cb766358952ca996037aa9ffcb0251b425776 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:24:35 +0200 Subject: [PATCH 5/6] doc: Fix parent-name reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes: https://gitlab.freedesktop.org/agx/feedbackd/-/issues/89 Signed-off-by: Guido Günther --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 51bb9c7..89f7147 100644 --- a/README.md +++ b/README.md @@ -100,7 +100,7 @@ You can add your own themes in multiple ways: ```json { "name: "custom" - "parent-theme": "default" + "parent-name": "default" "profiles" : [ ...(entries you want to change go here)... ] From 84b783cbf7763351de01fc819c05ec60fafd5cf9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Thu, 24 Apr 2025 10:59:08 +0200 Subject: [PATCH 6/6] doc: Clarify theme use MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guido Günther --- README.md | 14 ++++++-------- doc/feedback-themes.rst | 16 ++++++++++++---- doc/feedbackd.rst | 10 ++++++---- 3 files changed, 24 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 89f7147..017ae76 100644 --- a/README.md +++ b/README.md @@ -70,11 +70,9 @@ See `examples/` for a simple python example using GObject introspection. ## How it works -We're using a [event naming spec](./doc/Event-naming-spec-0.0.0.md) -similar to to name -events. This will allow us to act as a system sound library so -applications only need to call into this library and things like -the quiet and silent profile work out of the box. +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). 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 @@ -82,9 +80,9 @@ app that triggered it crashes. ### Feedback theme -Events are then mapped to a specific type of feedback (sound, led, vibra) via a -device specific theme - since devices have different capabilities and -different users different needs. +As devices have varying capabilities and users different needs, events +are mapped to a feedbacks (sound, LED, vibra) via a configurable +theme. Feedbackd is shipped with a default theme `default.json`. You can add your own themes in multiple ways: diff --git a/doc/feedback-themes.rst b/doc/feedback-themes.rst index bd57082..31fd868 100644 --- a/doc/feedback-themes.rst +++ b/doc/feedback-themes.rst @@ -11,10 +11,18 @@ Theme configuration for feedbackd DESCRIPTION ----------- -In order to reflect device specifics and user overrides the feedback -(such as sound, haptic or led) that is being triggered by an event can -be configured and overridden by so called themes. Feedback themes use a JSON -format that can be validated with ``fbd-theme-validate``. +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. + +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. For details on how to create or modify feedback themes see ``feedbackd's documentation`` at https://gitlab.freedesktop.org/agx/feedbackd#feedback-theme diff --git a/doc/feedbackd.rst b/doc/feedbackd.rst index fbe7039..005a09a 100644 --- a/doc/feedbackd.rst +++ b/doc/feedbackd.rst @@ -21,14 +21,14 @@ event feedback such as playing a sound, trigger a haptic motor or blink a LED. The feedback triggered by a given event is determined by the feedback theme in -use. Events are submitted via a DBus API. +use (see `feedback-themes(5)`). Events are submitted via a DBus API. 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 it crashes. For details refer to the event and feedback theme specs at -``__ +``__. Feedbackd reloads the feedback theme on `SIGHUP` (i.e. `pkill -HUP feedbackd`). @@ -49,7 +49,8 @@ These gsettings are used by ``feedbackd``: - `org.sigxcpu.feedbackd` - - `profile`: The current overall feedback profile + - `profile`: The current overall feedback profile. Valid values are + `full`, `quiet` and `silent`. - `allow-important`: List of apps that can override the feedback level (useful for e.g. allowing the alarm clock to also emit sound when device is in silent mode). @@ -61,7 +62,8 @@ These gsettings are used by ``feedbackd``: - `org.sigxcpu.feedbackd.application` - - `profile`: Per application profile levels + - `profile`: Per application profile levels. Valid values are + `full`, `quiet` and `silent`. See also ========