SDK Documentation
SDK Concepts
Conceptually, how does the Adaptr SDK work?
At the simplest level, the SDK provides a singleton music player with play, pause, skip, previous, like, dislike, favorite, and volume controls. The player, upon initialization, retrieves a list of available stations from the Adaptr servers that contain songs the player can retrieve and play. At any given time, a single station is the active station from which songs are retrieved for playback. The player 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 player generates and caches a random unique client id that is stored and sent with all network requests to track playback history and enforce playback restrictions.
The player can be commanded to play and pause music playback. 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. Calls to like and dislike inform the Adaptr servers how a user feels about the current song.
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 Curation and SDK Playback
Via the Adaptr.com website, you must create a connector. This connector will have a set of credentials (a token and secret) that you must provide to the SDK when initializing it.
When the SDK presents its credentials to the Adaptr API servers, it will receive a list of music stations available for playback. These stations are made available to the SDK client by creating playlists in the Adaptr.com web interface, connecting the playlists to the connector, and then publishing them to the connector. In the publishing process, a station is created for each playlist and made available to clients. Playlists can be edited at any time, but the music isn't made available as stations to SDK clients until those playlists are published.
Adaptr client libraries
If you're integrating Adaptr using our connectors, we offer binary SDKs for various platforms 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 source code for complete music player interfaces that make use of the SDKs and can be pasted into a connector or used as a model to help you build your own custom interface.
Here is what we have available for you:
iOS SDK / UIs
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.
Android SDK / UIs
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.
JavaScript SDK
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 JavaScript SDK documentation is here.
Other platforms
Are there other platforms you want to play music on? Contact us! We want to be your music provider!
Next Steps
Contact us to get a quote and get access to build your playlists and create a connector. This connector will have a set of credentials (a token and secret) that you must provide to the SDK when initializing it.
