The cl-scrobbler Reference Manual

Table of Contents

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

The cl-scrobbler Reference Manual

This is the cl-scrobbler Reference Manual, version 0.4, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:32:14 2018 GMT+0.


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

1 Introduction

Cl-scrobbler

cl-scrobbler is a Common Lisp library for scrobbling to last.fm.

It was initially designed to make it trivial to build a last.fm plugin for shuffletron but it should be useful to other hackers interested in scrobbling via CL, for whatever reason.

Install

You could git clone this library and make sure it's path on your computer is on your asdf:*central-registry* but I strongly recommend that you instead use Zach Beane's positively delightful quicklisp.

Getting Started

The Shuffletron Example

It is recommended to simply mirror the shuffletron plugin. Here's a handwavy explanation of that code:

You should set *song-time-fn* and *song-info-fn* so that the *last-seek* and *song-info* variables can be updated with the current track position and metadata, respectively. Then you can have hooks in your application to call maybe-queue-scrobble when a song ends, update-song-info when a song begins, and, if applicable, update-last-seek after a seek finishes and update-skipped after skipping the track.

Finally, you should fire off a thread to call scrobbler-init and scrobbler-loop which will do the work of creating or restoring the session key and cache and then scrobbling tracks when possible.


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 cl-scrobbler

Author

Brit Butler <redline6561@gmail.com>

License

BSD

Description

A library for scrobbling to last.fm

Version

0.4

Dependencies
Source

cl-scrobbler.asd (file)

Component

src (module)


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

3 Modules

Modules are listed depth-first from the system components tree.


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

3.1 cl-scrobbler/src

Parent

cl-scrobbler (system)

Location

src/

Components

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

4 Files

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


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

4.1 Lisp


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

4.1.1 cl-scrobbler.asd

Location

cl-scrobbler.asd

Systems

cl-scrobbler (system)


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

4.1.2 cl-scrobbler/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

cl-scrobbler


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

4.1.3 cl-scrobbler/src/config.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/config.lisp

Exported Definitions
Internal Definitions

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

4.1.4 cl-scrobbler/src/cache.lisp

Dependency

config.lisp (file)

Parent

src (module)

Location

src/cache.lisp

Exported Definitions

cache-contents (function)

Internal Definitions

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

4.1.5 cl-scrobbler/src/errors.lisp

Dependency

cache.lisp (file)

Parent

src (module)

Location

src/errors.lisp

Internal Definitions

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

4.1.6 cl-scrobbler/src/util.lisp

Dependency

errors.lisp (file)

Parent

src (module)

Location

src/util.lisp

Internal Definitions

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

4.1.7 cl-scrobbler/src/auth.lisp

Dependency

util.lisp (file)

Parent

src (module)

Location

src/auth.lisp

Internal Definitions

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

4.1.8 cl-scrobbler/src/scrobble.lisp

Dependency

auth.lisp (file)

Parent

src (module)

Location

src/scrobble.lisp

Exported Definitions
Internal Definitions

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

5 Packages

Packages are listed by definition order.


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

5.1 cl-scrobbler

Homepage: <a href="http://github.com/redline6561/cl-scrobbler">Github</a>

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

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

6 Definitions

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


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

6.1 Exported definitions


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

6.1.1 Special variables

Special Variable: *config-dir*

The directory to store the session key, scrobble cache and log in.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *scrobble-count*

The number of songs needed in the queue before an attempt to scrobble is made.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *song-info-fn*

This is a lambda or named function intended to take no arguments and return a list where the first element is the track name, the second is the artist and the third is the track length in seconds.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Special Variable: *song-time-fn*

This is a lambda or named function intended to take no arguments and return the current position in the track in seconds.

Package

cl-scrobbler

Source

scrobble.lisp (file)


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

6.1.2 Functions

Function: cache-contents ()

Get a copy of the contents of the *SCROBBLE-CACHE*.

Package

cl-scrobbler

Source

cache.lisp (file)

Function: maybe-queue-scrobble ()

When valid (as determined by VALID-SCROBBLE-P), add a song to the queue to be scrobbled. If there is a network failure, the track will be stored for later scrobbling when a connection is reestablished.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: scrobbler-init ()

Ensure needed variables are set, restore the cache and settings if present and, if scrobbling is enabled, restore or acquire a session key.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: scrobbler-loop ()

Loop indefinitely. If there are at least *SCROBBLE-COUNT* songs queued, scrobble until the queue is empty or errors occur. Sleep 2 minutes and repeat.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: set-now-playing ()

Update the now playing status when *NOW-PLAYING-P* is non-NIL.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: toggle-now-playing ()

Toggle whether or not the Now Playing status is updated with each song.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: toggle-scrobbling ()

Toggle whether or not new songs are added to the queue.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: update-last-seek ()

Set *LAST-SEEK* to the current track position via *SONG-TIME-FN*.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: update-skipped ()

Set *SKIPPED* to the current track position via *SONG-TIME-FN*.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: update-song-info ()

Set *SONG-INFO* to a list of (track artist duration timestamp) via *SONG-INFO-FN* and UNIX-TIMESTAMP.

Package

cl-scrobbler

Source

scrobble.lisp (file)


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

6.2 Internal definitions


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

6.2.1 Special variables

Special Variable: *api-key*

A valid Last.fm API key.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *api-secret*

A valid Last.fm API secret key.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *api-url*

The URL for Last.fm API calls.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *api-version*

The current Last.fm API version.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *error-codes*

A list of Last.fm Error codes. Duh. From http://www.last.fm/api/errorcodes

Package

cl-scrobbler

Source

errors.lisp (file)

Special Variable: *last-seek*

The destination position in seconds of the last seek in the current track.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Special Variable: *now-playing-p*

This variable determines whether the user’s now playing status is updated.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *scrobble-cache*

A queue of cached scrobbles to send when last.fm is available.

Package

cl-scrobbler

Source

cache.lisp (file)

Special Variable: *scrobble-p*

This variable determines whether or not songs are added to the scrobble cache.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *session-key*

The session key used to authenticate calls to last.fm.

Package

cl-scrobbler

Source

config.lisp (file)

Special Variable: *skipped*

Either NIL or the position in seconds before the user skipped to the next track.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Special Variable: *song-info*

A list of (track artist length timestamp) of type (string string int string) or NIL.

Package

cl-scrobbler

Source

scrobble.lisp (file)


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

6.2.2 Macros

Macro: defcall NAME PARAMETERS (&key DOCS METHOD) &body BODY

Define a function named by (FROB-LASTFM-NAME NAME) which calls the API method named by NAME with the given PARAMETERS. The result is bound to RESPONSE, the HTTP status code to STATUS and the headers to HEADERS, then BODY is executed in this environment. Note that this macro is thus unhygienic. DOCS is used to supply a docstring and METHOD determines the HTTP method to use.

Package

cl-scrobbler

Source

util.lisp (file)

Macro: with-logging () &body BODY

Execute BODY in a handler-case such that network failure or any error message from the server results in logging the error to disk via ADD-LOG-ENTRY.

Package

cl-scrobbler

Source

errors.lisp (file)


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

6.2.3 Functions

Function: add-log-entry &rest ARGS

Format ARGS and append the line to the cl-scrobbler log file, creating it if it does not exist.

Package

cl-scrobbler

Source

errors.lisp (file)

Function: add-to-cache SCROBBLE

Add the SCROBBLE to the cache and serialize it to disk.

Package

cl-scrobbler

Source

cache.lisp (file)

Function: attempt-scrobble ()

Peek at *SCROBBLE-CACHE* and attempt to scrobble the next song. If successful, remove the song from the cache and persist it to disk.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: authorize-scrobbling ()

Authorize cl-scrobbler to scrobble to an account, saving the session key in a binary file and setting the *SESSION-KEY* global on success.

Package

cl-scrobbler

Source

auth.lisp (file)

Function: config-file NAME

Return a pathname for NAME under *CONFIG-DIR* ensuring the directory exists.

Package

cl-scrobbler

Source

util.lisp (file)

Function: error-message ERRCODE

Retrieve the error message corresponding to the number ERRCODE.

Package

cl-scrobbler

Source

errors.lisp (file)

Function: frob-lastfm-name STRING

Lispify Last.fm method names. i.e. "auth.getToken" -> ’get-token

Package

cl-scrobbler

Source

util.lisp (file)

Function: frob-symbol SYMB

camelCase Lisp symbols. i.e. ’frob-lisp-symbol -> "frobLispSymbol"

Package

cl-scrobbler

Source

util.lisp (file)

Function: get-session TOKEN

Get a Session Token for scrobbling. Last.fm recommends storing these in a secure fashion as they generally have an infinite lifetime.

Package

cl-scrobbler

Source

auth.lisp (file)

Function: get-session-key ()

Attempt to retrieve session key from disk. If it is not present, authorize a new session with last.fm and store the key for future use.

Package

cl-scrobbler

Source

auth.lisp (file)

Function: get-token ()

Get an Unauthorized Token for initiating an authenticated session.

Package

cl-scrobbler

Source

auth.lisp (file)

Function: ksymb &rest ARGS
Package

cl-scrobbler

Source

util.lisp (file)

Function: lastfm-call PARAMS &key METHOD

Make an HTTP request to the *API-URL* with the specified METHOD and PARAMS. PARAMS should be a list of dotted pairs.

Package

cl-scrobbler

Source

util.lisp (file)

Function: make-param SYM VAL

Return a cons, or list of conses if VAL is a list, suitable for use as a POST parameter or GET queryparam in a last.fm call. SYM is converted to a camelCase string and, if VAL is a list, append C-style array indices to SYM.

Package

cl-scrobbler

Source

util.lisp (file)

Function: make-signature PARAMS

Construct an API method signature from PARAMS.

Package

cl-scrobbler

Source

util.lisp (file)

Function: md5sum STRING

Creates an MD5 byte-array of STRING and prints it as lower-case hexadecimal.

Package

cl-scrobbler

Source

util.lisp (file)

Function: mkstr &rest ARGS
Package

cl-scrobbler

Source

util.lisp (file)

Function: persist-cache ()

Persist the cache to disk.

Package

cl-scrobbler

Source

cache.lisp (file)

Function: remove-from-cache ()

Remove the last scrobble from the cache and persist the cache.

Package

cl-scrobbler

Source

cache.lisp (file)

Function: request-user-auth TOKEN

Ask the user to authorize cl-scrobbler to submit songs.

Package

cl-scrobbler

Source

auth.lisp (file)

Function: restore-cache ()

Restore the cache from disk.

Package

cl-scrobbler

Source

cache.lisp (file)

Function: restore-settings ()

Restore the *SCROBBLE-COUNT*, *SCROBBLE-P* and *NOW-PLAYING-P* variables.

Package

cl-scrobbler

Source

config.lisp (file)

Function: save-settings ()

Persist the *SCROBBLE-COUNT*, *SCROBBLE-P* and *NOW-PLAYING-P* settings.

Package

cl-scrobbler

Source

config.lisp (file)

Function: scrobble TRACK TIMESTAMP ARTIST SK

Scrobble the track!

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: simplified-camel-case-to-lisp CAMEL-STRING

Lispify camelCase or CamelCase strings to camel-case.

Package

cl-scrobbler

Source

util.lisp (file)

Function: simplified-lisp-to-camel-case LISP-STRING

This is a very naive lisp symbol to camel-case converter. It is not designed to be robust, merely to handle local variables in the typical lisp style.

Package

cl-scrobbler

Source

util.lisp (file)

Function: symb &rest ARGS
Package

cl-scrobbler

Source

util.lisp (file)

Function: unix-timestamp ()

Cross-implementation abstraction to get the current time measured from the unix epoch (1/1/1970). Should return (values sec nano-sec).

Package

cl-scrobbler

Source

util.lisp (file)

Function: update-now-playing TRACK ARTIST SK

Update the Now Playing status on last.fm.

Package

cl-scrobbler

Source

scrobble.lisp (file)

Function: valid-scrobble-p ()

Last.fm defines a valid scrobble as a track that is over 30 seconds long which has been played for over half its length OR 4 minutes. We extend this notion such that playtime must have occurred without seeking.

Package

cl-scrobbler

Source

scrobble.lisp (file)


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

6.2.4 Generic functions

Generic Function: message CONDITION
Package

cl-scrobbler

Methods
Method: message (CONDITION lastfm-server-error)
Source

errors.lisp (file)


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

6.2.5 Conditions

Condition: lastfm-server-error ()
Package

cl-scrobbler

Source

errors.lisp (file)

Direct superclasses

error (condition)

Direct methods

message (method)

Direct slots
Slot: message
Initargs

:message

Readers

message (generic function)

Condition: scrobble-error ()
Package

cl-scrobbler

Source

errors.lisp (file)

Direct superclasses

error (condition)


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

Appendix A Indexes


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

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
cl-scrobbler.asd: The cl-scrobbler<dot>asd file
cl-scrobbler/src: The cl-scrobbler/src module
cl-scrobbler/src/auth.lisp: The cl-scrobbler/src/auth<dot>lisp file
cl-scrobbler/src/cache.lisp: The cl-scrobbler/src/cache<dot>lisp file
cl-scrobbler/src/config.lisp: The cl-scrobbler/src/config<dot>lisp file
cl-scrobbler/src/errors.lisp: The cl-scrobbler/src/errors<dot>lisp file
cl-scrobbler/src/package.lisp: The cl-scrobbler/src/package<dot>lisp file
cl-scrobbler/src/scrobble.lisp: The cl-scrobbler/src/scrobble<dot>lisp file
cl-scrobbler/src/util.lisp: The cl-scrobbler/src/util<dot>lisp file

F
File, Lisp, cl-scrobbler.asd: The cl-scrobbler<dot>asd file
File, Lisp, cl-scrobbler/src/auth.lisp: The cl-scrobbler/src/auth<dot>lisp file
File, Lisp, cl-scrobbler/src/cache.lisp: The cl-scrobbler/src/cache<dot>lisp file
File, Lisp, cl-scrobbler/src/config.lisp: The cl-scrobbler/src/config<dot>lisp file
File, Lisp, cl-scrobbler/src/errors.lisp: The cl-scrobbler/src/errors<dot>lisp file
File, Lisp, cl-scrobbler/src/package.lisp: The cl-scrobbler/src/package<dot>lisp file
File, Lisp, cl-scrobbler/src/scrobble.lisp: The cl-scrobbler/src/scrobble<dot>lisp file
File, Lisp, cl-scrobbler/src/util.lisp: The cl-scrobbler/src/util<dot>lisp file

L
Lisp File, cl-scrobbler.asd: The cl-scrobbler<dot>asd file
Lisp File, cl-scrobbler/src/auth.lisp: The cl-scrobbler/src/auth<dot>lisp file
Lisp File, cl-scrobbler/src/cache.lisp: The cl-scrobbler/src/cache<dot>lisp file
Lisp File, cl-scrobbler/src/config.lisp: The cl-scrobbler/src/config<dot>lisp file
Lisp File, cl-scrobbler/src/errors.lisp: The cl-scrobbler/src/errors<dot>lisp file
Lisp File, cl-scrobbler/src/package.lisp: The cl-scrobbler/src/package<dot>lisp file
Lisp File, cl-scrobbler/src/scrobble.lisp: The cl-scrobbler/src/scrobble<dot>lisp file
Lisp File, cl-scrobbler/src/util.lisp: The cl-scrobbler/src/util<dot>lisp file

M
Module, cl-scrobbler/src: The cl-scrobbler/src module

Jump to:   C   F   L   M  

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

A.2 Functions

Jump to:   A   C   D   E   F   G   K   L   M   P   R   S   T   U   V   W  
Index Entry  Section

A
add-log-entry: Internal functions
add-to-cache: Internal functions
attempt-scrobble: Internal functions
authorize-scrobbling: Internal functions

C
cache-contents: Exported functions
config-file: Internal functions

D
defcall: Internal macros

E
error-message: Internal functions

F
frob-lastfm-name: Internal functions
frob-symbol: Internal functions
Function, add-log-entry: Internal functions
Function, add-to-cache: Internal functions
Function, attempt-scrobble: Internal functions
Function, authorize-scrobbling: Internal functions
Function, cache-contents: Exported functions
Function, config-file: Internal functions
Function, error-message: Internal functions
Function, frob-lastfm-name: Internal functions
Function, frob-symbol: Internal functions
Function, get-session: Internal functions
Function, get-session-key: Internal functions
Function, get-token: Internal functions
Function, ksymb: Internal functions
Function, lastfm-call: Internal functions
Function, make-param: Internal functions
Function, make-signature: Internal functions
Function, maybe-queue-scrobble: Exported functions
Function, md5sum: Internal functions
Function, mkstr: Internal functions
Function, persist-cache: Internal functions
Function, remove-from-cache: Internal functions
Function, request-user-auth: Internal functions
Function, restore-cache: Internal functions
Function, restore-settings: Internal functions
Function, save-settings: Internal functions
Function, scrobble: Internal functions
Function, scrobbler-init: Exported functions
Function, scrobbler-loop: Exported functions
Function, set-now-playing: Exported functions
Function, simplified-camel-case-to-lisp: Internal functions
Function, simplified-lisp-to-camel-case: Internal functions
Function, symb: Internal functions
Function, toggle-now-playing: Exported functions
Function, toggle-scrobbling: Exported functions
Function, unix-timestamp: Internal functions
Function, update-last-seek: Exported functions
Function, update-now-playing: Internal functions
Function, update-skipped: Exported functions
Function, update-song-info: Exported functions
Function, valid-scrobble-p: Internal functions

G
Generic Function, message: Internal generic functions
get-session: Internal functions
get-session-key: Internal functions
get-token: Internal functions

K
ksymb: Internal functions

L
lastfm-call: Internal functions

M
Macro, defcall: Internal macros
Macro, with-logging: Internal macros
make-param: Internal functions
make-signature: Internal functions
maybe-queue-scrobble: Exported functions
md5sum: Internal functions
message: Internal generic functions
message: Internal generic functions
Method, message: Internal generic functions
mkstr: Internal functions

P
persist-cache: Internal functions

R
remove-from-cache: Internal functions
request-user-auth: Internal functions
restore-cache: Internal functions
restore-settings: Internal functions

S
save-settings: Internal functions
scrobble: Internal functions
scrobbler-init: Exported functions
scrobbler-loop: Exported functions
set-now-playing: Exported functions
simplified-camel-case-to-lisp: Internal functions
simplified-lisp-to-camel-case: Internal functions
symb: Internal functions

T
toggle-now-playing: Exported functions
toggle-scrobbling: Exported functions

U
unix-timestamp: Internal functions
update-last-seek: Exported functions
update-now-playing: Internal functions
update-skipped: Exported functions
update-song-info: Exported functions

V
valid-scrobble-p: Internal functions

W
with-logging: Internal macros

Jump to:   A   C   D   E   F   G   K   L   M   P   R   S   T   U   V   W  

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

A.3 Variables

Jump to:   *  
M   S  
Index Entry  Section

*
*api-key*: Internal special variables
*api-secret*: Internal special variables
*api-url*: Internal special variables
*api-version*: Internal special variables
*config-dir*: Exported special variables
*error-codes*: Internal special variables
*last-seek*: Internal special variables
*now-playing-p*: Internal special variables
*scrobble-cache*: Internal special variables
*scrobble-count*: Exported special variables
*scrobble-p*: Internal special variables
*session-key*: Internal special variables
*skipped*: Internal special variables
*song-info*: Internal special variables
*song-info-fn*: Exported special variables
*song-time-fn*: Exported special variables

M
message: Internal conditions

S
Slot, message: Internal conditions
Special Variable, *api-key*: Internal special variables
Special Variable, *api-secret*: Internal special variables
Special Variable, *api-url*: Internal special variables
Special Variable, *api-version*: Internal special variables
Special Variable, *config-dir*: Exported special variables
Special Variable, *error-codes*: Internal special variables
Special Variable, *last-seek*: Internal special variables
Special Variable, *now-playing-p*: Internal special variables
Special Variable, *scrobble-cache*: Internal special variables
Special Variable, *scrobble-count*: Exported special variables
Special Variable, *scrobble-p*: Internal special variables
Special Variable, *session-key*: Internal special variables
Special Variable, *skipped*: Internal special variables
Special Variable, *song-info*: Internal special variables
Special Variable, *song-info-fn*: Exported special variables
Special Variable, *song-time-fn*: Exported special variables

Jump to:   *  
M   S  

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

A.4 Data types

Jump to:   C   L   P   S  
Index Entry  Section

C
cl-scrobbler: The cl-scrobbler system
cl-scrobbler: The cl-scrobbler package
Condition, lastfm-server-error: Internal conditions
Condition, scrobble-error: Internal conditions

L
lastfm-server-error: Internal conditions

P
Package, cl-scrobbler: The cl-scrobbler package

S
scrobble-error: Internal conditions
System, cl-scrobbler: The cl-scrobbler system

Jump to:   C   L   P   S