From 0190e032f9c24a2e8d24435aa2925db8bec4c977 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Guido=20G=C3=BCnther?= Date: Wed, 2 Oct 2024 15:39:41 +0200 Subject: [PATCH] doc: Modernize README a bit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Guido Günther --- README.md | 85 ++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 52 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 91067d7..b7fc78e 100644 --- a/README.md +++ b/README.md @@ -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 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)