Module scrobbler
[show private | hide private]
[frames | no frames]

Module scrobbler

A pure-python library to assist sending data to AudioScrobbler (the LastFM backend)

This library tries to keep as much of the protocol hidden from the end-user. Unfortunately not all can be hidden. But where possible, I try to use sensible default in the parameters, so that even if you do not specify them it should still somehow work.
Exceptions
AuthError Raised on authencitation errors
BackendError Raised if the AS backend does something funny
PostError Raised if something goes wrong when posting data to AS
ProtocolError Raised on general Protocol errors
SessionError Raised when problems with the session exist

Function Summary
  flush()
Sends the cached songs to AS.
  login(user, password, client)
Authencitate with AS (The Handshake)
  now_playing(artist, track, album, length, trackno, mbid)
Tells audioscrobbler what is currently running in your player.
  submit(artist, track, time, source, rating, length, album, trackno, mbid, autoflush)
Append a song to the submission cache.

Function Details

flush()

Sends the cached songs to AS.

login(user, password, client=('tst', '1.0'))

Authencitate with AS (The Handshake)
Parameters:
user - The username
password - The password
client - Client information (see http://www.audioscrobbler.net/development/protocol/ for more info)
           (type=Tuple: (client-id, client-version))

now_playing(artist, track, album='', length='', trackno='', mbid='')

Tells audioscrobbler what is currently running in your player. This won't affect the user-profile on last.fm. To do submissions, use the "submit" method
Parameters:
artist - The artist name
track - The track name
album - The album name
length - The song length in seconds
trackno - The track number
mbid - The MusicBrainz Track ID
Returns:
True on success, False on failure

submit(artist, track, time, source='P', rating='', length='', album='', trackno='', mbid='', autoflush=False)

Append a song to the submission cache. Use 'flush()' to send the cache to AS. You can also set "autoflush" to True.

From the Audioscrobbler protocol docs: ---------------------------------------------------------------------------

The client should monitor the user's interaction with the music playing service to whatever extent the service allows. In order to qualify for submission all of the following criteria must be met:
  1. The track must be submitted once it has finished playing. Whether it has finished playing naturally or has been manually stopped by the user is irrelevant.
  2. The track must have been played for a duration of at least 240 seconds or half the track's total length, whichever comes first. Skipping or pausing the track is irrelevant as long as the appropriate amount has been played.
  3. The total playback time for the track must be more than 30 seconds. Do not submit tracks shorter than this.
  4. Unless the client has been specially configured, it should not attempt to interpret filename information to obtain metadata instead of tags (ID3, etc).
Parameters:
artist - Artist name
track - Track name
time - Time the track *started* playing in the UTC timezone (see datetime.utcnow()). Example:
>>> time = int(time.mktime(datetime.utcnow()))
source - Source of the track. One of:
  • 'P': Chosen by the user
  • 'R': Non-personalised broadcast (e.g. Shoutcast, BBC Radio 1)
  • 'E': Personalised recommendation except Last.fm (e.g. Pandora, Launchcast)
  • 'L': Last.fm (any mode). In this case, the 5-digit Last.fm recommendation key must be appended to this source ID to prove the validity of the submission (for example, "L1b48a").
  • 'U': Source unknown
rating - The rating of the song. One of:
  • 'L': Love (on any mode if the user has manually loved the track)
  • 'B': Ban (only if source='L')
  • 'S': Skip (only if source='L')
  • '': Not applicable
length - The song length in seconds
album - The album name
trackno - The track number
mbid - MusicBrainz Track ID
autoflush - Automatically flush the cache to AS?

Generated by Epydoc 2.1 on Sun Oct 14 20:14:43 2007 http://epydoc.sf.net