Doc/library/sunaudio.rst

   1
   2 :mod:`sunaudiodev` --- Access to Sun audio hardware
   3 ===================================================
   4
   5 .. module:: sunaudiodev
   6    :platform: SunOS
   7    :synopsis: Access to Sun audio hardware.
   8    :deprecated:
   9
  10 .. deprecated:: 2.6
  11    The :mod:`sunaudiodev` module has been deprecated for removal in Python 3.0.
  12
  13
  14
  15 .. index:: single: u-LAW
  16
  17 This module allows you to access the Sun audio interface. The Sun audio hardware
  18 is capable of recording and playing back audio data in u-LAW format with a
  19 sample rate of 8K per second. A full description can be found in the
  20 :manpage:`audio(7I)` manual page.
  21
  22 .. index:: module: SUNAUDIODEV
  23
  24 The module :mod:`SUNAUDIODEV`  defines constants which may be used with this
  25 module.
  26
  27 This module defines the following variables and functions:
  28
  29
  30 .. exception:: error
  31
  32    This exception is raised on all errors. The argument is a string describing what
  33    went wrong.
  34
  35
  36 .. function:: open(mode)
  37
  38    This function opens the audio device and returns a Sun audio device object. This
  39    object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for
  40    record-only access, ``'w'`` for play-only access, ``'rw'`` for both and
  41    ``'control'`` for access to the control device. Since only one process is
  42    allowed to have the recorder or player open at the same time it is a good idea
  43    to open the device only for the activity needed. See :manpage:`audio(7I)` for
  44    details.
  45
  46    As per the manpage, this module first looks in the environment variable
  47    ``AUDIODEV`` for the base audio device filename.  If not found, it falls back to
  48    :file:`/dev/audio`.  The control device is calculated by appending "ctl" to the
  49    base audio device.
  50
  51
  52 .. _audio-device-objects:
  53
  54 Audio Device Objects
  55 --------------------
  56
  57 The audio device objects are returned by :func:`.open` define the following
  58 methods (except ``control`` objects which only provide :meth:`getinfo`,
  59 :meth:`setinfo`, :meth:`fileno`, and :meth:`drain`):
  60
  61
  62 .. method:: audio device.close()
  63
  64    This method explicitly closes the device. It is useful in situations where
  65    deleting the object does not immediately close it since there are other
  66    references to it. A closed device should not be used again.
  67
  68
  69 .. method:: audio device.fileno()
  70
  71    Returns the file descriptor associated with the device.  This can be used to set
  72    up ``SIGPOLL`` notification, as described below.
  73
  74
  75 .. method:: audio device.drain()
  76
  77    This method waits until all pending output is processed and then returns.
  78    Calling this method is often not necessary: destroying the object will
  79    automatically close the audio device and this will do an implicit drain.
  80
  81
  82 .. method:: audio device.flush()
  83
  84    This method discards all pending output. It can be used avoid the slow response
  85    to a user's stop request (due to buffering of up to one second of sound).
  86
  87
  88 .. method:: audio device.getinfo()
  89
  90    This method retrieves status information like input and output volume, etc. and
  91    returns it in the form of an audio status object. This object has no methods but
  92    it contains a number of attributes describing the current device status. The
  93    names and meanings of the attributes are described in ``<sun/audioio.h>`` and in
  94    the :manpage:`audio(7I)` manual page.  Member names are slightly different from
  95    their C counterparts: a status object is only a single structure. Members of the
  96    :cdata:`play` substructure have ``o_`` prepended to their name and members of
  97    the :cdata:`record` structure have ``i_``. So, the C member
  98    :cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`,
  99    :cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as
 100    :attr:`monitor_gain`.
 101
 102
 103 .. method:: audio device.ibufcount()
 104
 105    This method returns the number of samples that are buffered on the recording
 106    side, i.e. the program will not block on a :func:`read` call of so many samples.
 107
 108
 109 .. method:: audio device.obufcount()
 110
 111    This method returns the number of samples buffered on the playback side.
 112    Unfortunately, this number cannot be used to determine a number of samples that
 113    can be written without blocking since the kernel output queue length seems to be
 114    variable.
 115
 116
 117 .. method:: audio device.read(size)
 118
 119    This method reads *size* samples from the audio input and returns them as a
 120    Python string. The function blocks until enough data is available.
 121
 122
 123 .. method:: audio device.setinfo(status)
 124
 125    This method sets the audio device status parameters. The *status* parameter is
 126    an device status object as returned by :func:`getinfo` and possibly modified by
 127    the program.
 128
 129
 130 .. method:: audio device.write(samples)
 131
 132    Write is passed a Python string containing audio samples to be played. If there
 133    is enough buffer space free it will immediately return, otherwise it will block.
 134
 135 The audio device supports asynchronous notification of various events, through
 136 the SIGPOLL signal.  Here's an example of how you might enable this in Python::
 137
 138    def handle_sigpoll(signum, frame):
 139        print 'I got a SIGPOLL update'
 140
 141    import fcntl, signal, STROPTS
 142
 143    signal.signal(signal.SIGPOLL, handle_sigpoll)
 144    fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
 145
 146
 147 :mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev`
 148 =============================================================
 149
 150 .. module:: SUNAUDIODEV
 151    :platform: SunOS
 152    :synopsis: Constants for use with sunaudiodev.
 153    :deprecated:
 154
 155 .. deprecated:: 2.6
 156    The :mod:`SUNAUDIODEV` module has been deprecated for removal in Python 3.0.
 157
 158
 159
 160 .. index:: module: sunaudiodev
 161
 162 This is a companion module to :mod:`sunaudiodev` which defines useful symbolic
 163 constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The
 164 names of the constants are the same names as used in the C include file
 165 ``<sun/audioio.h>``, with the leading string ``AUDIO_`` stripped.
 166