Release 0.10.0

2023-04-16 00:08:27 +02:00
parent cbca6be937
commit 6b17f924e4
15 changed files with 1021 additions and 895 deletions
--- a/libalsaaudio.html
+++ b/libalsaaudio.html
@@ -1,18 +1,18 @@

 <!DOCTYPE html>

-<html>
+<html lang="en">
  <head>
    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

-    <title>alsaaudio &#8212; alsaaudio documentation 0.9.2 documentation</title>
+    <title>alsaaudio &#8212; alsaaudio documentation 0.10.0 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
-    <script src="_static/jquery.js"></script>
-    <script src="_static/underscore.js"></script>
    <script src="_static/doctools.js"></script>
+    <script src="_static/sphinx_highlight.js"></script>
+    <script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="prev" title="PCM Terminology and Concepts" href="terminology.html" />
@@ -33,7 +33,7 @@
          <div class="body" role="main">
            
  <section id="module-alsaaudio">
-<span id="alsaaudio"></span><h1><a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a><a class="headerlink" href="#module-alsaaudio" title="Permalink to this headline">¶</a></h1>
+<span id="alsaaudio"></span><h1><a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a><a class="headerlink" href="#module-alsaaudio" title="Permalink to this heading">¶</a></h1>
 <p>The <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a> module defines functions and classes for using ALSA.</p>
 <dl class="py function">
 <dt class="sig sig-object py" id="alsaaudio.pcms">
@@ -69,13 +69,15 @@ instead.</p>

 <dl class="py function">
 <dt class="sig sig-object py" id="alsaaudio.mixers">
-<span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">mixers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.mixers" title="Permalink to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">mixers</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.mixers" title="Permalink to this definition">¶</a></dt>
 <dd><p>List the available mixers. The arguments are:</p>
-<ul class="simple">
+<ul>
 <li><p><em>cardindex</em> - the card index. If this argument is given, the device name
 is constructed as: ‘hw:<em>cardindex</em>’ and
 the <cite>device</cite> keyword argument is ignored. <code class="docutils literal notranslate"><span class="pre">0</span></code> is the first hardware sound
-card.</p></li>
+card.</p>
+<p><strong>Note:</strong> This should not be used, as it bypasses most of ALSA’s configuration.</p>
+</li>
 <li><p><em>device</em> - the name of the device on which the mixer resides. The default
 is <code class="docutils literal notranslate"><span class="pre">'default'</span></code>.</p></li>
 </ul>
@@ -110,13 +112,13 @@ device, not the mixers for the first card.</p></li>
 </dd></dl>

 <section id="pcm-objects">
-<span id="id1"></span><h2>PCM Objects<a class="headerlink" href="#pcm-objects" title="Permalink to this headline">¶</a></h2>
+<span id="id1"></span><h2>PCM Objects<a class="headerlink" href="#pcm-objects" title="Permalink to this heading">¶</a></h2>
 <p>PCM objects in <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a> can play or capture (record) PCM
 sound through speakers or a microphone. The PCM constructor takes the
 following arguments:</p>
 <dl class="py class">
 <dt class="sig sig-object py" id="alsaaudio.PCM">
-<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">PCM</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_NORMAL</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rate</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">44100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channels</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_FORMAT_S16_LE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">periodsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">32</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM" title="Permalink to this definition">¶</a></dt>
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">PCM</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_NORMAL</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">rate</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">44100</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channels</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">format</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_FORMAT_S16_LE</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">periodsize</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">32</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">periods</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">4</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM" title="Permalink to this definition">¶</a></dt>
 <dd><p>This class is used to represent a PCM device (either for playback and
 recording). The arguments are:</p>
 <ul class="simple">
@@ -130,10 +132,6 @@ recording). The arguments are:</p>
 The default value is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_FORMAT_S16_LE</span></code>.</p></li>
 </ul>
 <table class="docutils align-default">
-<colgroup>
-<col style="width: 24%" />
-<col style="width: 76%" />
-</colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>Format</p></th>
 <th class="head"><p>Description</p></th>
@@ -144,7 +142,7 @@ The default value is <code class="xref py py-const docutils literal notranslate"
 <td><p>Signed 8 bit samples for each channel</p></td>
 </tr>
 <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">PCM_FORMAT_U8</span></code></p></td>
-<td><p>Signed 8 bit samples for each channel</p></td>
+<td><p>Unsigned 8 bit samples for each channel</p></td>
 </tr>
 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">PCM_FORMAT_S16_LE</span></code></p></td>
 <td><p>Signed 16 bit samples for each channel Little Endian byte order)</p></td>
@@ -223,17 +221,27 @@ The default value is <code class="xref py py-const docutils literal notranslate"
 </tr>
 </tbody>
 </table>
-<ul class="simple">
-<li><p><em>periodsize</em> - the period size in frames. Each write should consist of <em>periodsize</em> frames. The default value is 32.</p></li>
+<ul>
+<li><p><em>periodsize</em> - the period size in frames.
+Make sure you understand <a class="reference internal" href="terminology.html#term-period"><span class="std std-ref">the meaning of periods</span></a>.
+The default value is 32, which is below the actual minimum of most devices,
+and will therefore likely be larger in practice.</p></li>
+<li><p><em>periods</em> - the number of periods in the buffer. The default value is 4.</p></li>
 <li><p><em>device</em> - the name of the PCM device that should be used (for example
 a value from the output of <a class="reference internal" href="#alsaaudio.pcms" title="alsaaudio.pcms"><code class="xref py py-func docutils literal notranslate"><span class="pre">pcms()</span></code></a>). The default value is
 <code class="docutils literal notranslate"><span class="pre">'default'</span></code>.</p></li>
 <li><p><em>cardindex</em> - the card index. If this argument is given, the device name
 is constructed as ‘hw:<em>cardindex</em>’ and
 the <cite>device</cite> keyword argument is ignored.
-<code class="docutils literal notranslate"><span class="pre">0</span></code> is the first hardware sound card.</p></li>
+<code class="docutils literal notranslate"><span class="pre">0</span></code> is the first hardware sound card.</p>
+<p><strong>Note:</strong> This should not be used, as it bypasses most of ALSA’s configuration.</p>
+</li>
 </ul>
 <p>This will construct a PCM object with the given settings.</p>
+<p><em>Changed in 0.10:</em></p>
+<ul class="simple">
+<li><p>Added the optional named parameter <cite>periods</cite>.</p></li>
+</ul>
 <p><em>Changed in 0.9:</em></p>
 <ul class="simple">
 <li><p>Added the optional named parameters <cite>rate</cite>, <cite>channels</cite>, <cite>format</cite> and <cite>periodsize</cite>.</p></li>
@@ -249,6 +257,159 @@ name of the card. This was always fragile and broke some legitimate usecases.</p
 </dd></dl>

 <p>PCM objects have the following methods:</p>
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.info">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">info</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.info" title="Permalink to this definition">¶</a></dt>
+<dd><p>The info function returns a dictionary containing the configuration of a PCM device. As ALSA takes into account limitations of the hardware and software devices the configuration achieved might not correspond to the values used during creation. There is therefore a need to check the realised configuration before processing the sound coming from the device or before sending sound to a device. A small subset of parameters can be set, but cannot be queried. These parameters are stored by alsaaudio and returned as they were given by the user, to distinguish them from parameters retrieved from ALSA these parameters have a name prefixed with <strong>“ (call value) “</strong>. Yet another set of properties derives directly from the hardware and can be obtained through ALSA.</p>
+<table class="docutils align-default">
+<thead>
+<tr class="row-odd"><th class="head"><p>Key</p></th>
+<th class="head"><p>Description (Reference)</p></th>
+<th class="head"><p>Type</p></th>
+</tr>
+</thead>
+<tbody>
+<tr class="row-even"><td><p>name</p></td>
+<td><p>PCM():device</p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-odd"><td><p>card_no</p></td>
+<td><p><em>index of card</em></p></td>
+<td><p>integer  (negative indicates device not associable with a card)</p></td>
+</tr>
+<tr class="row-even"><td><p>device_no</p></td>
+<td><p><em>index of PCM device</em></p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-odd"><td><p>subdevice_no</p></td>
+<td><p><em>index of PCM subdevice</em></p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-even"><td><p>state</p></td>
+<td><p><em>name of PCM state</em></p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-odd"><td><p>access_type</p></td>
+<td><p><em>name of PCM access type</em></p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-even"><td><p>(call value) type</p></td>
+<td><p>PCM():type</p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-odd"><td><p>(call value) type_name</p></td>
+<td><p>PCM():type</p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-even"><td><p>(call value) mode</p></td>
+<td><p>PCM():mode</p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-odd"><td><p>(call value) mode_name</p></td>
+<td><p>PCM():mode</p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-even"><td><p>format</p></td>
+<td><p>PCM():format</p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-odd"><td><p>format_name</p></td>
+<td><p>PCM():format</p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-even"><td><p>format_description</p></td>
+<td><p>PCM():format</p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-odd"><td><p>subformat_name</p></td>
+<td><p><em>name of PCM subformat</em></p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-even"><td><p>subformat_description</p></td>
+<td><p><em>description of subformat</em></p></td>
+<td><p>string</p></td>
+</tr>
+<tr class="row-odd"><td><p>channels</p></td>
+<td><p>PCM():channels</p></td>
+<td><p>integer</p></td>
+</tr>
+<tr class="row-even"><td><p>rate</p></td>
+<td><p>PCM():rate</p></td>
+<td><p>integer (Hz)</p></td>
+</tr>
+<tr class="row-odd"><td><p>period_time</p></td>
+<td><p><em>period duration</em></p></td>
+<td><p>integer (<span class="math notranslate nohighlight">\(\mu s\)</span>)</p></td>
+</tr>
+<tr class="row-even"><td><p>period_size</p></td>
+<td><p>PCM():period_size</p></td>
+<td><p>integer (frames)</p></td>
+</tr>
+<tr class="row-odd"><td><p>buffer_time</p></td>
+<td><p><em>buffer time</em></p></td>
+<td><p>integer (<span class="math notranslate nohighlight">\(\mu s\)</span>) (negative indicates error)</p></td>
+</tr>
+<tr class="row-even"><td><p>buffer_size</p></td>
+<td><p><em>buffer size</em></p></td>
+<td><p>integer (frames) (negative indicates error)</p></td>
+</tr>
+<tr class="row-odd"><td><p>get_periods</p></td>
+<td><p><em>approx. periods in buffer</em></p></td>
+<td><p>integer (negative indicates error)</p></td>
+</tr>
+<tr class="row-even"><td><p>rate_numden</p></td>
+<td><p><em>numerator, denominator</em></p></td>
+<td><p>tuple (integer (Hz), integer (Hz))</p></td>
+</tr>
+<tr class="row-odd"><td><p>significant_bits</p></td>
+<td><p><em>significant bits in sample</em></p></td>
+<td><p>integer (negative indicates error)</p></td>
+</tr>
+<tr class="row-even"><td><p>is_batch</p></td>
+<td><p><em>hw: double buffering</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-odd"><td><p>is_block_transfer</p></td>
+<td><p><em>hw: block transfer</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-even"><td><p>is_double</p></td>
+<td><p><em>hw: double buffering</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-odd"><td><p>is_half_duplex</p></td>
+<td><p><em>hw: half-duplex</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-even"><td><p>is_joint_duplex</p></td>
+<td><p><em>hw: joint-duplex</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-odd"><td><p>can_overrange</p></td>
+<td><p><em>hw: overrange detection</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-even"><td><p>can_mmap_sample_resolution</p></td>
+<td><p><em>hw: sample-resol. mmap</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-odd"><td><p>can_pause</p></td>
+<td><p><em>hw: pause</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-even"><td><p>can_resume</p></td>
+<td><p><em>hw: resume</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+<tr class="row-odd"><td><p>can_sync_start</p></td>
+<td><p><em>hw: synchronized start</em></p></td>
+<td><p>boolean (True: hardware supported)</p></td>
+</tr>
+</tbody>
+</table>
+<p>The italicized descriptions give a summary of the “full” description as it can be found in the  <a class="reference external" href="https://www.alsa-project.org/alsa-doc">ALSA documentation</a>. “hw:”: indicates that the property indicated relates to the hardware. Parameters passed to the PCM object during instantation are prefixed with “PCM():”, they are described there for the keyword argument indicated after “PCM():”.</p>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.PCM.pcmtype">
 <span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">pcmtype</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.pcmtype" title="Permalink to this definition">¶</a></dt>
@@ -301,6 +462,38 @@ name of the card. This was always fragile and broke some legitimate usecases.</p
 </div>
 </dd></dl>

+<dl class="py method">
+<dt class="sig sig-object py" id="id0">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">info</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#id0" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returns a dictionary with the PCM object’s configured parameters.</p>
+<p>Values are retrieved from the ALSA library if they are available;
+otherwise they represent those stored by pyalsaaudio, and their keys
+are prefixed with ‘ (call value) ‘.</p>
+<p><em>New in 0.9.1</em></p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.dumpinfo">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">dumpinfo</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.dumpinfo" title="Permalink to this definition">¶</a></dt>
+<dd><p>Dumps the PCM object’s configured parameters to stdout.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.state">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">state</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.state" title="Permalink to this definition">¶</a></dt>
+<dd><p>Returs the current state of the stream, which can be one of
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_OPEN</span></code> (this should not actually happen),
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_SETUP</span></code> (after <a class="reference internal" href="#alsaaudio.PCM.drop" title="alsaaudio.PCM.drop"><code class="xref py py-func docutils literal notranslate"><span class="pre">drop()</span></code></a> or <a class="reference internal" href="#alsaaudio.PCM.drain" title="alsaaudio.PCM.drain"><code class="xref py py-func docutils literal notranslate"><span class="pre">drain()</span></code></a>),
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_PREPARED</span></code> (after construction),
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_RUNNING</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_XRUN</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_DRAINING</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_PAUSED</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_SUSPENDED</span></code>, and
+<code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_STATE_DISCONNECTED</span></code>.</p>
+<p><em>New in 0.10</em></p>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.PCM.read">
 <span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.read" title="Permalink to this definition">¶</a></dt>
@@ -331,6 +524,9 @@ size of the data provided.</p>
 <p>In <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_NONBLOCK</span></code> 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>
+<p>Note that this call completing means only that the samples were buffered
+in the kernel, and playout will continue afterwards. Make sure that the
+stream is drained before discarding the PCM handle.</p>
 </dd></dl>

 <dl class="py method">
@@ -340,12 +536,37 @@ should be written at a later time.</p>
 Otherwise, playback/capture is resumed.</p>
 </dd></dl>

+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.drop">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">drop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.drop" title="Permalink to this definition">¶</a></dt>
+<dd><p>Stop the stream and drop residual buffered frames.</p>
+<p><em>New in 0.9</em></p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.drain">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">drain</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.drain" title="Permalink to this definition">¶</a></dt>
+<dd><p>For <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code> PCM objects, play residual buffered frames
+and then stop the stream. In <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_NORMAL</span></code> mode,
+this function blocks until all pending playback is drained.</p>
+<p>For <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code> PCM objects, this function is not very useful.</p>
+<p><em>New in 0.10</em></p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.PCM.close">
+<span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.close" title="Permalink to this definition">¶</a></dt>
+<dd><p>Closes the PCM device.</p>
+<p>For <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code> PCM objects in <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_NORMAL</span></code> mode,
+this function blocks until all pending playback is drained.</p>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.PCM.polldescriptors">
 <span class="sig-prename descclassname"><span class="pre">PCM.</span></span><span class="sig-name descname"><span class="pre">polldescriptors</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.PCM.polldescriptors" title="Permalink to this definition">¶</a></dt>
-<dd><p>Returns a tuple of <em>(file descriptor, eventmask)</em> that can be used to
-wait for changes on the PCM with <em>select.poll</em>.</p>
-<p>The <em>eventmask</em> value is compatible with <a class="reference external" href="http://docs.python.org/library/select.html#poll-objects">poll.register</a> in the Python
+<dd><p>Returns a list of tuples of <em>(file descriptor, eventmask)</em> that can be
+used to wait for changes on the PCM with <em>select.poll</em>.</p>
+<p>The <em>eventmask</em> value is compatible with <a href="#id3"><span class="problematic" id="id4">`poll.register`__</span></a> in the Python
 <code class="xref py py-const docutils literal notranslate"><span class="pre">select</span></code> module.</p>
 </dd></dl>

@@ -385,10 +606,6 @@ return value can be either <code class="xref py py-const docutils literal notran
 <dd><p>Return a Python tuple <em>(seconds, nanoseconds, frames_available_in_buffer)</em>.</p>
 <p>The type of output is controlled by the tstamp_type, as described in the table below.</p>
 <table class="docutils align-default">
-<colgroup>
-<col style="width: 43%" />
-<col style="width: 57%" />
-</colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>Timestamp Type</p></th>
 <th class="head"><p>Description</p></th>
@@ -411,10 +628,6 @@ time using only the system clock.</p></td>
 </table>
 <p>The timestamp mode is controlled by the tstamp_mode, as described in the table below.</p>
 <table class="docutils align-default">
-<colgroup>
-<col style="width: 43%" />
-<col style="width: 57%" />
-</colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>Timestamp Mode</p></th>
 <th class="head"><p>Description</p></th>
@@ -455,11 +668,11 @@ 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>
 </section>
 <section id="mixer-objects">
-<span id="id3"></span><h2>Mixer Objects<a class="headerlink" href="#mixer-objects" title="Permalink to this headline">¶</a></h2>
+<span id="id2"></span><h2>Mixer Objects<a class="headerlink" href="#mixer-objects" title="Permalink to this heading">¶</a></h2>
 <p>Mixer objects provides access to the ALSA mixer API.</p>
 <dl class="py class">
 <dt class="sig sig-object py" id="alsaaudio.Mixer">
-<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">Mixer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">control</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'Master'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-</span> <span class="pre">1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer" title="Permalink to this definition">¶</a></dt>
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">alsaaudio.</span></span><span class="sig-name descname"><span class="pre">Mixer</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">control</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'Master'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">id</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">cardindex</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">device</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'default'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer" title="Permalink to this definition">¶</a></dt>
 <dd><p>Arguments are:</p>
 <ul class="simple">
 <li><p><em>control</em> - specifies which control to manipulate using this mixer
@@ -508,10 +721,6 @@ devices.</p></li>
 <dd><p>Returns a list of the switches which are defined by this specific mixer.
 Possible values in this list are:</p>
 <table class="docutils align-default">
-<colgroup>
-<col style="width: 31%" />
-<col style="width: 69%" />
-</colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>Switch</p></th>
 <th class="head"><p>Description</p></th>
@@ -551,10 +760,6 @@ Possible values in this list are:</p>
 <dd><p>Returns a list of the volume control capabilities of this
 mixer. Possible values in the list are:</p>
 <table class="docutils align-default">
-<colgroup>
-<col style="width: 28%" />
-<col style="width: 72%" />
-</colgroup>
 <thead>
 <tr class="row-odd"><th class="head"><p>Capability</p></th>
 <th class="head"><p>Description</p></th>
@@ -610,47 +815,45 @@ control.</p>
 </dd></dl>

 <dl class="py method">
-<dt class="sig sig-object py" id="alsaaudio.Mixer.getmute">
-<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getmute</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getmute" title="Permalink to this definition">¶</a></dt>
-<dd><p>Return a list indicating the current mute setting for each
-channel. 0 means not muted, 1 means muted.</p>
-<p>This method will fail if the mixer has no playback switch capabilities.</p>
+<dt class="sig sig-object py" id="alsaaudio.Mixer.setenum">
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">setenum</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">index</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.setenum" title="Permalink to this definition">¶</a></dt>
+<dd><p>For enumerated controls, sets the currently selected item.
+<em>index</em> is an index into the list of available enumerated items returned
+by <a class="reference internal" href="#alsaaudio.Mixer.getenum" title="alsaaudio.Mixer.getenum"><code class="xref py py-func docutils literal notranslate"><span class="pre">getenum()</span></code></a>.</p>
 </dd></dl>

 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.getrange">
-<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getrange</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getrange" title="Permalink to this definition">¶</a></dt>
-<dd><p>Return the volume range of the ALSA mixer controlled by this object.</p>
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getrange</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">units</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">VOLUME_UNITS_RAW</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getrange" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return the volume range of the ALSA mixer controlled by this object.
+The value is a tuple of integers whose meaning is determined by the
+<em>units</em> argument.</p>
 <p>The optional <em>pcmtype</em> argument can be either <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code> or
 <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>, which is relevant if the mixer can control both
 playback and capture volume.  The default value is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code>
 if the mixer has playback channels, otherwise it is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>.</p>
-</dd></dl>
-
-<dl class="py method">
-<dt class="sig sig-object py" id="alsaaudio.Mixer.getrec">
-<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getrec</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getrec" title="Permalink to this definition">¶</a></dt>
-<dd><p>Return a list indicating the current record mute setting for each channel. 0
-means not recording, 1 means recording.</p>
-<p>This method will fail if the mixer has no capture switch capabilities.</p>
+<p>The optional <em>units</em> argument can be one of <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_PERCENTAGE</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_RAW</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_DB</span></code>.</p>
 </dd></dl>

 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.getvolume">
-<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getvolume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getvolume" title="Permalink to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getvolume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">units</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">VOLUME_UNITS_PERCENTAGE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getvolume" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns a list with the current volume settings for each channel. The list
-elements are integer percentages.</p>
+elements are integers whose meaning is determined by the <em>units</em> argument.</p>
 <p>The optional <em>pcmtype</em> argument can be either <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code> or
 <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>, which is relevant if the mixer can control both
 playback and capture volume. The default value is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code>
 if the mixer has playback channels, otherwise it is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>.</p>
+<p>The optional <em>units</em> argument can be one of <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_PERCENTAGE</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_RAW</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_DB</span></code>.</p>
 </dd></dl>

 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.setvolume">
-<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">setvolume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">volume</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.setvolume" title="Permalink to this definition">¶</a></dt>
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">setvolume</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">volume</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pcmtype</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">PCM_PLAYBACK</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">units</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">VOLUME_UNITS_PERCENTAGE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.setvolume" title="Permalink to this definition">¶</a></dt>
 <dd><p>Change the current volume settings for this mixer. The <em>volume</em> argument
-controls the new volume setting as an integer percentage.</p>
+is an integer whose meaning is determined by the <em>units</em> argument.</p>
 <p>If the optional argument <em>channel</em> is present, the volume is set
 only for this channel. This assumes that the mixer can control the
 volume for the channels independently.</p>
@@ -658,6 +861,16 @@ volume for the channels independently.</p>
 <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>, which is relevant if the mixer can control both
 playback and capture volume. The default value is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_PLAYBACK</span></code>
 if the mixer has playback channels, otherwise it is <code class="xref py py-const docutils literal notranslate"><span class="pre">PCM_CAPTURE</span></code>.</p>
+<p>The optional <em>units</em> argument can be one of <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_PERCENTAGE</span></code>,
+<code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_RAW</span></code>, or <code class="xref py py-const docutils literal notranslate"><span class="pre">VOLUME_UNITS_DB</span></code>.</p>
+</dd></dl>
+
+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.Mixer.getmute">
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getmute</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getmute" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return a list indicating the current mute setting for each channel.
+0 means not muted, 1 means muted.</p>
+<p>This method will fail if the mixer has no playback switch capabilities.</p>
 </dd></dl>

 <dl class="py method">
@@ -670,6 +883,14 @@ muted. The default is to set the mute flag for all channels.</p>
 <p>This method will fail if the mixer has no playback mute capabilities</p>
 </dd></dl>

+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.Mixer.getrec">
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">getrec</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.getrec" title="Permalink to this definition">¶</a></dt>
+<dd><p>Return a list indicating the current record mute setting for each channel.
+0 means not recording, 1 means recording.</p>
+<p>This method will fail if the mixer has no capture switch capabilities.</p>
+</dd></dl>
+
 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.setrec">
 <span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">setrec</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">capture</span></span></em><span class="optional">[</span>, <em class="sig-param"><span class="n"><span class="pre">channel</span></span></em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.setrec" title="Permalink to this definition">¶</a></dt>
@@ -683,20 +904,26 @@ changed. The default is to set the capture flag for all channels.</p>
 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.polldescriptors">
 <span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">polldescriptors</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.polldescriptors" title="Permalink to this definition">¶</a></dt>
-<dd><p>Returns a tuple of <em>(file descriptor, eventmask)</em> that can be used to
-wait for changes on the mixer with <em>select.poll</em>.</p>
-<p>The <em>eventmask</em> value is compatible with <a class="reference external" href="http://docs.python.org/library/select.html#poll-objects">poll.register</a> in the Python
+<dd><p>Returns a list of tuples of <em>(file descriptor, eventmask)</em> that can be
+used to wait for changes on the mixer with <em>select.poll</em>.</p>
+<p>The <em>eventmask</em> value is compatible with <a href="#id3"><span class="problematic" id="id5">`poll.register`__</span></a> in the Python
 <code class="xref py py-const docutils literal notranslate"><span class="pre">select</span></code> module.</p>
 </dd></dl>

 <dl class="py method">
 <dt class="sig sig-object py" id="alsaaudio.Mixer.handleevents">
 <span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">handleevents</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.handleevents" title="Permalink to this definition">¶</a></dt>
-<dd><p>Acknowledge events on the <em>polldescriptors</em> file descriptors
+<dd><p>Acknowledge events on the <a class="reference internal" href="#alsaaudio.Mixer.polldescriptors" title="alsaaudio.Mixer.polldescriptors"><code class="xref py py-func docutils literal notranslate"><span class="pre">polldescriptors()</span></code></a> file descriptors
 to prevent subsequent polls from returning the same events again.
 Returns the number of events that were acknowledged.</p>
 </dd></dl>

+<dl class="py method">
+<dt class="sig sig-object py" id="alsaaudio.Mixer.close">
+<span class="sig-prename descclassname"><span class="pre">Mixer.</span></span><span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#alsaaudio.Mixer.close" title="Permalink to this definition">¶</a></dt>
+<dd><p>Closes the Mixer device.</p>
+</dd></dl>
+
 <p><strong>A rant on the ALSA Mixer API</strong></p>
 <p>The ALSA mixer API is extremely complicated - and hardly documented at all.
 <a class="reference internal" href="#module-alsaaudio" title="alsaaudio (Linux)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a> implements a much simplified way to access this API. In
@@ -716,7 +943,7 @@ understand half of the API, and that which I do understand has come from a
 painful trial and error process.</p>
 </section>
 <section id="examples">
-<span id="pcm-example"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
+<span id="pcm-example"></span><h2>Examples<a class="headerlink" href="#examples" title="Permalink to this heading">¶</a></h2>
 <p>The following example are provided:</p>
 <ul class="simple">
 <li><p><cite>playwav.py</cite></p></li>
@@ -740,7 +967,7 @@ painful trial and error process.</p>
 <p>mixertest.py accepts the commandline options <em>-d &lt;device&gt;</em> and
 <em>-c &lt;cardindex&gt;</em>.</p>
 <section id="playwav-py">
-<h3>playwav.py<a class="headerlink" href="#playwav-py" title="Permalink to this headline">¶</a></h3>
+<h3>playwav.py<a class="headerlink" href="#playwav-py" title="Permalink to this heading">¶</a></h3>
 <p><strong>playwav.py</strong> plays a wav file.</p>
 <p>To test PCM playback (on your default soundcard), run:</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python playwav.py &lt;wav file&gt;
@@ -748,7 +975,7 @@ painful trial and error process.</p>
 </div>
 </section>
 <section id="recordtest-py-and-playbacktest-py">
-<h3>recordtest.py and playbacktest.py<a class="headerlink" href="#recordtest-py-and-playbacktest-py" title="Permalink to this headline">¶</a></h3>
+<h3>recordtest.py and playbacktest.py<a class="headerlink" href="#recordtest-py-and-playbacktest-py" title="Permalink to this heading">¶</a></h3>
 <p><strong>recordtest.py</strong> and <strong>playbacktest.py</strong> will record and play a raw
 sound file in CD quality.</p>
 <p>To test PCM recordings (on your default soundcard), run:</p>
@@ -763,7 +990,7 @@ with <code class="docutils literal notranslate"><span class="pre">Ctl-C</span></
 </div>
 </section>
 <section id="mixertest-py">
-<h3>mixertest.py<a class="headerlink" href="#mixertest-py" title="Permalink to this headline">¶</a></h3>
+<h3>mixertest.py<a class="headerlink" href="#mixertest-py" title="Permalink to this heading">¶</a></h3>
 <p>Without arguments, <strong>mixertest.py</strong> will list all available <em>controls</em> on the
 default soundcard.</p>
 <p>The output might look like this:</p>
@@ -814,12 +1041,6 @@ Channel 0 volume: 61%
 Channel 1 volume: 61%
 </pre></div>
 </div>
-<p class="rubric">Footnotes</p>
-<dl class="footnote brackets">
-<dt class="label" id="f1"><span class="brackets">1</span></dt>
-<dd><p>ALSA also allows <code class="docutils literal notranslate"><span class="pre">PCM_ASYNC</span></code>, but this is not supported yet.</p>
-</dd>
-</dl>
 </section>
 </section>
 </section>
@@ -849,6 +1070,10 @@ Channel 1 volume: 61%
 <li class="toctree-l1"><a class="reference internal" href="pyalsaaudio.html#testing">Testing</a></li>
 <li class="toctree-l1"><a class="reference internal" href="terminology.html">PCM Terminology and Concepts</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">alsaaudio</span></code></a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#alsaaudio.pcms"><code class="docutils literal notranslate"><span class="pre">pcms()</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#alsaaudio.cards"><code class="docutils literal notranslate"><span class="pre">cards()</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#alsaaudio.mixers"><code class="docutils literal notranslate"><span class="pre">mixers()</span></code></a></li>
+<li class="toctree-l2"><a class="reference internal" href="#alsaaudio.asoundlib_version"><code class="docutils literal notranslate"><span class="pre">asoundlib_version()</span></code></a></li>
 <li class="toctree-l2"><a class="reference internal" href="#pcm-objects">PCM Objects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#mixer-objects">Mixer Objects</a></li>
 <li class="toctree-l2"><a class="reference internal" href="#examples">Examples</a></li>
@@ -873,7 +1098,7 @@ Channel 1 volume: 61%
    </form>
    </div>
 </div>
-<script>$('#searchbox').show(0);</script>
+<script>document.getElementById('searchbox').style.display = "block"</script>



@@ -890,8 +1115,8 @@ Channel 1 volume: 61%
      &copy;2017, Lars Immisch & Casper Wilstrup.
      
      |
-      Powered by <a href="http://sphinx-doc.org/">Sphinx 4.5.0</a>
-      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
+      Powered by <a href="http://sphinx-doc.org/">Sphinx 6.1.3</a>
+      &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.13</a>
      
      |
      <a href="_sources/libalsaaudio.rst.txt"