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>, 

Project's homepage:          http://www.htpc-tech.de/htpc/muggle.htm

Latest version available at: http://www.htpc-tech.de/htpc/muggle_archive/vdr-muggle-0.0.8-BETA.tgz

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 ack Acknowledgements

Thanks to all who have supported the development of this plugin. Special thanks (order does not mean importance :-) go to
- Muempf for the mp3 plugin. All code related to audio replay is largely taken over from this plugin.
- LordJaxom for constant support in the chat of VDR portal regarding OSD programming in VDR
- eloy (member of vdrportal.de) for alpha testing
- All beta testers at vdrportal.de and on the VDR mailing list
- decembersoul (member of vdrportal.de) for finding out how to run muggle on LinVDR
- Hulk (member of vdrportal.de) for submitting several patches (especially for gLCD display)

\section desc DESCRIPTION

The muggle plugin provides a database link for VDR so that selection of media becomes more flexible.
Prerequisites are describedin 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.

\section prereq PREREQUISITES

The plugin has been tested with VDR versions up to 1.3.12. In addition, the following pieces of 
software are required:

 - mySQL server (tested with 4.0.18) (Debian packages mysql-server, mysql-client)
 - mySQL client libraries
   (Debian package libmysqlclient-dev or 
    http://www.mysql.org)
 - 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
   (Debian packages  or
    http://www.xiph.org/ogg/vorbis/)

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. In my personal setup, the mySQL
database runs on a server where also all music files are stored. Muggle accesses them via Samba.

\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.7.tar.bz2
\endverbatim

Establish a symlink as you would for other plugins:

\verbatim
   ln -s muggle-0.1.7 muggle
\endverbatim

Note that the actual directory names may vary, e.g. the version number will changes. Within the VDR main directory (e.g. /usr/local/src/VDR) issue a 

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

\section import IMPORT

The import is done in two steps: First, a database is created and initialized with proper data structures (so-called schema). Then, these data structures are filled from the ID3 tags of your music tracks.

\subsection dbsetup Setup Database

This step can be done on the database server or on some other client machine.
Within the directory scripts there are a few helpful files to support setting
up the database. Change into that directory:

\verbatim
   cd scripts
\endverbatim

The first step is to essentially create the database:

\verbatim
   mysql -u root -p < createdb.mysql
\endverbatim

You will need to enter your root password that you choose during mySQL installation.
Next, we generate the database tables (schema):

\verbatim
   mysql -u root -p < createtables.mysql 
\endverbatim

Further, initial data about known languages, genres, sources and musictypes is fed into the database:
Execute these commands on a single line, the \ for the linebreak ist just for presentation purposes here.

\verbatim
   echo " use GiantDisc; load data local infile 'genres.txt' into table genre;" | \
      mysql -u root -p  --local-infile=1

   echo "use GiantDisc; load data local infile 'languages.txt' into table language;" | \
      mysql -u root --local-infile=1

   echo "use GiantDisc; load data local infile 'musictypes.txt' into table language;" | \
      mysql -u root --local-infile=1

   echo "use GiantDisc; load data local infile 'sources.txt' into table language;" | \
      mysql -u root --local-infile=1
\endverbatim

You can find the sequence of commands in the file scripts/make-empty-db. Use it at your own luck.

Please note, that the scripts and commands above are quite basic in terms of security (e.g. no
password set for the vdr user, no proper selection of privileges). You may want to spend some
time reading the mySQL documentation in order to set up a proper configuration. Especially when
VDR and mySQL will run on different machines you'll have to invest some time into mySQL
networking and access rights.

If you want your database name to be different than 'GiantDisc' you will need to adapt the name
in the files createdb.mysql and createtables.mysql and in the commands above. Now your database
is ready for import.

\subsection importfile Import Music

The next step is to feed all music information into the database. There is a small tool called 'mugglei'
in the muggle main directory. It connects to the database, evaluates ID3 tags from a file, and writes
the tags into the database. It runs on just one file, so you need some more effort using the Unix command
'find' to take all files into consideration. 

For this step, it is helpful, that all music files are somehow gathered under a toplevel directory.
It does not matter whether there are further subdirectories which organize files into genres, artists,
album or whatever. If this is not the case, you may want to take some time to do this. Read on before
you start

You probably do not want to import all files in one go: albums on which tracks of various artists are
found (samplers) require different treatment than albums containing files of just one artist. What I did:
all samplers are collected below a special subdirectory "Assorted". Import is then run separately for those
tracks.

For now, let's assume your music tracks are located in /home/music and samplers are in /home/music/Assorted.

First, let's import the files in Assorted. This requires the flag -a to mugglei. Further flags -h, -n, -u, and -p
specify database host, name, user and password, respectively. The filename to import is given using the -f
directive. Using 'find' you can import all files for assorted albums with a command like:

\verbatim
   find Assorted -name '*' -type f -exec mugglei -a -f {} \;
\endverbatim

For reasons of simplicity, the arguments -h, -n, -u and -p are not shown. You will need them if the default
values do not apply or modify the source code accordingly (beginning of function main). Also, make sure 
that either mugglei is on your path or specify an absolute or relative path in the above command line.

For "regular" albums, the following command may be helpful:

\verbatim
   find * -path 'Assorted' -prune -o -type f -exec mugglei -f {} \;
\endverbatim

It is important that you perform all these steps from the same location so the filenames are relative to
exactly the same directory (e.g. /home/music in the example case).

Speed should not be an issue: on my machine, it takes about 10 secs to run the import of 60 assorted
albums with more than 600 tracks. Further 1200 tracks or so require 20 more secs. This depends on machine
configuration, of course.

\section config MUGGLE CONFIGURATION

Muggle uses a small set of command line parameters in order to control the interaction with the mySQL server.
Let's look at an example:

\verbatim
  vdr -P'muggle -h localhost -u vdr -n GiantDisc -t/home/music'
\endverbatim

The -h parameter specifies the database host, -u specifies the user, -n is the database name. The scripts mentioned
above do not make use of passwords, but restrict database acccess on a server basis. 

The -t argument specifies the top level directory of the music files. On a local installation, this is the
directory in which you executed the import steps (Chapter 4.2).

\section use USING MUGGLE - QUICK OVERVIEW

Quick version: select Muggle on the OSD, browse titles (using up/down and Ok), add them using the red button.
Then turn to the playlist view using yellow and start play using again the red function key.

During playback, Up/Down jumps forth and back in the current playlist. Yellow toggles play/pause mode and Ok
brings up a progress display. For VDR 1.3.6- the progress display is "quite simple".

\section use-detail USING MUGGLE

The idea behind muggle and the concept of the GUI was driven by the requirement, that almost all funtionalities must be possible with only using the cursor keys, the colour keys and menu, ok and back. 

Muggle consist of three main views. The different views could always be switched with the yellow key. In every view there is a context sensitive menu with certain commands suitable for the current view. This menu could be reached from every view with the blue key. The two most common commands for a view could be reached with the remaining two colour keys red and green.

In all views the cursor keys are used like in every VDR menu.

That is all you have to know to get full access to all functions of muggle. So now lets look in more detail in the three different views.

\subsection browserview BROWSER VIEW

The Browser view will be the most used view within muggle. It presents all stored media within the database in a sort of tree view. A tree consist of nodes wich have child nodes which are also nodes. A leaf of such a tree consist of one single media file. Just to make it clear beneath a node there are on the bottom line at least on, but in the higher regions of the tree several media files.

At present there are 5 different main trees:
- artist -> album -> title
- genre -> artist -> album -> tilte
- artist -> title
- genre -> year -> title
- album -> title

To add all songs from Abba to the active playlist just use the "artist -> title" tree and look for Abba in the resulting list. Press OK and here you are. All songs from Abba which are stored in the database are shown on the screen and the higlighted one could be added with the red key (you remember: most common commands are on red/green) to the active playlist. If you want to add all songs from Abba to the active playlist just go up one level, Abba is highlighted and then press red and ready you are.

With the green colour key you could easily reach the main trees (this is not implemented yet).

Thats all you have to know about this view. Please keep in mind that red adds always _ALL_ songs beneath the current node to the active playlist. So pressing red on one of the main trees leads to adding _ALL_ media files within the database (this could be thousands) to the active playlist. 

\subsection playlistview PLAYLIST VIEW

In this view you see the active playlist. All songs currently added to the playlist are shown here. With the blue colour key you can reach the context sensitive menu. Here you can find some actions to modify, load, or save the playlist, clear all entries and many others. In detail the commands are
- Red: start playing the list from the beginning or at the last played song (cf. section Replay)
- Green: Move the current entry to reorder the playlist

In the submenu the following commands can be selected:
- Rename playlist: change the playlist name using the up/down cursor keys
- Load playlist: show playlists in the database and load one (using Ok)
- Save playlist: Store the current playlist status into the database
- Clear playlist: Remove all entries from the playlist
- Delete current entry: Remove the currently selected entry from the playlist
- Export playlist: export the playlist in m3u (version 2) into the muggle config directory as <listname>.m3u
- Playlist commands: similar to commands.conf or reccmds.conf for VDR a file containing commands to execute on a playlist can be specified in a file playlist_commands.conf which must reside in the muggle config directory. The commands listed in that file will be called with one argument which is the path of the playlist file in m3u (version 2).

\subsection searchview SEARCH VIEW

The search view is a more advanced method to look into the content of your database. If you search for all songs from Abba which are rated "++" this is your tool. You could find three different search methods which are descripte later. You switch betweeen this search methods with the green colour key.

\subsubsection titlesearch TITLE SEARCH

If you want to search for a single media file, this is for you. You could insert some search criteria and after pressing the red button you see all media files which fullfill the restrictions.

Example: Search for all songs from Abba which have "water" in the title an are publisched befor 2000.

 Artist:     Abba
 Title:      water
 Year(till): 2000

\subsubsection albumsearch ALBUM SEARCH

If you want to search for a certain album and are interested in all songs of that album even if the songs not fullfill the search criteria, than this search is for you.

Example: Search for all songs on an album from "U2" with "tree" in the album title.

 Album Title: tree
 Album Artist: U2

\subsubsection playlistsearch PLAYLIST SEARCH

If you want to search for a playlist wích contains songs which fullfill the criteria.

Example: Yesterday during your birthday party you played a song from Tina Turner during your party, your best friend is interested in the song which was played just behind that Tina Turner song. The search presents all titles of that playlist. You could easily browser the list, find Tinas song and you have the one behind.

 Playlist Title: Birthday Party 2004
 Artist:         Tina Turner

\subsection useplayer DURING PLAYBACK

The functions available furing playback mostly relate to navigation in the playlist
and displaying information about the current track or playlist.

- Up: Skip to the next title
- Down: Skip to the previous title
- Ok: toggle display (progress or information view)

- Red: When display shown: toggle between progress and information view, otherwise toggle loop mode (not yet functional)
- Green: When display shown: toggle between track and playlist view, otherwise toggle shuffle mode (not yet functional)
- Yellow: Play/Pause
- Blue: stop replay but remind resume index (so Play from browser view starts with the track played last)

- Back: stop replay (Play from browser will start from the beginning)

*/