mirror of
https://github.com/larsimmisch/pyalsaaudio.git
synced 2026-04-18 08:55:31 +00:00
Import from divmod. Original log message:
r1274 | casper | 2005-03-26 00:37:10 +0100 (Sat, 26 Mar 2005) | 2 lines Module documentation git-svn-id: svn://svn.code.sf.net/p/pyalsaaudio/code/trunk@9 ec2f30ec-7544-0410-870e-f70ca00c83f0
This commit is contained in:
larsimmisch
327
doc/pcm-objects.html
Normal file
327
doc/pcm-objects.html
Normal file
@@ -0,0 +1,327 @@
|
||||
<!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'>
|
||||
<META NAME="description" CONTENT="PCM Objects">
|
||||
<META NAME="keywords" CONTENT="pyalsaaudio">
|
||||
<META NAME="resource-type" CONTENT="document">
|
||||
<META NAME="distribution" CONTENT="global">
|
||||
<title>4.2 PCM Objects</title>
|
||||
</head>
|
||||
<body>
|
||||
<DIV CLASS="navigation">
|
||||
<table align="center" width="100%" cellpadding="0" cellspacing="2">
|
||||
<tr>
|
||||
<td><a rel="prev" title="4.1 PCM Terminology and"
|
||||
HREF="node7.html"><img src='previous.gif'
|
||||
border='0' height='32' alt='Previous Page' width='32'></A></td>
|
||||
<td><a rel="parent" title="4 alsaaudio"
|
||||
href="module-alsaaudio.html"><img src='up.gif'
|
||||
border='0' height='32' alt='Up One Level' width='32'></A></td>
|
||||
<td><a rel="next" title="4.3 Mixer Objects"
|
||||
href="mixer-objects.html"><img src='next.gif'
|
||||
border='0' height='32' alt='Next Page' width='32'></A></td>
|
||||
<td align="center" width="100%">PyAlsaAudio</td>
|
||||
<td><a rel="contents" title="Table of Contents"
|
||||
href="contents.html"><img src='contents.gif'
|
||||
border='0' height='32' alt='Contents' width='32'></A></td>
|
||||
<td><img src='blank.gif'
|
||||
border='0' height='32' alt='' width='32'></td>
|
||||
</tr></table>
|
||||
<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>
|
||||
<br><hr>
|
||||
</DIV>
|
||||
<!--End of Navigation Panel-->
|
||||
|
||||
<H2><A NAME="SECTION002420000000000000000"> </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> <a name="l2h-6"><tt class="class">PCM</tt></a></b>(</nobr></td>
|
||||
<td><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>)</td></tr></table>
|
||||
<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><a name="l2h-7"><tt class="method">pcmtype</tt></a></b>(</nobr></td>
|
||||
<td>)</td></tr></table>
|
||||
<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><a name="l2h-8"><tt class="method">pcmmode</tt></a></b>(</nobr></td>
|
||||
<td>)</td></tr></table>
|
||||
<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><a name="l2h-9"><tt class="method">cardname</tt></a></b>(</nobr></td>
|
||||
<td>)</td></tr></table>
|
||||
<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><a name="l2h-10"><tt class="method">setchannels</tt></a></b>(</nobr></td>
|
||||
<td><var>nchannels</var>)</td></tr></table>
|
||||
<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><a name="l2h-11"><tt class="method">setrate</tt></a></b>(</nobr></td>
|
||||
<td><var>rate</var>)</td></tr></table>
|
||||
<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><a name="l2h-12"><tt class="method">setformat</tt></a></b>(</nobr></td>
|
||||
<td>)</td></tr></table>
|
||||
<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:
|
||||
<table border align="center" style="border-collapse: collapse">
|
||||
<thead>
|
||||
<tr class="tableheader">
|
||||
<th align="left"><b>Format</b> </th>
|
||||
<th align="left"><b>Description</b> </th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody valign="baseline">
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S8</Formats></td>
|
||||
<td align="left">Signed 8 bit samples for each channel</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U8</Formats></td>
|
||||
<td align="left">Signed 8 bit samples for each channel</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S16_LE</Formats></td>
|
||||
<td align="left">Signed 16 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S16_BE</Formats></td>
|
||||
<td align="left">Signed 16 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U16_LE</Formats></td>
|
||||
<td align="left">Unsigned 16 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U16_BE</Formats></td>
|
||||
<td align="left">Unsigned 16 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S24_LE</Formats></td>
|
||||
<td align="left">Signed 24 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S24_BE</Formats></td>
|
||||
<td align="left">Signed 24 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U24_LE</Formats></td>
|
||||
<td align="left">Unsigned 24 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U24_BE</Formats></td>
|
||||
<td align="left">Unsigned 24 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S32_LE</Formats></td>
|
||||
<td align="left">Signed 32 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_S32_BE</Formats></td>
|
||||
<td align="left">Signed 32 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U32_LE</Formats></td>
|
||||
<td align="left">Unsigned 32 bit samples for each channel (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_U32_BE</Formats></td>
|
||||
<td align="left">Unsigned 32 bit samples for each channel (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT_LE</Formats></td>
|
||||
<td align="left">32 bit samples encoded as float. (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT_BE</Formats></td>
|
||||
<td align="left">32 bit samples encoded as float (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT64_LE</Formats></td>
|
||||
<td align="left">64 bit samples encoded as float. (Little Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_FLOAT64_BE</Formats></td>
|
||||
<td align="left">64 bit samples encoded as float. (Big Endian byte order)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_MU_LAW</Formats></td>
|
||||
<td align="left">A logarithmic encoding (used by Sun .au files)</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_A_LAW</Formats></td>
|
||||
<td align="left">Another logarithmic encoding</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_IMA_ADPCM</Formats></td>
|
||||
<td align="left">a 4:1 compressed format defined by the Interactive Multimedia Association</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_MPEG</Formats></td>
|
||||
<td align="left">MPEG encoded audio?</td>
|
||||
<tr><td align="left" valign="baseline"><Formats>PCM_FORMAT_GSM</Formats></td>
|
||||
<td align="left">9600 constant rate encoding well suitet for speech</td></tbody>
|
||||
</table>
|
||||
|
||||
<P>
|
||||
</dl>
|
||||
|
||||
<P>
|
||||
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
||||
<td><nobr><b><a name="l2h-13"><tt class="method">setperiodsize</tt></a></b>(</nobr></td>
|
||||
<td><var>period</var>)</td></tr></table>
|
||||
<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><a name="l2h-14"><tt class="method">read</tt></a></b>(</nobr></td>
|
||||
<td>)</td></tr></table>
|
||||
<dd>
|
||||
In PCM_NORMAL mode, this function blocks until a full period is available, and then returns a
|
||||
tuple (length,data) where <i>length</i> is the size in bytes of the captured data, and <i>data</i>
|
||||
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><a name="l2h-15"><tt class="method">write</tt></a></b>(</nobr></td>
|
||||
<td><var>data</var>)</td></tr></table>
|
||||
<dd>
|
||||
Writes (plays) the sound in data. The length of data <i>must</i> be a multiple of the frame size, and
|
||||
<i>should</i> 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>
|
||||
<b>A few hints on using PCM devices for playback</b>
|
||||
|
||||
<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 <i>exactly</i> the data rate of the device.
|
||||
|
||||
<P>
|
||||
If too little data is written to the device will an 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">
|
||||
<p><hr>
|
||||
<table align="center" width="100%" cellpadding="0" cellspacing="2">
|
||||
<tr>
|
||||
<td><a rel="prev" title="4.1 PCM Terminology and"
|
||||
rel="prev" title="4.1 PCM Terminology and"
|
||||
HREF="node7.html"><img src='previous.gif'
|
||||
border='0' height='32' alt='Previous Page' width='32'></A></td>
|
||||
<td><a rel="parent" title="4 alsaaudio"
|
||||
rel="parent" title="4 alsaaudio"
|
||||
href="module-alsaaudio.html"><img src='up.gif'
|
||||
border='0' height='32' alt='Up One Level' width='32'></A></td>
|
||||
<td><a rel="next" title="4.3 Mixer Objects"
|
||||
rel="next" title="4.3 Mixer Objects"
|
||||
href="mixer-objects.html"><img src='next.gif'
|
||||
border='0' height='32' alt='Next Page' width='32'></A></td>
|
||||
<td align="center" width="100%">PyAlsaAudio</td>
|
||||
<td><a rel="contents" title="Table of Contents"
|
||||
rel="contents" title="Table of Contents"
|
||||
href="contents.html"><img src='contents.gif'
|
||||
border='0' height='32' alt='Contents' width='32'></A></td>
|
||||
<td><img src='blank.gif'
|
||||
border='0' height='32' alt='' width='32'></td>
|
||||
</tr></table>
|
||||
<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>
|
||||
<hr>
|
||||
<span class="release-info">Release 0.1.</span>
|
||||
</DIV>
|
||||
<!--End of Navigation Panel-->
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
||||
Reference in New Issue
Block a user