DOCSEARCHbyAlgolia
Submit Docs

Fusuma Documentation

repository·main·Indexed 26 days ago

https://github.com/iberianpig/fusuma

A Linux tool for multitouch gesture recognition on touchpads. Fusuma allows users to map swipes, pinches, rotates, and holds to custom shell commands or keyboard shortcuts. It supports installation on Debian-based, Arch-based, and Fedora distributions, and provides configuration options for gesture sensitivity, intervals, and device filtering via a config.yml file.

Tokens
4.1K
Snippets
12
Records
37
Agent score
86%

What's inside Fusuma

  1. Autostart Fusuma using systemd user service

    main

    Use systemd to manage Fusuma (provides auto-restart on failure and journal-based logs).

    Setup Steps:

    1. Find the real binary path. If using a Ruby version manager (rbenv, asdf, etc.), use readlink -f $(which fusuma) to resolve the actual path.
    2. Create ~/.config/systemd/user/fusuma.service with the content provided below (replacing {path_to_fusuma}).
    3. Note: Do NOT use the -d or --daemon flag; systemd requires the process to run in the foreground (Type=simple).
    4. Reload and enable the service.

    Commands:

    systemctl --user daemon-reload
systemctl --user enable --now fusuma.service

    Management:

    • Check status: systemctl --user status fusuma.service
    • View logs: journalctl --user -u fusuma.service -f
    [Unit]
Description=Fusuma (multitouch gesture recognizer)
Documentation=https://github.com/iberianpig/fusuma
PartOf=graphical-session.target
After=graphical-session.target

[Service]
Type=simple
ExecStart={path_to_fusuma}
Restart=on-failure
RestartSec=3
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=graphical-session.target

  2. Install Fusuma on Fedora

    main

    Follow these steps to install Fusuma on Fedora:

    1. Install libinput (requires libinput 1.0 or later).
    2. Install ruby.
    3. Install fusuma via RubyGems.
    4. (Optional) Install xdotool to enable sending keyboard shortcuts.
    sudo dnf install libinput
sudo dnf install ruby
sudo gem install fusuma
sudo dnf install xdotool

  3. Install Fusuma on Debian-based distros (Ubuntu, Debian, Mint, Pop!_OS)

    main

    Follow these steps to install Fusuma and its dependencies on Debian-based systems:

    1. Install libinput-tools (requires libinput 1.0 or later).
    2. Install ruby.
    3. Install fusuma via RubyGems.
    4. (Optional) Install xdotool to enable sending keyboard shortcuts.
    sudo apt-get install libinput-tools
sudo apt-get install ruby
sudo gem install fusuma
sudo apt-get install xdotool

  4. Autostart Fusuma using gnome-session-properties

    main

    To automatically start Fusuma in GNOME:

    1. Find the installation path by running which fusuma.
    2. Open gnome-session-properties.
    3. Add a new entry named 'Fusuma'.
    4. In the command field, enter the path found in step 1 and append the -d option to run it as a daemon.

  5. Install and update Fusuma plugins

    main

    Fusuma functionality can be extended using plugins following the fusuma-plugin-XXXXX naming convention.

    Install a plugin:

    sudo gem install fusuma-plugin-XXXXX

    Update all installed plugins:

    sudo gem list fusuma-plugin- | cut -d' ' -f1 | xargs --no-run-if-empty sudo gem update
    sudo gem install fusuma-plugin-XXXXX

  6. Autostart Fusuma via Desktop Entry

    main

    Manually create a desktop entry to autostart Fusuma in your session:

    1. Find the installation path with which fusuma.
    2. Create ~/.config/autostart/fusuma.desktop.
    3. Populate the file with the configuration below, replacing {path_to_fusuma} with your actual path.
    4. Ensure the file is executable and restart your session.
    [Desktop Entry]
Name=fusuma
Comment=run fusuma
Exec={path_to_fusuma} -d --log=/tmp/fusuma.log
Icon=input-touchpad
X-GNOME-Autostart-enabled=true
Type=Application

  7. Grant permission to read the touchpad device

    main

    To allow Fusuma to read touchpad data, your user must be a member of the input group.

    1. Add your user to the group: sudo gpasswd -a $USER input
    2. Apply the changes without logging out or rebooting: newgrp input

    Warning: This makes /dev/input/ readable by your user, which may have privacy or security implications.

    sudo gpasswd -a $USER input
newgrp input

  8. Install Fusuma on Arch-based distros (Manjaro, Arch)

    main

    Follow these steps to install Fusuma on Arch-based systems:

    1. Install libinput-tools (requires libinput 1.0 or later).
    2. Install ruby.
    3. Install fusuma via RubyGems. Note that on Arch, gems are typically installed per-user in ~/.gem/ruby/ to avoid conflicts with Pacman. To install system-wide, refer to the Arch Wiki.
    4. (Optional) Install xdotool to enable sending keyboard shortcuts.

    Alternative: You can install the community-built AUR package ruby-fusuma, but it is not officially supported.

    sudo pacman -Syu libinput-tools
sudo pacman -Syu ruby
sudo gem install fusuma
sudo pacman -Syu xdotool

  9. Configure gesture mapping in config.yml

    main

    Custom gestures are configured in ~/.config/fusuma/config.yml. You must create the directory if it does not exist.

    Supported Gestures and Events

    • swipe: Supports 3: or 4: fingers; directions left:, right:, up:, down:; events begin:, update:, end:.
    • pinch: Supports 2:, 3:, 4: fingers; directions in:, out:; events begin:, update:, end:.
    • rotate: Supports 2:, 3:, 4: fingers; directions clockwise:, counterclockwise:; events begin:, update:, end:.
    • hold: (Requires libinput 1.19.0+) Supports 1:, 2:, 3:, 4: fingers; events begin:, end:, cancelled:.

    Configuration Properties

    • command:: The shell command to execute. Note: The shortcut: property is deprecated and was removed in version 1.0. Use command: instead.
    • threshold:: Sensitivity (default 1). A lower value (e.g., 0.5) makes the gesture easier to trigger by shortening the required distance.
    • interval:: Delay between gestures (default 1). A lower value (e.g., 0.5) allows for faster consecutive gestures.

    Priority of Settings

    1. Individual direction settings (e.g., swipe -> 3 -> left -> threshold).
    2. Root child elements (e.g., swipe -> threshold).
    3. Global default (1).
    swipe:
  3:
    left:
      command: "xdotool key alt+Right"
      threshold: 0.5
    right:
      command: "xdotool key alt+Left"
      threshold: 0.5
    up:
      command: "xdotool key super"
    down:
      command: "xdotool key super"
pinch:
  in:
    command: "xdotool keydown ctrl click 4 keyup ctrl"
  out:
    command: "xdotool keydown ctrl click 5 keyup ctrl"

threshold:
  pinch: 0.5

interval:
  swipe: 0.75
  pinch: 0.5

  10. Filter gestures by specific touchpad device

    main

    You can restrict multi-touch gestures to specific devices by using the libinput_device_filter plugin in your configuration file.

    plugin:
  filters:
    libinput_device_filter:
      keep_device_names:
        - "BUILT-IN TOUCHPAD NAME"
        - "EXTERNAL TOUCHPAD NAME"

  11. Fix touchpad not working in GNOME

    main

    If the touchpad is not responding in GNOME, ensure that touchpad events are being sent to the desktop by running the following command:

    gsettings set org.gnome.desktop.peripherals.touchpad send-events enabled

  12. Configure LibinputCommandInput parameters

    main

    When using the LibinputCommandInput plugin, you can configure several parameters to control how libinput commands are executed. These parameters allow you to specify the target device, toggle tap-to-click or disable tap-to-click (DWT), and set verbosity levels.

    Supported configuration keys and their expected types:

    • device: String (The path to the touchpad device)
    • enable-dwt: Boolean
    • disable-dwt: Boolean
    • enable-tap: Boolean
    • show-keycodes: Boolean
    • verbose: Boolean
    • libinput-command: String (Custom command for libinput)
    • libinput-debug-events: String (Custom command for libinput debug events)
    • libinput-list-devices: String (Custom command for listing devices)