The cl-scrobbler Reference Manual

This is the cl-scrobbler Reference Manual, version 0.4, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 04:27:32 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 cl-scrobbler

A library for scrobbling to last.fm

Author

Brit Butler <>

License

BSD

Version

0.4

Dependencies
  • md5 (system).
  • flexi-streams (system).
  • drakma (system).
  • st-json (system).
  • cl-store (system).
  • arnesi (system).
Source

cl-scrobbler.asd.

Child Component

src (module).


3 Modules

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


3.1 cl-scrobbler/src

Source

cl-scrobbler.asd.

Parent Component

cl-scrobbler (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 cl-scrobbler/cl-scrobbler.asd

Source

cl-scrobbler.asd.

Parent Component

cl-scrobbler (system).

ASDF Systems

cl-scrobbler.


4.1.2 cl-scrobbler/src/package.lisp

Source

cl-scrobbler.asd.

Parent Component

src (module).

Packages

cl-scrobbler.


4.1.3 cl-scrobbler/src/config.lisp

Dependency

package.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.4 cl-scrobbler/src/cache.lisp

Dependency

config.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Public Interface

cache-contents (function).

Internals

4.1.5 cl-scrobbler/src/errors.lisp

Dependency

cache.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Internals

4.1.6 cl-scrobbler/src/util.lisp

Dependency

errors.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Internals

4.1.7 cl-scrobbler/src/auth.lisp

Dependency

util.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Internals

4.1.8 cl-scrobbler/src/scrobble.lisp

Dependency

auth.lisp (file).

Source

cl-scrobbler.asd.

Parent Component

src (module).

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 cl-scrobbler

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

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


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.

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.

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.

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.


6.1.2 Ordinary functions

Function: cache-contents ()

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

Package

cl-scrobbler.

Source

cache.lisp.

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.

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.

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.

Function: set-now-playing ()

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

Package

cl-scrobbler.

Source

scrobble.lisp.

Function: toggle-now-playing ()

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

Package

cl-scrobbler.

Source

scrobble.lisp.

Function: toggle-scrobbling ()

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

Package

cl-scrobbler.

Source

scrobble.lisp.

Function: update-last-seek ()

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

Package

cl-scrobbler.

Source

scrobble.lisp.

Function: update-skipped ()

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

Package

cl-scrobbler.

Source

scrobble.lisp.

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.


6.2 Internals


6.2.1 Special variables

Special Variable: *api-key*

A valid Last.fm API key.

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *api-secret*

A valid Last.fm API secret key.

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *api-url*

The URL for Last.fm API calls.

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *api-version*

The current Last.fm API version.

Package

cl-scrobbler.

Source

config.lisp.

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.

Special Variable: *last-seek*

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

Package

cl-scrobbler.

Source

scrobble.lisp.

Special Variable: *now-playing-p*

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

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *scrobble-cache*

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

Package

cl-scrobbler.

Source

cache.lisp.

Special Variable: *scrobble-p*

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

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *session-key*

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

Package

cl-scrobbler.

Source

config.lisp.

Special Variable: *skipped*

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

Package

cl-scrobbler.

Source

scrobble.lisp.

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.


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.

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.


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

Function: add-to-cache (scrobble)

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

Package

cl-scrobbler.

Source

cache.lisp.

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.

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.

Function: config-file (name)

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

Package

cl-scrobbler.

Source

util.lisp.

Function: error-message (errcode)

Retrieve the error message corresponding to the number ERRCODE.

Package

cl-scrobbler.

Source

errors.lisp.

Function: frob-lastfm-name (string)

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

Package

cl-scrobbler.

Source

util.lisp.

Function: frob-symbol (symb)

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

Package

cl-scrobbler.

Source

util.lisp.

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.

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.

Function: get-token ()

Get an Unauthorized Token for initiating an authenticated session.

Package

cl-scrobbler.

Source

auth.lisp.

Function: ksymb (&rest args)
Package

cl-scrobbler.

Source

util.lisp.

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.

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.

Function: make-signature (params)

Construct an API method signature from PARAMS.

Package

cl-scrobbler.

Source

util.lisp.

Function: md5sum (string)

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

Package

cl-scrobbler.

Source

util.lisp.

Function: mkstr (&rest args)
Package

cl-scrobbler.

Source

util.lisp.

Function: persist-cache ()

Persist the cache to disk.

Package

cl-scrobbler.

Source

cache.lisp.

Function: remove-from-cache ()

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

Package

cl-scrobbler.

Source

cache.lisp.

Function: request-user-auth (token)

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

Package

cl-scrobbler.

Source

auth.lisp.

Function: restore-cache ()

Restore the cache from disk.

Package

cl-scrobbler.

Source

cache.lisp.

Function: restore-settings ()

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

Package

cl-scrobbler.

Source

config.lisp.

Function: save-settings ()

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

Package

cl-scrobbler.

Source

config.lisp.

Function: scrobble (track timestamp artist sk)

Scrobble the track!

Package

cl-scrobbler.

Source

scrobble.lisp.

Function: simplified-camel-case-to-lisp (camel-string)

Lispify camelCase or CamelCase strings to camel-case.

Package

cl-scrobbler.

Source

util.lisp.

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.

Function: symb (&rest args)
Package

cl-scrobbler.

Source

util.lisp.

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.

Function: update-now-playing (track artist sk)

Update the Now Playing status on last.fm.

Package

cl-scrobbler.

Source

scrobble.lisp.

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.


6.2.4 Generic functions

Generic Reader: message (condition)
Package

cl-scrobbler.

Methods
Reader Method: message ((condition lastfm-server-error))
Source

errors.lisp.

Target Slot

message.


6.2.5 Conditions

Condition: lastfm-server-error
Package

cl-scrobbler.

Source

errors.lisp.

Direct superclasses

error.

Direct methods

message.

Direct slots
Slot: message
Initargs

:message

Readers

message.

Writers

This slot is read-only.

Condition: scrobble-error
Package

cl-scrobbler.

Source

errors.lisp.

Direct superclasses

error.


Appendix A Indexes


A.1 Concepts


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: Private ordinary functions
add-to-cache: Private ordinary functions
attempt-scrobble: Private ordinary functions
authorize-scrobbling: Private ordinary functions

C
cache-contents: Public ordinary functions
config-file: Private ordinary functions

D
defcall: Private macros

E
error-message: Private ordinary functions

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

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

K
ksymb: Private ordinary functions

L
lastfm-call: Private ordinary functions

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

P
persist-cache: Private ordinary functions

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

S
save-settings: Private ordinary functions
scrobble: Private ordinary functions
scrobbler-init: Public ordinary functions
scrobbler-loop: Public ordinary functions
set-now-playing: Public ordinary functions
simplified-camel-case-to-lisp: Private ordinary functions
simplified-lisp-to-camel-case: Private ordinary functions
symb: Private ordinary functions

T
toggle-now-playing: Public ordinary functions
toggle-scrobbling: Public ordinary functions

U
unix-timestamp: Private ordinary functions
update-last-seek: Public ordinary functions
update-now-playing: Private ordinary functions
update-skipped: Public ordinary functions
update-song-info: Public ordinary functions

V
valid-scrobble-p: Private ordinary functions

W
with-logging: Private macros


A.3 Variables

Jump to:   *  
M   S  
Index Entry  Section

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

M
message: Private conditions

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


A.4 Data types