README

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 <decklin@red-bean.com>.

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+.