|
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 |
|
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 :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 |
|
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 deprecated for removal in Python 3.0. |
|
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 |