Quick Start

If you're just looking for how to use this program, read INSTALL and, if you want an MPD client, contrib/INSTALL.lastmp.

HOWTO Write Client Plugins for lastfmsubmitd

lastfmsubmitd is designed to handle the Last.fm protocol, so that every player plugin does not need to re-implement it. Player plugins that use lastfmsubmitd only need to determine when a song has been played and drop its information in lastfmsubmitd's spool directory. After doing so, the player plugin can forget about it -- If the network is down, or even if lastfmsubmitd is not running, the contents of the spool will be saved until they can be submitted.

To send song information to lastfmsubmitd, you can do one of the following:

• Fork and exec /usr/lib/lastfm/lastfmsubmit. lastfmsubmit fills a role similar to sendmail(1). It will take the song specified on the command line with --artist, --title, --length, and optionally --album and --mbid, and encode it in UTF-8 YAML. Then, it will write it to lastfmsubmitd's spool or stdout. The primary purpose of this program is to abstract character encoding and YAML document creation; all your player plugin needs to do is detect a song and invoke lastfmsubmit. Of course, you can also run it manually should something go wonky.

• Use the lastfm Python module. Example code::

  import time import lastfm

  get your song from somewhere...

  song = {'artist': 'New Order', 'title': 'Your Silent Face', 'album': 'Power, Corruption & Lies', 'mbid': '3a54b3b2-6037-4fc3-a7a0-ead924e55ea2', 'length': 359}

  cli = lastfm.client.Client('demo') cli.open_log()

  determine that your song has been played...

  song['time'] = time.gmtime()

  cli.log.info('Played song: %s' % lastfm.repr(song)) cli.submit(song)

  You can also supply a custom configuration, like this::

  cli = lastfm.client.Client('demo', lastfm.config.Config('/path/to/demo.conf'))

  Documentation for each of these functions can be read using pydoc.

• Write a file to /var/spool/lastfm yourself. Submission files contain simple data structures serialized as YAML_. You can use a YAML implementation such as Syck_, as long as it is UTF-8 clean. Alternatively, you can print the data yourself. Example data::

  ---

  artist: "The Jam" title: ""A" Bomb in Wardour Street" album: "All Mod Cons" length: 201 mbid: b7ec9e64-baa4-49bc-ad33-570919d01ba1 time: !timestamp 2006-03-23 13:42:25

  Make sure any non-ASCII characters are converted to UTF-8. If a string contains double-quotes, as above, they must be escaped with backslashes. Any literal backslashes must be escaped as well.

  If you have multiple submissions, you can write them all in one file. Each file in /var/spool/lastfm should be created with a unique name; mkstemp(3) is a good way to do this.

.. _YAML: http://yaml.org/ .. _Syck: http://whytheluckystiff.net/syck/

Examples

An example client for MPD called LastMP is included in the contrib directory; it uses the Python API. It is probably the most popular lastfmsubmitd client; the author, an MPD user, created lastfmsubmitd specifically so that he could write it.

Author and License

Copyright © 2005-2010 Decklin Foster [email protected].

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Because This is for Last.fm, After All

Thanks for the inspiration: David Holmes, Joy Electric, Minor Threat, Autechre, Wes Anderson et al, Boards of Canada, Pixies, Ted Leo, D+.