# Configuration
Source: https://touchdeck.codesft.dev/configuration
Tune media sources, polling, pages, and caches
All settings are persisted to `~/.config/touchdeck/settings.json` and loaded on startup. You can edit them in the Settings page or by hand (Touchdeck will coerce invalid values back to safe defaults).
## Core options
* **Media source**: `mpris` (default) or `spotify`. MPRIS uses D-Bus; Spotify uses the Web API.
* **Polling**: `music_poll_ms` (250–3000 ms) controls media refresh; `stats_poll_ms` (500–5000 ms) controls CPU/RAM/GPU refresh.
* **GPU stats**: `enable_gpu_stats` toggles NVML usage. When off, GPU rows are hidden.
* **Clock**: `clock_24h` and `show_clock_seconds` drive the Clock page.
* **UI**: `ui_scale_percent` (25–200) sets Qt scale; `ui_opacity_percent` (50–100) sets window opacity.
* **Theme**: `theme` selects a preset. See Themes for details.
* **Pages**: `enabled_pages` lists the visible pages in order. `settings` is always appended for safety.
* **Lyrics**: `lyrics_cache` stores LRCLIB lines per track to avoid re-fetching.
## Spotify settings
* **Client ID/secret**: required for Spotify mode; stored locally.
* **Redirect port**: defaults to 8765 and must match your Spotify app settings.
* **Device ID**: optional target for play/pause/seek and transfer.
## Quick actions
* **quick\_actions**: ordered list of action keys shown in the drawer.
* **custom\_actions**: array of `{key, title, command, timeout_ms}`. Keys must be unique; unknown keys are dropped.
* Timeout is clamped to 500–300000 ms in `touchdeck/settings.py`.
## Resetting
Delete `~/.config/touchdeck/settings.json` to return to defaults. The next launch will recreate it.
# Development
Source: https://touchdeck.codesft.dev/development
Work on Touchdeck and its docs locally
## Project layout
* App code: `touchdeck/`
* Tests: `tests/`
* Docs (this site): `docs/`
* Settings + caches at runtime: `~/.config/touchdeck/`
## Dev environment
```bash theme={null}
uv venv
uv sync --dev
```
This installs PySide6, qasync, psutil, NVML bindings (optional), Spotipy, and test tools.
```bash theme={null}
uv run touchdeck
# or: python -m touchdeck
```
Use `--display` flags? Not needed—the app prompts you to pick a screen on first launch.
```bash theme={null}
uv run pytest
```
For coverage:
```bash theme={null}
uv run pytest --cov --cov-branch --cov-report=xml --cov-report html:cov_html
```
## Code style and linting
* The codebase is type-hinted; prefer mypy-friendly changes.
* Keep UI styles consistent with `touchdeck/themes.py` and widget helpers.
* Avoid blocking the Qt event loop—use `asyncio.to_thread` where needed.
## Working on docs
```bash theme={null}
npm i -g mint
```
```bash theme={null}
cd docs
mint dev
```
Open [http://localhost:3000](http://localhost:3000) to view the docs.
## Where to contribute
* New UI pages or widgets: `touchdeck/ui/`
* Media providers: `touchdeck/services/mpris.py`, `touchdeck/services/spotify_provider.py`
* Settings and validation: `touchdeck/settings.py`
* Quick actions and custom commands: `touchdeck/quick_actions.py` and `touchdeck/ui/window.py`
See [README](../README.md) for user-facing setup.
# Touchdeck
Source: https://touchdeck.codesft.dev/index
Touch-friendly control surface for music, stats, and quick actions
Touchdeck is a touch-first "stream deck" UI for 800x480-ish landscape displays. It wraps your media controls, live lyrics, system stats, and a swipe-up quick actions drawer into a single PySide6 app.
Install with uv, pick a display, and start the deck.
Themes, polling rates, pages, and quick actions live in settings.json.
Music, stats, speed test, clock, emoji picker, developer info, and settings pages.
Fix MPRIS, GPU stats, speed tests, and display setup.
## Capabilities at a glance
* Now Playing controls via MPRIS (Linux-first) and Spotify Web API (with optional device transfer)
* Synced lyrics using LRCLIB with caching and on-demand refresh
* System stats (CPU/RAM and optional NVIDIA GPU via NVML) with configurable polling
* Swipe navigation between pages plus swipe-up quick actions drawer
* Built-in speed test, emoji picker, clock, developer status, and settings pages
* Themes, UI scale, and opacity for dark kiosks or bright panels
The docs are mirrored in Context7 for quick answers: [https://context7.com/codesoftgit/touchdeck](https://context7.com/codesoftgit/touchdeck)
## Requirements
* Python 3.10+
* Linux desktop with D-Bus (for MPRIS) and a compatible media player (Spotify, VLC, etc.)
* Optional: NVIDIA drivers + `nvidia-ml-py` for GPU stats; `speedtest-cli` for speed tests; Spotify client credentials for Spotify mode
* Small landscape touchscreen (default layout is 800x480); mouse/trackpad also works
## How Touchdeck is built
* PySide6 for UI, qasync to bridge Qt's event loop with asyncio
* Media providers: MPRIS and Spotify (`touchdeck/services/mpris.py`, `touchdeck/services/spotify_provider.py`)
* Stats: psutil and optional NVML (`touchdeck/services/stats.py`)
* Settings stored at `~/.config/touchdeck/settings.json` (`touchdeck/settings.py`)
* UI pages and widgets under `touchdeck/ui/`
Ready to drive it? Start with the quickstart, then tune settings and quick actions.
# Quick actions
Source: https://touchdeck.codesft.dev/quick-actions
Swipe-up drawer commands and custom actions
The quick actions drawer opens with an upward swipe from the bottom edge (or mouse drag) and closes with a downward swipe. Actions are large, touch-friendly buttons.
## Built-in actions
* `play_pause` — toggle playback on the current media provider
* `next_track` — skip forward
* `prev_track` — go back
* `run_speedtest` — start a new speed test
* `toggle_gpu` — enable/disable GPU stats at runtime
Default order: play/pause, next track, run speed test.
## Custom actions
Create custom shell commands from the Settings page. Each action is stored as `{key, title, command, timeout_ms}` in `custom_actions`.
* Keys are slugified; collisions are suffixed (`custom-foo-2`).
* Commands run via `subprocess.Popen(shell=True)` with live output streamed to the drawer.
* `timeout_ms` defaults to 8000 and is clamped between 500 and 300000 ms.
* Actions can be canceled while running.
## Ordering and visibility
* The drawer respects the order in `quick_actions` (unknown keys are filtered).
* If the list becomes empty, defaults are restored automatically.
* Custom actions appear alongside built-ins when their keys are listed.
# Quickstart
Source: https://touchdeck.codesft.dev/quickstart
Install, launch, and drive Touchdeck in minutes
## 1) Install Touchdeck
```bash theme={null}
uv venv
uv sync
```
Prefer pip? Use:
```bash theme={null}
python -m venv .venv
source .venv/bin/activate
pip install -e .
```
* `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.
```bash theme={null}
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
Media polling, lyrics cache, GPU toggle, and page visibility.
Add custom shell commands and reorder gestures.
Tune colors, UI scale, and opacity for your display.
Fix MPRIS, Spotify, speed tests, and display issues.
# Themes & layout
Source: https://touchdeck.codesft.dev/themes
Colors, scaling, and window behavior
Touchdeck includes preset themes defined in `touchdeck/themes.py`:
* Midnight (default)
* Glacier
* Sunset
* Dawn
* Aurora
* Berry
* Neon
Each theme sets gradients, text/subtle colors, panel/background shades, slider and progress hues. The Settings page lets you switch themes at runtime; changes are applied instantly via Qt style sheets.
## UI scale and opacity
* `ui_scale_percent` scales all Qt widgets (sets `QT_SCALE_FACTOR`); range 25–200.
* `ui_opacity_percent` dims the window for kiosk-style setups; range 50–100.
* Demo mode keeps the window resizable; normal mode opens full screen.
## Displays
On first launch, a dialog lets you choose which display to target and whether to enter demo mode. Choices persist in settings.
## Fonts and rounding
* Rounded corners are controlled by `touchdeck/constants.py` (`CORNER_RADIUS = 24`).
* The UI uses a modern sans stack (`Inter` → `SF Pro` → `Segoe UI` → `Noto Sans` → fallback sans).
# Troubleshooting
Source: https://touchdeck.codesft.dev/troubleshooting
Fix common Touchdeck issues
## Media / MPRIS
* Ensure a player that implements MPRIS is running (Spotify, VLC, etc.).
* If nothing appears, restart the player, then Touchdeck.
* DBus errors: verify you have a session bus (running under X/Wayland on Linux).
## Spotify
* "Spotify is not signed in": redo the Settings → Spotify sign-in flow.
* "Playback state not available": ensure your Spotify client is active and the selected device is online.
* Cover art missing: local files may not ship art via Web API; this is expected.
## GPU stats
* Install `nvidia-ml-py` and verify the NVIDIA driver is present.
* Toggle GPU stats off/on from Quick Actions to reinitialize NVML.
## Speed test
* Install `speedtest-cli` (`pip install speedtest-cli`).
* Network failures are surfaced in the Speed Test card; try again on a stable link.
## Display and input
* Qt must reach a display; SSH without X forwarding will fail to show a window.
* Touch input is synthesized from mouse events when missing; true touch works out of the box on Linux.
## Settings
* Corrupt settings file? Delete `~/.config/touchdeck/settings.json` and relaunch.
* Pages missing: ensure `enabled_pages` contains them; `settings` is always added automatically.
# UI pages
Source: https://touchdeck.codesft.dev/ui-pages
What each Touchdeck page does
Touchdeck ships with several swipeable pages. You can reorder or hide them (except Settings) via `enabled_pages` in settings.
## Music
* Controls play/pause/next/previous for the active provider (MPRIS or Spotify).
* Seek slider honors provider capabilities (MPRIS `CanSeek`, Spotify always true).
* Displays cover art (data URLs or HTTP) and metadata; falls back gracefully.
* Synced lyrics via LRCLIB with inline status messages and caching.
## Stats
* CPU percent, RAM usage, and optional GPU/VRAM usage via NVML.
* Updates on `stats_poll_ms`; GPU rows hide automatically if disabled.
## Speed Test
* Runs `speedtest-cli` in a worker thread and shows download/upload/ping.
* Handles missing dependency with a friendly error.
## Clock
* Large clock tuned for 800x480. Supports 12/24h and optional seconds.
## Emoji
* Tap to copy frequently used emoji (including clipboard-friendly text faces).
* Uses bundled Noto SVG emoji where available; falls back to text.
## Developer
* Shows current theme, UI scale, opacity, demo mode, GPU toggle, and enabled pages.
* Lists recent warnings/errors emitted by the app.
## Settings
* Central place to adjust media source, theme, display choices, quick actions, and Spotify auth.
* Editing settings here writes to `~/.config/touchdeck/settings.json` immediately.