+++ /dev/null
-============
-README.mysql
-============
-
-----
-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 AFS_WRITE
- and AFS_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
-
- para_server -h
-
-and look at the mysql options. You may either specify these options
-in ~/.paraslash/server.conf or directly at the command line (not
-recommended for passwd option). Don't forget to do
-
- chmod 600 ~/.paraslash/server.conf
-
-as this file contains the mysql passwd. To make these changes take
-effect you'll need to do
-
- para_client hup
-
-Or, restart the server.
-
----------------------------------------
-Switch to the mysql audio file selector
----------------------------------------
-
-The command
-
- para_client chs
-
-prints the name of the current selector. Try
-
- para_client chs mysql
-
-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 selector,
-you'll have to recompile. If configure does not detect your mysql
-installation, use the --with-mysql-headers and --with-mysql-libs
-options to specify the mysql path explicitly . Example:
-
- ./configure --with-mysql-headers=/Library/MySQL/include \
- --with-mysql-libs=/Library/MySQL/lib/mysql
-
-
----------------------
-Create a new database
----------------------
-
-Once the mysql selector is activated, create the database:
-
- para_client cdb
- para_client chs mysql
-
-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,
-or not readable. Fix this problem before proceeding.
-
-The command
-
- para_client ls
-
-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
----------------------------------------
-
-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
-
-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
-attribute "test" is created by
-
- para_client na test
-
-and
- para_client laa
-
-lists all available attributes. You can set the "test" attribute for
-the current audio file by executing
-
- para_client sa test+
-
-or for any particular audio file by
-
- para_client sa test+ filename
-
-Unset the attribute "test" for the current audio file with
-
- para_client sa test-
-
-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
-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
-temporary file, say tmpfile. An accept/deny/score line consists of
-an identifier ("accept:", "deny:", or "score:"), followed by an
-expression. The command
-
- para_client stradd my_stream < tmpfile
-
-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:
-
- echo "$MYSTREAMDEF" | para_client stradd my_stream
-
-
-Example:
-~~~~~~~~
-
-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
-
-Then, after switching to the "only_test" stream with
-
- para_client cs only_test
-
-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:
-
- para_client strq only_test
-
-The accept/deny expressions are used to find out which songs are
-permitted. The following four cases are all possible and valid:
-
- - Neither accept nor deny lines: This selects all songs.
-
- - Only accept lines: Songs that match at least one accept
- expression are accepted, all others are denied:
-
- accept_expr1 or accept_expr2 or ...
-
- - Only deny lines: Songs that match at least one deny expression are
- denied, all others are accepted:
-
- not (deny_expr1 or deny_expr2 ...)
-
- - 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 ..)
-
-The command
-
- para_client streams
-
-lists all available streams and
-
- para_client strdel streamname
-
-removes the stream "streamname".
-
-There are more sophisticated ways to define a stream than just using
-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:
-
- - 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
-have set these attributes for some or all of your songs having the
-corresponding properties.
-
-If you like to be waked up in the morning by poprock songs, but you
-have some strange feeling telling you that just a few seconds of
-Madonna's voice will be enough to mess up your whole day, just write
-the lines
-
- accept: IS_SET(pop) and IS_SET(rock)
- deny: NAME_LIKE(%Madonna%)
-
-to some temporary file "tmp" and do
-
- para_client stradd wake < tmp
-
-You can then switch to the new stream with
-
- para_client cs wake
-
-or you can let cron do this for you on a daily basis..
-
-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,
-the compiled in default is going to be used (see para_server -h).
-
-Simple examples of scoring rules (either specified in a stream
-definition or as the default scoring rule in the config file) include:
-
- LASTPLAYED()/1440
-
-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 files,
-once played, are going to be deferred for a possibly very long period
-depending on the size of your collection of (admissible) files. Hence
-the following scoring rule comes into mind:
-
- score: -NUMPLAYED()
-
-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()
-
-which subtracts 10 score points for each time paraslash has played
-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:
-
- score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
-
-------
-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
-para_krell. It is also possible to just retrieve the current image via
-
- para_client pic > filename
-
-in order to feed it to your favorite tool. Try
-
- para_client help | grep ^pic
-
-and read the online help of the shown commands for more information.
projects / paraslash.git / commitdiff