git-svn-id: https://vdr-muggle.svn.sourceforge.net/svnroot/vdr-muggle/branches/0.1.3-wr@506 e10066b5-e1e2-0310-b819-94efdf66514b

1 files changed, 399 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..dd0d00c
--- /dev/null
+++ b/README
@@ -0,0 +1,399 @@
+/*! \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 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 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:
+
+ - 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 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.
+
+\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. Define HAVE_VORBIS and/or HAVE_FLAC and adapt the LIBS variable accordingly.
+
+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.
+
+\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 musictype;" | \
+      mysql -u root --local-infile=1
+
+   echo "use GiantDisc; load data local infile 'sources.txt' into table source;" | \
+      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 after making necessary modification (program paths, database names, servers, users, etc.).
+
+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 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. There has been discussion
+about this and ideas for better solutions are welcome.
+
+For now, let's assume your music tracks are located in /home/music and samplers are in /home/music/Assorted.
+
+First, 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.
+
+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 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
+  -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 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.
+
+*/