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

Merge branch 'readme' into 'main'

Browse Source 
doc: Modernize README a bit

See merge request Librem5/feedbackd!145
This commit is contained in:
Guido Günther
2024-10-07 07:30:00 +00:00
parent f5c27d5521 0190e032f9
commit 9e6c1aba16
2 changed files with 52 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitlab-ci.yml
-30
View File
@@ -96,36 +96,6 @@ test:native-debian-trixie:
variables: variables:
- $PKG_ONLY == "1" - $PKG_ONLY == "1"
format-check:
<<: *tags
<<: *image
before_script:
- export DEBIAN_FRONTEND=noninteractive
- apt-get -y update
- apt-get -y install uncrustify git python3
stage: style-checks
needs: []
script:
- |
if [ -n "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" ]; then
git remote add target $CI_MERGE_REQUEST_PROJECT_URL.git
echo "Fetching MR target branch $CI_MERGE_REQUEST_TARGET_BRANCH_NAME from $CI_MERGE_REQUEST_PROJECT_URL"
git fetch target "$CI_MERGE_REQUEST_TARGET_BRANCH_NAME"
git fetch --deepen=100 origin HEAD
merge_base=$(git merge-base "target/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" HEAD)
if [ -z "$merge_base" ]; then
echo "Could't determine merge base"
exit 1
fi
echo "Merge base: $merge_base"
./.gitlab-ci/check-style.py --dry-run --sha $merge_base
else
echo "Not a merge request"
fi
allow_failure: true
rules:
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME'
format-check: format-check:
<<: *tags <<: *tags
stage: style-checks stage: style-checks
README.md
+52 -33
View File
@@ -1,6 +1,4 @@
Haptic/visual/audio feedback for GNOME # Theme based Haptic, Visual and Audio Feedback
======================================
[![Code coverage](https://source.puri.sm/Librem5/feedbackd/badges/master/coverage.svg)](https://source.puri.sm/guido.gunther/feedbackd/commits/master)
feedbackd provides a DBus daemon (feedbackd) to act on events to provide feedbackd provides a DBus daemon (feedbackd) to act on events to provide
haptic, visual and audio feedback. It offers a library (libfeedback) and 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. The master branch has the current development version.
## Dependencies ## Dependencies
On a Debian based system run On a Debian based system run
```sh ```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 We use the meson (and thereby Ninja) build system for feedbackd. The quickest
way to get going is to do the following: way to get going is to do the following:
meson . _build ```sh
ninja -C _build meson . _build
ninja -C _build test ninja -C _build
ninja -C _build install ninja -C _build test
ninja -C _build install
```
## Running ## Running
### Running from the source tree ### Running from the source tree
To run the daemon use To run the daemon use
```sh ```sh
@@ -65,10 +68,10 @@ To run feedback for an event, use [fbcli](#fbcli)
See `examples/` for a simple python example using GObject introspection. 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) 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 events. This will allow us to act as a system sound library so
applications only need to call into this library and things like applications only need to call into this library and things like
the quiet and silent profile work out of the box. 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 client disconnects from DBus. This makes sure all feedbacks get canceled if the
app that triggered it crashes. app that triggered it crashes.
## Feedback theme ### Feedback theme
Events are then mapped to a specific type of feedback (sound, led, vibra) via a Events are then mapped to a specific type of feedback (sound, led, vibra) via a
device specific theme - since devices have different capabilities and device specific theme - since devices have different capabilities and
different users different needs. 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 1. By exporting an environment variable `FEEDBACK_THEME` with a path to a
valid theme file (not recommended, use for testing only), or 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 If `XDG_CONFIG_HOME` environment variable is not set or empty, it will
default to `$HOME/.config`, or 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 You only specify the values you want to change in that theme and add an entry
```json ```json
{ {
"name: "custom" "name: "custom"
"parent-theme": "default" "parent-theme": "default"
"profiles" : [ "profiles" : [
...(entries you want to change go here)... ...(entries you want to change go here)...
] ]
} }
``` ```
next to the `name` entry in. This has the upside that your theme 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 gets way smaller and that new entries added to the default theme
will automatically be used by your theme too. See 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 an example. Once you have the file in place, tell feedbackd the
them you want to use: 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: 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 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 starting with `__` or `$` as this namespace is reserved. This is the
preferred way to specify a custom theme. 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 environment variable, appended with `feedbackd/themes/`. This folder isn't
created automatically, so you have to create it yourself. Here's an example: created automatically, so you have to create it yourself. Here's an example:
```bash
```sh
# Check which folders are "valid" # Check which folders are "valid"
$ echo $XDG_DATA_DIRS $ echo $XDG_DATA_DIRS
[ ... ]:/usr/local/share:/usr/share [ ... ]:/usr/local/share:/usr/share
# Pick a folder that suits you. Note that you shouldn't place themes in # Pick a folder that suits you. Note that you shouldn't place themes in
# /usr/share, because they would be overwritten by updates! # /usr/share, because they would be overwritten by updates!
# Create missing directories # Create missing directories
$ sudo mkdir -p /usr/local/share/feedbackd/themes $ sudo mkdir -p /usr/local/share/feedbackd/themes
# Add your theme file! # Add your theme file!
$ sudo cp my_awesome_theme.json /usr/local/share/feedbackd/themes/ $ 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 filenames for your custom theme (**Note**: You must run this command on the
device you want to create the theme for!): device you want to create the theme for!):
```bash ```sh
$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n" cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
``` ```
Example output (for a Pine64 PinePhone): Example output (for a Pine64 PinePhone):
```bash ```sh
$ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n" $ cat /sys/firmware/devicetree/base/compatible | tr '\0' "\n"
pine64,pinephone-1.2 pine64,pinephone-1.2
pine64,pinephone pine64,pinephone
@@ -166,9 +177,9 @@ modified theme file in
If multiple theme files exist, the selection logic follows these steps: If multiple theme files exist, the selection logic follows these steps:
1. It picks an identifier from the devicetree, until none are left 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 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. **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 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 the theme file format) is not stable but considered internal to the
daemon. daemon.
## Profiles ### Profiles
The profile determines which parts of the theme are in use: The profile determines which parts of the theme are in use:
- `full`: Use configured events from the `full`, `quiet` and `silent` parts of - `full`: Use configured events from the `full`, `quiet` and `silent` parts of
@@ -203,28 +215,32 @@ It can be set via a GSetting
```sh ```sh
gsettings set org.sigxcpu.feedbackd profile full gsettings set org.sigxcpu.feedbackd profile full
``` ```
## fbcli ## fbcli
`fbcli` can be used to trigger feedback for different events. Here are some examples: `fbcli` can be used to trigger feedback for different events. Here are some examples:
### Phone call ### Phone call
Run feedbacks for event `phone-incoming-call` until explicitly stopped: Run feedbacks for event `phone-incoming-call` until explicitly stopped:
``` ```sh
_build/cli/fbcli -t 0 -E phone-incoming-call _build/cli/fbcli -t 0 -E phone-incoming-call
``` ```
### New instant message ### New instant message
Run feedbacks for event `message-new-instant` just once: Run feedbacks for event `message-new-instant` just once:
``` ```sh
_build/cli/fbcli -t -1 -E message-new-instant _build/cli/fbcli -t -1 -E message-new-instant
``` ```
### Alarm clock ### Alarm clock
Run feedbacks for event `message-new-instant` for 10 seconds: Run feedbacks for event `message-new-instant` for 10 seconds:
``` ```sh
_build/cli/fbcli -t 10 -E alarm-clock-elapsed _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. to demo the usage.
## Per app profiles ## Per app profiles
One can set the feedback profile of an individual application One can set the feedback profile of an individual application
via `GSettings`. E.g. for an app with app id `sm.puri.Phosh` via `GSettings`. E.g. for an app with app id `sm.puri.Phosh`
to set the profile to `quiet` do: to set the profile to `quiet` do:
``` ```sh
GSETTINGS_SCHEMA_DIR=_build/data/ gsettings set org.sigxcpu.feedbackd.application:/org/sigxcpu/feedbackd/application/sm-puri-phosh/ profile quiet # 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/) - [Libfeedback API](https://honk.sigxcpu.org/projects/feedbackd/doc/)
- [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md) - [Event naming spec draft](./doc/Event-naming-spec-0.0.0.md)