Previous  Up  Next

Module Lastfm.Audioscrobbler

module Audioscrobbler: Lastfm_generic.Audioscrobbler_t

Implementation of Audioscrobbler using the ocamlnet Http request.

Audioscrobbler is the submission protocol as described at

http://www.audioscrobbler.net/development/protocol/

Types

type source =
| User
| Broadcast
| Recommendation
| Lastfm
| Unknown

source of the track

type rating =
| Love
| Ban
| Skip

possible rating for the track

type action =
| NowPlaying
| Submit

type of action

type song = {
   artist : string;
   track : string;
   time : float option;
   source : source option;
   rating : rating option;
   length : float option;
   album : string option;
   trackauth : string option;
   tracknumber : int option;
   musicbrainzid : string option;
}

song submission type

type error =
| Http of string
| Banned
| Badauth
| Badtime
| Failed of string
| UnknownError of string
| Success
| Internal of string
| BadData of string

various errors

exception Error of error
val string_of_error : error -> string

Get meaning of Error e

val base_port : int Stdlib.ref

Base port. Default: 80

val base_host : string Stdlib.ref

Base host. Default: "post.audioscrobbler.com"

Common API

Functions common to both basic and advanced APIs

val get_song : ?time:float ->
       ?source:source ->
       ?rating:rating ->
       ?length:float ->
       ?album:string ->
       ?tracknumber:int ->
       ?musicbrainzid:string ->
       ?trackauth:string ->
       artist:string -> track:string -> unit -> song

get_song create a song record based on given values.

Optional records can be ommited there.

val check_song : song ->
       action -> unit

Check wether required song informations are supplied for given action.

Raises Error (BadData reason) if invalid data is given.

See protocol details there:

http://www.audioscrobbler.net/development/protocol/

Basic API

Using this API, all requests are done in one single step

val do_np : ?timeout:float ->
       ?host:string * int ->
       Lastfm_generic.client ->
       Lastfm_generic.login -> song -> unit

do_np client login song execute a nowplaying request with authentification

Optional host parameter is a pair "host",port to override the global values.

val do_submit : ?timeout:float ->
       ?host:string * int ->
       Lastfm_generic.client ->
       Lastfm_generic.login ->
       song list ->
       (error * song)
       list

do_submit client login songs execute a nowplaying request with authentification.

This functions returns a list songs for which supplied informations were incomplete, with corresponding exception (see check_song source)

Advanced API

This API is for advanced usages.

You may use it this way:

  1. handshake : initiate session
  2. np/submit: execute request

The module will cache session informations and avoid redundant requests, so you might always call handshake.

However, if a np or submit fails, it can be because the session has expired on server side, but the module cache still refered to it. So you might clear this session id, and try another handshake+submit/np.

Check do_no and do_submit for examples.

val handshake : ?timeout:float ->
       ?host:string * int -> Lastfm_generic.client -> Lastfm_generic.login -> string

handshake client login open session, returns session ID

Optional host parameter is a pair "host",port to override the global values.

val np : ?timeout:float -> string -> song -> unit

np sessionID track execute a nowplaying request

val submit : ?timeout:float ->
       string ->
       song list ->
       (error * song)
       list

submit sessionID tracks execute a submit request

This functions returns a list songs for which supplied informations were incomplete, with corresponding exception (see check_song)