/*! \mainpage Muggle: Media Juggler for VDR

This is a plugin for the Video Disk Recorder (VDR).

Written by:                  Andi Kellner,
                             Lars von Wedel <vonwedel@web.de>,
                             Ralf Klueber <r@lf-klueber.de>, 
                             Wolfgang Rohdewald <wolfgang@rohdewald.de>

Project's homepage:          http://sourceforge.net/projects/vdr-muggle

Latest version available at: http://sourceforge.net/projects/vdr-muggle

See the file COPYING for license information.

\section foreword PLEASE!

This is a difficult plugin. It's nice but difficult.  With difficult I
mean, that due to the underlying database, many more sources of error
can occur as opposed to other plugins.

Take some time to carefully read these instructions.  Please provide
feedback to the authors whenever you think, these instructions are not
appropriate, wrong, or useless in any other sense.

\section desc DESCRIPTION

The muggle plugin provides a database link for VDR so that selection
of media becomes more flexible.  Prerequisites are described in
Section 2, Notes on Compilation are in Section 3. Before using the
plugin, you need to import your media into the database (cf. Section
4). The configuration of VDR and startup parameters are described in
Section 5.


The plugin currently runs on versions 1.3.17- of VDR (including
1.2.6). It also compiles on versions up to at least 1.3.23 but your
mileage may vary. In addition, the following pieces of software are
required:

 - a database backend. You can use mysql, embedded mysql, postgresql
   and SQLite. If you want to be compatible with GiantDisc, use
   mysql. If other applications will access this data base, do not use
   embedded mysql. The easiest to install are embedded mysql and SQLite.
   SQLite will use much less RAM than the others. By default muggle will
   be built using the embedded mysql library so that it is  not required
   to install further packages or run additional services. For details
   see README.mysql, README.postgresql, README.sqlite.
 - libmad (for mp3 decoding)
   (Debian package libmad0-dev or 
    http://www.underbit.com/products/mad/)
 - libtag (for ID3 tag reading/writing)
   (Debian package libtag1-dev or 
    http://developer.kde.org/~wheeler/taglib.html)
 - optionally libvorbis and libvorbisfile to replay OGG Vorbis files
   (Debian packages libvorbis-dev or
    http://www.xiph.org/ogg/vorbis/)
 - optionally libFLAC++ to replay FLAC files
   (Debian package libflac++-dev or sources from flac.sourceforge.net)
 - recode, python, python-chardet and Googlyrics2 if you want to download lyrics.
   Googlyrics2 must be newer than Beta3, otherwise umlauts will be
   wrong

The developer versions are needed because their headers are required
for compilation.  The server need not be on the same machine as the
VDR. Also, music tracks can reside somewhere else, if they are
available through a remote filesystem (NFS, Samba). However, in this
case you should know what you are doing in terms of networking and
security issues.

Support for using a libsndfile decoder requires libsndfile1-dev as a
debian package or a corresponding library installation.

Since release 0.1.8 Muggle is able to display cover pictures. The
required packages are
 - mjpegtools (Debian package mjpegtools)
 - netpbm (Debian package netpbm)

Since release 0.2.0 Muggle has a new player OSD. It now also requires
the package
 - Imlib2 (Debian packages libimlib2 and libimlib2-dev for compilation)

\section install INSTALLING 

Unpack the sources in PLUGINS/src below your VDR directory (i.e. where
all your other plugins are.  For example (paths and version numbers
may vary)

\verbatim
   cd /usr/local/src/VDR/PLUGINS/src
   tar xvjf muggle-0.1.8.tgz
\endverbatim

Establish a symlink as you would for other plugins:

\verbatim
   ln -s muggle-0.1.8 muggle
\endverbatim

Adapt the Makefile to your system. Or better yet adapt your
Make.config. This file might be in /usr/include.  Define HAVE_VORBIS
and/or HAVE_FLAC and the database definitions as described in
README.mysql, README.postgresql, README.SQLite.

Then, within the VDR main directory (e.g. /usr/local/src/VDR) issue

\verbatim
   make plugins
\endverbatim

This should build all relevant stuff. If you have difficulties, check
that required libraries are in the library directories stated in the
muggle Makefile.

Note: On some Debian sarge systems a proper symlink for libwrap.so
might be missing.  missing. Check this in case the compiler complains
about a missing -lwrap.

\section SET UP MUGGLE 

First let's define what the top level directory (short TLD) is. Muggle
expects all music files to be in the same directory (and its
subdirectories). Symbolic links will be followed. You specify the TLD
with the argument -t. The default is /mnt/music; you can change the
default at build time using the MUSICDIR Makefile variable.  It is
recommended to store only music files in the TLD. You can organize
files in orders per genre, album or whatever.

It is essential that you always use the same TLD when using the muggle
plugin or the external program mugglei, otherwise muggle will not find
your files. So please take some time to plan where to put your music
files. The plugin must be able to find and to read them. The data base
only holds the names of your music files but not the content. The
database does NOT hold the TLD but only the file names relative to the
TLD. Example: let's assume you have a file
/home/music/Pop/Rea/title.mp3, and all other music is also in
/home/music:

\verbatim
mugglei -t /home/music Pop/Rea/title.mp3
\endverbatim

will save Pop/Rea/title.mp3 as file name. If you want to play this,
you will also have to tell the plugin with option -t /home/music where
to find it. muggle only stores the file names relative to the TLD
because this makes it possible to move the TLD somewhere else without
having to reimport everything. You could as an example rename the TLD
/home/music to /server5/MUSIK and simply change the value of the -t
argument when starting the plugin.

Of course, you will normally not import single files. The normal
command would be

\verbatim
mugglei -t /home/music .
\endverbatim

(Notice the single dot meaning "this directory")

Next you have to decide which database software best suits your needs.
We assume that the database software is already configured. See the
corresponding README.*

When starting up muggle the first time it will check whether the
database exists and might ask whether to create it. Confirm this with
Ok.

After successfully creating the database, muggle will ask you whether
to import music. Confirm this question with Ok, too. Muggle will now
recursively descend into the directories below the TLD.  Once muggle
is running, you can import new tracks and read updated tags by a
command in the setup menu. The use of mugglei is still possible, but
possibly only while VDR is not running, depending on the database you
are using. (because muggle will then block the use of the
database). This is especially true for SQLite. The remote mysql and
postgresql versions do not block.

\section SET UP MUGGLE USING MUGGLEI

You can also initialize and populate the data base from the command
line with the external program mugglei. This can be done on the
database server or on some other client machine as long as it can
access the data base and the files it should import.

mugglei takes some parameters defining how the data base can be
accessed.  These parameters vary slightly depending of the data base
software you have chosen. Start mugglei without arguments to see a
list and explanation for all available parameters.

The simplest form for initializing (parameter -c) and populating (the
rest on the command line) the data base is

\verbatim
mugglei -c -t /home/music .
\endverbatim

(notice the single dot). This uses default values for all other
parameters.  mugglei will create a new databases and initialize it
with basic information about languages, genres etc. It will also
import all files in the TLD /home/music and its subdirectories. For
details call mugglei without arguments, some help will be displayed.


\section config MUGGLE CONFIGURATION

muggle uses a small set of command line parameters which define how
the database can be accessed. These are the same as for mugglei. You
get help about them with

\verbatim
vdr -h -Pmuggle
\endverbatim

Let's look at an example:

\verbatim
vdr  -P'muggle -t/home/music'
\endverbatim

The -t argument specifies the TLD as described above.

Depending on your data base you may have to give mugglei more
arguments, telling mugglei how to access the data base.  For details
see the README.* that corresponds to your data base software.

\section importremote IMPORTING MUSIC FILES 

You can do this directly from vdr (in the muggle configuration menu)
or by using mugglei as explained above. The program will connect to
the database, evaluate ID3 tags from files and write the tags into the
database.


\verbatim
   mugglei -t /home/music .
\endverbatim

(Notice the single dot) will import all music files (*.mp3., *.ogg,
*.flac) in the directory . (the single dot stands for the current
directory) As already explained, it is important that you always use
the same value for -t whenever you import so that filenames are
relative to exactly the same directory (e.g. /home/music in the
example case).

NOTE: mugglei can only be called in the TLD or in some subdirectory of
the TLD.  Otherwise mugglei displays an error and does nothing.

As with the muggle plugin, you may need additional options for the
database host, user, etc.

If a track has no ID3 tags, the following defaults will be applied:

- Title: Filename will be used
- Artist: "Unknown"
- Album: "Unassigned"
- Track: 0
- Year: 0

\section covers COVERS

Muggle can display cover images (and others). Set the setup entry
"Background mode" to "Cover small" or "Cover big" to enable this
feature. "Cover small" puts it into the lower right corner which
is unused by the main player screen, "Cover big" shows it on
the full screen as background image. If you get problems with your
FF card like "timeout waiting for Loadbitmap", please use the background
mode "Bitmap".

Please note that the mechanism to find images has changed in release 0.1.9
(and may be changed again in future versions). The images are now
found like this.

1. Check whether there are images in the APIC id3v2 tag of the file.
   If so, expand these and show them on the screen during replay.
2. Otherwise, check all image files in the directory of the current song
3. Recursively look into parent directories (up to top level) until at
   least one image is found and display it.
4. If no images can be found at all, nothing is displayed.

So if you want a default background for all tracks you should put it
into the toplevel directory (e.g. cover.jpg). It is strongly
recommended to define such a default background. Otherwise if no cover
is found for a track, the previously displayed cover stays on the
screen. This is a known "behavior".

Currently, the database entry (album.coverimg) is not taken into account.

During installation, make sure that the script called muggle-image-convert
(from the scripts directory) is somewhere in your PATH. Also, make
sure to use the -c flag if you use a runvdr (or similar) script.

An interesting feature can be achieved with recent VDR versions (>=
1.3.30) in conjunction with the image plugin. Through the new service
interface, the image plugin can send a list of images to Muggle which
will then take care of displaying them as a background (instead of
covers). This way, one can have an image playlist together with a
music playlist replayed side by side! In order to enable this
behavior, apply the patch (vdr-image-0.2.3.diff) to the image plugin
sources and recompile.

The images need to be converted to Mpeg. Starting with muggle 0.2.0,
the converted images are stored in a cache directory (define it in
the setup menu). So if you change between Cover small and Cover big,
you will need to remove all cached images. If the original image file
changes, the image will also be regenerated.


\section lyrics LYRICS

Muggle can display lyrics from local files or from the internet.
The lyrics are stored in the cache directory, with
the file name extension .lyrics or .lyrics.tmp. .lyrics is for
the saved version, .lyrics.tmp is downloaded from the internet but
not saved. Both files can coexist, however if .lyrics.tmp exists,
this one will be displayed with the option to save it. Saving of
course removes .lyrics.tmp

The directory lyrics.tmp.new contains all versions downloaded from
the internet. If the user wants to download or rejects a version,
the first version from this directory is returned and removed
from the lyrics.tmp.new. Only if no version is available from
lyrics.tmp.new, muggle actually invokes googlyrics2 for a new
download.

If a track starts playing and lyrics are wanted, muggle first tries the local file.
If it does not exist, muggle will automatically get it from the
internet and save the first version. If you do not like the text,
you can edit the lyrics file
(outside of muggle) or request another load from the internet -
maybe somebody fixed it meanwhile. If characters in the lyrics are
not shown correcly, you can try to adjust the muggle_getlyrics script.

Muggle starts the retrieval script in the background and displays
the lyrics as soon as it is available. If you change track before
the retrieval finished, two ore more retrieval scripts might be
running at the same time - no problem.

with vdr versions before 1.5.4, muggle cannot start this in the background.
Instead it waits until the script has finished. Meanwhile it will not
respond to commands, and the message "loading lyrics" will only appear
after they have been loaded.

Muggle calls the python program muggle_getlyrics which 
uses the Googlyrics2 python modules.
Googlyrics2 is a plugin to the amarok music player, it can currently ask
27 different sources.

If the lyrics lines are too long, they are split by muggle_getlyrics. If
those lines are too short or too long, adapt MAXLINELENGTH in muggle_getlyrics.
Currently lines are split at normal space and at nbsp (unicode non breaking
space). Lines that have no such spaces are not split.



\section quickuse QUICK INTRO

Quick version: select Muggle on the OSD, browse titles (using up/down
and Ok), add them using the red button. Music will start instantly
while you can continue to browse and add tracks.

Starting with 0.2.0, muggle has a new OSD for playback mode. It is
similar to the OSD of the Music plugin but with less possibilities.
Move the cursor in the track list as usual and press enter to play
the currently selected track. Most other thing should be self
explaining.


\section use DETAILED USER'S GUIDE

The core concept of the Muggle user interface is called a
*selection*. That is, as the name suggests, a selection of music
tracks. Note, that a selection can be as small as a single track (a
very simple selection, indeed) or as large as the whole music library.

Selections are used to structure all tracks (the music library) into
sets (e.g. a selection of all tracks by an author) and subsets
(e.g. the tracks of an author on a certain album). Such selections are
built by means of keys (e.g. author or album) defined in the database
and are displayed in the *music browser*. The current selection in the
*music browser* contains all tracks defined by the line the cursor is
on. So if you place the cursor on the line "Pop", all tracks with
Genre Pop are selected. If you then enter Pop and go to the line
"Beatles", you narrow your selection to pop songs from The Beatles.

A collection is a special selection. Collections can be defined by the
user, and he can add or remove any selection to / from a collection. A
collection has only one order: a number which is incremented for every
added track. Otherwise, since a collection is also a selection,
everything that is valid for selections also holds for collections.

Collections can be defined by the user in the sense of a
playlist. This is done by adding/removing selections to/from the
*default collection*.

Changing the contents of a collection changes them directly in the
data base. Saving or loading collections is not needed.

An important term while working with Muggle is the *default
collection*. This is a special collection which is the target of
commands working on collections.  Whenever you add selections to
somewhere, they will be added to the default collection. The same
happens when you remove selections.

Another important collection is the 'play' collection. This is a
temporary collection.  Whatever is added to it will be played in that
order. If you add something while muggle is not playing anything, this
collection will first be emptied. However 'temporary' does not mean
that its content is not saved to the data base.

Starting from release 0.1.1 Muggle can be also used without default
playlists. There are new menu entries "Add X to collection" and
"Remove X from collection" which show a list of all collections to
choose from. The concept of a default collection still exists and both
approaches can be used in common. However, you can specify which
commands to use for the special keys Red/Green/Blueas you like.

\subsection general General remarks

There are two main views in Muggle, the *Music browser* view and the
*Collection browser* view. You can toggle between them using the
Yellow key by default, however the key binding can be changed.

Each of the two views has associated commands. To show a summary of
the commands available for the current view press the blue key. Note,
that the red, green and yellow keys do not have a fixed
meaning. Rather, while the commands for a certain view are displayed,
you can press red/green/yellow to make the respective key execute the
command currently selected (highlighted) by the cursor. The commands
you choose for red/green/yellow will be saved for the next time you
start muggle. You can define different commands in both view *Music
browser* and *Collection browser*.

\subsection browse Music browser

By default, Muggle starts in the *Music browser* display at the place
where you left it last time. This browser displays the music library
according to a search order, e.g. according to artists / albums /
tracks or genre / year / track. These search orders are currently
fixed in the code, but the objective is to make them editable by the
user on the OSD. Browsing these search orders is done using
Up/Down/Left/Right keys. To display the contents of a currently
selected selection, press Ok. To return to the parent selection press
Back.

A set of commands can be displayed with the Blue key on the remote
control. A new menu will open and show the commands explained
below. Remember that pressing Red, Green or Yellow will make these
keys execute the command currently highlighted by the cursor from now
on.

Those commands are currently available in the *music browser*:

- Instant Play: instantly play the current selection. This does not
  enter any collection.

- Add to 'play': add the current selection to the default
  collection. After the first start of Muggle, the default collection is
  'play'

- Remove from 'play': remove the current selection from the default
  collection. If there are more than one instances of a specific track
  in the collection, they are all removed.

- Collections: switch to the collection view

- Select an order: select another search order, edit existing ones, or
  create new ones (see below)

- Export tracklist: generate a file X.m3u containing all tracks from
  the current selection

- External commands: whatever you define

By default, the red key adds the currently selected collection to the
default collection. The green key instantly plays the currently
selected collection. The yellow key toggles between the *Music
browser* and the *Collection browser*. Thus, if you want to play an
album, browse to it and press green. Remember that you can redefine
commands executed by Red, Green and Yellow by pressing them while
displaying the command list.

Muggle comes with a few default browsing orders (like artist / album
/track). Since release 0.1.2 it is possible for the user to change
these or create now ones without going into the code.  In the music
browser submenu (enter with blue while in the music browser) enter
"Select an order".  Existing search orders will be shown. Move the
cursor to any of those and press the Red button to edit it. Each key
of the current search order will be shown on a line. Move the cursor
to a line and change the search key using Left/Right buttons. Note,
that the number of key depends on what is currently selected. So keys
may appear/vanish as you cycle through the choices. This is intended
and not a bug. Play around with this a while to see, why this is
necessary. Press Ok to make your choices persistent, use back to leave
the search order editor without making any changes.

In addition, you can create new search orders using the Green key and
delete orders no longer needed using Yellow. As an exercise, try to
e.g. create orders like "Decade > Genre > Track" or "Year > Album >
Track".

\subsection collections Collection browser

The *Collection browser* displays a list of available
collections. Browse the list with Up/Down and display the collection
contents with Ok. Returning to the collection list is done by pressing
Back. One of the collections (the one called "play" when you start up
Muggle for the first time) is marked with a "->" in front of the name,
meaning that it is the default collection. Whenever you add or remove
selections, this default collection is the current target, meaning
that selections will be added/removed to/from this collection.

At the bottom of the list, the entry "Create collection" is
displayed. Entering it with the right key will make the editor appear
on the second half of the line and using the keys Up/Down/Left/Right
you can enter the name of the new collection. Pressing Ok will
terminate the editing process and add the new collection to the list.

Just like with the *music browser*, a set of commands can be displayed
with the Blue key on the remote control.

Those commands are currently available in the list of
collections. Depending on the current selection, not all of them are
available:

- Instant play: See *music browser*

- Add to 'play': See *music browser*

- Remove from 'play': See *music browser*. Not available when the
  cursor is on the default collection.

- Remove all entries from 'play': Only available when the cursor is on
  the default collection.

- Search: switch to the *music browser*

- Set default collection to 'X': as it says.

- Delete collection: Not available for the default collection and for
  the 'play' collection.

- Export track list: See *music browser*

- External commands: whatever you define

Note that you cannot only add to/remove from collections in the *music
browser*.  Rather, also collections can be added/removed. The reason
is that - as explained above - a collection is also a selection. So
everything that can be done with selections can also be done with
collections. An example: if you want to give a party, you could create
a new collection "Party". Now, steer your cursor to the collection
entitled "Lounge music" and select add. Then go to "Pop 80s" and add
again. Finally, go to "Dance classics" and add. Now you have created a
collection "Party" from three already existing collections. To
continue this example, let us assume that one of your guests has a
personal dislike against "Modern Talking". Switch to the browser view,
go to the artist selection of "Modern Talking" and select
"Remove". Now all tracks written by Modern Talking will be removed
from your "Party" collection.

Please note that "Remove" means removing from the default
collection. "Delete" will delete a collection.

It is possible that a collection holds the same track several times if
you add it several times. However when you remove that track, all of
its occurrences will be removed.

The remote buttons Play, Pause, Stop are also supported while muggle
displays its OSD. If Stop is pressed, muggle first stops playing what
was started by Instant Play. Muggle will then continue playing the
'play' collection. A second Stop will stop playing the 'play'
collection.

If instant play is used while playing the 'play' collection, the
latter will resume after instant play finishes.

*/