## 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 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.

`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 ``/usr/include/sun/audioio.h`' and in the audio man 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.

Useability of the control device is limited at the moment, since there is no way to use the ``wait for something to happen'' feature the device provides.