map track attributes to their min/max and types

Author: adamint

src/main/kotlin/com/adamratzman/spotify/endpoints/public/BrowseAPI.kt

@@ -25,8 +25,7 @@ import com.adamratzman.spotify.models.serialization.toPagingObject
 import com.neovisionaries.i18n.CountryCode
 import java.text.SimpleDateFormat
 import java.time.Instant
-import java.util.Date
-import java.util.HashMap
+import java.util.*
 import java.util.function.Supplier
 
 /**
@@ -229,19 +228,75 @@ class BrowseAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
      *
      * @throws BadRequestException if any filter is applied illegally
      */
+    @Suppress("DEPRECATION")
+    fun getTrackRecommendations(
+            seedArtists: List<String>? = null,
+            seedGenres: List<String>? = null,
+            seedTracks: List<String>? = null,
+            limit: Int? = null,
+            market: CountryCode? = null,
+            targetAttributes: List<TrackAttribute<*>> = listOf(),
+            minAttributes: List<TrackAttribute<*>> = listOf(),
+            maxAttributes: List<TrackAttribute<*>> = listOf()
+    ): SpotifyRestAction<RecommendationResponse> =
+            getRecommendations(
+                    seedArtists,
+                    seedGenres,
+                    seedTracks,
+                    limit,
+                    market,
+                    targetAttributes.map { it.tuneableTrackAttribute to it.value }.toMap(),
+                    minAttributes.map { it.tuneableTrackAttribute to it.value }.toMap(),
+                    maxAttributes.map { it.tuneableTrackAttribute to it.value }.toMap()
+            )
+
+
+    /**
+     * Create a playlist-style listening experience based on seed artists, tracks and genres.
+     * Recommendations are generated based on the available information for a given seed entity and matched against similar
+     * artists and tracks. If there is sufficient information about the provided seeds, a list of tracks will be returned
+     * together with pool size details. For artists and tracks that are very new or obscure there might not be enough data
+     * to generate a list of tracks.
+     *
+     * **5** seeds of any combination of [seedArtists], [seedGenres], and [seedTracks] can be provided. AT LEAST 1 seed must be provided.
+     *
+     * **All attributes** are weighted equally.
+     *
+     * See [here](https://developer.spotify.com/documentation/web-api/reference/browse/get-recommendations/#tuneable-track-attributes) for a list
+     * and descriptions of tuneable track attributes and their ranges.
+     *
+     * @param seedArtists A possibly null provided list of <b>Artist IDs</b> to be used to generate recommendations
+     * @param seedGenres A possibly null provided list of <b>Genre IDs</b> to be used to generate recommendations. Invalid genres are ignored
+     * @param seedTracks A possibly null provided list of <b>Track IDs</b> to be used to generate recommendations
+     * @param limit The number of objects to return. Default: 20. Minimum: 1. Maximum: 50.
+     * @param market Provide this parameter if you want the list of returned items to be relevant to a particular country.
+     * If omitted, the returned items will be relevant to all countries.
+     * @param targetAttributes For each of the tunable track attributes a target value may be provided.
+     * Tracks with the attribute values nearest to the target values will be preferred.
+     * @param minAttributes For each tunable track attribute, a hard floor on the selected track attribute’s value can be provided.
+     * @param maxAttributes For each tunable track attribute, a hard ceiling on the selected track attribute’s value can be provided.
+     * For example, setting max instrumentalness equal to 0.35 would filter out most tracks that are likely to be instrumental.
+     *
+     * @return [RecommendationResponse] with [RecommendationSeed]s used and [SimpleTrack]s found
+     *
+     * @throws BadRequestException if any filter is applied illegally
+     *
+     */
+    @Deprecated("Ambiguous track attribute setting. Please use BrowseAPI#getTrackRecommendations instead")
     fun getRecommendations(
         seedArtists: List<String>? = null,
         seedGenres: List<String>? = null,
         seedTracks: List<String>? = null,
         limit: Int? = null,
         market: CountryCode? = null,
-        targetAttributes: HashMap<TuneableTrackAttribute, Number> = hashMapOf(),
-        minAttributes: HashMap<TuneableTrackAttribute, Number> = hashMapOf(),
-        maxAttributes: HashMap<TuneableTrackAttribute, Number> = hashMapOf()
+        targetAttributes: Map<TuneableTrackAttribute<*>, Number> = mapOf(),
+        minAttributes: Map<TuneableTrackAttribute<*>, Number> = mapOf(),
+        maxAttributes: Map<TuneableTrackAttribute<*>, Number> = mapOf()
     ): SpotifyRestAction<RecommendationResponse> {
         if (seedArtists?.isEmpty() != false && seedGenres?.isEmpty() != false && seedTracks?.isEmpty() != false) {
             throw BadRequestException(ErrorObject(400, "At least one seed (genre, artist, track) must be provided."))
         }
+
         return toAction(Supplier {
             val builder = EndpointBuilder("/recommendations").with("limit", limit).with("market", market?.name)
                     .with("seed_artists", seedArtists?.joinToString(",") { ArtistURI(it).id.encode() })
@@ -253,75 +308,77 @@ class BrowseAPI(api: SpotifyAPI) : SpotifyEndpoint(api) {
             get(builder.toString()).toObject<RecommendationResponse>(api)
         })
     }
+
+
 }
 
 /**
  * Describes a track attribute
  *
  * @param attribute The spotify id for the track attribute
  */
-enum class TuneableTrackAttribute(private val attribute: String) {
+sealed class TuneableTrackAttribute <T: Number>(val attribute: String, val integerOnly: Boolean, val min: T?, val max: T?) {
     /**
      * A confidence measure from 0.0 to 1.0 of whether the track is acoustic.
      * 1.0 represents high confidence the track is acoustic.
      */
-    ACOUSTICNESS("acousticness"),
+    object ACOUSTICNESS : TuneableTrackAttribute<Float>("acousticness", false,0f, 1f)
     /**
      * Danceability describes how suitable a track is for dancing based on a combination of musical
      * elements including tempo, rhythm stability, beat strength, and overall regularity. A value of 0.0 is
      * least danceable and 1.0 is most danceable.
      */
-    DANCEABILITY("danceability"),
+    object DANCEABILITY : TuneableTrackAttribute<Float>("danceability", false,0f, 1f)
     /**
      * The duration of the track in milliseconds.
      */
-    DURATION_IN_MILLISECONDS("duration_ms"),
+    object DURATION_IN_MILLISECONDS : TuneableTrackAttribute<Int>("duration_ms", true,0, null)
     /**
      * Energy is a measure from 0.0 to 1.0 and represents a perceptual measure of intensity and activity.
      * Typically, energetic tracks feel fast, loud, and noisy. For example, death metal has high energy,
      * while a Bach prelude scores low on the scale. Perceptual features contributing to this attribute
      * include dynamic range, perceived loudness, timbre, onset rate, and general entropy.
      */
-    ENERGY("energy"),
+    object ENERGY : TuneableTrackAttribute<Float>("energy", false, 0f, 1f)
     /**
      * Predicts whether a track contains no vocals. “Ooh” and “aah” sounds are treated as
      * instrumental in this context. Rap or spoken word tracks are clearly “vocal”. The
      * closer the instrumentalness value is to 1.0, the greater likelihood the track contains
      * no vocal content. Values above 0.5 are intended to represent instrumental tracks, but
      * confidence is higher as the value approaches 1.0.
      */
-    INSTRUMENTALNESS("instrumentalness"),
+    object INSTRUMENTALNESS : TuneableTrackAttribute<Float>("instrumentalness", false,0f, 1f)
     /**
      * The key the track is in. Integers map to pitches using standard Pitch Class notation.
      * E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.
      */
-    KEY("key"),
+   object KEY : TuneableTrackAttribute<Int>("key", true,0, null)
     /**
      * Detects the presence of an audience in the recording. Higher liveness values represent an increased
      * probability that the track was performed live. A value above 0.8 provides strong likelihood
      * that the track is live.
      */
-    LIVENESS("liveness"),
+    object LIVENESS : TuneableTrackAttribute<Float>("liveness", false,0f, 1f)
     /**
      * The overall loudness of a track in decibels (dB). Loudness values are averaged across the
      * entire track and are useful for comparing relative loudness of tracks. Loudness is the
      * quality of a sound that is the primary psychological correlate of physical strength (amplitude).
-     * Values typical range between -60 and 0 db.
+     * Values typically range between -60 and 0 db.
      */
-    LOUDNESS("loudness"),
+    object LOUDNESS : TuneableTrackAttribute<Float>("loudness", false,null, null)
     /**
      * Mode indicates the modality (major or minor) of a track, the type of scale from which its
      * melodic content is derived. Major is represented by 1 and minor is 0.
      */
-    MODE("mode"),
+    object MODE : TuneableTrackAttribute<Int>("mode", true,0, 1)
     /**
      * The popularity of the track. The value will be between 0 and 100, with 100 being the most popular.
      * The popularity is calculated by algorithm and is based, in the most part, on the total number of
      * plays the track has had and how recent those plays are. Note: When applying track relinking via
      * the market parameter, it is expected to find relinked tracks with popularities that do not match
      * min_*, max_*and target_* popularities. These relinked tracks are accurate replacements for unplayable tracks with the expected popularity scores. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response.
      */
-    POPULARITY("popularity"),
+    object POPULARITY : TuneableTrackAttribute<Int>("popularity", true,0, 100)
     /**
      * Speechiness detects the presence of spoken words in a track. The more exclusively speech-like the
      * recording (e.g. talk show, audio book, poetry), the closer to 1.0 the attribute value. Values above
@@ -330,23 +387,36 @@ enum class TuneableTrackAttribute(private val attribute: String) {
      * such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like
      * tracks.
      */
-    SPEECHINESS("speechiness"),
+    object SPEECHINESS : TuneableTrackAttribute<Float>("speechiness", false,0f, 1f)
     /**
      * The overall estimated tempo of a track in beats per minute (BPM). In musical terminology, tempo is the
      * speed or pace of a given piece and derives directly from the average beat duration.
      */
-    TEMPO("tempo"),
+    object TEMPO : TuneableTrackAttribute<Float>("tempo", false,0f, null)
     /**
      * An estimated overall time signature of a track. The time signature (meter)
      * is a notational convention to specify how many beats are in each bar (or measure).
      */
-    TIME_SIGNATURE("time_signature"),
+    object TIME_SIGNATURE  :TuneableTrackAttribute<Int>("time_signature", true,null, null)
     /**
      * A measure from 0.0 to 1.0 describing the musical positiveness conveyed by a track. Tracks with high
      * valence sound more positive (e.g. happy, cheerful, euphoric), while tracks with low valence
      * sound more negative (e.g. sad, depressed, angry).
      */
-    VALENCE("valence");
+    object VALENCE : TuneableTrackAttribute<Float>("valence", false,0f, 1f)
 
     override fun toString() = attribute
+
+    fun asTrackAttribute(value: T): TrackAttribute<T> {
+        if (min != null && min.toDouble() > value.toDouble()) throw IllegalArgumentException("Attribute value for $this must be greater than $min!")
+        if (max != null && max.toDouble() < value.toDouble()) throw IllegalArgumentException("Attribute value for $this must be less than $max!")
+
+        return TrackAttribute(this, value)
+    }
+}
+
+data class TrackAttribute<T : Number>(val tuneableTrackAttribute: TuneableTrackAttribute<T>, val value: T) {
+    companion object {
+        fun <T : Number> create(tuneableTrackAttribute: TuneableTrackAttribute<T>, value: T) = tuneableTrackAttribute.asTrackAttribute(value)
+    }
 }

src/test/kotlin/com/adamratzman/spotify/public/BrowseAPITest.kt

@@ -51,52 +51,52 @@ class BrowseAPITest : Spek({
 
         describe("get recommendations") {
             it("no parameters") {
-                assertThrows<BadRequestException> { b.getRecommendations().complete() }
+                assertThrows<BadRequestException> { b.getTrackRecommendations().complete() }
             }
             it("seed artists") {
-                assertThrows<BadRequestException> { b.getRecommendations(seedArtists = listOf("abc")).complete() }
-                assertTrue(b.getRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89")).complete().tracks.isNotEmpty())
-                assertTrue(b.getRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89", "7lMgpN1tEBQKpRoUMKB8iw")).complete().tracks.isNotEmpty())
+                assertThrows<BadRequestException> { b.getTrackRecommendations(seedArtists = listOf("abc")).complete() }
+                assertTrue(b.getTrackRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89")).complete().tracks.isNotEmpty())
+                assertTrue(b.getTrackRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89", "7lMgpN1tEBQKpRoUMKB8iw")).complete().tracks.isNotEmpty())
             }
             it("seed tracks") {
-                assertThrows<BadRequestException> { b.getRecommendations(seedTracks = listOf("abc")).complete() }
-                assertTrue(b.getRecommendations(seedTracks = listOf("3Uyt0WO3wOopnUBCe9BaXl")).complete().tracks.isNotEmpty())
-                assertTrue(b.getRecommendations(seedTracks = listOf("6d9iYQG2JvTTEgcndW81lt", "3Uyt0WO3wOopnUBCe9BaXl")).complete().tracks.isNotEmpty())
+                assertThrows<BadRequestException> { b.getTrackRecommendations(seedTracks = listOf("abc")).complete() }
+                assertTrue(b.getTrackRecommendations(seedTracks = listOf("3Uyt0WO3wOopnUBCe9BaXl")).complete().tracks.isNotEmpty())
+                assertTrue(b.getTrackRecommendations(seedTracks = listOf("6d9iYQG2JvTTEgcndW81lt", "3Uyt0WO3wOopnUBCe9BaXl")).complete().tracks.isNotEmpty())
             }
             it("seed genres") {
-                assertDoesNotThrow { b.getRecommendations(seedGenres = listOf("abc")).complete() }
-                assertTrue(b.getRecommendations(seedGenres = listOf("pop")).complete().tracks.isNotEmpty())
-                assertTrue(b.getRecommendations(seedGenres = listOf("pop", "latinx")).complete().tracks.isNotEmpty())
+                assertDoesNotThrow { b.getTrackRecommendations(seedGenres = listOf("abc")).complete() }
+                assertTrue(b.getTrackRecommendations(seedGenres = listOf("pop")).complete().tracks.isNotEmpty())
+                assertTrue(b.getTrackRecommendations(seedGenres = listOf("pop", "latinx")).complete().tracks.isNotEmpty())
             }
             it("multiple seed types") {
                 assertDoesNotThrow {
-                    b.getRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89"),
+                    b.getTrackRecommendations(seedArtists = listOf("2C2sVVXanbOpymYBMpsi89"),
                             seedTracks = listOf("6d9iYQG2JvTTEgcndW81lt", "3Uyt0WO3wOopnUBCe9BaXl"),
                             seedGenres = listOf("pop")).complete()
                 }
             }
             it("target attributes") {
-                assertThrows<BadRequestException> {
-                    b.getRecommendations(targetAttributes = hashMapOf(TuneableTrackAttribute.ACOUSTICNESS to 3)).complete()
+                assertThrows<IllegalArgumentException> {
+                    b.getTrackRecommendations(targetAttributes = listOf(TuneableTrackAttribute.ACOUSTICNESS.asTrackAttribute(3f))).complete()
                 }
-                assertTrue(b.getRecommendations(
-                        targetAttributes = hashMapOf(TuneableTrackAttribute.ACOUSTICNESS to 1.0, TuneableTrackAttribute.DANCEABILITY to .5),
+                assertTrue(b.getTrackRecommendations(
+                        targetAttributes = listOf(TuneableTrackAttribute.ACOUSTICNESS.asTrackAttribute(1f), TuneableTrackAttribute.DANCEABILITY.asTrackAttribute(0.5f)),
                         seedGenres = listOf("pop")).complete().tracks.isNotEmpty())
             }
             it("min attributes") {
-                assertThrows<BadRequestException> {
-                    b.getRecommendations(minAttributes = hashMapOf(TuneableTrackAttribute.ACOUSTICNESS to 3)).complete()
+                assertThrows<IllegalArgumentException> {
+                    b.getTrackRecommendations(minAttributes = listOf(TuneableTrackAttribute.ACOUSTICNESS.asTrackAttribute(3f))).complete()
                 }
-                assertTrue(b.getRecommendations(
-                        minAttributes = hashMapOf(TuneableTrackAttribute.ACOUSTICNESS to 0.5, TuneableTrackAttribute.DANCEABILITY to .5),
+                assertTrue(b.getTrackRecommendations(
+                        minAttributes = listOf(TuneableTrackAttribute.ACOUSTICNESS.asTrackAttribute(0.5f), TuneableTrackAttribute.DANCEABILITY.asTrackAttribute(0.5f)),
                         seedGenres = listOf("pop")).complete().tracks.isNotEmpty())
             }
             it("max attributes") {
                 assertThrows<BadRequestException> {
-                    b.getRecommendations(maxAttributes = hashMapOf(TuneableTrackAttribute.SPEECHINESS to 3)).complete()
+                    b.getTrackRecommendations(maxAttributes = listOf(TuneableTrackAttribute.SPEECHINESS.asTrackAttribute(0.9f))).complete()
                 }
-                assertTrue(b.getRecommendations(
-                        maxAttributes = hashMapOf(TuneableTrackAttribute.ACOUSTICNESS to 0.9, TuneableTrackAttribute.DANCEABILITY to 0.9),
+                assertTrue(b.getTrackRecommendations(
+                        maxAttributes = listOf(TuneableTrackAttribute.ACOUSTICNESS.asTrackAttribute(0.9f), TuneableTrackAttribute.DANCEABILITY.asTrackAttribute(0.9f)),
                         seedGenres = listOf("pop")).complete().tracks.isNotEmpty())
             }
         }