spicetify-websocket 0.1.0__py3-none-any.whl

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/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.")

spicetify/models.py

@@ -0,0 +1,459 @@
+import uuid
+from enum import IntEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, model_serializer
+
+# --- Utility Helpers ---
+
+
+def _convert_spotify_image_url(url: str) -> str:
+    """Convert a Spotify image URL to a standard HTTP URL.
+
+    Args:
+        url: The Spotify image URL to convert.
+
+    Returns:
+        The converted HTTP URL, or the original URL if it doesn't match the expected format.
+    """
+    if url and url.startswith("spotify:image:"):
+        image_id = url.replace("spotify:image:", "")
+        return f"https://i.scdn.co/image/{image_id}"
+    return url
+
+
+def _generate_id() -> str:
+    """Generate a unique request ID."""
+    return str(uuid.uuid4())
+
+
+# --- Request Models ---
+
+
+class BaseRequest(BaseModel):
+    """Base model for requests sent to Spicetify.
+
+    The serialized form contains `requestName`, `requestId`, and a nested
+    `payload` object with the remaining fields.
+
+    Attributes:
+        requestName: The request type name sent over the wire.
+        requestId: Unique request identifier used to match responses.
+    """
+
+    requestName: str
+    requestId: str = Field(default_factory=_generate_id)
+
+    @model_serializer(mode="wrap")
+    def _serialize(self, handler) -> dict:
+        """Serialize the request into the wire format expected by Spicetify.
+
+        Returns:
+            dict: Serialized request with `requestName`, `requestId`, and
+            `payload`.
+        """
+        data = handler(self)
+
+        req_name = data.pop("requestName")
+        req_id = data.pop("requestId")
+
+        return {"requestName": req_name, "requestId": req_id, "payload": data}
+
+
+# --- Playback control requests ---
+class PlayRequest(BaseRequest):
+    """Request to start playback."""
+
+    requestName: Literal["Play"] = "Play"
+
+
+class TogglePlayRequest(BaseRequest):
+    """Request to toggle playback."""
+
+    requestName: Literal["TogglePlay"] = "TogglePlay"
+
+
+class NextSongRequest(BaseRequest):
+    """Request to skip to the next song."""
+
+    requestName: Literal["NextSong"] = "NextSong"
+
+
+class PreviousSongRequest(BaseRequest):
+    """Request to skip to the previous song."""
+
+    requestName: Literal["PreviousSong"] = "PreviousSong"
+
+
+class ForcePreviousSongRequest(BaseRequest):
+    """Request to force skip to the previous song."""
+
+    requestName: Literal["ForcePreviousSong"] = "ForcePreviousSong"
+
+
+# --- State Query Requests ---
+class GetPlayerStateRequest(BaseRequest):
+    """Request to retrieve the current player state."""
+
+    requestName: Literal["GetPlayerState"] = "GetPlayerState"
+
+
+class GetCurrentTrackRequest(BaseRequest):
+    """Request to retrieve the current track information."""
+
+    requestName: Literal["GetCurrentTrack"] = "GetCurrentTrack"
+
+
+class GetVolumeRequest(BaseRequest):
+    """Request to retrieve the current playback volume."""
+
+    requestName: Literal["GetVolume"] = "GetVolume"
+
+
+class GetPlayPauseRequest(BaseRequest):
+    """Request to retrieve the current play/pause state."""
+
+    requestName: Literal["GetPlayPause"] = "GetPlayPause"
+
+
+class PauseRequest(BaseRequest):
+    """Request to pause playback."""
+
+    requestName: Literal["Pause"] = "Pause"
+
+
+# --- Playback Setting Requests ---
+class SetShuffleRequest(BaseRequest):
+    """Request to enable or disable shuffle mode.
+
+    Attributes:
+        state: True to enable shuffle, False to disable.
+    """
+
+    requestName: Literal["SetShuffle"] = "SetShuffle"
+    state: bool = Field(..., description="True to enable shuffle, False to disable")
+
+
+class SetMuteRequest(BaseRequest):
+    """Request to mute or unmute the playback.
+
+    Attributes:
+        state: True to mute, False to unmute.
+    """
+
+    requestName: Literal["SetMute"] = "SetMute"
+    state: bool = Field(..., description="True to mute, False to unmute")
+
+
+class SeekRequest(BaseRequest):
+    """Request to seek to a specific position in the current track.
+
+    Attributes:
+        position: Position in milliseconds to seek to.
+    """
+
+    requestName: Literal["Seek"] = "Seek"
+    position: int | float = Field(..., ge=0, description="Position in milliseconds to seek to")
+
+
+class SetVolumeRequest(BaseRequest):
+    """Request to set the playback volume.
+
+    Attributes:
+        level: Desired volume level between 0.0 and 1.0.
+    """
+
+    requestName: Literal["SetVolume"] = "SetVolume"
+    level: float | int = Field(..., ge=0.0, le=1.0, description="Volume between 0.0 and 1.0")
+
+
+class SetRepeatRequest(BaseRequest):
+    """Request to change the repeat mode.
+
+    Attributes:
+        mode: Repeat mode, where 0 means off, 1 means context, and 2 means track.
+    """
+
+    requestName: Literal["SetRepeat"] = "SetRepeat"
+    mode: int = Field(..., ge=0, le=2, description="0=Off, 1=Context, 2=Track")
+
+
+class PlayUriRequest(BaseRequest):
+    """Request to start playback from a Spotify URI or URL.
+
+    Attributes:
+        uri: Spotify URI/URL to play.
+    """
+
+    requestName: Literal["PlayUri"] = "PlayUri"
+    uri: str
+
+
+# --- Metadata Models ---
+
+
+class ArtistInfo(BaseModel):
+    """Metadata for an artist.
+
+    Attributes:
+        name: Artist name.
+        uri: Spotify URI of the artist.
+    """
+
+    name: str
+    uri: str
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the artist."""
+        return f"{self.name} ({self.uri})"
+
+    @property
+    def url(self) -> str:
+        """Return the Spotify web URL for the artist.
+
+        Returns:
+            Spotify web URL for the artist.
+        """
+        return f"https://open.spotify.com/artist/{self.uri.split(':')[-1]}"
+
+
+class TrackInfo(BaseModel):
+    """Metadata for the currently playing track.
+
+    Attributes:
+        uri: Spotify URI of the track.
+        title: Track title.
+        duration_ms: Track duration in milliseconds.
+        artists: List of artists associated with the track.
+        album_name: Name of the album.
+        album_uri: Spotify URI of the album.
+        image_url: URL of the album artwork image. Default is None if not available.
+        is_explicit: Whether the track is marked as explicit. Default is False.
+    """
+
+    uri: str
+    title: str
+    duration_ms: int
+    artists: list[ArtistInfo]
+    album_name: str
+    album_uri: str
+    image_url: str | None = None
+    is_explicit: bool = False
+
+    def __str__(self) -> str:
+        """Return a human-readable string representation of the track."""
+        artist_names = ", ".join(artist.name for artist in self.artists)
+        return f"{self.title} by {artist_names} from the album '{self.album_name}'"
+
+    @property
+    def url(self) -> str:
+        """Return the Spotify web URL for the track.
+
+        Returns:
+            Spotify web URL for the track.
+        """
+        return f"https://open.spotify.com/track/{self.uri.split(':')[-1]}"
+
+    @property
+    def album_url(self) -> str:
+        """Return the Spotify web URL for the album.
+
+        Returns:
+            Spotify web URL for the album.
+        """
+        return f"https://open.spotify.com/album/{self.album_uri.split(':')[-1]}"
+
+    @property
+    def duration_seconds(self) -> float | int:
+        """Return the track duration in seconds.
+
+        Returns:
+            Track duration in seconds.
+        """
+        return self.duration_ms / 1000
+
+    @staticmethod
+    def from_payload(payload: dict[str, Any]) -> "TrackInfo":
+        """Create a TrackInfo instance from a payload dictionary.
+
+        Args:
+            payload: Payload containing track information.
+
+        Returns:
+            A :class:`TrackInfo` instance populated from the payload.
+
+        """
+        track_data = payload.get("track", {})
+        metadata = track_data.get("metadata", {})
+
+        raw_artists = track_data.get("artists", [])
+        artists = [
+            ArtistInfo(name=artist.get("name"), uri=artist.get("uri")) for artist in raw_artists
+        ]
+
+        duration = track_data.get("duration", {})
+        if isinstance(duration, dict):
+            duration_ms = duration.get("milliseconds", 0)
+        else:
+            duration_ms = int(duration) if duration else 0
+
+        images = track_data.get("images", [])
+        has_image = False
+        raw_image_url = ""
+        if images and len(images) > 0:
+            has_image = True
+            raw_image_url = images[0].get("url")
+        elif "image_url" in metadata:
+            has_image = True
+            raw_image_url = metadata.get("image_url")
+
+        image_url = _convert_spotify_image_url(raw_image_url) if has_image else None
+
+        return TrackInfo(
+            uri=track_data.get("uri", ""),
+            title=track_data.get("name", ""),
+            duration_ms=duration_ms,
+            artists=artists,
+            album_name=track_data.get("album", {}).get("name", ""),
+            album_uri=track_data.get("album", {}).get("uri", ""),
+            image_url=image_url,
+            is_explicit=track_data.get("isExplicit", False),
+        )
+
+
+# --- Playback State Models ---
+
+
+class PlayerStateEvent(BaseModel):
+    """Represents the current Spotify player state.
+
+    Attributes:
+        event: Event name emitted by the client.
+        is_playing: Whether playback is currently active.
+        volume: Current playback volume.
+        current_track: Information about the current track, if available.
+            See :class:`TrackInfo`.
+    """
+
+    event: Literal["player_state_changed"] = "player_state_changed"
+    is_playing: bool
+    volume: float
+    current_track: TrackInfo | None = None
+
+
+class RepeatMode(IntEnum):
+    """Enumeration of supported repeat modes."""
+
+    OFF = 0
+    CONTEXT = 1
+    TRACK = 2
+
+
+class PlayerState(BaseModel):
+    """Represents the current Spotify player state.
+
+    Attributes:
+        is_playing: Whether playback is currently active.
+        position_ms: Current playback position in milliseconds.
+        duration_ms: Total duration of the current track in milliseconds.
+        shuffle: Whether shuffle mode is enabled.
+        smart_shuffle: Whether smart shuffle mode is enabled.
+        repeat_mode: Current repeat mode. See :class:`RepeatMode`.
+        track: Information about the current track, if available.
+            See :class:`TrackInfo`.
+        context_uri: Spotify URI of the current playback context, if available.
+    """
+
+    is_playing: bool
+    position_ms: int
+    duration_ms: int
+    shuffle: bool
+    smart_shuffle: bool
+    repeat_mode: RepeatMode
+    track: TrackInfo | None = None
+    context_uri: str | None = None
+
+    def __str__(self) -> str:
+        """Return a human-readable string of the PlayerState"""
+        track_info = str(self.track) if self.track else "No track playing"
+        return (
+            f"PlayerState:\n"
+            f"  Is Playing: {self.is_playing}\n"
+            f"  Position: {self.position_ms} ms\n"
+            f"  Duration: {self.duration_ms} ms\n"
+            f"  Shuffle: {self.shuffle}\n"
+            f"  Smart Shuffle: {self.smart_shuffle}\n"
+            f"  Repeat Mode: {self.repeat_mode.name}\n"
+            f"  Track Info: {track_info}\n"
+            f"  Context URI: {self.context_uri}"
+        )
+
+    @property
+    def position_seconds(self) -> float | int:
+        """Return the current playback position in seconds.
+
+        Returns:
+            Current playback position in seconds.
+        """
+        return self.position_ms / 1000
+
+    @property
+    def duration_seconds(self) -> float | int:
+        """Return the total duration of the current track in seconds.
+
+        Returns:
+            Total duration of the current track in seconds.
+        """
+        return self.duration_ms / 1000
+
+    @property
+    def context_url(self) -> str | None:
+        """Return the Spotify web URL for the current playback context.
+
+        Returns:
+            Spotify web URL for the context, or None if not available.
+        """
+        if self.context_uri:
+            return f"https://open.spotify.com/{self.context_uri.split(':')[1]}/{self.context_uri.split(':')[-1]}"
+        return None
+
+    @staticmethod
+    def from_payload(payload: dict[str, Any]) -> "PlayerState":
+        """Create a PlayerState instance from a payload dictionary.
+
+        Args:
+            payload: Payload containing player state information.
+
+        Returns:
+            A :class:`PlayerState` instance populated with data from the
+            payload.
+
+        """
+        track = None
+        item = payload.get("item")
+        if item and isinstance(item, dict):
+            track = TrackInfo.from_payload({"track": item})
+
+        context = payload.get("context", {})
+        context_uri = context.get("uri") if isinstance(context, dict) else None
+
+        is_paused = payload.get("isPaused", True)
+        is_playing = not is_paused
+
+        position_ms = payload.get("positionAsOfTimestamp", 0)
+        duration_ms = payload.get("duration", 0)
+
+        shuffle = payload.get("shuffle", False)
+        smart_shuffle = payload.get("smartShuffle", False)
+        repeat_mode = RepeatMode(payload.get("repeat", 0))
+
+        return PlayerState(
+            is_playing=is_playing,
+            position_ms=position_ms,
+            duration_ms=duration_ms,
+            shuffle=shuffle,
+            smart_shuffle=smart_shuffle,
+            repeat_mode=repeat_mode,
+            track=track,
+            context_uri=context_uri,
+        )

spicetify/server.py

@@ -0,0 +1,695 @@
+import asyncio
+import inspect
+import json
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from typing_extensions import Self
+from websockets.asyncio.server import Server, ServerConnection, serve
+
+from .exceptions import NotConnectedError, RequestTimeoutError, SpicetifyError
+from .models import (
+    BaseRequest,
+    ForcePreviousSongRequest,
+    GetCurrentTrackRequest,
+    GetPlayerStateRequest,
+    GetPlayPauseRequest,
+    GetVolumeRequest,
+    NextSongRequest,
+    PauseRequest,
+    PlayerState,
+    PlayRequest,
+    PlayUriRequest,
+    PreviousSongRequest,
+    RepeatMode,
+    SeekRequest,
+    SetMuteRequest,
+    SetRepeatRequest,
+    SetShuffleRequest,
+    SetVolumeRequest,
+    TogglePlayRequest,
+    TrackInfo,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class SpotifyServer:
+    """WebSocket server for controlling Spotify via Spicetify.
+
+    The server starts a WebSocket listener, waits for a Spicetify client to
+    connect, and exposes convenience methods for playback control and state
+    queries.
+
+    Note:
+        This class is asynchronous and is intended to be used as an async
+        context manager.
+
+    Attributes:
+        host: Hostname to bind the server to.
+        port: Port to bind the server to.
+        websocket: Active WebSocket connection, if any.
+        server: Running WebSocket server instance, if any.
+
+    Examples:
+        >>> import asyncio
+        >>> from spicetify import SpotifyServer
+        >>>
+        >>> async def main():
+        ...     async with SpotifyServer() as server:
+        ...         await server.wait_for_connection()
+        ...
+        ...         await server.set_repeat(RepeatMode.CONTEXT)
+        ...
+        ...         @server.on_play_pause_changed
+        ...         def callback(player: PlayerState):
+        ...             print(player)
+        ...             if player.track:
+        ...                 print(", ".join([artist.name for artist in player.track.artists]))
+        ...
+        ...         await asyncio.Event().wait()
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 9090) -> None:
+        self.host = host
+        self.port = port
+        self.websocket: ServerConnection | None = None
+        self.server: Server | None = None
+        self._pending_requests: dict[str, asyncio.Future] = {}
+        self._connected_event = asyncio.Event()
+        self._event_callbacks: dict[str, list[Callable]] = {}
+        self._background_tasks: set[asyncio.Task[Any]] = set()
+
+    # --- Event Registration ---
+
+    def on(self, event_name: str) -> Callable[[Callable[[Any], Any]], Callable[[Any], Any]]:
+        """Register a callback for a Spicetify event.
+
+        The decorated callback is invoked whenever the matching event is
+        received from the connected Spicetify client. Callback names are
+        matched case-insensitively.
+
+        Args:
+            event_name: Name of the Spicetify event to subscribe to.
+
+        Returns:
+            A decorator that registers the given function as event
+            handler.
+
+        Note:
+            This method is a decorator factory and must be called with the
+            event name, for example ``@server.on("SongChanged")``.
+
+        """
+
+        def decorator(func: Callable[[Any], Any]) -> Callable[[Any], Any]:
+            """Attach `func` as a callback for the configured event.
+
+            Args:
+                func: The callback function to register.
+
+            Returns:
+                The original function, unchanged.
+
+            """
+            key = event_name.lower()
+            if key not in self._event_callbacks:
+                self._event_callbacks[key] = []
+            self._event_callbacks[key].append(func)
+            return func
+
+        return decorator
+
+    # --- Convenience Event Decorators ---
+
+    def on_initial_state(self, func: Callable[[PlayerState], Any]) -> Callable[[PlayerState], Any]:
+        """Register a callback for the ``InitialState`` event.
+
+        The callback receives a :class:`PlayerState` instance parsed from the
+        initial player data.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_initial_state``.
+
+        Args:
+            func: Callback that accepts the initial player state.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("InitialState")(func)
+
+    def on_song_changed(self, func: Callable[[TrackInfo], Any]) -> Callable[[TrackInfo], Any]:
+        """Register a callback for the ``SongChanged`` event.
+
+        The callback receives a :class:`TrackInfo` instance for the current
+        song.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_song_changed``.
+
+        Args:
+            func: Callback that accepts the current track information.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("SongChanged")(func)
+
+    def on_play_pause_changed(
+        self, func: Callable[[PlayerState], Any]
+    ) -> Callable[[PlayerState], Any]:
+        """Register a callback for the ``PlayPauseChanged`` event.
+
+        The callback receives a :class:`PlayerState` instance representing the
+        current playback state.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_play_pause_changed``.
+
+        Args:
+            func: Callback that accepts the current player state.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("PlayPauseChanged")(func)
+
+    def on_volume_changed(self, func: Callable[[float | int], Any]) -> Callable[[float | int], Any]:
+        """Register a callback for the ``VolumeChanged`` event.
+
+        The callback receives the current volume as a number in the range
+        ``0`` to ``100``.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_volume_changed``.
+
+        Args:
+            func: Callback that accepts the current volume percentage.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("VolumeChanged")(func)
+
+    def on_repeat_changed(self, func: Callable[[RepeatMode], Any]) -> Callable[[RepeatMode], Any]:
+        """Register a callback for the ``RepeatChanged`` event.
+
+        The callback receives a :class:`RepeatMode` value.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_repeat_changed``.
+
+        Args:
+            func: Callback that accepts the current repeat mode.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("RepeatChanged")(func)
+
+    def on_shuffle_changed(self, func: Callable[[bool], Any]) -> Callable[[bool], Any]:
+        """Register a callback for the ``ShuffleChanged`` event.
+
+        The callback receives ``True`` or ``False`` to indicate whether
+        shuffle is enabled.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_shuffle_changed``.
+
+        Args:
+            func: Callback that accepts the shuffle state.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("ShuffleChanged")(func)
+
+    def on_seek_changed(self, func: Callable[[int | float], Any]) -> Callable[[int | float], Any]:
+        """Register a callback for the ``SeekChanged`` event.
+
+        The callback receives the seek position in milliseconds.
+
+        Note:
+            Use this decorator without parentheses, for example
+            ``@server.on_seek_changed``.
+
+        Args:
+            func: Callback that accepts the current seek position.
+
+        Returns:
+            The original callback, unchanged.
+
+        """
+        return self.on("SeekChanged")(func)
+
+    # -------------------------------
+
+    # --- Event Dispatch ---
+
+    async def _dispatch_event(self, event_name: str, payload: dict[str, Any]) -> None:
+        """Dispatch an incoming event to all registered callbacks.
+
+        The event payload is converted into a typed Python object when a known
+        event type is received. Synchronous callbacks are invoked directly,
+        while coroutine callbacks are scheduled as background tasks.
+
+        Args:
+            event_name: Name of the received event.
+            payload: Event payload received from Spicetify.
+
+        """
+        key = event_name.lower()
+        callbacks = self._event_callbacks.get(key, [])
+
+        if not callbacks:
+            return
+
+        parsed_data = self._parse_event_payload(event_name, payload)
+
+        for callback in callbacks:
+            # noinspection broad-exception
+            try:
+                if inspect.iscoroutinefunction(callback):
+                    task = asyncio.create_task(callback(parsed_data))
+                    self._background_tasks.add(task)
+                    task.add_done_callback(self._background_tasks.discard)
+                else:
+                    callback(parsed_data)
+            except Exception:
+                logger.exception("Error executing the event callback for %s", event_name)
+
+    @staticmethod
+    def _parse_event_payload(event_name: str, payload: dict[str, Any]) -> Any:
+        """Convert a raw event payload into a typed Python value.
+
+        Args:
+            event_name: Name of the event that produced the payload.
+            payload: Raw payload as received from Spicetify.
+
+        Returns:
+            A typed representation for known events, or the raw payload for unknown events.
+
+        """
+        key = event_name.lower()
+
+        if key == "initialstate":
+            return PlayerState.from_payload(payload.get("playerData", payload))
+        elif key == "playpausechanged":
+            return PlayerState.from_payload(payload.get("playerState", payload))
+        elif key == "songchanged":
+            return TrackInfo.from_payload(payload)
+        elif key == "volumechanged":
+            return payload.get("level", 0) * 100
+        elif key == "repeatchanged":
+            return RepeatMode(payload.get("mode"))
+        elif key == "shufflechanged":
+            return payload.get("state")
+        elif key == "seekchanged":
+            return payload.get("position")
+
+        return payload
+
+    # --- Async Context Manager ---
+
+    async def __aenter__(self) -> Self:
+        """Enter the async context manager.
+
+        Returns:
+            The running server instance.
+        """
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit the async context manager and stop the server."""
+        await self.stop()
+
+    # --- Connection Management ---
+
+    async def wait_for_connection(self, timeout: float | None = None) -> None:
+        """Wait for a Spicetify client connection.
+
+        Args:
+            timeout: Maximum time to wait in seconds. If ``None``, waits indefinitely.
+                Defaults to ``None``.
+
+        Raises:
+            NotConnectedError: If timeout expires before connection is established.
+        """
+        if self.websocket is not None:
+            return
+
+        if timeout is None:
+            await self._connected_event.wait()
+        else:
+            try:
+                await asyncio.wait_for(self._connected_event.wait(), timeout=timeout)
+            except asyncio.TimeoutError:
+                logger.warning("Connection timeout after %f seconds", timeout)
+                raise NotConnectedError("Timeout: Spicetify did not connect in time.") from None
+
+    # --- Server Lifecycle ---
+
+    async def _send_command(self, request: BaseRequest, timeout: float = 5.0) -> dict:
+        """Send a command request to Spicetify and wait for its response.
+
+        Args:
+            request: The request object to send.
+            timeout: Maximum time to wait for a response. Defaults to ``5.0``.
+
+        Returns:
+            The response data from Spicetify.
+
+        Raises:
+            NotConnectedError: If no active WebSocket connection exists.
+            RequestTimeoutError: If the response doesn't arrive within timeout.
+        """
+        if not self.websocket:
+            raise NotConnectedError()
+
+        loop = asyncio.get_running_loop()
+        future = loop.create_future()
+
+        self._pending_requests[request.requestId] = future
+
+        json_data = request.model_dump_json()
+        logger.debug("Send: %s", json_data)
+        await self.websocket.send(json_data)
+
+        try:
+            response_data = await asyncio.wait_for(future, timeout=timeout)
+            return response_data
+        except asyncio.TimeoutError:
+            self._pending_requests.pop(request.requestId, None)
+            raise RequestTimeoutError(request.requestName, timeout) from None
+
+    async def start(self) -> None:
+        """Start the WebSocket server."""
+        self.server = await serve(self._handler, self.host, self.port)
+        logger.info("Server started on %s:%d", self.host, self.port)
+
+    async def stop(self) -> None:
+        """Stop the WebSocket server and close any active connection."""
+        if self.websocket:
+            await self.websocket.close()
+            self.websocket = None
+            logger.info("WebSocket connection closed.")
+        if self.server:
+            self.server.close()
+            await self.server.wait_closed()
+            logger.info("Server has stopped.")
+
+    # --- WebSocket Message Handling ---
+
+    async def _handler(self, websocket: ServerConnection) -> None:
+        """Handle incoming WebSocket messages and resolve pending requests.
+
+        Args:
+            websocket: The WebSocket connection from a client.
+        """
+        self.websocket = websocket
+        self._connected_event.set()
+        logger.info(f"Connection established with {websocket.remote_address[0]}.")
+        try:
+            async for message in websocket:
+                try:
+                    data = json.loads(message)
+
+                    event_name = data.get("eventName")
+                    request_id = data.get("requestId")
+
+                    if (
+                        event_name == "Response"
+                        and request_id
+                        and request_id in self._pending_requests
+                    ):
+                        future = self._pending_requests.pop(request_id)
+                        if not future.done():
+                            if data.get("success") is False:
+                                msg = data.get("message", "Unknown Spicetify error")
+                                future.set_exception(SpicetifyError(f"Request failed: {msg}"))
+                            else:
+                                future.set_result(data)
+                            logger.debug(
+                                "Received response for requestId: %s, Data: %s",
+                                request_id,
+                                data,
+                            )
+
+                    elif event_name:
+                        logger.debug("Event received: %s: %s", event_name, data.get("payload"))
+                        await self._dispatch_event(event_name, data.get("payload", {}))
+
+                    else:
+                        logger.debug("Event received: %s: %s", event_name, data.get("payload"))
+                except json.JSONDecodeError:
+                    logger.error("JSON parsing error: %s", message)
+        finally:
+            self.websocket = None
+            self._connected_event.clear()
+            logger.info("Connection lost.")
+
+    # --- Playback Controls ---
+
+    async def play(self) -> None:
+        """Send a command to start playback.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(PlayRequest())
+
+    async def pause(self) -> None:
+        """Send a command to pause playback.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(PauseRequest())
+
+    async def next_song(self) -> None:
+        """Send a command to play the next song.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(NextSongRequest())
+
+    async def previous_song(self, force: bool = False) -> None:
+        """Send a command to play the previous song.
+
+        Notes:
+            If force is ``True``, the previous song will be played
+            regardless of the current playback position.
+            If force is ``False``, it could either restart the current
+            song or play the previous song based on the playback position.
+
+        Args:
+            force: If ``True``, ensures the previous song is played.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        if force:
+            await self._send_command(ForcePreviousSongRequest())
+        else:
+            await self._send_command(PreviousSongRequest())
+
+    async def set_repeat(self, mode: RepeatMode) -> RepeatMode:
+        """Set the repeat mode for playback.
+
+        Args:
+            mode: The repeat mode to set (off, context, track).
+
+        Returns:
+            The repeat mode that was set.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(SetRepeatRequest(mode=mode))
+        return mode
+
+    async def set_shuffle(self, state: bool) -> bool:
+        """Enable or disable shuffle mode.
+
+        Args:
+            state: ``True`` to enable shuffle, ``False`` to disable.
+
+        Returns:
+            The shuffle state that was set.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(SetShuffleRequest(state=state))
+        return state
+
+    async def set_mute(self, state: bool) -> bool:
+        """Enable or disable mute for playback.
+
+        Args:
+            state: ``True`` to mute, ``False`` to unmute.
+
+        Returns:
+            The mute state that was set.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(SetMuteRequest(state=state))
+        return state
+
+    async def toggle_play(self) -> None:
+        """Send a command to toggle playback (play/pause).
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(TogglePlayRequest())
+
+    async def set_volume(self, percent: float) -> float | int:
+        """Set Spotify volume level.
+
+        Args:
+            percent: Volume level between 0 and 100.
+
+        Returns:
+            The volume level that was set.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+            ValueError: If percent is not between 0 and 100.
+        """
+        if not 0 <= percent <= 100:
+            raise ValueError("percent must be between 0 and 100.")
+        await self._send_command(SetVolumeRequest(level=(percent / 100)))
+        return percent
+
+    async def play_uri(self, uri: str) -> str:
+        """Play a specific Spotify URI.
+
+        Args:
+            uri: Spotify URI or URL to play.
+
+        Returns:
+            The URI/URL that was played.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self._send_command(PlayUriRequest(uri=uri))
+        return uri
+
+    async def play_url(self, url: str) -> str:
+        """Alias for play_uri. Play a specific Spotify URL.
+
+        Args:
+            url: Spotify URL to play.
+
+        Returns:
+            The URL that was played.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        await self.play_uri(uri=url)
+        return url
+
+    async def seek(self, position: float) -> int | float:
+        """Seek to a specific position in the current track.
+
+        Args:
+            position: Position in milliseconds to seek to.
+
+        Returns:
+            The position that was sought to.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+            ValueError: If position is negative.
+        """
+        if not position >= 0:
+            raise ValueError("position must be greater than or equal to 0.")
+        await self._send_command(SeekRequest(position=position))
+        return position
+
+    # --- Playback State Queries ---
+
+    async def get_player_state(self) -> PlayerState:
+        """Get the current playback state from Spicetify.
+
+        Returns:
+            A ``PlayerState`` object containing the current playback state.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        response = await self._send_command(GetPlayerStateRequest())
+        return PlayerState.from_payload(response.get("payload", {}).get("playerData", {}))
+
+    async def get_is_playing(self) -> bool:
+        """Get the current play/pause state from Spicetify.
+
+        Returns:
+            ``True`` if currently playing, ``False`` if paused.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        response = await self._send_command(GetPlayPauseRequest())
+        return response.get("payload", {}).get("isPlaying", False)
+
+    async def get_volume(self) -> float | int:
+        """Get the current volume level from Spicetify.
+
+        Returns:
+            The current volume level between ``0`` and ``100``.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        response = await self._send_command(GetVolumeRequest())
+        return response.get("payload", {}).get("level", 0) * 100
+
+    async def get_current_track(self) -> TrackInfo:
+        """Get the current track information from Spicetify.
+
+        Returns:
+            A ``TrackInfo`` object containing details about the current track.
+
+        Raises:
+            NotConnectedError: If not connected to Spicetify.
+            RequestTimeoutError: If Spicetify doesn't respond in time.
+        """
+        response = await self._send_command(GetCurrentTrackRequest())
+        return TrackInfo.from_payload(response.get("payload", {}))

spicetify_websocket-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+spicetify/__init__.py,sha256=J5RW22mxf1ukLB8Mxu5s4M_k6JoJXEPDtfbfSF8836E,477
+spicetify/exceptions.py,sha256=4OW8SLQFujRY3ZFkc8PBlsfmgaVYMra95sZdgTK8ek8,850
+spicetify/models.py,sha256=Ww71uwV6NbeIvYAFj8Fs66vsMhJK5l9XWix-mHW0t1c,13788
+spicetify/server.py,sha256=0TD_nptLSCIb0fNtlzqBAMwp8L9eOXhD6s4FU4VQeuo,24100
+spicetify_websocket-0.1.0.dist-info/licenses/LICENSE,sha256=zht6N0Z-g7To_wE77T80ci3UfXA0LA-PofRub-k1-ok,1071
+spicetify_websocket-0.1.0.dist-info/METADATA,sha256=s6fk9E0HMHNxMWoP9jzo3mSALyCgHddbbcT1xOo8p7g,5320
+spicetify_websocket-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+spicetify_websocket-0.1.0.dist-info/top_level.txt,sha256=-lJY1CHEqqFMWhl2Zl_ih6foLtRJ4ZQkmPMRFLsNqE0,10
+spicetify_websocket-0.1.0.dist-info/RECORD,,

spicetify_websocket-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spicetify_websocket-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+spicetify