spicetify-websocket 0.1.0__tar.gz

spicetify_websocket-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tobias Schmitt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spicetify_websocket-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: spicetify-websocket
+Version: 0.1.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, and playback state.
+- 🎮 **Full Playback Control:** Play, pause, skip, seek, volume, repeat, and shuffle.
+- 🛠️ **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.
+
+---
+
+## 🚀 Example Usage
+
+```python
+import asyncio
+from spicetify import RepeatMode, SpotifyServer, TrackInfo
+
+
+async def main():
+    async with SpotifyServer() as server:
+        # Wait until Spicetify client connects
+        await server.wait_for_connection()
+
+        # 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)
+
+        # Playback State
+        current_track: TrackInfo = await server.get_current_track()
+        print(current_track)
+
+        # 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))
+
+        # 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. |
+---

spicetify_websocket-0.1.0/README.md

@@ -0,0 +1,86 @@
+[![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, and playback state.
+- 🎮 **Full Playback Control:** Play, pause, skip, seek, volume, repeat, and shuffle.
+- 🛠️ **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.
+
+---
+
+## 🚀 Example Usage
+
+```python
+import asyncio
+from spicetify import RepeatMode, SpotifyServer, TrackInfo
+
+
+async def main():
+    async with SpotifyServer() as server:
+        # Wait until Spicetify client connects
+        await server.wait_for_connection()
+
+        # 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)
+
+        # Playback State
+        current_track: TrackInfo = await server.get_current_track()
+        print(current_track)
+
+        # 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))
+
+        # 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. |
+---

spicetify_websocket-0.1.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spicetify-websocket"
+authors = [
+  { name="Tobias Schmitt", email="support@tobfd.de" },
+]
+description = "An asynchronous Python wrapper and WebSocket server for controlling the Spotify desktop client via Spicetify and the spicetify-connect-api extension."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Utilities",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Software Development :: Libraries :: Python Modules"
+]
+keywords = ["spicetify", "websocket", "local", "spotify"]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+dependencies = [
+  "pydantic>=2.13.4,<3.0",
+  "websockets>=16.1.1,<17.0",
+]
+dynamic = ["version"]
+
+[project.urls]
+Github = "https://github.com/tobfd/spicetify-websocket"
+Documentation = "https://spicetify-websocket.readthedocs.io"
+Changelog = "https://github.com/tobfd/spicetify-websocket/releases"
+
+[tool.setuptools.dynamic]
+version = {attr = "spicetify.__version__"}
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+fix = true
+
+[tool.ruff.lint]
+extend-select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "I",      # isort (Import sorting)
+    "UP",     # pyupgrade (Modern Python)
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "RUF",    # Ruff-specific rules
+]
+
+[lint.per-file-ignores]
+"examples/*" = ["T201"]
+"tests/*" = ["SLF001", "S101"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=spicetify --cov-report=term-missing --cov-report=html"
+asyncio_mode = "auto"

spicetify_websocket-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spicetify_websocket-0.1.0/spicetify/__init__.py

@@ -0,0 +1,19 @@
+__title__ = "spicetify-websocket"
+__license__ = "MIT"
+__version__ = "0.1.0"
+
+from .exceptions import NotConnectedError, RequestTimeoutError, SpicetifyError
+from .models import ArtistInfo, PlayerState, RepeatMode, TrackInfo
+from .server import SpotifyServer
+
+__all__ = [
+    "ArtistInfo",
+    "NotConnectedError",
+    "PlayerState",
+    "RepeatMode",
+    "RequestTimeoutError",
+    "SpicetifyError",
+    "SpotifyServer",
+    "TrackInfo",
+    "__version__",
+]

spicetify_websocket-0.1.0/spicetify/exceptions.py

@@ -0,0 +1,27 @@
+class SpicetifyError(Exception):
+    """Base exception for all errors raised by this library."""
+
+
+class NotConnectedError(SpicetifyError):
+    """Raised when an action is attempted without an active connection.
+
+    Args:
+        message: Human-readable error message.
+    """
+
+    def __init__(self, message="No active connection to Spicetify is available."):
+        super().__init__(message)
+
+
+class RequestTimeoutError(SpicetifyError):
+    """Raised when Spotify does not respond to a command in time.
+
+    Args:
+        command: Name of the command that timed out.
+        timeout: Timeout value in seconds.
+    """
+
+    def __init__(self, command: str, timeout: float):
+        self.command = command
+        self.timeout = timeout
+        super().__init__(f"Command '{command}' did not respond within {timeout}s.")