spicetify-websocket 0.1.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, 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.

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.

🚀 Example Usage

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