Fix 1.3.2-1 release date
[osspd.git] / README
1
2  OSS Proxy - emulate OSS device using CUSE
3
4  Copyright (C) 2008-2009  SUSE Linux Products GmbH
5  Copyright (C) 2008-2009  Tejun Heo <tj@kernel.org>
6
7 1. What is it?
8 --------------
9
10 Well, first, OSS refers to Open Sound System.  If it still doesn't
11 ring a bell, think /dev/dsp, /dev/adsp and /dev/mixer.
12
13 Currently, Linux supports two audio programming interface - ALSA and
14 OSS.  The latter one is deprecated and has been that way for a long
15 time but there still are applications which still use them including
16 UML (usermode Linux) host sound support.
17
18 ALSA contains OSS emulation but sadly the emulation is behind
19 multiplexing layer (which is in userland) which means that if your
20 sound card doesn't support multiple audio streams, only either one of
21 ALSA or OSS interface would be usable at any given moment.
22
23 There have been also attempts to emulate OSS in userland using dynamic
24 library preloading - aoss and more recently padsp.  This works for
25 many applications but it's just not easy to emulate everything using
26 the technique.  Things like polling, signals, forking, privilege
27 changes make it very difficult to emulate things reliably.
28
29 OSS Proxy uses CUSE (extension of FUSE allowing character devices to
30 be implemented in userspace) to implement OSS interface - /dev/dsp,
31 /dev/adsp and /dev/mixer.  From the POV of the applications, these
32 devices are proper character devices and behave exactly the same way
33 so it can be made quite versatile.
34
35
36 2. Hmmm... So, how does the whole thing work?
37 ---------------------------------------------
38
39 The OSS Proxy daemon - osspd - should be started first.  Note that
40 osspd will fail to start if sound device number regions are already
41 occupied.  You'll need to turn off OSS or its emulation[1].
42
43 On startup, osspd creates /dev/dsp, /dev/adsp and /dev/mixer using
44 CUSE.  When an application access one of the devices, all IOs are
45 redirected to osspd via CUSE.  Upon receiving a new DSP open request,
46 osspd creates a slave process which drops the root privilege and
47 assumes the opening process's credentials.  After handshaking, osspd
48 forwards all relevant IOs to the slave which is responsible for
49 actually playing the sound.
50
51 Currently there's only one slave implemented - ossp-padsp, which as
52 the name suggests forwards (again) the sound to pulseaudio.  To sum
53 up, the whole pipe looks like the following.
54
55  App <-> /dev/dsp <-> CUSE <-> osspd <-> ossp-padsp <-> pulseaudio
56
57 Which is a lot of forwarding, but on modern machines, it won't be too
58 noticeable.
59
60
61 3. What works?
62 --------------
63
64 Well, MIDI part isn't implemented and I doubt it will be in any near
65 future but except that everything should work.  Playing, recording,
66 5.1ch, A-V syncing, all should work.  If not, it's a bug, so please
67 report.
68
69 The mixer behaves a bit differently tho.  In the original OSS,
70 /dev/mixer is the hardware mixer, so adjusting volumes there affects
71 all audio streams.  When using ossp, each process group gets its own
72 mixer and the mixer always contains only two knobs - PCM and IGAIN.
73 Combined with per-stream volume control of pulseaudio, this scheme
74 works quite well for applications with embedded volume control
75 although it makes standalone OSS mixer programs virtually useless[2].
76
77
78 4. How do I use it?
79 -------------------
80
81 First you need CUSE support in kernel which might land on 2.6.28 with
82 sufficient luck[3] and then you also need libfuse which supports
83 CUSE[4].  Once you have both, it should be easy.  First build it by
84 running `make'.  You can set OSSPD_CFLAGS, OSSPD_LDFLAGS,
85 OSSP_PADSP_CFLAGS and OSSP_PADSP_LDFLAGS if you have stuff at
86 non-default locations.
87
88 After build completes, there will be two executables - `osspd' and
89 `ossp-padsp'.  Just copy them to where other system executables live.
90 Specific location doesn't matter as long as both files end up in the
91 same directory.
92
93 Execute `osspd'.  It will create the device files and you're all set.
94 `osspd' uses syslog with LOG_DAEMON facility, so if something doesn't
95 work take a look at what osspd complains about.
96
97
98 [1] As of this writing, turning on any sound support makes the
99     soundcore module claim OSS device regions.  Patch to make it claim
100     OSS device regions only when OSS support or emulation is enabled
101     is scheduled for 2.6.28.  Even with the patch, soundcore will
102     claim OSS device regions if OSS support or ALSA OSS emulation is
103     enabled.  Make sure they're turned off.
104
105 [2] If you have a strong reason to use standalone OSS mixer program,
106     you can play some shell tricks to put it into the same process
107     group as the target audio application.  e.g. To use aumix with
108     mpg123 - `(mpg123 asdf.mp3 > /dev/null 2>&1 & aumix)', but
109     seriously, just use PA or ALSA one.
110
111 [3] For the time being, here's the git tree with all the necessary
112     changes.  This tree is base on top of 2.6.27-rc3.
113
114     http://git.kernel.org/?p=linux/kernel/git/tj/misc.git;a=shortlog;h=cuse
115     git://git.kernel.org/pub/scm/linux/kernel/git/tj/misc.git cuse
116
117 [4] And libfuse with the modifications can be found at...
118
119     http://userweb.kernel.org/~tj/ossp/fuse-cuse.tar.gz