source: gutenbach/debian/lib/README @ 331684f

debianmacno-cupsnodebathenaweb
Last change on this file since 331684f was 331684f, checked in by Jessica B. Hamrick <jhamrick@…>, 14 years ago

Readd -really-quiet.

Signed-off-by: Edward Z. Yang <edwardzyang@…>

  • Property mode set to 100644
File size: 8.8 KB
Line 
1sipbmp3
2    The SIPB MP3 Music Spooler
3
4We would love you forever if you took this README/INSTALL document and made
5a Debian package out of it.  That would be uber-awesome.  But otherwise, we're
6assuming that you just want to get sipbmp3 up and running on your own
7system.  Well, maybe we shouldn't assume that.
8
9
10What does sipbmp3 do?
11---------------------
12
13sipbmp3 is a music spooler.  As it turns out, streaming music is a hard
14problem, with lots of proprietary protocols, client and server software.
15All of these jiggety bits are kind of a pain to get working correctly,
16so, we built sipbmp3 on top of... a printer system.  It's very simple:
17you print an mp3 file to a special "printer", and it gets played on
18whatever speakers you're hooked up to.
19
20
21Prerequisites
22-------------
23
24You'll need a server hooked up to an audio system that you want to use, with
25Debathena installed on top of it.  Ubuntu Server Edition tends to work
26well.
27
28
29Installing sipbmp3
30------------------
31
32
331. Configuring your sound
34
35If you're installing sipbmp3 on a server environment, it's highly likely
36that you have a bare bones audio setup and everything is muted.  Make sure
37your sound works!  One common problem is that the daemon user (the user which
38will be actually playing the songs, or the user that your lpd, the print server,
39will be running under), isn't in the group audio, and thus can't play
40anything. If you're on Ubuntu Desktop, you'll probably have pulse-audio
41installed, in which case you should add lpd to the pulse-audio group
42as well, and make pulse-audio a single, system-wide instance. See
43this URL for detailed instructions:
44
45    http://www.pulseaudio.org/wiki/SystemWideInstance
46
47
482. Install some prerequisite software
49
50On a vanilla Ubuntu server install, sipbmp3 will also need the following
51packages to work properly:
52
53    * mplayer
54    * libimage-exiftool-perl
55
56mpg123 can also be useful for testing, but is not strictly necessary.
57
58
593. Setup sipbmp3
60
61The Git repository for sipbmp3 is located in:
62
63    /afs/sipb/project/sipbmp3/sipbmp3.git
64
65While sudo'ed as root, you should git clone this somewhere; zsr has
66it dumped in /usr/local/bin, while scourge puts it the more cordoned
67off /root/sipbmp3.
68
69
704. Configure sipbmp3
71
72sipbmp3 will send zephyrs during playback start and end.  Since you don't
73want to be spamming sipb-auto (which is the default zephyr class these
74are sent to), you should create a configuration file:
75
76    /etc/sipbmp3-filter-config.pl
77
78That looks like:
79
80    $zephyr_class = "my-auto-class"
81    $host = "hostname"
82    $queue = "printername"
83
84XXX: Auto-detect hostname and invent a sane default zephyr class off of it.
85
86
875. Configure sipbmp3 init scripts
88
89sipbmp3 will attempt to drop some information into /var/run/sipbmp3, which
90needs to exist and you can't simply mkdir since /var/run on Ubuntu is
91a tempfs. Thus, add the following lines to a new file, /etc/init.d/sipbmp3:
92
93#!/bin/sh
94mkdir /var/run/sipbmp3
95touch /var/run/sipbmp3/status
96chmod 0777 /var/run/sipbmp3/status
97
98You should also run these commands yourself. :-)
99
100XXX: We need better permissions for status. Also, quentin wants to put this
101file in AFS.
102
103
1046. Configure lpd
105
106You'll need to setup a printcap file so that your machine will be actually
107running a printer! The magic lines are:
108
109    :if=|/path/to/sipbmp3-filter
110    :lp=/dev/null
111
112Which mean that we pipe the mp3 files through sipbmp3-filter (which does
113the actual playing), and then dump the rest of the output into /dev/null,
114since we don't actually care about it.
115
116A standard printcap entry looks like this:
117
118printername
119  :server
120  :cm=Human Readable Printer Name
121  :lp=/dev/null
122  :if=|/path/to/sipbmp3-filter
123  :sd=/var/spool/lpd/printername
124  :ml=0:mx=0:sh:sf
125  :auth_forward=kerberos5
126  :use_auth=kerberos5
127  :create_files
128
129printcap is located in /etc/printcap, but you can also edit the symlink
130in /etc/lprng/printcap.
131
132To check your modifications, and create the necessary files and folders,
133you should run:
134
135    checkpc -V -f
136
137(As root, of course). You might get a failure on a directory
138/var/spool/lpd/%P doesn't exist; simply mkdir it and run checkpc -V -f
139again.
140
141With recent versions of lprng, you will also need to make lpd less paranoid
142about accepting connections.  This usually means the following two changes:
143
144In /etc/lprng/lpd.perms:
145
146    REJECT NOT SERVER
147
148should be commented out, as:
149
150    #REJECT NOT SERVER
151
152And, in /etc/lprng/lpd.conf:
153
154    printcap_path=...
155
156add /etc/lprng/printcap to the beginning of the pathlist, so it looks like:
157
158    printcap_path=/etc/lprng/printcap:|/usr/lib/get_hesiod_pcap
159
160/etc/printcap will also work, assuming lprng doesn't do something funky
161in the future.
162
163You will also need to add this line:
164
165    lpd_listen_port=515
166
167By default, printers don't allow other users to remove other people's print
168jobs.  For an MP3 spooler, however, this may be a desirable trait, especially
169if someone trys to rickroll you.  You can let everyone lprm jobs by
170commenting out the line:
171
172    REJECT SERVICE=M
173
174XXX: On scourge, ACCEPT SERVICE=M SAMEHOST SAMEUSER doesn't seem to work
175properly, so removing the REJECT line is a must!
176
177XXXXXX: sipbmp3 accepts no responsibility for social faux pas that may
178be committed with this system.  It is consider good etiquette, however,
179to clear the status file if you're on zsr.
180
181
1827. Test, round one
183
184The first test you should do to make sure sipbmp3 is configured properly is
185to attempt to play an mp3 file locally, via lpr.  The command you should use
186is:
187
188    mit-lpr -Pprintername@localhost filename.mp3
189
190Note the "mit-" prefix; Debathena defaults to CUPS, which we have not set
191up yet.
192
193See below for troubleshooting tips.
194
195
1968. Test, round two
197
198The second test you should do is try playing an MP3 remotely. The appropriate
199command is:
200
201    mit-lpr -Pprintername@hostname filename.mp3
202
203(Once again, with "mit-").  See below for troubleshooting tips.
204
205
2069. Troubleshooting
207
208So, it didn't work.  How did it fail?
209
210----
211sending job 'ezyang@vivace+800' to asdfasdf@localhost
212 connecting to 'localhost', attempt 1
213 cannot open connection to localhost - No such file or directory
214----
215
216This means that lpd is not accepting connections properly.  Check to see
217if you configured lpd.perms and lpd.conf correctly.  Try rebooting lpd
218by pkill lpd && lpd.  Use nmap to check of port 515 is open, both on the
219local machine and on a remote machine.  Check if networking is working
220on the server.  Use netstat to see what programs are listening to port
221515, and from which hosts.  Check iptables.
222
223----
224lpr: The printer or class was not found.
225----
226
227You're using lpr, not mit-lpr.
228
229----
230(no output, but no sound)
231----
232
233It looks like you managed to send the file over.  To diagnose the problems
234further:
235
236    * Check the zephyr logs of the class sipbmp3 was configured to
237      send messages to:
238
239        - If you see a reasonably full and formatted message, that means
240          that either: 1. your volume is turned off, or 2. mplayer is
241          horribly broken (XXX: it probably isn't, but I don't know what
242          error message it gives in that case)
243
244          By the way, be sure to check both the *hardware* and the
245          *software* volume.
246
247        - If you see a blank zephyr, that means that sipbmp3-filter died
248          trying to get a handle to /var/run/sipbmp3/status and failing.
249          Check if you created the file correctly, and that daemon has
250          permissions to write to it. If you rebooted recently, check if
251          you have the appropriate init.d script setup.
252
253    * Otherwise, check /var/spool/lpd/printername/status.pr (most of all the
254      other files are useless, especially including log):
255
256        - If you see a Perl error, fix it. The most common cause is because
257          exiftools is not installed.
258
259    * Otherwise, double check the userland code in sipbmp3-filter. XXX: There
260      are some edge-cases that don't give nice error messages, for example
261      the failed write to /var/run/sipbmp3/status
262
263
26410. Deploying CUPS
265------------------
266
267The final step is to give your newfangled printer a cups.mit.edu record.
268In order to do this, you will need to ask IS&T for a Moira pcap entry
269request.  Send mail to hesreq@mit.edu, specifying that you are setting
270up a sipbmp3 clone, that you want a Moira pcap entry, the printer name
271and server name of your queue, and that you want hwtype=LOCAL. It wouldn't
272hurt to also tell them where your print queue is, and a contact list.
273
274Once you get the pcap entry, ping sipb-cups@mit.edu to add your machine
275to the public list.
276
277
278X. Setting up remctl commands
279-----------------------------
280
281It's useful to be able to control the volume. Remctl is the way to do
282this without asking people to ssh in, and then alsamix(er). XXX: These
283batch scripts and remctl files are not yet public.
284
285
286X. Deploying sipbmp3web
287------------------------
288
289sipbmp3 web provides a nice and user-friendly interface for some common
290tasks. XXX: It is currently not portable beyond zsr. Stay tuned!
291
Note: See TracBrowser for help on using the repository browser.