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

doc: Modernize README a bit

Browse Source 
Signed-off-by: Guido Günther <agx@sigxcpu.org>
This commit is contained in:
Guido Günther
2024-10-02 16:05:55 +02:00
parent e79b1eec7b
commit 0190e032f9
1 changed files with 52 additions and 33 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+52 -33
View File
@@ -1,6 +1,4 @@
Haptic/visual/audio feedback for GNOME
======================================
[![Code coverage](https://source.puri.sm/Librem5/feedbackd/badges/master/coverage.svg)](https://source.puri.sm/guido.gunther/feedbackd/commits/master)
# 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
@@ -21,6 +19,7 @@ cd feedbackd
The master branch has the current development version.
## Dependencies
On a Debian based system run
```sh
@@ -36,13 +35,17 @@ For an explicit list of dependencies check the `Build-Depends` entry in the
We use the meson (and thereby Ninja) build system for feedbackd. The quickest
way to get going is to do the following:
meson . _build
ninja -C _build
ninja -C _build test
ninja -C _build install
```sh
meson . _build
ninja -C _build
ninja -C _build test
ninja -C _build install
```
## Running
### Running from the source tree
To run the daemon use
```sh
@@ -65,10 +68,10 @@ To run feedback for an event, use [fbcli](#fbcli)
See `examples/` for a simple python example using GObject introspection.
# How it works
## How it works
We're using a [event naming spec](./doc/Event-naming-spec-0.0.0.md)
similar to http://0pointer.de/public/sound-naming-spec.html to name
similar to <http://0pointer.de/public/sound-naming-spec.html> 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.
@@ -77,7 +80,8 @@ 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.
## Feedback theme
### 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.
@@ -87,20 +91,22 @@ You can add your own themes in multiple ways:
1. By exporting an environment variable `FEEDBACK_THEME` with a path to a
valid theme file (not recommended, use for testing only), or
2. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/default.json`.
1. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/default.json`.
If `XDG_CONFIG_HOME` environment variable is not set or empty, it will
default to `$HOME/.config`, or
3. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/custom.json`.
1. By creating a theme file under `$XDG_CONFIG_HOME/feedbackd/themes/custom.json`.
You only specify the values you want to change in that theme and add an entry
```json
{
"name: "custom"
"parent-theme": "default"
"profiles" : [
...(entries you want to change go here)...
]
"profiles" : [
...(entries you want to change go here)...
]
}
```
next to the `name` entry in. This has the upside that your theme
gets way smaller and that new entries added to the default theme
will automatically be used by your theme too. See
@@ -108,29 +114,34 @@ You can add your own themes in multiple ways:
an example. Once you have the file in place, tell feedbackd the
them you want to use:
gsettings set org.sigxcpu.feedbackd theme custom
```sh
gsettings set org.sigxcpu.feedbackd theme custom
```
When you want to go back to the default theme just do:
gsettings reset org.sigxcpu.feedbackd theme
```sh
gsettings reset org.sigxcpu.feedbackd theme
```
Note that you can name your theme as you wish but avoid theme names
starting with `__` or `$` as this namespace is reserved. This is the
preferred way to specify a custom theme.
4. By adding your theme file to one of the folders in the `XDG_DATA_DIRS`
1. By adding your theme file to one of the folders in the `XDG_DATA_DIRS`
environment variable, appended with `feedbackd/themes/`. This folder isn't
created automatically, so you have to create it yourself. Here's an example:
```bash
```sh
# Check which folders are "valid"
$ echo $XDG_DATA_DIRS
[ ... ]:/usr/local/share:/usr/share
# Pick a folder that suits you. Note that you shouldn't place themes in
# /usr/share, because they would be overwritten by updates!
# Create missing directories
$ sudo mkdir -p /usr/local/share/feedbackd/themes
# Add your theme file!
$ sudo cp my_awesome_theme.json /usr/local/share/feedbackd/themes/
```
@@ -146,13 +157,13 @@ device-tree attribute. You can run the following command to get a list of valid
filenames for your custom theme (**Note**: You must run this command on the
device you want to create the theme for!):
```bash
$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
```sh
cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
```
Example output (for a Pine64 PinePhone):
```bash
```sh
$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
pine64,pinephone-1.2
pine64,pinephone
@@ -166,9 +177,9 @@ modified theme file in
If multiple theme files exist, the selection logic follows these steps:
1. It picks an identifier from the devicetree, until none are left
2. It searches through the folders in `XDG_DATA_DIRS` in order of appearence,
1. It searches through the folders in `XDG_DATA_DIRS` in order of appearence,
until none are left
3. If a theme file is found in the current location with the current name,
1. If a theme file is found in the current location with the current name,
**it will be chosen** and other themes are ignored.
If no theme file can be found this way (i.e. there are no identifiers and
@@ -188,7 +199,8 @@ for available properties. Note that the feedback theme API (including
the theme file format) is not stable but considered internal to the
daemon.
## Profiles
### Profiles
The profile determines which parts of the theme are in use:
- `full`: Use configured events from the `full`, `quiet` and `silent` parts of
@@ -203,28 +215,32 @@ 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:
### Phone call
Run feedbacks for event `phone-incoming-call` until explicitly stopped:
```
```sh
_build/cli/fbcli -t 0 -E phone-incoming-call
```
### New instant message
Run feedbacks for event `message-new-instant` just once:
```
```sh
_build/cli/fbcli -t -1 -E message-new-instant
```
### Alarm clock
Run feedbacks for event `message-new-instant` for 10 seconds:
```
```sh
_build/cli/fbcli -t 10 -E alarm-clock-elapsed
```
@@ -250,15 +266,18 @@ bindings ship an [example](https://gitlab.gnome.org/guidog/libfeedback-rs/-/blob
to demo the usage.
## Per app profiles
One can set the feedback profile of an individual application
via `GSettings`. E.g. for an app with app id `sm.puri.Phosh`
to set the profile to `quiet` do:
```
GSETTINGS_SCHEMA_DIR=_build/data/ gsettings set org.sigxcpu.feedbackd.application:/org/sigxcpu/feedbackd/application/sm-puri-phosh/ profile quiet
```sh
# If you don't have feedbackd installed, run this from the built source tree:
export GSETTINGS_SCHEMA_DIR=_build/data/
gsettings set org.sigxcpu.feedbackd.application:/org/sigxcpu/feedbackd/application/sm-puri-phosh/ profile quiet
```
# Documentation
## Documentation
- [Libfeedback API](https://honk.sigxcpu.org/projects/feedbackd/doc/)
- [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md)