Table of Contents

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

1. Introduction

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

1. Support for Qt4, Qt5, KDE, MacOSX, Windows, and Ubuntu Touch 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, ShoutCast, or Dirble.
   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.
   18. Basic support for touch-style interface (views are made 'flickable')
   19. Scrobbling.
   20. Ratings support.

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. Also, as of 1.4.0, by default Cantata is built as a Qt-only application (with no KDE dependencies)

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.

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
   10. LibQJson - only for Qt4, and KDE4, builds. If this is not found on the system then Cantata will use its own bundled copy.
   11. LibEbur128 - ReplayGain detection code. If this is not found on the system then Cantata will use its own bundled copy.

3. Building

Please refer to the INSTALL file for general build instructions. Details on how Cantata is build for Windows can be found in section 16, and Mac OSX in section 17.

Some Qt4 builds still use com.trolltech.QtDBus.QtTypeName, whereas newer ones use org.qtproject.QtDBus.QtTypeName. If you get build failures such as "fatal error: playeradaptor.h: No such file or directory" then set -DUSE_OLD_DBUS_TYPEDEF=ON when calling CMake.

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

5. Translations

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

6. 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}.png

...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. ${albumArtist} - ${album}.jpg
   11. ${albumArtist} - ${album}.png
   12. ${album}.jpg
   13. ${album}.png
   14. Image embedded within current song's tags.
   15. ANY other jpg, or png

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

16. ${albumArtist}/${album}.jpg
17. ${albumArtist}/${album}.png

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

18. ${url}/${dirFromFile}/cover.jpg
    • or ${url}/${dirFromFile}/${configuredName}.jpg (if set)
19. ${url}/${dirFromFile}/cover.png
    • or ${url}/${dirFromFile}/${configuredName}.png (if set)

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

20. 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 PNG 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}.png

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

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

maxCoverUpdatePerIteration= Non cached covers, and cached covers in albums view, are not located and loaded in the UI thread - as this causes lag when scrolling. A separate background thread is use for this. These covers 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 10. (Values 1..50 are acceptable)

coverCacheSize= Cantata stores scaled versions of covers in a cache in memory, to reduce memory usage and/or disk access. This setting controls the maximum size (in megabytes) that Cantata will use for this cache. The default is 10 (Values 1..512 are acceptable)

cueFileCodecs= 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= Volume % increments. Used when mouse wheel is activated over volume control. Default is 5. (Values 1..20 are acceptable)

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

mpdPoll= 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= 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= 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 (when MPD version is <0.19 or not connected to 127.0.0.1). Default is false.

alwaysUseLsInfo= Versions of Cantata before 1.6 defaulted to using 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 fallback to calling "lsinfo

        streams.xml.gz should be GZip compressed.
        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')