Metadata-Version: 2.4
Name: spicetify-websocket
Version: 0.2.0
Summary: An asynchronous Python wrapper and WebSocket server for controlling the Spotify desktop client via Spicetify and the spicetify-connect-api extension.
Author-email: Tobias Schmitt <support@tobfd.de>
License-Expression: MIT
Project-URL: Github, https://github.com/tobfd/spicetify-websocket
Project-URL: Documentation, https://spicetify-websocket.readthedocs.io
Project-URL: Changelog, https://github.com/tobfd/spicetify-websocket/releases
Keywords: spicetify,websocket,local,spotify
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Topic :: Utilities
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic<3.0,>=2.13.4
Requires-Dist: websockets<17.0,>=16.1.1
Dynamic: license-file

[![spicetify-websocket](https://github.com/tobfd/spicetify-websocket/blob/master/docs/_static/logo.png?raw=true)](https://github.com/tobfd/spicetify-websocket)

[![PyPI Version](https://img.shields.io/pypi/v/spicetify-websocket?style=for-the-badge&logo=pypi&logoColor=white&color=magenta)](https://pypi.org/project/spicetify-websocket/)
[![GitHub License](https://img.shields.io/github/license/tobfd/spicetify-websocket?style=for-the-badge&logo=github&color=red)](https://github.com/tobfd/spicetify-websocket/blob/master/LICENSE)
[![](https://img.shields.io/badge/python-3.10%2B-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![Read the Docs](https://img.shields.io/readthedocs/spicetify-websocket?style=for-the-badge&logo=readthedocs)](https://spicetify-websocket.readthedocs.io/)

An asynchronous Python wrapper and WebSocket server for controlling the Spotify desktop client via [Spicetify](https://spicetify.app/) and the [spicetify-connect-api](https://github.com/tobfd/spicetify-connect-api) extension.

## ✨ Features

- ⚡ **Real-time Push Events:** Instant updates for song changes, volume, seeking, ping heartbeats, and playback state.
- 🎮 **Full Playback Control:** Play, pause, skip, seek, volume, repeat, shuffle, and ping latency checks.
- 🔑 **API Key Security:** Optional token authorization for securing command execution and event streaming.
- 🔒 **Secure WebSockets (WSS):** Built-in SSL/TLS support via `ssl_context` or `certfile`/`keyfile`.
- 🛠️ **Convenience Decorators:** Easy event listening with syntax like `@server.on_song_changed`.
- 🏷️ **Fully Typed:** Pydantic V2 models (`TrackInfo`, `PlayerState`, `RepeatMode`).
- 🔄 **Async & Non-blocking:** Built on `asyncio` and `websockets` for maximum performance.

---

## ⚙️ Installation

Python 3.10 or higher is required.

```bash
pip install spicetify-websocket
```

---

## 📋 Prerequisites

To use this library, ensure you have:
1. **Spotify Desktop Client** installed.
2. **[Spicetify CLI](https://spicetify.app/)** installed and configured.
3. The **[spicetify-connect-api](https://github.com/tobfd/spicetify-connect-api)** extension enabled in Spicetify.

---

## 📚 Documentation & Guides

Explore the official [documentation](https://spicetify-websocket.readthedocs.io/) for detailed references and setup guides:

- 📖 **[API Reference](https://spicetify-websocket.readthedocs.io/)** – Full documentation for `SpotifyServer`, models, decorators, and exceptions.
- 💡 **[Code Examples](https://spicetify-websocket.readthedocs.io/en/latest/examples/examples.html)** – Runnable scripts for basic usage, API key auth, and WSS encryption.
- 🛠️ **[Deployment Guides](https://spicetify-websocket.readthedocs.io/en/latest/guides/guides.html)** – Step-by-step guides for local WSS setups and production VPS deployment.

---

## 🚀 Example Usage

```python
import asyncio
from spicetify import RepeatMode, SpotifyServer, TrackInfo


async def main():
    async with SpotifyServer() as server:

        # Events
        @server.on_song_changed
        def callback(track: TrackInfo):
            print("New song is playing:", track.title)
            print("Artist/s:", ", ".join(artist.name for artist in track.artists))

        # Wait until Spicetify client connects
        await server.wait_for_connection()

        # Playback State
        is_playing: bool = await server.get_is_playing()
        print("Is Spotify playing:", is_playing)

        # Playback Controls
        await server.play_url(url="https://open.spotify.com/intl-de/track/55pBIZO1cqoldeqpp5WR7H?si=57cde33a1bd34ac9")
        await server.set_volume(percent=75)
        await server.set_repeat(mode=RepeatMode.TRACK)

        # Keep the server running to receive events
        await asyncio.Event().wait()


if __name__ == "__main__":
    asyncio.run(main())
```

---

## 📻 Events Reference

| Event Name | Convenience Decorator | Callback Payload Type | Description |
| :--- | :--- | :--- | :--- |
| `InitialState` | `@server.on_initial_state` | `PlayerState` | Fired immediately when Spicetify connects. |
| `SongChanged` | `@server.on_song_changed` | `TrackInfo` | Fired when a new track starts playing. |
| `PlayPauseChanged` | `@server.on_play_pause_changed` | `PlayerState` | Fired when playback state changes. |
| `VolumeChanged` | `@server.on_volume_changed` | `float` (0–100%) | Fired when volume level changes. |
| `RepeatChanged` | `@server.on_repeat_changed` | `RepeatMode` | Fired when repeat mode changes (`OFF`, `CONTEXT`, `TRACK`). |
| `ShuffleChanged` | `@server.on_shuffle_changed` | `bool` | Fired when shuffle mode is toggled. |
| `SeekChanged` | `@server.on_seek_changed` | `int` (ms) | Fired when timeline position is manually changed. |
| `Ping` | `@server.on_ping` | `datetime` (UTC) | Fired on periodic heartbeat pings from Spicetify. |

---
