\r \r

ClawSpotify 🎵\r

\r Control your Spotify playback directly from your OpenClaw agent or terminal. Works with both Free and Premium Spotify accounts.\r \r ---\r \r

📦 Installation\r

\r

Via ClawHub (recommended)\r

clawhub install clawspotify\r
```\r
\r
### Manual from GitHub\r
```bash\r
# Clone main skill\r
git clone https://github.com/ejatapibeda/ClawSpotify.git ~/.openclaw/workspace/skills/ClawSpotify\r
\r
# Create virtual environment\r
python3 -m venv ~/.venv-clawspotify\r
\r
# Install SpotAPI (modified version with session support)\r
git clone https://github.com/ejatapibeda/SpotAPI.git ~/.openclaw/workspace/skills/SpotAPI\r
~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI\r
\r
# Create wrapper script\r
cat > ~/.local/bin/clawspotify \x3C\x3C 'EOF'\r
#!/bin/bash\r
VENV="/home/$(whoami)/.venv-clawspotify"\r
SCRIPT_DIR="/home/$(whoami)/.openclaw/workspace/skills/ClawSpotify"\r
exec "$VENV/bin/python" "$SCRIPT_DIR/scripts/spotify.py" "$@"\r
EOF\r
chmod +x ~/.local/bin/clawspotify\r
\r
# Ensure ~/.local/bin is in PATH\r
export PATH="$HOME/.local/bin:$PATH"\r
```\r
\r
### Dependencies\r
- Python 3.10+\r
- SpotAPI (custom version from ejatapibeda/SpotAPI)\r
- Active Spotify account (Free or Premium)\r
- Spotify app open on at least one device (PC/phone/web) for playback commands to work\r
\r
---\r
\r
## 🔐 First-Time Setup (Authentication)\r
\r
`clawspotify` authenticates using two session cookies from your browser (`sp_dc` and `sp_key`). You only need to do this **once per account**.\r
\r
### Step-by-step\r
\r
1. Open **[https://open.spotify.com](https://open.spotify.com)** in your browser and **log in**\r
2. Press **F12** to open DevTools\r
3. Go to **Application** tab → **Cookies** → `https://open.spotify.com`\r
4. Find and copy the value of **`sp_dc`**\r
5. Find and copy the value of **`sp_key`**\r
6. Run:\r
```bash\r
clawspotify setup --sp-dc "AQC..." --sp-key "07c9..."\r
```\r
\r
Session is saved to `~/.config/spotapi/session.json` and reused automatically.\r
\r
#### Multi-account support\r
```bash\r
clawspotify setup --sp-dc "..." --sp-key "..." --id "work"\r
clawspotify status --id "work"\r
```\r
\r
> **Note:** Cookies expire periodically. If commands fail with a 401 error, re-run setup with fresh cookies.\r
\r
---\r
\r
## 🎮 Commands\r
\r
### Now playing status\r
```bash\r
clawspotify status            # default account\r
clawspotify status --id work  # specific account\r
```\r
\r
### Search music (without playing)\r
```bash\r
clawspotify search "Bohemian Rhapsody"        # search tracks, show top 5\r
clawspotify search-playlist "Workout"         # search playlists, show top 5\r
```\r
\r
### Search and play\r
```bash\r
clawspotify play "Bohemian Rhapsody"          # play first result\r
clawspotify play "Bohemian Rhapsody" --index 2  # pick result #2 (0-indexed)\r
clawspotify play-playlist "Lofi Girl"         # play first playlist result\r
```\r
\r
### Playback controls\r
```bash\r
clawspotify pause\r
clawspotify resume\r
clawspotify skip                     # next track\r
clawspotify prev                     # previous track\r
clawspotify restart                  # restart from beginning\r
```\r
\r
### Queue\r
```bash\r
clawspotify queue "Stairway to Heaven"\r
clawspotify queue "spotify:track:3z8h0TU..."  # add by URI\r
```\r
\r
### Volume\r
```bash\r
clawspotify volume 50     # set to 50%\r
clawspotify volume 0      # mute\r
clawspotify volume 100    # max\r
```\r
\r
### Shuffle / Repeat\r
```bash\r
clawspotify shuffle on\r
clawspotify shuffle off\r
clawspotify repeat on\r
clawspotify repeat off\r
```\r
\r
---\r
\r
## 💡 Usage Tips\r
\r
- **Spotify must be open** on at least one device for playback commands to work. The skill transfers playback to a phantom device but needs an active session.\r
- **First run may be slow** (10-30 seconds) due to WebSocket handshake and device registration. Subsequent commands are faster.\r
- **Session identifier:** Default is `"default"`. Use `--id` flag to manage multiple Spotify accounts.\r
- **Search is fuzzy:** Use artist name + title for best results.\r
- **Output:** Commands print status messages (e.g., `Searching for "...", Playing: URI`).\r
\r
---\r
\r
## ⚠️ Troubleshooting\r
\r
### "No active Spotify device found"\r
- Open Spotify on any device (PC, phone, or web) and start playing something first.\r
- Ensure you're logged in with the same account as the cookies.\r
\r
### "spotapi is not installed" or import errors\r
- Verify virtual environment: `ls ~/.venv-clawspotify/bin/python`\r
- Reinstall SpotAPI: `~/.venv-clawspotify/bin/pip install -e ~/.openclaw/workspace/skills/SpotAPI`\r
\r
### 401 Unauthorized / Session expired\r
- Cookies (`sp_dc`, `sp_key`) expire. Re-run `clawspotify setup` with fresh cookies from browser.\r
\r
### Commands time out or hang\r
- The skill uses WebSockets for real-time state. If Spotify's API is slow, commands may take longer. Use longer timeout or background execution.\r
- Restart OpenClaw gateway to reload skill if it becomes unresponsive.\r
\r
### Wrapper not found (`command not found: clawspotify`)\r
- Ensure `~/.local/bin` is in your `PATH`: `echo $PATH`\r
- Or run directly: `~/.venv-clawspotify/bin/python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py \x3Ccommand>`\r
\r
---\r
\r
## 📂 File Locations\r
\r
| Component | Path |\r
|-----------|------|\r
| Skill folder | `~/.openclaw/workspace/skills/ClawSpotify` |\r
| Wrapper script | `~/.local/bin/clawspotify` |\r
| Virtualenv | `~/.venv-clawspotify` |\r
| SpotAPI (editable) | `~/.openclaw/workspace/skills/SpotAPI` |\r
| Session credentials | `~/.config/spotapi/session.json` |\r
| Main script | `~/skills/ClawSpotify/scripts/spotify.py` |\r
\r
---\r
\r
## 🔧 Agent Implementation Notes\r
\r
When using this skill via OpenClaw agent:\r
\r
1. **Playback commands** (`play`, `pause`, `skip`, etc.) are asynchronous. The command returns once Spotify accepts the request. Actual playback may take a few seconds to start.\r
2. **Long-running operations:** Use background execution or extended timeout (15-30 seconds) for `play`, `search`, and `status` to avoid premature termination.\r
3. **Status query** may occasionally timeout due to WebSocket latency. Play commands are more reliable.\r
4. **Always check** Spotify app/device for actual playback state. The CLI reports what Spotify acknowledges.\r
5. If the skill becomes unresponsive, restart the OpenClaw gateway to clear WebSocket connections.\r
\r
---\r
\r
## 🌐 Platform Note\r
\r
- **Linux/macOS:** Works natively with bash.\r
- **Windows:** Requires WSL, Git Bash, or Cygwin to run the `clawspotify` bash script. Alternatively, run Python directly:\r
  ```bash\r
  python ~/.openclaw/workspace/skills/ClawSpotify/scripts/spotify.py play "song name"\r
  ```\r
\r
---\r
\r
**Version:** 1.0.1 (skill) | SpotAPI: 1.2.7 (custom)\r
**Homepage:** https://github.com/ejatapibeda/ClawSpotify\r
**Author:** Deli (OpenClaw agent) + ejatapibeda (original author)\r