4 This file describes how to use the mysql audio file selector which
5 comes with the paraslash package.
7 It assumes you have already installed mysql and paraslash as described
8 in INSTALL, so read README and INSTALL before proceeding.
10 First of all, make sure that
14 - para_server is running and compiled with mysql support
15 (type "para_client si" to find out)
17 - the user who runs para_client has the paraslash DB_WRITE
18 and DB_READ permissions set in server.users
20 - the user who runs para_server has create privileges on the
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
28 Specify mysql data (port, passwd,...)
29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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
39 chmod 600 ~/.paraslash/server.conf
41 as this file contains the mysql passwd. To make these changes take
42 effect you'll need to do
46 Or, restart the server.
48 Switch to the mysql audio file selector
49 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
55 prints the name of the current selector. Try
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
65 to find out. If mysql is not mentioned as a supported selector,
66 you'll have to recompile. If configure does not detect your mysql
67 installation, use the --enable-mysql-headers and --enable-mysql-libs
68 options to specify the mysql path explicitly . Example:
70 ./configure --enable-mysql-headers=/Library/MySQL/include \
71 --enable-mysql-libs=/Library/MySQL/lib/mysql
77 Once the mysql selector is activated, create the database:
82 The second command forces para_server to re-init the mysql selector.
83 Check the log. There should not be any warnings or errors.
86 Fill your database with content
87 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
91 If this command fails, it most likely means the audio file directory
92 (given in the server configuration file) does not exist, is empty,
93 not readable, or contains different files with identical basenames. Fix
94 this problem before proceeding.
100 prints the list of all files known by the mysql selector. If the list
101 is empty, double check the mysql_audio_file_dir option.
104 Create a stream which selects all songs
105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
107 To keep it simple, let's only define the stream "all_songs". See below for
108 advanced stream usage.
110 para_client stradd all_songs < /dev/null
111 para_client sl 10 all_songs
113 The latter command should show you ten filenames.
116 Change to the all_songs stream
117 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119 para_client cs all_songs
121 You should now be able to start streaming with
129 An attribute is simply a bit which can be set for each audio file
130 individually. You may have as many attributes as you like. A new
131 attribute "test" is created by
138 lists all available attributes. You can set the "test" attribute for
139 the current audio file by executing
143 or for any particular audio file by
145 para_client sa test+ filename
147 Unset the attribute "test" for the current audio file with
151 and drop the test attribute entirely from the database with
158 A stream is a pair of expressions in terms of attributes and other data
159 contained in the database. The first, boolian, expression determines
160 the set of audio files which are admissible in this stream. The second,
161 integer, expression determines the order in which admissible files
162 are going to be fed to the audio file sender(s).
164 To create a new stream called "my_stream", put arbitrary many (including
165 none) accept or deny lines and one or zero score lines into some
166 temporary file, say tmpfile. An accept/deny/score line consists of
167 an identifier ("accept:", "deny:", or "score:"), followed by an
168 expression. The command
170 para_client stradd my_stream < tmpfile
172 adds the stream "my_stream" to the table of streams.
174 If the stream definition is really short, you may also just pipe it to
175 the client rather than using temporary files. Like this:
177 echo "$MYSTREAMDEF" | para_client stradd my_stream
182 Assume you already have an attribute "test" and you'd like to
183 to restrict audio streaming to those files having the "test"
184 attribute set. Define a new stream "only_test" by
186 echo 'accept: IS_SET(test)' | para_client stradd only_test
188 Then, after switching to the "only_test" stream with
190 para_client cs only_test
192 only the desired files are going to be streamed.
194 There is no need to keep the temporary files containing the stream
195 definition since you can always use the strq command to get it back:
197 para_client strq only_test
199 The accept/deny expressions are used to find out which songs are
200 permitted. The following four cases are all possible and valid:
202 o Neither accept nor deny lines: This selects all songs.
204 o Only accept lines: Songs that match at least one accept
205 expression are accepted, all others are denied:
207 accept_expr1 or accept_expr2 or ...
209 o Only deny lines: Songs that match at least one deny expression are
210 denied, all others are accepted:
212 not (deny_expr1 or deny_expr2 ...)
214 o Both accept and deny lines: A song is accepted if it matches
215 at least one accept expression, but no deny expression, i.e.
217 (accept_expr1 or accept_expr2 or ..) and not
218 (deny_expr1 or deny_expr2 ..)
224 lists all available streams and
226 para_client strdel streamname
228 removes the stream "streamname".
230 There are more sophisticated ways to define a stream than just using
231 one IS_SET() macro as in the example above. Of course, IS_SET(foo)
232 is true for a given audio file if and only if it has the attribute
233 "foo" set. Here are some more macros you can use:
235 o IS_N_SET(attr): True if attribute attr is not set
237 o NAME_LIKE(string): True if basename is like (in the sense
240 o LASTPLAYED(): Expands to number of minutes that are gone
241 since this audio file has been played (by paraslash).
243 o NUMPLAYED(): Expands to number of times, the file has
246 o PICID(): Expands to the number of the picture which is
247 associated with this song.
249 To give a real-life example, suppose you have already added the
250 attributes "pop", "rock" with the "na" command. Assume also that you
251 have set these attributes for some or all of your songs having the
252 corresponding properties.
254 If you like to be waked up in the morning by poprock songs, but you
255 have some strange feeling telling you that just a few seconds of
256 Madonna's voice will be enough to mess up your whole day, just write
259 accept: IS_SET(pop) and IS_SET(rock)
260 deny: NAME_LIKE(%Madonna%)
262 to some temporary file "tmp" and do
264 para_client stradd wake < tmp
266 You can then switch to the new stream with
270 or you can let cron do this for you on a daily basis..
272 Accept/deny lines affect only the set of admissible audio files,
273 but not the order in which these are streamed. That's where the score
274 expression comes into play.
278 You may put a single score line anywhere in the stream definition. If
279 omitted, the default scoring rule specified in the configuration file
280 applies. If there is no default scoring rule in the config file either,
281 the compiled in default is going to be used (see para_server -h).
283 Simple examples of scoring rules (either specified in a stream
284 definition or as the default scoring rule in the config file) include:
288 This means that the score of an audio file is just the number of days
289 that went by since it has been played the last time (one day is 1440
290 minutes). In other words, the mysql selector choses that admissible
291 file which wasn't played for the longest time.
293 However, one disadvantage of this scoring sheme is that new files,
294 once played, are going to be deferred for a possibly very long period
295 depending on the size of your collection of (admissible) files. Hence
296 the following scoring rule comes into mind:
300 since this gives newer files, i.e. files to which you haven't listen to
301 that often, a higher score than older songs you already know by heart.
303 You can also use a combination of these two methods:
305 score: LASTPLAYED()/1440 - 10 * NUMPLAYED()
307 which subtracts 10 score points for each time paraslash has played
310 Another useful feature for scoring is due to the fact that
311 "true" expands to one and "false" to zero. So you can also use the
312 IS_SET/IS_N_SET/NAME_LIKE macros in a score line to give your favorite
313 band "bar" some extra points:
315 score: 40 * IS_SET(foo) + 20 * NAME_LIKE(%bar%) + LASTPLAYED()/1440
321 The mysql selector can also magage images that, when associated
322 with one or more audio files, can be displayed by para_sdl_gui and
323 para_krell. It is also possible to just retrieve the current image via
325 para_client pic > filename
327 in order to feed it to your favorite tool. Try
329 para_client help | grep ^pic
331 and read the online help of the shown commands for more information.