Class: Spotify::API Private

Inherits:
Object
  • Object
show all
Extended by:
FFI::Library, APIHelpers
Includes:
APIHelpers
Defined in:
lib/spotify/api.rb,
lib/spotify/types.rb,
lib/spotify/api/link.rb,
lib/spotify/api/user.rb,
lib/spotify/api/album.rb,
lib/spotify/api/error.rb,
lib/spotify/api/image.rb,
lib/spotify/api/inbox.rb,
lib/spotify/api/track.rb,
lib/spotify/api/artist.rb,
lib/spotify/api/search.rb,
lib/spotify/api/session.rb,
lib/spotify/api/playlist.rb,
lib/spotify/api/album_browse.rb,
lib/spotify/api/artist_browse.rb,
lib/spotify/api/miscellaneous.rb,
lib/spotify/api/toplist_browse.rb,
lib/spotify/api/playlist_container.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Note:

The API is private because this class is an implementation detail.

Note:

You should never call any Spotify::API.method() directly, but instead you should call them via Spotify.method(). libspotify is not thread-safe, but it is documented to be okay to call the API from multiple threads if you only call one function at a time, which is ensured by the lock in the Spotify module.

API is the class which has all libspotify functions attached.

All functions are attached as both instance methods and class methods, mainly because that’s how FFI works it’s magic with attach_function. However, as this is a class it allows to be instantiated.

Link collapse

User collapse

Album collapse

Error collapse

Image collapse

Inbox collapse

Track collapse

Artist collapse

Search collapse

Session collapse

Playlist collapse

AlbumBrowse collapse

ArtistBrowse collapse

Miscellaneous collapse

ToplistBrowse collapse

PlaylistContainer collapse

Class Method Summary collapse

Methods included from APIHelpers

with_buffer, with_string_buffer

Class Method Details

.attach_function(c_name = nil, name, args, returns, &block) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Overloaded to ensure all methods are defined as blocking, and they return a managed pointer with the correct refcount.

Parameters:

  • name (#to_s) —

    function name sans sp_ prefix.

  • args (Array)
  • returns (Object) 


40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/spotify/api.rb', line 40

def self.attach_function(c_name = nil, name, args, returns, &block)
  if returns.respond_to?(:retaining_class) && name !~ /create/
    returns = returns.retaining_class
  end

  options  = { blocking: true }
  name = name.to_sym
  c_name ||= :"sp_#{name}"
  super(name, c_name, args, returns, options)

  if block_given?
    alias_method c_name, name
    define_method name, &block

    singleton_class.instance_eval do
      alias_method c_name, name
      define_method name, &block
    end

    name
  end
end

Instance Method Details

#album_artist(album) ⇒ Artist?

Note:

the album must be loaded, or this function always return nil.

Returns authoring artist of the album.

Parameters:

Returns:

  • (Artist, nil) —

    authoring artist of the album

See Also:



22
 
# File 'lib/spotify/api/album.rb', line 22

attach_function :album_artist, [ Album ], Artist

#album_cover(album, image_size) ⇒ String?

Note:

the album must be loaded, or this function always return nil.

Returns image ID to pass to #image_create, or nil if the album has no image.

Parameters:

  • album (Album)
  • image_size (Symbol) —

    one of :normal, :small, :large

Returns:

  • (String, nil) —

    image ID to pass to #image_create, or nil if the album has no image

See Also:



31
 
# File 'lib/spotify/api/album.rb', line 31

attach_function :album_cover, [ Album, :image_size ], ImageID

#album_is_available(album) ⇒ Boolean

Note:

the album must be loaded, or this function always return false.

Returns true if the album is available for playback.

Parameters:

Returns:

  • (Boolean) —

    true if the album is available for playback

See Also:



15
 
# File 'lib/spotify/api/album.rb', line 15

attach_function :album_is_available, [ Album ], :bool

#album_is_loaded(album) ⇒ Boolean

Returns true if the album is populated with data.

Parameters:

Returns:

  • (Boolean) —

    true if the album is populated with data



8
 
# File 'lib/spotify/api/album.rb', line 8

attach_function :album_is_loaded, [ Album ], :bool

#album_name(album) ⇒ String

Note:

the album must be loaded, or this function always return an empty string.

Returns name of the album.

Parameters:

Returns:

  • (String) —

    name of the album

See Also:



38
 
# File 'lib/spotify/api/album.rb', line 38

attach_function :album_name, [ Album ], UTF8String

#album_type(album) ⇒ Symbol

Note:

the album must be loaded, or this function always return :unknown.

Returns album type, one of :album, :single, :compilation, :unknown.

Parameters:

Returns:

  • (Symbol) —

    album type, one of :album, :single, :compilation, :unknown

See Also:



52
 
# File 'lib/spotify/api/album.rb', line 52

attach_function :album_type, [ Album ], :albumtype

#album_year(album) ⇒ String

Note:

the album must be loaded, or this function always return 0.

Returns release year of the album.

Parameters:

Returns:

  • (String) —

    release year of the album

See Also:



45
 
# File 'lib/spotify/api/album.rb', line 45

attach_function :album_year, [ Album ], :int

#albumbrowse_album(album_browse) ⇒ Album?

Note:

the album browse request must have completed, or this function always return nil.

Returns the album being browsed.

Parameters:

Returns:

  • (Album, nil) —

    the album being browsed

See Also:



36
 
# File 'lib/spotify/api/album_browse.rb', line 36

attach_function :albumbrowse_album, [ AlbumBrowse ], Album

#albumbrowse_artist(album_browse) ⇒ Artist?

Note:

the album browse request must have completed, or this function always return nil.

Returns the authoring artist of the album being browsed.

Parameters:

Returns:

  • (Artist, nil) —

    the authoring artist of the album being browsed

See Also:



43
 
# File 'lib/spotify/api/album_browse.rb', line 43

attach_function :albumbrowse_artist, [ AlbumBrowse ], Artist

#albumbrowse_backend_request_duration(album_browse) ⇒ Integer

Note:

the album browse request must have completed, or this function will return an undefined value.

Returns the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache.

Parameters:

Returns:

  • (Integer) —

    the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache

See Also:



91
 
# File 'lib/spotify/api/album_browse.rb', line 91

attach_function :albumbrowse_backend_request_duration, [ AlbumBrowse ], :int

#albumbrowse_copyright(album_browse, index) ⇒ String?

Note:

if index is out of range, returns nil.

Returns the copyright string at index.

Parameters:

Returns:

  • (String, nil) —

    the copyright string at index

See Also:



60
 
# File 'lib/spotify/api/album_browse.rb', line 60

attach_function :albumbrowse_copyright, [ AlbumBrowse, :int ], UTF8String

#albumbrowse_create(session, album, albumbrowse_complete_callback, userdata) ⇒ AlbumBrowse

Note:

make very sure the callback proc is not garbage collected before it is called!

Returns a request for browsing an album.

Examples:

# this is called some time later, as a result of calling {#session_process_events}
browse_callback = proc do |album_browse|
  puts "Album browse has completed!"
end
album_browse = Spotify.albumbrowse_create(session, album, browse_callback, nil)

Parameters:

Returns:



19
 
# File 'lib/spotify/api/album_browse.rb', line 19

attach_function :albumbrowse_create, [ Session, Album, :albumbrowse_complete_cb, :userdata ], AlbumBrowse

#albumbrowse_error(album_browse) ⇒ Symbol

Returns album browsing error code.

Parameters:

Returns:

  • (Symbol) —

    album browsing error code



29
 
# File 'lib/spotify/api/album_browse.rb', line 29

attach_function :albumbrowse_error, [ AlbumBrowse ], APIError

#albumbrowse_is_loaded(album_browse) ⇒ Boolean

Returns true if the album browse request has completed.

Parameters:

Returns:

  • (Boolean) —

    true if the album browse request has completed



24
 
# File 'lib/spotify/api/album_browse.rb', line 24

attach_function :albumbrowse_is_loaded, [ AlbumBrowse ], :bool

#albumbrowse_num_copyrights(album_browse) ⇒ Integer

Note:

the album browse request must have completed, or this function always return 0.

Returns number of copyright strings on the album being browsed.

Parameters:

Returns:

  • (Integer) —

    number of copyright strings on the album being browsed

See Also:



51
 
# File 'lib/spotify/api/album_browse.rb', line 51

attach_function :albumbrowse_num_copyrights, [ AlbumBrowse ], :int

#albumbrowse_num_tracks(album_browse) ⇒ Integer

Note:

the album browse request must have completed, or this function always return 0.

Returns number of tracks on the album being browsed.

Parameters:

Returns:

  • (Integer) —

    number of tracks on the album being browsed

See Also:



68
 
# File 'lib/spotify/api/album_browse.rb', line 68

attach_function :albumbrowse_num_tracks, [ AlbumBrowse ], :int

#albumbrowse_review(album_browse) ⇒ String

Note:

the album browse request must have completed, or this function always return an empty string.

Returns the review for the album being browsed.

Parameters:

Returns:

  • (String) —

    the review for the album being browsed

See Also:



84
 
# File 'lib/spotify/api/album_browse.rb', line 84

attach_function :albumbrowse_review, [ AlbumBrowse ], UTF8String

#albumbrowse_track(album_browse, index) ⇒ Track?

Note:

if index is out of range, returns nil.

Returns the track at index.

Parameters:

Returns:

  • (Track, nil) —

    the track at index

See Also:



77
 
# File 'lib/spotify/api/album_browse.rb', line 77

attach_function :albumbrowse_track, [ AlbumBrowse, :int ], Track

#artist_is_loaded(artist) ⇒ Boolean

Returns true if the artist is populated with data.

Parameters:

Returns:

  • (Boolean) —

    true if the artist is populated with data



15
 
# File 'lib/spotify/api/artist.rb', line 15

attach_function :artist_is_loaded, [ Artist ], :bool

#artist_name(artist) ⇒ String

Note:

the artist must be loaded, or this function always return an empty string.

Returns name of the artist.

Parameters:

Returns:

  • (String) —

    name of the artist

See Also:



10
 
# File 'lib/spotify/api/artist.rb', line 10

attach_function :artist_name, [ Artist ], UTF8String

#artist_portrait(artist, image_size) ⇒ String?

Note:

the artist must be loaded, or this function always return nil.

Returns image ID to pass to #image_create, or nil if the artist has no image.

Parameters:

  • artist (Artist)
  • image_size (Symbol) —

    one of :normal, :small, :large

Returns:

  • (String, nil) —

    image ID to pass to #image_create, or nil if the artist has no image

See Also:



24
 
# File 'lib/spotify/api/artist.rb', line 24

attach_function :artist_portrait, [ Artist, :image_size ], ImageID

#artistbrowse_album(artist_browse, index) ⇒ Track?

Note:

if index is out of range, returns nil.

Returns the album at index.

Parameters:

Returns:

  • (Track, nil) —

    the album at index

See Also:



88
 
# File 'lib/spotify/api/artist_browse.rb', line 88

attach_function :artistbrowse_album, [ ArtistBrowse, :int ], Album

#artistbrowse_artist(artist_browse) ⇒ Artist?

Note:

the artist browse request must have completed, or this function always return nil.

Returns the artist being browsed.

Parameters:

Returns:

  • (Artist, nil) —

    the artist being browsed

See Also:



37
 
# File 'lib/spotify/api/artist_browse.rb', line 37

attach_function :artistbrowse_artist, [ ArtistBrowse ], Artist

#artistbrowse_backend_request_duration(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function will return an undefined value.

Returns the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache.

Parameters:

Returns:

  • (Integer) —

    the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache

See Also:



119
 
# File 'lib/spotify/api/artist_browse.rb', line 119

attach_function :artistbrowse_backend_request_duration, [ ArtistBrowse ], :int

#artistbrowse_biography(artist_browse) ⇒ String

Note:

the artist browse request must have completed, or this function always return an empty string.

Returns the review for the artist being browsed.

Parameters:

Returns:

  • (String) —

    the review for the artist being browsed

See Also:



112
 
# File 'lib/spotify/api/artist_browse.rb', line 112

attach_function :artistbrowse_biography, [ ArtistBrowse ], UTF8String

#artistbrowse_create(session, artist, type, callback, userdata) ⇒ ArtistBrowse

Note:

make very sure the callback proc is not garbage collected before it is called!

Returns a request for browsing an artist.

Examples:

# this is called some time later, as a result of calling {#session_process_events}
browse_callback = proc do |artist_browse|
  puts "Artist browse has completed!"
end
artist_browse = Spotify.artistbrowse_create(session, artist, :no_albums, browse_callback, nil)

Parameters:

  • session (Session)
  • artist (Artist)
  • type (Symbol) —

    one of :full, :no_tracks, :no_albums

  • callback (Proc<ArtistBrowse, FFI::Pointer>)
  • userdata (FFI::Pointer)

Returns:



20
 
# File 'lib/spotify/api/artist_browse.rb', line 20

attach_function :artistbrowse_create, [ Session, Artist, :artistbrowse_type, :artistbrowse_complete_cb, :userdata ], ArtistBrowse

#artistbrowse_error(artist_browse) ⇒ Symbol

Returns artist browsing error code.

Parameters:

Returns:

  • (Symbol) —

    artist browsing error code



30
 
# File 'lib/spotify/api/artist_browse.rb', line 30

attach_function :artistbrowse_error, [ ArtistBrowse ], APIError

#artistbrowse_is_loaded(artist_browse) ⇒ Boolean

Returns true if the artist browse request has completed.

Parameters:

Returns:

  • (Boolean) —

    true if the artist browse request has completed



25
 
# File 'lib/spotify/api/artist_browse.rb', line 25

attach_function :artistbrowse_is_loaded, [ ArtistBrowse ], :bool

#artistbrowse_num_albums(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function always return 0.

Returns number of artist albums.

Parameters:

Returns:

  • (Integer) —

    number of artist albums

See Also:



79
 
# File 'lib/spotify/api/artist_browse.rb', line 79

attach_function :artistbrowse_num_albums, [ ArtistBrowse ], :int

#artistbrowse_num_portraits(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function always return 0.

Returns number of artist portraits.

Parameters:

Returns:

  • (Integer) —

    number of artist portraits

See Also:



45
 
# File 'lib/spotify/api/artist_browse.rb', line 45

attach_function :artistbrowse_num_portraits, [ ArtistBrowse ], :int

#artistbrowse_num_similar_artists(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function always return 0.

Returns number of similar artists.

Parameters:

Returns:

  • (Integer) —

    number of similar artists

See Also:



96
 
# File 'lib/spotify/api/artist_browse.rb', line 96

attach_function :artistbrowse_num_similar_artists, [ ArtistBrowse ], :int

#artistbrowse_num_tophit_tracks(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function always return 0.

Returns number of tophit tracks.

Parameters:

Returns:

  • (Integer) —

    number of tophit tracks

See Also:



127
 
# File 'lib/spotify/api/artist_browse.rb', line 127

attach_function :artistbrowse_num_tophit_tracks, [ ArtistBrowse ], :int

#artistbrowse_num_tracks(artist_browse) ⇒ Integer

Note:

the artist browse request must have completed, or this function always return 0.

Returns number of artist tracks.

Parameters:

Returns:

  • (Integer) —

    number of artist tracks

See Also:



62
 
# File 'lib/spotify/api/artist_browse.rb', line 62

attach_function :artistbrowse_num_tracks, [ ArtistBrowse ], :int

#artistbrowse_portrait(artist_browse, index) ⇒ String?

Note:

if index is out of range, returns nil.

Returns image ID to pass to #image_create.

Parameters:

Returns:

See Also:



54
 
# File 'lib/spotify/api/artist_browse.rb', line 54

attach_function :artistbrowse_portrait, [ ArtistBrowse, :int ], ImageID

#artistbrowse_similar_artist(artist_browse, index) ⇒ Track?

Note:

if index is out of range, returns nil.

Returns a similar artist at index.

Parameters:

Returns:

  • (Track, nil) —

    a similar artist at index

See Also:



105
 
# File 'lib/spotify/api/artist_browse.rb', line 105

attach_function :artistbrowse_similar_artist, [ ArtistBrowse, :int ], Artist

#artistbrowse_tophit_track(artist_browse, index) ⇒ Track?

Note:

if index is out of range, returns nil.

Returns the tophit track at index.

Parameters:

Returns:

  • (Track, nil) —

    the tophit track at index

See Also:



136
 
# File 'lib/spotify/api/artist_browse.rb', line 136

attach_function :artistbrowse_tophit_track, [ ArtistBrowse, :int ], Track

#artistbrowse_track(artist_browse, index) ⇒ Track?

Note:

if index is out of range, returns nil.

Returns the track at index.

Parameters:

Returns:

  • (Track, nil) —

    the track at index

See Also:



71
 
# File 'lib/spotify/api/artist_browse.rb', line 71

attach_function :artistbrowse_track, [ ArtistBrowse, :int ], Track

#build_id ⇒ String

Returns libspotify build ID.

Returns:

  • (String) —

    libspotify build ID

See Also:



8
 
# File 'lib/spotify/api/miscellaneous.rb', line 8

attach_function :build_id, [], UTF8String

#error_message(error) ⇒ String

Returns explanatory error message for an error code.

Parameters:

Returns:

  • (String) —

    explanatory error message for an error code



8
 
# File 'lib/spotify/api/error.rb', line 8

attach_function :error_message, [ APIError ], UTF8String

#image_add_load_callback(image, callback, userdata) ⇒ Symbol

Note:

make very sure the callback proc is not garbage collected before it is called!

Add a callback that will be invoked when the image is loaded.

Parameters:

  • image (Image)
  • callback (Proc<Image, FFI::Pointer>)
  • userdata (FFI::Pointer)

Returns:

  • (Symbol) —

    error code

See Also:



20
 
# File 'lib/spotify/api/image.rb', line 20

attach_function :image_add_load_callback, [ Image, :image_loaded_cb, :userdata ], APIError

#image_create(session, image_id) ⇒ Image

Returns image from an image id.

Parameters:

  • session (Session)
  • image_id (String)

Returns:

  • (Image) —

    image from an image id



9
 
# File 'lib/spotify/api/image.rb', line 9

attach_function :image_create, [ Session, ImageID ], Image

#image_create_from_link(session, link) ⇒ Image?

Returns image pointed to by link, or nil if link is not a valid image link.

Parameters:

Returns:

  • (Image, nil) —

    image pointed to by link, or nil if link is not a valid image link



77
 
# File 'lib/spotify/api/image.rb', line 77

attach_function :image_create_from_link, [ Session, Link ], Image

#image_data(image) ⇒ String?

Note:

the image must be loaded, or this function always return nil.

Retrieves raw image data.

Examples:

Spotify.image_data(image) # => "\xFF\xD8\xFF\xE0…

Parameters:

Returns:

  • (String, nil) —

    raw image data, or nil if no image data available

See Also:



60
61
62
63
64
65
66
 
# File 'lib/spotify/api/image.rb', line 60

attach_function :image_data, [ Image, :buffer_out ], :pointer do |image|
  with_buffer(:size_t, clear: true) do |image_size_buffer|
    data = sp_image_data(image, image_size_buffer)
    image_size = image_size_buffer.read_size_t
    data.read_bytes(image_size) if image_size > 0
  end
end

#image_error(image) ⇒ Symbol

Returns image error code.

Parameters:

Returns:

  • (Symbol) —

    image error code



41
 
# File 'lib/spotify/api/image.rb', line 41

attach_function :image_error, [ Image ], APIError

#image_format(image) ⇒ Symbol

Note:

the image must be loaded, or this function always return :unknown.

Returns image format, one of :unknown, or :jpeg.

Parameters:

Returns:

  • (Symbol) —

    image format, one of :unknown, or :jpeg

See Also:



48
 
# File 'lib/spotify/api/image.rb', line 48

attach_function :image_format, [ Image ], :imageformat

#image_image_id(image) ⇒ String

Returns image id.

Parameters:

Returns:

  • (String) —

    image id



71
 
# File 'lib/spotify/api/image.rb', line 71

attach_function :image_image_id, [ Image ], ImageID

#image_is_loaded(image) ⇒ Boolean

Note:

Images that don’t exist in Spotify can also return true.

Returns true if the image information has been retrieved.

Parameters:

Returns:

  • (Boolean) —

    true if the image information has been retrieved



36
 
# File 'lib/spotify/api/image.rb', line 36

attach_function :image_is_loaded, [ Image ], :bool

#image_remove_load_callback(image, callback, userdata) ⇒ Symbol

Remove an image load callback previously added with #image_add_load_callback.

Parameters:

  • image (Image)
  • callback (Proc<Image, FFI::Pointer>)
  • userdata (FFI::Pointer)

Returns:

  • (Symbol) —

    error code

See Also:



30
 
# File 'lib/spotify/api/image.rb', line 30

attach_function :image_remove_load_callback, [ Image, :image_loaded_cb, :userdata ], APIError

#inbox_error(inbox) ⇒ Symbol

Returns error status of inbox post.

Parameters:

Returns:

  • (Symbol) —

    error status of inbox post



33
 
# File 'lib/spotify/api/inbox.rb', line 33

attach_function :inbox_error, [ Inbox ], APIError

#inbox_post_tracks(session, username, tracks, message, callback, userdata) ⇒ Inbox

Post an array of tracks to a Spotify user’s inbox.

Examples:

callback = proc do |inbox|
  puts "Message posted."
end
inbox = Spotify.inbox_post_tracks(session, "burgestrand", tracks, "You must listen to these!", callback, nil)

Parameters:

  • session (Session)
  • username (String) —

    canonical username of recipient

  • tracks (Array<Track>, Track)
  • message (String) —

    message to attach to post

  • Proc<Inbox, (Proc<Inbox, FFI::Pointer] callback to call on completion) —

    FFI::Pointer] callback to call on completion

  • userdata (FFI::Pointer)

Returns:



21
22
23
24
25
26
27
28
 
# File 'lib/spotify/api/inbox.rb', line 21

attach_function :inbox_post_tracks, [ Session, UTF8String, :array, :int, UTF8String, :inboxpost_complete_cb, :userdata ], Inbox do |session, username, tracks, message, callback, userdata|
  tracks = Array(tracks)

  with_buffer(Spotify::Track, size: tracks.length) do |tracks_buffer|
    tracks_buffer.write_array_of_pointer(tracks)
    sp_inbox_post_tracks(session, username, tracks_buffer, tracks.length, message, callback, userdata)
  end
end

#link_as_album(link) ⇒ Album?

Returns album pointed to by the link, or nil if not an album.

Parameters:

Returns:

  • (Album, nil) —

    album pointed to by the link, or nil if not an album



123
 
# File 'lib/spotify/api/link.rb', line 123

attach_function :link_as_album, [ Link ], Album

#link_as_artist(link) ⇒ Artist?

Returns artist pointed to by the link, or nil if not an artist.

Parameters:

Returns:

  • (Artist, nil) —

    artist pointed to by the link, or nil if not an artist



128
 
# File 'lib/spotify/api/link.rb', line 128

attach_function :link_as_artist, [ Link ], Artist

#link_as_string(link) ⇒ String

Retrieve string representation of link.

Examples:

Spotify.link_as_string(link) # => "spotify:user:burgestrand"

Parameters:

Returns:

  • (String) —

    string representation of the link



87
88
89
90
91
92
 
# File 'lib/spotify/api/link.rb', line 87

attach_function :link_as_string, [ Link, :buffer_out, :int ], :int do |link|
  link_length = sp_link_as_string(link, nil, 0)
  with_string_buffer(link_length) do |string_buffer, size|
    sp_link_as_string(link, string_buffer, size)
  end
end

#link_as_track(link) ⇒ Track?

Returns track pointed to by the link, or nil if not a track.

Parameters:

Returns:

  • (Track, nil) —

    track pointed to by the link, or nil if not a track



102
 
# File 'lib/spotify/api/link.rb', line 102

attach_function :link_as_track, [ Link ], Track

#link_as_track_and_offset(link) ⇒ Array<Track, Integer>?

Note:

if the link is not a track link, this method returns nil.

Note:

if no track offset is available in the link, the offset out will always be set to 0.

Returns track and offset (in ms) as a tuple, or nil.

Examples:

Spotify.link_as_track_and_offset(link) # => [track, 1337]

Parameters:

Returns:

  • (Array<Track, Integer>, nil) —

    track and offset (in ms) as a tuple, or nil



113
114
115
116
117
118
 
# File 'lib/spotify/api/link.rb', line 113

attach_function :link_as_track_and_offset, [ Link, :buffer_out ], Track do |link|
  with_buffer(:int) do |offset_buffer|
    track = sp_link_as_track_and_offset(link, offset_buffer)
    [track, offset_buffer.read_int] if track
  end
end

#link_as_user(link) ⇒ User?

Returns user pointed to by the link, or nil if not a user.

Parameters:

Returns:

  • (User, nil) —

    user pointed to by the link, or nil if not a user



133
 
# File 'lib/spotify/api/link.rb', line 133

attach_function :link_as_user, [ Link ], User

#link_create_from_album(album) ⇒ Link?

Parameters:

Returns:



21
 
# File 'lib/spotify/api/link.rb', line 21

attach_function :link_create_from_album, [ Album ], Link

#link_create_from_album_cover(album, image_size) ⇒ Link?

Parameters:

  • album (Album)
  • image_size (Symbol) —

    one of :normal, :small, :large

Returns:



55
 
# File 'lib/spotify/api/link.rb', line 55

attach_function :link_create_from_album_cover, [ Album, :image_size ], Link

#link_create_from_artist(artist) ⇒ Link?

Parameters:

Returns:



26
 
# File 'lib/spotify/api/link.rb', line 26

attach_function :link_create_from_artist, [ Artist ], Link

#link_create_from_artist_portrait(artist, image_size) ⇒ Link?

Parameters:

  • artist (Artist)
  • image_size (Symbol) —

    one of :normal, :small, :large

Returns:



42
 
# File 'lib/spotify/api/link.rb', line 42

attach_function :link_create_from_artist_portrait, [ Artist, :image_size ], Link

#link_create_from_artistbrowse_portrait(artist_browse, index) ⇒ Link?

Parameters:

Returns:

See Also:



49
 
# File 'lib/spotify/api/link.rb', line 49

attach_function :link_create_from_artistbrowse_portrait, [ ArtistBrowse, :int ], Link

#link_create_from_image(image) ⇒ Link

Examples:

image id from spotify URI

image_id = ":\xD94#\xAD\xD9\x97f\xE0-V6\x05\xC6\xE7n\xD2\xB0\xE4P"
image_uri = "spotify:image:3ad93423add99766e02d563605c6e76ed2b0e450"
image = Spotify.image_create(session, image_id)
image_link = Spotify.link_create_from_image(image)

# And here are some cool equivalents:
image_id == ["3ad93423add99766e02d563605c6e76ed2b0e450"].pack("H40")
image_uri == "spotify:image:#{image_id.unpack("H40")[0]}"
image_link == Spotify.link_create_from_string(image_uri)
image == Spotify.image_create_from_link(session, image_link)

Parameters:

Returns:



72
 
# File 'lib/spotify/api/link.rb', line 72

attach_function :link_create_from_image, [ Image ], Link

#link_create_from_playlist(playlist) ⇒ Link?

Parameters:

Returns:



36
 
# File 'lib/spotify/api/link.rb', line 36

attach_function :link_create_from_playlist, [ Playlist ], Link

#link_create_from_search(search) ⇒ Link?

Parameters:

Returns:



31
 
# File 'lib/spotify/api/link.rb', line 31

attach_function :link_create_from_search, [ Search ], Link

#link_create_from_string(spotify_uri) ⇒ Link

Create a Link from a Spotify URI or Spotify HTTP URL.

Parameters:

  • spotify_uri (String) —

    can be regular spotify URI, or spotify HTTP URL

Returns:



10
 
# File 'lib/spotify/api/link.rb', line 10

attach_function :link_create_from_string, [ BestEffortString ], Link

#link_create_from_track(track, offset) ⇒ Link?

Parameters:

  • track (Track)
  • offset (Integer) —

    number of milliseconds into track to link to

Returns:



16
 
# File 'lib/spotify/api/link.rb', line 16

attach_function :link_create_from_track, [ Track, :int ], Link

#link_create_from_user(user) ⇒ Link

Parameters:

Returns:



77
 
# File 'lib/spotify/api/link.rb', line 77

attach_function :link_create_from_user, [ User ], Link

#link_type(link) ⇒ Symbol

Returns type of link, one of :invalid, :track, :album, :artist, :search, :playlist, :profile, :starred, :localtrack, :image.

Parameters:

Returns:

  • (Symbol) —

    type of link, one of :invalid, :track, :album, :artist, :search, :playlist, :profile, :starred, :localtrack, :image



97
 
# File 'lib/spotify/api/link.rb', line 97

attach_function :link_type, [ Link ], :linktype

#localtrack_create(artist, title, album, duration) ⇒ Track

Create a local Track reference, whatever that means.

Examples:

track = Spotify.localtrack_create("Indianer", "The Best Of Indianer", "Armonia", 343_000)
# track spotify URI is: spotify:local:Indianer:Armonia:The+Best+Of+Indianer:34

Parameters:

  • artist (String)
  • title (String)
  • album (String)
  • duration (Integer) —

    in milliseconds, or -1 if not available

Returns:



151
 
# File 'lib/spotify/api/track.rb', line 151

attach_function :localtrack_create, [ UTF8String, UTF8String, UTF8String, :int ], Track

#offline_num_playlists(session) ⇒ Integer

Returns total number of playlists marked for offline synchronization.

Parameters:

Returns:

  • (Integer) —

    total number of playlists marked for offline synchronization



275
 
# File 'lib/spotify/api/session.rb', line 275

attach_function :offline_num_playlists, [ Session ], :int

#offline_sync_get_status(session, offline_sync_status) ⇒ Boolean

Returns true if offline synching is enabled.

Examples:

status = Spotify::OfflineSyncStatus.new
Spotify.offline_sync_get_status(session, status)
p status.to_h # => { queued_tracks: 0, queued_bytes: 0, … }

Parameters:

Returns:

  • (Boolean) —

    true if offline synching is enabled



286
 
# File 'lib/spotify/api/session.rb', line 286

attach_function :offline_sync_get_status, [ Session, OfflineSyncStatus.by_ref ], :bool

#offline_time_left(session) ⇒ Integer

Returns remaining time (in seconds) until offline key store expires and user is required to relogin.

Parameters:

Returns:

  • (Integer) —

    remaining time (in seconds) until offline key store expires and user is required to relogin



291
 
# File 'lib/spotify/api/session.rb', line 291

attach_function :offline_time_left, [ Session ], :int

#offline_tracks_to_sync(session) ⇒ Integer

Returns total number of tracks left to sync before all offline content has downloaded.

Parameters:

Returns:

  • (Integer) —

    total number of tracks left to sync before all offline content has downloaded



270
 
# File 'lib/spotify/api/session.rb', line 270

attach_function :offline_tracks_to_sync, [ Session ], :int

#playlist_add_callbacks(playlist, playlist_callbacks, userdata) ⇒ Symbol

Note:

it is very important that the callbacks are not garbage collected before they are called!

Attach callbacks to the playlist, used for getting change notifications.

Examples:

callbacks = Spotify::PlaylistCallbacks.new({
  tracks_added: proc do |playlist, tracks_pointer, count, position|
    puts "#{count} tracks added at #{position}."
  end,
  playlist_renamed: proc { |playlist| puts "Playlist renamed!" },
})
Spotify.playlist_add_callbacks(playlist, callbacks, nil) # => ok

Parameters:

Returns:

  • (Symbol) —

    error code



27
 
# File 'lib/spotify/api/playlist.rb', line 27

attach_function :playlist_add_callbacks, [ Playlist, PlaylistCallbacks.by_ref, :userdata ], APIError

#playlist_add_tracks(playlist, tracks, offset, session) ⇒ Symbol

Note:

if the playlist is not loaded, the function always return an error.

Add tracks to the playlist.

Examples:

single track

Spotify.playlist_add_tracks(playlist, track, offset, session) # => :ok

array of tracks

Spotify.playlist_add_tracks(playlist, tracks, offset, session) # => :ok

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



202
203
204
205
206
207
208
209
 
# File 'lib/spotify/api/playlist.rb', line 202

attach_function :playlist_add_tracks, [ Playlist, :array, :int, :int, Session ], APIError do |playlist, tracks, offset, session|
  tracks = Array(tracks)

  with_buffer(Spotify::Track, size: tracks.length) do |tracks_buffer|
    tracks_buffer.write_array_of_pointer(tracks)
    sp_playlist_add_tracks(playlist, tracks_buffer, tracks.length, offset, session)
  end
end

#playlist_create(session, link) ⇒ Playlist?

Instantiate a Playlist from a Link.

Parameters:

Returns:

  • (Playlist, nil) —

    playlist, or nil if link was not a valid playlist link



313
 
# File 'lib/spotify/api/playlist.rb', line 313

attach_function :playlist_create, [ Session, Link ], Playlist

#playlist_get_description(playlist) ⇒ String?

Note:

if the playlist is not loaded, the function always return nil.

Returns playlist description, if available.

Parameters:

Returns:

  • (String, nil) —

    playlist description, if available

See Also:



157
 
# File 'lib/spotify/api/playlist.rb', line 157

attach_function :playlist_get_description, [ Playlist ], UTF8String

#playlist_get_image(playlist) ⇒ String?

Note:

if the playlist is not loaded, the function always return nil.

Retrieve playlist image ID as a string.

Examples:

Spotify.playlist_get_image(playlist) # =>

Parameters:

Returns:

  • (String, nil) —

    image ID for playlist image, or nil if no image available.

See Also:



170
171
172
173
174
175
176
 
# File 'lib/spotify/api/playlist.rb', line 170

attach_function :playlist_get_image, [ Playlist, :buffer_out ], :bool do |playlist|
  with_buffer(Spotify::ImageID) do |image_id_buffer|
    if sp_playlist_get_image(playlist, image_id_buffer)
      ImageID.from_native(image_id_buffer, nil)
    end
  end
end

#playlist_get_offline_download_completed(session, playlist) ⇒ Integer

Note:

if the playlist is not loaded, the function always return 0.

Note:

if the playlist is not marked for offline download, the function always return 0.

Returns percentage of playlist downloaded, 0..100.

Parameters:

Returns:

  • (Integer) —

    percentage of playlist downloaded, 0..100



330
 
# File 'lib/spotify/api/playlist.rb', line 330

attach_function :playlist_get_offline_download_completed, [ Session, Playlist ], :int

#playlist_get_offline_status(session, playlist) ⇒ Symbol

Note:

if the playlist is not loaded, the function always return :no.

Returns playlist offline status, one of :no, :yes, :downloading, or :waiting.

Parameters:

Returns:

  • (Symbol) —

    playlist offline status, one of :no, :yes, :downloading, or :waiting

See Also:



322
 
# File 'lib/spotify/api/playlist.rb', line 322

attach_function :playlist_get_offline_status, [ Session, Playlist ], :playlist_offline_status

#playlist_has_pending_changes(playlist) ⇒ Boolean

Note:

if the playlist is not loaded, the function always return true.

Returns true if the playlist has local changes that have not yet been acknowledged by Spotify backend.

Parameters:

Returns:

  • (Boolean) —

    true if the playlist has local changes that have not yet been acknowledged by Spotify backend

See Also:



183
 
# File 'lib/spotify/api/playlist.rb', line 183

attach_function :playlist_has_pending_changes, [ Playlist ], :bool

#playlist_is_collaborative(playlist) ⇒ Boolean

Note:

if #playlist_set_collaborative was used, the final value will not be visible until after libspotify has negotiated with Spotify backend.

Note:

if playlist is not loaded, the function always return false.

Returns true if the playlist is collaborative, i.e. editable by others.

Parameters:

Returns:

  • (Boolean) —

    true if the playlist is collaborative, i.e. editable by others.

See Also:



128
 
# File 'lib/spotify/api/playlist.rb', line 128

attach_function :playlist_is_collaborative, [ Playlist ], :bool

#playlist_is_in_ram(session, playlist) ⇒ Boolean

Returns true if playlist is loaded in memory, as opposed to only stored on disk.

Parameters:

Returns:

  • (Boolean) —

    true if playlist is loaded in memory, as opposed to only stored on disk.

See Also:



295
 
# File 'lib/spotify/api/playlist.rb', line 295

attach_function :playlist_is_in_ram, [ Session, Playlist ], :bool

#playlist_is_loaded(playlist) ⇒ Boolean

Returns true if playlist is loaded.

Parameters:

Returns:

  • (Boolean) —

    true if playlist is loaded



8
 
# File 'lib/spotify/api/playlist.rb', line 8

attach_function :playlist_is_loaded, [ Playlist ], :bool

#playlist_name(playlist) ⇒ String

Note:

if playlist is not loaded, the function always return an empty string.

Returns name of the playlist.

Parameters:

Returns:

  • (String) —

    name of the playlist

See Also:



103
 
# File 'lib/spotify/api/playlist.rb', line 103

attach_function :playlist_name, [ Playlist ], UTF8String

#playlist_num_subscribers(playlist) ⇒ Integer

Note:

if the playlist is not loaded, the function always return 0.

Note:

if #playlist_update_subscribers have not been called, the function always return 0.

Returns number of playlist subscribers.

Parameters:

Returns:

  • (Integer) —

    number of playlist subscribers

See Also:



264
 
# File 'lib/spotify/api/playlist.rb', line 264

attach_function :playlist_num_subscribers, [ Playlist ], :uint

#playlist_num_tracks(playlist) ⇒ Integer

Note:

if playlist is not loaded, the function always return 0.

Returns number of tracks in the playlist.

Parameters:

Returns:

  • (Integer) —

    number of tracks in the playlist

See Also:



44
 
# File 'lib/spotify/api/playlist.rb', line 44

attach_function :playlist_num_tracks, [ Playlist ], :int

#playlist_owner(playlist) ⇒ User

Returns owner of the playlist.

Parameters:

Returns:

  • (User) —

    owner of the playlist



118
 
# File 'lib/spotify/api/playlist.rb', line 118

attach_function :playlist_owner, [ Playlist ], User

#playlist_remove_callbacks(playlist, playlist_callbacks, userdata) ⇒ Symbol

Remove playlist callbacks previously added with #playlist_add_callbacks.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



37
 
# File 'lib/spotify/api/playlist.rb', line 37

attach_function :playlist_remove_callbacks, [ Playlist, PlaylistCallbacks.by_ref, :userdata ], APIError

#playlist_remove_tracks(playlist, indices) ⇒ Symbol

Note:

if the playlist is not loaded, the function always return an error.

Note:

any index in indices_pointer must exist at most once, i.e. [0,1,2] is valid, [0,0,1] is not.

Remove tracks from the playlist at the given indices.

Examples:

single index

Spotify.playlist_remove_tracks(playlist, 3) # => :ok

array of indices

Spotify.playlist_remove_tracks(playlist, [1, 3]) # => :ok

Parameters:

  • playlist (Playlist)
  • indices_pointer (Array<Integer>, Integer) —

    pointer to array of track indices

Returns:

  • (Symbol) —

    error code

See Also:



226
227
228
229
230
231
232
233
 
# File 'lib/spotify/api/playlist.rb', line 226

attach_function :playlist_remove_tracks, [ Playlist, :array, :int ], APIError do |playlist, indices|
  indices = Array(indices)

  with_buffer(:int, size: indices.length) do |indices_buffer|
    indices_buffer.write_array_of_int(indices)
    sp_playlist_remove_tracks(playlist, indices_buffer, indices.length)
  end
end

#playlist_rename(playlist, new_name) ⇒ Symbol

Note:

if playlist is not loaded, the function always return :permission_denied.

Rename the playlist.

Parameters:

  • playlist (Playlist)
  • new_name (String) —

    new name of the playlist

Returns:

  • (Symbol) —

    error code

See Also:



113
 
# File 'lib/spotify/api/playlist.rb', line 113

attach_function :playlist_rename, [ Playlist, UTF8String ], APIError

#playlist_reorder_tracks(playlist, indices, index) ⇒ Symbol

Note:

if the playlist is not loaded, the function always return an error.

Note:

any index in indices_pointer must exist at most once, i.e. [0,1,2] is valid, [0,0,1] is not.

Move tracks at the given indices to position index and forward.

Examples:

Spotify.playlist_reorder_tracks(playlist, [1, 7], 0) # => :ok

Parameters:

  • playlist (Playlist)
  • indices_pointer (Array<Integer>) —

    pointer to array of track indices

  • index (Integer) —

    starting position of tracks to be placed at, number between 0..#playlist_num_tracks

Returns:

  • (Symbol) —

    error code

See Also:



248
249
250
251
252
253
254
255
 
# File 'lib/spotify/api/playlist.rb', line 248

attach_function :playlist_reorder_tracks, [ Playlist, :array, :int, :int ], APIError do |playlist, indices, index|
  indices = Array(indices)

  with_buffer(:int, size: indices.length) do |indices_buffer|
    indices_buffer.write_array_of_int(indices)
    sp_playlist_reorder_tracks(playlist, indices_buffer, indices.length, index)
  end
end

#playlist_set_autolink_tracks(playlist, autolink) ⇒ Symbol

Note:

the function always return :ok.

Set autolinking state for a playlist.

If a playlist is set to autolink, unplayable tracks will be made playable by linking them to an equivalent playable track when possible.

Parameters:

  • playlist (Playlist)
  • autolink (Boolean)

Returns:

  • (Symbol) —

    error code



150
 
# File 'lib/spotify/api/playlist.rb', line 150

attach_function :playlist_set_autolink_tracks, [ Playlist, :bool ], APIError

#playlist_set_collaborative(playlist, collaborative) ⇒ Symbol

Note:

the function always return :ok.

Set collaborative status on a playlist.

Parameters:

  • playlist (Playlist)
  • collaborative (Boolean)

Returns:

  • (Symbol) —

    error code

See Also:



138
 
# File 'lib/spotify/api/playlist.rb', line 138

attach_function :playlist_set_collaborative, [ Playlist, :bool ], APIError

#playlist_set_in_ram(session, playlist, in_ram) ⇒ Symbol

Set if playlist should be loaded into memory, as opposed to only read from on disk.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



305
 
# File 'lib/spotify/api/playlist.rb', line 305

attach_function :playlist_set_in_ram, [ Session, Playlist, :bool ], APIError

#playlist_set_offline_mode(session, playlist, offline) ⇒ Symbol

Set if playlist should be marked for offline playback.

Parameters:

  • session (Session)
  • playlist (Playlist)
  • offline (Boolean) —

    true if playlist should be downloaded for offline usage

Returns:

  • (Symbol) —

    error code



339
 
# File 'lib/spotify/api/playlist.rb', line 339

attach_function :playlist_set_offline_mode, [ Session, Playlist, :bool ], APIError

#playlist_subscribers(playlist) ⇒ Subscribers

Note:

if the playlist is not loaded, the function always return an empty structure.

Note:

if #playlist_update_subscribers have not been called, the function always return an empty structure.

Examples:

subscribers = Spotify.playlist_subscribers(playlist).to_a
puts "Subscribers: ", subscribers.join(", ")

Parameters:

Returns:

See Also:



278
 
# File 'lib/spotify/api/playlist.rb', line 278

attach_function :playlist_subscribers, [ Playlist ], Subscribers.auto_ptr

#playlist_track(playlist, index) ⇒ Track?

Note:

if index is out of range, the function always return nil.

Returns track at index.

Parameters:

Returns:

  • (Track, nil) —

    track at index

See Also:



52
 
# File 'lib/spotify/api/playlist.rb', line 52

attach_function :playlist_track, [ Playlist, :int ], Track

#playlist_track_create_time(playlist, index) ⇒ Integer

Note:

if index is out of range, the function always return -1.

Returns time in seconds since unix epoch that track was added at index in the playlist.

Parameters:

Returns:

  • (Integer) —

    time in seconds since unix epoch that track was added at index in the playlist

See Also:



60
 
# File 'lib/spotify/api/playlist.rb', line 60

attach_function :playlist_track_create_time, [ Playlist, :int ], :int

#playlist_track_creator(playlist, index) ⇒ User?

Note:

if index is out of range, the function always return nil.

Returns user that added the track at index in the playlist.

Parameters:

Returns:

  • (User, nil) —

    user that added the track at index in the playlist

See Also:



68
 
# File 'lib/spotify/api/playlist.rb', line 68

attach_function :playlist_track_creator, [ Playlist, :int ], User

#playlist_track_message(playlist, index) ⇒ String

Note:

if index is out of range, the function always return nil.

Returns message attached to a playlist item.

Parameters:

Returns:

  • (String) —

    message attached to a playlist item

See Also:



96
 
# File 'lib/spotify/api/playlist.rb', line 96

attach_function :playlist_track_message, [ Playlist, :int ], UTF8String

#playlist_track_seen(playlist, index) ⇒ Boolean

Note:

if index is out of range, the function always return false.

Returns true if playlist has been marked as seen with #playlist_track_set_seen.

Parameters:

Returns:

See Also:



77
 
# File 'lib/spotify/api/playlist.rb', line 77

attach_function :playlist_track_seen, [ Playlist, :int ], :bool

#playlist_track_set_seen(playlist, index, seen) ⇒ Symbol

Set seen flag on track. The flag can be retrieved by #playlist_track_seen.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



88
 
# File 'lib/spotify/api/playlist.rb', line 88

attach_function :playlist_track_set_seen, [ Playlist, :int, :bool ], APIError

#playlist_update_subscribers(session, playlist) ⇒ Symbol

Note:

the function updates subscribers asynchronously, see PlaylistCallbacks#subscribers_changed for callback.

Request download of the subscribers list.

Parameters:

Returns:

  • (Symbol) —

    error code



288
 
# File 'lib/spotify/api/playlist.rb', line 288

attach_function :playlist_update_subscribers, [ Session, Playlist ], APIError

#playlistcontainer_add_callbacks(container, container_callbacks, userdata) ⇒ Symbol

Note:

it is very important that the callbacks are not garbage collected before they are called!

Attach callbacks to the container, used for getting change notifications.

Examples:

callbacks = Spotify::PlaylistContainerCallbacks.new({
  container_loaded: proc { |playlist| puts "Container loaded!" },
})
Spotify.playlistcontainer_add_callbacks(container, callbacks, nil) # => :ok

Parameters:

Returns:

  • (Symbol) —

    error code



19
 
# File 'lib/spotify/api/playlist_container.rb', line 19

attach_function :playlistcontainer_add_callbacks, [ PlaylistContainer, PlaylistContainerCallbacks.by_ref, :userdata ], APIError

#playlistcontainer_add_folder(container, index, folder_name) ⇒ Object

Note:

you cannot rename folders, if you want to do so you have to destroy the folder and recreate it

Create a new folder in the container.

This creates a start_folder marker, and an end_folder marker right after it, at specified index.

Parameters:



134
 
# File 'lib/spotify/api/playlist_container.rb', line 134

attach_function :playlistcontainer_add_folder, [ PlaylistContainer, :int, UTF8String ], APIError

#playlistcontainer_add_new_playlist(container, playlist_name) ⇒ Playlist?

Note:

the name must not constist of only spaces, and it must be shorter than 256 bytes.

Add a new playlist to the end of the container.

Parameters:

Returns:

  • (Playlist, nil) —

    the new playlist, or nil if creation failed



91
 
# File 'lib/spotify/api/playlist_container.rb', line 91

attach_function :playlistcontainer_add_new_playlist, [ PlaylistContainer, UTF8String ], Playlist

#playlistcontainer_add_playlist(container, link) ⇒ Playlist?

Add an existing playlist to the end of the container.

Parameters:

Returns:

  • (Playlist, nil) —

    the playlist, or nil if the playlist already exists, or if the link was not a valid playlist link



99
 
# File 'lib/spotify/api/playlist_container.rb', line 99

attach_function :playlistcontainer_add_playlist, [ PlaylistContainer, Link ], Playlist

#playlistcontainer_clear_unseen_tracks(container, playlist) ⇒ Integer

Clear unseen tracks for a playlist on a container

This will cause the next#playlistcontainer_get_unseen_tracks call to return 0.

Parameters:

Returns:

  • (Integer) —

    0 on success, and -1 on failure



177
 
# File 'lib/spotify/api/playlist_container.rb', line 177

attach_function :playlistcontainer_clear_unseen_tracks, [ PlaylistContainer, Playlist ], :int

#playlistcontainer_get_unseen_tracks(container, playlist) ⇒ Array<Track>

Note:

if the playlist is not in the container, this function always return an empty array.

Number of new tracks in playlist since #playlistcontainer_clear_unseen_tracks was called.

Examples:

number of unseen tracks in playlist

Spotify.playlistcontainer_get_unseen_tracks(container, playlist) # => [#<Spotify::Track::Retaining address=0x103a36c10>…

Parameters:

Returns:

  • (Array<Track>) —

    an array of unseen tracks



157
158
159
160
161
162
163
164
165
166
167
 
# File 'lib/spotify/api/playlist_container.rb', line 157

attach_function :playlistcontainer_get_unseen_tracks, [ PlaylistContainer, Playlist, :array, :int ], :int do |container, playlist|
  count = sp_playlistcontainer_get_unseen_tracks(container, playlist, nil, 0)
  tracks = with_buffer(Spotify::Track, size: count) do |tracks_buffer|
    sp_playlistcontainer_get_unseen_tracks(container, playlist, tracks_buffer, count)
    tracks_buffer.read_array_of_pointer(count).map do |pointer|
      Spotify::Track.retaining_class.from_native(pointer, nil)
    end
  end

  tracks || []
end

#playlistcontainer_is_loaded(container) ⇒ Boolean

Returns true if the container is loaded.

Parameters:

Returns:

  • (Boolean) —

    true if the container is loaded



144
 
# File 'lib/spotify/api/playlist_container.rb', line 144

attach_function :playlistcontainer_is_loaded, [ PlaylistContainer ], :bool

#playlistcontainer_move_playlist(container, index, new_position, dry_run) ⇒ Symbol

Note:

if the index is out of range, the function always return an error.

Move a playlist to another position in the container.

Parameters:

Returns:

  • (Symbol) —

    error code



122
 
# File 'lib/spotify/api/playlist_container.rb', line 122

attach_function :playlistcontainer_move_playlist, [ PlaylistContainer, :int, :int, :bool ], APIError

#playlistcontainer_num_playlists(container) ⇒ Integer

Note:

if the container is not loaded, the function will always return 0.

Returns number of playlists in container.

Parameters:

Returns:

  • (Integer) —

    number of playlists in container

See Also:



37
 
# File 'lib/spotify/api/playlist_container.rb', line 37

attach_function :playlistcontainer_num_playlists, [ PlaylistContainer ], :int

#playlistcontainer_owner(container) ⇒ User

Returns owner of the container.

Parameters:

Returns:

  • (User) —

    owner of the container



139
 
# File 'lib/spotify/api/playlist_container.rb', line 139

attach_function :playlistcontainer_owner, [ PlaylistContainer ], User

#playlistcontainer_playlist(container) ⇒ Playlist?

Note:

if index is out of range, the function always return nil.

Returns playlist at index.

Parameters:

Returns:

See Also:



45
 
# File 'lib/spotify/api/playlist_container.rb', line 45

attach_function :playlistcontainer_playlist, [ PlaylistContainer, :int ], Playlist

#playlistcontainer_playlist_folder_id(container, index) ⇒ Integer

Note:

if the index is out of range, the function always return 0.

Returns folder id at index.

Parameters:

Returns:

  • (Integer) —

    folder id at index



82
 
# File 'lib/spotify/api/playlist_container.rb', line 82

attach_function :playlistcontainer_playlist_folder_id, [ PlaylistContainer, :int ], :uint64

#playlistcontainer_playlist_folder_name(container, index) ⇒ String?

Note:

the spotify client appear to constrain the name to 255 chars, so this function does too.

Note:

if index is out of range, the function always return nil.

Retrieve folder name of a folder in a container.

Examples:

Spotify.playlistcontainer_playlist_folder_name(container, index = 0) # => "Summer Playlists"

Parameters:

Returns:

  • (String, nil) —

    name of the folder as a string, or nil if not a folder, or out of range

See Also:



69
70
71
72
73
74
75
 
# File 'lib/spotify/api/playlist_container.rb', line 69

attach_function :playlistcontainer_playlist_folder_name, [ PlaylistContainer, :int, :buffer_out, :int ], APIError do |container, index|
  folder_name = with_string_buffer(255) do |folder_name_buffer, size|
    sp_playlistcontainer_playlist_folder_name(container, index, folder_name_buffer, size)
  end

  folder_name unless folder_name.empty?
end

#playlistcontainer_playlist_type(container, index) ⇒ Symbol

Note:

if index is out of range, the function always return :playlist.

Returns playlist type of playlist at index, one of :playlist, :start_folder, :end_folder, :placeholder.

Parameters:

Returns:

  • (Symbol) —

    playlist type of playlist at index, one of :playlist, :start_folder, :end_folder, :placeholder

See Also:



53
 
# File 'lib/spotify/api/playlist_container.rb', line 53

attach_function :playlistcontainer_playlist_type, [ PlaylistContainer, :int ], :playlist_type

#playlistcontainer_remove_callbacks(container, container_callbacks, userdata) ⇒ Symbol

Remove container callbacks previously added with #playlistcontainer_add_callbacks.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



29
 
# File 'lib/spotify/api/playlist_container.rb', line 29

attach_function :playlistcontainer_remove_callbacks, [ PlaylistContainer, PlaylistContainerCallbacks.by_ref, :userdata ], APIError

#playlistcontainer_remove_playlist(container, index) ⇒ Symbol

Note:

if you remove a folder marker, remove the other corresponding (start or stop) marker as well, or the playlist will be left in an inconsistent state.

Note:

if the index is out of range, the function always return an error.

Remove a playlist from a container.

Parameters:

Returns:

  • (Symbol) —

    error code



111
 
# File 'lib/spotify/api/playlist_container.rb', line 111

attach_function :playlistcontainer_remove_playlist, [ PlaylistContainer, :int ], APIError

#search_album(search, index) ⇒ Album?

Note:

if index is out of range, the function always return nil.

Returns album at index.

Parameters:

Returns:

  • (Album, nil) —

    album at index

See Also:



85
 
# File 'lib/spotify/api/search.rb', line 85

attach_function :search_album, [ Search, :int ], Album

#search_artist(search, index) ⇒ Artist?

Note:

if index is out of range, the function always return nil.

Returns artist at index.

Parameters:

Returns:

  • (Artist, nil) —

    artist at index

See Also:



103
 
# File 'lib/spotify/api/search.rb', line 103

attach_function :search_artist, [ Search, :int ], Artist

#search_create(session, query, track_offset, track_count, album_offset, album_count, artist_offset, artist_count, playlist_offset, playlist_count, search_type, callback, userdata) ⇒ Search

Note:

it is very important that the callback is not garbage collected before it is called!

Fire off a search query for tracks, albums, artists, and playlists.

Examples:

callback = proc { |search| puts "Search results are available!" }
search = Spotify.search_create(session, "Zanarkand", 0, 10, 0, 10, 0, 10, 0, 10, :standard, callback, nil)

Parameters:

  • session (Session)
  • query (String)
  • track_offset (Integer)
  • track_count (Integer)
  • album_offset (Integer)
  • album_count (Integer)
  • artist_offset (Integer)
  • artist_count (Integer)
  • playlist_offset (Integer)
  • playlist_count (Integer)
  • search_type (Integer) —

    one of :standard, or :suggest

  • callback (Proc<Search, FFI::Pointer>)
  • userdata (FFI::Pointer)

Returns:



27
 
# File 'lib/spotify/api/search.rb', line 27

attach_function :search_create, [ Session, UTF8String, :int, :int, :int, :int, :int, :int, :int, :int, :search_type, :search_complete_cb, :userdata ], Search

#search_did_you_mean(search) ⇒ String

Note:

if the search is not loaded, the function always return an empty string.

Returns spotify’s guess at what the query might have meant instead.

Parameters:

Returns:

  • (String) —

    spotify’s guess at what the query might have meant instead

See Also:



49
 
# File 'lib/spotify/api/search.rb', line 49

attach_function :search_did_you_mean, [ Search ], UTF8String

#search_error(search) ⇒ Symbol

Returns error code.

Parameters:

Returns:

  • (Symbol) —

    error code



37
 
# File 'lib/spotify/api/search.rb', line 37

attach_function :search_error, [ Search ], APIError

#search_is_loaded(search) ⇒ Boolean

Returns true if the search has completed.

Parameters:

Returns:

  • (Boolean) —

    true if the search has completed



32
 
# File 'lib/spotify/api/search.rb', line 32

attach_function :search_is_loaded, [ Search ], :bool

#search_num_albums(search) ⇒ Integer

Note:

if #search_total_albums is larger than this number, you may retrieve additional results if you make the same search query again, but with a higher album_offset

Note:

if the search is not loaded, the function always return 0.

Returns number of albums in the search result.

Parameters:

Returns:

  • (Integer) —

    number of albums in the search result

See Also:



77
 
# File 'lib/spotify/api/search.rb', line 77

attach_function :search_num_albums, [ Search ], :int

#search_num_artists(search) ⇒ Integer

Note:

if #search_total_artists is larger than this number, you may retrieve additional results if you make the same search query again, but with a higher artist_offset

Note:

if the search is not loaded, the function always return 0.

Returns number of artists in the search result.

Parameters:

Returns:

  • (Integer) —

    number of artists in the search result

See Also:



95
 
# File 'lib/spotify/api/search.rb', line 95

attach_function :search_num_artists, [ Search ], :int

#search_num_playlists(search) ⇒ Integer

Note:

if #search_total_playlists is larger than this number, you may retrieve additional results if you make the same search query again, but with a higher playlist_offset

Note:

if the search is not loaded, the function always return 0.

Returns number of playlists in the search result.

Parameters:

Returns:

  • (Integer) —

    number of playlists in the search result

See Also:



113
 
# File 'lib/spotify/api/search.rb', line 113

attach_function :search_num_playlists, [ Search ], :int

#search_num_tracks(search) ⇒ Integer

Note:

if #search_total_tracks is larger than this number, you may retrieve additional results if you make the same search query again, but with a higher track_offset

Note:

if the search is not loaded, the function always return 0.

Returns number of tracks in the search result.

Parameters:

Returns:

  • (Integer) —

    number of tracks in the search result

See Also:



59
 
# File 'lib/spotify/api/search.rb', line 59

attach_function :search_num_tracks, [ Search ], :int

#search_playlist(search, index) ⇒ Playlist?

Note:

if index is out of range, the function always return nil.

Returns playlist at index.

Parameters:

Returns:

See Also:



121
 
# File 'lib/spotify/api/search.rb', line 121

attach_function :search_playlist, [ Search, :int ], Playlist

#search_playlist_image_uri(search, index) ⇒ String?

Note:

if index is out of range, the function always return nil.

Returns image uri for playlist at index.

Parameters:

Returns:

  • (String, nil) —

    image uri for playlist at index

See Also:



147
 
# File 'lib/spotify/api/search.rb', line 147

attach_function :search_playlist_image_uri, [ Search, :int ], UTF8String

#search_playlist_name(search, index) ⇒ String?

Note:

if index is out of range, the function always return nil.

Returns name for playlist at index.

Parameters:

Returns:

  • (String, nil) —

    name for playlist at index

See Also:



129
 
# File 'lib/spotify/api/search.rb', line 129

attach_function :search_playlist_name, [ Search, :int ], UTF8String

#search_playlist_uri(search, index) ⇒ String?

Note:

if index is out of range, the function always return nil.

Returns spotify uri for playlist at index.

Parameters:

Returns:

  • (String, nil) —

    spotify uri for playlist at index

See Also:



138
 
# File 'lib/spotify/api/search.rb', line 138

attach_function :search_playlist_uri, [ Search, :int ], UTF8String

#search_query(search) ⇒ String

Returns search query.

Parameters:

Returns:

  • (String) —

    search query



42
 
# File 'lib/spotify/api/search.rb', line 42

attach_function :search_query, [ Search ], UTF8String

#search_total_albums(search) ⇒ Integer

Note:

if the search is not loaded, the function always return 0.

Returns number of total albums in the search result.

Parameters:

Returns:

  • (Integer) —

    number of total albums in the search result

See Also:



161
 
# File 'lib/spotify/api/search.rb', line 161

attach_function :search_total_albums, [ Search ], :int

#search_total_artists(search) ⇒ Integer

Note:

if the search is not loaded, the function always return 0.

Returns number of total artists in the search result.

Parameters:

Returns:

  • (Integer) —

    number of total artists in the search result

See Also:



168
 
# File 'lib/spotify/api/search.rb', line 168

attach_function :search_total_artists, [ Search ], :int

#search_total_playlists(search) ⇒ Integer

Note:

if the search is not loaded, the function always return 0.

Returns number of total playlists in the search result.

Parameters:

Returns:

  • (Integer) —

    number of total playlists in the search result

See Also:



175
 
# File 'lib/spotify/api/search.rb', line 175

attach_function :search_total_playlists, [ Search ], :int

#search_total_tracks(search) ⇒ Integer

Note:

if the search is not loaded, the function always return 0.

Returns number of total tracks in the search result.

Parameters:

Returns:

  • (Integer) —

    number of total tracks in the search result

See Also:



154
 
# File 'lib/spotify/api/search.rb', line 154

attach_function :search_total_tracks, [ Search ], :int

#search_track(search, index) ⇒ Track?

Note:

if index is out of range, the function always return nil.

Returns track at index.

Parameters:

Returns:

  • (Track, nil) —

    track at index

See Also:



67
 
# File 'lib/spotify/api/search.rb', line 67

attach_function :search_track, [ Search, :int ], Track

#session_connectionstate(session) ⇒ Symbol

Returns current session connection state, one of :logged_out, :logged_in, :disconnected, :undefined, :offline.

Parameters:

Returns:

  • (Symbol) —

    current session connection state, one of :logged_out, :logged_in, :disconnected, :undefined, :offline



139
 
# File 'lib/spotify/api/session.rb', line 139

attach_function :session_connectionstate, [ Session ], :connectionstate

#session_create(config) ⇒ Array<Symbol, Session>

Note:

it is very important that the callbacks are not garbage collected while they may be called!

Returns a tuple of error code, and session.

Examples:

$callbacks = Spotify::SessionCallbacks.new({
  connectionstate_updated: proc do |session|
    puts "New connection state: #{Spotify.session_connectionstate(session)}."
  end,
  music_delivery: proc do |session, format, frames, num_frames|
    puts "More audio coming through!"
  end,
})

config = {
  api_version: Spotify::API_VERSION.to_i,
  application_key: File.binread("./spotify_appkey.key"),
  cache_location: "",
  user_agent: "spotify for ruby",
  callbacks: $callbacks,
}

error, session = Spotify.session_create(config)
raise Spotify::APIError.new(error) if error

Parameters:

Returns:

  • (Array<Symbol, Session>) —

    a tuple of error code, and session



30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/spotify/api/session.rb', line 30

attach_function :session_create, [ SessionConfig.by_ref, :buffer_out ], APIError do |config|
  config = Spotify::SessionConfig.new(config.to_h)

  with_buffer(Spotify::Session) do |session_buffer|
    error = sp_session_create(config, session_buffer)
    error = nil if error == :ok

    session = if error.nil?
      Spotify::Session.from_native(session_buffer.read_pointer, nil)
    end

    [error, session]
  end
end

#session_flush_caches(session) ⇒ Symbol

Note:

libspotify does this periodically by itself, and on logout, so usually this is not needed.

Force libspotify to write all disk-stored data to disk immediately.

Parameters:

Returns:

  • (Symbol) —

    error code



328
 
# File 'lib/spotify/api/session.rb', line 328

attach_function :session_flush_caches, [ Session ], APIError

#session_forget_me(session) ⇒ Symbol

Forget a previously remembered user.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



102
 
# File 'lib/spotify/api/session.rb', line 102

attach_function :session_forget_me, [ Session ], APIError

#session_get_volume_normalization(session) ⇒ Boolean

Returns current volume normalization setting.

Parameters:

Returns:

  • (Boolean) —

    current volume normalization setting

See Also:



320
 
# File 'lib/spotify/api/session.rb', line 320

attach_function :session_get_volume_normalization, [ Session ], :bool

#session_inbox_create(session) ⇒ Playlist

Note:

if not logged in, the function always return nil.

Returns inbox playlist for currently logged in user (playlist where items sent by other users are posted to).

Parameters:

Returns:

  • (Playlist) —

    inbox playlist for currently logged in user (playlist where items sent by other users are posted to)



214
 
# File 'lib/spotify/api/session.rb', line 214

attach_function :session_inbox_create, [ Session ], Playlist

#session_is_private_session(session) ⇒ Boolean

Returns true if private session is enabled.

Parameters:

Returns:

  • (Boolean) —

    true if private session is enabled

See Also:



351
 
# File 'lib/spotify/api/session.rb', line 351

attach_function :session_is_private_session, [ Session ], :bool

#session_is_scrobbling(session, social_provider) ⇒ Symbol

Retrieve the scrobbling state.

This makes it possible to find out if scrobbling is locally overrided or if global setting is used.

Examples:

Spotify.session_is_scrobbling(session, :spotify) # => :global_enabled

Parameters:

  • session (Session)
  • social_provider (Symbol)

Returns:

  • (Symbol) —

    current scrobbling state for the social provider



374
375
376
377
378
379
 
# File 'lib/spotify/api/session.rb', line 374

attach_function :session_is_scrobbling, [ Session, :social_provider, :buffer_out ], APIError do |session, social_provider|
  with_buffer(:int) do |state_buffer|
    error = sp_session_is_scrobbling(session, social_provider, state_buffer)
    enum_type(:scrobbling_state)[state_buffer.read_int] if error == :ok
  end
end

#session_is_scrobbling_possible(session, social_provider) ⇒ Boolean

Note:

currently this setting is only relevant to the facebook provider

Retrieve if it is possible to scrobble to the social provider.

Parameters:

  • session (Session)
  • social_provider (Symbol)

Returns:

  • (Boolean) —

    true if scrobbling is possible



390
391
392
393
394
395
 
# File 'lib/spotify/api/session.rb', line 390

attach_function :session_is_scrobbling_possible, [ Session, :social_provider, :buffer_out ], APIError do |session, social_provider|
  with_buffer(:char) do |possible_buffer|
    error = sp_session_is_scrobbling_possible(session, social_provider, possible_buffer)
    possible_buffer.read_char != 0 if error == :ok
  end
end

#session_login(session, username, password, remember_me, password_blob) ⇒ Symbol

Note:

Login happens in the background. You have to process events a few times before you are logged in.

Schedule a login.

Parameters:

  • session (Session)
  • username (String) —

    spotify username, or facebook e-mail

  • password (String) —

    spotify password, or facebook password, or nil

  • remember_me (Boolean) —

    true if #session_relogin should be possible

  • password_blob (String) —

    an alternative to password, stored from credentials_blob_updated session callback

Returns:

  • (Symbol) —

    error code

See Also:



80
 
# File 'lib/spotify/api/session.rb', line 80

attach_function :session_login, [ Session, UTF8String, UTF8String, :bool, UTF8String ], APIError

#session_logout(session) ⇒ Symbol

Note:

This updates credentials in remember_me from #session_login and #session_forget_me.

Note:

Logout happen asynchronously. You need to call #session_process_events a little while.

Schedule a logout.

Parameters:

Returns:

  • (Symbol) —

    error code



134
 
# File 'lib/spotify/api/session.rb', line 134

attach_function :session_logout, [ Session ], APIError

#session_player_load(session, track) ⇒ Symbol

Load the specified track for playback.

When the the function returns, the track will have been loaded assuming there as no error.

Parameters:

Returns:

  • (Symbol) —

    error code



162
 
# File 'lib/spotify/api/session.rb', line 162

attach_function :session_player_load, [ Session, Track ], APIError

#session_player_play(session, play) ⇒ Symbol

Play or pause the currently loaded track.

This will start delivery of audio frames to the music_delivery callback in #session_create. However, playback should wait until SessionCallbacks#start_playback callback is called by libspotify.

Parameters:

  • session (Session)
  • play (Boolean) —

    if set to true, playback will be resumed, if set to false playback will be paused

Returns:

  • (Symbol) —

    error code

See Also:



183
 
# File 'lib/spotify/api/session.rb', line 183

attach_function :session_player_play, [ Session, :bool ], APIError

#session_player_prefetch(session, track) ⇒ Symbol

Note:

prefetching is only possible if using a cache from config in #session_create

Tell libspotify to start preloading a track so that #session_player_load has less work to do.

This could be done towards the end of a track in a queue, before starting playing the next.

Parameters:

Returns:

  • (Symbol) —

    error code



202
 
# File 'lib/spotify/api/session.rb', line 202

attach_function :session_player_prefetch, [ Session, Track ], APIError

#session_player_seek(session, position) ⇒ Symbol

Seek to position in the currently loaded track.

Parameters:

  • session (Session)
  • position (Integer) —

    in milliseconds

Returns:

  • (Symbol) —

    error code

See Also:



171
 
# File 'lib/spotify/api/session.rb', line 171

attach_function :session_player_seek, [ Session, :int ], APIError

#session_player_unload(session) ⇒ Symbol

Stop playback and clear the currently loaded track.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



191
 
# File 'lib/spotify/api/session.rb', line 191

attach_function :session_player_unload, [ Session ], APIError

#session_playlistcontainer(session) ⇒ PlaylistContainer?

Note:

if not logged in, the function always return nil.

Returns playlist container for currently logged in user.

Parameters:

Returns:



208
 
# File 'lib/spotify/api/session.rb', line 208

attach_function :session_playlistcontainer, [ Session ], PlaylistContainer

#session_preferred_bitrate(session, bitrate) ⇒ Symbol

Set preferred bitrate for music streaming.

Parameters:

  • session (Session)
  • bitrate (Symbol) —

    one of :160k, :320k, :96k

Returns:

  • (Symbol) —

    error code



242
 
# File 'lib/spotify/api/session.rb', line 242

attach_function :session_preferred_bitrate, [ Session, :bitrate ], APIError

#session_preferred_offline_bitrate(session, bitrate, resync) ⇒ Symbol

Set preferred bitrate for offline playback.

Parameters:

  • session (Session)
  • bitrate (Symbol) —

    one of :160k, :320k, :96k

  • resync (Boolean) —

    true if libspotify should redownload tracks with new bitrate

Returns:

  • (Symbol) —

    error code



306
 
# File 'lib/spotify/api/session.rb', line 306

attach_function :session_preferred_offline_bitrate, [ Session, :bitrate, :bool ], APIError

#session_process_events(session) ⇒ Integer

Tell libspotify to process pending events from the backend.

This will download changes and updates from Spotify, while simultaneously also uploading changes made locally, such as tracks added to playlists and more.

This method is the cornerstone of libspotify. It should be called frequently to synchronize data. This method is also responsible for calling most callbacks.

Examples:

Spotify.session_process_events(session) # => 1337

Parameters:

Returns:

  • (Integer) —

    time (in milliseconds) until you should call process_events again



61
62
63
64
65
66
 
# File 'lib/spotify/api/session.rb', line 61

attach_function :session_process_events, [ Session, :buffer_out ], APIError do |session|
  with_buffer(:int) do |timeout_buffer|
    sp_session_process_events(session, timeout_buffer)
    timeout_buffer.read_int
  end
end

#session_publishedcontainer_for_user_create(session, username) ⇒ PlaylistContainer?

Note:

if not logged in, the function always return nil.

Returns published playlists container for the specified user.

Parameters:

  • session (Session)
  • username (String) —

    canonical username of user

Returns:



234
 
# File 'lib/spotify/api/session.rb', line 234

attach_function :session_publishedcontainer_for_user_create, [ Session, UTF8String ], PlaylistContainer

#session_relogin(session) ⇒ Symbol

Note:

You must call #session_logout for remembered credentials to be stored.

Note:

Login happens in the background. You have to process events a few times before you are logged in.

Log in a previously remembered login from #session_login.

You would use this after terminating your application, and later starting it again, assuming #session_remembered_user contains a username that is remembered.

Parameters:

Returns:

  • (Symbol) —

    error code

See Also:



94
 
# File 'lib/spotify/api/session.rb', line 94

attach_function :session_relogin, [ Session ], APIError

#session_remembered_user(session) ⇒ String?

Retrieve the remembered user from #session_login.

This is the user that will be logged in if you use #session_relogin.

Examples:

Spotify.session_remembered_user(session) # => "Burgestrand"

Parameters:

Returns:

  • (String, nil) —

    username of the remembered user, or nil if there was none



114
115
116
117
118
119
120
 
# File 'lib/spotify/api/session.rb', line 114

attach_function :session_remembered_user, [ Session, :buffer_out, :size_t ], :int do |session|
  username_length = sp_session_remembered_user(session, nil, 0)
  username = with_string_buffer(username_length) do |username_buffer, size|
    sp_session_remembered_user(session, username_buffer, size)
  end
  username unless username.empty?
end

#session_set_cache_size(session, cache_size) ⇒ Symbol

Set the allowed disk cache size used by libspotify.

Parameters:

  • session (Session)
  • cache_size (Integer) —

    maximum cache size in megabytes, 0 means libspotify automatically resize cache as needed

Returns:

  • (Symbol) —

    error code



152
 
# File 'lib/spotify/api/session.rb', line 152

attach_function :session_set_cache_size, [ Session, :size_t ], APIError

#session_set_connection_rules(session, rules) ⇒ Symbol

Set rules for how libspotify connects to Spotify servers and synchronizes offline content.

Examples:

online_mode = Spotify::Util.enum_value!(:network, :connection_rules)
over_wifi = Spotify::Util.enum_value!(:allow_sync_over_wifi, :connection_rules)
Spotify.session_set_connection_rules($session, online_mode | over_wifi) # => :ok

Parameters:

  • session (Session)
  • rules (Symbol) —

    any of :network, :network_if_roaming, :allow_sync_over_mobile, :allow_sync_over_wifi

Returns:

  • (Symbol) —

    error code

See Also:



265
 
# File 'lib/spotify/api/session.rb', line 265

attach_function :session_set_connection_rules, [ Session, :connection_rules ], APIError

#session_set_connection_type(session, type) ⇒ Symbol

Set current connection type.

Parameters:

  • session (Session)
  • type (Symbol) —

    one of :unknown, :none, :mobile, :mobile_roaming, :wifi, :wired

Returns:

  • (Symbol) —

    error code

See Also:



251
 
# File 'lib/spotify/api/session.rb', line 251

attach_function :session_set_connection_type, [ Session, :connection_type ], APIError

#session_set_private_session(session, enabled) ⇒ Symbol

Set if private session is enabled.

This disables sharing of what the user is listening to with Spotify Social, Facebook, and LastFM. The private session will automatically revert back to normal state after a period of inactivity (6 hours?).

Parameters:

  • session (Session)
  • enabled (Boolean) —

    true if playback should be private

Returns:

  • (Symbol) —

    error code



345
 
# File 'lib/spotify/api/session.rb', line 345

attach_function :session_set_private_session, [ Session, :bool ], APIError

#session_set_scrobbling(session, social_provider, scrobbling_state) ⇒ Symbol

Note:

changing the global settings are currently not supported.

Set if scrobbling should be enabled.

Parameters:

  • session (Session)
  • social_provider (Symbol) —

    one of :spotify, :facebook, or :lastfm

  • scrobbling_state (Symbol) —

    one of :use_global_setting, :local_enabled, :local_disabled, :global_enabled, :global_disabled

Returns:

  • (Symbol) —

    error code



361
 
# File 'lib/spotify/api/session.rb', line 361

attach_function :session_set_scrobbling, [ Session, :social_provider, :scrobbling_state ], APIError

#session_set_social_credentials(session, social_provider, username, password) ⇒ Symbol

Note:

currently this is only relevenat for LastFm

Note:

set scrobbling state to true to force an authentication attempt, if it fails the scrobble_error callback will be invoked

Set the user’s credentials for a social provider.

Parameters:

  • session (Session)
  • social_provider (Symbol)
  • username (String)
  • password (String)

Returns:

  • (Symbol) —

    error code

See Also:



408
 
# File 'lib/spotify/api/session.rb', line 408

attach_function :session_set_social_credentials, [ Session, :social_provider, UTF8String, UTF8String ], APIError

#session_set_volume_normalization(session, normalize) ⇒ Symbol

Set volume normalization.

Parameters:

  • session (Session)
  • normalize (Boolean) —

    true if libspotify should attempt to normalize sound volume

Returns:

  • (Symbol) —

    error code



314
 
# File 'lib/spotify/api/session.rb', line 314

attach_function :session_set_volume_normalization, [ Session, :bool ], APIError

#session_starred_create(session) ⇒ Playlist?

Note:

if not logged in, the function always return nil.

Returns starred playlist for currently logged in user.

Parameters:

Returns:

  • (Playlist, nil) —

    starred playlist for currently logged in user



220
 
# File 'lib/spotify/api/session.rb', line 220

attach_function :session_starred_create, [ Session ], Playlist

#session_starred_for_user_create(session, username) ⇒ Playlist?

Note:

if not logged in, the function always return nil.

Returns starred playlist for the specified user.

Parameters:

  • session (Session)
  • username (String) —

    canonical username of user

Returns:

  • (Playlist, nil) —

    starred playlist for the specified user



227
 
# File 'lib/spotify/api/session.rb', line 227

attach_function :session_starred_for_user_create, [ Session, UTF8String ], Playlist

#session_user(session) ⇒ User?

Returns currently logged in user.

Parameters:

Returns:

  • (User, nil) —

    currently logged in user



125
 
# File 'lib/spotify/api/session.rb', line 125

attach_function :session_user, [ Session ], User

#session_user_country(session) ⇒ String

Note:

if not logged in, the function always return “ZZ”.

Returns currently logged in user’s country code.

Parameters:

Returns:

  • (String) —

    currently logged in user’s country code



297
 
# File 'lib/spotify/api/session.rb', line 297

attach_function :session_user_country, [ Session ], CountryCode

#session_user_name(session) ⇒ String

Note:

if not logged in, the function always return an empty string.

Returns canonical name for currently logged in user.

Parameters:

Returns:

  • (String) —

    canonical name for currently logged in user



334
 
# File 'lib/spotify/api/session.rb', line 334

attach_function :session_user_name, [ Session ], UTF8String

#session_userdata(session) ⇒ FFI::Pointer

Returns userdata from config in #session_create.

Parameters:

Returns:



144
 
# File 'lib/spotify/api/session.rb', line 144

attach_function :session_userdata, [ Session ], :userdata

#toplistbrowse_album(toplist_browse, index) ⇒ Album?

Note:

if index is out of range, the function always return nil.

Returns album at index.

Parameters:

Returns:

  • (Album, nil) —

    album at index

See Also:



63
 
# File 'lib/spotify/api/toplist_browse.rb', line 63

attach_function :toplistbrowse_album, [ ToplistBrowse, :int ], Album

#toplistbrowse_artist(toplist_browse, : int) ⇒ Artist?

Note:

if index is out of range, the function always return nil.

Returns artist at index.

Parameters:

Returns:

  • (Artist, nil) —

    artist at index

See Also:



48
 
# File 'lib/spotify/api/toplist_browse.rb', line 48

attach_function :toplistbrowse_artist, [ ToplistBrowse, :int ], Artist

#toplistbrowse_backend_request_duration(toplist_browse) ⇒ Integer

Returns the time in ms that was spent waiting for Spotify backend to serve request, or -1 if served from cache.

Parameters:

Returns:

  • (Integer) —

    the time in ms that was spent waiting for Spotify backend to serve request, or -1 if served from cache



83
 
# File 'lib/spotify/api/toplist_browse.rb', line 83

attach_function :toplistbrowse_backend_request_duration, [ ToplistBrowse ], :int

#toplistbrowse_create(session, type, region, username, callback, userdata) ⇒ Object

Note:

it is very important that the callback is not garbage collected before it is called!

Initiate a request for browsing a toplist.

Examples:

callback = proc { |toplist_browse| puts "Toplist query finished!" }
toplist_browse = Spotify.toplistbrowse_create(session, :tracks, :everywhere, nil, callback, nil)

for sweden

callback = proc { |toplist_browse| puts "Toplist query finished!" }
toplist_browse = Spotify.toplistbrowse_create(session, :tracks, Spotify::CountryCode.to_native("SE", nil), nil, callback, nil)

Parameters:

  • session (Session)
  • type (Symbol) —

    one of :artists, :albums, :tracks

  • region (Symbol) —

    :everywhere, :user, or a CountryCode

  • username (String, nil) —

    if region is :user this is the user to get toplists for, use nil for currently logged in user

  • callback (Proc<ToplistBrowse, FFI::Pointer>)
  • userdata (FFI::Pointer) 


23
 
# File 'lib/spotify/api/toplist_browse.rb', line 23

attach_function :toplistbrowse_create, [ Session, :toplisttype, :toplistregion, UTF8String, :toplistbrowse_complete_cb, :userdata ], ToplistBrowse

#toplistbrowse_error(toplist_browse) ⇒ Symbol

Returns error code.

Parameters:

Returns:

  • (Symbol) —

    error code



33
 
# File 'lib/spotify/api/toplist_browse.rb', line 33

attach_function :toplistbrowse_error, [ ToplistBrowse ], APIError

#toplistbrowse_is_loaded(toplist_browse) ⇒ Boolean

Returns true if toplist request has finished loading.

Parameters:

Returns:

  • (Boolean) —

    true if toplist request has finished loading



28
 
# File 'lib/spotify/api/toplist_browse.rb', line 28

attach_function :toplistbrowse_is_loaded, [ ToplistBrowse ], :bool

#toplistbrowse_num_albums(toplist_browse) ⇒ Integer

Note:

if the toplist is not loaded, the function always return 0.

Returns number of albums in the toplist result.

Parameters:

Returns:

  • (Integer) —

    number of albums in the toplist result

See Also:



55
 
# File 'lib/spotify/api/toplist_browse.rb', line 55

attach_function :toplistbrowse_num_albums, [ ToplistBrowse ], :int

#toplistbrowse_num_artists(toplist_browse) ⇒ Integer

Note:

if the toplist is not loaded, the function always return 0.

Returns number of artists in the toplist result.

Parameters:

Returns:

  • (Integer) —

    number of artists in the toplist result

See Also:



40
 
# File 'lib/spotify/api/toplist_browse.rb', line 40

attach_function :toplistbrowse_num_artists, [ ToplistBrowse ], :int

#toplistbrowse_num_tracks(toplist_browse) ⇒ Integer

Note:

if the toplist is not loaded, the function always return 0.

Returns number of tracks in the toplist result.

Parameters:

Returns:

  • (Integer) —

    number of tracks in the toplist result

See Also:



70
 
# File 'lib/spotify/api/toplist_browse.rb', line 70

attach_function :toplistbrowse_num_tracks, [ ToplistBrowse ], :int

#toplistbrowse_track(toplist_browse, index) ⇒ Track?

Note:

if index is out of range, the function always return nil.

Returns track at index.

Parameters:

Returns:

  • (Track, nil) —

    track at index

See Also:



78
 
# File 'lib/spotify/api/toplist_browse.rb', line 78

attach_function :toplistbrowse_track, [ ToplistBrowse, :int ], Track

#track_album(track) ⇒ Album?

Note:

if the track is not loaded, the function always return nil.

Returns album of the track.

Parameters:

Returns:

  • (Album, nil) —

    album of the track



81
 
# File 'lib/spotify/api/track.rb', line 81

attach_function :track_album, [ Track ], Album

#track_artist(track, index) ⇒ Artist?

Note:

if index is out of range, the function always return nil.

Returns artist at index.

Parameters:

Returns:

  • (Artist, nil) —

    artist at index

See Also:



75
 
# File 'lib/spotify/api/track.rb', line 75

attach_function :track_artist, [ Track, :int ], Artist

#track_disc(track) ⇒ Integer

Note:

The function only returns valid data for tracks appearing in an ArtistBrowse or AlbumBrowse result.

Note:

if the disc is not available, the function always return 0.

Returns disc number for the track, 1..(total number of discs on album).

Parameters:

Returns:

  • (Integer) —

    disc number for the track, 1..(total number of discs on album)



106
 
# File 'lib/spotify/api/track.rb', line 106

attach_function :track_disc, [ Track ], :int

#track_duration(track) ⇒ Integer

Note:

if the track is not loaded, the function always return 0.

Returns duration of the track in milliseconds.

Parameters:

Returns:

  • (Integer) —

    duration of the track in milliseconds



93
 
# File 'lib/spotify/api/track.rb', line 93

attach_function :track_duration, [ Track ], :int

#track_error(track) ⇒ Symbol

Returns error code.

Parameters:

Returns:

  • (Symbol) —

    error code



13
 
# File 'lib/spotify/api/track.rb', line 13

attach_function :track_error, [ Track ], APIError

#track_get_availability(session, track) ⇒ Symbol

Note:

if the track is not loaded, the function always return :unavailable.

Returns track availability, one of :unavailable, :available, :not_streamable, :banned_by_artist.

Parameters:

Returns:

  • (Symbol) —

    track availability, one of :unavailable, :available, :not_streamable, :banned_by_artist

See Also:



21
 
# File 'lib/spotify/api/track.rb', line 21

attach_function :track_get_availability, [ Session, Track ], :track_availability

#track_get_playable(session, track) ⇒ Track

Note:

If the track has been autolinked, the returned track will not be the same track.

Returns the actual track that will be played if track is scheduled for playback.

Parameters:

Returns:

  • (Track) —

    the actual track that will be played if track is scheduled for playback



132
 
# File 'lib/spotify/api/track.rb', line 132

attach_function :track_get_playable,  [ Session, Track ], Track

#track_index(track) ⇒ Integer

Note:

The function only returns valid data for tracks appearing in an ArtistBrowse or AlbumBrowse result.

Note:

if the disc is not available, the function always return 0.

Returns position of track on it’s disc, starts at 1.

Parameters:

Returns:

  • (Integer) —

    position of track on it’s disc, starts at 1



113
 
# File 'lib/spotify/api/track.rb', line 113

attach_function :track_index, [ Track ], :int

#track_is_autolinked(session, track) ⇒ Boolean

Note:

if the track is not loaded, the function always return false.

Returns true if the track is automatically linked to another playable version of the track.

Parameters:

Returns:

  • (Boolean) —

    true if the track is automatically linked to another playable version of the track



35
 
# File 'lib/spotify/api/track.rb', line 35

attach_function :track_is_autolinked, [ Session, Track ], :bool

#track_is_loaded(track) ⇒ Boolean

Returns true if track has finished loading.

Parameters:

Returns:

  • (Boolean) —

    true if track has finished loading



8
 
# File 'lib/spotify/api/track.rb', line 8

attach_function :track_is_loaded, [ Track ], :bool

#track_is_local(session, track) ⇒ Boolean

Note:

if the track is not loaded, the function always return false.

Returns true if the track is a local track.

Parameters:

Returns:

  • (Boolean) —

    true if the track is a local track



28
 
# File 'lib/spotify/api/track.rb', line 28

attach_function :track_is_local, [ Session, Track ], :bool

#track_is_placeholder(track) ⇒ Boolean

Note:

the track does not need to be loaded for this function to return a correct value.

Note:

use #link_create_from_track to get a link to the wrapped item.

Placeholder tracks are a way to store non-track items in a playlist.

This is used when sending playlists to users, for example.

Parameters:

Returns:

  • (Boolean) —

    true if track is a placeholder

See Also:



125
 
# File 'lib/spotify/api/track.rb', line 125

attach_function :track_is_placeholder, [ Track ], :bool

#track_is_starred(session, track) ⇒ Boolean

Note:

if the track is not loaded, the function always return false.

Returns true if the track is starred by the current user.

Parameters:

Returns:

  • (Boolean) —

    true if the track is starred by the current user



42
 
# File 'lib/spotify/api/track.rb', line 42

attach_function :track_is_starred, [ Session, Track ], :bool

#track_name(track) ⇒ String

Note:

if the track is not loaded, the function always return an empty string.

Returns track name.

Parameters:

Returns:

  • (String) —

    track name



87
 
# File 'lib/spotify/api/track.rb', line 87

attach_function :track_name, [ Track ], UTF8String

#track_num_artists(track) ⇒ Integer

Note:

if the track is not loaded, the function always return 0.

Returns number of artists performing the track.

Parameters:

Returns:

  • (Integer) —

    number of artists performing the track



67
 
# File 'lib/spotify/api/track.rb', line 67

attach_function :track_num_artists, [ Track ], :int

#track_offline_get_status(track) ⇒ Symbol

Returns offline status of track, one of :no, :waiting, :downloading, :done, :error, :done_expired, :limit_exceeded, :done_resync.

Parameters:

Returns:

  • (Symbol) —

    offline status of track, one of :no, :waiting, :downloading, :done, :error, :done_expired, :limit_exceeded, :done_resync



137
 
# File 'lib/spotify/api/track.rb', line 137

attach_function :track_offline_get_status, [ Track ], :track_offline_status

#track_popularity(track) ⇒ Integer

Note:

if the track is not loaded, the function always return 0.

Returns popularity of the track, 0..100.

Parameters:

Returns:

  • (Integer) —

    popularity of the track, 0..100



99
 
# File 'lib/spotify/api/track.rb', line 99

attach_function :track_popularity, [ Track ], :int

#track_set_starred(session, tracks, starred) ⇒ Symbol

Star or unstar a list of tracks.

Examples:

Spotify.track_set_starred(session, [track_a, track_b], true) => :ok

Parameters:

  • session (Session)
  • tracks (Array<Track>)
  • starred (Boolean) —

    true if tracks should be starred, false if unstarred

Returns:

  • (Symbol) —

    error code



54
55
56
57
58
59
60
61
 
# File 'lib/spotify/api/track.rb', line 54

attach_function :track_set_starred, [ Session, :array, :int, :bool ], APIError do |session, tracks, starred|
  tracks = Array(tracks)

  with_buffer(Spotify::Track, size: tracks.length) do |tracks_buffer|
    tracks_buffer.write_array_of_pointer(tracks)
    sp_track_set_starred(session, tracks_buffer, tracks.length, starred)
  end
end

#user_canonical_name(user) ⇒ String

Returns canonical username of user, the one used by Spotify in just about all places.

Parameters:

Returns:

  • (String) —

    canonical username of user, the one used by Spotify in just about all places



8
 
# File 'lib/spotify/api/user.rb', line 8

attach_function :user_canonical_name, [ User ], UTF8String

#user_display_name(user) ⇒ String

Note:

#user_is_loaded can return true even if libspotify does not know the display name yet.

Note:

if libspotify does not have a display name, the function will return the canonical name of the user.

Returns display name of user.

Parameters:

Returns:

  • (String) —

    display name of user



15
 
# File 'lib/spotify/api/user.rb', line 15

attach_function :user_display_name, [ User ], UTF8String

#user_is_loaded(user) ⇒ Boolean

Note:

the function may return true, even if display name is not yet known, make sure to #session_process_events!

Returns true if user has finished loading.

Parameters:

Returns:

  • (Boolean) —

    true if user has finished loading



21
 
# File 'lib/spotify/api/user.rb', line 21

attach_function :user_is_loaded, [ User ], :bool