Packages

Description

The Adaptr Music SDK For Android.

• Overview
• Crossfading
• Changelog

Overview

The SDK centers around two classes AdaptrPlayer and Adaptr. AdaptrPlayer presents a fully functional music player that can play and stream music from the Adaptr servers. Adaptr is used to retrieve and manage a singleton AdaptrPlayer 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 AdaptrPlayer takes place asynchronously, clients may register implementations of the various listener interfaces to receive notification of player events.

The Adaptr class must be initialized with a token and secret before playback becomes available. The AdaptrPlayer uses those credentials to contact the Adaptr 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 Adaptr class takes care of managing lock screen integration, notifications, audio ducking, and playback controls. There are AdaptrPlayer methods 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 implementation 'com.adaptr:AndroidSDK:0.1.9' to your build.gradle file

Assign token and secret

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

 Adaptr.initialize(getApplicationContext(), "adaptr", "adaptr");

Your token and secret values are provided to you when you sign up with adaptr, 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 Adaptr

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

    Adaptr.getPlayerInstance(new AvailabilityListener() {
        public void onPlayerAvailable(AdaptrPlayer player) {
            //   Save reference to instance
            myPlayer = 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 in a station immediately with:
            //   player.play(player.getStationList().get(0));

            //   .. or do nothing, and call 'player.play()' when the user
            //   wants to start music
            //    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
            }

    });

If clients desire, they can create a AdaptrPlayer instance directly using one of its public constructors. This prevents 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

State	description
UNINITIALIZED	Player hasn't contacted Adaptr yet
READY_TO_PLAY	Player is ready to begin music playback
PAUSED	Music playback has paused
PLAYING	Music playback is happening
STALLED	The player is waiting for music data from the Adaptr CDN
WAITING_FOR_ITEM	The player is waiting for the Adaptr servers to tell is what the next song will be
UNAVAILABLE	No music is available for the current client. This is most likely due to the client not being in compliance to DMCA rules, location etc.

The STALLED and the new WAITING_FOR_ITEM states should cause some kind of 'spinner' or 'waiting' notification to be shown to the user. While in the STALLED state, the player will have metadata about the current song to display to the user. While in the WAITING_FOR_MUSIC state, there will be no current song and, therefore, no song metadata to display.

Player Events

The following listeners are defined in the SDK:

Event	description
AvailabilityListener	Player has contacted Adaptr and player is now available or UNAVAILABLE.
LikeStatusChangeListener	A song was liked or disliked.
MusicQueuedListener	Music is now queued and ready to instantly begin playback.
OutOfMusicListener	This station has no more music available for this user.
PlayListener	Monitor changes to the currently playing music
SkipListener	Monitor the skip status
StateListener	Watch the current state of the player and any changes to it
StationChangedListener	Watch for changes to current station
UnhandledErrorListener	An unexpected error has occured

Crossfading Rules

The player can crossfade between songs and when changing stations. This can be controlled on the client by providing a non-zero value to AdaptrPlayer.setSecondsOfCrossfade(). Alternatively, the crossfade duration can be assigned to values provided by the Adaptr servers. Any values sent from the servers override any crossfade timing set on the client.

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.

Latest versions and Change log

Please subscribe to the following repository to keep up with the latest releases and look at the change log

https://github.com/Adaptr-Music/Android-SDK/releases