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.
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,
+to find out. If mysql is not mentioned as a supported selector,
you'll have to recompile.
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.
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.
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
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
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:
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 the set of songs being played to those having the
+ "test" attribute set. Define a new stream "only_test" by
echo 'accept: IS_SET(test)' | para_client stradd only_test
only the desired songs are going to be played.
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
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
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