SDK Documentation

Adaptr SDK

The Adaptr SDK is how you integrate with the Adaptr service. We provide libraries for the following platforms:

The core of the SDK is the Player, which maintains station data, the currently selected station, and controls playback. It also offers methods for retrieving the music available in each station (through pagination or search) so that individual tracks can be played back on demand and client-side playlists can be created.

The SDK generates and maintains a client ID unique to each user, for the purpose of playback restrictions and recording a user's play history across sessions. The client ID is sent to the Adaptr service with each request.

Managing your application

If you haven't already done so, register your application via the apps portal. You will need to be logged in for this, but registration is quick and free. The application you create is how you will manage your integration with Adaptr. Take note of the token and secret provided for your app. You'll need these to initialize the Adaptr SDK.

Before you can play music, you need to configure a playlist in the playlists portal. A playlist is a collection of tracks that you've selected. When you attach a playlist to your app and publish it, we create a copy that will never change. This copy is a station.

Playlists can be edited at any time, but the music isn't made available as new stations to the Adaptr SDK clients until those changes are published.

Playing music

Begin by initializing the player with the token and secret associated with your application (you can find these at any time in the application portal). Upon initialization, the player retrieves a list of available stations from the Adaptr servers.

The player can then be commanded to play, pause, skip, previous, like, dislike, favorite, and control playback volume. 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.

Current station

When you first initialize the Adaptr SDK, there is no current station. To play music you can specify the station to play as an argument to the first call to play. This will cause a short delay as station audio is loaded, then playback will begin. Alternatively, you can select the station in advance to preload audio for it, and then call play with no arguments to play what has been queued.

See the SDK documentation for your specific platform for specific instructions on how to follow these two patterns.

Liking and favoriting

Calls to like and dislike inform the Adaptr servers how a user feels about the current song. You can remove a like using unlike.

Calls to favorite will mark a song as a user favorite, and can be reversed with unfavorite.

Player state

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 Adaptr to give it a song to play
stalled
the player is blocked and 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
complete
the player has reached the end of music in the current playlist.

Adaptr SDK client libraries

For native apps, we offer binary SDKs that handle basic audio playback and native device control integration. You must build the user interface, although we offer various supporting views and controllers to assist.

We also offer a web client with a limited set of features compared to the platform libraries.

We additionally provide source code for complete music player interfaces that make use of the SDKs and can be pasted into an app or used as a model to help you build your own custom interface.

Adaptr SDK and UIs for iOS

Full documentation

Our iOS SDK is written in Objective-C and runs on recent versions of iOS and tvOS. The library can be retrieved via Swift Package manager. Appledocs are available for all versions including the latest version.

The iOS SDK is kept up to date with all our latest features and handles integration with the iOS lock screen for background playback, if desired.

Adaptr SDK and UIs for Android

Full documentation

The Android SDK is written in Kotlin, works back to API 16, and is compiled with the latest released Android API. The SDK is available as an .aar from our GitHub Android SDK Release Page. Javadocs are available for all versions, including the latest version.

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're using a version of ExoPlayer we aren't currently publishing, please let us know and we can likely add your version in as well.

The Android SDK is kept up to date with all our latest features and handles integration with Android Notifications for lock screen playback control.

Adaptr SDK for JavaScript/TypeScript

Full documentation

Adaptr's JavaScript SDK powers music playback for websites. This SDK does not have all the features of our native SDKs, but it does support basic streaming and simulcast playback. The library is published via NPM as adaptr-music-player. The SDK makes use of the HTML Audio element, and has no external dependencies.

The web SDK is built with TypeScript and comes with full types.

Other platforms

Are there other platforms you want to play music on? Contact us! We want to be your music provider!

Resources
Blog News Get Help
Follow Us