spicetify-websocket 0.2.0

An asynchronous Python wrapper and WebSocket server for controlling the Spotify desktop client via Spicetify and the 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.

pip install spicetify-websocket

📋 Prerequisites

To use this library, ensure you have:

1. Spotify Desktop Client installed.
2. Spicetify CLI installed and configured.
3. The spicetify-connect-api extension enabled in Spicetify.

📚 Documentation & Guides

Explore the official documentation for detailed references and setup guides:

• 📖 API Reference – Full documentation for SpotifyServer, models, decorators, and exceptions.
• 💡 Code Examples – Runnable scripts for basic usage, API key auth, and WSS encryption.
• 🛠️ Deployment Guides – Step-by-step guides for local WSS setups and production VPS deployment.

🚀 Example Usage

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