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 removed in Python 3. 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 :c:data:`play` substructure have ``o_`` prepended to their name and members of 97 the :c:data:`record` structure have ``i_``. So, the C member 98 :c:data:`play.sample_rate` is accessed as :attr:`o_sample_rate`, 99 :c:data:`record.gain` as :attr:`i_gain` and :c:data:`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 a 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 removed in Python 3. 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 167
