SymbX/feedbackd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'theme-doc' into 'main'

Browse Source 
doc: Document `$device` in device themes

See merge request agx/feedbackd!206
This commit is contained in:
Guido Günther
2026-01-16 09:02:56 +00:00
parent ba3ff42794 de3acfb5b6
commit 3177ae8232
2 changed files with 92 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+75 -45
View File
@@ -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.
@@ -178,7 +212,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 +244,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 +252,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.
@@ -218,26 +261,10 @@ 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:
`fbcli` is a command line tool that can be used to trigger feedback
for different events. Here are some examples:
### Phone call
@@ -319,20 +346,20 @@ a haptic device is found.
## Getting in Touch
- Issue tracker: <https://gitlab.freedesktop.org/agx/feedbackd/-/issues>
- Matrix: <https://matrix.to/#/#phosh:phosh.mobi>
- Chat via Matrix: <https://matrix.to/#/#phosh:phosh.mobi>
## 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
@@ -340,3 +367,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/
doc/feedback-themes.rst
+17 -8
View File
@@ -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
<https://gitlab.freedesktop.org/agx/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md>`_
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
========