README.mysql

   1 README.mysql
   2 ============
   3
   4 This file describes how to use the mysql audio file selector which
   5 comes with the paraslash package.
   6
   7 It assumes you have already installed mysql and paraslash as described
   8 in INSTALL, so read README and INSTALL before proceeding.
   9
  10 First of all, make sure that
  11
  12         - mysqld is running
  13
  14         - para_server is running and compiled with mysql support
  15         (type "para_client si" to find out)
  16
  17         - the user who runs para_client has the paraslash DB_WRITE
  18         and DB_READ permissions set in server.users
  19
  20         - the user who runs para_server has create privileges on the
  21         mysql server.
  22
  23 Remember: If something doesn't work as expected, look at the server
  24 log file and/or increase output verbosity by using the -l switch for
  25 server and client.
  26
  27
  28 Specify mysql data (port, passwd,...)
  29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  30
  31 Type
  32
  33         para_server -h
  34
  35 and look at the mysql options. You may either specify these options
  36 in ~/.paraslash/server.conf or directly at the command line (not
  37 recommended for passwd option). Don't forget to do
  38
  39         chmod 600 ~/.paraslash/server.conf
  40
  41 as this file contains the mysql passwd. To make these changes take
  42 effect you'll need to do
  43
  44         para_client hup
  45
  46 Or, restart the server.
  47
  48 Switch to the mysql audio file selector
  49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  50
  51 The command
  52
  53         para_client chs
  54
  55 prints the name of the current selector. Try
  56
  57         para_client chs mysql
  58
  59 to switch to the mysql selector. If this doesn't work, it means that
  60 some required config options were not specified (check the log for
  61 more info) or that para_server was built without mysql support. Type
  62
  63         para_client si
  64
  65 to find out. If mysql is not mentioned as a supported selector,
  66 you'll have to recompile.
  67
  68
  69 Create a new database
  70 ~~~~~~~~~~~~~~~~~~~~~
  71
  72 Once the mysql selector is activated, create the database:
  73
  74         para_client cdb
  75         para_client chs mysql
  76
  77 The second command forces para_server to re-init the mysql selector.
  78 Check the log. There should not be any warnings or errors.
  79
  80
  81 Fill your database with content
  82 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  83
  84         para_client upd
  85
  86 If this command fails, it most likely means the audio file directory
  87 (given in the server configuration file) does not exist, is empty,
  88 not readable, or contains different files with identical basenames. Fix
  89 this problem before proceeding.
  90
  91 The command
  92
  93         para_client ls
  94
  95 prints the list of all files known by the mysql selector. If the list
  96 is empty, double check the mysql_audio_file_dir option.
  97
  98
  99 Create a stream which selects all songs
 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 101
 102 To keep it simple, let's only define the stream "all_songs". See below for
 103 advanced stream usage.
 104
 105         para_client stradd all_songs < /dev/null
 106         para_client sl 10 all_songs
 107
 108 The latter command should show you ten filenames.
 109
 110
 111 Change to the all_songs stream
 112 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 113
 114         para_client cs all_songs
 115
 116 You should now be able to start streaming with
 117
 118         para_client play
 119
 120
 121 Attribute usage
 122 ~~~~~~~~~~~~~~~
 123
 124 An attribute is simply a bit which can be set for each audio file
 125 individually. You may have as many attributes as you like. A new
 126 attribute "test" is created by
 127
 128         para_client na test
 129
 130 and
 131         para_client laa
 132
 133 lists all available attributes. You can set the "test" attribute for
 134 the current audio file by executing
 135
 136         para_client sa test+
 137
 138 or for any particular audio file by
 139
 140         para_client sa test+ filename
 141
 142 Unset the attribute "test" for the current audio file with
 143
 144         para_client sa test-
 145
 146 and drop the test attribute entirely from the database with
 147
 148         para_client da test
 149
 150 Stream usage
 151 ~~~~~~~~~~~~
 152
 153 A stream is a pair of expressions in terms of attributes and other data
 154 contained in the database. The first, boolian, expression determines
 155 the set of audio files which are admissible in this stream. The second,
 156 integer, expression determines the order in which admissible files
 157 are going to be fed to the audio file sender(s).
 158
 159 To create a new stream called "my_stream", put arbitrary many (including
 160 none) accept or deny lines and one or zero score lines into some
 161 temporary file, say tmpfile. An accept/deny/score line consists of
 162 an identifier ("accept:", "deny:", or "score:"), followed by an
 163 expression. The command
 164
 165         para_client stradd my_stream < tmpfile
 166
 167 adds the stream "my_stream" to the table of streams.
 168
 169 If the stream definition is really short, you may also just pipe it to
 170 the client rather than using temporary files. Like this:
 171
 172         echo "$MYSTREAMDEF" | para_client stradd my_stream
 173
 174
 175 Example:
 176
 177         Assume you already have an attribute "test" and you'd like to
 178         to restrict audio streaming to those files having the "test"
 179         attribute set. Define a new stream "only_test" by
 180
 181                 echo 'accept: IS_SET(test)' | para_client stradd only_test
 182
 183         Then, after switching to the "only_test" stream with
 184
 185                 para_client cs only_test
 186
 187         only the desired files are going to be streamed.
 188
 189 There is no need to keep the temporary files containing the stream
 190 definition since you can always use the strq command to get it back:
 191
 192         para_client strq only_test
 193
 194 The accept/deny expressions are used to find out which songs are
 195 permitted. The following four cases are all possible and valid:
 196
 197         o Neither accept nor deny lines: This selects all songs.
 198
 199         o Only accept lines: Songs that match at least one accept
 200         expression are accepted, all others are denied:
 201
 202                 accept_expr1 or accept_expr2 or ...
 203
 204         o Only deny lines: Songs that match at least one deny expression are
 205         denied, all others are accepted:
 206
 207                 not (deny_expr1 or deny_expr2 ...)
 208
 209         o Both accept and deny lines: A song is accepted if it matches
 210         at least one accept expression, but no deny expression, i.e.
 211
 212                 (accept_expr1 or accept_expr2 or ..) and not
 213                         (deny_expr1 or deny_expr2 ..)
 214
 215 The command
 216
 217         para_client streams
 218
 219 lists all available streams and
 220
 221         para_client strdel streamname
 222
 223 removes the stream "streamname".
 224
 225 There are more sophisticated ways to define a stream than just using
 226 one IS_SET() macro as in the example above. Of course, IS_SET(foo)
 227 is true for a given audio file if and only if it has the attribute
 228 "foo" set.  Here are some more macros you can use:
 229
 230         o IS_N_SET(attr): True if attribute attr is not set
 231
 232         o NAME_LIKE(string): True if basename is like (in the sense
 233         of mysql) "string"
 234
 235         o LASTPLAYED(): Expands to number of minutes that are gone
 236         since this audio file has been played (by paraslash).
 237
 238         o NUMPLAYED(): Expands to number of times, the file has
 239         been played.
 240
 241         o PICID(): Expands to the number of the picture which is
 242         associated with this song.
 243
 244 To give a real-life example, suppose you have already added the
 245 attributes "pop", "rock" with the "na" command. Assume also that you
 246 have set these attributes for some or all of your songs having the
 247 corresponding properties.
 248
 249 If you like to be waked up in the morning by poprock songs, but you
 250 have some strange feeling telling you that just a few seconds of
 251 Madonna's voice will be enough to mess up your whole day, just write
 252 the lines
 253
 254         accept: IS_SET(pop) and IS_SET(rock)
 255         deny: NAME_LIKE(%Madonna%)
 256
 257 to some temporary file "tmp" and do
 258
 259         para_client stradd wake < tmp
 260
 261 You can then switch to the new stream with
 262
 263         para_client cs wake
 264
 265 or you can let cron do this for you on a daily basis..
 266
 267 Accept/deny lines affect only the set of admissible audio files,
 268 but not the order in which these are streamed. That's where the score
 269 expression comes into play.
 270
 271 Scoring
 272 ~~~~~~~
 273 You may put a single score line anywhere in the stream definition. If
 274 omitted, the default scoring rule specified in the configuration file
 275 applies. If there is no default scoring rule in the config file either,
 276 the compiled in default is going to be used (see para_server -h).
 277
 278 Simple examples of scoring rules (either specified in a stream
 279 definition or as the default scoring rule in the config file) include:
 280
 281         LASTPLAYED()/1440
 282
 283 This means that the score of an audio file is just the number of days
 284 that went by since it has been played the last time (one day is 1440
 285 minutes). In other words, the mysql selector choses that admissible
 286 file which wasn't played for the longest time.
 287
 288 However, one disadvantage of this scoring sheme is that new files,
 289 once played, are going to be deferred for a possibly very long period
 290 depending on the size of your collection of (admissible) files. Hence
 291 the following scoring rule comes into mind:
 292
 293         score: -NUMPLAYED()
 294
 295 since this gives newer files, i.e. files to which you haven't listen to
 296 that often, a higher score than older songs you already know by heart.
 297
 298 You can also use a combination of these two methods:
 299
 300         score: LASTPLAYED()/1440 - 10 * NUMPLAYED()
 301
 302 which subtracts 10 score points for each time paraslash has played
 303 this file.
 304
 305 Another useful feature for scoring is due to the fact that
 306 "true" expands to one and "false" to zero. So you can also use the
 307 IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give your favorite
 308 band "bar" some extra points:
 309
 310         score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
 311
 312
 313 Pictures
 314 ~~~~~~~~
 315
 316 The mysql selector can also magage images that, when associated
 317 with one or more audio files, can be displayed by para_sdl_gui and
 318 para_krell. It is also possible to just retrieve the current image via
 319
 320         para_client pic > filename
 321
 322 in order to feed it to your favorite tool. Try
 323
 324         para_client help | grep ^pic
 325
 326 and read the online help of the shown commands for more information.