SDK Overview
Our SDKs can handle audio playback and native device control integration on various platforms. While you build the user interface, the SDK provides various supporting views and controllers to assist. We offer the following SDKs:
Shared 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 subset of the available stations from the Feed.fm servers that the player can pull music from. The player can also search the full set of available stations to find one to play. At any given time, a single station is the active station from which songs are retrieved for playback.
In order to match end users with music available in their territory, the Feed.fm SDK automatically determines a user's location by geo-mapping their IP address.
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 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.
The player maintains a public state, which will be one of the following:
uninitialized: the player hasn't been given a token/secret pair yetunavailable: music is not available for the current userready to play: the player is idle and can begin playback when there is still music available to play.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 playstalled: the player is waiting for audio data for the current song (it is buffering)playing: the player is actively playing a songpaused: the player has paused playbackrequesting skip: the user has asked to skip the current song, and the player is waiting for permission from the Feed.fm servers to skipcomplete: the player has run out of music to play in the active station and is now sitting idle because there is no more music left to play in the station.
SDK Features
Crossfade
This is a short fade in/out between songs that aims to eliminate momentary silence when one song ends and another begins. This value can be configured on a station level for all songs in the station. Contact your Customer Success Manager if you want to set up crossfades.
Like/Dislike
Our SDKs support like/dislike reporting for a song in order to send feedback to our curation team. This functionality is only available to users in the US. A dislike 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.
Offline Streaming
Stations featuring music from our Global catalog can be configured to be played offline through our iOS and Android SDKs only. This is useful when a user’s internet connection is unavailable or unstable. For compatible stations, music can be downloaded locally in the client for offline use. When streaming offline, music is able to be played sequentially.
The Feed.fm servers may provide the player with a list of 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.
Contact your Customer Success Manager if you want to enable offline playback. See our recipe for Offline Playback for configuration tips.
Skip
Our SDK lets users skip to the next song in the station while a song is currently streaming. Skip availability varies by geographic area, and the SDK manages making it available or not — the player reports whether the current song can be skipped and announces changes to that status, so your app only needs to show or hide its skip button accordingly. Users are generally permitted to skip up to 6 songs per hour. If they reach that threshold, we won’t change the song after a skip is requested (recommended to disable the UI button in this case).
Station Images
While Feed.fm does not currently support album artwork, we do offer the ability to add custom images for each of your stations. Please contact your Customer Success Manager if you’re interested in this feature.
Track Metadata
The Feed.fm SDK delivers, by default, song level metadata to all clients: song title, artist name, release (album) name, and song duration. In addition, the Feed.fm SDK can deliver custom station-level metadata to your app. Contact your Customer Success Manager if you wish to add custom metadata.
Volume Control
Our dual stream technology allows you to stream Feed.fm as a soundtrack to your video or audio narration. By maintaining a separate stream, your users can control the volume of the Feed.fm station independently from the audio inherent in the video.