chiark / gitweb /
TODOs for choose-search.c
[disorder] / doc / disobedience.1.in
1 .\"
2 .\" Copyright (C) 2004-2008 Richard Kettlewell
3 .\"
4 .\" This program is free software; you can redistribute it and/or modify
5 .\" it under the terms of the GNU General Public License as published by
6 .\" the Free Software Foundation; either version 2 of the License, or
7 .\" (at your option) any later version.
8 .\"
9 .\" This program is distributed in the hope that it will be useful, but
10 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
11 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12 .\" General Public License for more details.
13 .\"
14 .\" You should have received a copy of the GNU General Public License
15 .\" along with this program; if not, write to the Free Software
16 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17 .\" USA
18 .\"
19 .TH disobedience 1
20 .SH NAME
21 disobedience \- GUI client for DisOrder jukebox
22 .SH SYNOPSIS
23 .B disobedience
24 .RI [ OPTIONS ]
25 .SH DESCRIPTION
26 .B disobedience
27 is a graphical client for DisOrder.
28 .SH "WINDOWS AND ICONS"
29 .SS "Server Menu"
30 This has the following options:
31 .TP
32 .B Login
33 Brings up the \fBLogin Details Window\fR; see below.
34 .TP
35 .B "Manage Users"
36 Brings up the \fBUser Management Window\fR; see below.
37 .TP
38 .B Quit
39 Terminates the program.
40 .SS "Edit Menu"
41 This has the following options:
42 .TP
43 .B "Select All"
44 Select all tracks in whichever of the Queue or Recent tabs are showing.
45 .TP
46 .B Properties
47 Edit the details of the selected tracks.
48 See
49 .B "Properties Window"
50 below.
51 .SS "Control Menu"
52 This has the following options:
53 .TP
54 .B Scratch
55 Interrupts the currently playing track.
56 .TP
57 .B Playing
58 Pause and resume the current track.
59 .TP
60 .B "Random play"
61 Enable and disable random play.
62 Does not take effect until the currently playing track finishes.
63 .TP
64 .B "Network player"
65 Enables or disables network play.
66 See
67 .B "NETWORK PLAY"
68 below.
69 .SS "Help Menu"
70 This has only one option, "About DisOrder", which pops up a box giving the
71 name, author and version number of the software.
72 .SS "Controls"
73 .TP
74 .B "Pause button"
75 The pause button can be used to pause and resume tracks.
76 .TP
77 .B "Scratch button"
78 The scratch button, a red cross, can be used to interrupt the currently playing
79 track.
80 .TP
81 .B "Random play button"
82 The random play button can be used to enable and disable random play.
83 It does not take effect until the currently playing track finishes.
84 .TP
85 .B "Play button"
86 The play button controls whether tracks will be played at all.
87 As above it does not take effect until the currently playing track finishes.
88 .TP
89 .B "Network play button"
90 The network play buttons enables or disables network play.
91 See
92 .B "NETWORK PLAY"
93 below.
94 .TP
95 .B "Volume slider"
96 The volume slider indicates the current volume level and can be used to adjust
97 it.
98 0 is silent and 10 is maximum volume.
99 .TP
100 .B "Balance slider"
101 The balance slider indicates the current balance and can be used to adjust it.
102 -1 means only the left speaker, 0 means both speakers at equal volume and +1
103 means the only the right speaker.
104 .SS "Queue Tab"
105 This displays the currently playing track and the queue.
106 The currently playing track is at the top, and can be distinguished by
107 the constantly updating timer.
108 Queued tracks appear below it.
109 .PP
110 The left button can be use to select and deselect tracks.
111 On its own it just selects the pointed track and deselects everything else.
112 With CTRL it flips the state of the pointed track without affecting anything
113 else.
114 With SHIFT it selects every track from the last click to the current position
115 and deselects everything else.
116 With both CTRL and SHIFT it selects everything from the last click to the
117 current position without deselecting anything.
118 .PP
119 Tracks can be moved within the queue by dragging them to a new position with
120 the left button.
121 .PP
122 The right button pops up a menu.
123 This has the following options:
124 .TP
125 .B Properties
126 Edit the details of the selected tracks.
127 See
128 .B "Properties Window"
129 below.
130 .TP
131 .B "Select All"
132 Select all tracks.
133 .TP
134 .B Scratch
135 Interrupt the currently playing track.
136 (Note that this appears even if you right click over a queued track rather
137 than the currently playing track.)
138 .TP
139 .B Remove
140 Remove the selected tracks from the queue.
141 .SS "Recent Tab"
142 This displays recently played tracks, the most recent at the top.
143 .PP
144 The left button functions as above, except that drag-and-drop rearrangement
145 is not possible.
146 The right button pops up a menu with the following options:
147 .TP
148 .B Properties
149 Edit the details of the selected tracks.
150 See
151 .B "Properties Window"
152 below.
153 .TP
154 .B "Select All"
155 Select all tracks.
156 .SS "Choose Tab"
157 This displays all the tracks known to the server in a tree structure.
158 .PP
159 Directories are represented with an arrow to their left.
160 This can be clicked to reveal or hide the contents of the directory.
161 The top level "directories" break up tracks by their first letter.
162 .PP
163 Playable files are represented by their name.
164 If they are playing or in the queue then a notes icon appears next to them.
165 .PP
166 Left clicking on a file will select it.
167 As with the queue tab you can use SHIFT and CTRL to select multiple files.
168 .PP
169 The text box at the top is a search form.
170 If you enter search terms here then tracks containing all those words will be
171 highlighted.
172 You can also limit the results to tracks with particular tags, by including
173 \fBtag:\fITAG\fR for each tag.
174 .PP
175 To start a new search just edit the contents of the search box.
176 The cancel button to its right clears the current search.
177 The up and down arrows will scroll the window to make the previous or next
178 search result visible.
179 .PP
180 Right clicking over a track will pop up a menu with the following options:
181 .TP
182 .B Play
183 Play selected tracks.
184 .TP
185 .B Properties
186 Edit properties of selected tracks.
187 See
188 .B "Properties Window"
189 below.
190 .PP
191 A middle click on a track will add it to the queue.
192 .PP
193 Right clicking over a directory will pop up a menu with the following options:
194 .TP
195 .B "Play all tracks"
196 Play all the tracks in the directory, in the order they appear on screen.
197 .TP
198 .B "Track properties"
199 Edit properties of all tracks in the directory.
200 .TP
201 .B "Select all tracks"
202 Select all the tracks in the directory (and deselect everything else).
203 .PP
204 Note that these options do not apply recursively - only the tracks in the
205 relevant directory are affected, not those in its subdirectories.
206 .SS "Added Tab"
207 This displays a list of tracks recently added to the server's database.
208 The most recently added track is at the top.
209 .PP
210 Left clicking a track will select it.
211 CTRL and SHIFT work as above to select muliple files.
212 .PP
213 Right clicking over a track will pop up a menu with the following options:
214 .TP
215 .B "Track properties"
216 Edit properties of selected tracks.
217 See
218 .B "Properties Window"
219 below.
220 .TP
221 .B "Play track"
222 Play selected tracks.
223 .TP
224 .B "Select All Tracks"
225 Select all tracks.
226 .SS "Login Details Window"
227 The login details window allows you to edit the connection details and
228 authorization information used by Disobedience.
229 It has four text entry fields:
230 .TP
231 .B Hostname
232 The host to connect to.
233 .TP
234 .B Service
235 The service name or port number to connect to.
236 .TP
237 .B "User name"
238 The user name to log in as.
239 .TP
240 .B Password
241 The password to use when logging in.
242 Note that this is NOT your login password but is your password to the
243 DisOrder server.
244 .PP
245 It has three buttons:
246 .TP
247 .B Login
248 This button attempts to (re-)connect to the server with the currently displayed
249 settings.
250 The settings are not saved.
251 .TP
252 .B Save
253 This button saves the current settings in 
254 .IR $HOME/.disorder/passwd .
255 .TP
256 .B Close
257 This button closes the window, discarding any unsaved changes.
258 .SS "Properties Window"
259 This window contains details of one or more tracks and allows them to be
260 edited.
261 .PP
262 The Artist, Album and Title fields determine how the tracks appear in
263 the queue and recently played tabs.
264 .PP
265 The Tags field determine which tags apply to the track.
266 Tags are separated by commas and can contain any printing characters except
267 comma.
268 .PP
269 The Weight field determines the track weight.  Tracks with higher weights are
270 proportionately more likely to be picked at random.  The default weight is
271 90000, and the maximum weight is 2147483647.
272 .PP
273 The Random checkbox determines whether the track will be picked at random.
274 Random play is enabled for every track by default, but it can be turned off
275 here.
276 .PP
277 The double-headed arrow to the right of each preference will propagate its
278 value to all the other tracks in the window.
279 For instance, this can be used to efficiently correct the artist or album
280 fields, or bulk-disable random play for many tracks.
281 .PP
282 Press "OK" to confirm all changes and close the window, "Apply" to confirm
283 changes but keep the window open and "Cancel" to close the window and discard
284 all changes.
285 .SS "User Management Window"
286 This window is primarily of interest to adminstrators, and will not be
287 available to users without admin rights.  The left hand side is a list of all
288 users; the right hand side contains the editable details of the currently
289 selected user.
290 .PP
291 When you select any user you can edit their email address or change their
292 password.  It is also possible to edit the individual user rights.  Click on
293 the "Apply" button to commit any changes you make.
294 .PP
295 The "Add" button creates a new user.  You must enter at least a username.
296 Default rights are setting according to local configuration, \fInot\fR server
297 configuration (but this may be changed in the future).  As above, click on
298 "Apply" to actually create the new user.
299 .PP
300 The "Delete" button deletes the selected user.  This operation cannot be
301 undone.
302 .SH "KEYBOARD SHORTCUTS"
303 .TP
304 .B CTRL+A
305 Select all tracks (queue/recent)
306 .TP
307 .B CTRL+L
308 Brings up the \fBLogin Details Window\fR.
309 .TP
310 .B CTRL+Q
311 Quit.
312 .SH "NETWORK PLAY"
313 Network play uses a background
314 .BR disorder\-playrtp (1)
315 process.
316 If you quit Disobedience the player will continue playing and can be
317 disabled from a later run of Disobedience.
318 .PP
319 The player will log to
320 .I ~/.disorder/HOSTNAME\-rtp.log
321 so look there if it does not seem to be working.
322 .PP
323 You can stop it without running Disobedience by the command
324 .BR "killall disorder\-playrtp" .
325 .SH OPTIONS
326 .TP
327 .B \-\-config \fIPATH\fR, \fB\-c \fIPATH
328 Set the configuration file.
329 The default is
330 .IR pkgconfdir/config .
331 .TP
332 .B \-\-debug\fR, \fB\-d
333 Enable debugging.
334 .TP
335 .B \-\-help\fR, \fB\-h
336 Display a usage message.
337 .TP
338 .B \-\-version\fR, \fB\-V
339 Display version number.
340 .SS "GTK+ Options"
341 Additional options are supported by the GTK+ library.
342 Refer to GTK+ documentation for further information.
343 Under X11 they include:
344 .TP
345 .B \-\-display \fIDISPLAY\fR
346 The X display to use.
347 .TP
348 .B \-\-screen \fISCREEN\fR
349 The screen number to use.
350 .\" If know enough to use it you know enough to find it
351 .\" .TP
352 .\" .B \-\-sync
353 .\" Make all X requests synchronously.
354 .SH CONFIGURATION
355 If you are using
356 .B disobedience
357 on the same host as the server then no additional configuration should be
358 required.
359 .PP
360 If it is running on a different host then the easiest way to set it up is to
361 use the login details window in Disobedience.
362 Enter the connection details, use Login to connect to the server, and then
363 use Save to store them for future sessions.
364 .PP
365 The other clients read their configuration from the same location so after
366 setting up with Disobedience, tools such as
367 .BR disorder (1)
368 should work as well.
369 .SH BUGS
370 There is no particular provision for multiple users of the same computer
371 sharing a single \fBdisorder\-playrtp\fR process.
372 This shouldn't be too much of a problem in practice but something could
373 perhaps be done given demand.
374 .PP
375 Try to do remote user management when the server is configured to refuse this
376 produces rather horrible error behavior.
377 .PP
378 Only one track can be dragged at a time.
379 .PP
380 Resizing columns doesn't work very well.
381 This is a GTK+ bug.
382 .SH FILES
383 .TP
384 .I ~/.disorder/HOSTNAME\-rtp
385 Socket for communication with RTP player.
386 .TP
387 .I ~/.disorder/HOSTNAME\-rtp.log
388 Log file for RTP player.
389 .SH "SEE ALSO"
390 .BR disorder\-playrtp (1),
391 .BR disorder_config (5)
392 .PP
393 .B http://www.greenend.org.uk/rjk/disorder/
394 .br
395 - DisOrder home page
396 .PP
397 .B http://www.gtk.org/api/2.6/gtk/gtk\-x11.html
398 .br
399 - Using GTK+ on the X Window System
400 .\" Local Variables:
401 .\" mode:nroff
402 .\" fill-column:79
403 .\" End: