Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mihaiolteanu/lastfm

Last.fm API for Common Lisp
https://github.com/mihaiolteanu/lastfm

api common-lisp lastfm

Last synced: about 1 month ago
JSON representation

Last.fm API for Common Lisp

Awesome Lists containing this project

README 

        
# lastfm

Interface for the [last.fm](https://www.last.fm) [API](https://www.last.fm/api),

including the services that need authentication and song generators for extra

functionality.



# Installation



## 1. Install the library



Using quickload

```common-lisp

(ql:quickload :lastfm)

```



Or clone it to local-projects 

```bash

git clone https://github.com/mihaiolteanu/lastfm ~/quicklisp/local-projects/lastfm

```



```common-lisp

; 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](https://www.last.fm/api) 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.



```common-lisp

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

```common-lisp

(ql:quickload :lastfm)

(lastfm:generate-session-key)

```

This will open up the [last.fm/api/auth](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).

 

 

 grant permission to last.fm



 

You will need to grant this

 `lastfm` library permission to use your last.fm account ([step

 3](https://www.last.fm/api/desktopauth) in the official last.fm authentication

 process). 

 

 

 permission granted



 

After that, return to your editor (Emacs) and continue from breakpoint.

 

 continue from breakpoint

 

If this step is succesful, the secret key will be added to your

config file, which should now look like this:

```common-lisp

;; ~/.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



```common-lisp

; Get the first top tracks for the given artist.

(artist-gettoptracks "anathema" 5)

    => ("Fragile Dreams" "One Last Goodbye" "A Natural Disaster" "Flying" "Deep")

```



```common-lisp

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

```



```common-lisp

; If step four was done, this will add the song to your last.fm loved tracks.

(track-love "alphaville" "forever young")

```



```common-lisp

;; 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](www.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](http://quickdocs.org/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](www.mihaiolteanu.me)



Licensed under the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.en.html) license.