Merged from 0.1.7-wr

git-svn-id: https://vdr-muggle.svn.sourceforge.net/svnroot/vdr-muggle/trunk/muggle-plugin@791 e10066b5-e1e2-0310-b819-94efdf66514b

1 files changed, 141 insertions, 85 deletions

diff --git a/README b/README
index 67004ec..1f3f4a2 100644
--- a/README
+++ b/README
@@ -28,20 +28,21 @@ 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 describedin Section 2, Notes on Compilation are in Section 3. Before using the plugin, 
+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.
 
-\section prereq PREREQUISITES
 
-The plugin currently runs on versions 1.3.17- of VDR (including 1.2.6). It also compiles on 1.3.18 
-but your mileage may vary. In addition, the following pieces of software are required:
+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:
 
- - mySQL client libraries
-   (Debian package libmysqlclient-dev or 
-    http://www.mysql.org)
- - mySQL server (tested with 4.0.18) (Debian packages mysql-server, mysql-client)
-    only needed, if you want to run the database server on a remote machine
+ - 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/)
@@ -53,11 +54,18 @@ but your mileage may vary. In addition, the following pieces of software are req
     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)
+ - 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.
@@ -74,21 +82,9 @@ Establish a symlink as you would for other plugins:
    ln -s muggle-0.1.1 muggle
 \endverbatim
 
-Adapt the Makefile to your system. Define HAVE_VORBIS and/or HAVE_FLAC and adapt
-the LIBS variable accordingly.
-
-NOTE: 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. If you want to use
-the remote server as in previous versions, you have to define the variable HAVE_SERVER
-in the Makefile by uncommenting the corresponding line.
-
-NOTE: If you have not installed the mysql server package on your machine the files
-containing error messages for MySQL you will see an error message like this:
-
-050306  9:29:14 Can't find messagefile '/usr/share/mysql/english/errmsg.sys'
-050306  9:29:14 Aborting
-
-In this case you need to obtain these files and put them there.
+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
 
@@ -99,68 +95,131 @@ Then, within the VDR main directory (e.g. /usr/local/src/VDR) issue
 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 my Debian sarge system, I had difficulties because a proper symlink for libwrap.so was
+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 WITH EMBEDDED MYSQL
+\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")
 
-The step of setting up the database and importing music has been simplified a lot
-for Muggle using the embedded MySQL server. When starting up muggle the first time
-it will determine that the database does not exist and will ask, whether to
-create the database. Confirm this with Ok. 
+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.*
 
-After successfully creating the database, muggle will query whether to import music. 
+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 music directory specified with the -t option on the command line.
+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 only while VDR is not
-running (because muggle will then block the use of the database).
+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
 
-NOTE: The embedded MySQL server cannot be used by other programs. The use of the
-GiantDisc web interface for example is not possible. 
+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.
 
-\section SET UP MUGGLE WITH REMOTE MYSQL
+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.
 
-If you already have a MySQL server running in your network (e.g. as a basis
-for a webserver) or want to access the music database with other programs
-(e.g. the GiantDisc web interface) you may be interested in using
+The simplest form for initializing (parameter -c) and populating (the rest
+on the command line) the data base is
 
-This step can be done on the database server or on some other client machine.
-The scripts in the directory scripts is no longer needed. Instead, mugglei can
-now also create new databases and provide basic information about existing languages,
-genres etc. A small utility called 'mugglei' to administer the database has been
-created along with the plugin. Run
+\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
-  mugglei -c 
+vdr  -P'muggle -t/home/music'
 \endverbatim
 
-to create a database and initialize the tables. This replaces the series of commands
-needed in former commands. If you want to change the server or database name look at
-the command line arguments (execute mugglei without arguments to see a list).
+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.
 
-\subsection importremote Import for Muggle with remote MySQL
+\section importremote IMPORTING MUSIC FILES 
 
-The next step is to feed all music information into the database. To accomplish this, mugglei
-connects to the database, evaluates ID3 tags from a file, and writes the tags into the 
-database. Since release 0.1.4 mugglei recursively descends a file system hierarchy so that 
-the use of find is no longer needed.
+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.
 
-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. Executing 
 
 \verbatim
-   mugglei *
+   mugglei -t /home/music .
 \endverbatim
 
-will import all music files (*.mp3., *.ogg, *.flac) below the current directory. Obviously,
-you may need additional options for the database host, user, etc.
-It is important that you perform various import steps from the same location so the 
-filenames are relative to exactly the same directory (e.g. /home/music in the example case).
+(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.
 
-NOTE: The options -f and -a are no longer needed. mugglei should now automatically do the right thing.
+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:
 
@@ -170,30 +229,24 @@ If a track has no ID3 tags, the following defaults will be applied:
 - Track: 0
 - Year: 0
 
-\section config MUGGLE CONFIGURATION
-
-In case you use mugglei with the embedded MySQL server the most important
-options are -d DIR (controls where the database file is created) and
--t DIR (controls where the music resides).
+\section covers COVERS
 
-When using the remote MySQL server, 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:
+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.
 
-\verbatim
-  -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. 
+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.
 
-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).
-
-In case you want to use Muggle with the embedded MySQL server, specify the
-directory to place the database into with the option -d DIR.
+During installation, make sure that the script called image_convert.sh
+(from the scripts directory) is somewhere on your path.
 
 \section quickuse QUICK INTRO
 
@@ -382,4 +435,7 @@ 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.
+
 */