lastfm

Interface for the last.fm API, including the services that need authentication and song generators for extra functionality.

Installation

1. Install the library

Using quickload

(ql:quickload :lastfm)

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 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.

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.

Usage

; 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") 

API

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-getinfo artist

artist-getsimilar artist limit

artist-gettoptags artist

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-getinfo tag

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)))

Random items

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)

Generators

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.

Authors

Copyright (c) 2019 Mihai Olteanu

Licensed under the GPLv3 license.