aacdec: raise min buffer size to 1000 bytes.
[paraslash.git] / README.mysql
index d2a27e7..e619a81 100644 (file)
@@ -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 dopey
-dbtool is still 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