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