Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 117 lines (76 sloc) 4.25 kb
64d7ab0 @rsms added WIP API markdown document
rsms authored
1 # node-spotify API
2
3 ## spotify
4
5 The module.
6
7 var spotify = require('spotify');
8
9 ### spotify.version -> string
10
11 Module version. I.e. `"0.1"`
12
13 ### spotify.spotifyAPIVersion -> int
14
15 Which Spotify API version this module is compatible with. I.e. `2`.
16
0732341 @rsms some progress on the API doc
rsms authored
17 ## spotify.Session(configuration)
64d7ab0 @rsms added WIP API markdown document
rsms authored
18
1615c47 @rsms some progress on the API doc
rsms authored
19 Represents a session. You can think of a "session" as a logged in and running Spotify client.
64d7ab0 @rsms added WIP API markdown document
rsms authored
20
0732341 @rsms some progress on the API doc
rsms authored
21 var session = new spotify.Session({
22 applicationKey: appkey, // [required] array of ints
23 userAgent: "my app", // [optional] defaults to "node-spotify"
24 cacheLocation: ".cache", // [optional] defaults to ".spotify-cache"
25 settingsLocation: ".conf" // [optional] defaults to ".spotify-settings"
26 });
27
64d7ab0 @rsms added WIP API markdown document
rsms authored
28 > **Note:** Even though this API allows for virtually unlimited number of concurrent Session objects, it is still considered experimental because libspotify has not been extensively tested with session concurrency (i.e. there might be thread sync bugs lurking in the depts of libspotify).
29
0eb0fad @rsms some progress on the API doc
rsms authored
30 All methods except `login` require the session to be in a logged in state (`session.connectionState === "logged_in"`) when called, or weird and highly unexpected things will happen.
0732341 @rsms some progress on the API doc
rsms authored
31
32 ### spotify.Session.prototype.login(username, password, callback(err))
33
34 Sign in to Spotify. The required callback is invoked when you are logged in or an error occurred (e.g. wrong username or password).
35
36 session.login("johndoe", "foobar", function(err) {
37 if (err) throw err;
38 sys.puts("Logged in");
39 session.logout();
40 });
41
42 ### spotify.Session.prototype.logout([callback()])
43
44 Sign out of Spotify. The optional callback is called once all finalization code has been run (e.g. writing settings and syncing with Spotify servers).
45
46 session.login("johndoe", "foobar", function(err) {
47 if (err) throw err;
48 session.logout(function(){
49 sys.puts("Logged out. Bye bye.");
50 });
51 });
52
d076d17 @rsms some progress on the API doc
rsms authored
53 Note that your program will not exit by itself until you have logged out a logged in session (because the session is active), so remember to call `logout` when you are done.
54
0732341 @rsms some progress on the API doc
rsms authored
55 ### spotify.Session.prototype.search(query, callback(err, result))
56
57 Search the Spotify catalouge.
58
5e1aa35 @rsms some progress on the API doc
rsms authored
59 `query` can be either an object:
0732341 @rsms some progress on the API doc
rsms authored
60
61 var query = {
62 query: "album:belle", // [required] query string
63 trackOffset: 0, // [optional] defaults to 0
64 trackCount: 10, // [optional] defaults to 10
65 albumOffset: 0, // [optional] defaults to 0
66 albumCount: 5, // [optional] defaults to 10
67 artistOffset: 0, // [optional] defaults to 0
68 artistCount: 3 // [optional] defaults to 10
69 };
70 session.search(query, function(err, result){
71 if (err) throw err;
72 sys.puts(sys.inspect(result.tracks));
64d7ab0 @rsms added WIP API markdown document
rsms authored
73 });
0732341 @rsms some progress on the API doc
rsms authored
74
5e1aa35 @rsms some progress on the API doc
rsms authored
75 ...or it can be a simple string:
76
77 session.search("album:belle", function(err, result){
78 if (err) throw err;
79 sys.puts(sys.inspect(result.tracks));
80 });
81
0732341 @rsms some progress on the API doc
rsms authored
82 ### spotify.Session.prototype.getTrackByLink(link[, callback(err, track)]) -> track
83
84 Look up a track from a track link (URI or URL). If a callback function is passed as the 2nd argument, that callback will be called when the track's info has loaded:
85
86 var link = 'spotify:track:01gCUID7bHTcp6JzeTfpIe';
87 session.getTrackByLink(link, function(err, track) {
88 if (err) throw err;
89 sys.puts('track info:\n'+sys.inspect(track));
90 });
91
92 If no callback is passed errors like malformed link are thrown (rather than passed to a callback):
93
94 var link = 'spotify:track:01gCUID7bHTcp6JzeTfpIe';
95 try {
96 var track = session.getTrackByLink(link);
97 } catch (e) {
98 sys.error(e.stack || e);
99 }
100
101 Note that the track object returned from this function is not guaranteed to be in a usable (i.e. `track.loaded == true`) state.
102
103 ### spotify.Session.prototype.user -> User
104
105 The currently logged in user.
106
107 ### spotify.Session.prototype.playlists -> PlaylistContainer
108
109 An array-like object representing all playlists you are subscribing to (all the playlists in the left hand side column in the official Spotify desktop client).
110
111 ### spotify.Session.prototype.connectionState -> string
112
113 The state of the session (e.g. "logged_in" or "disconnected"). See `spotify/index.js` for details.
114
115
64d7ab0 @rsms added WIP API markdown document
rsms authored
116
Something went wrong with that request. Please try again.