spotify 12.2.0 → 12.3.0

data/lib/spotify/api/artist.rb

@@ -0,0 +1,10 @@
+module Spotify
+  class API
+    # @!group Artist
+    attach_function :artist_name, [ Artist ], UTF8String
+    attach_function :artist_is_loaded, [ Artist ], :bool
+    attach_function :artist_portrait, [ Artist, :image_size ], ImageID
+    attach_function :artist_add_ref, [ Artist ], :error
+    attach_function :artist_release, [ Artist ], :error
+  end
+end

data/lib/spotify/api/artist_browse.rb

@@ -0,0 +1,23 @@
+module Spotify
+  class API
+    # @!group ArtistBrowse
+    attach_function :artistbrowse_create, [ Session, Artist, :artistbrowse_type, :artistbrowse_complete_cb, :userdata ], ArtistBrowse
+    attach_function :artistbrowse_is_loaded, [ ArtistBrowse ], :bool
+    attach_function :artistbrowse_error, [ ArtistBrowse ], :error
+    attach_function :artistbrowse_artist, [ ArtistBrowse ], Artist
+    attach_function :artistbrowse_num_portraits, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_portrait, [ ArtistBrowse, :int ], ImageID
+    attach_function :artistbrowse_num_tracks, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_track, [ ArtistBrowse, :int ], Track
+    attach_function :artistbrowse_num_albums, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_album, [ ArtistBrowse, :int ], Album
+    attach_function :artistbrowse_num_similar_artists, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_similar_artist, [ ArtistBrowse, :int ], Artist
+    attach_function :artistbrowse_biography, [ ArtistBrowse ], UTF8String
+    attach_function :artistbrowse_backend_request_duration, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_num_tophit_tracks, [ ArtistBrowse ], :int
+    attach_function :artistbrowse_tophit_track, [ ArtistBrowse, :int ], Track
+    attach_function :artistbrowse_add_ref, [ ArtistBrowse ], :error
+    attach_function :artistbrowse_release, [ ArtistBrowse ], :error
+  end
+end

data/lib/spotify/api/error.rb

@@ -0,0 +1,6 @@
+module Spotify
+  class API
+    # @!group Error
+    attach_function :error_message, [ :error ], UTF8String
+  end
+end

data/lib/spotify/api/image.rb

@@ -0,0 +1,16 @@
+module Spotify
+  class API
+    # @!group Image
+    attach_function :image_create, [ Session, ImageID ], Image
+    attach_function :image_add_load_callback, [ Image, :image_loaded_cb, :userdata ], :error
+    attach_function :image_remove_load_callback, [ Image, :image_loaded_cb, :userdata ], :error
+    attach_function :image_is_loaded, [ Image ], :bool
+    attach_function :image_error, [ Image ], :error
+    attach_function :image_format, [ Image ], :imageformat
+    attach_function :image_data, [ Image, :buffer_out ], :pointer
+    attach_function :image_image_id, [ Image ], ImageID
+    attach_function :image_create_from_link, [ Session, Link ], Image
+    attach_function :image_add_ref, [ Image ], :error
+    attach_function :image_release, [ Image ], :error
+  end
+end

data/lib/spotify/api/inbox.rb

@@ -0,0 +1,9 @@
+module Spotify
+  class API
+    # @!group Inbox
+    attach_function :inbox_post_tracks, [ Session, UTF8String, :array, :int, UTF8String, :inboxpost_complete_cb, :userdata ], Inbox
+    attach_function :inbox_error, [ Inbox ], :error
+    attach_function :inbox_add_ref, [ Inbox ], :error
+    attach_function :inbox_release, [ Inbox ], :error
+  end
+end

data/lib/spotify/api/link.rb

@@ -0,0 +1,25 @@
+module Spotify
+  class API
+    # @!group Link
+    attach_function :link_create_from_string, [ :string ], Link
+    attach_function :link_create_from_track, [ Track, :int ], Link
+    attach_function :link_create_from_album, [ Album ], Link
+    attach_function :link_create_from_artist, [ Artist ], Link
+    attach_function :link_create_from_search, [ Search ], Link
+    attach_function :link_create_from_playlist, [ Playlist ], Link
+    attach_function :link_create_from_artist_portrait, [ Artist, :image_size ], Link
+    attach_function :link_create_from_artistbrowse_portrait, [ ArtistBrowse, :int ], Link
+    attach_function :link_create_from_album_cover, [ Album, :image_size ], Link
+    attach_function :link_create_from_image, [ Image ], Link
+    attach_function :link_create_from_user, [ User ], Link
+    attach_function :link_as_string, [ Link, :buffer_out, :int ], :int
+    attach_function :link_type, [ Link ], :linktype
+    attach_function :link_as_track, [ Link ], Track
+    attach_function :link_as_track_and_offset, [ Link, :buffer_out ], Track
+    attach_function :link_as_album, [ Link ], Album
+    attach_function :link_as_artist, [ Link ], Artist
+    attach_function :link_as_user, [ Link ], User
+    attach_function :link_add_ref, [ Link ], :error
+    attach_function :link_release, [ Link ], :error
+  end
+end

data/lib/spotify/api/playlist.rb

@@ -0,0 +1,39 @@
+module Spotify
+  class API
+    # @!group Playlist
+    attach_function :playlist_is_loaded, [ Playlist ], :bool
+    attach_function :playlist_add_callbacks, [ Playlist, PlaylistCallbacks, :userdata ], :error
+    attach_function :playlist_remove_callbacks, [ Playlist, PlaylistCallbacks, :userdata ], :error
+    attach_function :playlist_num_tracks, [ Playlist ], :int
+    attach_function :playlist_track, [ Playlist, :int ], Track
+    attach_function :playlist_track_create_time, [ Playlist, :int ], :int
+    attach_function :playlist_track_creator, [ Playlist, :int ], User
+    attach_function :playlist_track_seen, [ Playlist, :int ], :bool
+    attach_function :playlist_track_set_seen, [ Playlist, :int, :bool ], :error
+    attach_function :playlist_track_message, [ Playlist, :int ], UTF8String
+    attach_function :playlist_name, [ Playlist ], UTF8String
+    attach_function :playlist_rename, [ Playlist, UTF8String ], :error
+    attach_function :playlist_owner, [ Playlist ], User
+    attach_function :playlist_is_collaborative, [ Playlist ], :bool
+    attach_function :playlist_set_collaborative, [ Playlist, :bool ], :error
+    attach_function :playlist_set_autolink_tracks, [ Playlist, :bool ], :error
+    attach_function :playlist_get_description, [ Playlist ], UTF8String
+    attach_function :playlist_get_image, [ Playlist, :buffer_out ], :bool
+    attach_function :playlist_has_pending_changes, [ Playlist ], :bool
+    attach_function :playlist_add_tracks, [ Playlist, :array, :int, :int, Session ], :error
+    attach_function :playlist_remove_tracks, [ Playlist, :array, :int ], :error
+    attach_function :playlist_reorder_tracks, [ Playlist, :array, :int, :int ], :error
+    attach_function :playlist_num_subscribers, [ Playlist ], :uint
+    attach_function :playlist_subscribers, [ Playlist ], Subscribers
+    attach_function :playlist_subscribers_free, [ Subscribers ], :error
+    attach_function :playlist_update_subscribers, [ Session, Playlist ], :error
+    attach_function :playlist_is_in_ram, [ Session, Playlist ], :bool
+    attach_function :playlist_set_in_ram, [ Session, Playlist, :bool ], :error
+    attach_function :playlist_create, [ Session, Link ], Playlist
+    attach_function :playlist_get_offline_status, [ Session, Playlist ], :playlist_offline_status
+    attach_function :playlist_get_offline_download_completed, [ Session, Playlist ], :int
+    attach_function :playlist_set_offline_mode, [ Session, Playlist, :bool ], :error
+    attach_function :playlist_add_ref, [ Playlist ], :error
+    attach_function :playlist_release, [ Playlist ], :error
+  end
+end

data/lib/spotify/api/playlist_container.rb

@@ -0,0 +1,23 @@
+module Spotify
+  class API
+    # @!group PlaylistContainer
+    attach_function :playlistcontainer_add_callbacks, [ PlaylistContainer, PlaylistContainerCallbacks, :userdata ], :error
+    attach_function :playlistcontainer_remove_callbacks, [ PlaylistContainer, PlaylistContainerCallbacks, :userdata ], :error
+    attach_function :playlistcontainer_num_playlists, [ PlaylistContainer ], :int
+    attach_function :playlistcontainer_playlist, [ PlaylistContainer, :int ], Playlist
+    attach_function :playlistcontainer_playlist_type, [ PlaylistContainer, :int ], :playlist_type
+    attach_function :playlistcontainer_playlist_folder_name, [ PlaylistContainer, :int, :buffer_out, :int ], :error
+    attach_function :playlistcontainer_playlist_folder_id, [ PlaylistContainer, :int ], :uint64
+    attach_function :playlistcontainer_add_new_playlist, [ PlaylistContainer, UTF8String ], Playlist
+    attach_function :playlistcontainer_add_playlist, [ PlaylistContainer, Link ], Playlist
+    attach_function :playlistcontainer_remove_playlist, [ PlaylistContainer, :int ], :error
+    attach_function :playlistcontainer_move_playlist, [ PlaylistContainer, :int, :int, :bool ], :error
+    attach_function :playlistcontainer_add_folder, [ PlaylistContainer, :int, UTF8String ], :error
+    attach_function :playlistcontainer_owner, [ PlaylistContainer ], User
+    attach_function :playlistcontainer_is_loaded, [ PlaylistContainer ], :bool
+    attach_function :playlistcontainer_get_unseen_tracks, [ PlaylistContainer, Playlist, :array, :int ], :int
+    attach_function :playlistcontainer_clear_unseen_tracks, [ PlaylistContainer, Playlist ], :int
+    attach_function :playlistcontainer_add_ref, [ PlaylistContainer ], :error
+    attach_function :playlistcontainer_release, [ PlaylistContainer ], :error
+  end
+end

data/lib/spotify/api/search.rb

@@ -0,0 +1,27 @@
+module Spotify
+  class API
+    # @!group Search
+    attach_function :search_create, [ Session, UTF8String, :int, :int, :int, :int, :int, :int, :int, :int, :search_type, :search_complete_cb, :userdata ], Search
+    attach_function :search_is_loaded, [ Search ], :bool
+    attach_function :search_error, [ Search ], :error
+    attach_function :search_query, [ Search ], UTF8String
+    attach_function :search_did_you_mean, [ Search ], UTF8String
+    attach_function :search_num_tracks, [ Search ], :int
+    attach_function :search_track, [ Search, :int ], Track
+    attach_function :search_num_albums, [ Search ], :int
+    attach_function :search_album, [ Search, :int ], Album
+    attach_function :search_num_artists, [ Search ], :int
+    attach_function :search_artist, [ Search, :int ], Artist
+    attach_function :search_num_playlists, [ Search ], :int
+    attach_function :search_playlist, [ Search, :int ], Playlist
+    attach_function :search_playlist_name, [ Search, :int ], UTF8String
+    attach_function :search_playlist_uri, [ Search, :int ], UTF8String
+    attach_function :search_playlist_image_uri, [ Search, :int ], UTF8String
+    attach_function :search_total_tracks, [ Search ], :int
+    attach_function :search_total_albums, [ Search ], :int
+    attach_function :search_total_artists, [ Search ], :int
+    attach_function :search_total_playlists, [ Search ], :int
+    attach_function :search_add_ref, [ Search ], :error
+    attach_function :search_release, [ Search ], :error
+  end
+end

data/lib/spotify/api/session.rb

@@ -0,0 +1,46 @@
+module Spotify
+  class API
+    # @!group Session
+    attach_function :session_create, [ SessionConfig, :buffer_out ], :error
+    attach_function :session_release, [ Session ], :error
+    attach_function :session_process_events, [ Session, :buffer_out ], :error
+    attach_function :session_login, [ Session, UTF8String, :string, :bool, :string ], :error
+    attach_function :session_relogin, [ Session ], :error
+    attach_function :session_forget_me, [ Session ], :error
+    attach_function :session_remembered_user, [ Session, :buffer_out, :size_t ], :int
+    attach_function :session_user, [ Session ], User
+    attach_function :session_logout, [ Session ], :error
+    attach_function :session_connectionstate, [ Session ], :connectionstate
+    attach_function :session_userdata, [ Session ], :userdata
+    attach_function :session_set_cache_size, [ Session, :size_t ], :error
+    attach_function :session_player_load, [ Session, Track ], :error
+    attach_function :session_player_seek, [ Session, :int ], :error
+    attach_function :session_player_play, [ Session, :bool ], :error
+    attach_function :session_player_unload, [ Session ], :error
+    attach_function :session_player_prefetch, [ Session, Track ], :error
+    attach_function :session_playlistcontainer, [ Session ], PlaylistContainer
+    attach_function :session_inbox_create, [ Session ], Playlist
+    attach_function :session_starred_create, [ Session ], Playlist
+    attach_function :session_starred_for_user_create, [ Session, UTF8String ], Playlist
+    attach_function :session_publishedcontainer_for_user_create, [ Session, UTF8String ], PlaylistContainer
+    attach_function :session_preferred_bitrate, [ Session, :bitrate ], :error
+    attach_function :session_set_connection_type, [ Session, :connection_type ], :error
+    attach_function :session_set_connection_rules, [ Session, :connection_rules ], :error
+    attach_function :offline_tracks_to_sync, [ Session ], :int
+    attach_function :offline_num_playlists, [ Session ], :int
+    attach_function :offline_sync_get_status, [ Session, OfflineSyncStatus ], :bool
+    attach_function :offline_time_left, [ Session ], :int
+    attach_function :session_user_country, [ Session ], :int
+    attach_function :session_preferred_offline_bitrate, [ Session, :bitrate, :bool ], :error
+    attach_function :session_set_volume_normalization, [ Session, :bool ], :error
+    attach_function :session_get_volume_normalization, [ Session ], :bool
+    attach_function :session_flush_caches, [ Session ], :error
+    attach_function :session_user_name, [ Session ], :string
+    attach_function :session_set_private_session, [ Session, :bool ], :error
+    attach_function :session_is_private_session, [ Session ], :bool
+    attach_function :session_set_scrobbling, [ Session, :social_provider, :scrobbling_state ], :error
+    attach_function :session_is_scrobbling, [ Session, :social_provider, :buffer_out ], :error
+    attach_function :session_is_scrobbling_possible, [ Session, :social_provider, :buffer_out ], :error
+    attach_function :session_set_social_credentials, [ Session, :social_provider, UTF8String, :string ], :error
+  end
+end

data/lib/spotify/api/toplist_browse.rb

@@ -0,0 +1,17 @@
+module Spotify
+  class API
+    # @!group ToplistBrowse
+    attach_function :toplistbrowse_create, [ Session, :toplisttype, :toplistregion, UTF8String, :toplistbrowse_complete_cb, :userdata ], ToplistBrowse
+    attach_function :toplistbrowse_is_loaded, [ ToplistBrowse ], :bool
+    attach_function :toplistbrowse_error, [ ToplistBrowse ], :error
+    attach_function :toplistbrowse_num_artists, [ ToplistBrowse ], :int
+    attach_function :toplistbrowse_artist, [ ToplistBrowse, :int ], Artist
+    attach_function :toplistbrowse_num_albums, [ ToplistBrowse ], :int
+    attach_function :toplistbrowse_album, [ ToplistBrowse, :int ], Album
+    attach_function :toplistbrowse_num_tracks, [ ToplistBrowse ], :int
+    attach_function :toplistbrowse_track, [ ToplistBrowse, :int ], Track
+    attach_function :toplistbrowse_backend_request_duration, [ ToplistBrowse ], :int
+    attach_function :toplistbrowse_add_ref, [ ToplistBrowse ], :error
+    attach_function :toplistbrowse_release, [ ToplistBrowse ], :error
+  end
+end

data/lib/spotify/api/track.rb

@@ -0,0 +1,26 @@
+module Spotify
+  class API
+    # @!group Track
+    attach_function :track_is_loaded, [ Track ], :bool
+    attach_function :track_error, [ Track ], :error
+    attach_function :track_get_availability, [ Session, Track ], :track_availability
+    attach_function :track_is_local, [ Session, Track ], :bool
+    attach_function :track_is_autolinked, [ Session, Track ], :bool
+    attach_function :track_is_starred, [ Session, Track ], :bool
+    attach_function :track_set_starred, [ Session, :array, :int, :bool ], :error
+    attach_function :track_num_artists, [ Track ], :int
+    attach_function :track_artist, [ Track, :int ], Artist
+    attach_function :track_album, [ Track ], Album
+    attach_function :track_name, [ Track ], UTF8String
+    attach_function :track_duration, [ Track ], :int
+    attach_function :track_popularity, [ Track ], :int
+    attach_function :track_disc, [ Track ], :int
+    attach_function :track_index, [ Track ], :int
+    attach_function :track_is_placeholder, [ Track ], :bool
+    attach_function :track_get_playable,  [ Session, Track ], Track
+    attach_function :track_offline_get_status, [ Track ], :track_offline_status
+    attach_function :localtrack_create, [ UTF8String, UTF8String, UTF8String, :int ], Track
+    attach_function :track_add_ref, [ Track ], :error
+    attach_function :track_release, [ Track ], :error
+  end
+end

data/lib/spotify/api/user.rb

@@ -0,0 +1,10 @@
+module Spotify
+  class API
+    # @!group User
+    attach_function :user_canonical_name, [ User ], UTF8String
+    attach_function :user_display_name, [ User ], UTF8String
+    attach_function :user_is_loaded, [ User ], :bool
+    attach_function :user_add_ref, [ User ], :error
+    attach_function :user_release, [ User ], :error
+  end
+end

data/lib/spotify/defines.rb

@@ -0,0 +1,109 @@
+module Spotify
+  class API
+    typedef :pointer, :frames
+    typedef :pointer, :userdata
+    typedef :pointer, :array
+
+    #
+    # Error
+    #
+    enum :error, [:ok, 0,
+                  :bad_api_version, :api_initialization_failed, :track_not_playable,
+
+                  :bad_application_key, 5,
+                  :bad_username_or_password, :user_banned,
+                  :unable_to_contact_server, :client_too_old, :other_permanent,
+                  :bad_user_agent, :missing_callback, :invalid_indata,
+                  :index_out_of_range, :user_needs_premium, :other_transient,
+                  :is_loading, :no_stream_available, :permission_denied,
+                  :inbox_is_full, :no_cache, :no_such_user, :no_credentials,
+                  :network_disabled, :invalid_device_id, :cant_open_trace_file,
+                  :application_banned,
+
+                  :offline_too_many_tracks, 31,
+                  :offline_disk_cache, :offline_expired, :offline_not_allowed,
+                  :offline_license_lost, :offline_license_error,
+
+                  :lastfm_auth_error, 39,
+                  :invalid_argument, :system_failure]
+
+    #
+    # Audio
+    #
+    enum :sampletype, [:int16] # int16_native_endian
+    enum :bitrate, %w(160k 320k 96k).map(&:to_sym)
+
+    #
+    # Session
+    #
+    enum :social_provider, [:spotify, :facebook, :lastfm]
+    enum :scrobbling_state, [:use_global_setting, :local_enabled, :local_disabled, :global_enabled, :global_disabled]
+    enum :connectionstate, [:logged_out, :logged_in, :disconnected, :undefined, :offline]
+    enum :connection_type, [:unknown, :none, :mobile, :mobile_roaming, :wifi, :wired]
+    enum :connection_rules, [:network               , 0x1,
+                             :network_if_roaming    , 0x2,
+                             :allow_sync_over_mobile, 0x4,
+                             :allow_sync_over_wifi  , 0x8]
+
+    #
+    # Image
+    #
+    callback :image_loaded_cb, [ Image.retaining_class, :userdata ], :void
+    enum :imageformat, [:unknown, -1, :jpeg]
+    enum :image_size, [ :normal, :small, :large ]
+
+    #
+    # Link
+    #
+    enum :linktype, [:invalid, :track, :album, :artist, :search,
+                     :playlist, :profile, :starred, :localtrack, :image]
+
+    #
+    # Track
+    #
+    enum :availability, [:unavailable, :available, :not_streamable, :banned_by_artist]
+    typedef :availability, :track_availability # for automated testing
+    enum :track_offline_status, [:no, :waiting, :downloading, :done, :error, :done_expired, :limit_exceeded, :done_resync]
+
+    #
+    # Album
+    #
+    callback :albumbrowse_complete_cb, [AlbumBrowse.retaining_class, :userdata], :void
+    enum :albumtype, [:album, :single, :compilation, :unknown]
+
+    #
+    # Artist browsing
+    #
+    callback :artistbrowse_complete_cb, [ArtistBrowse.retaining_class, :userdata], :void
+    enum :artistbrowse_type, [:full, :no_tracks, :no_albums]
+
+    #
+    # Search
+    #
+    callback :search_complete_cb, [Search.retaining_class, :userdata], :void
+    enum :search_type, [:standard, :suggest]
+
+    #
+    # Playlist
+    #
+    enum :playlist_type, [:playlist, :start_folder, :end_folder, :placeholder]
+    enum :playlist_offline_status, [:no, :yes, :downloading, :waiting]
+
+    #
+    # User
+    #
+    enum :relation_type, [:unknown, :none, :unidirectional, :bidirectional]
+
+    #
+    # Toplist
+    #
+    callback :toplistbrowse_complete_cb, [ToplistBrowse.retaining_class, :userdata], :void
+    enum :toplisttype, [:artists, :albums, :tracks]
+    enum :toplistregion, [:everywhere, :user]
+
+    #
+    # Inbox
+    #
+    callback :inboxpost_complete_cb, [Inbox.retaining_class, :userdata], :void
+  end
+end

data/lib/spotify/error.rb

@@ -0,0 +1,62 @@
+module Spotify
+  # A generic error class for Spotify errors.
+  class Error < StandardError
+    class << self
+      # Explain a Spotify error with a descriptive message.
+      #
+      # @param [Symbol, Integer] error
+      # @return [String] a decriptive string of the error
+      def explain(error)
+        error, symbol = disambiguate(error)
+
+        message = []
+        message << "[#{symbol.to_s.upcase}]"
+        message << Spotify.error_message(error)
+        message << "(#{error})"
+
+        message.join(' ')
+      end
+
+      # Given a number or a symbol, find both the symbol and the error
+      # number it represents.
+      #
+      # @example given an integer
+      #   Spotify::Error.disambiguate(0) # => [0, :ok]
+      #
+      # @example given a symbol
+      #   Spotify::Error.disambiguate(:ok) # => [0, :ok]
+      #
+      # @example given bogus
+      #   Spotify::Error.disambiguate(:bogus) # => [-1, nil]
+      #
+      # @param [Symbol, Fixnum] error
+      # @return [[Fixnum, Symbol]] (error code, error symbol)
+      def disambiguate(error)
+        @enum ||= Spotify.enum_type(:error)
+
+        if error.is_a? Symbol
+          error = @enum[symbol = error]
+        else
+          symbol = @enum[error]
+        end
+
+        if error.nil? || symbol.nil?
+          [-1, nil]
+        else
+          [error, symbol]
+        end
+      end
+    end
+
+    # Overridden to allow raising errors with just an error code.
+    #
+    # @param [Integer, String] code_or_message spotify error code, or string message.
+    def initialize(code_or_message = nil)
+      if code_or_message.is_a?(Integer) or code_or_message.is_a?(Symbol)
+        code_or_message &&= self.class.explain(code_or_message)
+      end
+
+      super(code_or_message)
+    end
+  end
+end