forked from auracaster/pyalsaaudio
df89c12581
items. Argument parsing errors are reported with the methodname (minor improvement). Smallish documentation improvements. git-svn-id: svn://svn.code.sf.net/p/pyalsaaudio/code/trunk@23 ec2f30ec-7544-0410-870e-f70ca00c83f0
380 lines
16 KiB
HTML
380 lines
16 KiB
HTML
<!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 http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<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
|
|
(probably 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> <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 through
|
|
this API yet.
|
|
|
|
<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>format</var>)</td></tr></table></dt>
|
|
<dd>
|
|
The sound <var>format</var> 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 bits/s constant rate encoding 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 number of frames of 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.
|
|
</dl>
|
|
|
|
<p>
|
|
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
|
|
<td><nobr><b><tt id='l2h-16' xml:id='l2h-16' class="method">pause</tt></b>(</nobr></td>
|
|
<td><var></var><big>[</big><var>enable=1</var><big>]</big><var></var>)</td></tr></table></dt>
|
|
<dd>
|
|
If <var>enable</var> is 1, playback or capture is paused. If <var>enable</var> is 0,
|
|
playback/capture is resumed.
|
|
</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 APIs 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.4.</span>
|
|
</div>
|
|
<!--End of Navigation Panel-->
|
|
|
|
</body>
|
|
</html>
|