Skip navigation links

Feed.fm SDK version 5.2.8

feed.fm logo

See: Description

Packages 
Package Description
fm.feed.android.playersdk  
fm.feed.android.playersdk.models  
feed.fm logo

The Feed.fm Music SDK For Android.

Overview

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 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.

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 FeedPlayerService must be 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 (FeedAudioPlayer.setArtwork(android.graphics.Bitmap) and FeedAudioPlayer.setNotificationStyle(fm.feed.android.playersdk.models.NotificationStyle)) 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, do the following: Add

 compile 'fm.feed.android:player-sdk:5.2.8'
to your build.gradle file

Assign token and secret

Place the following call in your Application.onCreate() method to begin communication with the service:

 FeedPlayerService.initialize(getApplicationContext(), "demo", "demo");

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:

demo 3 simple stations with no skip limits.
counting one station with short audio clips of a voice speaking a number. Useful for testing song transitions.
badgeo this simulates the response from the server when the client is not in a region licensed play music.

Conditionally expose music controls

In your Activity that exposes player functionality, you should default to not making music visible or available to the user, and then register a listener with the FeedPlayerService.

Update the UI to expose music controls when music does come available. For instance, add the following code to your Activity.onCreate(android.os.Bundle) method:

    FeedPlayerService.getInstance(new FeedAudioPlayer.AvailabilityListener() {
        public void onPlayerAvailable(FeedAudioPlayer player) {
            //   Save reference to instance
            mFeedPlayer = player;

            // .. enable player control buttons here

            //   Optionally queue up audio data to reduce lag when the user hits play:
            //   player.prepareStations();

            //   optionally start playing music immediately with:
            //   player.play();

            //   .. or do nothing, and call 'player.play()' when the user
            //   wants to start music

            //   optionally customize the notification style:
            //   NotificationStyle ns = new NotificationStyle()
            //        .setColor(Color.RED)
            //        .setSmallIcon(R.drawable.my_funky_icon);
            //   player.setNotificationStyle(ns);

            //   Enable cross fading:
            //   player.setCrossFadeInEnabled(true)

            //    Add Listeners

            //    player.addPlayListener(MainActivity.this);
            //    player.addStateListener(MainActivity.this);
            //    player.addLikeStatusChangeListener(MainActivity.this);
            //    player.prepareToPlay(MainActivity.this);
        }

            public void onPlayerUnavailable(Exception e) {
            // .. hide player buttons if they aren't already
            // hidden, because music isn't available to this user
            }

    });

Demo app

        https://github.com/feedfm/AndroidSDK2-Radioplayer
    

Proguard Rules

If you are using proguard, no additional rules are needed as the library contains proguard settings that would be auto-merged in client apps proguard rules.

Change log

This section has been moved to https://github.com/feedfm/Android-SDK/releases
5.1.7
  • Fix for music auto stopping
  • Added Proguard rules to the Library
  • Bump support library to 27.0.2
5.1.3
  • 'out of music' error still wasn't being propagated to clients. It is now.
  • Revert to support library 26.0.2 for clients that haven't moved past it
5.1.2
  • Properly handle 'out of music' error, which was improperly being marked as an unhandled error
5.1.1
  • Explicitly handle cancelled network requests
  • Prevent simultaneous skip requests
  • All logging can be filtered with 'fm.feed'
5.0.8
  • Support for API 27
  • Removed redundancies
5.0.7
  • Added buffering time tracker for each song
  • Fixed crash in ExoMixingPlayer
5.0.6
  • Changes to volume normalization
  • Null Pointer Exception bugfix
5.0.7
  • Added volume normalization
  • Bug fix - player stuck in waiting_for_item state

Upgrading from 4.x

Our 5.x Android SDK has been rewritten to operate more similarly to the [previously more advanced] iOS version. The public footprint of the library is fairly small and the basic operations haven't changed. The portions of the library that have changed are documented below.

FeedAudioPlayer Singleton / Initialization

In the 4.x version of the library, there was a singleton available via the Player.getInstance() call. That singleton created and managed a Player instance, which was tied [behind the scenes] to an Android Service. In the 5.x version of the library a new class, fm.feed.android.playersdk.FeedPlayerService, creates and maintains a singleton FeedAudioPlayer and associates it with an Android Service. To more clearly indicate that the FeedAudioPlayer may not be used until it has been created and contacted Feed.fm to determine that music is available for the current client, the FeedPlayerService will only return a reference to the FeedAudioPlayer after successful initialization.

4.x SDK clients would initialize the player in an Application subclass with:

Player.setTokens(getApplicationContext(), "demo", "demo");
mPlayer = Player.getInstance();

The 5.x SDK should be used as follows:

FeedPlayerService.initialize(getApplicationContext(), "demo", "demo")
FeedPlayerService.getInstance(new FeedAudioPlayer.AvailabilityListener() {
  public void onPlayerAvailable(FeedAudioPlayer player) {
    mPlayer = player;

    // expose music player to clients
  }

  public void onPlayerUnavailable(Exception e) {
    // no music is available
  }
});

The SDK begins requesting access to music with the initialize() call, and one of the onPlayerAvailable() and onPlayerUnavailable() methods will be called as soon as the SDK knows if music is available or not.

The FeedPlayerService.getInstance() call can be placed within the onCreate() method of activities that expose player functionality, and one of the two methods in the listener is guaranteed to be called exactly once.

If clients desire, they can create a FeedAudioPlayer instance directly using one of its public constructors. This prevents music the SDK from creating and managing an Android Service and creating and updating Notifications. It is not recommended to use this direct constructor if your app is planning on playing music while backgrounded.

Player States

The 5.x FeedAudioPlayer has a reduced number of states that the player can be in. The mapping from old 4.x PlayerState to the new 5.x FeedAudioPlayer.State looks like the following:

4.x PlayerState description 5.x FeedAudioPlayer.State change from 4.x -> 5.x
UNINITIALIZED player hasn't contacted feed.fm yet UNINITIALIZED same behavior
READY player is ready to begin music playback READY_TO_PLAY same behavior
TUNING player is loading audio for playback none removed
TUNED player has audio ready for immediate playback on play() call none use the FeedAudioPlayer.prepareToPlay() call
PAUSED music playback has paused PAUSED same behavior
PLAYING music playback is happening PLAYING same behavior
STALLED the player is waiting for music data or a response from the feed.fm servers STALLED the player is waiting for music data from the feed.fm CDN
REQUESTING_SKIP the user has hit the skip button and the player is awaiting permission to skip the current song none removed. Use FeedAudioPlayer.SkipListener to be informed of skip status changes
UNAVAILABLE no music is available for the current client UNAVAILABLE same behavior
none this was part of the STALLED state WAITING_FOR_ITEM the player is waiting for the feed.fm servers to tell is what the next song will be

The STALLED and the new WAITING_FOR_ITEM states should cause some kind of 'spinner' or 'waiting' notification to be shown to the user, but the new STALLED state will have metadata about the current song to display to the user while the WAITING_FOR_MUSIC state will not.

Player Events

The three listener classes in the old SDK (PlayerAvailabilityListener, PlayerListener, SocialListener) have been replaced with a larger collection of listeners defined in the FeedAudioPlayer class (AvailabilityListener, LikeStatusChangeListener, MusicQueuedListener, NotificationDataListener, OutOfMusicListener, PlayListener, SkipListener, StateListener, StationChangedListener, UnhandledErrorListener).

The mapping from the old listeners is as follows:

PlayerAvailabilityListener

This class maps directly to the new FeedAudioPlayer.AvailabilityListener, but the new AvailabilityListener additionally includes a reference to the initialized FeedAudioPlayer instance when the player is announced as ready.

PlayerListener

The onPlayerInitialized() method should be replaced with a FeedAudioPlayer.AvailabilityListener instance.

onPlaybackStateChanged() should be replaced with a FeedAudioPlayer.StateListener instance.

onSkipStatusChange() should be replaced with a FeedAudioPlayer.PlayListener instance.

onError() should be replaced with a FeedAudioPlayer.UnhandledErrorListener instance.

SocialListener

Instances of the SocialListener should be replaced with FeedAudioPlayer.LikeStatusChangeListener instances.

Notification and Service Methods

In the old SDK, notifications and automatic creation/updating of an Android Service was the default behavior. The new SDK continues that behavior if you use the FeedPlayerService methods for player creation. To bypass Service creation and Notifictions, just create a FeedAudioPlayer object directly.

Notification styling works exactly the same between SDKS, and the setNotificationStyle() and setPendingIntent() methods in the Player class work the same in the new FeedAudioPlayer class.

New Functionality

The new SDK offers a few pieces of extra functionality that weren't present in the old SDK:

Skip navigation links