Skip to main content

SDK concepts

At the simplest level, the SDK provides a music player with play, pause, skip, like, dislike and volume controls. The player, upon initialization, retrieves a list of available stations from the Feed.fm servers that the player can pull music from. At any given time, a single station is the active station from which songs are retrieved for playback.

The player generates and caches a random unique client id that is sent with all network requests to track playback history and enforce playback restrictions.

The player can be commanded to play and pause music playback. All calls to the player are asynchronous, so events are emitted that indicate when songs start, elapse, and complete playback. Once the music begins, there will always be a current song with associated metadata that can be displayed to the user. Calls to like and dislike inform the Feed.fm servers how a user feels about the current song. A skip command doesn't immediately skip the current song, but rather a request is made to the server for permission to skip the song. If the skip is granted, the current song will stop and the next will begin. Otherwise, a failed skip event will announce the skip failed and music will continue.

The player maintains a public state, which will be one of the following:

  • uninitialized: the player hasn't been given a token/secret pair yet
  • unavailable: music is not available to the user for some reason
  • ready to play: the player is idle and can begin playback, but hasn't
  • offline only: the player is idle and ready to play, but only offline stations will currently work.
  • waiting for item: the player is waiting for Feed.fm to give it a song to play
  • stalled: the player is waiting for audio data for the current song (it is buffering)
  • playing: the player is actively playing a song
  • paused: the player has paused playback
  • requesting skip: the user has asked to skip the current song, and the player is waiting for permission from the feed.fm servers to skip
  • complete: the player has run out of music to play in the active station and is now sitting idle

Playback commands and playback events function the same, regardless of whether the active station is streaming radio, simulcast, on-demand, or offline.

On-demand stations make available a list of songs that can be shown to the user and passed to the player for playback.

The Feed.fm servers may provide the player with a list of remote offline stations, which are stations available for download and offline playback. The player may be asked to download a remote offline station, which results in a local offline station that is completely stored on the device and may be played even when no Internet connection is available, just like any other station. Remote offline stations may be downloaded in full at once or partially over time. Also, the player may be asked to refresh the contents of local offline stations with any newly available music.