There are 4 types in XPSL: user, room, track, playlist. This blog post lists the functional requirements for each of these types.

XPSL User #

  • A user must have access to either Spotify or Apple Music
  • A user must authorise XPSL for their Spotify and/or Apple Music account
  • User can only belong to 1 room
  • User can create a room or join a room once they have authorised XPSL to access Spotify and/or Apple Music
  • XPSL will refresh Spotify access token on the user’s behalf
  • Each XPSL user has a unique ID
  • A user must have a display name
  • A user could have a short name
  • XPSL user client is a NATS client that subscribe to a XPSL Room (NATS Topic)

XPSL Room #

  • Each room has a group of users who manage a shared playlist
  • Room is a NATS topic that multiple users can subscribe to
  • Each room has a topic ID of xpsl-room-
  • Each room can have 1 or more users. If there are no users in the room, the room is deleted.
  • A user can only have 1 room
  • Each room can only have 1 playlist
  • Each room broadcast to subscribers events emitted from playlist controls (play, pause, next, previous, add, remove) and events from users interacting with the room (leave, join)
  • Rooms track currently playing track
  • Users can input share link from Spotify and Apple Music
  • Users can search for songs. Only shared results from Spotify and Apple Music are shown.

XPSL Track #

  • Track has a unique ISRC
  • Track has a name, album, artists, a single ISRC, Spotify and/or Apple Music links
  • Track can belong to multiple playlists

XPSL Playlist #

  • A playlist can belong to only 1 room
  • A playlist can contain multiple tracks
  • Playlists emit track add and remove events
  • Playlists emit play, pause, next, previous events, each of this event must contain the track ISRC, Spotify link and/or Apple Music link

Getting track information from Spotify / Apple Music #

  • XPSL stores Spotify access token from the user
  • XPSL stores Apple Music access token from the developer
  • When looking up a song in Spotify, a random access token from a user is used
  • When looking up a song in Apple Music, the developer’s access token is used
  • If a user inputs a Spotify share link, the track’s metadata are retrieved using that user’s access token - unless track metadata is already present
  • If a user inputs an Apple Music share link, the track’s metadata are retrieved using the developer’s access token

Note: NATS.io is not a hard requirement