Step one - install the library and the dependencies
# clone to local-projects for quickload access git clone https://github.com/mihaiolteanu/lastfm ~/quicklisp/local-projects/lastfm
; Register the new project (ql:register-local-projects)
# API calls are signed with an external application sudo apt-get md5sum
Step two - obtain the last.fm API key
To use this library, a last.fm API Key is needed. For that you need a last.fm account and then an API account. Follow the instructions from the official documentation page and you will receive and api-key and a shared secret. Write them down.
Step three - create or update the config file with the API key
Create a config file,
~/.lastfmrc, with the info received from last.fm on step one.
;; ~/.lastfmrc (CONFIG :API-KEY "yout-api-key-string" :SHARED-SECRET "your-shared-secret-string" :USERNAME "your-last-fm-username")
One thing missing from this config file is the secret key (SK) which will be added by this library after the authentication process (see below) is completed. The authentication only needs to be done once.
Step four - generate the session key
Load the library and generate the session key by calling the appropriate interface.
(ql:quickload :lastfm) (lastfm:generate-session-key)
This will open up the last.fm/api/auth page in your favorite browser and put a breakpoint in the code (My app is called muse, in this case. Yours might differ).
You will need to grant this
lastfm library permission to use your last.fm account (step 3 in the official last.fm authentication process).
After that, return to your editor (Emacs) and continue from breakpoint.
If this step is succesful, the secret key will be added to your config file, which should now look like this:
;; ~/.lastfmrc (CONFIG :API-KEY "yout-api-key-string" :SHARED-SECRET "your-shared-secret-string" :USERNAME "your-last-fm-username" :SK "your-secret-key-generated-at-step-four")
If you don't follow this step, the lastfm services that need authentication (love/unlove track, scrobble track) won't work.
; Get the first top tracks for the given artist. (artist-gettoptracks "anathema" 5) => ("Fragile Dreams" "One Last Goodbye" "A Natural Disaster" "Flying" "Deep")
; Get the best ten artist from the 80s. (tag-gettopartists "80s" 10) => ("Duran Duran" "a-ha" "Hall & Oates" "Cyndi Lauper" "Eurythmics" "Erasure" "Wham!" "Alphaville" "Men at Work" "Bonnie Tyler")
; If step four was done, this will add the song to your last.fm loved tracks. (track-love "alphaville" "forever young")
;; Extra functionality not covered by the last.fm API (ql:quickload :generators) ; Get a generator with the first 5 toptracks from the artist (defparameter *anathema* (artist-songs "anathema" 5 T)) ; Calling next on the generator will return a random song. The list is ; infinite. If the random parameter is nil instead of T, the generator is ; circular, but still infinite (next *anathema*) => ("anathema" "Fragile Dreams") (next *anathema*) => ("anathema" "One Last Goodbye") (next *anathema*) => ("anathema" "Fragile Dreams")
last.fm API interfaces
The following last.fm API interfaces are implemented by this library.
limit means the number of items to return. Browse the official last.fm API page for further details. All interfaces that don't need authentication are memoized. A second call with the exact same parameters will be much faster and it won't result in a fresh last.fm request.
album-getinfo artist album
artist-getsimilar artist limit
artist-gettopalbums artist limit
artist-gettoptracks artist limit
artist-search artist limit
Search for a given artist and return limit number of matches as best guesses.
tag-gettoptracks tag limit
tag-gettopartists tag limit
user-getlovedtracks user limit
track-love artist track
Add this track to the list of user's loved track. The username is the one specified in the .lastfmrc config file. Authentication needed (step 4)
track-unlove artist track
Remove this track to the list of user's loved track. The username is the one specified in the .lastfmrc config file. Authentication needed (step 4).
track-scrobble artist track timestamp
Authentication needed (step 4) Timestamp must be in UNIX timestamp format. For example (ql:quickload :local-time) (track-scrobble "anathema" "one last goodbye" (local-time:timestamp-to-unix (local-time:now)))
Extra useful functionality not covered by the last.fm API, but built on top of it and that you might find useful.
song-youtube-url artist song
Since there is no youtube link available through the last.fm API, try and get it from the last.fm song's page.
random-artist-song artist &optional (limit 20)
random-similar-artist artist &optional (limit 20)
random-user-loved-song user &optional (limit 20)
random-tag-song tag &optional (limit 20)
random-tag-artist tag &optional (limit 20)
These will return generators that can be used by calling next on them. On each call, a new item is received. If the
random parameter, where available, is specified as T, a random elemenent is received on each call. Otherwise, the elements are returned in order, as they appear on their respective last.fm page. After the last element is returned, the
next call will again return the first one (i.e. the generator is cyclic). You need to use the generators library for that.
nparameters specify the number of elements to be taken into consideration, similar to the
limit parameter in the last.fm API case.
artist-songs artist nsongs random
A generator for the artist's first best nsongs
album-songs artist album
Return a non-random generator with all the songs on the artist's album.
tag-songs tagname nsongs random
Best nsongs generators for the given tag.
user-songs username nsongs random
Return a generator with songs from a user of your choice.
my-loved-songs nsongs random
Return a generator with the current user loved songs. The username is the one specified in the .lastfmrc config file.
artist-similar-artists-songs artist nartists nsongs
Each call will first pick a random artist from the list of similar artists and then pick a random song from this chosen artist. This is a random generator.
tag-similar-artists-songs tag nartists nsongs
Each call will first pick a random artist from the list of top artists for this tag and then pick a random song from this chosen artist. This is a random generator.
Copyright (c) 2019 Mihai Olteanu
Licensed under the GPLv3 license.