467 lines
16 KiB
Plaintext
467 lines
16 KiB
Plaintext
Introduction
|
|
============
|
|
|
|
Cantata is a GUI front-end for MPD. The code is forked from QtMPC. However,
|
|
both the code itself, and the GUI are now *very* different to QtMPC.
|
|
|
|
|
|
Dependencies
|
|
============
|
|
|
|
Cantata requires the following Qt libraries:
|
|
|
|
1. QtCore
|
|
2. QtGui
|
|
3. QtNetwork
|
|
4. QtXml
|
|
5. QtDBus (Only for Linux builds)
|
|
|
|
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. Lame - Encode Audio CD streams when sent via HTTP server.
|
|
|
|
|
|
Translations
|
|
============
|
|
|
|
Cantata started out as a KDE4 application, but as of v0.9.0 both the KDE
|
|
and Qt-only builds have the same functionality. Because of its KDE base, 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 will 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 whetever 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 manully 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 what is used to
|
|
extract translateable strings, and update current translations.
|
|
|
|
|
|
Covers
|
|
======
|
|
|
|
When displaying covers, Cantata will load album covers in the following order:
|
|
|
|
...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:
|
|
|
|
1. ${configuredName}.jpg - if set
|
|
2. ${configuredName}.png - if set
|
|
3. cover.jpg
|
|
4. cover.png
|
|
5. AlbumArt.jpg
|
|
6. AlbumArt.png
|
|
7. folder.jpg
|
|
8. folder.png
|
|
9. ${file}.jpg
|
|
10. ${file}.png
|
|
11. ${albumArtist} - ${album}.jpg
|
|
12. ${albumArtist} - ${album}.png
|
|
13. ${album}.jpg
|
|
14. ${album}.png
|
|
15. Image embedded within current songs tags.
|
|
16. ANY other jpg, or png
|
|
|
|
...then Cantata will check its cache folder (~/.cache/cantata/covers), for :
|
|
|
|
17. ${albumArtist}/${album}.jpg
|
|
18. ${albumArtist}/${album}.png
|
|
|
|
...if compiled for Linux
|
|
|
|
19. Matching Amarok cover
|
|
20. Matching Clementine cover
|
|
|
|
...if the MPD folder was specified as a http URL
|
|
|
|
21. ${url}/${dirFromFile}/cover.jpg
|
|
- or ${url}/${dirFromFile}/${configuredName}.jpg (if set)
|
|
22. ${url}/${dirFromFile}/cover.png
|
|
- or ${url}/${dirFromFile}/${configuredName}.png (if set)
|
|
|
|
...lastly
|
|
|
|
23. 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.
|
|
|
|
|
|
For artist images:
|
|
|
|
...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:
|
|
|
|
1. ${albumArtist}.jpg
|
|
2. ${albumArtist}.png
|
|
3. artist.jpg
|
|
4. artist.png
|
|
|
|
... the above will be repeated for each parent folder (until we reach the MPD
|
|
root folder)
|
|
|
|
...then Cantata will check its cache folder (~/.cache/cantata/covers), for :
|
|
|
|
5. ${albumArtist}.jpg
|
|
6. ${albumArtist}.png
|
|
|
|
...if the MPD folder was specified as a http URL
|
|
|
|
7. ${url}/${dirFromFile}/artist.jpg
|
|
8. ${url}/${dirFromFile}/artist.png
|
|
|
|
... the above will be repeated for each parent folder (until we reach the MPD
|
|
root folder)
|
|
|
|
...lastly
|
|
|
|
9. 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 heirarchy is 2 levels (artist/album/) and the user has write
|
|
permissions. If not, then they will be saved in Cantata's cache folder.
|
|
|
|
|
|
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. The Qt only
|
|
builds (under Linux) can 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 Cantata's configuration dialog.
|
|
|
|
If your system does not have this daemon, you could possibly use
|
|
https://code.google.com/p/mediakeys-daemon/ which is a python re-implementation
|
|
of the interface.
|
|
|
|
|
|
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
|
|
~/.config/cantata/dynamic
|
|
|
|
To 'load' a dynamic playlist, all you need to do is symlink the desired one in
|
|
~/.config/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/.config/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
|
|
|
|
|
|
Dynamic Helper - 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/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.
|
|
|
|
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
|
|
|
|
'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 dyamic rules are stored. The user the script
|
|
is run as should have read/write permissions to this folder.
|
|
|
|
'activeFile' When a set of rule 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' then if 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.
|
|
|
|
|
|
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 script 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.
|
|
|
|
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
|
|
|
|
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}
|
|
Return: String containd 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]
|
|
|
|
|
|
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)
|
|
|
|
|
|
Source Code
|
|
===========
|
|
|
|
The Cantata source folder contains the following structure:
|
|
3rdparty - Third party libraries
|
|
cmake - CMake scripts
|
|
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
|
|
lyrics - Lyrics
|
|
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 and Magantune
|
|
po - Translations
|
|
replaygain - ReplayGain calculation
|
|
streams - Internet radio streams
|
|
support - Generic classes that /may/ be usefull to other projects.
|
|
Mainly used for Qt/KDE and Gtk support.
|
|
tags - Tag reading, editing, etc.
|
|
widgets - Widgets that are probably Cantata specific.
|
|
|
|
|
|
Credits
|
|
=======
|
|
|
|
Cantata contains code/icons from:
|
|
Amarok - amarok.kde.org (Transcoding, Cover fetching code in cover
|
|
dialog, Jamendo and Magnatune icons)
|
|
Clementine - www.clementine-player.org (Lyrics searches)
|
|
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
|
|
Ayatana Qt - Overlay scrollbar code copied/modified from
|
|
https://launchpad.net/ayatana-scrollbar-qt
|
|
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
|
|
radio icon - Taken from WP Woothemes Ultimate (findicons.com)
|
|
licence: Freeware
|
|
Sidebar icons - Taken frmo IcoMoon - http://icomoon.io/#icons
|
|
|
|
|
|
Windows
|
|
=======
|
|
|
|
The following steps are used to compile Cantata, and create the windows
|
|
installer.
|
|
|
|
This assumes the following folder structure:
|
|
z:\cantata\src
|
|
z:\cantata\build
|
|
z:\cantata\install
|
|
z:\cantata\oxygen
|
|
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.):
|
|
cmake ../src -G "MinGW Makefiles" -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 -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
|
|
|
|
(Note: -DENABLE_TAGLIB=OFF stops cmake from trynig to find TagLib, as the TagLib setting shave 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 build from TagLib 1.8, using the following cmake command:
|
|
cmake .. -G "MinGW Makefiles" -DWITH_ASF=1 -DWITH_MP4=1 -DCMAKE_INSTALL_PRFIX=z:\dev\taglib
|
|
|