PageRenderTime 498ms CodeModel.GetById 139ms app.highlight 145ms RepoModel.GetById 201ms app.codeStats 1ms

/Doc/library/ossaudiodev.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 429 lines | 280 code | 149 blank | 0 comment | 0 complexity | efe36790c184de619a94c043f00c4cca MD5 | raw file
  1
  2:mod:`ossaudiodev` --- Access to OSS-compatible audio devices
  3=============================================================
  4
  5.. module:: ossaudiodev
  6   :platform: Linux, FreeBSD
  7   :synopsis: Access to OSS-compatible audio devices.
  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
 16.. 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
 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
 20   majority of Linux audio apps anyways.
 21
 22   Sounds like things are also complicated for other BSDs.  In response
 23   to my python-dev query, Thomas Wouters said:
 24
 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
 27   > kernel :)
 28
 29   but Aleksander Piotrowsk actually has an OpenBSD box, and he quotes
 30   from its <soundcard.h>:
 31   >  * WARNING!  WARNING!
 32   >  * This is an OSS (Linux) audio emulator.
 33   >  * Use the Native NetBSD API for developing new code, and this
 34   >  * only for compiling Linux programs.
 35
 36   There's also an ossaudio manpage on OpenBSD that explains things
 37   further.  Presumably NetBSD and OpenBSD have a different standard
 38   audio interface.  That's the great thing about standards, there are so
 39   many to choose from ... ;-)
 40
 41   This probably all warrants a footnote or two, but I don't understand
 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
 51   driver; see ``<sys/soundcard.h>`` on either Linux or FreeBSD for a listing .
 52
 53:mod:`ossaudiodev` defines the following variables and functions:
 54
 55
 56.. exception:: OSSAudioError
 57
 58   This exception is raised on certain errors.  The argument is a string describing
 59   what went wrong.
 60
 61   (If :mod:`ossaudiodev` receives an error from a system call such as
 62   :cfunc:`open`, :cfunc:`write`, or :cfunc:`ioctl`, it raises :exc:`IOError`.
 63   Errors detected directly by :mod:`ossaudiodev` result in :exc:`OSSAudioError`.)
 64
 65   (For backwards compatibility, the exception class is also available as
 66   ``ossaudiodev.error``.)
 67
 68
 69.. function:: open([device, ]mode)
 70
 71   Open an audio device and return an OSS audio device object.  This object
 72   supports many file-like methods, such as :meth:`read`, :meth:`write`, and
 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
 81   *mode* is one of ``'r'`` for read-only (record) access, ``'w'`` for
 82   write-only (playback) access and ``'rw'`` for both. Since many sound cards
 83   only allow one process to have the recorder or player open at a time, it is a
 84   good idea to open the device only for the activity needed.  Further, some
 85   sound cards are half-duplex: they can be opened for reading or writing, but
 86   not both at once.
 87
 88   Note the unusual calling syntax: the *first* argument is optional, and the
 89   second is required.  This is a historical artifact for compatibility with the
 90   older :mod:`linuxaudiodev` module which :mod:`ossaudiodev` supersedes.
 91
 92   .. XXX it might also be motivated
 93      by my unfounded-but-still-possibly-true belief that the default
 94      audio device varies unpredictably across operating systems.  -GW
 95
 96
 97.. function:: openmixer([device])
 98
 99   Open a mixer device and return an OSS mixer device object.   *device* is the
100   mixer device filename to use.  If it is not specified, this module first looks
101   in the environment variable :envvar:`MIXERDEV` for a device to use.  If not
102   found, it falls back to :file:`/dev/mixer`.
103
104
105.. _ossaudio-device-objects:
106
107Audio Device Objects
108--------------------
109
110Before you can write to or read from an audio device, you must call three
111methods in the correct order:
112
113#. :meth:`setfmt` to set the output format
114
115#. :meth:`channels` to set the number of channels
116
117#. :meth:`speed` to set the sample rate
118
119Alternately, you can use the :meth:`setparameters` method to set all three audio
120parameters at once.  This is more convenient, but may not be as flexible in all
121cases.
122
123The audio device objects returned by :func:`open` define the following methods
124and (read-only) attributes:
125
126
127.. method:: oss_audio_device.close()
128
129   Explicitly close the audio device.  When you are done writing to or reading from
130   an audio device, you should explicitly close it.  A closed device cannot be used
131   again.
132
133
134.. method:: oss_audio_device.fileno()
135
136   Return the file descriptor associated with the device.
137
138
139.. method:: oss_audio_device.read(size)
140
141   Read *size* bytes from the audio input and return them as a Python string.
142   Unlike most Unix device drivers, OSS audio devices in blocking mode (the
143   default) will block :func:`read` until the entire requested amount of data is
144   available.
145
146
147.. method:: oss_audio_device.write(data)
148
149   Write the Python string *data* to the audio device and return the number of
150   bytes written.  If the audio device is in blocking mode (the default), the
151   entire string is always written (again, this is different from usual Unix device
152   semantics).  If the device is in non-blocking mode, some data may not be written
153   ---see :meth:`writeall`.
154
155
156.. method:: oss_audio_device.writeall(data)
157
158   Write the entire Python string *data* to the audio device: waits until the audio
159   device is able to accept data, writes as much data as it will accept, and
160   repeats until *data* has been completely written. If the device is in blocking
161   mode (the default), this has the same effect as :meth:`write`; :meth:`writeall`
162   is only useful in non-blocking mode.  Has no return value, since the amount of
163   data written is always equal to the amount of data supplied.
164
165The following methods each map to exactly one :func:`ioctl` system call.  The
166correspondence is obvious: for example, :meth:`setfmt` corresponds to the
167``SNDCTL_DSP_SETFMT`` ioctl, and :meth:`sync` to ``SNDCTL_DSP_SYNC`` (this can
168be useful when consulting the OSS documentation).  If the underlying
169:func:`ioctl` fails, they all raise :exc:`IOError`.
170
171
172.. method:: oss_audio_device.nonblock()
173
174   Put the device into non-blocking mode.  Once in non-blocking mode, there is no
175   way to return it to blocking mode.
176
177
178.. method:: oss_audio_device.getfmts()
179
180   Return a bitmask of the audio output formats supported by the soundcard.  Some
181   of the formats supported by OSS are:
182
183   +-------------------------+---------------------------------------------+
184   | Format                  | Description                                 |
185   +=========================+=============================================+
186   | :const:`AFMT_MU_LAW`    | a logarithmic encoding (used by Sun ``.au`` |
187   |                         | files and :file:`/dev/audio`)               |
188   +-------------------------+---------------------------------------------+
189   | :const:`AFMT_A_LAW`     | a logarithmic encoding                      |
190   +-------------------------+---------------------------------------------+
191   | :const:`AFMT_IMA_ADPCM` | a 4:1 compressed format defined by the      |
192   |                         | Interactive Multimedia Association          |
193   +-------------------------+---------------------------------------------+
194   | :const:`AFMT_U8`        | Unsigned, 8-bit audio                       |
195   +-------------------------+---------------------------------------------+
196   | :const:`AFMT_S16_LE`    | Signed, 16-bit audio, little-endian byte    |
197   |                         | order (as used by Intel processors)         |
198   +-------------------------+---------------------------------------------+
199   | :const:`AFMT_S16_BE`    | Signed, 16-bit audio, big-endian byte order |
200   |                         | (as used by 68k, PowerPC, Sparc)            |
201   +-------------------------+---------------------------------------------+
202   | :const:`AFMT_S8`        | Signed, 8 bit audio                         |
203   +-------------------------+---------------------------------------------+
204   | :const:`AFMT_U16_LE`    | Unsigned, 16-bit little-endian audio        |
205   +-------------------------+---------------------------------------------+
206   | :const:`AFMT_U16_BE`    | Unsigned, 16-bit big-endian audio           |
207   +-------------------------+---------------------------------------------+
208
209   Consult the OSS documentation for a full list of audio formats, and note that
210   most devices support only a subset of these formats.  Some older devices only
211   support :const:`AFMT_U8`; the most common format used today is
212   :const:`AFMT_S16_LE`.
213
214
215.. method:: oss_audio_device.setfmt(format)
216
217   Try to set the current audio format to *format*---see :meth:`getfmts` for a
218   list.  Returns the audio format that the device was set to, which may not be the
219   requested format.  May also be used to return the current audio format---do this
220   by passing an "audio format" of :const:`AFMT_QUERY`.
221
222
223.. method:: oss_audio_device.channels(nchannels)
224
225   Set the number of output channels to *nchannels*.  A value of 1 indicates
226   monophonic sound, 2 stereophonic.  Some devices may have more than 2 channels,
227   and some high-end devices may not support mono. Returns the number of channels
228   the device was set to.
229
230
231.. method:: oss_audio_device.speed(samplerate)
232
233   Try to set the audio sampling rate to *samplerate* samples per second.  Returns
234   the rate actually set.  Most sound devices don't support arbitrary sampling
235   rates.  Common rates are:
236
237   +-------+-------------------------------------------+
238   | Rate  | Description                               |
239   +=======+===========================================+
240   | 8000  | default rate for :file:`/dev/audio`       |
241   +-------+-------------------------------------------+
242   | 11025 | speech recording                          |
243   +-------+-------------------------------------------+
244   | 22050 |                                           |
245   +-------+-------------------------------------------+
246   | 44100 | CD quality audio (at 16 bits/sample and 2 |
247   |       | channels)                                 |
248   +-------+-------------------------------------------+
249   | 96000 | DVD quality audio (at 24 bits/sample)     |
250   +-------+-------------------------------------------+
251
252
253.. method:: oss_audio_device.sync()
254
255   Wait until the sound device has played every byte in its buffer.  (This happens
256   implicitly when the device is closed.)  The OSS documentation recommends closing
257   and re-opening the device rather than using :meth:`sync`.
258
259
260.. method:: oss_audio_device.reset()
261
262   Immediately stop playing or recording and return the device to a state where it
263   can accept commands.  The OSS documentation recommends closing and re-opening
264   the device after calling :meth:`reset`.
265
266
267.. method:: oss_audio_device.post()
268
269   Tell the driver that there is likely to be a pause in the output, making it
270   possible for the device to handle the pause more intelligently.  You might use
271   this after playing a spot sound effect, before waiting for user input, or before
272   doing disk I/O.
273
274The following convenience methods combine several ioctls, or one ioctl and some
275simple calculations.
276
277
278.. method:: oss_audio_device.setparameters(format, nchannels, samplerate [, strict=False])
279
280   Set the key audio sampling parameters---sample format, number of channels, and
281   sampling rate---in one method call.  *format*,  *nchannels*, and *samplerate*
282   should be as specified in the :meth:`setfmt`, :meth:`channels`, and
283   :meth:`speed`  methods.  If *strict* is true, :meth:`setparameters` checks to
284   see if each parameter was actually set to the requested value, and raises
285   :exc:`OSSAudioError` if not.  Returns a tuple (*format*, *nchannels*,
286   *samplerate*) indicating the parameter values that were actually set by the
287   device driver (i.e., the same as the return values of :meth:`setfmt`,
288   :meth:`channels`, and :meth:`speed`).
289
290   For example,  ::
291
292      (fmt, channels, rate) = dsp.setparameters(fmt, channels, rate)
293
294   is equivalent to  ::
295
296      fmt = dsp.setfmt(fmt)
297      channels = dsp.channels(channels)
298      rate = dsp.rate(channels)
299
300
301.. method:: oss_audio_device.bufsize()
302
303   Returns the size of the hardware buffer, in samples.
304
305
306.. method:: oss_audio_device.obufcount()
307
308   Returns the number of samples that are in the hardware buffer yet to be played.
309
310
311.. method:: oss_audio_device.obuffree()
312
313   Returns the number of samples that could be queued into the hardware buffer to
314   be played without blocking.
315
316Audio device objects also support several read-only attributes:
317
318
319.. attribute:: oss_audio_device.closed
320
321   Boolean indicating whether the device has been closed.
322
323
324.. attribute:: oss_audio_device.name
325
326   String containing the name of the device file.
327
328
329.. attribute:: oss_audio_device.mode
330
331   The I/O mode for the file, either ``"r"``, ``"rw"``, or ``"w"``.
332
333
334.. _mixer-device-objects:
335
336Mixer Device Objects
337--------------------
338
339The mixer object provides two file-like methods:
340
341
342.. method:: oss_mixer_device.close()
343
344   This method closes the open mixer device file.  Any further attempts to use the
345   mixer after this file is closed will raise an :exc:`IOError`.
346
347
348.. method:: oss_mixer_device.fileno()
349
350   Returns the file handle number of the open mixer device file.
351
352The remaining methods are specific to audio mixing:
353
354
355.. method:: oss_mixer_device.controls()
356
357   This method returns a bitmask specifying the available mixer controls ("Control"
358   being a specific mixable "channel", such as :const:`SOUND_MIXER_PCM` or
359   :const:`SOUND_MIXER_SYNTH`).  This bitmask indicates a subset of all available
360   mixer controls---the :const:`SOUND_MIXER_\*` constants defined at module level.
361   To determine if, for example, the current mixer object supports a PCM mixer, use
362   the following Python code::
363
364      mixer=ossaudiodev.openmixer()
365      if mixer.controls() & (1 << ossaudiodev.SOUND_MIXER_PCM):
366          # PCM is supported
367          ... code ...
368
369   For most purposes, the :const:`SOUND_MIXER_VOLUME` (master volume) and
370   :const:`SOUND_MIXER_PCM` controls should suffice---but code that uses the mixer
371   should be flexible when it comes to choosing mixer controls.  On the Gravis
372   Ultrasound, for example, :const:`SOUND_MIXER_VOLUME` does not exist.
373
374
375.. method:: oss_mixer_device.stereocontrols()
376
377   Returns a bitmask indicating stereo mixer controls.  If a bit is set, the
378   corresponding control is stereo; if it is unset, the control is either
379   monophonic or not supported by the mixer (use in combination with
380   :meth:`controls` to determine which).
381
382   See the code example for the :meth:`controls` function for an example of getting
383   data from a bitmask.
384
385
386.. method:: oss_mixer_device.reccontrols()
387
388   Returns a bitmask specifying the mixer controls that may be used to record.  See
389   the code example for :meth:`controls` for an example of reading from a bitmask.
390
391
392.. method:: oss_mixer_device.get(control)
393
394   Returns the volume of a given mixer control.  The returned volume is a 2-tuple
395   ``(left_volume,right_volume)``.  Volumes are specified as numbers from 0
396   (silent) to 100 (full volume).  If the control is monophonic, a 2-tuple is still
397   returned, but both volumes are the same.
398
399   Raises :exc:`OSSAudioError` if an invalid control was is specified, or
400   :exc:`IOError` if an unsupported control is specified.
401
402
403.. method:: oss_mixer_device.set(control, (left, right))
404
405   Sets the volume for a given mixer control to ``(left,right)``. ``left`` and
406   ``right`` must be ints and between 0 (silent) and 100 (full volume).  On
407   success, the new volume is returned as a 2-tuple. Note that this may not be
408   exactly the same as the volume specified, because of the limited resolution of
409   some soundcard's mixers.
410
411   Raises :exc:`OSSAudioError` if an invalid mixer control was specified, or if the
412   specified volumes were out-of-range.
413
414
415.. method:: oss_mixer_device.get_recsrc()
416
417   This method returns a bitmask indicating which control(s) are currently being
418   used as a recording source.
419
420
421.. method:: oss_mixer_device.set_recsrc(bitmask)
422
423   Call this function to specify a recording source.  Returns a bitmask indicating
424   the new recording source (or sources) if successful; raises :exc:`IOError` if an
425   invalid source was specified.  To set the current recording source to the
426   microphone input::
427
428      mixer.setrecsrc (1 << ossaudiodev.SOUND_MIXER_MIC)
429