liblastfm
=========
liblastfm is a collection of libraries to help you integrate Last.fm services
into your rich desktop software. It is officially supported software developed
by Last.fm staff.

Max Howell   http://twitter.com/mxcl
Jono Cole    http://twitter.com/jonocole
Doug Mansell http://twitter.com/dougma

Fork it: http://github.com/mxcl/liblastfm


Dependencies
============
The build process requires ruby, Qt>=4.4 and GNU make (or MS nmake).

Mac OS X
--------
    sudo port selfupdate
    sudo port upgrade installed
    sudo port install libsamplerate fftw-3 qt4-mac-devel

qt4-mac-devel will take a long time to build. So you may want to install the
Trolltech binary package instead.

Linux
-----
For Ubuntu 9.04 (some are build deps, eg. Ruby is used during configure):

    sudo apt-get install qt4-qmake pkg-config libsamplerate-dev libfftw3-dev ruby g++ libqt4-dev

The configure process also requires lsb_release on Linux. This is usually
already installed (correct me if I'm wrong).

Windows
-------
Best of luck to you. You'll need Ruby, GNU Make and the Windows Server 2003
Platform SDK r2:

http://www.microsoft.com/Downloads/details.aspx?FamilyID=484269e2-3b89-47e3-8eb7-1f2be6d7123a&displaylang=en

liblastfm should build under both cygwin and regular Windows shell.


Installing liblastfm
====================
    ./configure --release --prefix /usr/local && make && sudo make install

Packaging liblastfm
-------------------
DESTDIR is supported.

The library is split into liblastfm and liblastfm_fingerprint. The
fingerprinting part is separate as it links to libfftw3. So if you want to
package it separately then you can. Sadly because there is simply no good
configuration system in the world, you still have to build both…


Using liblastfm
===============
We have copied the API at http://last.fm/api onto C++, so like you find
artist.getInfo there you will find an lastfm::Artist::getInfo function in our
C++ API. lastfm is a namespace, Artist a class and getInfo a function.

Thus the API is quite easy to learn. We suggest installing and checking the
include/lastfm/* directory to find out all capabilities.

The demos directory shows some further basic usage including Audioscrobbling
and getting metadata for music via our fingerprinting technology.

You need an API key from http://last.fm/api to use the webservice API.

Your link line needs to include the following:

    -llastfm -lQtCore -lQtNetwork -lQtXml

Radio
-----
Please set an identifiable UserAgent on your HTTP requests for the actual MP3s,
in extreme cases we'll contact you directly and demand you do so :P

HTTP & Networking
-----------------
You can specify your own QNetworkAccessManager derived class for liblastfm to
use with lastfm::setNetworkAccessManager(). Our default is pretty good
though, auto-determining proxy settings on Windows and OS X for instance.


Using liblastfm_fingerprint
===========================
The liblastfm_fingerprint library does not decode audio files. We anticipate
that Phonon will soon do that work for us. In the meantime, sample *Source
files for MP3, Ogg Vorbis, FLAC, and AAC/MP4 are available in
src/fingerprint/contrib. If you want to fingerprint files or get metadata
suggestions, you either need to add the *Source files to your project, or
implement your own.


Development
===========
Public Headers
--------------
1. Header guards should be prefixed with LASTFM, eg. LASTFM_WS_REPLY_H
2. #includes should be to the system path eg. #include <lastfm/Scrobbler>
3. Don't make a header public unless it is absolutely required!
4. To make the header public edit the headers.files line in the pro file

Private Headers
---------------
1. For consistency and to make it more obvious it is a private header, don't
   prefix the header guard with LASTFM
2. #includes should be the full source tree path, eg.
   #include "../core/UrlBuilder.h"


Release History
===============
0.2 -- 20th April 2009
