rest25/library/ossaudiodev.rst => rest262/library/ossaudiodev.rst
8
9
10.. versionadded:: 2.3
11
12This module allows you to access the OSS (Open Sound System) audio interface.
13OSS is available for a wide range of open-source and commercial Unices, and is
14the standard audio interface for Linux and recent versions of FreeBSD.
15
n16-.. % Things will get more complicated for future Linux versions, since
n16+.. Things will get more complicated for future Linux versions, since
17-.. % ALSA is in the standard kernel as of 2.5.x.  Presumably if you
17+   ALSA is in the standard kernel as of 2.5.x.  Presumably if you
18-.. % use ALSA, you'll have to make sure its OSS compatibility layer
18+   use ALSA, you'll have to make sure its OSS compatibility layer
19-.. % is active to use ossaudiodev, but you're gonna need it for the vast
19+   is active to use ossaudiodev, but you're gonna need it for the vast
20-.. % majority of Linux audio apps anyways.
20+   majority of Linux audio apps anyways.
21-.. % 
21+ 
22-.. % Sounds like things are also complicated for other BSDs.  In response
22+   Sounds like things are also complicated for other BSDs.  In response
23-.. % to my python-dev query, Thomas Wouters said:
23+   to my python-dev query, Thomas Wouters said:
24-.. % 
24+ 
25-.. % > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
25+   > Likewise, googling shows OpenBSD also uses OSS/Free -- the commercial
26-.. % > OSS installation manual tells you to remove references to OSS/Free from the
26+   > OSS installation manual tells you to remove references to OSS/Free from the
27-.. % > kernel :)
27+   > kernel :)
28-.. % 
28+ 
29-.. % but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
29+   but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
30-.. % from its <soundcard.h>:
30+   from its <soundcard.h>:
31-.. % >  * WARNING!  WARNING!
31+   >  * WARNING!  WARNING!
32-.. % >  * This is an OSS (Linux) audio emulator.
32+   >  * This is an OSS (Linux) audio emulator.
33-.. % >  * Use the Native NetBSD API for developing new code, and this
33+   >  * Use the Native NetBSD API for developing new code, and this
34-.. % >  * only for compiling Linux programs.
34+   >  * only for compiling Linux programs.
35-.. % 
35+ 
36-.. % There's also an ossaudio manpage on OpenBSD that explains things
36+   There's also an ossaudio manpage on OpenBSD that explains things
37-.. % further.  Presumably NetBSD and OpenBSD have a different standard
37+   further.  Presumably NetBSD and OpenBSD have a different standard
38-.. % audio interface.  That's the great thing about standards, there are so
38+   audio interface.  That's the great thing about standards, there are so
39-.. % many to choose from ... ;-)
39+   many to choose from ... ;-)
40-.. % 
40+ 
41-.. % This probably all warrants a footnote or two, but I don't understand
41+   This probably all warrants a footnote or two, but I don't understand
42-.. % things well enough right now to write it!   --GPW
42+   things well enough right now to write it!   --GPW
43
44
45.. seealso::
46
47   `Open Sound System Programmer's Guide <http://www.opensound.com/pguide/oss.pdf>`_
48      the official documentation for the OSS C API
49
50   The module defines a large number of constants supplied by the OSS device
73   :meth:`fileno` (although there are subtle differences between conventional Unix
74   read/write semantics and those of OSS audio devices).  It also supports a number
75   of audio-specific methods; see below for the complete list of methods.
76
77   *device* is the audio device filename to use.  If it is not specified, this
78   module first looks in the environment variable :envvar:`AUDIODEV` for a device
79   to use.  If not found, it falls back to :file:`/dev/dsp`.
80
n81-   *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for write-only
n81+   *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for
82-   (playback) access and ``'rw'`` for both. Since many sound cards only allow one
82+   write-only (playback) access and ``'rw'`` for both. Since many sound cards
83-   process to have the recorder or player open at a time, it is a good idea to open
83+   only allow one process to have the recorder or player open at a time, it is a
84-   the device only for the activity needed.  Further, some sound cards are half-
84+   good idea to open the device only for the activity needed.  Further, some
85-   duplex: they can be opened for reading or writing, but not both at once.
85+   sound cards are half-duplex: they can be opened for reading or writing, but
86+   not both at once.
86
87   Note the unusual calling syntax: the *first* argument is optional, and the
88   second is required.  This is a historical artifact for compatibility with the
89   older :mod:`linuxaudiodev` module which :mod:`ossaudiodev` supersedes.
90
n91-   .. % XXX it might also be motivated
n92+   .. XXX it might also be motivated
92-   .. % by my unfounded-but-still-possibly-true belief that the default
93+      by my unfounded-but-still-possibly-true belief that the default
93-   .. % audio device varies unpredictably across operating systems.  -GW
94+      audio device varies unpredictably across operating systems.  -GW
94
95
96.. function:: openmixer([device])
97
98   Open a mixer device and return an OSS mixer device object.   *device* is the
99   mixer device filename to use.  If it is not specified, this module first looks
100   in the environment variable :envvar:`MIXERDEV` for a device to use.  If not
101   found, it falls back to :file:`/dev/mixer`.
118Alternately, you can use the :meth:`setparameters` method to set all three audio
119parameters at once.  This is more convenient, but may not be as flexible in all
120cases.
121
122The audio device objects returned by :func:`open` define the following methods
123and (read-only) attributes:
124
125
n126-.. method:: audio device.close()
n127+.. method:: oss_audio_device.close()
127
128   Explicitly close the audio device.  When you are done writing to or reading from
129   an audio device, you should explicitly close it.  A closed device cannot be used
130   again.
131
132
n133-.. method:: audio device.fileno()
n134+.. method:: oss_audio_device.fileno()
134
135   Return the file descriptor associated with the device.
136
137
n138-.. method:: audio device.read(size)
n139+.. method:: oss_audio_device.read(size)
139
140   Read *size* bytes from the audio input and return them as a Python string.
141   Unlike most Unix device drivers, OSS audio devices in blocking mode (the
142   default) will block :func:`read` until the entire requested amount of data is
143   available.
144
145
n146-.. method:: audio device.write(data)
n147+.. method:: oss_audio_device.write(data)
147
148   Write the Python string *data* to the audio device and return the number of
149   bytes written.  If the audio device is in blocking mode (the default), the
150   entire string is always written (again, this is different from usual Unix device
151   semantics).  If the device is in non-blocking mode, some data may not be written
152   ---see :meth:`writeall`.
153
154
n155-.. method:: audio device.writeall(data)
n156+.. method:: oss_audio_device.writeall(data)
156
157   Write the entire Python string *data* to the audio device: waits until the audio
158   device is able to accept data, writes as much data as it will accept, and
159   repeats until *data* has been completely written. If the device is in blocking
160   mode (the default), this has the same effect as :meth:`write`; :meth:`writeall`
161   is only useful in non-blocking mode.  Has no return value, since the amount of
162   data written is always equal to the amount of data supplied.
163
164The following methods each map to exactly one :func:`ioctl` system call.  The
165correspondence is obvious: for example, :meth:`setfmt` corresponds to the
166``SNDCTL_DSP_SETFMT`` ioctl, and :meth:`sync` to ``SNDCTL_DSP_SYNC`` (this can
167be useful when consulting the OSS documentation).  If the underlying
168:func:`ioctl` fails, they all raise :exc:`IOError`.
169
170
n171-.. method:: audio device.nonblock()
n172+.. method:: oss_audio_device.nonblock()
172
173   Put the device into non-blocking mode.  Once in non-blocking mode, there is no
174   way to return it to blocking mode.
175
176
n177-.. method:: audio device.getfmts()
n178+.. method:: oss_audio_device.getfmts()
178
179   Return a bitmask of the audio output formats supported by the soundcard.  Some
180   of the formats supported by OSS are:
181
182   +-------------------------+---------------------------------------------+
183   | Format                  | Description                                 |
184   +=========================+=============================================+
185   | :const:`AFMT_MU_LAW`    | a logarithmic encoding (used by Sun ``.au`` |
206   +-------------------------+---------------------------------------------+
207
208   Consult the OSS documentation for a full list of audio formats, and note that
209   most devices support only a subset of these formats.  Some older devices only
210   support :const:`AFMT_U8`; the most common format used today is
211   :const:`AFMT_S16_LE`.
212
213
n214-.. method:: audio device.setfmt(format)
n215+.. method:: oss_audio_device.setfmt(format)
215
216   Try to set the current audio format to *format*---see :meth:`getfmts` for a
217   list.  Returns the audio format that the device was set to, which may not be the
218   requested format.  May also be used to return the current audio format---do this
219   by passing an "audio format" of :const:`AFMT_QUERY`.
220
221
n222-.. method:: audio device.channels(nchannels)
n223+.. method:: oss_audio_device.channels(nchannels)
223
224   Set the number of output channels to *nchannels*.  A value of 1 indicates
225   monophonic sound, 2 stereophonic.  Some devices may have more than 2 channels,
226   and some high-end devices may not support mono. Returns the number of channels
227   the device was set to.
228
229
n230-.. method:: audio device.speed(samplerate)
n231+.. method:: oss_audio_device.speed(samplerate)
231
232   Try to set the audio sampling rate to *samplerate* samples per second.  Returns
233   the rate actually set.  Most sound devices don't support arbitrary sampling
234   rates.  Common rates are:
235
236   +-------+-------------------------------------------+
237   | Rate  | Description                               |
238   +=======+===========================================+
244   +-------+-------------------------------------------+
245   | 44100 | CD quality audio (at 16 bits/sample and 2 |
246   |       | channels)                                 |
247   +-------+-------------------------------------------+
248   | 96000 | DVD quality audio (at 24 bits/sample)     |
249   +-------+-------------------------------------------+
250
251
n252-.. method:: audio device.sync()
n253+.. method:: oss_audio_device.sync()
253
254   Wait until the sound device has played every byte in its buffer.  (This happens
255   implicitly when the device is closed.)  The OSS documentation recommends closing
256   and re-opening the device rather than using :meth:`sync`.
257
258
n259-.. method:: audio device.reset()
n260+.. method:: oss_audio_device.reset()
260
261   Immediately stop playing or recording and return the device to a state where it
262   can accept commands.  The OSS documentation recommends closing and re-opening
263   the device after calling :meth:`reset`.
264
265
n266-.. method:: audio device.post()
n267+.. method:: oss_audio_device.post()
267
268   Tell the driver that there is likely to be a pause in the output, making it
269   possible for the device to handle the pause more intelligently.  You might use
270   this after playing a spot sound effect, before waiting for user input, or before
271   doing disk I/O.
272
273The following convenience methods combine several ioctls, or one ioctl and some
274simple calculations.
275
276
n277-.. method:: audio device.setparameters(format, nchannels, samplerate [, strict=False])
n278+.. method:: oss_audio_device.setparameters(format, nchannels, samplerate [, strict=False])
278
279   Set the key audio sampling parameters---sample format, number of channels, and
280   sampling rate---in one method call.  *format*,  *nchannels*, and *samplerate*
281   should be as specified in the :meth:`setfmt`, :meth:`channels`, and
282   :meth:`speed`  methods.  If *strict* is true, :meth:`setparameters` checks to
283   see if each parameter was actually set to the requested value, and raises
284   :exc:`OSSAudioError` if not.  Returns a tuple (*format*, *nchannels*,
285   *samplerate*) indicating the parameter values that were actually set by the
292
293   is equivalent to  ::
294
295      fmt = dsp.setfmt(fmt)
296      channels = dsp.channels(channels)
297      rate = dsp.rate(channels)
298
299
n300-.. method:: audio device.bufsize()
n301+.. method:: oss_audio_device.bufsize()
301
302   Returns the size of the hardware buffer, in samples.
303
304
n305-.. method:: audio device.obufcount()
n306+.. method:: oss_audio_device.obufcount()
306
307   Returns the number of samples that are in the hardware buffer yet to be played.
308
309
n310-.. method:: audio device.obuffree()
n311+.. method:: oss_audio_device.obuffree()
311
312   Returns the number of samples that could be queued into the hardware buffer to
313   be played without blocking.
314
315Audio device objects also support several read-only attributes:
316
317
n318-.. attribute:: audio device.closed
n319+.. attribute:: oss_audio_device.closed
319
320   Boolean indicating whether the device has been closed.
321
322
n323-.. attribute:: audio device.name
n324+.. attribute:: oss_audio_device.name
324
325   String containing the name of the device file.
326
327
n328-.. attribute:: audio device.mode
n329+.. attribute:: oss_audio_device.mode
329
330   The I/O mode for the file, either ``"r"``, ``"rw"``, or ``"w"``.
331
332
333.. _mixer-device-objects:
334
335Mixer Device Objects
336--------------------
337
338The mixer object provides two file-like methods:
339
340
n341-.. method:: mixer device.close()
n342+.. method:: oss_mixer_device.close()
342
343   This method closes the open mixer device file.  Any further attempts to use the
344   mixer after this file is closed will raise an :exc:`IOError`.
345
346
n347-.. method:: mixer device.fileno()
n348+.. method:: oss_mixer_device.fileno()
348
349   Returns the file handle number of the open mixer device file.
350
351The remaining methods are specific to audio mixing:
352
353
n354-.. method:: mixer device.controls()
n355+.. method:: oss_mixer_device.controls()
355
356   This method returns a bitmask specifying the available mixer controls ("Control"
357   being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or
358   :const:`SOUND_MIXER_SYNTH`).  This bitmask indicates a subset of all available
359   mixer controls---the :const:`SOUND_MIXER_\*` constants defined at module level.
360   To determine if, for example, the current mixer object supports a PCM mixer, use
361   the following Python code::
362
366          ... code ...
367
368   For most purposes, the :const:`SOUND_MIXER_VOLUME` (master volume) and
369   :const:`SOUND_MIXER_PCM` controls should suffice---but code that uses the mixer
370   should be flexible when it comes to choosing mixer controls.  On the Gravis
371   Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist.
372
373
n374-.. method:: mixer device.stereocontrols()
n375+.. method:: oss_mixer_device.stereocontrols()
375
376   Returns a bitmask indicating stereo mixer controls.  If a bit is set, the
377   corresponding control is stereo; if it is unset, the control is either
378   monophonic or not supported by the mixer (use in combination with
379   :meth:`controls` to determine which).
380
381   See the code example for the :meth:`controls` function for an example of getting
382   data from a bitmask.
383
384
n385-.. method:: mixer device.reccontrols()
n386+.. method:: oss_mixer_device.reccontrols()
386
387   Returns a bitmask specifying the mixer controls that may be used to record.  See
388   the code example for :meth:`controls` for an example of reading from a bitmask.
389
390
n391-.. method:: mixer device.get(control)
n392+.. method:: oss_mixer_device.get(control)
392
393   Returns the volume of a given mixer control.  The returned volume is a 2-tuple
394   ``(left_volume,right_volume)``.  Volumes are specified as numbers from 0
395   (silent) to 100 (full volume).  If the control is monophonic, a 2-tuple is still
396   returned, but both volumes are the same.
397
398   Raises :exc:`OSSAudioError` if an invalid control was is specified, or
399   :exc:`IOError` if an unsupported control is specified.
400
401
n402-.. method:: mixer device.set(control, (left, right))
n403+.. method:: oss_mixer_device.set(control, (left, right))
403
404   Sets the volume for a given mixer control to ``(left,right)``. ``left`` and
405   ``right`` must be ints and between 0 (silent) and 100 (full volume).  On
406   success, the new volume is returned as a 2-tuple. Note that this may not be
407   exactly the same as the volume specified, because of the limited resolution of
408   some soundcard's mixers.
409
410   Raises :exc:`OSSAudioError` if an invalid mixer control was specified, or if the
411   specified volumes were out-of-range.
412
413
n414-.. method:: mixer device.get_recsrc()
n415+.. method:: oss_mixer_device.get_recsrc()
415
416   This method returns a bitmask indicating which control(s) are currently being
417   used as a recording source.
418
419
t420-.. method:: mixer device.set_recsrc(bitmask)
t421+.. method:: oss_mixer_device.set_recsrc(bitmask)
421
422   Call this function to specify a recording source.  Returns a bitmask indicating
423   the new recording source (or sources) if successful; raises :exc:`IOError` if an
424   invalid source was specified.  To set the current recording source to the
425   microphone input::
426
427      mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
428
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op