/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
 17This module allows you to access the Sun audio interface. The Sun audio hardware
 18is capable of recording and playing back audio data in u-LAW format with a
 19sample 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
 24The module :mod:`SUNAUDIODEV`  defines constants which may be used with this
 25module.
 26
 27This 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
 54Audio Device Objects
 55--------------------
 56
 57The audio device objects are returned by :func:`open` define the following
 58methods (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
135The audio device supports asynchronous notification of various events, through
136the 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
162This is a companion module to :mod:`sunaudiodev` which defines useful symbolic
163constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The
164names 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