[OpenSPARC-T2-SAM] / sam-t2 / devtools / amd64 / html / python / lib / audio-device-objects.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="lib.html" title='Python Library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="prev" href="module-sunaudiodev.html" />
<link rel="parent" href="module-sunaudiodev.html" />
<link rel="next" href="module-sunaudiodev-constants.html" />
<meta name='aesop' content='information' />
<title>21.1.1 Audio Device Objects </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="21.1 sunaudiodev  "
  href="module-sunaudiodev.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="21.1 sunaudiodev  "
  href="module-sunaudiodev.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="21.2 SUNAUDIODEV  "
  href="module-sunaudiodev-constants.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sunaudiodev.html">21.1 sunaudiodev  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sunaudiodev.html">21.1 sunaudiodev  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-sunaudiodev-constants.html">21.2 SUNAUDIODEV  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H2><A NAME="SECTION0023110000000000000000"></A><A NAME="audio-device-objects"></A>
<BR>
21.1.1 Audio Device Objects 
</H2>

<P>
The audio device objects are returned by <tt class="function">open()</tt> define the
following methods (except <code>control</code> objects which only provide
<tt class="method">getinfo()</tt>, <tt class="method">setinfo()</tt>, <tt class="method">fileno()</tt>, and
<tt class="method">drain()</tt>):

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5227' xml:id='l2h-5227' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
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.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5228' xml:id='l2h-5228' class="method">fileno</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Returns the file descriptor associated with the device.  This can be
used to set up <code>SIGPOLL</code> notification, as described below.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5229' xml:id='l2h-5229' class="method">drain</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
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.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5230' xml:id='l2h-5230' class="method">flush</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
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).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5231' xml:id='l2h-5231' class="method">getinfo</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
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
<code>&lt;sun/audioio.h&gt;</code> and in the <span class="manpage"><i>audio</i>(7I)</span>
manual page.  Member names
are slightly different from their C counterparts: a status object is
only a single structure. Members of the <tt class="cdata">play</tt> substructure have
"<tt class="samp">o_</tt>" prepended to their name and members of the <tt class="cdata">record</tt>
structure have "<tt class="samp">i_</tt>". So, the C member <tt class="cdata">play.sample_rate</tt> is
accessed as <tt class="member">o_sample_rate</tt>, <tt class="cdata">record.gain</tt> as <tt class="member">i_gain</tt>
and <tt class="cdata">monitor_gain</tt> plainly as <tt class="member">monitor_gain</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5232' xml:id='l2h-5232' class="method">ibufcount</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
This method returns the number of samples that are buffered on the
recording side, i.e. the program will not block on a
<tt class="function">read()</tt> call of so many samples.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5233' xml:id='l2h-5233' class="method">obufcount</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
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.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5234' xml:id='l2h-5234' class="method">read</tt></b>(</nobr></td>
  <td><var>size</var>)</td></tr></table></dt>
<dd>
This method reads <var>size</var> samples from the audio input and returns
them as a Python string. The function blocks until enough data is available.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5235' xml:id='l2h-5235' class="method">setinfo</tt></b>(</nobr></td>
  <td><var>status</var>)</td></tr></table></dt>
<dd>
This method sets the audio device status parameters. The <var>status</var>
parameter is an device status object as returned by <tt class="function">getinfo()</tt> and
possibly modified by the program.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-5236' xml:id='l2h-5236' class="method">write</tt></b>(</nobr></td>
  <td><var>samples</var>)</td></tr></table></dt>
<dd>
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.
</dl>

<P>
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:

<P>
<div class="verbatim"><pre>
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)
</pre></div>

<P>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="21.1 sunaudiodev  "
  href="module-sunaudiodev.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="21.1 sunaudiodev  "
  href="module-sunaudiodev.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="21.2 SUNAUDIODEV  "
  href="module-sunaudiodev-constants.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-sunaudiodev.html">21.1 sunaudiodev  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-sunaudiodev.html">21.1 sunaudiodev  </A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-sunaudiodev-constants.html">21.2 SUNAUDIODEV  </A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>
Commit	Line	Data
920dae64 AT	1	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	2	<html>
	3	<head>
	4	<link rel="STYLESHEET" href="lib.css" type='text/css' />
	5	<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
	6	<link rel='start' href='../index.html' title='Python Documentation Index' />
	7	<link rel="first" href="lib.html" title='Python Library Reference' />
	8	<link rel='contents' href='contents.html' title="Contents" />
	9	<link rel='index' href='genindex.html' title='Index' />
	10	<link rel='last' href='about.html' title='About this document...' />
	11	<link rel='help' href='about.html' title='About this document...' />
	12	<link rel="prev" href="module-sunaudiodev.html" />
	13	<link rel="parent" href="module-sunaudiodev.html" />
	14	<link rel="next" href="module-sunaudiodev-constants.html" />
	15	<meta name='aesop' content='information' />
	16	<title>21.1.1 Audio Device Objects </title>
	17	</head>
	18	<body>
	19	<DIV CLASS="navigation">
	20	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	21	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	22	<tr>
	23	<td class='online-navigation'><a rel="prev" title="21.1 sunaudiodev "
	24	href="module-sunaudiodev.html"><img src='../icons/previous.png'
	25	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	26	<td class='online-navigation'><a rel="parent" title="21.1 sunaudiodev "
	27	href="module-sunaudiodev.html"><img src='../icons/up.png'
	28	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	29	<td class='online-navigation'><a rel="next" title="21.2 SUNAUDIODEV "
	30	href="module-sunaudiodev-constants.html"><img src='../icons/next.png'
	31	border='0' height='32' alt='Next Page' width='32' /></A></td>
	32	<td align="center" width="100%">Python Library Reference</td>
	33	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	34	href="contents.html"><img src='../icons/contents.png'
	35	border='0' height='32' alt='Contents' width='32' /></A></td>
	36	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	37	border='0' height='32' alt='Module Index' width='32' /></a></td>
	38	<td class='online-navigation'><a rel="index" title="Index"
	39	href="genindex.html"><img src='../icons/index.png'
	40	border='0' height='32' alt='Index' width='32' /></A></td>
	41	</tr></table>
	42	<div class='online-navigation'>
	43	<b class="navlabel">Previous:</b>
	44	<a class="sectref" rel="prev" href="module-sunaudiodev.html">21.1 sunaudiodev </A>
	45	<b class="navlabel">Up:</b>
	46	<a class="sectref" rel="parent" href="module-sunaudiodev.html">21.1 sunaudiodev </A>
	47	<b class="navlabel">Next:</b>
	48	<a class="sectref" rel="next" href="module-sunaudiodev-constants.html">21.2 SUNAUDIODEV </A>
	49	</div>
	50	<hr /></div>
	51	</DIV>
	52	<!--End of Navigation Panel-->
	53
	54	<H2><A NAME="SECTION0023110000000000000000"></A><A NAME="audio-device-objects"></A>
	55	<BR>
	56	21.1.1 Audio Device Objects
	57	</H2>
	58
	59	<P>
	60	The audio device objects are returned by <tt class="function">open()</tt> define the
	61	following methods (except <code>control</code> objects which only provide
	62	<tt class="method">getinfo()</tt>, <tt class="method">setinfo()</tt>, <tt class="method">fileno()</tt>, and
	63	<tt class="method">drain()</tt>):
	64
65	<P>
66	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
67	<td><nobr><b><tt id='l2h-5227' xml:id='l2h-5227' class="method">close</tt></b>(</nobr></td>
68	<td><var></var>)</td></tr></table></dt>
69	<dd>
70	This method explicitly closes the device. It is useful in situations
71	where deleting the object does not immediately close it since there
72	are other references to it. A closed device should not be used again.
73	</dl>
74
75	<P>
76	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
77	<td><nobr><b><tt id='l2h-5228' xml:id='l2h-5228' class="method">fileno</tt></b>(</nobr></td>
78	<td><var></var>)</td></tr></table></dt>
79	<dd>
80	Returns the file descriptor associated with the device. This can be
81	used to set up <code>SIGPOLL</code> notification, as described below.
82	</dl>
83
84	<P>
85	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
86	<td><nobr><b><tt id='l2h-5229' xml:id='l2h-5229' class="method">drain</tt></b>(</nobr></td>
87	<td><var></var>)</td></tr></table></dt>
88	<dd>
89	This method waits until all pending output is processed and then returns.
90	Calling this method is often not necessary: destroying the object will
91	automatically close the audio device and this will do an implicit drain.
92	</dl>
93
94	<P>
95	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
96	<td><nobr><b><tt id='l2h-5230' xml:id='l2h-5230' class="method">flush</tt></b>(</nobr></td>
97	<td><var></var>)</td></tr></table></dt>
98	<dd>
99	This method discards all pending output. It can be used avoid the
100	slow response to a user's stop request (due to buffering of up to one
101	second of sound).
102	</dl>
103
104	<P>
105	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
106	<td><nobr><b><tt id='l2h-5231' xml:id='l2h-5231' class="method">getinfo</tt></b>(</nobr></td>
107	<td><var></var>)</td></tr></table></dt>
108	<dd>
109	This method retrieves status information like input and output volume,
110	etc. and returns it in the form of
111	an audio status object. This object has no methods but it contains a
112	number of attributes describing the current device status. The names
113	and meanings of the attributes are described in
114	<code><sun/audioio.h></code> and in the <span class="manpage"><i>audio</i>(7I)</span>
115	manual page. Member names
116	are slightly different from their C counterparts: a status object is
117	only a single structure. Members of the <tt class="cdata">play</tt> substructure have
118	"<tt class="samp">o_</tt>" prepended to their name and members of the <tt class="cdata">record</tt>
119	structure have "<tt class="samp">i_</tt>". So, the C member <tt class="cdata">play.sample_rate</tt> is
120	accessed as <tt class="member">o_sample_rate</tt>, <tt class="cdata">record.gain</tt> as <tt class="member">i_gain</tt>
121	and <tt class="cdata">monitor_gain</tt> plainly as <tt class="member">monitor_gain</tt>.
122	</dl>
123
124	<P>
125	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
126	<td><nobr><b><tt id='l2h-5232' xml:id='l2h-5232' class="method">ibufcount</tt></b>(</nobr></td>
127	<td><var></var>)</td></tr></table></dt>
128	<dd>
129	This method returns the number of samples that are buffered on the
130	recording side, i.e. the program will not block on a
131	<tt class="function">read()</tt> call of so many samples.
132	</dl>
133
134	<P>
135	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
136	<td><nobr><b><tt id='l2h-5233' xml:id='l2h-5233' class="method">obufcount</tt></b>(</nobr></td>
137	<td><var></var>)</td></tr></table></dt>
138	<dd>
139	This method returns the number of samples buffered on the playback
140	side. Unfortunately, this number cannot be used to determine a number
141	of samples that can be written without blocking since the kernel
142	output queue length seems to be variable.
143	</dl>
144
145	<P>
146	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
147	<td><nobr><b><tt id='l2h-5234' xml:id='l2h-5234' class="method">read</tt></b>(</nobr></td>
148	<td><var>size</var>)</td></tr></table></dt>
149	<dd>
150	This method reads <var>size</var> samples from the audio input and returns
151	them as a Python string. The function blocks until enough data is available.
152	</dl>
153
154	<P>
155	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
156	<td><nobr><b><tt id='l2h-5235' xml:id='l2h-5235' class="method">setinfo</tt></b>(</nobr></td>
157	<td><var>status</var>)</td></tr></table></dt>
158	<dd>
159	This method sets the audio device status parameters. The <var>status</var>
160	parameter is an device status object as returned by <tt class="function">getinfo()</tt> and
161	possibly modified by the program.
162	</dl>
163
164	<P>
165	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
166	<td><nobr><b><tt id='l2h-5236' xml:id='l2h-5236' class="method">write</tt></b>(</nobr></td>
167	<td><var>samples</var>)</td></tr></table></dt>
168	<dd>
169	Write is passed a Python string containing audio samples to be played.
170	If there is enough buffer space free it will immediately return,
171	otherwise it will block.
172	</dl>
173
174	<P>
175	The audio device supports asynchronous notification of various events,
176	through the SIGPOLL signal. Here's an example of how you might enable
177	this in Python:
178
179	<P>
180	<div class="verbatim"><pre>
181	def handle_sigpoll(signum, frame):
182	print 'I got a SIGPOLL update'
183
184	import fcntl, signal, STROPTS
185
186	signal.signal(signal.SIGPOLL, handle_sigpoll)
187	fcntl.ioctl(audio_obj.fileno(), STROPTS.I_SETSIG, STROPTS.S_MSG)
188	</pre></div>
189
190	<P>
191
192	<DIV CLASS="navigation">
193	<div class='online-navigation'>
194	<p></p><hr />
195	<table align="center" width="100%" cellpadding="0" cellspacing="2">
196	<tr>
197	<td class='online-navigation'><a rel="prev" title="21.1 sunaudiodev "
198	href="module-sunaudiodev.html"><img src='../icons/previous.png'
199	border='0' height='32' alt='Previous Page' width='32' /></A></td>
200	<td class='online-navigation'><a rel="parent" title="21.1 sunaudiodev "
201	href="module-sunaudiodev.html"><img src='../icons/up.png'
202	border='0' height='32' alt='Up One Level' width='32' /></A></td>
203	<td class='online-navigation'><a rel="next" title="21.2 SUNAUDIODEV "
204	href="module-sunaudiodev-constants.html"><img src='../icons/next.png'
205	border='0' height='32' alt='Next Page' width='32' /></A></td>
206	<td align="center" width="100%">Python Library Reference</td>
207	<td class='online-navigation'><a rel="contents" title="Table of Contents"
208	href="contents.html"><img src='../icons/contents.png'
209	border='0' height='32' alt='Contents' width='32' /></A></td>
210	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
211	border='0' height='32' alt='Module Index' width='32' /></a></td>
212	<td class='online-navigation'><a rel="index" title="Index"
213	href="genindex.html"><img src='../icons/index.png'
214	border='0' height='32' alt='Index' width='32' /></A></td>
215	</tr></table>
216	<div class='online-navigation'>
217	<b class="navlabel">Previous:</b>
218	<a class="sectref" rel="prev" href="module-sunaudiodev.html">21.1 sunaudiodev </A>
219	<b class="navlabel">Up:</b>
220	<a class="sectref" rel="parent" href="module-sunaudiodev.html">21.1 sunaudiodev </A>
221	<b class="navlabel">Next:</b>
222	<a class="sectref" rel="next" href="module-sunaudiodev-constants.html">21.2 SUNAUDIODEV </A>
223	</div>
224	</div>
225	<hr />
226	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
227	</DIV>
228	<!--End of Navigation Panel-->
229	<ADDRESS>
230	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
231	</ADDRESS>
232	</BODY>
233	</HTML>