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