Table of Contents
-----------------

 1. Introduction
 2. Dependencies
 3. Bugs
 4. Translations
 5. Covers
 6. Advanced Config Items
 7. CUE Files
 8. Streams
 9. MultiMedia Keys
10. Dynamic Helper Script - Local Mode
11. Dynamic Helper Script - Server Mode
12. Source Code
13. Debug Logging
14. Credits
15. Windows



1. Introduction
===============

Cantata is a graphical client for MPD. It contains the following features:

 1. Support for Qt4, Qt5, Windows, and KDE builds.
 2. Multiple MPD collections.
 3. Highly customisable layout.
 4. Songs grouped by album in play queue.
 5. Context view to show artist, album, and song information of current track.
 6. Simple tag editor.
 7. File organizer - use tags to organize files and folders.
 8. Ability to calculate ReplyGain tags. (Linux only, and if relevant libraries
    installed)
 9. Dynamic playlists.
10. Online services; Jamendo, Magnatune, SoundCloud, and Podcasts.
11. Radio stream support - with the ability to search for streams via TuneIn or
    ShoutCast.
12. USB-Mass-Storage and MTP device support. (Linux only, and if relevant
    libraries installed)
13. Audio CD ripping and playback. (Linux only, and if relevant libraries
    installed)
14. Playback of non-MPD songs - via simple in-built HTTP server if connected
    to MPD via a standard socket, otherwise filepath is sent to MPD.
15. MPRISv2 DBUS interface.
16. Support for KDE global shortcuts (KDE builds), GNOME media keys
    (Linux only), and standard media keys (via Qxt)
17. Ubuntu/ambiance theme integration - including dragging of window via
    toolbar.

Cantata started off as a fork of QtMPC, mainly to provide better KDE
integration - by using KDE libraries/classes wherever possible. However, the
code (and user interface) is now *very* different to that of QtMPC, and both
KDE and Qt (Linux) builds have the same feature set.

Unlike most other MPD clients, Cantata caches a copy of the MPD music library.
This is so that it can create a proper hierarchy of artists and albums (where
Cantata will use the AlbumArtist tag if found, otherwise it will fallback to
the Artist tag), to provide album counts, tracks counts, etc in the browser
views and tooltips, and also to help with copying songs to/from devices.

This cache is updated only when MPD indicates that its version of the collection
is different to Cantata's. If you press the 'Refresh Database' button in either
the artist, albums, folders, or playlists views, then this cache is deleted and
recreated with the response from MPD.

By default, Cantata will use the "listallinfo" command to retrieve the music
collection. However, it has been noted that MPD 0.18 requires more memory for
the collection details (due to MPD now reading more information), this may
cause the "listallinfo" command to fail. If it does, Cantata (as of v1.3.0)
will fallback to recursively calling "lsinfo" for each MPD folder.


2. Dependencies
===============

Cantata requires the following Qt libraries:

1. QtCore
2. QtGui
3. QtNetwork
4. QtXml
5. QtDBus (Only for Linux builds)
6. QtWidgets (Qt5 builds - where widgets are now separated from QtGui)

Cantata may also use the following optional libraries:

1. KDElibs4
2. TagLib - Tag edit dialog, replaygain, track organizer, and UMS device
            support.
3. LibMTP - MTP devices.
4. FFMPEG (libavcodec) - ReplayGain detection code.
5. SpeexDSP - ReplayGain detection code.
6. MPG123 - ReplayGain detection code.
7. CDParanoia - Read/rip Audio CDs.
8. CDDB - either this or MusicBrainz5 required for Audio CDs
9. MusicBrainz5 - either this or CDDB required for Audio CDs


3. Bugs
=======

Before reporting bugs, please check that this is not an MPD related issue with
your system - e.g. please try recreating the issue with another MPD client,
such as MPDroid, GMPC, etc.

To report bugs please visit http://code.google.com/p/cantata

When reporting a bug, please mention the Cantata version number, the Cantata
build type (Linux/KDE, Linux/Qt, Windows), any cmake options you specified
(other than the defaults listed at the top of the INSTALL file), and the
version of MPD you are using.

Please DO NOT attach images to the bug page - as the attachment quota is almost
full. Instead, please provide links to any relevant screenshots.


4. Translations
===============

Becasue Cantata started out as a KDE4 application, the translation files are
based upon KDE's i18n framework - these are located within the 'po' folder.

Translations for Qt-only builds are created from the KDE translations using
'lconvert'. To work-around issues with plural translations, Qt builds will
contain extra strings to handle plural forms.

e.g.

    KDE will have:
        msgid "1 Track"
        msgid_plural "%1 Tracks"
        msgstr[0] ""
        msgstr[1] ""

    Qt will have:
        msgid "1 Track"
        msgstr ""

        msgid "%1 Tracks"
        msgstr ""

In the code, cantata will use "%1 Tracks" for any count other than 1. If the
language you are translating into has more plural forms (i.e. the above two
strings are not sufficient), then please translate both into the form
"Tracks: N" - e.g.

    Qt would now have:
        msgid "1 Track"
        msgstr "Tracks: 1"

        msgid "%1 Tracks"
        msgstr "Tracks: %1"


Creating a new translation
--------------------------

To generate a new translation for Cantata, please just copy cantata.pot (in the
po folder) to whatever letter code your language uses (e.g. es.po for Spanish).
Then edit this new file to add the translations.

Please DO NOT use any tools to manually generate the translations from
Cantata's source code, as this will probably not work. This is due to Cantata
using the KDE framework for translations, and then generating the Qt-only ones
from this.

In the po folder there is a script named generate.sh, this is used to extract
translatable strings and update current translations.


5. Covers
=========

When displaying covers, Cantata will load album covers in the following order:

...if configured to 'Cache scaled covers', Cantata will check its scaled-covers
   cache folder (~/.cache/cantata/covers-scaled/SIZE) for:

 1. ${albumArtist}/${album}.jpg

...if MPD folder exists, is not specified as a http URL, and is readable, then
   cantata will look for the following within the folder containing the song:

 2. ${configuredName}.jpg - if set
 3. ${configuredName}.png - if set
 4. cover.jpg
 5. cover.png
 6. AlbumArt.jpg
 7. AlbumArt.png
 8. folder.jpg
 9. folder.png
10. ${file}.jpg - e.g. "01 Wibble.mp3" -> "01 Wibble.jpg"
11. ${file}.png
12. ${albumArtist} - ${album}.jpg
13. ${albumArtist} - ${album}.png
14. ${album}.jpg
15. ${album}.png
16. Image embedded within current song's tags.
17. ANY other jpg, or png

...then Cantata will check its cache folder (~/.cache/cantata/covers), for :

18. ${albumArtist}/${album}.jpg
19. ${albumArtist}/${album}.png

...if compiled for Linux

20. Matching Amarok cover
21. Matching Clementine cover

...if the MPD folder was specified as a http URL

22. ${url}/${dirFromFile}/cover.jpg
    - or ${url}/${dirFromFile}/${configuredName}.jpg (if set)
23. ${url}/${dirFromFile}/cover.png
    - or ${url}/${dirFromFile}/${configuredName}.png (if set)

...lastly, if user has enabled downloading via last.fm

24. Query last.fm using ${albumArtist} and ${album}. Cantata will attempt to
    download the image specified with the "extralarge" size.

Downloaded images will be saved as ${configuredName}.jpg/png (if set), or
cover.jpg/png, within the song folder if possible. If not, then they will be
saved in Cantata's cache folder.

If configured to 'Cache scaled covers', then the resized cover (as displayed)
will be saved as a JPG within covers-scaled.


For artist images:

...if configured to 'Cache scaled covers', Cantata will check its scaled-covers
   cache folder (~/.cache/cantata/covers-scaled/SIZE) for:

 1. ${albumArtist}.jpg

...if MPD folder exists, is not specified as a http URL, and is readable, then
   cantata will look for the following within the folder containing the song:

 2. ${basicArtist}.jpg
 3. ${basicArtist}.png
 4. artist.jpg
 5. artist.png

...the above will be repeated for the parent folder

...if song is from a Various Artists album, or file is a non-MPD file, then
   cantata will look for the following within the MPD root folder:

 6. ${basicArtist}/${basicArtist}.jpg
 7. ${basicArtist}/${basicArtist}.png
 8. ${basicArtist}/artist.jpg
 9. ${basicArtist}/artist.png

...then Cantata will check its cache folder (~/.cache/cantata/covers), for :

10. ${albumArtist}.jpg
11. ${albumArtist}.png

...if the MPD folder was specified as a http URL

12. ${url}/${dirFromFile}/artist.jpg
13. ${url}/${dirFromFile}/artist.png
 
...the above will be repeated for the parent folder

...lastly, if user has enabled downloading via last.fm

14. Query last.fm using ${albumArtist}. Cantata will attempt to download the
    image specified with the "extralarge" size.

Downloaded images will be saved as artist.jpg/png, within the artist folder
if the folder hierarchy is 2 levels (artist/album/) and the user has write
permissions. If not, then they will be saved in Cantata's cache folder.

If configured to 'Cache scaled covers', then the resized cover (as displayed) 
will be saved as a JPG within covers-scaled.


For context view backdrops:

...if MPD folder exists, is not specified as a http URL, and is readable, OR
   the song's filename starts with '/', then cantata will look for the
   following within the folder containing the song:

 1. ${currentArtist}-backdrop.jpg
 2. ${currentArtist}-backdrop.png
 3. backdrop.jpg
 4. backdrop.png

...the above will be repeated for the parent folder

...if song is from a Various Artists album, or file is a non-MPD file, then
   cantata will look for the following within the MPD root folder:

 5. ${currentArtist}/${currentArtist}-backdrop.jpg
 6. ${currentArtist}/${currentArtist}-backdrop.png
 7. ${currentArtist}/backdrop.jpg
 8. ${currentArtist}/backdrop.png

...then Cantata will check its cache folder (~/.cache/cantata/backdrops), for :

 9. ${currentArtist}.jpg

...internet services:

10. MusizBrainz is queried for an artist ID. If returned, this artist ID is used
    to locate a cover from fanart.tv
11. Download image from discogs

...lastly:

12. If all the above fails, a backdrop is created from all the album covers
    featuring the artist.

Downloaded images will be saved as backdrop.jpg, within the artist folder
if the current song is not from a Various Artists album, the file is from MPD,
the folder hierarchy is 2 levels (artist/album/), and the user has write
permissions. If not, then they will be saved in Cantata's cache folder.


6. Advanced Config Items
========================

Cantata contains a few advanced config items, for which there is currently no
graphical way to control the setting. For these, you will need to edit
Cantata's config by hand - whilst Cantata is NOT running!

Under Linux, the Cantata config file will be:
    Qt builds:  ~/.config/cantata/cantata.conf  ( Current User )
                /etc/xdg/cantata.conf           ( All Users    )
    KDE builds: ~/.kde/share/config/cantatarc   ( Current User )
                /etc/kde4/cantatarc             ( All Users    )

The following config items should be added to the "[General]" section.

iconTheme=<Icon theme name>
    For Qt-only Linux builds, this allows you to force cantata to use the
    configured icon theme. This config is empty by default, and Cantata uses
    the system configured icon theme.
    
maxCoverFindPerIteration=<Integer>
    Controls the maximum number of covers that will attempted to be located per
    UI event loop iteration. This is set to 5 by default. Increasing this will
    cause more covers to be loaded in the main UI thread - which will speed up
    loading, but might make the UI appear to block. Reducing this should reduce
    lag when scrolling the Albums view. (Values 0..20 are acceptable)

maxCoverUpdatePerIteration=<Integer>
    Covers the are not located and loaded in the UI thread, will be loaded in a
    background thread. These then need to be sent to the UI thread to be
    displayed. This config controls the number of covers that are sent in one
    batch. The default is again 5. (Values 1..20 are acceptable)

cueFileCodecs=<Comma separated list of codecs>
    List of extra text codecs to try when loading CUE files. UTF-8 and System
    default are tried first, and then the entries from this config are tried.
    My Qt4.8 has the following codecs available:

    GBK, CP936, MS936, windows-936, System, UTF-8, ISO-8859-1, latin1, CP819,
    IBM819, iso-ir-100, csISOLatin1, ISO-8859-15, latin9, UTF-32LE, UTF-32BE,
    UTF-32, UTF-16LE, UTF-16BE, UTF-16, mulelao-1, roman8, hp-roman8,
    csHPRoman8, TIS-620, ISO, WINSAMI2, WS2, Apple, macintosh, MacRoman,
    windows-1258, CP1258, windows-1257, CP1257, windows-1256, CP1256,
    windows-1255, CP1255, windows-1254, CP1254, windows-1253, CP1253,
    windows-1252, CP1252, windows-1251, CP1251, windows-1250, CP1250, IBM866,
    CP866, csIBM866, IBM874, CP874, IBM850, CP850, csPC850Multilingual,
    ISO-8859-16, iso-ir-226, latin10, ISO-8859-14, iso-ir-199, latin8,
    iso-celtic, ISO-8859-13, ISO-8859-10, iso-ir-157, latin6, ISO-8859-10:1992,
    csISOLatin6, ISO-8859-9, iso-ir-148, latin5, csISOLatin5, ISO-8859-8, ISO,
    iso-ir-138, hebrew, csISOLatinHebrew, ISO-8859-7, ECMA-118, greek,
    iso-ir-126, csISOLatinGreek, ISO-8859-6, ISO-8859-6-I, ECMA-114, ASMO-708,
    arabic, iso-ir-127, csISOLatinArabic, ISO-8859-5, cyrillic, iso-ir-144,
    csISOLatinCyrillic, ISO-8859-4, latin4, iso-ir-110, csISOLatin4, ISO-8859-3,
    latin3, iso-ir-109, csISOLatin3, ISO-8859-2, latin2, iso-ir-101,
    csISOLatin2, KOI8-U, KOI8-RU, KOI8-R, csKOI8R, Iscii-Mlm, Iscii-Knd,
    Iscii-Tlg, Iscii-Tml, Iscii-Ori, Iscii-Gjr, Iscii-Pnj, Iscii-Bng, Iscii-Dev,
    TSCII, GB18030, GB2312, gb2312.1980-0, gbk-0, EUC-JP, ISO-2022-JP,
    Shift_JIS, jisx0201*-0, jisx0208*-0, JIS7, SJIS, MS_Kanji, EUC-KR,
    ksc5601.1987-0, cp949, Big5, Big5-HKSCS, big5-0, big5hkscs-0, Big5-ETen,
    CP950

networkAccessEnabled=<Bool - true/false>
    Configure whether Cantata should be allowed to make networks requests - for
    accessing covers, etc. By default this is set to true.

volumeStep=<Integer>
    Volume % increments. Used when mouse wheel is activated over volume control.
    Default is 5. (Values 1..20 are acceptable)

undoSteps=<Integer>
    Control maximum number of playqueue undo/redo steps. Set to 0 to disable
    undo/redo.
    Default is 10. (Values 0..20 are acceptable)

mpdPoll=<Integer>
    Specified in seconds, this controls how often Cantata should poll MPD to
    determine its current state whilst playing. Set to 0 to disable polling,
    and rely on MPD's IDLE mechanism to determine MPD state changes.
    Default is 0 (no polling). (Values 0..60 are acceptable)

mpdListSize=<Integer>
    This config controls the maximum number of files sent in 1 chunk of an
    "add" command when adding files to the playqueue.
    Default is 10000. (Values 100..65535 are acceptable)

alwaysUseHttp=<Boolean>
    Set to 'true' to always serve non-MPD files via HTTP server. If set to
    'false', then Cantata will only use its internal HTTP server for songs
    from media devices, or when connected to MPD via a standard socket.
    Default is false.

alwaysUseLsInfo=<Boolean>
    By default, Cantata uses MPD's listallinfo command to retrieve the whole
    music collection. This can fail (especially with MPD 0.18.x which needs
    more memory), and if it does Cantata will fall back to calling
    "lsinfo <dir>" for each directory. Setting this config item to true will
    cause Cantata to always use this alternative method.
    Default is false.

e.g.
[General]
iconTheme=oxygen
maxCoverFindPerIteration=5
maxCoverUpdatePerIteration=5
cueFileCodecs=GBK, big5-0
networkAccessEnabled=false
volumeStep=2
undoSteps=20
mpdPoll=true
mpdListSize=5000
alwaysUseHttp=true
alwaysUseLsInfo=true


7. CUE Files
============

If Cantata is running with MPD>=0.17, then it will attempt to parse the contents
of CUE files. The CUE file will be parsed to ascertain the album and track
details. The track durations for all bar the last should be accurate, and
Cantata will attempt to determine the duration of the last track - but this
might not be 100% accurate.

If the CUE file references an audio file that does not exist in the MPD music
folder, then the CUE file contents will NOT be used.

There is no reliable way for Cantata to ascertain the text encoding that a CUE
file uses - so, for portability, it would be best if your CUE files used UTF-8
encoding. When loading a CUE file, Cantata will attempt to load the file as if
it was UTF-8 encoded, if this fails it will try with the "System" codec. You may
add to this list of encodings to try by using the 'cueFileCodecs' config item
(as detailed in section 6 above). If Cantata fails with all configured
encodings, then it will 'peek' at the 1st 1k bytes, and ask Qt to see if it can
determine the encoding - and fallback to UTF-8 otherwise. (This peeking and
fallback was how Cantata behaved in pre 1.2 versions - and is how Clementine
behaves (where Cantata's CUE file support originates from.))

NOTE: If Cantata cannot access the CUE file (as MPD is running on a remote host,
or you have not configured the music folder correctly, etc.) then Cantata will
add the CUE File to the album's track listing.


8. Streams
==========

Cantata contains a list of in-built stream categories, or providers. To import
new stream categories into Cantata, files need to be GZip compressed tarballs
of the following format.

  Filename: CATEGORY_NAME.streams  (e.g. German Radio.streams)

  Contents: Either streams.xml or streams.xml.gz, & either icon.png or icon.svg
            streams.xml.gz should be gzipped.
            icon.svg should be a non-compressed SVG file.

            Icons for sub-categories (first level only) - these should be named
            the same as the category (with / replaced by _) -
            e.g. 'Hard_Soft Rock.svg' for 'Hard/Soft Rock')

streams.xml.gz is the same format as Cantata's "Favourites" streams file, and
the same as stream cache files. The format is as follows:

  <?xml version="1.0" encoding="UTF-8"?>
  <streams version="1.0" addCategoryName="true">
    <stream name="Station Name" url="http://station.stream.url"/>
  </streams>

if "addCategoryName" is set to true, then when Cantata adds a station from this
category to either favourites or the playqueue, it will prepend the Category
name to the station name.

e.g. To create a stream category named "Wicked Radio" that has 2
sub-categeries, and 3 stream URLs you would need:

streams.xml.gz with:
  <?xml version="1.0" encoding="UTF-8"?>
  <streams version="1.0" addCategoryName="true">
    <category name="Rock">
      <stream name="Hard Rock" url="http://127.0.0.1/hard.ogg"/>
      <stream name="Soft Rock" url="http://127.0.0.1/soft.ogg"/>
    </category>
    <stream name="Blues" url="http://127.0.0.1/blues.ogg"/>
  </streams>

streams.xml.gz & icon.svg need to be placed into a gzip'ed tarball named
Wicked Radio.streams

With the above example, Cantata would list the following in the streams view:

> Wicked Radio
   > Rock
       Hard Rock
       Soft Rock
   Blues

When "Hard Rock" is added to the playqueue, it will be listed as
"Wicked Radio - Hard Rock"

If Rock.png (or Rock.svg) and/or Blues.png (or Blues.svg) also exist in the
tarball, then they will be copied to the install location and used as icons for
the respective category.

To create .streams file:
    1. Place all files in a temp folder
    2. cd into temp folder
    3. tar cfz NAME.tar.gz *
    4. mv NAME.tar.gz NAME.streams


9. MultiMedia Keys
==================

Cantata may be controlled via the media keys on some keyboards. To enable this,
the KDE version can be configured to use KDE's global shortcuts. 

Linux Qt4 and Windows builds, as of 1.2, now also support basic media-keys
shortcuts.

Linux Qt4 and Qt5 builds can also use the GNOME settings daemon's MediaKeys
interface. This interface is normally started automatically under GNOME/Unity
- and you will also need to enable the setting in the shortcuts page of
Cantata's configuration dialog (as of v1.1 this option is enabled by default)


10. Dynamic Helper Script - Local Mode
======================================

When a dynamic playlist is loaded in Cantata, the cantata-dynamic helper script
is executed in the background to do the actual song selection. In this way the
dynamic playlist can still function even when cantata is terminated. It is
possible for this script to be controlled on the command line (although it was
never written with this in mind).

The list of dynamic playlists may be obtained by looking in
~/.local/share/cantata/dynamic

To 'load' a dynamic playlist, all you need to do is symlink the desired one in
~/.local/share/cantata/dynamic to ~/.cache/cantata/dynamic/rules. Then you can
start the helper by calling '/usr/share/cantata/scripts/cantata-dynamic start'
(or first call '/usr/share/cantata/scripts/cantata-dynamic stop' to stop any
current playlist).

To pass connection details, cantata-dynamic reads the same environment variables
as mpc - namely MPD_HOST and MPD_PORT

e.g. the following bash script (not tested!) will stop any current dynamic
playlist, load the 'MyPlaylist' playlist, and start this on the mpd at
'hostname:1234' with password 'pass'

    # Stop current dynamic playlist
    /usr/share/cantata/scripts/cantata-dynamic stop
    # Clear the playqueue (this requires mpc)
    MPD_HOST=pass@hostname MPD_PORT=1234 mpc clear
    # 'Load' new playlist
    if [ -f "$HOME/.cache/cantata/dynamic/rules" ] ; then
        rm "$HOME/.cache/cantata/dynamic/rules"
    fi
    ln -s "$HOME/.local/share/cantata/dynamic/MyPlaylist.rules" "$HOME/.cache/cantata/dynamic/rules"
    # Restart dynamic script
    MPD_HOST=pass@hostname MPD_PORT=1234 /usr/share/cantata/scripts/cantata-dynamic start


11. Dynamic Helper Script - Server Mode
=======================================

In addition to the above, the helper script may be installed on the system
containing MPD, and run in 'server' mode. When run in this mode, it is intended
that the script be run system-wide and started when the system (or MPD) is
started. e.g. The script should be started as:

    <prefix>/share/cantata/scripts/cantata-dynamic server <location of config file>

    e.g.:  /usr/share/cantata/scripts/cantata-dynamic server /etc/cantata-dynamic.conf

When run as described above, the script will automatically daemonize itself.

To stop the dynamizer:

     <prefix>/share/cantata/scripts/cantata-dynamic stopserver

    e.g.:  /usr/share/cantata/scripts/cantata-dynamic stopserver

Cantata's 'Connection' settings page contains an entry to configure the port
which the dynamic script is listening on. If Cantata is configured in this
manner, then it will attempt to talk to the helper via its HTTP API, and will
not start/stop a per-user instance of the script. If the config is left blank,
then cantata will assume the script is to be run in local mode.


Configuration
-------------

The server mode has a simple ini-style configuration file, that has the
following parameters (shown here with the default values):

    pidFile=/var/run/cantata-dynamic/pid
    filesDir=/var/lib/mpd/dynamic
    activeFile=/var/run/cantata-dynamic/rules
    mpdHost=localhost
    mpdPort=6600
    mpdPassword=
    httpPort=6601
    httpControlPage=0
    id=${hostname}
    msgGroup=239.123.123.123
    msgPort=6602
    msgTtl

'pidFile' When started, the script will store its PID within the file
configured here. This is then used to detect if the script is running, etc.

'filesDir' This controls where the dynamic rules are stored. The user the script
is run as should have read/write permissions to this folder.

'activeFile' When a set of rules is made 'active', all cantata does is create a
symbolic link from the rules file to the file specified in 'activeFile'. Again,
the user the script is run as should have read/write permissions to this file.

'mpdHost', 'mpdPort', and 'mpdPassword' are the connection details of the MPD
server.

'httpPort' is the port to be opened by the script to allow it to be controlled.

'httpControlPage' If set to '1' and you point a browser to
'http://<host>:<httpPort>' then the script will return a simple web-page
containing a list of the dynamic rules (which if clicked will become 'active'),
and a button to stop dynamic mode. Set to '0' to disable this page.

'id' is a unique ID that can be used by the client to detect that multicast UDP
messages came from this instance. If this config is left blank, then the
hostname of the machine will be used.

'msgGroup' is the UDP multicast group used to send status messages.

'msgPort' is the UDP multicast port used to send status messages.

'msgTtl' sets the UDP time-to-live parameter. A value of 1 restricts the
message to the local network.


Installation
-------------

Within the dynamic/init folder are example configuration and init files. Copy
one of the example init scripts (or create a new one) to
/etc/init.d/cantata.dynamic - and create the appropriate links in /etc/rc?.d

NOTE: These example scripts assume cantata has been installed to /usr, and that
cantata-dynamic is in /usr/share/cantata/scripts. If this is not the case, then
these will need to be edited.

Copy dynamic/init/cantata-dynamic.conf to /etc, and edit as appropriate.


API
---

This is a brief (and probably incomplete) explanation of the HTTP API.
Currently it is only used by Cantata.

GetId
    Mode:   HTTP GET
    URL:    http://host:port/id
    Params: none
    Return: String containing:
            ID:<current ID>
            GROUP:<udp multicast group>
            PORT:<udp port>

    This should be the first call that a client makes to the dyanmizer. The
    ID that is returned should then be used to confirm that UDP multicast
    messages originated from this instance. Both GROUP and PORT can then be
    used to open a socket to listen for messages.

GetStatus
    Mode:   HTTP GET
    URL:    http://host:port/status
    Params: statusTime=${clientStatusTime}
    Return: String containing:
            STATE:<current status>
            RULES:<name of currently active rule>
            TIME:<epoch time since started, or last rule modification>

    <current status> may be:
        IDLE       - dynamic mode is not running
        NO_SONGS   - no songs matched current rules
        HAVE_SONGS - dynamic mode running, and songs found
        STARTING   - dynamic mode is starting
        TERINATED  - dynamizer has been terminated

    The client should store the TIME value, and use it to determine whether
    any rules have been changed since it last retrieved the list.

ListPlaylists:
    Mode:   HTTP GET
    URL:    http://host:port/list
    Params: statusTime=${clientStatusTime}
            withDetails=1
    Return: String containg list of current rules. if 'withDetails' is set to
            '1' then the contents of the rules are also returned.

    Example return:
        FILENAME: Wibble.rules
        Rule
        Artist: Wibble
        FILENAME: Heavy Metal.rules
        Rule
        Genre: Heavy Metal

GetPlaylist:
    Mode:   HTTP GET
    URL:    http://host:port/${playlist}
    Params: statusTime=${clientStatusTime}
    Return: Returns the contents of the specified 'playlist'. Or, a string
            starting with 'ERROR:' in the case of failure.

DeletePlaylist:
    Mode:   HTTP DELETE
    URL:    http://host:port/${playlist}
    Return:

SavePlaylist:
    Mode:   HTTP POST
    URL:    http://host:port/save
    Params: name=${playlist}  [Required]
    BODY:   Playlist content
    Return:

SetActive:
    Mode:   HTTP POST
    URL:    http://host:port/setActive
    Params: name=${playlist}  [Required]
            start={1/0}       If set to '1' dynamic mode is also started.

ControlDynamizer:
    Mode:   HTTP POST
    URL:    http://host:port/control
    Params: state={start/stop} [Required]
            clear={1/0}        If set to '1', and state=stop, then the MPD
                               playqueue is also cleared.


In order to detect whether the set of stored rules has changed, a client should
supply the 'statusTime' parameter with the value set to the last 'TIME' value
returned by a 'status' call. (If the client has no current value, use '1') The
script will then return the current statusTime, as well as the string
UPDATE_REQUIRED if the client should update its list of playlists (by calling
the 'ListPlaylists' API)


UDP Multicast Messages
----------------------

When run in server mode, the helper script will emit a UDP mutlicast message
when the status changes. This will be on ${msgPort} and group ${msgGroup}. The
format of the message is the same as GetStatus response, apart from the
addition of a header - e.g.

{CANTATA/<id>}STATUS:STATE:<current status>\nRULES:<name of currently active rule>\nTIME:<epoch time since started, or last rule modification>


12. Source Code
===============

The Cantata source folder contains the following structure:

    3rdparty   - Third party libraries
    cmake      - CMake scripts
    context    - Context view classes
    dbus       - DBUS related classes and XML files
    devices    - Device related classes
    dynamic    - Dynamic playlists
    gui        - General GUI classes, e.g. MainWindow, AlbumsPage, etc.
    http       - HTTP server
    icons      - Icons
    models     - Most models, apart from dynamic playlist and shortcut models
    mpd        - MPD related classes; connection, status, song, etc.
    network    - Generic Network classes (and proxy support for Qt builds)
    online     - Jamendo, Magantune, SoundCloud, and Podcasts
    po         - Translations
    replaygain - ReplayGain calculation
    streams    - Internet radio streams
    support    - Generic classes that /may/ be useful to other projects.
                 Mainly used for Qt/KDE and Gtk support.
    tags       - Tag reading, editing, etc.
    widgets    - Widgets that are probably Cantata specific.
    windows    - Files relevant to creating the windows installer.

Cantata's SVG icons have been 'cleaned' using:
  scour --strip-xml-prolog --indent=none -i in.svg -o out.svg

Symbolc media icons are taken from gnome icon theme, but have been scaled with
  rsvg-convert -a -w 128 -f svg in.svg -o out.svg


13. Debug Logging
=================

Cantata contains some debug logging that might help to diagnose certain issues.
To enable this, you must set an environment variable before starting Cantata.
Therefore, its probably better to start Cantata from the commandline.

The following debug values may be used:

    MPD communications           1
    MPD Parsing                  2
    Covers                       4
    Wikipedia context info       8
    Last.fm context info        16
    Combined context info       32
    Context widget              64
    Context backdrop           128
    Dynamic                    256
    Stream Fetching            512
    Http Server               1024
    Song Dialog file checks   2048 (Tag Editor, Track Organiser, etc)
    Network Access            4096
    Context lyrics            8192
    Threads                  16384

These values may be combined to enable multiple output. e.g. to enable MPD and
covers logging:

    CANTATA_DEBUG=5 cantata
    
for just covers logging:

    CANTATA_DEBUG=4 cantata

As of Cantata 1.2.0, all logging output is saved to a file. On Linux systems
this will be ~/.cache/cantata/cantata.log For Windows this will be
C:\Users\USERNAME\AppData\Local\mpd\cantata\cache\cantata.log

To disable logging to file, and log to the terminal instead, use a negative
number. e.g. CANTATA_DEBUG=-4

With windows builds, it is probably easier to set the env var from a DOS
command prompt box. e.g.:

    1. Run cmd.exe from start menu.
    2. cd c:\Program Files\Cantata
    3. set CANTATA_DEBUG=4
    4. cantata.exe

NOTE: Debug logging will function regardless of whether you have created a
Debug or Release build.


14. Credits
===========

Cantata contains code/icons from:

    Amarok         - amarok.kde.org (Transcoding, Cover fetching code in cover
                     dialog)
    Clementine     - www.clementine-player.org (Lyrics searches, CUE file
                     parsing, digitally imported support, and stretched header
                     view)
    Be::MPC        - Wikipedia parsing code
    Quassel        - quassel-irc.org (Qt-only keyboard short-cut config support)
    Solid          - solid.kde.org (Device detection for Qt-only builds)
    Musique        - Copied code for Gtk theme detection
    Asunder        - CDDB code
    libkcddb       - MusicBrainz code
    libebur128     - https://github.com/jiixyj/libebur128 (Replay gain
                     calculation)
    QJson          - JSON parser, taken from https://github.com/flavio/qjson
    IcoMoon        - http://icomoon.io/#icons (Monochrome sidebar icons)
    Qxt            - Multi-media key support
    QtSolutions    - QtIOCompressor, and QtSingleApplication


15. Windows
===========

The following steps are used to compile Cantata, and create the windows
installer.

This assumes the following folder structure:

    z:\cantata\src          [ Checkout of Cantata's source code ]
    z:\cantata\build        
    z:\cantata\install      [ make install will place target files here ]
    z:\cantata\oxygen       [ Oxygen icons folder ]
    z:\dev\MingGW
    z:\dev\Qt\4.8.4
    z:\dev\taglib
    z:\dev\zlib


1. Install Qt, MinGW, cmake, TagLib and zlib. TagLib and zlib will probably
   need compiling.

2. Call cmake (e.g. from build folder):
     cmake ../src -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DENABLE_TAGLIB=OFF -DTAGLIB_FOUND=1 -DTAGLIB_INCLUDES=z:/dev/taglib/include -DTAGLIB_LIBRARIES=z:/dev/taglib/lib/libtag.dll.a -DTAGLIB_MP4_FOUND=1 -DTAGLIB_ASF_FOUND=1 -DTAGLIB_CAN_SAVE_ID3VER=1 -DZLIB_INCLUDE_DIR=z:/dev/zlib/include -DZLIB_LIBRARY=z:/dev/zlib/libz.dll.a -DCMAKE_INSTALL_PREFIX=z:/cantata/install -DCANTATA_WINDOWS_INSTALLER_DEST=z:/cantata -DCANTATA_MINGW_LIBS=z:/dev/MinGW/bin/mingwm10.dll;z:/dev/MinGW/bin/libgcc_s_dw2-1.dll -DCANTATA_OXYGEN_DIR=z:/cantata/oxygen -DCMAKE_BUILD_TYPE=Release -DENABLE_KDE=OFF

   (Note: -DENABLE_TAGLIB=OFF stops cmake from trying to find TagLib, as the TagLib settings have been manually set)

3. make

4. make install

5. Run Inno Setup Compiler, and use the windows-installer.iss that has been
   generated in the build folder. This will place the setup exe in z:\cantata

This build is as per Qt-only, but does not have support for dbus, local dynamic
playlists, device support, or replaygain calculation.


TagLib
------

Windows version of taglib was built from TagLib 1.8, using the following cmake command:
    cmake .. -G "MinGW Makefiles" -DWITH_ASF=1 -DWITH_MP4=1 -DCMAKE_INSTALL_PREFIX=z:\dev\taglib

