Skip to main content

​
1) Install Touchdeck

1

Create a virtual environment (uv recommended)

uv venv
uv sync
Prefer pip? Use:
python -m venv .venv
source .venv/bin/activate
pip install -e .
2

Optional: install extras

  • speedtest-cli enables the Speed Test page.
  • nvidia-ml-py enables GPU stats through NVML.
  • Spotify mode requires client ID/secret from the Spotify dashboard.
3

Run Touchdeck

uv run touchdeck  # or: python -m touchdeck
On first launch you’ll be asked to pick a display and whether to start in demo mode.

​
2) Learn the gestures

  • Swipe left/right (or use mouse) to move between pages.
  • Swipe up from the bottom edge to open the quick actions drawer; swipe down to close.
  • Tap cards and buttons; sliders support touch + mouse.

​
3) Configure the basics

  • Open the Settings page from the last tab.
  • Pick MPRIS or Spotify as the media source.
  • Set UI scale/opacity to match your panel, and choose a theme.
  • Enable/disable pages you want visible.
Settings are stored at ~/.config/touchdeck/settings.json and saved automatically.

​
4) Connect Spotify (optional)

  1. Go to Settings → Music → Spotify.
  2. Enter your client ID/secret and redirect port (defaults to 8765).
  3. Tap Sign in to Spotify and complete the browser OAuth flow.
  • Tap Refresh devices to list active Spotify Connect devices.
  • Select the device, then Transfer playback to move audio there.

​
Next steps

Configure settings

Media polling, lyrics cache, GPU toggle, and page visibility.

Quick actions

Add custom shell commands and reorder gestures.

Themes & layout

Tune colors, UI scale, and opacity for your display.

Troubleshooting

Fix MPRIS, Spotify, speed tests, and display issues.