1. Install the library
Or clone it to local-projects
git clone https://github.com/mihaiolteanu/lastfm ~/quicklisp/local-projects/lastfm
; Register the new project (ql:register-local-projects)
2. 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.
3. Create or update the config file with the API key
Create a config file 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")
This file is usually located at
~/.config/.lastfmrc. If you want to be
absolutely sure, evaluate
(xdg-config-home) to find out where your config
folder is located. Then create the
.lastfmrc config file there with the
contents from above.
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.
4. 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
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.
Keep this file in a safe place. The next time you install lastfm on a new computer, you only need to copy this file into the correct location and skip all these authentication steps.
; 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.
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
will again return the first one (i.e. the generator is cyclic). You need to
use the generators library for
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.