Overview
The Android SDK is written in Kotlin, works back to API 23, and is compiled with the
latest released Android API. The SDK is available as an .aar via The Central Repository
or from our GitHub Android SDK Release Page.
The SDK depends on Google's ExoPlayer for audio playback, as we've found that to work best in multiple environments. Because of changes in ExoPlayer's API and the difficulties involved in using different ExoPlayer versions at the same time, we publish multiple versions of our SDK, each linked to a different ExoPlayer version. If you are using Jetpack Media3 library you don't need to worry about exoplayer compatibility and should use the default version.
The Android SDK is kept up to date with all our latest features and handles integration with Android Notifications for lock screen playback control.
For example purposes we have 2 fully functional music player interfaces available as Android Studio projects on GitHub. The first is called RadioPlayer and is available at github.com/feedfm/AndroidSDK2-Radioplayer. This player implements a simple tab interface to let the user switch between and control 2-3 streaming radio stations. The second music player is called RadioPlayer 2, is available at github.com/feedfm/AndroidSDK2-Radioplayer-2, and supports any number of stations and all different station types (streaming, on-demand, simulcast and offline).
Concepts
The SDK centers around two classes FeedAudioPlayer and FeedPlayerService. FeedAudioPlayer presents a fully functional music player that can play and stream music from the Feed.fm servers. FeedPlayerService is an optional class that can be used to retrieve and manage a singleton FeedAudioPlayer instance that is tied to an Android Foreground Service and Notification so that music can continue while your app is backgrounded and music can be controlled from the lock screen and media controls. If you do not need a service We recommend creating FeedAudioPlayer directly using its builder instead of using FeedPlayerService
Because virtually all functionality in the FeedAudioPlayer takes place asynchronously, clients may register implementations of the various listener interfaces to receive notification of player events.
The FeedAudioPlayer is initialized with a token and secret before playback becomes available. The FeedAudioPlayer uses those credentials to contact the Feed.fm server, confirm that the client is in a region licensed for music playback, and retrieve the list of stations that the user may pull music from.
The FeedPlayerService takes care of managing lock screen integration, notifications, audio ducking, and playback controls. There are FeedAudioPlayer methods setArtwork() and setNotificationStyle() that allow clients to customize the layout and imagery used for the lock screen and notifications.
Minimal integration
To minimally get music playback started in your application, add the following to your build.gradle file
compile 'fm.feed.android:player-sdk:latest'
Assign token and secret
The following call should be made to initialize FeedAudioPlayer and begin communication with the service. While you can call the constructors for FeedAudioPlayer we recommend using the builder.
new FeedAudioPlayer.Builder(getApplicationContext(), "demo", "demo").setAvailabilityListener(new AvailabilityListener() {
@Override
public void onPlayerAvailable(@NonNull FeedAudioPlayer player) {
// player is now ready, save its reference for later use
mPlayer = player;
// get the station list
StationList list = player.getStationList();
//set the correct station
player.setActiveStation(list.getFirst(),false);
//call play
player.play();
}
@Override
public void onPlayerUnavailable(@NonNull Exception e) {
// Player is not available, the the user does not have a correct location or feed servers could not be reached.
}
}).build();
Since this is a crucial call to initialize the SDK if it fails due to network error the player will be useless, therefore we recommend either retrying the call in case of a failure or setting FeedAudioPlayer.autoNetworkRetry = true to enable automatic retrying.
Your token and secret values are provided to you when you sign up with Feed.fm, and will give your app access to your custom stations. Until you have them, you can use the "demo" string above, or one of the following strings for your token and secret value:
FeedPlayerService
If clients desire, they can instead create a FeedAudioPlayer singleton instance using FeedPlayerService using one of its public constructors. This will allow use of Android Foreground Service and Notification so that music can continue while your app is backgrounded and music can be controlled from the lock screen and media controls. This can be useful if your app does not have a service of its own and expects to be backgrounded but needs the music to keep going.
FeedPlayerService.initialize(getApplicationContext(), "demo", "demo");
To access the player singleton use an availability listener.
FeedPlayerService.getInstance(new AvailabilityListener() {
@Override
public void onPlayerAvailable(@NonNull FeedAudioPlayer player) {
}
@Override
public void onPlayerUnavailable(@NonNull Exception e) {
}
});
States
Before you start the implementation its important to familirize yourself with SDK states so you can react to them accordingly. Here you can find a list of states for FeedAudioPlayer and what they mean.
Testing credentials
demo demo 3 simple stations with no skip limits.
counting counting one station with short audio clips of a voice speaking a number. Useful for testing song transitions.
badgeo badgeo this simulates the response from the server when the client is not in a region licensed play music.