rspotify 1.17.0 → 1.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ec64ebb3e63e640a69c4fc621b98927e493340b2
-  data.tar.gz: 1f2586292e73e9af6d7ff149a7a872e28e9d6f65
+  metadata.gz: d1ea05cdf97229f89e4289ab13ffb98e69c9c83d
+  data.tar.gz: 51189c1a34623a092bbf00228dde6f74f01602ad
 SHA512:
-  metadata.gz: 1e5845de63d4bf7153726d24eda36de52306a798d6f439970434bc0850befbfeea4af4f149c7c87cf2e2aa2b3192530f916231f84760bdef6e1deb4e70438630
-  data.tar.gz: aca1f97b5fb3d2bd385eb96cd11b18c1093965af878ee1aaf3951040075a72c5c90848ffc58157bbfed40f586b6a4dd5bfcf313fefba2074b6e89ba4edf6dd74
+  metadata.gz: 2f3606c24acaaaa73c3bb63b4686e763517f5b75f302dec396f32389efb85d9eaba23c7fe8d06acdc21fd2d30f38a0804ba464e33e09c5dc0d3a43623fba5de3
+  data.tar.gz: c02ebfec2b609bcabf1b06647db8d23dba3706d63cb77d8609afa4ecb989e4d5d7ef43f06e776c83c662f2777691cb66fd24eac2c0493e9e9e4d8b45abb2d1f3

data/README.md

@@ -79,8 +79,8 @@ am.album_type #=> "single"
 do_i_wanna_know = RSpotify::Track.find('2UzMpPKPhbcC8RbsmuURAZ')
 do_i_wanna_know.album #=> (Album object)
 
-wizzler = RSpotify::User.find('wizzler')
-wizzler.uri #=> "spotify:user:wizzler"
+me = RSpotify::User.find('guilhermesad')
+me.uri #=> "spotify:user:guilhermesad"
 
 # Or find several objects at once:
 
@@ -99,14 +99,14 @@ RSpotify.authenticate("<your_client_id>", "<your_client_secret>")
 
 # Now you can access playlists in detail, browse featured content and more
 
-wizzler = RSpotify::User.find('wizzler')
-wizzler.playlists #=> (Playlist array)
+me = RSpotify::User.find('guilhermesad')
+me.playlists #=> (Playlist array)
 
 # Find by id
-playlist = RSpotify::Playlist.find('wizzler', '00wHcTN0zQiun4xri9pmvX')
-playlist.name               #=> "Movie Soundtrack Masterpieces"
-playlist.description        #=> "Iconic soundtracks featured..."
-playlist.followers['total'] #=> 13
+playlist = RSpotify::Playlist.find('guilhermesad', '1Xi8mgiuHHPLQYOw2Q16xv')
+playlist.name               #=> "d33p"
+playlist.description        #=> "d33p h0uz"
+playlist.followers['total'] #=> 1
 playlist.tracks             #=> (Track array)
 
 # Search by category
@@ -117,6 +117,18 @@ categories = RSpotify::Category.list # See all available categories
 # Access featured content from Spotify's Browse tab
 featured_playlists = RSpotify::Playlist.browse_featured(country: 'US')
 new_releases = RSpotify::Album.new_releases(country: 'ES')
+
+# Access tracks' audio features
+sorry = RSpotify::Track.search("Sorry").first
+sorry.audio_features.danceability #=> 0.605
+sorry.audio_features.energy #=> 0.768
+sorry.audio_features.tempo #=> 100.209
+
+# Get recommendations
+recommendations = RSpotify::Recommendations.generate(seed_genres: ['blues', 'country'])
+recommendations = RSpotify::Recommendations.generate(seed_tracks: my_fav_tracks.map(&:id))
+recommendations = RSpotify::Recommendations.generate(seed_artists: my_fav_artists.map(&:id))
+recommendations.tracks #=> (Track array)
 ```
 
 ## Rails + OAuth
@@ -196,6 +208,10 @@ class UsersController < ApplicationController
     spotify_user.follows?(artists)
     spotify_user.unfollow(users)
 
+    # Get user's top played artists and tracks
+    spotify_user.top_artists #=> (Artist array)
+    spotify_user.top_tracks(time_range: 'short_term') #=> (Track array)
+
     # Check doc for more
   end
 end

data/lib/rspotify.rb

@@ -2,11 +2,14 @@ require 'rspotify/connection'
 require 'rspotify/version'
 
 module RSpotify
-  autoload :Album,    'rspotify/album'
-  autoload :Artist,   'rspotify/artist'
-  autoload :Base,     'rspotify/base'
-  autoload :Category, 'rspotify/category'
-  autoload :Playlist, 'rspotify/playlist'
-  autoload :Track,    'rspotify/track'
-  autoload :User,     'rspotify/user'
+  autoload :Album,              'rspotify/album'
+  autoload :Artist,             'rspotify/artist'
+  autoload :AudioFeatures,      'rspotify/audio_features'
+  autoload :Base,               'rspotify/base'
+  autoload :Category,           'rspotify/category'
+  autoload :Playlist,           'rspotify/playlist'
+  autoload :Recommendations,    'rspotify/recommendations'
+  autoload :RecommendationSeed, 'rspotify/recommendation_seed'
+  autoload :Track,              'rspotify/track'
+  autoload :User,               'rspotify/user'
 end

data/lib/rspotify/audio_features.rb

@@ -0,0 +1,72 @@
+module RSpotify
+
+  # @attr [Float]   acousticness      A confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.
+  # @attr [String]  analysis_url      An HTTP URL to access the full audio analysis of this track. This URL is cryptographically signed and configured to expire after roughly 10 minutes. Do not store these URLs for later use.
+  # @attr [Float]   danceability      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.
+  # @attr [Integer] duration_ms       The duration of the track in milliseconds.
+  # @attr [Float]   energy            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.
+  # @attr [Float]   instrumentalness  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.
+  # @attr [Integer] key               The key the track is in. Integers map to pitches using standard {https://en.wikipedia.org/wiki/Pitch_class Pitch Class notation}. E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.
+  # @attr [Float]   liveness          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.
+  # @attr [Float]   loudness          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.
+  # @attr [Integer] mode              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.
+  # @attr [Float]   speechiness       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 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.
+  # @attr [Float]   tempo             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.
+  # @attr [Integer] time_signature    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).
+  # @attr [String]  track_href        A link to the Web API endpoint providing full details of the track.
+  # @attr [Float]   valence           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).
+  class AudioFeatures < Base
+
+    # Retrieves AudioFeatures object(s) for the track id(s) provided
+    #
+    # @param ids [String, Array] Either a single track id or a list track ids. Maximum: 100 IDs.
+    # @return [AudioFeatures, Array<AudioFeatures>]
+    #
+    # @example
+    #           audio_features = RSpotify::AudioFeatures.find('1zHlj4dQ8ZAtrayhuDDmkY')
+    #           audio_features = RSpotify::AudioFeatures.find(['1zHlj4dQ8ZAtrayhuDDmkY', '7ouMYWpwJ422jRcDASZB7P', '4VqPOruhp5EdPBeR92t6lQ'])
+    def self.find(ids)
+      case ids
+      when Array
+        url = "audio-features?ids=#{ids.join(',')}"
+        response = RSpotify.get(url)
+        return response if RSpotify.raw_response
+
+        response['audio_features'].map { |i| AudioFeatures.new i }
+      when String
+        url = "audio-features/#{ids}"
+        response = RSpotify.get(url)
+        return response if RSpotify.raw_response
+
+        AudioFeatures.new response
+      end
+    end
+
+    def initialize(options = {})
+      @acousticness = options['acousticness']
+      @analysis_url = options['analysis_url']
+      @danceability = options['danceability']
+      @duration_ms = options['duration_ms']
+      @energy = options['energy']
+      @instrumentalness = options['instrumentalness']
+      @key = options['key']
+      @liveness = options['liveness']
+      @loudness = options['loudness']
+      @mode = options['mode']
+      @speechiness = options['speechiness']
+      @tempo = options['tempo']
+      @time_signature = options['time_signature']
+      @track_href = options['track_href']
+      @valence = options['valence']
+
+      super(options)
+    end
+
+    # Spotify does not support search for audio features
+    def self.search(*)
+      warn 'Spotify API does not support search for audio features'
+      false
+    end
+
+  end
+end

data/lib/rspotify/base.rb

@@ -121,6 +121,46 @@ module RSpotify
       @uri           = options['uri']
     end
 
+    # Generate an embed code for an album, artist or track.
+    # @param [Hash] options
+    # @option options [Fixnum] :width the width of the frame
+    # @option options [Fixnum] :height the height of the frame
+    # @option options [Fixnum] :frameborder the frameborder of the frame
+    # @option options [Boolean] :allowtransparency toggle frame transparency
+    # @option options [nil|String|Symbol] :view specific view option for iframe
+    # @option options [nil|String|Symbol] :theme specific theme option for iframe
+    #
+    # For full documentation on widgets/embeds, check out the official documentation:
+    # @see https://developer.spotify.com/technologies/widgets/examples/
+    #
+    def embed(options = {})
+      default_options = {
+        width: 300,
+        height: 380,
+        frameborder: 0,
+        allowtransparency: true,
+        view: nil,
+        theme: nil,
+      }
+      options = default_options.merge(options)
+
+      src = "https://embed.spotify.com/?uri=#{@uri}"
+      src << "&view=#{options[:view]}" unless options[:view].nil?
+      src << "&theme=#{options[:theme]}" unless options[:theme].nil?
+
+      template = <<-HTML
+        <iframe
+          src="#{src}"
+          width="#{options[:width]}"
+          height="#{options[:height]}"
+          frameborder="#{options[:frameborder]}"
+          allowtransparency="#{options[:allowtransparency]}">
+        </iframe>
+      HTML
+
+      template.gsub(/\s+/, " ").strip
+    end
+
     # When an object is obtained undirectly, Spotify usually returns a simplified version of it.
     # This method updates it into a full object, with all attributes filled.
     #

data/lib/rspotify/recommendation_seed.rb

@@ -0,0 +1,18 @@
+module RSpotify
+
+  # @attr [Integer] after_filtering_size The number of tracks available after min_* and max_* filters have been applied.
+  # @attr [Integer] after_relinking_size The number of tracks available after relinking for regional availability.
+  # @attr [Integer] initial_pool_size    The number of recommended tracks available for this seed.
+  class RecommendationSeed < Base
+    
+    def initialize(options = {})
+      @after_filtering_size = options['afterFilteringSize']
+      @after_relinking_size = options['afterRelinkingSize']
+      @initial_pool_size    = options['initialPoolSize']
+
+      super(options)
+    end
+
+  end
+
+end

data/lib/rspotify/recommendations.rb

@@ -0,0 +1,108 @@
+module RSpotify
+
+  # @attr [Array<Track>]              tracks An array of {https://developer.spotify.com/web-api/object-model/#track-object-simplified track object (simplified)} ordered according to the parameters supplied.
+  # @attr [Array<RecommendationSeed>] seeds An array of {https://developer.spotify.com/web-api/object-model/#recommendations-seed-object recommendation seed objects}.
+  class Recommendations < Base
+    
+    # Retrieve a list of available genres seed parameter values for recommendations. 
+    # @return [Array<String>] 
+    #
+    # @example
+    #          genres = RSpotify::Recommendations.available_genre_seeds
+    def self.available_genre_seeds
+      response = RSpotify.get('recommendations/available-genre-seeds')
+      return response if RSpotify.raw_response
+
+      response['genres']
+    end
+
+    # Create a playlist-style listening experience based on seed artists, tracks and genres
+    #
+    # @note Up to 5 seed values may be provided in any combination of seed_artists, seed_tracks and seed_genres.
+    #
+    # @param limit        [Integer]       The target size of the list of recommended tracks. For seeds with unusually small pools or when highly restrictive filtering is applied, it may be impossible to generate the requested number of recommended tracks. Debugging information for such cases is available in the response. Default: 20. Minimum: 1. Maximum: 100.
+    # @param seed_artists [Array<String>] A list of Spotify IDs for seed artists.
+    # @param seed_genres  [Array<String>] A list of any genres in the set of {https://developer.spotify.com/web-api/get-recommendations/#available-genre-seeds available genre seeds}.
+    # @param seed_tracks  [Array<String>] A list of Spotify IDs for seed tracks.
+    # @param market       [String]        Optional. An {https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2  ISO 3166-1 alpha-2 country code}. Provide this parameter if you want to apply Track Relinking. Because min_*, max_* and target_* are applied to pools before relinking, the generated results may not precisely match the filters applied. Original, non-relinked tracks are available via the linked_from attribute of the relinked track response.
+    # @option options     [Float]         :min_acousticness Hard floor on the confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.          
+    # @option options     [Float]         :max_acousticness Hard ceiling on the confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic. 
+    # @option options     [Float]         :target_acousticness Target value on the confidence measure from 0.0 to 1.0 of whether the track is acoustic. 1.0 represents high confidence the track is acoustic.
+    # @option options     [Float]         :min_danceability Hard floor on 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.
+    # @option options     [Float]         :max_danceability Hard ceiling on 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.
+    # @option options     [Float]         :target_danceability Target value on 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.
+    # @option options     [Integer]       :min_duration_ms Hard floor on the duration of the track in milliseconds.
+    # @option options     [Integer]       :max_duration_ms Hard ceiling on the duration of the track in milliseconds.
+    # @option options     [Integer]       :target_duration_ms Target value on the duration of the track in milliseconds.
+    # @option options     [Float]         :min_energy Hard floor on energy which 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.
+    # @option options     [Float]         :max_energy Hard ceiling on energy which 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.
+    # @option options     [Float]         :target_energy Target value on energy which 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.
+    # @option options     [Float]         :min_instrumentalness Hard floor on prediction of 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.
+    # @option options     [Float]         :max_instrumentalness Hard ceiling on prediction of 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.
+    # @option options     [Float]         :target_instrumentalness Target value on prediction of 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.
+    # @option options     [Integer]       :min_key Hard floor on the key the track is in. Integers map to pitches using standard {https://en.wikipedia.org/wiki/Pitch_class Pitch Class notation}. E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.
+    # @option options     [Integer]       :max_key Hard ceiling on the key the track is in. Integers map to pitches using standard {https://en.wikipedia.org/wiki/Pitch_class Pitch Class notation}. E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.   
+    # @option options     [Integer]       :target_key Target value on the key the track is in. Integers map to pitches using standard {https://en.wikipedia.org/wiki/Pitch_class Pitch Class notation}. E.g. 0 = C, 1 = C♯/D♭, 2 = D, and so on.   
+    # @option options     [Float]         :min_liveness Hard floor on liveness, which 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.
+    # @option options     [Float]         :max_liveness Hard ceiling on liveness, which 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.
+    # @option options     [Float]         :target_liveness Target value on liveness, which 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.
+    # @option options     [Float]         :min_loudness Hard floor on 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.
+    # @option options     [Float]         :max_loudness Hard ceiling on 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.
+    # @option options     [Float]         :target_loudness Target value on 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.
+    # @option options     [Integer]       :min_mode Hard floor on 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.         
+    # @option options     [Integer]       :max_mode Hard ceiling on 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.         
+    # @option options     [Integer]       :target_mode Target value on 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.         
+    # @option options     [Integer]       :min_popularity Hard floor on 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.
+    # @option options     [Integer]       :max_popularity Hard ceiling on 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.
+    # @option options     [Integer]       :target_popularity Target value on 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.
+    # @option options     [Float]         :min_speechiness Hard floor on speechiness which 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 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.
+    # @option options     [Float]         :max_speechiness Hard ceiling on speechiness which 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 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.
+    # @option options     [Float]         :target_speechiness Target value on speechiness which 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 0.66 describe tracks that are probably made entirely of spoken words. Values between 0.33 and 0.66 describe tracks that may contain both music and speech, either in sections or layered, including such cases as rap music. Values below 0.33 most likely represent music and other non-speech-like tracks.
+    # @option options     [Float]         :min_tempo Hard floor on 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.
+    # @option options     [Float]         :max_tempo Hard ceiling on 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.
+    # @option options     [Float]         :target_tempo Target value on 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.
+    # @option options     [Integer]       :min_time_signature Hard floor on the 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).
+    # @option options     [Integer]       :max_time_signature Hard ceiling on the 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).
+    # @option options     [Integer]       :target_time_signature Target value on the 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).
+    # @option options     [Float]         :min_valence Hard floor on the 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).
+    # @option options     [Float]         :max_valence Hard ceiling on the 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).
+    # @option options     [Float]         :target_valence Target value on the 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).
+    # @return [Array<Recommendations>]
+    #
+    # @example
+    #          recommendations = RSpotify::Recommendations.generate(limit: 20, seed_tracks: ['0c6xIDDpzE81m2q797ordA'])
+    #          recommendations = RSpotify::Recommendations.generate(seed_tracks: ['0c6xIDDpzE81m2q797ordA'], seed_artists: ['4NHQUGzhtTLFvgF5SZesLK'], market: 'ES')
+    #          recommendations = RSpotify::Recommendations.generate(seed_tracks: ['0c6xIDDpzE81m2q797ordA'], seed_genres: ['alt_rock'], seed_artists: ['4NHQUGzhtTLFvgF5SZesLK'], target_energy: 1.0)
+    def self.generate(limit: 20, seed_artists: [], seed_genres: [], seed_tracks: [], market: nil, **options)
+      url = "recommendations?limit=#{limit}"
+
+      url << "&seed_artists=#{seed_artists.join(',')}" if seed_artists.any?
+      url << "&seed_genres=#{seed_genres.join(',')}" if seed_genres.any?
+      url << "&seed_tracks=#{seed_tracks.join(',')}" if seed_tracks.any?
+
+      options.each do |option, value|
+        url << "&#{option}=#{value}"
+      end
+
+      response = if market.is_a? Hash
+        url << '&market=from_token'
+        User.oauth_get(market[:from].id, url)
+      else
+        url << "&market=#{market}" if market
+        RSpotify.get(url)
+      end
+
+      return response if RSpotify.raw_response
+
+      Recommendations.new response
+    end
+
+    def initialize(options = {})
+      @seeds = options['seeds'].map { |i| RecommendationSeed.new i }
+      @tracks = options['tracks'].map { |i| Track.new i }
+
+      super(options)
+    end
+  end
+
+end

data/lib/rspotify/track.rb

@@ -49,6 +49,11 @@ module RSpotify
       super(query, 'track', limit: limit, offset: offset, market: market)
     end
 
+    # Retrieves the audio features for the track
+    def audio_features
+      RSpotify::AudioFeatures.find(@id)
+    end
+
     def initialize(options = {})
       @available_markets = options['available_markets']
       @disc_number       = options['disc_number']

data/lib/rspotify/user.rb

@@ -366,6 +366,42 @@ module RSpotify
       Hash[pairs]
     end
 
+    # Get the current user’s top artists based on calculated affinity. Requires the *user-top-read* scope.
+    #
+    # @param limit  [Integer] Optional. The number of entities to return. Default: 20. Minimum: 1. Maximum: 50.
+    # @param offset [Integer] Optional. The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.
+    # @param time_range [String] Optional. Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term.
+    # @return [Array<Artist>]
+    #
+    # @example
+    #           top_artists = user.top_artists
+    #           top_artists.size       #=> 20
+    #           top_artists.first.name #=> "Nine Inch Nails"
+    def top_artists(limit: 20, offset: 0, time_range: 'medium_term')
+      url = "me/top/artists?limit=#{limit}&offset=#{offset}&time_range=#{time_range}"
+      response = User.oauth_get(@id, url) 
+      return response if RSpotify.raw_response
+      response['items'].map { |i| Artist.new i }
+    end
+
+    # Get the current user’s top tracks based on calculated affinity. Requires the *user-top-read* scope.
+    #
+    # @param limit  [Integer] Optional. The number of entities to return. Default: 20. Minimum: 1. Maximum: 50.
+    # @param offset [Integer] Optional. The index of the first entity to return. Default: 0 (i.e., the first track). Use with limit to get the next set of entities.
+    # @param time_range [String] Optional. Over what time frame the affinities are computed. Valid values: long_term (calculated from several years of data and including all new data as it becomes available), medium_term (approximately last 6 months), short_term (approximately last 4 weeks). Default: medium_term.
+    # @return [Array<Track>]
+    #
+    # @example
+    #           top_tracks = user.top_tracks
+    #           top_tracks.size       #=> 20
+    #           top_tracks.first.name #=> "Ice to Never"
+    def top_tracks(limit: 20, offset: 0, time_range: 'medium_term')
+      url = "me/top/tracks?limit=#{limit}&offset=#{offset}&time_range=#{time_range}"
+      response = User.oauth_get(@id, url) 
+      return response if RSpotify.raw_response
+      response['items'].map { |i| Track.new i }
+    end
+
     # Remove the current user as a follower of one or more artists, other Spotify users or a playlist. Unfollowing artists or users require the *user-follow-modify* scope.
     # Unfollowing a publicly followed playlist requires the *playlist-modify-public* scope; unfollowing a privately followed playlist requires the *playlist-modify-private* scope.
     #

data/lib/rspotify/version.rb

@@ -1,3 +1,3 @@
 module RSpotify
-  VERSION = '1.17.0'
+  VERSION = '1.18.0'
 end

data/spec/lib/rspotify/album_spec.rb

@@ -138,4 +138,51 @@ describe RSpotify::Album do
       expect(ES_albums.length).to eq(albums.length)
     end
   end
+
+  describe '.embed' do
+    before(:each) do
+      @album = VCR.use_cassette('album:find:5bU1XKYxHhEwukllT20xtk') do
+        RSpotify::Album.find('5bU1XKYxHhEwukllT20xtk')
+      end
+    end
+
+    it 'returns the correct iframe' do
+      expect(@album.embed).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk" width="300" height="380" frameborder="0" allowtransparency="true"> </iframe>'
+    end
+
+    context 'with a coverart view' do
+      it 'returns the correct iframe' do
+        expect(@album.embed(view: :coverart)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk&view=coverart" width="300" height="380" frameborder="0" allowtransparency="true"> </iframe>'
+      end
+    end
+
+    context 'with different width & height' do
+      it 'returns the correct iframe' do
+        expect(@album.embed(width: 800)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk" width="800" height="380" frameborder="0" allowtransparency="true"> </iframe>'
+      end
+
+      it 'returns the correct iframe' do
+        expect(@album.embed(height: 100)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk" width="300" height="100" frameborder="0" allowtransparency="true"> </iframe>'
+      end
+    end
+
+    context 'with frameborder' do
+      it 'returns the correct iframe' do
+        expect(@album.embed(frameborder: 10)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk" width="300" height="380" frameborder="10" allowtransparency="true"> </iframe>'
+      end
+    end
+
+    context 'with allowtransparency' do
+      it 'returns the correct iframe' do
+        expect(@album.embed(allowtransparency: false)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk" width="300" height="380" frameborder="0" allowtransparency="false"> </iframe>'
+      end
+    end
+
+    context 'with theme' do
+      it 'returns the correct iframe' do
+        expect(@album.embed(theme: :white)).to eq '<iframe src="https://embed.spotify.com/?uri=spotify:album:5bU1XKYxHhEwukllT20xtk&theme=white" width="300" height="380" frameborder="0" allowtransparency="true"> </iframe>'
+      end
+    end
+  end
 end
+