← Back to branch summary

~malept/ubuntu/lucid/python2.6/dev-dependency-fix

« back to all changes in this revision

Viewing changes to Doc/library/sunaudio.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-02-13 12:51:00 UTC
  • Revision ID: james.westby@ubuntu.com-20090213125100-uufgcb9yeqzujpqw
Tags: upstream-2.6.1
Import upstream version 2.6.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/library/sunaudio.rst
 
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