[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / html / python / lib / module-aifc.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="next" href="module-sunau.html" />
<link rel="prev" href="module-imageop.html" />
<link rel="parent" href="mmedia.html" />
<link rel="next" href="module-sunau.html" />
<meta name='aesop' content='information' />
<title>14.3 aifc -- Read and write AIFF and AIFC files</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="14.2 imageop  "
  href="module-imageop.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="14. Multimedia Services"
  href="mmedia.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="14.4 sunau  "
  href="module-sunau.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-imageop.html">14.2 imageop  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-sunau.html">14.4 sunau  </A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION0016300000000000000000">
14.3 <tt class="module">aifc</tt> --
         Read and write AIFF and AIFC files</A>
</H1>

<P>
<A NAME="module-aifc"></A>

<P>
This module provides support for reading and writing AIFF and AIFF-C
files.  AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file.  AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
<a id='l2h-4664' xml:id='l2h-4664'></a>

<P>
<strong>Caveat:</strong>  Some operations may only work under IRIX; these will
raise <tt class="exception">ImportError</tt> when attempting to import the
<tt class="module">cl</tt> module, which is only available on IRIX.

<P>
Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
sound is sampled.  The number of channels indicate if the audio is
mono, stereo, or quadro.  Each frame consists of one sample per
channel.  The sample size is the size in bytes of each sample.  Thus a
frame consists of <var>nchannels</var>*<var>samplesize</var> bytes, and a
second's worth of audio consists of
<var>nchannels</var>*<var>samplesize</var>*<var>framerate</var> bytes.

<P>
For example, CD quality audio has a sample size of two bytes (16
bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second.  This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes (176,400 bytes).

<P>
Module <tt class="module">aifc</tt> defines the following function:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4636' xml:id='l2h-4636' class="function">open</tt></b>(</nobr></td>
  <td><var>file</var><big>[</big><var>, mode</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below.  The argument <var>file</var> is either a
string naming a file or a file object.  <var>mode</var> must be <code>'r'</code>
or <code>'rb'</code> when the file must be opened for reading, or <code>'w'</code> 
or <code>'wb'</code> when the file must be opened for writing.  If omitted,
<code><var>file</var>.mode</code> is used if it exists, otherwise <code>'rb'</code> is
used.  When used for writing, the file object should be seekable,
unless you know ahead of time how many samples you are going to write
in total and use <tt class="method">writeframesraw()</tt> and <tt class="method">setnframes()</tt>.
</dl>

<P>
Objects returned by <tt class="function">open()</tt> when a file is opened for
reading have the following methods:

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4637' xml:id='l2h-4637' class="method">getnchannels</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the number of audio channels (1 for mono, 2 for stereo).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4638' xml:id='l2h-4638' class="method">getsampwidth</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the size in bytes of individual samples.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4639' xml:id='l2h-4639' class="method">getframerate</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the sampling rate (number of audio frames per second).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4640' xml:id='l2h-4640' class="method">getnframes</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the number of audio frames in the file.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4641' xml:id='l2h-4641' class="method">getcomptype</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a four-character string describing the type of compression used
in the audio file.  For AIFF files, the returned value is
<code>'NONE'</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4642' xml:id='l2h-4642' class="method">getcompname</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a human-readable description of the type of compression used in
the audio file.  For AIFF files, the returned value is <code>'not
compressed'</code>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4643' xml:id='l2h-4643' class="method">getparams</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a tuple consisting of all of the above values in the above
order.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4644' xml:id='l2h-4644' class="method">getmarkers</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return a list of markers in the audio file.  A marker consists of a
tuple of three elements.  The first is the mark ID (an integer), the
second is the mark position in frames from the beginning of the data
(an integer), the third is the name of the mark (a string).
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4645' xml:id='l2h-4645' class="method">getmark</tt></b>(</nobr></td>
  <td><var>id</var>)</td></tr></table></dt>
<dd>
Return the tuple as described in <tt class="method">getmarkers()</tt> for the mark
with the given <var>id</var>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4646' xml:id='l2h-4646' class="method">readframes</tt></b>(</nobr></td>
  <td><var>nframes</var>)</td></tr></table></dt>
<dd>
Read and return the next <var>nframes</var> frames from the audio file.  The
returned data is a string containing for each frame the uncompressed
samples of all channels.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4647' xml:id='l2h-4647' class="method">rewind</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Rewind the read pointer.  The next <tt class="method">readframes()</tt> will start from
the beginning.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4648' xml:id='l2h-4648' class="method">setpos</tt></b>(</nobr></td>
  <td><var>pos</var>)</td></tr></table></dt>
<dd>
Seek to the specified frame number.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4649' xml:id='l2h-4649' class="method">tell</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current frame number.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4650' xml:id='l2h-4650' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Close the AIFF file.  After calling this method, the object can no
longer be used.
</dl>

<P>
Objects returned by <tt class="function">open()</tt> when a file is opened for
writing have all the above methods, except for <tt class="method">readframes()</tt> and
<tt class="method">setpos()</tt>.  In addition the following methods exist.  The
<tt class="method">get*()</tt> methods can only be called after the corresponding
<tt class="method">set*()</tt> methods have been called.  Before the first
<tt class="method">writeframes()</tt> or <tt class="method">writeframesraw()</tt>, all parameters
except for the number of frames must be filled in.

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4651' xml:id='l2h-4651' class="method">aiff</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Create an AIFF file.  The default is that an AIFF-C file is created,
unless the name of the file ends in <code>'.aiff'</code> in which case the
default is an AIFF file.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4652' xml:id='l2h-4652' class="method">aifc</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Create an AIFF-C file.  The default is that an AIFF-C file is created,
unless the name of the file ends in <code>'.aiff'</code> in which case the
default is an AIFF file.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4653' xml:id='l2h-4653' class="method">setnchannels</tt></b>(</nobr></td>
  <td><var>nchannels</var>)</td></tr></table></dt>
<dd>
Specify the number of channels in the audio file.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4654' xml:id='l2h-4654' class="method">setsampwidth</tt></b>(</nobr></td>
  <td><var>width</var>)</td></tr></table></dt>
<dd>
Specify the size in bytes of audio samples.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4655' xml:id='l2h-4655' class="method">setframerate</tt></b>(</nobr></td>
  <td><var>rate</var>)</td></tr></table></dt>
<dd>
Specify the sampling frequency in frames per second.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4656' xml:id='l2h-4656' class="method">setnframes</tt></b>(</nobr></td>
  <td><var>nframes</var>)</td></tr></table></dt>
<dd>
Specify the number of frames that are to be written to the audio file.
If this parameter is not set, or not set correctly, the file needs to
support seeking.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4657' xml:id='l2h-4657' class="method">setcomptype</tt></b>(</nobr></td>
  <td><var>type, name</var>)</td></tr></table></dt>
<dd>
Specify the compression type.  If not specified, the audio data will
not be compressed.  In AIFF files, compression is not possible.  The
name parameter should be a human-readable description of the
compression type, the type parameter should be a four-character
string.  Currently the following compression types are supported:
NONE, ULAW, ALAW, G722.
<a id='l2h-4665' xml:id='l2h-4665'></a>
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4658' xml:id='l2h-4658' class="method">setparams</tt></b>(</nobr></td>
  <td><var>nchannels, sampwidth, framerate, comptype, compname</var>)</td></tr></table></dt>
<dd>
Set all the above parameters at once.  The argument is a tuple
consisting of the various parameters.  This means that it is possible
to use the result of a <tt class="method">getparams()</tt> call as argument to
<tt class="method">setparams()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4659' xml:id='l2h-4659' class="method">setmark</tt></b>(</nobr></td>
  <td><var>id, pos, name</var>)</td></tr></table></dt>
<dd>
Add a mark with the given id (larger than 0), and the given name at
the given position.  This method can be called at any time before
<tt class="method">close()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4660' xml:id='l2h-4660' class="method">tell</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Return the current write position in the output file.  Useful in
combination with <tt class="method">setmark()</tt>.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4661' xml:id='l2h-4661' class="method">writeframes</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Write data to the output file.  This method can only be called after
the audio file parameters have been set.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4662' xml:id='l2h-4662' class="method">writeframesraw</tt></b>(</nobr></td>
  <td><var>data</var>)</td></tr></table></dt>
<dd>
Like <tt class="method">writeframes()</tt>, except that the header of the audio file
is not updated.
</dl>

<P>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-4663' xml:id='l2h-4663' class="method">close</tt></b>(</nobr></td>
  <td><var></var>)</td></tr></table></dt>
<dd>
Close the AIFF file.  The header of the file is updated to reflect the
actual size of the audio data. After calling this method, the object
can no longer be used.
</dl>

<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="14.2 imageop  "
  href="module-imageop.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="14. Multimedia Services"
  href="mmedia.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="14.4 sunau  "
  href="module-sunau.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-imageop.html">14.2 imageop  </A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="module-sunau.html">14.4 sunau  </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="next" href="module-sunau.html" />
	13	<link rel="prev" href="module-imageop.html" />
	14	<link rel="parent" href="mmedia.html" />
	15	<link rel="next" href="module-sunau.html" />
	16	<meta name='aesop' content='information' />
	17	<title>14.3 aifc -- Read and write AIFF and AIFC files</title>
	18	</head>
	19	<body>
	20	<DIV CLASS="navigation">
	21	<div id='top-navigation-panel' xml:id='top-navigation-panel'>
	22	<table align="center" width="100%" cellpadding="0" cellspacing="2">
	23	<tr>
	24	<td class='online-navigation'><a rel="prev" title="14.2 imageop "
	25	href="module-imageop.html"><img src='../icons/previous.png'
	26	border='0' height='32' alt='Previous Page' width='32' /></A></td>
	27	<td class='online-navigation'><a rel="parent" title="14. Multimedia Services"
	28	href="mmedia.html"><img src='../icons/up.png'
	29	border='0' height='32' alt='Up One Level' width='32' /></A></td>
	30	<td class='online-navigation'><a rel="next" title="14.4 sunau "
	31	href="module-sunau.html"><img src='../icons/next.png'
	32	border='0' height='32' alt='Next Page' width='32' /></A></td>
	33	<td align="center" width="100%">Python Library Reference</td>
	34	<td class='online-navigation'><a rel="contents" title="Table of Contents"
	35	href="contents.html"><img src='../icons/contents.png'
	36	border='0' height='32' alt='Contents' width='32' /></A></td>
	37	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
	38	border='0' height='32' alt='Module Index' width='32' /></a></td>
	39	<td class='online-navigation'><a rel="index" title="Index"
	40	href="genindex.html"><img src='../icons/index.png'
	41	border='0' height='32' alt='Index' width='32' /></A></td>
	42	</tr></table>
	43	<div class='online-navigation'>
	44	<b class="navlabel">Previous:</b>
	45	<a class="sectref" rel="prev" href="module-imageop.html">14.2 imageop </A>
	46	<b class="navlabel">Up:</b>
	47	<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
	48	<b class="navlabel">Next:</b>
	49	<a class="sectref" rel="next" href="module-sunau.html">14.4 sunau </A>
	50	</div>
	51	<hr /></div>
	52	</DIV>
	53	<!--End of Navigation Panel-->
	54
	55	<H1><A NAME="SECTION0016300000000000000000">
	56	14.3 <tt class="module">aifc</tt> --
	57	Read and write AIFF and AIFC files</A>
	58	</H1>
	59
	60	<P>
	61	<A NAME="module-aifc"></A>
	62
	63	<P>
	64	This module provides support for reading and writing AIFF and AIFF-C
65	files. AIFF is Audio Interchange File Format, a format for storing
66	digital audio samples in a file. AIFF-C is a newer version of the
67	format that includes the ability to compress the audio data.
68	<a id='l2h-4664' xml:id='l2h-4664'></a>
69
70	<P>
71	<strong>Caveat:</strong> Some operations may only work under IRIX; these will
72	raise <tt class="exception">ImportError</tt> when attempting to import the
73	<tt class="module">cl</tt> module, which is only available on IRIX.
74
75	<P>
76	Audio files have a number of parameters that describe the audio data.
77	The sampling rate or frame rate is the number of times per second the
78	sound is sampled. The number of channels indicate if the audio is
79	mono, stereo, or quadro. Each frame consists of one sample per
80	channel. The sample size is the size in bytes of each sample. Thus a
81	frame consists of <var>nchannels</var>*<var>samplesize</var> bytes, and a
82	second's worth of audio consists of
83	<var>nchannels</var><var>samplesize</var><var>framerate</var> bytes.
84
85	<P>
86	For example, CD quality audio has a sample size of two bytes (16
87	bits), uses two channels (stereo) and has a frame rate of 44,100
88	frames/second. This gives a frame size of 4 bytes (2*2), and a
89	second's worth occupies 2244100 bytes (176,400 bytes).
90
91	<P>
92	Module <tt class="module">aifc</tt> defines the following function:
93
94	<P>
95	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
96	<td><nobr><b><tt id='l2h-4636' xml:id='l2h-4636' class="function">open</tt></b>(</nobr></td>
97	<td><var>file</var><big>[</big><var>, mode</var><big>]</big><var></var>)</td></tr></table></dt>
98	<dd>
99	Open an AIFF or AIFF-C file and return an object instance with
100	methods that are described below. The argument <var>file</var> is either a
101	string naming a file or a file object. <var>mode</var> must be <code>'r'</code>
102	or <code>'rb'</code> when the file must be opened for reading, or <code>'w'</code>
103	or <code>'wb'</code> when the file must be opened for writing. If omitted,
104	<code><var>file</var>.mode</code> is used if it exists, otherwise <code>'rb'</code> is
105	used. When used for writing, the file object should be seekable,
106	unless you know ahead of time how many samples you are going to write
107	in total and use <tt class="method">writeframesraw()</tt> and <tt class="method">setnframes()</tt>.
108	</dl>
109
110	<P>
111	Objects returned by <tt class="function">open()</tt> when a file is opened for
112	reading have the following methods:
113
114	<P>
115	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
116	<td><nobr><b><tt id='l2h-4637' xml:id='l2h-4637' class="method">getnchannels</tt></b>(</nobr></td>
117	<td><var></var>)</td></tr></table></dt>
118	<dd>
119	Return the number of audio channels (1 for mono, 2 for stereo).
120	</dl>
121
122	<P>
123	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
124	<td><nobr><b><tt id='l2h-4638' xml:id='l2h-4638' class="method">getsampwidth</tt></b>(</nobr></td>
125	<td><var></var>)</td></tr></table></dt>
126	<dd>
127	Return the size in bytes of individual samples.
128	</dl>
129
130	<P>
131	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
132	<td><nobr><b><tt id='l2h-4639' xml:id='l2h-4639' class="method">getframerate</tt></b>(</nobr></td>
133	<td><var></var>)</td></tr></table></dt>
134	<dd>
135	Return the sampling rate (number of audio frames per second).
136	</dl>
137
138	<P>
139	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
140	<td><nobr><b><tt id='l2h-4640' xml:id='l2h-4640' class="method">getnframes</tt></b>(</nobr></td>
141	<td><var></var>)</td></tr></table></dt>
142	<dd>
143	Return the number of audio frames in the file.
144	</dl>
145
146	<P>
147	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
148	<td><nobr><b><tt id='l2h-4641' xml:id='l2h-4641' class="method">getcomptype</tt></b>(</nobr></td>
149	<td><var></var>)</td></tr></table></dt>
150	<dd>
151	Return a four-character string describing the type of compression used
152	in the audio file. For AIFF files, the returned value is
153	<code>'NONE'</code>.
154	</dl>
155
156	<P>
157	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
158	<td><nobr><b><tt id='l2h-4642' xml:id='l2h-4642' class="method">getcompname</tt></b>(</nobr></td>
159	<td><var></var>)</td></tr></table></dt>
160	<dd>
161	Return a human-readable description of the type of compression used in
162	the audio file. For AIFF files, the returned value is <code>'not
163	compressed'</code>.
164	</dl>
165
166	<P>
167	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
168	<td><nobr><b><tt id='l2h-4643' xml:id='l2h-4643' class="method">getparams</tt></b>(</nobr></td>
169	<td><var></var>)</td></tr></table></dt>
170	<dd>
171	Return a tuple consisting of all of the above values in the above
172	order.
173	</dl>
174
175	<P>
176	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
177	<td><nobr><b><tt id='l2h-4644' xml:id='l2h-4644' class="method">getmarkers</tt></b>(</nobr></td>
178	<td><var></var>)</td></tr></table></dt>
179	<dd>
180	Return a list of markers in the audio file. A marker consists of a
181	tuple of three elements. The first is the mark ID (an integer), the
182	second is the mark position in frames from the beginning of the data
183	(an integer), the third is the name of the mark (a string).
184	</dl>
185
186	<P>
187	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
188	<td><nobr><b><tt id='l2h-4645' xml:id='l2h-4645' class="method">getmark</tt></b>(</nobr></td>
189	<td><var>id</var>)</td></tr></table></dt>
190	<dd>
191	Return the tuple as described in <tt class="method">getmarkers()</tt> for the mark
192	with the given <var>id</var>.
193	</dl>
194
195	<P>
196	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
197	<td><nobr><b><tt id='l2h-4646' xml:id='l2h-4646' class="method">readframes</tt></b>(</nobr></td>
198	<td><var>nframes</var>)</td></tr></table></dt>
199	<dd>
200	Read and return the next <var>nframes</var> frames from the audio file. The
201	returned data is a string containing for each frame the uncompressed
202	samples of all channels.
203	</dl>
204
205	<P>
206	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
207	<td><nobr><b><tt id='l2h-4647' xml:id='l2h-4647' class="method">rewind</tt></b>(</nobr></td>
208	<td><var></var>)</td></tr></table></dt>
209	<dd>
210	Rewind the read pointer. The next <tt class="method">readframes()</tt> will start from
211	the beginning.
212	</dl>
213
214	<P>
215	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
216	<td><nobr><b><tt id='l2h-4648' xml:id='l2h-4648' class="method">setpos</tt></b>(</nobr></td>
217	<td><var>pos</var>)</td></tr></table></dt>
218	<dd>
219	Seek to the specified frame number.
220	</dl>
221
222	<P>
223	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
224	<td><nobr><b><tt id='l2h-4649' xml:id='l2h-4649' class="method">tell</tt></b>(</nobr></td>
225	<td><var></var>)</td></tr></table></dt>
226	<dd>
227	Return the current frame number.
228	</dl>
229
230	<P>
231	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
232	<td><nobr><b><tt id='l2h-4650' xml:id='l2h-4650' class="method">close</tt></b>(</nobr></td>
233	<td><var></var>)</td></tr></table></dt>
234	<dd>
235	Close the AIFF file. After calling this method, the object can no
236	longer be used.
237	</dl>
238
239	<P>
240	Objects returned by <tt class="function">open()</tt> when a file is opened for
241	writing have all the above methods, except for <tt class="method">readframes()</tt> and
242	<tt class="method">setpos()</tt>. In addition the following methods exist. The
243	<tt class="method">get*()</tt> methods can only be called after the corresponding
244	<tt class="method">set*()</tt> methods have been called. Before the first
245	<tt class="method">writeframes()</tt> or <tt class="method">writeframesraw()</tt>, all parameters
246	except for the number of frames must be filled in.
247
248	<P>
249	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
250	<td><nobr><b><tt id='l2h-4651' xml:id='l2h-4651' class="method">aiff</tt></b>(</nobr></td>
251	<td><var></var>)</td></tr></table></dt>
252	<dd>
253	Create an AIFF file. The default is that an AIFF-C file is created,
254	unless the name of the file ends in <code>'.aiff'</code> in which case the
255	default is an AIFF file.
256	</dl>
257
258	<P>
259	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
260	<td><nobr><b><tt id='l2h-4652' xml:id='l2h-4652' class="method">aifc</tt></b>(</nobr></td>
261	<td><var></var>)</td></tr></table></dt>
262	<dd>
263	Create an AIFF-C file. The default is that an AIFF-C file is created,
264	unless the name of the file ends in <code>'.aiff'</code> in which case the
265	default is an AIFF file.
266	</dl>
267
268	<P>
269	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
270	<td><nobr><b><tt id='l2h-4653' xml:id='l2h-4653' class="method">setnchannels</tt></b>(</nobr></td>
271	<td><var>nchannels</var>)</td></tr></table></dt>
272	<dd>
273	Specify the number of channels in the audio file.
274	</dl>
275
276	<P>
277	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
278	<td><nobr><b><tt id='l2h-4654' xml:id='l2h-4654' class="method">setsampwidth</tt></b>(</nobr></td>
279	<td><var>width</var>)</td></tr></table></dt>
280	<dd>
281	Specify the size in bytes of audio samples.
282	</dl>
283
284	<P>
285	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
286	<td><nobr><b><tt id='l2h-4655' xml:id='l2h-4655' class="method">setframerate</tt></b>(</nobr></td>
287	<td><var>rate</var>)</td></tr></table></dt>
288	<dd>
289	Specify the sampling frequency in frames per second.
290	</dl>
291
292	<P>
293	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
294	<td><nobr><b><tt id='l2h-4656' xml:id='l2h-4656' class="method">setnframes</tt></b>(</nobr></td>
295	<td><var>nframes</var>)</td></tr></table></dt>
296	<dd>
297	Specify the number of frames that are to be written to the audio file.
298	If this parameter is not set, or not set correctly, the file needs to
299	support seeking.
300	</dl>
301
302	<P>
303	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
304	<td><nobr><b><tt id='l2h-4657' xml:id='l2h-4657' class="method">setcomptype</tt></b>(</nobr></td>
305	<td><var>type, name</var>)</td></tr></table></dt>
306	<dd>
307	Specify the compression type. If not specified, the audio data will
308	not be compressed. In AIFF files, compression is not possible. The
309	name parameter should be a human-readable description of the
310	compression type, the type parameter should be a four-character
311	string. Currently the following compression types are supported:
312	NONE, ULAW, ALAW, G722.
313	<a id='l2h-4665' xml:id='l2h-4665'></a>
314	</dl>
315
316	<P>
317	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
318	<td><nobr><b><tt id='l2h-4658' xml:id='l2h-4658' class="method">setparams</tt></b>(</nobr></td>
319	<td><var>nchannels, sampwidth, framerate, comptype, compname</var>)</td></tr></table></dt>
320	<dd>
321	Set all the above parameters at once. The argument is a tuple
322	consisting of the various parameters. This means that it is possible
323	to use the result of a <tt class="method">getparams()</tt> call as argument to
324	<tt class="method">setparams()</tt>.
325	</dl>
326
327	<P>
328	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
329	<td><nobr><b><tt id='l2h-4659' xml:id='l2h-4659' class="method">setmark</tt></b>(</nobr></td>
330	<td><var>id, pos, name</var>)</td></tr></table></dt>
331	<dd>
332	Add a mark with the given id (larger than 0), and the given name at
333	the given position. This method can be called at any time before
334	<tt class="method">close()</tt>.
335	</dl>
336
337	<P>
338	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
339	<td><nobr><b><tt id='l2h-4660' xml:id='l2h-4660' class="method">tell</tt></b>(</nobr></td>
340	<td><var></var>)</td></tr></table></dt>
341	<dd>
342	Return the current write position in the output file. Useful in
343	combination with <tt class="method">setmark()</tt>.
344	</dl>
345
346	<P>
347	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
348	<td><nobr><b><tt id='l2h-4661' xml:id='l2h-4661' class="method">writeframes</tt></b>(</nobr></td>
349	<td><var>data</var>)</td></tr></table></dt>
350	<dd>
351	Write data to the output file. This method can only be called after
352	the audio file parameters have been set.
353	</dl>
354
355	<P>
356	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
357	<td><nobr><b><tt id='l2h-4662' xml:id='l2h-4662' class="method">writeframesraw</tt></b>(</nobr></td>
358	<td><var>data</var>)</td></tr></table></dt>
359	<dd>
360	Like <tt class="method">writeframes()</tt>, except that the header of the audio file
361	is not updated.
362	</dl>
363
364	<P>
365	<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
366	<td><nobr><b><tt id='l2h-4663' xml:id='l2h-4663' class="method">close</tt></b>(</nobr></td>
367	<td><var></var>)</td></tr></table></dt>
368	<dd>
369	Close the AIFF file. The header of the file is updated to reflect the
370	actual size of the audio data. After calling this method, the object
371	can no longer be used.
372	</dl>
373
374	<DIV CLASS="navigation">
375	<div class='online-navigation'>
376	<p></p><hr />
377	<table align="center" width="100%" cellpadding="0" cellspacing="2">
378	<tr>
379	<td class='online-navigation'><a rel="prev" title="14.2 imageop "
380	href="module-imageop.html"><img src='../icons/previous.png'
381	border='0' height='32' alt='Previous Page' width='32' /></A></td>
382	<td class='online-navigation'><a rel="parent" title="14. Multimedia Services"
383	href="mmedia.html"><img src='../icons/up.png'
384	border='0' height='32' alt='Up One Level' width='32' /></A></td>
385	<td class='online-navigation'><a rel="next" title="14.4 sunau "
386	href="module-sunau.html"><img src='../icons/next.png'
387	border='0' height='32' alt='Next Page' width='32' /></A></td>
388	<td align="center" width="100%">Python Library Reference</td>
389	<td class='online-navigation'><a rel="contents" title="Table of Contents"
390	href="contents.html"><img src='../icons/contents.png'
391	border='0' height='32' alt='Contents' width='32' /></A></td>
392	<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
393	border='0' height='32' alt='Module Index' width='32' /></a></td>
394	<td class='online-navigation'><a rel="index" title="Index"
395	href="genindex.html"><img src='../icons/index.png'
396	border='0' height='32' alt='Index' width='32' /></A></td>
397	</tr></table>
398	<div class='online-navigation'>
399	<b class="navlabel">Previous:</b>
400	<a class="sectref" rel="prev" href="module-imageop.html">14.2 imageop </A>
401	<b class="navlabel">Up:</b>
402	<a class="sectref" rel="parent" href="mmedia.html">14. Multimedia Services</A>
403	<b class="navlabel">Next:</b>
404	<a class="sectref" rel="next" href="module-sunau.html">14.4 sunau </A>
405	</div>
406	</div>
407	<hr />
408	<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
409	</DIV>
410	<!--End of Navigation Panel-->
411	<ADDRESS>
412	See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
413	</ADDRESS>
414	</BODY>
415	</HTML>