path: root/README

/*! \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://www.htpc-tech.de/htpc/muggle.htm

Latest version available at: http://www.htpc-tech.de/htpc/muggle-dev.htm

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

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 relase 0.1.8 Muggle is able to display cover pictures. The required packages are 
 - mjpegtools (Debian package mjpegtools. This is not a standard Debian package. You can get it by 
   adding this line to /etc/apt/sources.list: "deb ftp://ftp.nerim.net/debian-marillat/ stable main")
 - netpbm (Debian package netpbm)

\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.1.tgz
\endverbatim

Establish a symlink as you would for other plugins:

\verbatim
   ln -s muggle-0.1.1 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, HAVE_FLAC, HAVE_SNDFILE as wanted 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.
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 slighlty 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. This is how it tries to find them:
1. if the database field album.coverimg contains something: This is 
   displayed. If the image file does not exist, show an error.
2. else: take the track filename and replace its extension by .jpg
   if this file exists, display it
3. else try the file "cover.jpg" in the current directory. If it
   does not exist, try parent directory. Repeat until the TLD is
   reached.

So if you want a default background for all tracks you should put it 
into TLD/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.

During installation, make sure that the script called image_convert.sh
(from the scripts directory) is somewhere on your path.

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

During playback, Up/Down jumps forth and back in the current playlist. Yellow 
toggles play/pause mode and Ok toggles a display of the replay process. Using
Green, the display can be switched between playlist and single display mode,
Red toggles info and progress view. For VDR 1.3.6- the progress display is
"quite simple", unfortunately.

\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 spceify 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 intented
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.

*/