/thirdparty/liblastfm2/README

  1liblastfm
  2=========
  3liblastfm is a collection of libraries to help you integrate Last.fm services
  4into your rich desktop software. It is officially supported software developed
  5by Last.fm staff.
  6
  7Max Howell   http://twitter.com/mxcl
  8Jono Cole    http://twitter.com/jonocole
  9Doug Mansell http://twitter.com/dougma
 10
 11Fork it: http://github.com/mxcl/liblastfm
 12
 13
 14Dependencies
 15============
 16liblastfm dynamically links to:
 17
 18* Qt 4.4
 19  http://www.qtsoftware.com
 20* FFTW 3.2
 21  Compiled with single precision
 22  http://www.fftw.org
 23* Secret Rabbit code (aka libsamplerate)
 24  http://www.mega-nerd.com/SRC
 25
 26Additionally, to build you will need Ruby and GNU make (or Microsoft nmake).
 27
 28Mac OS X
 29--------
 30    sudo port selfupdate
 31    sudo port upgrade installed
 32    sudo port install libsamplerate fftw-3 qt4-mac-devel
 33
 34qt4-mac-devel will take a long time to build. So you may want to install the
 35Trolltech binary package instead.
 36
 37MacPorts carries liblastfm now, so you may have downloaded this package simply
 38to perform this next line:
 39
 40    sudo port install liblastfm
 41
 42Linux/*NIX
 43----------
 44Do something like this:
 45
 46    sudo apt-get install qt4-qmake pkg-config libsamplerate-dev libfftw3-dev ruby g++ libqt4-dev
 47
 48Additionally on Linux the configure process requires lsb_release. This is
 49usually already installed (correct me if I'm wrong).
 50
 51Please note, we have only tested on Linux, but we think it'll work on all
 52varieties of UNIX. If it doesn't, report the bug to mxcl on GitHub.
 53
 54Windows
 55-------
 56Install Ruby. Install Visual Studio 2005 or higher. Install Qt. Install the
 57Windows Server 2003 Platform SDK r2:
 58
 59http://www.microsoft.com/Downloads/details.aspx?FamilyID=484269e2-3b89-47e3-8eb7-1f2be6d7123a
 60
 61Set up your environment variables so all include paths and tools are
 62available.
 63
 64Build and install FFTW and Secret Rabbit Code.
 65
 66Open a plain Windows shell (Cygwin will work but we don't recommend it), and
 67see the next section.
 68
 69
 70Installing liblastfm
 71====================
 72    ruby configure --release --prefix /usr/local && make && sudo make install
 73
 74Packaging liblastfm
 75-------------------
 76DESTDIR is supported.
 77
 78liblastfm builds to two dynamic libraries (liblastfm.so and
 79liblastfm_fingerprint.so). liblastfm.so links only to Qt, but the
 80fingerprinting part has additional dependencies. So ideally, you would
 81distribute two packages.
 82
 83
 84Using liblastfm
 85===============
 86We have copied the API at http://last.fm/api onto C++, so like you find
 87artist.getInfo there you will find an lastfm::Artist::getInfo function in our
 88C++ API. lastfm is a namespace, Artist a class and getInfo a function.
 89
 90Thus the API is quite easy to learn. We suggest installing and checking the
 91include/lastfm/* directory to find out all capabilities.
 92
 93The demos directory shows some further basic usage including Audioscrobbling
 94and getting metadata for music via our fingerprinting technology.
 95
 96You need an API key from http://last.fm/api to use the webservice API.
 97
 98Your link line needs to include the following:
 99
100    -llastfm -lQtCore -lQtNetwork -lQtXml
101
102Radio
103-----
104Please set an identifiable UserAgent on your HTTP requests for the actual MP3s,
105in extreme cases we'll contact you directly and demand you do so :P
106
107HTTP & Networking
108-----------------
109You can specify your own QNetworkAccessManager derived class for liblastfm to
110use with lastfm::setNetworkAccessManager(). Our default is pretty good
111though, auto-determining proxy settings on Windows and OS X for instance.
112
113
114Using liblastfm_fingerprint
115===========================
116The liblastfm_fingerprint library does not decode audio files. We anticipate
117that Phonon will soon do that work for us. In the meantime, sample *Source
118files for MP3, Ogg Vorbis, FLAC, and AAC/MP4 are available in
119src/fingerprint/contrib. If you want to fingerprint files or get metadata
120suggestions, you either need to add the *Source files to your project, or
121implement your own.
122
123
124Development
125===========
126Public Headers
127--------------
1281. Header guards should be prefixed with LASTFM, eg. LASTFM_WS_REPLY_H
1292. #includes should be to the system path eg. #include <lastfm/Scrobbler>
1303. Don't make a header public unless it is absolutely required!
1314. To make the header public edit the headers.files line in the pro file
132
133Private Headers
134---------------
1351. For consistency and to make it more obvious it is a private header, don't
136   prefix the header guard with LASTFM
1372. #includes should be the full source tree path, eg.
138   #include "../core/UrlBuilder.h"