KRunner SpotifyEnhanced

Control Spotify directly from KRunner using spe commands.

Highlights

• Universal playback control across Spotify devices
• Command prefix flow (spe play, spe next, spe pause, ...)
• Search for songs, artists, playlists, podcasts, episodes
• Queue management, seek, repeat, shuffle, volume, track info
• Fork-maintained by Ashley (MeIsGaming) with upstream credits retained

Requirements

• Linux with KDE Plasma / KRunner
• Python 3.9+
• python3-venv
• pip

Install

git clone https://github.com/MeIsGaming/krunner-spotify.git
cd krunner-spotify
./install.sh

Optional install flags:

./install.sh --no-restart
./install.sh --python python3.12
./install.sh --skip-pip
./install.sh --no-systemd

Installer actions:

• Creates .venv (if missing)
• Installs Python dependencies
• Installs KRunner DBus plugin metadata
• Installs and starts a user systemd service (krunner-spotify.service) when available
• Installs icons into ~/.local/share/pixmaps
• Restarts KRunner if kquitapp6 is available

Verify Installation

After install, check these files exist:

• ~/.local/share/krunner/dbusplugins/plasma-runner-KRunnerSpotify.desktop
• ~/.local/share/dbus-1/services/org.kde.KRunnerSpotify.service
• ~/.config/KRunner-Spotify/KRunner-Spotify.config

Then open KRunner and run:

spe login
spe trackinfo

Quick Usage

spe
spe help
spe list
spe ?
spe commands
spe list 2
spe list vol
spe list 2 vol
spe login
spe play bohemian rhapsody
spe next
spe pause
spe resume

KRunner often shows only the first ~10 visible results at once. Use paging for full list views:

spe list 1
spe list 2
spe list 3
spe list next
spe list prev

You can also filter command discovery by text:

spe list vol
spe help play
spe commands info

Full command reference: USAGE.md

Compatibility

• Primary command prefix is spe.
• Optional legacy alias mode (sp) can be enabled in config:

ENABLE_LEGACY_SP_ALIAS = True

Config file path:

• ~/.config/KRunner-Spotify/KRunner-Spotify.config

Common Fixes

• If only one suggestion appears when typing spe, restart KRunner and service:

kquitapp6 krunner
systemctl --user restart krunner-spotify.service

• If commands still show 403, verify CLIENT_ID, REDIRECT_URI, and app user access in Spotify Dashboard.

Quality & Tests

make lint
make shellcheck
make docs-check
make test
make smoke

Optional integration tests (requires running DBus service):

make test-integration

Debug / Uninstall

./debug.sh
./uninstall.sh

Additional options:

./debug.sh --no-redeploy
./uninstall.sh --keep-config --keep-cache

If KRunner does not auto-activate the DBus service on your distro/session bus, the user systemd service keeps the runner available in the background.

Documentation

• wiki/README.md: multilingual wiki entrypoint (DE/EN, extensible)
• USAGE.md: command reference
• docs/DEVELOPMENT.md: local dev guide
• docs/TROUBLESHOOTING.md: common issues
• CONTRIBUTING.md: contribution rules
• CREDITS.md: attribution and maintainer info
• CHANGELOG.md: release notes
• packaging/aur: AUR -git package files (builds from upstream main)
• packaging/aur-stable: AUR stable package files

Maintainer

• Ashley (MeIsGaming)
• Contact: mailto:info@meisgaming.net

Credits

This repository is a maintained fork and keeps clear attribution:

• Original project author: Martijn Vogelaar
• Maintained/extended by: Jochem Kuipers
• Current fork maintainer: Ashley (MeIsGaming)
• Upstream: https://github.com/JochemKuipers/krunner-spotify

License

Distributed under GPL-3.0. See LICENSE.