File: lastfm.mli

package info (click to toggle)
ocaml-lastfm 0.1.2-1
  • links: PTS, VCS
  • area: main
  • in suites: lenny
  • size: 364 kB
  • ctags: 59
  • sloc: ml: 619; makefile: 119; sh: 3
file content (241 lines) | stat: -rw-r--r-- 7,504 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
(*****************************************************************************

  Liquidsoap, a programmable audio stream generator.
  Copyright 2003-2007 Savonet team

  This program is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  This program is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details, fully stated in the COPYING
  file at the root of the liquidsoap distribution.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

 *****************************************************************************)

(** API to various lastfm protocols *)

(** Records for login and client *)
type client = { client : string ; version : string }
type login = { user : string ; password : string }

module Audioscrobbler :
sig

  (** Audioscrobbler is the submission protocol as described at
    
     {{:http://www.audioscrobbler.net/development/protocol/}http://www.audioscrobbler.net/development/protocol/} *)

  (** {2 Types} *)

  (** source of the track *)
  type source = User | Broadcast | Recommendation | Lastfm | Unknown

  (** possible rating for the track *)
  type rating = Love | Ban | Skip

  (** type of action *)
  type action = NowPlaying | Submit

  (** song submission type *)
  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 }

  (** various errors *)
  type error = Http of string | Banned | Badauth | Badtime
              | Failed of string | UnknownError of string | Success
              | Internal of string | BadData of string
  exception Error of error
  
  (** Get meaning of Error e *)
  val string_of_error : error -> string

  (** {2 Common API}

     Functions common to both basic and advanced APIs *)

    (** [get_song] 
        create a song record based on given values.

        Optional records can be ommited there. *)
    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

    (** 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/}http://www.audioscrobbler.net/development/protocol/}
     *)
    val check_song : song -> action -> unit
  
  (** {2 Basic API} 
     
     Using this API, all requests are done in one single step *)
  
  (** [do_np client login song]
     execute a nowplaying request 
     with authentification *)
  val do_np : client -> login -> song -> unit

  (** [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) *)
  val do_submit : client -> login -> song list -> (error * song) list

  (** {2 Advanced API} 
     
     This API is for advanced usages.
     
     You may use it this way:
     {ol {- handshake : initiate session }
      {- 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. *)

  (** [handshake client login] 
     open session, returns session ID *)
  val handshake : client -> login -> string

  (** [np sessionID track]
     execute a nowplaying request *)
   val np : string -> song -> unit

  (** [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) *)
   val submit : string -> song list -> (error * song) list

end

module Radio : 
sig

(** API for using lastfm radios 

    No protocol documentation avaible for now... *) 

  (** {2 Types} *)

  (** Type for track datas 
   
    A track is a list of "field","value" metadatas and an uri *)
  type track = (string * string) list * string
  
  (** Various errors *)
  type error = Http of string | Auth of string | Adjust of string*string | Playlist | Empty
  exception Error of error
  
  (** Get meaning of Error e *)
  val string_of_error : error -> string

  (** {2 Basic API} *)
  
  (** [get uri] performs whole process and
      outputs a list of metadatas,uri
      from given lastfm uri.
      
      This function cannot handle well
      multiple anonymous requests.
      
      If you plan to play simultaneously 
      several anonymous radios, you better 
      use the advanced API to keep track 
      of every opened session. *)
  val get : string -> track list

  (** {2 Advanced API} 

     Using this API you shall call: 
    {ol {- parse: get required parts of the uri}
    {- init: initiate a session}
    {- adjust: adjust station } }
    Then you can use any of the following:
    {ul {- playlist: return the raw xml content of the playlist}
    {- tracks : returns the parsed playlist.}}
    After each of those calls, you shall use *only* one
    of the songs from the playlist.
  
    The module will cache session informations and avoid redundant
    requests, so you might always call init and adjust.

    If you call [playlist], and anything went bad, 
    you have to call [clear] to remove cached data 
    about this session. 
    
    In any case you may also give another try, 
    in case of inconsistent cached session data. 
    See [get] source for details *)

  (** [parse uri] parse the given lastfm:// uri
    *
    * returns login option,station,options *)
  val parse : string -> (login option)*string*(string option)
  
  (** [init login] initiate lastfm session
    *
    * Returns the session id *)
  val init : login option -> string
  
  (** [adjust id station] adjusts lastfm station 
    * for given session ID 
    *
    * Returns a list of (variable,value) as returned
    * by the server. Contains settings for adjusted
    * radio.
    *)
  val adjust : string -> string -> (string*string) list

  (** [playlist id] returns the raw xml content of the playlist *)
  val playlist : string -> string option -> string

  (** [tracks id] 
    * returns a list of metadatas,uri  *)
  val tracks : string -> string option -> track list
  
  (** [clear id] closes and clear all 
    * informations about the given session ID *)
  val clear : string -> unit

end