diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/sunaudio.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/sunaudio.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,166 @@ + +:mod:`sunaudiodev` --- Access to Sun audio hardware +=================================================== + +.. module:: sunaudiodev + :platform: SunOS + :synopsis: Access to Sun audio hardware. + :deprecated: + +.. deprecated:: 2.6 + The :mod:`sunaudiodev` module has been deprecated for removal in Python 3.0. + + + +.. index:: single: u-LAW + +This module allows you to access the Sun audio interface. The Sun audio hardware +is capable of recording and playing back audio data in u-LAW format with a +sample rate of 8K per second. A full description can be found in the +:manpage:`audio(7I)` manual page. + +.. index:: module: SUNAUDIODEV + +The module :mod:`SUNAUDIODEV` defines constants which may be used with this +module. + +This module defines the following variables and functions: + + +.. exception:: error + + This exception is raised on all errors. The argument is a string describing what + went wrong. + + +.. function:: open(mode) + + This function opens the audio device and returns a Sun audio device object. This + object can then be used to do I/O on. The *mode* parameter is one of ``'r'`` for + record-only access, ``'w'`` for play-only access, ``'rw'`` for both and + ``'control'`` for access to the control device. Since only one process is + allowed to have the recorder or player open at the same time it is a good idea + to open the device only for the activity needed. See :manpage:`audio(7I)` for + details. + + As per the manpage, this module first looks in the environment variable + ``AUDIODEV`` for the base audio device filename. If not found, it falls back to + :file:`/dev/audio`. The control device is calculated by appending "ctl" to the + base audio device. + + +.. _audio-device-objects: + +Audio Device Objects +-------------------- + +The audio device objects are returned by :func:`open` define the following +methods (except ``control`` objects which only provide :meth:`getinfo`, +:meth:`setinfo`, :meth:`fileno`, and :meth:`drain`): + + +.. method:: audio device.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. + + +.. method:: audio device.fileno() + + Returns the file descriptor associated with the device. This can be used to set + up ``SIGPOLL`` notification, as described below. + + +.. method:: audio device.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. + + +.. method:: audio device.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). + + +.. method:: audio device.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 ```` and in + the :manpage:`audio(7I)` manual page. Member names are slightly different from + their C counterparts: a status object is only a single structure. Members of the + :cdata:`play` substructure have ``o_`` prepended to their name and members of + the :cdata:`record` structure have ``i_``. So, the C member + :cdata:`play.sample_rate` is accessed as :attr:`o_sample_rate`, + :cdata:`record.gain` as :attr:`i_gain` and :cdata:`monitor_gain` plainly as + :attr:`monitor_gain`. + + +.. method:: audio device.ibufcount() + + This method returns the number of samples that are buffered on the recording + side, i.e. the program will not block on a :func:`read` call of so many samples. + + +.. method:: audio device.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. + + +.. method:: audio device.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. + + +.. method:: audio device.setinfo(status) + + This method sets the audio device status parameters. The *status* parameter is + an device status object as returned by :func:`getinfo` and possibly modified by + the program. + + +.. method:: audio device.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. + +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) + + +:mod:`SUNAUDIODEV` --- Constants used with :mod:`sunaudiodev` +============================================================= + +.. module:: SUNAUDIODEV + :platform: SunOS + :synopsis: Constants for use with sunaudiodev. + :deprecated: + +.. deprecated:: 2.6 + The :mod:`SUNAUDIODEV` module has been deprecated for removal in Python 3.0. + + + +.. index:: module: sunaudiodev + +This is a companion module to :mod:`sunaudiodev` which defines useful symbolic +constants like :const:`MIN_GAIN`, :const:`MAX_GAIN`, :const:`SPEAKER`, etc. The +names of the constants are the same names as used in the C include file +````, with the leading string ``AUDIO_`` stripped. +