##
17.1.1 Audio Device Objects

The audio device objects are returned by `open()` define the following methods (except `control` objects which only provide `getinfo()`, `setinfo()`, `fileno()`, and `drain()`):

`close` ()
  This method explicitly closes the device. It is useful in situations where deleting the object does not immediately close it since there are other references to it. A closed device should not be used again.

`fileno` ()
  Returns the file descriptor associated with the device. This can be used to set up `SIGPOLL` notification, as described below.

`drain` ()
  This method waits until all pending output is processed and then returns. Calling this method is often not necessary: destroying the object will automatically close the audio device and this will do an implicit drain.

`flush` ()
  This method discards all pending output. It can be used avoid the slow response to a user's stop request (due to buffering of up to one second of sound).

`getinfo` ()
  This method retrieves status information like input and output volume, etc. and returns it in the form of an audio status object. This object has no methods but it contains a number of attributes describing the current device status. The names and meanings of the attributes are described in `<sun/audioio.h>` and in the audio(7I) manual page. Member names are slightly different from their C counterparts: a status object is only a single structure. Members of the `play` substructure have "`o_`" prepended to their name and members of the `record` structure have "`i_`". So, the C member `play.sample_rate` is accessed as `o_sample_rate`, `record.gain` as `i_gain` and `monitor_gain` plainly as `monitor_gain`.

`ibufcount` ()
  This method returns the number of samples that are buffered on the recording side, i.e. the program will not block on a `read()` call of so many samples.

`obufcount` ()
  This method returns the number of samples buffered on the playback side. Unfortunately, this number cannot be used to determine a number of samples that can be written without blocking since the kernel output queue length seems to be variable.

`read` (size)
  This method reads size samples from the audio input and returns them as a Python string. The function blocks until enough data is available.

`setinfo` (status)
  This method sets the audio device status parameters. The status parameter is an device status object as returned by `getinfo()` and possibly modified by the program.

`write` (samples)
  Write is passed a Python string containing audio samples to be played. If there is enough buffer space free it will immediately return, otherwise it will block.

There is a companion module, `SUNAUDIODEV`, which defines useful symbolic constants like `MIN_GAIN`, `MAX_GAIN`, `SPEAKER`, etc. The names of the constants are the same names as used in the C include file `<sun/audioio.h>`, with the leading string "`AUDIO_`" stripped.

The audio device supports asynchronous notification of various events, through the SIGPOLL signal. Here's an example of how you might enable this in Python:

      def handle_sigpoll(signum, frame):
          print 'I got a SIGPOLL update'

      import fcntl, signal, STROPTS

      signal.signal(signal.SIGPOLL, handle_sigpoll)
      fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)