Makefile.in: add targets for man page generation

[paraslash.git] / README.mysql

============
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 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

        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 --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:

        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.