1 | # lastfm-node
|
2 |
|
3 | Read and write to users recent plays on Last.fm.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | npm install lastfm
|
8 |
|
9 | ## Usage
|
10 |
|
11 | var LastFmNode = require('lastfm').LastFmNode;
|
12 |
|
13 | var lastfm = new LastFmNode({
|
14 | api_key: 'apikey', // sign-up for a key at http://www.last.fm/api
|
15 | secret: 'secret'
|
16 | });
|
17 |
|
18 | ## Documentation
|
19 |
|
20 | ### RecentTracksStream
|
21 |
|
22 | lastfm.stream(username);
|
23 |
|
24 | Returns: a `RecentTracksStream` instance
|
25 |
|
26 | Methods:
|
27 |
|
28 | - *start()*
|
29 |
|
30 | Start streaming recent track info.
|
31 |
|
32 | - *stop()*
|
33 |
|
34 | Stop streaming recent track info.
|
35 |
|
36 | - *on(event, listener)*
|
37 |
|
38 | Adds a listener for the specified event.
|
39 |
|
40 | - *removeListener(event, listener)*
|
41 |
|
42 | Removes the listener for the specified event.
|
43 |
|
44 | Options:
|
45 |
|
46 | - *autostart*
|
47 |
|
48 | Start streaming automatically. Defaults to false.
|
49 |
|
50 | - *lastPlayed*, *nowPlaying*, *scrobbled*, *stoppedPlaying*, *error*
|
51 |
|
52 | Event listeners.
|
53 |
|
54 | Events:
|
55 |
|
56 | - *lastPlayed(track)*
|
57 |
|
58 | The user's last scrobbled track.
|
59 |
|
60 | - *nowPlaying(track)*
|
61 |
|
62 | Track the user is currently listening to.
|
63 |
|
64 | - *scrobbled(track)*
|
65 |
|
66 | Now playing track has been scrobbled.
|
67 |
|
68 | - *stoppedPlaying(track)*
|
69 |
|
70 | User stopped listening to current track.
|
71 |
|
72 | - *error(error)*
|
73 |
|
74 | Ruh-roh.
|
75 |
|
76 | ### LastFmSession
|
77 |
|
78 | lastfm.session([user], [key]);
|
79 |
|
80 | Returns: a `LastFmSession` instance.
|
81 |
|
82 | If no key is supplied then the authorise() method must be used before the session can be used to make authenticated calls. See the last.fm API documentation for more info.
|
83 |
|
84 | Public properties:
|
85 |
|
86 | - *user*
|
87 |
|
88 | The username of the Last.fm user associated with the session.
|
89 |
|
90 | - *key*
|
91 |
|
92 | The session key. Either passed in or generated using authorise().
|
93 |
|
94 | Methods:
|
95 |
|
96 | - *authorise(token, [options])*
|
97 |
|
98 | Authorises user with Last.fm api. See last.fm documentation.
|
99 | Options:
|
100 | - *authorised* : `function(session)`
|
101 | Listener for *authorised* event. See below.
|
102 |
|
103 | - *error* : `function(error)`
|
104 | Listener for `error` event. See below.
|
105 |
|
106 | - *on(event, handler)*
|
107 |
|
108 | Adds a listener for the specified event.
|
109 |
|
110 | - *removeListener(event, handler)*
|
111 |
|
112 | Removes the listener for the specified event.
|
113 |
|
114 | - *isAuthorised()*
|
115 |
|
116 | Returns true if the session has been authorised or a key was specified in the constructor.
|
117 |
|
118 | Events:
|
119 |
|
120 | - *authorised(session)*
|
121 |
|
122 | Authorisation of session was successful.
|
123 | Note: Only emitted after a call to authorise(). Keys supplied in the constructor are assumed to be valid.
|
124 |
|
125 | - *error(track, error)*
|
126 |
|
127 | Ruh-roh.
|
128 |
|
129 | ### LastFmUpdate
|
130 |
|
131 | lastfm.update(method, session, options);
|
132 |
|
133 | Returns a `LastFmUpdate` instance.
|
134 |
|
135 | Valid methods are 'nowplaying' and 'scrobble'.
|
136 |
|
137 | An authorised `LastFmSession` instance is required to make a successful update.
|
138 |
|
139 | Options:
|
140 |
|
141 | - *track*
|
142 |
|
143 | Track for nowplaying and scrobble requests. Uses same format as returned by `RecentTracksStream` events.
|
144 |
|
145 | - *timestamp*
|
146 |
|
147 | Required for scrobble requests. Timestamp is in unix time (seconds since 01-01-1970 and is in UTC time).
|
148 |
|
149 | - *success*
|
150 |
|
151 | Listener for `success` event.
|
152 |
|
153 | - *error*
|
154 |
|
155 | Listener for `error` event.
|
156 |
|
157 | Events:
|
158 |
|
159 | - *success(track)*
|
160 |
|
161 | Update request was successful.
|
162 |
|
163 | - *error(track, error)*
|
164 |
|
165 | Ruh-roh.
|
166 |
|
167 | ### LastFmInfo
|
168 |
|
169 | lastfm.info(itemtype, [options]);
|
170 |
|
171 | Returns: a `LastFmInfo` instance.
|
172 |
|
173 | Gets extended info about specified item.
|
174 |
|
175 | Public properties:
|
176 |
|
177 | - *itemtype*
|
178 |
|
179 | Any Last.fm item with a getInfo method. eg user, track, artist, etc.
|
180 |
|
181 | Options:
|
182 |
|
183 | - *success*
|
184 |
|
185 | Listener for `success` event.
|
186 |
|
187 | - *error*
|
188 |
|
189 | Listener for `error` event.
|
190 |
|
191 | - *various*
|
192 |
|
193 | Params as specified in Last.fm API, eg user: "username"
|
194 |
|
195 | Special cases:
|
196 |
|
197 | When requesting track info the `track` param can be either the track name or a track object as returned by `RecentTracksStream`.
|
198 |
|
199 |
|
200 | ## Example
|
201 |
|
202 | var LastFmNode = require('lastfm').LastFmNode;
|
203 |
|
204 | var lastfm = new LastFmNode({
|
205 | api_key: 'abc',
|
206 | secret: 'secret'
|
207 | });
|
208 |
|
209 | var trackStream = lastfm.stream('username');
|
210 |
|
211 | trackStream.on('lastPlayed', function(track) {
|
212 | console.log('Last played: ' + track.name);
|
213 | });
|
214 |
|
215 | trackStream.on('nowPlaying', function(track) {
|
216 | console.log('Now playing: ' + track.name);
|
217 | });
|
218 |
|
219 | trackStream.on('scrobbled', function(track) {
|
220 | console.log('Scrobbled: ' + track.name);
|
221 | });
|
222 |
|
223 | trackStream.on('stoppedPlaying', function(track) {
|
224 | console.log('Stopped playing: ' + track.name);
|
225 | });
|
226 |
|
227 | trackStream.on('error', function(error) {
|
228 | console.log('Error: ' + error.message);
|
229 | });
|
230 |
|
231 | trackStream.start();
|
232 |
|
233 | var session = lastfm.session();
|
234 | session.authorise(token, {
|
235 | authorised: function(session) {
|
236 | lastfm.update('nowplaying', session, { track: track } );
|
237 | lastfm.update('scrobble', session, { track: track, timestamp: 12345678 });
|
238 | }
|
239 | });
|
240 |
|
241 | ## Influences
|
242 |
|
243 | Heavily drawn from technoweenie's twitter-node
|
244 | http://github.com/technoweenie/twitter-node
|