X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=blobdiff_plain;f=README.mysql;h=e619a814bc827a566fc5a2df766f7246fb53d64b;hp=7af828073e3621385ac3db5cf69e3bb63b491bc7;hb=446f934790d9d60b4aaa63faa41217fa8134a4be;hpb=c589157169366fa47f2041cfe52e7019fbc19b35 diff --git a/README.mysql b/README.mysql index 7af82807..e619a814 100644 --- a/README.mysql +++ b/README.mysql @@ -1,8 +1,8 @@ README.mysql ============ -This file describes how to use the mysql database tool which comes -with the paraslash package. +This file describes how to use the mysql audio file selector which +comes with the paraslash package. It assumes you have already installed mysql and paraslash as described in INSTALL, so read README and INSTALL before proceeding. @@ -10,15 +10,19 @@ in INSTALL, so read README and INSTALL before proceeding. First of all, make sure that - mysqld is running - - para_server is running and compiled with mysql support (type - "para_client si" to find out) - - the user who runs para_client has the paraslash DB_WRITE and DB_READ - permissions set in server.users - - the user who runs para_server has create privileges on the mysql - server. -Remember: If something doesn't work as expected, look at the server log file -and/or increase output verbosity by using the -l switch for server and client. + - para_server is running and compiled with mysql support + (type "para_client si" to find out) + + - the user who runs para_client has the paraslash DB_WRITE + and DB_READ permissions set in server.users + + - the user who runs para_server has create privileges on the + mysql server. + +Remember: If something doesn't work as expected, look at the server +log file and/or increase output verbosity by using the -l switch for +server and client. Specify mysql data (port, passwd,...) @@ -41,39 +45,41 @@ effect you'll need to do Or, restart the server. -Switch to the mysql dbtool -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Switch to the mysql audio file selector +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Actually, the mysql database tool should already be selected (just -ignore the warning about the missing database). To verify that it is -indeed activated, type +The command - para_client cdt + para_client chs -which prints the name of the current database tool. If the mysql -dbtool is not selected, try +prints the name of the current selector. Try - para_client cdt mysql + para_client chs mysql -If this doesn't work either, it means that some required config options -were not specified (check the log for more info) or that para_server -was built without mysql support. Type +to switch to the mysql selector. If this doesn't work, it means that +some required config options were not specified (check the log for +more info) or that para_server was built without mysql support. Type para_client si -to find out. If mysql is not mentioned as a supported database tool, -you'll have to recompile. +to find out. If mysql is not mentioned as a supported selector, +you'll have to recompile. If configure does not detect your mysql +installation, use the --enable-mysql-headers and --enable-mysql-libs +options to specify the mysql path explicitly . Example: + + ./configure --enable-mysql-headers=/Library/MySQL/include \ + --enable-mysql-libs=/Library/MySQL/lib/mysql Create a new database ~~~~~~~~~~~~~~~~~~~~~ -Once the mysql database tool is selected, create the database: +Once the mysql selector is activated, create the database: para_client cdb - para_client cdt mysql + para_client chs mysql -The second command forces para_server to re-init the mysql dbtool. +The second command forces para_server to re-init the mysql selector. Check the log. There should not be any warnings or errors. @@ -82,16 +88,18 @@ Fill your database with content para_client upd +Note that the mysql selector assumes that the basenames of your audio +files are unique. If this is not the case, duplicates are ignored. + If this command fails, it most likely means the audio file directory (given in the server configuration file) does not exist, is empty, -not readable, or contains different files with identical basenames. Fix -this problem before proceeding. +or not readable. Fix this problem before proceeding. The command para_client ls -prints the list of all files known by the mysql dbtool. If the list +prints the list of all files known by the mysql selector. If the list is empty, double check the mysql_audio_file_dir option. @@ -120,7 +128,7 @@ You should now be able to start streaming with Attribute usage ~~~~~~~~~~~~~~~ -An attribute is simply a bit which can be set for each sound file +An attribute is simply a bit which can be set for each audio file individually. You may have as many attributes as you like. A new attribute "test" is created by @@ -130,30 +138,30 @@ and para_client laa lists all available attributes. You can set the "test" attribute for -the current song by executing +the current audio file by executing para_client sa test+ -or for any particular song by +or for any particular audio file by para_client sa test+ filename -You can unset the attribute "test" for the current song with +Unset the attribute "test" for the current audio file with - para_client sa test- + para_client sa test- -and you can drop the test attribute entirely from the database with +and drop the test attribute entirely from the database with para_client da test Stream usage ~~~~~~~~~~~~ -A stream is a pair of expressions in terms of attributes and other -meta data contained in the database. The first, boolian, expression -determines the set of songs which are permitted in this stream. The -second, integer, expression determines the order in which permitted -songs are going to be fed to the audio file sender(s). +A stream is a pair of expressions in terms of attributes and other data +contained in the database. The first, boolian, expression determines +the set of audio files which are admissible in this stream. The second, +integer, expression determines the order in which admissible files +are going to be fed to the audio file sender(s). To create a new stream called "my_stream", put arbitrary many (including none) accept or deny lines and one or zero score lines into some @@ -163,7 +171,7 @@ expression. The command para_client stradd my_stream < tmpfile -adds the stream "my_stream" to dbtool's stream database. +adds the stream "my_stream" to the table of streams. If the stream definition is really short, you may also just pipe it to the client rather than using temporary files. Like this: @@ -173,9 +181,9 @@ the client rather than using temporary files. Like this: Example: - Assume you already have an attribute "test" and you'd like to - to restrict the set of songs being played to those having the - "test" attribute set. Define a new stream "only_test" by + Assume you already have an attribute "test" and you'd like to + to restrict audio streaming to those files having the "test" + attribute set. Define a new stream "only_test" by echo 'accept: IS_SET(test)' | para_client stradd only_test @@ -183,10 +191,10 @@ Example: para_client cs only_test - only the desired songs are going to be played. + only the desired files are going to be streamed. There is no need to keep the temporary files containing the stream -definition since you can always query the database to get it back: +definition since you can always use the strq command to get it back: para_client strq only_test @@ -263,8 +271,8 @@ You can then switch to the new stream with or you can let cron do this for you on a daily basis.. -Accept/deny lines affect only the set of admissible songs, but not -the order in which these songs are played. That's where the score +Accept/deny lines affect only the set of admissible audio files, +but not the order in which these are streamed. That's where the score expression comes into play. Scoring @@ -279,32 +287,32 @@ definition or as the default scoring rule in the config file) include: LASTPLAYED()/1440 -This means that each song's score is just the number of days that went -by since this song has been played (one day is 1440 minutes). This -is fine in many cases since the dbtool then always chooses that -admissible song, which wasn't played for the longest time. +This means that the score of an audio file is just the number of days +that went by since it has been played the last time (one day is 1440 +minutes). In other words, the mysql selector choses that admissible +file which wasn't played for the longest time. -However, one disadvantage of this scoring sheme is that new songs, +However, one disadvantage of this scoring sheme is that new files, once played, are going to be deferred for a possibly very long period -depending on the size of your collection of (admissible) songs. Hence +depending on the size of your collection of (admissible) files. Hence the following scoring rule comes into mind: - score: -NUMPLAYED() + score: -NUMPLAYED() -since this gives newer songs, i.e. songs to which you haven't listen to +since this gives newer files, i.e. files to which you haven't listen to that often, a higher score than older songs you already know by heart. You can also use a combination of these two methods: - score: LASTPLAYED()/1440 - 10 * NUMPLAYED() + score: LASTPLAYED()/1440 - 10 * NUMPLAYED() which subtracts 10 score points for each time paraslash has played -this song. +this file. -Another useful feature for scoring is due to the fact that "true" -expands to one and "false" to zero. So you can also use the -IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give -your favorite band "bar" some extra points: +Another useful feature for scoring is due to the fact that +"true" expands to one and "false" to zero. So you can also use the +IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give your favorite +band "bar" some extra points: score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440 @@ -312,9 +320,9 @@ your favorite band "bar" some extra points: Pictures ~~~~~~~~ -dbtool can also magage images that, when associated with certain songs, -can be displayed by para_sdl_gui and para_krell when one of these songs -is playing. It is also possible to just retrieve the current image via +The mysql selector can also magage images that, when associated +with one or more audio files, can be displayed by para_sdl_gui and +para_krell. It is also possible to just retrieve the current image via para_client pic > filename