AJAZZ-Plugin 🎛️

AJAZZ-Plugin is a Python plugin for Stream Deck/StreamDock that makes it easy to control media and display status on keys and encoders. The current version includes actions for Spotify and Discord: per‑app volume control, track control, and showing album art/playback status.

---

✨ Core Features

• Per‑application volume control via Encoder (Knob)
  • Discord
  • Spotify
• Spotify playback control
  • Play/Pause
  • Next/Previous track
  • Track tile with cover art and scrolling title/progress
• On‑screen toasts
  • Lightweight floating text notifications (PySide6)
• Extensibility
  • BaseAction class for quickly adding your own actions

---

🧰 Tech Stack

• Language: Python 3.13+
• Platform: Windows (system audio mixer via pycaw)
• SDK: streamdeck_sdk (WebSocket communication with the host app)
• GUI/overlays: PySide6
• Audio control: pycaw
• Spotify API: spotipy + OAuth
• Environment variables: python-dotenv

---

⚙️ Installation & Setup

1. Clone the repository

git clone https://github.com/<your-account>/AJAZZ-Plugin.git
cd AJAZZ-Plugin

2. Create and activate a virtual environment (recommended)

python -m venv .venv
# Windows PowerShell
. .\.venv\Scripts\Activate.ps1

3. Install dependencies

pip install -r requirements.txt

4. Configure Spotify API access

This plugin uses OAuth. Create a .env file in the project root with your Spotify app credentials:

SPOTIPY_CLIENT_ID=your_client_id
SPOTIPY_CLIENT_SECRET=your_client_secret
SPOTIPY_REDIRECT_URI=http://localhost:8888/callback

The redirect URI must match your app configuration in the Spotify Developer Dashboard.

---

🚀 Running

Typically the plugin is launched by the host application (Stream Deck/StreamDock), which passes connection arguments (port, UUID, etc.) to main.py. There are two ways to run it during local development.

• Option A. Through the host app

  • Place the plugin folder into your host's plugins directory. This repo contains an example structure in Plugin-Files/dev.zebaro.testVersion.sdPlugin/ (icons, manifest, plugin/main.bat).
  • Restart the host app. It will run plugin/main.bat, which calls python main.py with the required arguments.

• Option B. Dev loop (manual restart)

  • Use tools/start.bat — the script reads arguments.txt (written by the host next to the plugin) and restarts main.py when it exits.
  • Edit the path to your arguments.txt inside tools/start.bat for your system (by default it points to the developer's path).

Running without arguments (just python main.py) will not connect to the SDK host.

---

📁 Project Structure (high‑level)

• main.py — plugin entry point, action registration and run via streamdeck_sdk
• core/ — core
  • base_action.py — base class for actions
  • audio_mixer.py — control system app volumes (pycaw)
  • spotify_cli.py — Spotify API wrapper (spotipy) + auto playback updates
  • text_widget.py — tiny on‑screen widget/toasts (PySide6)
• actions.py — implemented actions (Spotify/Discord: volume, tracks, cover art)
• Plugin-Files/… — example ready‑to‑use plugin structure for the host
• tools/ — helper scripts for development (auto‑restart, etc.)

---

📬 Contact

• Developer: Denys Shcherbatyi (Zebaro)
• Email: zebaro.work@gmail.com
• Telegram: https://t.me/Zebaro24

If you have ideas to improve the plugin or found a bug, please open an issue or reach out.