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.
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.
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.
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.
dislike inform the Adaptr servers how a user feels about the current song. You can remove a like using
favorite will mark a song as a user favorite, and can be reversed with
The player maintains a public
state, which will be one of the following:
ready to play
waiting for item
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.
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.
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.
Audio element, and has no external dependencies.
The web SDK is built with TypeScript and comes with full types.
Are there other platforms you want to play music on? Contact us! We want to be your music provider!