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