recv.c: Make rn_event_handler() static
[paraslash.git] / README.mysql
index 92c8c6d..87ee27b 100644 (file)
@@ -1,6 +1,8 @@
+============
 README.mysql
 ============
 
+----
 This file describes how to use the mysql audio file selector which
 comes with the paraslash package.
 
@@ -10,19 +12,20 @@ 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,...)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------
 
 Type
 
@@ -41,8 +44,9 @@ effect you'll need to do
 
 Or, restart the server.
 
+---------------------------------------
 Switch to the mysql audio file selector
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------
 
 The command
 
@@ -59,11 +63,17 @@ 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 selector,
-you'll have to recompile.
+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 selector is activated, create the database:
 
@@ -73,16 +83,18 @@ Once the mysql selector is activated, create the database:
 The second command forces para_server to re-init the mysql selector.
 Check the log. There should not be any warnings or errors.
 
-
+-------------------------------
 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
 
@@ -91,21 +103,21 @@ The command
 prints the list of all files known by the mysql selector. If the list
 is empty, double check the mysql_audio_file_dir option.
 
+---------------------------------------
+Create a stream which selects all files
+---------------------------------------
 
-Create a stream which selects all songs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To keep it simple, let's only define the stream "all_songs". See below for
-advanced stream usage.
+To keep it simple, let's only define the stream "all_songs". See
+below for advanced stream usage.
 
        para_client stradd all_songs < /dev/null
        para_client sl 10 all_songs
 
 The latter command should show you ten filenames.
 
-
+------------------------------
 Change to the all_songs stream
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
        para_client cs all_songs
 
@@ -113,9 +125,9 @@ You should now be able to start streaming with
 
        para_client play
 
-
+---------------
 Attribute usage
-~~~~~~~~~~~~~~~
+---------------
 
 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
@@ -143,8 +155,9 @@ 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 data
 contained in the database. The first, boolian, expression determines
@@ -169,18 +182,19 @@ 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
+       echo 'accept: IS_SET(test)' | para_client stradd only_test
 
-       Then, after switching to the "only_test" stream with
+Then, after switching to the "only_test" stream with
 
-               para_client cs only_test
+       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 use the strq command to get it back:
@@ -190,20 +204,20 @@ definition since you can always use the strq command to get it back:
 The accept/deny expressions are used to find out which songs are
 permitted. The following four cases are all possible and valid:
 
-       o Neither accept nor deny lines: This selects all songs.
+       - Neither accept nor deny lines: This selects all songs.
 
-       o Only accept lines: Songs that match at least one accept
-       expression are accepted, all others are denied:
+       - Only accept lines: Songs that match at least one accept
+         expression are accepted, all others are denied:
 
                accept_expr1 or accept_expr2 or ...
 
-       o Only deny lines: Songs that match at least one deny expression are
-       denied, all others are accepted:
+       - Only deny lines: Songs that match at least one deny expression are
+         denied, all others are accepted:
 
                not (deny_expr1 or deny_expr2 ...)
 
-       o Both accept and deny lines: A song is accepted if it matches
-       at least one accept expression, but no deny expression, i.e.
+       - Both accept and deny lines: A song is accepted if it matches
+         at least one accept expression, but no deny expression, i.e.
 
                (accept_expr1 or accept_expr2 or ..) and not
                        (deny_expr1 or deny_expr2 ..)
@@ -223,19 +237,15 @@ one IS_SET() macro as in the example above. Of course, IS_SET(foo)
 is true for a given audio file if and only if it has the attribute
 "foo" set.  Here are some more macros you can use:
 
-       o IS_N_SET(attr): True if attribute attr is not set
-
-       o NAME_LIKE(string): True if basename is like (in the sense
-       of mysql) "string"
-
-       o LASTPLAYED(): Expands to number of minutes that are gone
-       since this audio file has been played (by paraslash).
-
-       o NUMPLAYED(): Expands to number of times, the file has
-       been played.
-
-       o PICID(): Expands to the number of the picture which is
-       associated with this song.
+       - IS_N_SET(attr): True if attribute attr is not set
+       - NAME_LIKE(string): True if basename is like (in the sense
+         of mysql) "string"
+       - LASTPLAYED(): Expands to number of minutes that are gone
+         since this audio file has been played (by paraslash).
+       - NUMPLAYED(): Expands to number of times, the file has
+         been played.
+       - PICID(): Expands to the number of the picture which is
+         associated with this song.
 
 To give a real-life example, suppose you have already added the
 attributes "pop", "rock" with the "na" command. Assume also that you
@@ -260,12 +270,14 @@ 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
-~~~~~~~
+-------
+
 You may put a single score line anywhere in the stream definition. If
 omitted, the default scoring rule specified in the configuration file
 applies. If there is no default scoring rule in the config file either,
@@ -305,9 +317,9 @@ band "bar" some extra points:
 
        score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
 
-
-Pictures
-~~~~~~~~
+------
+Images
+------
 
 The mysql selector can also magage images that, when associated
 with one or more audio files, can be displayed by para_sdl_gui and