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.
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,...)
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.
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.
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 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
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
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
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
projects / paraslash.git / blobdiff