← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/oss4/oneiric-proposed

« back to all changes in this revision

Viewing changes to kernel/drv/oss_audioloop/oss_audioloop.man

  • Committer: Bazaar Package Importer
  • Author(s): Stefano Rivera
  • Date: 2011-06-16 20:37:48 UTC
  • mfrom: (5.1.3 sid)
  • Revision ID: james.westby@ubuntu.com-20110616203748-jbrxik6ql33z54co
Tags: 4.2-build2004-1ubuntu1
https://launchpad.net/bugs/746048
https://launchpad.net/bugs/770972
* Merge from Debian unstable.
  - Supports our current kernel (LP: #746048)
  Remaining changes:
  - debian/oss4-dkms.dkms.in: s/source/build/ in Kernel headers paths.
* ld-as-needed.patch: Re-order CC arguments to enable building with ld
  --as-needed (LP: #770972)

Show diffs side-by-side

added added

removed removed

Lines of Context:
kernel/drv/oss_audioloop/oss_audioloop.man
 
1
NAME
 
2
oss_audioloop - Loopback audio driver.
 
3
 
 
4
DESCRIPTION
 
5
The loopback audio driver makes it possible to create special purpose
 
6
virtual audio devices based on user land server processes.
 
7
 
 
8
Loopback devices are driven by a timer interrupt and no real audio
 
9
hardware is required.
 
10
 
 
11
 INTRODUCTION
 
12
Audio loopback devices are like named pipes or pseudo terminals. They are 
 
13
grouped in client and server device pairs. The server side device must be open
 
14
before the client side device can be opened.
 
15
 
 
16
Loopback devices are typically used to implement server based special purpose
 
17
audio devices. This kind of server can for example transfer the audio data
 
18
played by the client application to some remote system using some VoIP
 
19
protocol. However the server application doesn't need to be any dedicated
 
20
server. Practically any audio application can be used as the server.
 
21
 
 
22
 SERVER SIDE DEVICE
 
23
The server side applications sets up the native sampling rate and sample format
 
24
(number of bits and channels). The server side device can be opened for input
 
25
(O_RDONLY) pr output (O_WRONLY). Opening for simultaneous input and output
 
26
(O_RDWR) is not permitted.
 
27
 
 
28
The server application will automatically be paused at the moment it tries to
 
29
read or write audio data for the first time. It will be kept in sleep until the
 
30
client side application starts writing or reading data. This sleep period may
 
31
last forever and in some cases the first write/read call never returns. For
 
32
this reason it's not recommended to use GUI based audio applications as the
 
33
server. Note that this wait will occur even in the non-blocking 
 
34
(O_NONBLOCK) mode (this is intentional feature and not a bug).
 
35
 
 
36
 CLIENT SIDE DEVICE
 
37
The client side device is typically used by any ordinary audio application.
 
38
There is nothing special in loopback devices.
 
39
 
 
40
Since the loop is unidirectional the client side will be forced to be write
 
41
only if the server side device is open for recording and vice versa.
 
42
 
 
43
The loop will use the sample rate and sample format (number of bits and
 
44
channels) set by the server side application. If the client uses different 
 
45
settings then OSS will perform the required sampling rate and format conversions
 
46
automatically.
 
47
 
 
48
COMPATIBILITY ISSUES
 
49
Audio loopback devices differ from "normal" audio devices because an
 
50
application is needed at the both ends of the loop. The loop device
 
51
will return a "Connection reset by peer" error (ECONNRESET) error. Applications
 
52
designed to be used as loopback based server applications can/should use this
 
53
error (returned by read or write) as an end-of-stream indication.
 
54
 
 
55
OPTIONS
 
56
 
 
57
o audioloop_instances:  Specifies how many loopback client/server audio device
 
58
                        pairs to be created.
 
59
                                Values: 1-16     Default: 1
 
60
 
 
61
KNOWN PROBLEMS
 
62
o There is no mixer (volume control) related with loopback audio devices. This
 
63
may prevent poorly designed audio applications (that expect/require a mixer)
 
64
from working. There is no workaround available.
 
65
 
 
66
o The server side application will wait until the client side application 
 
67
starts using it. This wait may last forever which in turn may cause 
 
68
unrecoverable (network) problems with some applications.
 
69
 
 
70
o Loopback devices may return "Connection reset by peer" error when the
 
71
reote side of the loop disconnects the device. Some recording applications
 
72
may fail to save the recorded data properly because of this. Use some
 
73
other application (such as ossrecord) if this happens.
 
74
 
 
75
FILES
 
76
CONFIGFILEPATH/oss_audioloop.conf Device configuration file
 
77
 
 
78
AUTHOR
 
79
4Front Technologies
 
80