File: README

package info (click to toggle)
cantata 2.3.3.ds1-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 18,180 kB
  • sloc: cpp: 98,927; perl: 1,356; xml: 717; python: 139; lex: 110; sh: 85; yacc: 78; makefile: 9
file content (821 lines) | stat: -rw-r--r-- 28,737 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
Table of Contents
=================

 1. Introduction
 2. Dependencies
 3. Building
 4. Bugs
 5. Translations
 6. Covers
 7. CUE Files
 8. Streams
 9. MultiMedia Keys
10. DBUS Actions
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 Linux, MacOSX, and Windows.
 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. Basic support for touch-style interface (views are made 'flickable')
17. Scrobbling.
18. Ratings support.

Cantata started off as a fork of QtMPC, however, the code (and user interface)
is now *very* different to that of QtMPC.

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.


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

Cantata requires the following Qt libraries:

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

Cantata may also use the following optional libraries:

1. TagLib - Tag edit dialog, replaygain, track organizer, and UMS device
            support.
2. LibMTP - MTP devices.
3. FFMPEG (libavcodec) - ReplayGain detection code.
4. MPG123 - ReplayGain detection code.
5. CDParanoia - Read/rip Audio CDs.
6. CDDB - either this or MusicBrainz5 required for Audio CDs
7. MusicBrainz5 - either this or CDDB required for Audio CDs
8. LibEbur128 - ReplayGain detection code. If this is not found on the
   system then Cantata will use its own bundled copy.
9. libavahi-common / libavahi-client - Avahi support (automatic mpd discovery)


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.


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 https://github.com/CDrummond/cantata

When reporting a bug, please mention the Cantata version number, the Cantata
build type (Linux, Windows, Mac), 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.


5. Translations
===============

As of version 2.1.0, Cantata uses Qt5's translation framework.

To generate a new translation for Cantata:

1. Copy translations/blank.ts to cantata_LANG_CODE.ts
   (Replace LANG_CODE with the language code for the desired language, e.g. 
   'fr' for French - so this would be cantata_fr.ts)
2. Open your new ts file with Qt Linguist.
3. In Qt Linguist set the target language and country.
4. Update the translations.
5. Either email me the new translation (address is in the AUTHORS file), or
   create a pull request on github.


6. Covers
=========

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

${configuredName} is either:
a. cover - if not configured in Cantata's config dialog
b. Setting from cantata with the following replacements:
    %albumartist% => Album Artist
    %artist% => Track Artist
    %album% => Album Name
    Any other % removed

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

${configuredName} is either:
a. artist - if configured Album cover ${configuredName} is empty, or does not
   contain %
b. ${albumArtist} - if configured Album cover ${configuredName} contains % and
   ${albumArtist} is not 'Various Artists'
c. ${basicArtist} if configured Album cover ${configuredName} contains % and
   ${albumArtist} is 'Various Artists'

...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. ${configuredName}.jpg
 5. ${configuredName}.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}/${configuredName}.jpg
 9. ${basicArtist}/${configuredName}.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}/${configuredName}.jpg
13. ${url}/${dirFromFile}/${configuredName}.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 composer images:

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

1. ${composer}.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. composer.jpg
3. composer.png

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

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

4. ${composer}.jpg
5. ${composer}.png

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

6. ${url}/${dirFromFile}/composer.jpg
7. ${url}/${dirFromFile}/composer.png

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

Downloaded images will be saved as composer.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. 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 7 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
==========

As of 1.4.0, Cantata only comes with TuneIn, ShoutCast, IceCast and Dirble
stream providers. To install new providers, you can either use Cantata's
download dialog (to install for Cantata's extras github repo), or install from
file. To import new stream categories into Cantata, these files need to be GZip
compressed tarballs of the following format.

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

  Contents: Either streams.xml, streams.xml.gz, OR settings.json, AND
            Either icon.png OR icon.svg

            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')

settings.json is really only intended to be used by Cantata for providers
stored in its extras github repo. This JSON file has the following syntax:

  { "type": "streamType", "url": "Stream listing URL" }
  
  "streamType" can be either di, soma, or listenlive. Cantata contains code to
  download from "Stream listing URL" and parse the response based upon
  "streamType"

In general, for externally provided stream lists, it is more convenient to just
list all a providers streams within stream.xml.gz. This has the following
format:

  <?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 compressed 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


cantata-extra on github
-----------------------

The streams page on Cantata's settings dialog, will allow you to install new
providers from Cantata's extras github repo. To do this, the dialog first
downloads the list of providers, this is obtained from the following URL:

https://raw.githubusercontent.com/CDrummond/cantata-extra/master/streams/2.1/list.xml

The contents of this file will be something like:

<providers>
 <category type="0">
  <provider name="1.fm" md5="cbd6ad834d4493662952a653cea5c779"/>
  ...

If you want to manually download a provider, use the listed URL to download the
.streams file. e.g. for the above:

    wget https://raw.githubusercontent.com/CDrummond/cantata-extra/master/streams/2.1/1.fm.streams.gz

Extract the contents with:

    tar zxvf 1.fm.streams.gz

If you wish to distribute a new stream provider via Cantata's extras github
repo, please send me an email with the .streams.gz file. My address is in the AUTHORS
file.


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

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

Linux use the GNOME settings daemon's MediaKeys interface. This interface is
normally started automatically under GNOME/Unity.


10. DBUS Actions
================

All of Cantata's internal actions are accessible via DBUS. The
cantata-remote helper script may be used to invoke these, e.g. to toggle
playback:

    cantata-remote cantata playpausetrack

The list of action names maybe obtained by calling the listActions DBUS method,
e.g.:

    qdbus mpd.cantata /cantata listActions


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


12. 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. This requires MPD>=0.17, as
communications are via MPD's client-to-client messages.

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

When MPD informs Cantata that the 'cantata-dynamic-in' channel has been
created, Cantata will automatically switch itself to server mode. The list of
rules is then loaded from the server, and Cantata will change the backdrop of
the dynamic page to indicate that the rules are comming from the server.

Server mode is currently the only way for dynamic playlists to be used under
Windows.


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=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 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' if this is set to non-zero, then the script will serve up a *very*
simple HTTP control page - allowing playlists to be started and stopped.


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

Within the playlists folder is a systemd service file.

NOTE: This service file assumes cantata has been installed to /usr, and that
cantata-dynamic is in /usr/share/cantata/scripts. If this is not the case, then
this will need to be edited.

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


13. 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
    playlists  - Playlists
    gui        - General GUI classes, e.g. MainWindow, LibraryPage, 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 and Gtk support.
    tags       - Tag reading, editing, etc.
    widgets    - Widgets that are probably Cantata specific.
    windows    - Files specfic to Windows builds..
    mac        - Files specfic to MacOSX builds.

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


14. Debug Logging
=================

Cantata contains some debug logging that might help to diagnose certain issues.
To enable this, you need to use the --debug commandline option. This option
takes a comma-separated list of debug areas.
Therefore, its probably better to start Cantata from the commandline.

The following debug areas may be used:

    MPD communications        mpd
    MPD Parsing               mpdparse
    Covers                    covers (or covers-verbose)
    Wikipedia context info    context-wikipedia
    Last.fm context info      context-lastfm
    Combined context info     context-info
    Context widget            context-widget
    Context lyrics            context-lyrics
    Dynamic                   dynamic
    Stream fetching           stream-fetcher
    Http server               http-server
    Song dialog file checks   song-dialog
    Network access            network-access
    Threads                   threads
    External tags             tags
    Scrobbling                scrobbler
    Devices                   devices
    SQL                       sql
    MPD HTTP stream playback  http-stream
    MPD auto discover         avahi
    Media keys                media-keys
    Cusrtom actions           custom-actions

To log debug to a file use --debug-to-file. e.g. To log MPD communications and
cover access to a file, start cantata as follows:

    cantata --debug=mpd,covers --debug-to-file


The loccation of the debug file will vary dependant upon OS. 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 And for OSX it
will be /Users/$USER/Library/Caches/cantata/cantata/cantata.log


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


15. 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)
    Asunder            - CDDB code
    libkcddb           - MusicBrainz code
    libebur128         - https://github.com/jiixyj/libebur128 (Replay gain
                         calculation)
    IcoMoon            - http://icomoon.io/#icons (Monochrome sidebar icons)
    Qxt                - Multi-media key support
    QtSolutions        - QtIOCompressor, and QtSingleApplication
    QMPDClient         - Last.fm scrobbling


16. Windows
===========

Icon created under Linux using the createicon.sh in the windows folder.

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:\dev\Qt
    z:\dev\taglib
    z:\dev\zlib
    z:\dev\ssl              [ libeay32.dll and ssleay32.dll ]
s

1. Install Qt (5.3 or later), cmake, TagLib and zlib. TagLib and zlib will probably
   need compiling.

2. Set (or amend) the following environemnt variables:
    QTDIR=z:\dev\Qt\5.3\mingw482_32
    PATH=z:\dev\Qt\5.3\mingw482_32\bin;z:\dev\Qt\Tools\mingw482_32\bin;z:\dev\taglib\bin;z:\dev\cmake\bin

3. Load cantata's CMakeLists.txt in QtCreator, and pass the following to cmake:
     ../src -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/lib/libz.dll.a -DCMAKE_INSTALL_PREFIX=z:/cantata/install -DCANTATA_WINDOWS_INSTALLER_DEST=z:/cantata -DCANTATA_SSL_LIBS=z:/dev/ssl/libeay32.dll;z:/dev/ssl/ssleay32.dll

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

4. Build via QtCreator

5. Create an 'install' project in QtCreator
  - Projects
  - Add/Clone Selected
  - Expand Build Steps, and select install

6. Build 'install' project via QtCreator

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


Create Installer
----------------
Run Nullsoft Scriptable Install System, and use the cantata.nsi that has been
generated in the install folder. This will place the setup exe into the install
folder as well.


TagLib
------

Windows version of taglib was built from TagLib 1.9.1, using QtCreator with the
following passed to cmake:

    -DCMAKE_BUILD_TYPE=Release -DWITH_ASF=1 -DWITH_MP4=1 -DCMAKE_INSTALL_PREFIX=z:\dev\taglib


17. Mac OSX
===========

Icon created under OSX using the createicon.sh in the mac folder.

The following steps are used to compile Cantata, and create the OS X application
bundle.

These steps assume the following structure:

    src/
    build/
    install/

1. Install HomeBrew

2. brew install cmake taglib ffmpeg openssl qt5

3. Load cantata's CMakeLists.txt in QtCreator, and pass the following to cmake:
     ../src -DCMAKE_PREFIX_PATH=/usr/local/Cellar/qt5/5.9.1/ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=`pwd`/../install

4. Build via QtCreator

5. Create an 'install' project in QtCreator
  - Projects
  - Add/Clone Selected
  - Expand Build Steps, and select install

6. Build 'install' project via QtCreator


If Qt Creator is not installed, or calling CMake from the commandline, you may
need to set CMAKE_PREFIX_PATH e.g.

    export CMAKE_PREFIX_PATH=/usr/local/Cellar/qt/5.9.1/lib/cmake/:${CMAKE_PREFIX_PATH}

Ensure 'lrelease' (required to build Cantata translations) is in PATH, e.g.

    export PATH=/usr/local/Cellar/qt/5.9.1/bin/:${PATH}


Create Installer
----------------

1. Go into the 'mac' folder within the build folder

2. Run ./create-dmg.sh