Web   ·   Wiki   ·   Activities   ·   Blog   ·   Lists   ·   Chat   ·   Meeting   ·   Bugs   ·   Git   ·   Translate   ·   Archive   ·   People   ·   Donate
summaryrefslogtreecommitdiffstats
path: root/arch_src/pyalsaaudio-0.2/doc/pcm-objects.html
diff options
context:
space:
mode:
Diffstat (limited to 'arch_src/pyalsaaudio-0.2/doc/pcm-objects.html')
-rw-r--r--arch_src/pyalsaaudio-0.2/doc/pcm-objects.html331
1 files changed, 331 insertions, 0 deletions
diff --git a/arch_src/pyalsaaudio-0.2/doc/pcm-objects.html b/arch_src/pyalsaaudio-0.2/doc/pcm-objects.html
new file mode 100644
index 0000000..3fc5d78
--- /dev/null
+++ b/arch_src/pyalsaaudio-0.2/doc/pcm-objects.html
@@ -0,0 +1,331 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<link rel="STYLESHEET" href="pyalsaaudio.css" type='text/css' />
+<link rel="first" href="pyalsaaudio.html" title='PyAlsaAudio' />
+<link rel='contents' href='contents.html' title="Contents" />
+<link rel='last' href='about.html' title='About this document...' />
+<link rel='help' href='about.html' title='About this document...' />
+<link rel="next" href="mixer-objects.html" />
+<link rel="prev" href="node7.html" />
+<link rel="parent" href="module-alsaaudio.html" />
+<link rel="next" href="mixer-objects.html" />
+<meta name='aesop' content='information' />
+<title>4.2 PCM 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="4.1 PCM Terminology and"
+ href="node7.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="4 alsaaudio"
+ href="module-alsaaudio.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="4.3 Mixer Objects"
+ href="mixer-objects.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">PyAlsaAudio</td>
+<td class='online-navigation'><a rel="contents" title="Table of Contents"
+ href="contents.html"><img src='contents.png'
+ border='0' height='32' alt='Contents' width='32' /></A></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node7.html">4.1 PCM Terminology and</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-alsaaudio.html">4 alsaaudio</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="mixer-objects.html">4.3 Mixer Objects</A>
+</div>
+<hr /></div>
+</DIV>
+<!--End of Navigation Panel-->
+
+<H2><A NAME="SECTION002420000000000000000"></A>
+<A NAME="pcm-objects"></A>
+<BR>
+4.2 PCM Objects
+</H2>
+
+<P>
+The acronym PCM is short for Pulse Code Modulation and is the method used in ALSA
+and many other places to handle playback and capture of sampled sound data.
+
+<P>
+PCM objects in <tt class="module">alsaaudio</tt> are used to do exactly that, either play sample based
+sound or capture sound from some input source (perhaps a microphone). The PCM object
+constructor takes the following arguments:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-6' xml:id='l2h-6' class="class">PCM</tt></b>(</nobr></td>
+ <td><var></var><big>[</big><var>type</var><big>]</big><var>, </var><big>[</big><var>mode</var><big>]</big><var>, </var><big>[</big><var>cardname</var><big>]</big><var></var>)</td></tr></table></dt>
+<dd>
+
+<P>
+<var>type</var> - can be either PCM_CAPTURE or PCM_PLAYBACK (default).
+
+<P>
+<var>mode</var> - can be either PCM_NONBLOCK, PCM_ASYNC, or PCM_NORMAL (the default).
+In PCM_NONBLOCK mode, calls to read will return immediately independent of wether
+there is any actual data to read. Similarly, write calls will return immediately
+without actually writing anything to the playout buffer if the buffer is full.
+
+<P>
+In the current version of <tt class="module">alsaaudio</tt> PCM_ASYNC is useless, since it relies
+on a callback procedure, which can't be specified from Python.
+
+<P>
+<var>cardname</var> - specifies which card should be used (this is only relevant
+if you have more than one sound card). Omit to use the default sound card
+
+<P>
+This will construct a PCM object with default settings:
+
+<P>
+Sample format: PCM_FORMAT_S16_LE
+<BR>
+Rate: 8000 Hz
+<BR>
+Channels: 2
+<BR>
+Period size: 32 frames
+<BR></dl>
+
+<P>
+PCM objects have the following methods:
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-7' xml:id='l2h-7' class="method">pcmtype</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Returns the type of PCM object. Either PCM_CAPTURE or PCM_PLAYBACK.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-8' xml:id='l2h-8' class="method">pcmmode</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the mode of the PCM object. One of PCM_NONBLOCK, PCM_ASYNC, or PCM_NORMAL
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-9' xml:id='l2h-9' class="method">cardname</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+Return the name of the sound card used by this PCM object.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-10' xml:id='l2h-10' class="method">setchannels</tt></b>(</nobr></td>
+ <td><var>nchannels</var>)</td></tr></table></dt>
+<dd>
+Used to set the number of capture or playback channels. Common values are: 1 = mono, 2 = stereo,
+and 6 = full 6 channel audio. Few sound cards support more than 2 channels
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-11' xml:id='l2h-11' class="method">setrate</tt></b>(</nobr></td>
+ <td><var>rate</var>)</td></tr></table></dt>
+<dd>
+Set the sample rate in Hz for the device. Typical values are 8000 (poor sound), 16000, 44100 (cd quality),
+and 96000
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-12' xml:id='l2h-12' class="method">setformat</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+The sound format of the device. Sound format controls how the PCM device interpret data for playback,
+and how data is encoded in captures.
+
+<P>
+The following formats are provided by ALSA:
+<div class="center"><table class="realtable">
+ <thead>
+ <tr>
+ <th class="left" >Format</th>
+ <th class="left" >Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S8</Formats></td>
+ <td class="left" >Signed 8 bit samples for each channel</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U8</Formats></td>
+ <td class="left" >Signed 8 bit samples for each channel</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S16_LE</Formats></td>
+ <td class="left" >Signed 16 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S16_BE</Formats></td>
+ <td class="left" >Signed 16 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U16_LE</Formats></td>
+ <td class="left" >Unsigned 16 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U16_BE</Formats></td>
+ <td class="left" >Unsigned 16 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S24_LE</Formats></td>
+ <td class="left" >Signed 24 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S24_BE</Formats></td>
+ <td class="left" >Signed 24 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U24_LE</Formats></td>
+ <td class="left" >Unsigned 24 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U24_BE</Formats></td>
+ <td class="left" >Unsigned 24 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S32_LE</Formats></td>
+ <td class="left" >Signed 32 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_S32_BE</Formats></td>
+ <td class="left" >Signed 32 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U32_LE</Formats></td>
+ <td class="left" >Unsigned 32 bit samples for each channel (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_U32_BE</Formats></td>
+ <td class="left" >Unsigned 32 bit samples for each channel (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT_LE</Formats></td>
+ <td class="left" >32 bit samples encoded as float. (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT_BE</Formats></td>
+ <td class="left" >32 bit samples encoded as float (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT64_LE</Formats></td>
+ <td class="left" >64 bit samples encoded as float. (Little Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT64_BE</Formats></td>
+ <td class="left" >64 bit samples encoded as float. (Big Endian byte order)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_MU_LAW</Formats></td>
+ <td class="left" >A logarithmic encoding (used by Sun .au files)</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_A_LAW</Formats></td>
+ <td class="left" >Another logarithmic encoding</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_IMA_ADPCM</Formats></td>
+ <td class="left" >a 4:1 compressed format defined by the Interactive Multimedia Association</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_MPEG</Formats></td>
+ <td class="left" >MPEG encoded audio?</td></tr>
+ <tr><td class="left" valign="baseline"><Formats>PCM_FORMAT_GSM</Formats></td>
+ <td class="left" >9600 constant rate encoding well suitet for speech</td></tr></tbody>
+</table></div>
+
+<P>
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-13' xml:id='l2h-13' class="method">setperiodsize</tt></b>(</nobr></td>
+ <td><var>period</var>)</td></tr></table></dt>
+<dd>
+Sets the actual period size in frames. Each write should consist of exactly this number of frames, and
+each read will return this number of frames (unless the device is in PCM_NONBLOCK mode, in which case
+it may return nothing at all)
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-14' xml:id='l2h-14' class="method">read</tt></b>(</nobr></td>
+ <td><var></var>)</td></tr></table></dt>
+<dd>
+In PCM_NORMAL mode, this function blocks until a full period is available, and then returns a
+tuple (length,data) where <em>length</em> is the size in bytes of the captured data, and <em>data</em>
+is the captured sound frames as a string. The length of the returned data will be periodsize*framesize
+bytes.
+
+<P>
+In PCM_NONBLOCK mode, the call will not block, but will return <code>(0,'')</code> if no new period
+has become available since the last call to read.
+</dl>
+
+<P>
+<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
+ <td><nobr><b><tt id='l2h-15' xml:id='l2h-15' class="method">write</tt></b>(</nobr></td>
+ <td><var>data</var>)</td></tr></table></dt>
+<dd>
+Writes (plays) the sound in data. The length of data <em>must</em> be a multiple of the frame size, and
+<em>should</em> be exactly the size of a period. If less than 'period size' frames are provided, the actual
+playout will not happen until more data is written.
+
+<P>
+If the device is not in PCM_NONBLOCK mode, this call will block if the kernel buffer is full, and
+until enough sound has been played to allow the sound data to be buffered. The call always returns
+the size of the data provided
+
+<P>
+In PCM_NONBLOCK mode, the call will return immediately, with a return value of zero, if the buffer is
+full. In this case, the data should be written at a later time.
+
+<P>
+</dl>
+
+<P>
+<strong>A few hints on using PCM devices for playback</strong>
+
+<P>
+The most common reason for problems with playback of PCM audio, is that the people don't properly understand
+that writes to PCM devices must match <em>exactly</em> the data rate of the device.
+
+<P>
+If too little data is written to the device, it will underrun, and ugly clicking sounds will occur. Conversely,
+of too much data is written to the device, the write function will either block (PCM_NORMAL mode) or return zero
+(PCM_NONBLOCK mode).
+
+<P>
+If your program does nothing, but play sound, the easiest way is to put the device in PCM_NORMAL mode, and just
+write as much data to the device as possible. This strategy can also be achieved by using a separate thread
+with the sole task of playing out sound.
+
+<P>
+In GUI programs, however, it may be a better strategy to setup the device, preload the buffer with a few
+periods by calling write a couple of times, and then use some timer method to write one period size of data to
+the device every period. The purpose of the preloading is to avoid underrun clicks if the used timer
+doesn't expire exactly on time.
+
+<P>
+Also note, that most timer API's that you can find for Python will cummulate time delays: If you set the timer
+to expire after 1/10'th of a second, the actual timeout will happen slightly later, which will accumulate to
+quite a lot after a few seconds. Hint: use time.time() to check how much time has really passed, and add
+extra writes as nessecary.
+
+<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="4.1 PCM Terminology and"
+ href="node7.html"><img src='previous.png'
+ border='0' height='32' alt='Previous Page' width='32' /></A></td>
+<td class='online-navigation'><a rel="parent" title="4 alsaaudio"
+ href="module-alsaaudio.html"><img src='up.png'
+ border='0' height='32' alt='Up One Level' width='32' /></A></td>
+<td class='online-navigation'><a rel="next" title="4.3 Mixer Objects"
+ href="mixer-objects.html"><img src='next.png'
+ border='0' height='32' alt='Next Page' width='32' /></A></td>
+<td align="center" width="100%">PyAlsaAudio</td>
+<td class='online-navigation'><a rel="contents" title="Table of Contents"
+ href="contents.html"><img src='contents.png'
+ border='0' height='32' alt='Contents' width='32' /></A></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+<td class='online-navigation'><img src='blank.png'
+ border='0' height='32' alt='' width='32' /></td>
+</tr></table>
+<div class='online-navigation'>
+<b class="navlabel">Previous:</b>
+<a class="sectref" rel="prev" href="node7.html">4.1 PCM Terminology and</A>
+<b class="navlabel">Up:</b>
+<a class="sectref" rel="parent" href="module-alsaaudio.html">4 alsaaudio</A>
+<b class="navlabel">Next:</b>
+<a class="sectref" rel="next" href="mixer-objects.html">4.3 Mixer Objects</A>
+</div>
+</div>
+<hr />
+<span class="release-info">Release 0.2.</span>
+</DIV>
+<!--End of Navigation Panel-->
+
+</BODY>
+</HTML>