v0.3.0

🚀 Release v0.3.0

Version v0.3.0 is a major upgrade featuring standardized event signatures, expanded Pydantic V2 models with rich metadata, wildcard event listening, and full Heart/Like track management.

Important

Version v0.3.0 or higher of spicetify-connect-api is required.

---

🚨 Breaking Changes

Warning

Please review your event handler signatures before upgrading from v0.2.x to v0.3.0.

1. Standardized Event Callbacks (PlayerState Payload):

   • All state-change event callbacks (@server.on_song_changed, @server.on_volume_changed, @server.on_repeat_changed, @server.on_shuffle_changed, @server.on_seek_changed, @server.on_play_pause_changed) now receive the full PlayerState snapshot object instead of individual primitive values or sub-models.
   • Migration Example:

     # OLD (v0.2.x)
     @server.on_song_changed
     def on_song(track: TrackInfo):
         print(track.title)
     
     # NEW (v0.3.0)
     @server.on_song_changed
     def on_song(state: PlayerState):
         if state.track:
             print(state.track.title)

   (Note: @server.on_ping continues to receive a UTC datetime object).

2. Internalization of Request Models:

   • Internal wire request models (PlayRequest, SetVolumeRequest, etc.) have been prefixed with _ (e.g. _PlayRequest, _SetVolumeRequest) and removed from the public module exports to maintain a clean API surface.

---

✨ New Features

This version introduces several new Pydantic models and parses significantly more metadata fields directly from Spotify:

1. PlayerState (Top-Level Snapshot)

• event_name: str | None – Name of the event that triggered the state update (e.g. "SongChanged", "VolumeChanged").
• is_hearted: bool – Whether the currently playing track is liked/hearted.
• item_index: int | None – 0-based index of the active song in the current context/playlist.
• context: PlaybackContext | None – Active context metadata object.
• restrictions: PlaybackRestrictions – Action permissions for the player.
• timestamp: datetime | None – UTC timestamp of the state snapshot.
• is_buffering: bool – Stream buffering flag.
• previous_tracks: list[TrackInfo] – History of previously played tracks in current session.
• next_tracks: list[TrackInfo] – Upcoming tracks queue.

2. New Sub-Models

• PlaybackContext: Contains uri, description (e.g. Playlist/Album title), owner, owner_url, image_url, track_count, and url.
• PlaybackRestrictions: Boolean permissions (can_pause, can_resume, can_seek, can_skip_previous, can_skip_next, can_toggle_repeat_context, can_toggle_repeat_track, can_toggle_shuffle, can_toggle_smart_shuffle).
• TrackImages: Multi-resolution cover artwork links (small, standard, large, xlarge).

3. Expanded TrackInfo & AlbumInfo

• TrackInfo: Added images: TrackImages, has_lyrics: bool | None, popularity: int | None, and is_hearted: bool | None.
• AlbumInfo: Added release_date: str | None and images: list[str].

---

• 🌐 Wildcard State Decorator (@server.on_state_changed):
  Subscribe to every player state update event using a single decorator. Access the triggering event name via state.event_name.

  @server.on_state_changed
  def on_any_update(state: PlayerState):
      print(f"[{state.event_name}] Playing: {state.is_playing} | Vol: {state.volume}%")

• 💚 Full Heart / Like Support:

  • Control liking/unliking tracks: await server.get_heart(), await server.set_heart(status), and await server.toggle_heart().
  • New event decorator: @server.on_heart_changed.
  • New attribute is_hearted available on PlayerState and TrackInfo (for the active song).

---

What's Changed

• patch: add permissions for CI content access by @tobfd in #5
• docs: repo health by @tobfd in #7
• feat: return playerstate by event by @tobfd in #8

Full Changelog: 0.2.0...0.3.0