The lastfm Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The lastfm Reference Manual

This is the lastfm Reference Manual, version 0.1, generated automatically by Declt version 2.4 patchlevel 1 "Will Decker" on Mon Jul 29 15:58:43 2019 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

lastfm

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

Installation

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

grant permission to last.fm

You will need to grant this lastfm library permission to use your last.fm account (step 3 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:

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

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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 lastfm

Author

Mihai Olteanu

License

GPLv3

Description

Interface for the Last.fm API (https://www.last.fm/api/)

Version

0.1

Dependencies
Source

lastfm.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 lastfm.asd

Location

lastfm.asd

Systems

lastfm (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 lastfm/package.lisp

Parent

lastfm (system)

Location

package.lisp

Packages

lastfm


Previous: , Up: Lisp files   [Contents][Index]

3.1.3 lastfm/lastfm.lisp

Dependency

package.lisp (file)

Parent

lastfm (system)

Location

lastfm.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 lastfm

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: album-getinfo ARTIST ALBUM
Package

lastfm

Source

lastfm.lisp (file)

Function: album-songs ARTIST ALBUM

Return a generator with all the songs on the artist’s album.

Package

lastfm

Source

lastfm.lisp (file)

Function: artist-getinfo ARTIST
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-getsimilar ARTIST LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-gettopalbums ARTIST LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-gettoptags ARTIST
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-gettoptracks ARTIST LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-search ARTIST LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: artist-similar-artists-songs ARTIST NARTISTS NSONGS

Return an infinite songs generator. Every new song is picked by first selecting a random artist from the first nartists similar to the given artist, according to the last.fm info. From this random artist a random song is picked from the first best nsongs according to the last.fm info. When called, the generator returns a list of two items, an artist and a song.

Package

lastfm

Source

lastfm.lisp (file)

Function: artist-songs ARTIST NSONGS RANDOM

Return an infinite songs generator. If random is T, every new song is picked at random from the artists’ first best nsongs of all time, as seen on the artist’s last.fm page. If random is nil, the songs are picked in order. After the last song, the first song is returned again, ad infinitum.

Package

lastfm

Source

lastfm.lisp (file)

Function: auth-getsession TOKEN
Package

lastfm

Source

lastfm.lisp (file)

Function: auth-gettoken ()
Package

lastfm

Source

lastfm.lisp (file)

Function: generate-session-key ()

Fetch a token, and then let the user authorize the application in his browser. Only after the user authorizes the application can the session key fetching continue. Thus, we wait until a return from the breakpoint is signaled by the user. After that, call last.fm again to fetch the session key, save it to the rc-file and reload the rc-file.

Package

lastfm

Source

lastfm.lisp (file)

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

Package

lastfm

Source

lastfm.lisp (file)

Function: random-artist-song ARTIST &optional LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: random-similar-artist ARTIST &optional LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: random-tag-artist TAG &optional LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: random-tag-song TAG &optional LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: random-user-loved-song USER &optional LIMIT
Package

lastfm

Source

lastfm.lisp (file)

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

Package

lastfm

Source

lastfm.lisp (file)

Function: tag-getinfo TAG
Package

lastfm

Source

lastfm.lisp (file)

Function: tag-gettopartists TAG LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: tag-gettoptracks TAG LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: tag-similar-artists-songs TAG NARTISTS NSONGS
Package

lastfm

Source

lastfm.lisp (file)

Function: tag-songs TAGNAME NSONGS RANDOM
Package

lastfm

Source

lastfm.lisp (file)

Function: track-love ARTIST TRACK
Package

lastfm

Source

lastfm.lisp (file)

Function: track-scrobble ARTIST TRACK TIMESTAMP
Package

lastfm

Source

lastfm.lisp (file)

Function: track-unlove ARTIST TRACK
Package

lastfm

Source

lastfm.lisp (file)

Function: user-getlovedtracks USER LIMIT
Package

lastfm

Source

lastfm.lisp (file)

Function: user-songs USERNAME NSONGS RANDOM

Return a generator with songs from a user of your choice.

Package

lastfm

Source

lastfm.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *api-key*
Package

lastfm

Source

lastfm.lisp (file)

Special Variable: *base-url*
Package

lastfm

Source

lastfm.lisp (file)

Special Variable: *methods*
Package

lastfm

Source

lastfm.lisp (file)

Special Variable: *shared-secret*
Package

lastfm

Source

lastfm.lisp (file)

Special Variable: *sk*
Package

lastfm

Source

lastfm.lisp (file)

Special Variable: *username*
Package

lastfm

Source

lastfm.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Macros

Macro: build-lastfm-functions ()

Create a function for each of the last.fm methods and memoize the ones that don’t need authentication. All the created functions are exported.

Package

lastfm

Source

lastfm.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Functions

Function: add-sk-to-rcfile SK

Add the session key to the user config file.

Package

lastfm

Source

lastfm.lisp (file)

Function: auth-needed-p METHOD
Package

lastfm

Source

lastfm.lisp (file)

Function: authorize-user TOKEN

Ask the user to authorize the application.

Package

lastfm

Source

lastfm.lisp (file)

Function: config &key API-KEY SHARED-SECRET USERNAME SK

This function is called from the user config file once it is loaded.

Package

lastfm

Source

lastfm.lisp (file)

Function: create-double-generator ARTIST-FN NAME NARTISTS NSONGS
Package

lastfm

Source

lastfm.lisp (file)

Function: create-generator FN NAME NITEMS RANDOM &key YIELD-NAME
Package

lastfm

Source

lastfm.lisp (file)

Function: find-method-entry NAME
Package

lastfm

Source

lastfm.lisp (file)

Function: lfm-request METHOD &rest PARAM-VALUES
Package

lastfm

Source

lastfm.lisp (file)

Function: load-rc-file ()

Load the config file. Create it with empty strings if the file does not exist. The user will have to update this file, otherwise, all calls willl return NIL.

Package

lastfm

Source

lastfm.lisp (file)

Function: method-name METHOD
Package

lastfm

Source

lastfm.lisp (file)

Function: method-name-string METHOD

A method name string in the format requested by the Last.fm API parameters

Package

lastfm

Source

lastfm.lisp (file)

Function: method-parameters METHOD
Package

lastfm

Source

lastfm.lisp (file)

Function: multi-query-p QUERY

CSS selectors with ’,’ allow retrieving multiple tags in the same request

Package

lastfm

Source

lastfm.lisp (file)

Function: param-value-list METHOD PARAM-VALUES

Build the parameter/value list according to the given method and the user supplied values.

Package

lastfm

Source

lastfm.lisp (file)

Function: parameter-string PARAM
Package

lastfm

Source

lastfm.lisp (file)

Function: parse-request-results HTML QUERY
Package

lastfm

Source

lastfm.lisp (file)

Function: query-string METHOD
Package

lastfm

Source

lastfm.lisp (file)

Function: request-method METHOD PARAM-VALUES &key RETRIES

Make the request through the Last.fm API

Package

lastfm

Source

lastfm.lisp (file)

Function: request-string PARAMS

The signing procedure for authentication needs all the parameters and values lumped together in one big string without equal or ampersand symbols between them, and with the shared secret appended to the end of this string.

Package

lastfm

Source

lastfm.lisp (file)

Function: session-key-p METHOD
Package

lastfm

Source

lastfm.lisp (file)

Function: sign STR
Package

lastfm

Source

lastfm.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L  
Index Entry  Section

F
File, Lisp, lastfm.asd: The lastfm<dot>asd file
File, Lisp, lastfm/lastfm.lisp: The lastfm/lastfm<dot>lisp file
File, Lisp, lastfm/package.lisp: The lastfm/package<dot>lisp file

L
lastfm.asd: The lastfm<dot>asd file
lastfm/lastfm.lisp: The lastfm/lastfm<dot>lisp file
lastfm/package.lisp: The lastfm/package<dot>lisp file
Lisp File, lastfm.asd: The lastfm<dot>asd file
Lisp File, lastfm/lastfm.lisp: The lastfm/lastfm<dot>lisp file
Lisp File, lastfm/package.lisp: The lastfm/package<dot>lisp file

Jump to:   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   A   B   C   F   G   L   M   P   Q   R   S   T   U  
Index Entry  Section

A
add-sk-to-rcfile: Internal functions
album-getinfo: Exported functions
album-songs: Exported functions
artist-getinfo: Exported functions
artist-getsimilar: Exported functions
artist-gettopalbums: Exported functions
artist-gettoptags: Exported functions
artist-gettoptracks: Exported functions
artist-search: Exported functions
artist-similar-artists-songs: Exported functions
artist-songs: Exported functions
auth-getsession: Exported functions
auth-gettoken: Exported functions
auth-needed-p: Internal functions
authorize-user: Internal functions

B
build-lastfm-functions: Internal macros

C
config: Internal functions
create-double-generator: Internal functions
create-generator: Internal functions

F
find-method-entry: Internal functions
Function, add-sk-to-rcfile: Internal functions
Function, album-getinfo: Exported functions
Function, album-songs: Exported functions
Function, artist-getinfo: Exported functions
Function, artist-getsimilar: Exported functions
Function, artist-gettopalbums: Exported functions
Function, artist-gettoptags: Exported functions
Function, artist-gettoptracks: Exported functions
Function, artist-search: Exported functions
Function, artist-similar-artists-songs: Exported functions
Function, artist-songs: Exported functions
Function, auth-getsession: Exported functions
Function, auth-gettoken: Exported functions
Function, auth-needed-p: Internal functions
Function, authorize-user: Internal functions
Function, config: Internal functions
Function, create-double-generator: Internal functions
Function, create-generator: Internal functions
Function, find-method-entry: Internal functions
Function, generate-session-key: Exported functions
Function, lfm-request: Internal functions
Function, load-rc-file: Internal functions
Function, method-name: Internal functions
Function, method-name-string: Internal functions
Function, method-parameters: Internal functions
Function, multi-query-p: Internal functions
Function, my-loved-songs: Exported functions
Function, param-value-list: Internal functions
Function, parameter-string: Internal functions
Function, parse-request-results: Internal functions
Function, query-string: Internal functions
Function, random-artist-song: Exported functions
Function, random-similar-artist: Exported functions
Function, random-tag-artist: Exported functions
Function, random-tag-song: Exported functions
Function, random-user-loved-song: Exported functions
Function, request-method: Internal functions
Function, request-string: Internal functions
Function, session-key-p: Internal functions
Function, sign: Internal functions
Function, song-youtube-url: Exported functions
Function, tag-getinfo: Exported functions
Function, tag-gettopartists: Exported functions
Function, tag-gettoptracks: Exported functions
Function, tag-similar-artists-songs: Exported functions
Function, tag-songs: Exported functions
Function, track-love: Exported functions
Function, track-scrobble: Exported functions
Function, track-unlove: Exported functions
Function, user-getlovedtracks: Exported functions
Function, user-songs: Exported functions

G
generate-session-key: Exported functions

L
lfm-request: Internal functions
load-rc-file: Internal functions

M
Macro, build-lastfm-functions: Internal macros
method-name: Internal functions
method-name-string: Internal functions
method-parameters: Internal functions
multi-query-p: Internal functions
my-loved-songs: Exported functions

P
param-value-list: Internal functions
parameter-string: Internal functions
parse-request-results: Internal functions

Q
query-string: Internal functions

R
random-artist-song: Exported functions
random-similar-artist: Exported functions
random-tag-artist: Exported functions
random-tag-song: Exported functions
random-user-loved-song: Exported functions
request-method: Internal functions
request-string: Internal functions

S
session-key-p: Internal functions
sign: Internal functions
song-youtube-url: Exported functions

T
tag-getinfo: Exported functions
tag-gettopartists: Exported functions
tag-gettoptracks: Exported functions
tag-similar-artists-songs: Exported functions
tag-songs: Exported functions
track-love: Exported functions
track-scrobble: Exported functions
track-unlove: Exported functions

U
user-getlovedtracks: Exported functions
user-songs: Exported functions

Jump to:   A   B   C   F   G   L   M   P   Q   R   S   T   U  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*api-key*: Internal special variables
*base-url*: Internal special variables
*methods*: Internal special variables
*shared-secret*: Internal special variables
*sk*: Internal special variables
*username*: Internal special variables

S
Special Variable, *api-key*: Internal special variables
Special Variable, *base-url*: Internal special variables
Special Variable, *methods*: Internal special variables
Special Variable, *shared-secret*: Internal special variables
Special Variable, *sk*: Internal special variables
Special Variable, *username*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   L   P   S  
Index Entry  Section

L
lastfm: The lastfm system
lastfm: The lastfm package

P
Package, lastfm: The lastfm package

S
System, lastfm: The lastfm system

Jump to:   L   P   S