Add echo (seed for loopback.py)

we *really* should not paper over underruns, as they require attention.
however, the previous attempt (c2a6b6e) caused an exception to be thrown
(see #130), which was a bit excessive, and was consequently reverted
(438e52e).

so instead we make the handling consistent with what we do in read():
return the verbatim -EPIPE in this case. this can be simply ignored, and
the next write will resume the stream, so this is mostly backwards-
compatible (the failing write will be discarded and would need
repeating, but that will just cause a skip after the interruption,
which does not seem particularly relevant).

as a drive-by, again stop using snd_pcm_recover(), as it still just
obfuscates the snd_pcm_prepare() call it does in the end.

CHANGES.md

@@ -1,3 +1,8 @@
+# Version 0.10.1
+- revert to not throwing an exception on playback buffer underrun;
+  instead, return -EPIPE like `PCM.read()` does on overrun; #131
+- type hints
+
 # Version 0.10.0
 - assorted improvements (#123 from @ossilator)
   - support for `periods` in the `PCM` constructor.

MANIFEST.in

@@ -1,4 +1,5 @@
 include *.py
+include alsaaudio.pyi
 include CHANGES
 include TODO
 include LICENSE

alsaaudio.c

@@ -196,8 +196,8 @@ get_pcmtype(PyObject *obj)
 static bool is_value_volume_unit(long unit)
 {
 	if (unit == VOLUME_UNITS_PERCENTAGE ||
-	    unit == VOLUME_UNITS_RAW ||
-	    unit == VOLUME_UNITS_DB) {
+		unit == VOLUME_UNITS_RAW ||
+		unit == VOLUME_UNITS_DB) {
 		return true;
 	}
 	return false;
@@ -1364,12 +1364,23 @@ alsapcm_read(alsapcm_t *self, PyObject *args)
 	buffer = PyBytes_AS_STRING(buffer_obj);
 #endif
 
+	// After drop() and drain(), we need to prepare the stream again.
+	// Note that fresh streams are already prepared by snd_pcm_hw_params().
 	state = snd_pcm_state(self->handle);
-	if ((state != SND_PCM_STATE_XRUN && state != SND_PCM_STATE_SETUP) ||
-		(res = snd_pcm_prepare(self->handle)) >= 0) {
+	if ((state != SND_PCM_STATE_SETUP) ||
+		!(res = snd_pcm_prepare(self->handle))) {
+
 		Py_BEGIN_ALLOW_THREADS
 		res = snd_pcm_readi(self->handle, buffer, self->periodsize);
 		Py_END_ALLOW_THREADS
+
+		if (res == -EPIPE) {
+			// This means buffer overrun, which we need to report.
+			// However, we recover the stream, so the next PCM.read() will work
+			// again. If recovery fails (very unlikely), report that instead.
+			if (!(res = snd_pcm_prepare(self->handle)))
+				res = -EPIPE;
+		}
 	}
 
 	if (res != -EPIPE)
@@ -1385,10 +1396,10 @@ alsapcm_read(alsapcm_t *self, PyObject *args)
 			Py_DECREF(buffer_obj);
 			return NULL;
 		}
-	}
-
-	if (res > 0 ) {
-		sizeout = res * self->framesize;
+		else
+		{
+			sizeout = res * self->framesize;
+		}
 	}
 
 	if (size != sizeout) {
@@ -1423,11 +1434,8 @@ alsapcm_read(alsapcm_t *self, PyObject *args)
 
 static PyObject *alsapcm_write(alsapcm_t *self, PyObject *args)
 {
-	snd_pcm_state_t state;
-	int res;
 	int datalen;
 	char *data;
-	PyObject *rc = NULL;
 
 #if PY_MAJOR_VERSION < 3
 	if (!PyArg_ParseTuple(args,"s#:write", &data, &datalen))
@@ -1445,6 +1453,11 @@ static PyObject *alsapcm_write(alsapcm_t *self, PyObject *args)
 	if (!self->handle)
 	{
 		PyErr_SetString(ALSAAudioError, "PCM device is closed");
+
+#if PY_MAJOR_VERSION >= 3
+		PyBuffer_Release(&buf);
+#endif
+
 		return NULL;
 	}
 
@@ -1452,34 +1465,80 @@ static PyObject *alsapcm_write(alsapcm_t *self, PyObject *args)
 	{
 		PyErr_SetString(ALSAAudioError,
 						"Data size must be a multiple of framesize");
+
+#if PY_MAJOR_VERSION >= 3
+		PyBuffer_Release(&buf);
+#endif
 		return NULL;
 	}
 
-	state = snd_pcm_state(self->handle);
-	if ((state != SND_PCM_STATE_XRUN && state != SND_PCM_STATE_SETUP) ||
-		(res = snd_pcm_prepare(self->handle)) >= 0) {
+	int res;
+	// After drop() and drain(), we need to prepare the stream again.
+	// Note that fresh streams are already prepared by snd_pcm_hw_params().
+	snd_pcm_state_t state = snd_pcm_state(self->handle);
+	if ((state != SND_PCM_STATE_SETUP) ||
+		!(res = snd_pcm_prepare(self->handle))) {
+
 		Py_BEGIN_ALLOW_THREADS
 		res = snd_pcm_writei(self->handle, data, datalen/self->framesize);
 		Py_END_ALLOW_THREADS
+
+		if (res == -EPIPE) {
+			// This means buffer underrun, which we need to report.
+			// However, we recover the stream, so the next PCM.write() will work
+			// again. If recovery fails (very unlikely), report that instead.
+			if (!(res = snd_pcm_prepare(self->handle)))
+				res = -EPIPE;
+		}
 	}
 
-	if (res == -EAGAIN) {
-		rc = PyLong_FromLong(0);
-	}
-	else if (res < 0)
+	if (res != -EPIPE)
 	{
-		PyErr_Format(ALSAAudioError, "%s [%s]", snd_strerror(res),
-					 self->cardname);
-	}
-	else {
-		rc = PyLong_FromLong(res);
+		if (res == -EAGAIN)
+		{
+			res = 0;
+		}
+		else if (res < 0) {
+			PyErr_Format(ALSAAudioError, "%s [%s]", snd_strerror(res),
+						 self->cardname);
+
+#if PY_MAJOR_VERSION >= 3
+			PyBuffer_Release(&buf);
+#endif
+
+			return NULL;
+		}
 	}
 
 #if PY_MAJOR_VERSION >= 3
 	PyBuffer_Release(&buf);
 #endif
 
-	return rc;
+	return PyLong_FromLong(res);
+}
+
+static PyObject *
+alsapcm_avail(alsapcm_t *self, PyObject *args)
+{
+	if (!PyArg_ParseTuple(args,":avail"))
+		return NULL;
+
+	if (!self->handle)
+	{
+		PyErr_SetString(ALSAAudioError, "PCM device is closed");
+		return NULL;
+	}
+
+	long avail = snd_pcm_avail(self->handle);
+	// if (avail < 0)
+	// {
+	// 	PyErr_Format(ALSAAudioError, "%s [%s]", snd_strerror(avail),
+	// 				 self->cardname);
+
+	// 	return NULL;
+	// }
+
+	return PyLong_FromLong(avail);
 }
 
 static PyObject *alsapcm_pause(alsapcm_t *self, PyObject *args)
@@ -1603,6 +1662,72 @@ alsapcm_polldescriptors(alsapcm_t *self, PyObject *args)
 	return result;
 }
 
+static PyObject *
+alsapcm_polldescriptors_revents(alsapcm_t *self, PyObject *args)
+{
+	PyObject *list_obj;
+
+	if (!PyArg_ParseTuple(args, "O!:polldescriptors_revents", &PyList_Type, &list_obj))
+	{
+		PyErr_SetString(PyExc_TypeError, "parameter must be a list.");
+		return NULL;
+	}
+
+	Py_ssize_t list_size = PyList_Size(list_obj);
+
+	struct pollfd *fds = (struct pollfd*)calloc(list_size, sizeof(struct pollfd));
+	if (!fds)
+	{
+		PyErr_Format(PyExc_MemoryError, "Out of memory [%s]",
+					 self->cardname);
+		return NULL;
+	}
+
+	for (int i = 0; i < list_size; i++)
+	{
+		PyObject *tuple_obj = PyList_GetItem(list_obj, i);
+		if(!PyTuple_Check(tuple_obj)) {
+			PyErr_SetString(PyExc_TypeError, "list items must be tuples.");
+			free(fds);
+			return NULL;
+		}
+
+		Py_ssize_t tuple_size = PyTuple_Size(tuple_obj);
+		if (tuple_size != 2) {
+			PyErr_SetString(PyExc_TypeError, "tuples inside list must be (fd: int, mask: int)");
+			free(fds);
+			return NULL;
+		}
+
+		PyObject* t0 = PyTuple_GetItem(tuple_obj, 0);
+		PyObject* t1 = PyTuple_GetItem(tuple_obj, 1);
+
+		if (!PyLong_Check(t0) || !PyLong_Check(t1)) {
+			PyErr_SetString(PyExc_TypeError, "tuples inside list must be (fd: int, mask: int)");
+			free(fds);
+			return NULL;
+		}
+
+		// leave fds[i].event as 0 (from calloc) for now
+		fds[i].fd = PyLong_AS_LONG(t0);
+		fds[i].revents = PyLong_AS_LONG(t1);
+	}
+
+	unsigned short revents;
+	int rc = snd_pcm_poll_descriptors_revents(self->handle, fds, (unsigned short)list_size, &revents);
+	if (rc < 0)
+	{
+		PyErr_Format(ALSAAudioError, "%s [%s]", snd_strerror(rc),
+					 self->cardname);
+		free(fds);
+		return NULL;
+	}
+
+	free(fds);
+
+	return PyLong_FromLong(revents);
+}
+
 /* ALSA PCM Object Bureaucracy */
 
 static PyMethodDef alsapcm_methods[] = {
@@ -1627,11 +1752,13 @@ static PyMethodDef alsapcm_methods[] = {
 	{"getchannels", (PyCFunction)alsapcm_getchannels, METH_VARARGS},
 	{"read", (PyCFunction)alsapcm_read, METH_VARARGS},
 	{"write", (PyCFunction)alsapcm_write, METH_VARARGS},
+	{"avail", (PyCFunction)alsapcm_avail, METH_VARARGS},
 	{"pause", (PyCFunction)alsapcm_pause, METH_VARARGS},
 	{"drop", (PyCFunction)alsapcm_drop, METH_VARARGS},
 	{"drain", (PyCFunction)alsapcm_drain, METH_VARARGS},
 	{"close", (PyCFunction)alsapcm_close, METH_VARARGS},
 	{"polldescriptors", (PyCFunction)alsapcm_polldescriptors, METH_VARARGS},
+	{"polldescriptors_revents", (PyCFunction)alsapcm_polldescriptors_revents, METH_VARARGS},
 	{NULL, NULL}
 };
 
@@ -2157,13 +2284,10 @@ alsamixer_getvolume(alsamixer_t *self, PyObject *args, PyObject *kwds)
 {
 	snd_mixer_elem_t *elem;
 	int channel;
-	long ival;
 	PyObject *pcmtypeobj = NULL;
 	long pcmtype;
 	int iunits = VOLUME_UNITS_PERCENTAGE;
-	PyObject *result;
-	PyObject *item;
-
+	PyObject *result = NULL;
 	char *kw[] = { "pcmtype", "units", NULL };
 
 	if (!PyArg_ParseTupleAndKeywords(args, kwds, "|Oi:getvolume", kw, &pcmtypeobj, &iunits)) {
@@ -2187,6 +2311,9 @@ alsamixer_getvolume(alsamixer_t *self, PyObject *args, PyObject *kwds)
 	}
 	volume_units_t units = iunits;
 
+	// handle updates that may have occurred
+	snd_mixer_handle_events(self->handle);
+
 	elem = alsamixer_find_elem(self->handle,self->controlname,self->controlid);
 
 	if (!pcmtypeobj || (pcmtypeobj == Py_None)) {
@@ -2201,6 +2328,8 @@ alsamixer_getvolume(alsamixer_t *self, PyObject *args, PyObject *kwds)
 	result = PyList_New(0);
 
 	for (channel = 0; channel <= SND_MIXER_SCHN_LAST; channel++) {
+		long ival;
+
 		if (pcmtype == SND_PCM_STREAM_PLAYBACK &&
 			snd_mixer_selem_has_playback_channel(elem, channel))
 		{
@@ -2218,7 +2347,7 @@ alsamixer_getvolume(alsamixer_t *self, PyObject *args, PyObject *kwds)
 				break;
 			}
 
-			item = PyLong_FromLong(ival);
+			PyObject* item = PyLong_FromLong(ival);
 			PyList_Append(result, item);
 			Py_DECREF(item);
 		}
@@ -2239,7 +2368,7 @@ alsamixer_getvolume(alsamixer_t *self, PyObject *args, PyObject *kwds)
 				break;
 			}
 
-			item = PyLong_FromLong(ival);
+			PyObject* item = PyLong_FromLong(ival);
 			PyList_Append(result, item);
 			Py_DECREF(item);
 		}

alsaaudio.pyi

@@ -0,0 +1,128 @@
+from typing import list
+
+PCM_PLAYBACK: int
+PCM_CAPTURE: int
+
+PCM_NORMAL: int
+PCM_NONBLOCK: int
+PCM_ASYNC: int
+
+PCM_FORMAT_S8: int
+PCM_FORMAT_U8: int
+PCM_FORMAT_S16_LE: int
+PCM_FORMAT_S16_BE: int
+PCM_FORMAT_U16_LE: int
+PCM_FORMAT_U16_BE: int
+PCM_FORMAT_S24_LE: int
+PCM_FORMAT_S24_BE: int
+PCM_FORMAT_U24_LE: int
+PCM_FORMAT_U24_BE: int
+PCM_FORMAT_S32_LE: int
+PCM_FORMAT_S32_BE: int
+PCM_FORMAT_U32_LE: int
+PCM_FORMAT_U32_BE: int
+PCM_FORMAT_FLOAT_LE: int
+PCM_FORMAT_FLOAT_BE: int
+PCM_FORMAT_FLOAT64_LE: int
+PCM_FORMAT_FLOAT64_BE: int
+PCM_FORMAT_MU_LAW: int
+PCM_FORMAT_A_LAW: int
+PCM_FORMAT_IMA_ADPCM: int
+PCM_FORMAT_MPEG: int
+PCM_FORMAT_GSM: int
+PCM_FORMAT_S24_3LE: int
+PCM_FORMAT_S24_3BE: int
+PCM_FORMAT_U24_3LE: int
+PCM_FORMAT_U24_3BE: int
+
+PCM_TSTAMP_NONE: int
+PCM_TSTAMP_ENABLE: int
+
+PCM_TSTAMP_TYPE_GETTIMEOFDAY: int
+PCM_TSTAMP_TYPE_MONOTONIC: int
+PCM_TSTAMP_TYPE_MONOTONIC_RAW: int
+
+PCM_FORMAT_DSD_U8: int
+PCM_FORMAT_DSD_U16_LE: int
+PCM_FORMAT_DSD_U32_LE: int
+PCM_FORMAT_DSD_U32_BE: int
+
+PCM_STATE_OPEN: int
+PCM_STATE_SETUP: int
+PCM_STATE_PREPARED: int
+PCM_STATE_RUNNING: int
+PCM_STATE_XRUN: int
+PCM_STATE_DRAINING: int
+PCM_STATE_PAUSED: int
+PCM_STATE_SUSPENDED: int
+PCM_STATE_DISCONNECTED: int
+
+MIXER_CHANNEL_ALL: int
+
+MIXER_SCHN_UNKNOWN: int
+MIXER_SCHN_FRONT_LEFT: int
+MIXER_SCHN_FRONT_RIGHT: int
+MIXER_SCHN_REAR_LEFT: int
+MIXER_SCHN_REAR_RIGHT: int
+MIXER_SCHN_FRONT_CENTER: int
+MIXER_SCHN_WOOFER: int
+MIXER_SCHN_SIDE_LEFT: int
+MIXER_SCHN_SIDE_RIGHT: int
+MIXER_SCHN_REAR_CENTER: int
+MIXER_SCHN_MONO: int
+
+VOLUME_UNITS_PERCENTAGE: int
+VOLUME_UNITS_RAW: int
+VOLUME_UNITS_DB: int
+
+def pcms(pcmtype:int) -> list[str]: ...
+def cards() -> list[str]: ...
+def mixers(cardindex:int=-1, device:str='default') -> list[str]: ...
+def asoundlib_version() -> str: ...
+
+class PCM:
+	def __init__(type:int=PCM_PLAYBACK, mode:int=PCM_NORMAL, rate:int=44100, channels:int=2,
+		format:int=PCM_FORMAT_S16_LE, periodsize:int=32, periods:int=4,
+		device:str='default', cardindex:int=-1) -> PCM: ...
+	def info() -> dict: ...
+	def pcmtype() -> int: ...
+	def pcmmode() -> int: ...
+	def cardname() -> str: ...
+	def setchannels(nchannels: int) -> None: ...
+	def setrate(rate: int) -> None: ...
+	def setformat(format: int) -> int: ...
+	def setperiodsize(period: int) -> int: ...
+	def dumpinfo() -> None: ...
+	def state() -> int: ...
+	def read() -> tuple[int, bytes]: ...
+	def write(data:bytes) -> int: ...
+	def pause(enable:bool=True) -> int: ...
+	def drop() -> int: ...
+	def drain() -> int: ...
+	def polldescriptors() -> list[tuple[int, int]]: ...
+	def set_tstamp_mode(mode:int=PCM_TSTAMP_ENABLE) -> None: ...
+	def get_tstamp_mode() -> int: ...
+	def set_tstamp_type(type:int=PCM_TSTAMP_TYPE_GETTIMEOFDAY) -> None: ...
+	def get_tstamp_type() -> int: ...
+	def htimestamp() -> tuple[int, int, int]: ...
+
+class Mixer:
+	def __init__(control:str='Master', id:int=0, cardindex:int=-1, device:str='default') -> Mixer: ...
+	def cardname() -> str: ...
+	def mixer() -> str: ...
+	def mixerid() -> int: ...
+	def switchcap() -> int: ...
+	def volumecap() -> int: ...
+	def getenum() -> tuple[ str, list[str]]: ...
+	def setenum(index:int) -> None: ...
+	def getrange(pcmtype:int=PCM_PLAYBACK, units:int=VOLUME_UNITS_RAW) -> tuple[int, int]: ...
+	def getvolume(pcmtype:int=PCM_PLAYBACK, units:int=VOLUME_UNITS_PERCENTAGE) -> int: ...
+	def setvolume(volume:int, pcmtype:int=PCM_PLAYBACK, units:int=VOLUME_UNITS_PERCENTAGE, channel:int|None=None) -> None: ...
+	def getmute() -> list[int]: ...
+	def setmute(mute:bool, channel:int|None=None) -> None: ...
+	def getrec() -> list[int]: ...
+	def setrec(capture:int, channel:int|None=None) -> None: ...
+	def polldescriptors() -> list[tuple[int, int]]: ...
+	def close() -> None: ...
+
+

doc/libalsaaudio.rst

@@ -10,14 +10,14 @@
 
 The :mod:`alsaaudio` module defines functions and classes for using ALSA.
 
-.. function:: pcms(pcmtype=PCM_PLAYBACK)
+.. function:: pcms(pcmtype:int=PCM_PLAYBACK) ->list[str]
 
    List available PCM devices by name.
 
    Arguments are:
 
    * *pcmtype* - can be either :const:`PCM_CAPTURE` or :const:`PCM_PLAYBACK`
-     (default).  
+     (default).
 
    **Note:**
 
@@ -34,7 +34,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
 
    *New in 0.8*
 
-.. function:: cards()
+.. function:: cards() -> list[str]
 
    List the available ALSA cards by name. This function is only moderately
    useful. If you want to see a list of available PCM devices, use :func:`pcms`
@@ -96,18 +96,18 @@ PCM objects in :mod:`alsaaudio` can play or capture (record) PCM
 sound through speakers or a microphone. The PCM constructor takes the
 following arguments:
 
-.. class:: PCM(type=PCM_PLAYBACK, mode=PCM_NORMAL, rate=44100, channels=2, format=PCM_FORMAT_S16_LE, periodsize=32, periods=4, device='default', cardindex=-1)
+.. class:: PCM(type=PCM_PLAYBACK, mode=PCM_NORMAL, rate=44100, channels=2, format=PCM_FORMAT_S16_LE, periodsize=32, periods=4, device='default', cardindex=-1) -> PCM
 
    This class is used to represent a PCM device (either for playback and
    recording). The arguments are:
 
    * *type* - can be either :const:`PCM_CAPTURE` or :const:`PCM_PLAYBACK`
-     (default).  
+     (default).
    * *mode* - can be either :const:`PCM_NONBLOCK`, or :const:`PCM_NORMAL`
-     (default). 
+     (default).
    * *rate* - the sampling rate in Hz. Typical values are ``8000`` (mainly used for telephony), ``16000``, ``44100`` (default), ``48000`` and ``96000``.
    * *channels* - the number of channels. The default value is 2 (stereo).
-   * *format* - the data format. This controls how the PCM device interprets data for playback, and how data is encoded in captures. 
+   * *format* - the data format. This controls how the PCM device interprets data for playback, and how data is encoded in captures.
      The default value is :const:`PCM_FORMAT_S16_LE`.
 
    =========================  ===============
@@ -179,24 +179,24 @@ following arguments:
 
 PCM objects have the following methods:
 
-.. method:: PCM.info()
+.. method:: PCM.info() -> dict
 
    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 **" (call value) "**. Yet another set of properties derives directly from the hardware and can be obtained through ALSA.
-   
+
    ===========================  =============================  ==================================================================
-        Key                      Description (Reference)            Type       
+        Key                      Description (Reference)            Type
    ===========================  =============================  ==================================================================
    name                         PCM():device                      string
    card_no                      *index of card*                   integer  (negative indicates device not associable with a card)
-   device_no                    *index of PCM device*             integer 
-   subdevice_no                 *index of PCM subdevice*          integer 
+   device_no                    *index of PCM device*             integer
+   subdevice_no                 *index of PCM subdevice*          integer
    state                        *name of PCM state*               string
    access_type                  *name of PCM access type*         string
    (call value) type            PCM():type                        integer
    (call value) type_name       PCM():type                        string
    (call value) mode            PCM():mode                        integer
    (call value) mode_name       PCM():mode                        string
-   format                       PCM():format                      integer 
+   format                       PCM():format                      integer
    format_name                  PCM():format                      string
    format_description           PCM():format                      string
    subformat_name               *name of PCM subformat*           string
@@ -219,13 +219,13 @@ PCM objects have the following methods:
    can_mmap_sample_resolution   *hw: sample-resol. mmap*          boolean (True: hardware supported)
    can_pause                    *hw: pause*                       boolean (True: hardware supported)
    can_resume                   *hw: resume*                      boolean (True: hardware supported)
-   can_sync_start               *hw: synchronized start*          boolean (True: hardware supported) 
+   can_sync_start               *hw: synchronized start*          boolean (True: hardware supported)
    ===========================  =============================  ==================================================================
 
    The italicized descriptions give a summary of the "full" description as it can be found in the  `ALSA documentation <https://www.alsa-project.org/alsa-doc>`_. "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():".
 
 
-.. method:: PCM.pcmtype()
+.. method:: PCM.pcmtype() -> int
 
    Returns the type of PCM object. Either :const:`PCM_CAPTURE` or
    :const:`PCM_PLAYBACK`.
@@ -267,37 +267,29 @@ PCM objects have the following methods:
    Returns a dictionary of supported format codes (integers) keyed by
    their standard ALSA names (strings).
 
-.. method:: PCM.setchannels(nchannels)
+.. method:: PCM.setchannels(nchannels: int) -> int
 
    .. deprecated:: 0.9 Use the `channels` named argument to :func:`PCM`.
 
-.. method:: PCM.setrate(rate)
+.. method:: PCM.setrate(rate: int) -> int
 
    .. deprecated:: 0.9 Use the `rate` named argument to :func:`PCM`.
 
-.. method:: PCM.setformat(format)
+.. method:: PCM.setformat(format: int) -> int
 
    .. deprecated:: 0.9 Use the `format` named argument to :func:`PCM`.
 
-.. method:: PCM.setperiodsize(period)
+.. method:: PCM.setperiodsize(period: int) -> int
 
    .. deprecated:: 0.9 Use the `periodsize` named argument to :func:`PCM`.
 
-.. method:: PCM.info()
-
-   Returns a dictionary with the PCM object's configured parameters.
-
-   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) '.
-
    *New in 0.9.1*
 
-.. method:: PCM.dumpinfo()
+.. method:: PCM.dumpinfo() -> None
 
    Dumps the PCM object's configured parameters to stdout.
 
-.. method:: PCM.state()
+.. method:: PCM.state() -> int
 
    Returs the current state of the stream, which can be one of
    :const:`PCM_STATE_OPEN` (this should not actually happen),
@@ -312,54 +304,66 @@ PCM objects have the following methods:
 
    *New in 0.10*
 
-.. method:: PCM.read()
+.. method:: PCM.read() -> tuple[int, bytes]
 
    In :const:`PCM_NORMAL` mode, this function blocks until a full period is
    available, and then returns a tuple (length,data) where *length* is
    the number of frames of captured data, and *data* is the captured
-   sound frames as a string. The length of the returned data will be 
+   sound frames as a string. The length of the returned data will be
    periodsize\*framesize bytes.
 
    In :const:`PCM_NONBLOCK` mode, the call will not block, but will return
    ``(0,'')`` if no new period has become available since the last
    call to read.
 
-   In case of an overrun, this function will return a negative size: :const:`-EPIPE`.
-   This indicates that data was lost, even if the operation itself succeeded.
-   Try using a larger periodsize.
+   In case of a buffer overrun, this function will return the negative
+   size :const:`-EPIPE`, and no data is read.
+   This indicates that data was lost. To resume capturing, just call read
+   again, but note that the stream was already corrupted.
+   To avoid the problem in the future, try using a larger period size
+   and/or more periods, at the cost of higher latency.
 
-.. method:: PCM.write(data)
+.. method:: PCM.write(data: bytes) -> int
 
    Writes (plays) the sound in data. The length of data *must* be a
    multiple of the frame size, and *should* 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.
 
-   If the device is not in :const:`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.
+   If the data was successfully written, the call returns the size of the
+   data *in frames*.
+
+   If the device is not in :const:`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.
 
    In :const:`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.
+   should be written again at a later time.
+
+   In case of a buffer underrun, this function will return the negative
+   size :const:`-EPIPE`, and no data is written.
+   At this point, the playback was already corrupted. If you want to play
+   the data nonetheless, call write again with the same data.
+   To avoid the problem in the future, try using a larger period size
+   and/or more periods, at the cost of higher latency.
 
    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.
 
-.. method:: PCM.pause([enable=True])
+.. method:: PCM.pause([enable=True]) -> int
 
    If *enable* is :const:`True`, playback or capture is paused.
    Otherwise, playback/capture is resumed.
 
-.. method:: PCM.drop()
+.. method:: PCM.drop() -> int
 
    Stop the stream and drop residual buffered frames.
 
    *New in 0.9*
 
-.. method:: PCM.drain()
+.. method:: PCM.drain() -> int
 
    For :const:`PCM_PLAYBACK` PCM objects, play residual buffered frames
    and then stop the stream. In :const:`PCM_NORMAL` mode,
@@ -369,44 +373,37 @@ PCM objects have the following methods:
 
    *New in 0.10*
 
-.. method:: PCM.close()
-
-   Closes the PCM device.
-
-   For :const:`PCM_PLAYBACK` PCM objects in :const:`PCM_NORMAL` mode,
-   this function blocks until all pending playback is drained.
-
-.. method:: PCM.polldescriptors()
+.. method:: PCM.polldescriptors() -> list[tuple[int, int]]
 
    Returns a list of tuples of *(file descriptor, eventmask)* that can be
    used to wait for changes on the PCM with *select.poll*.
 
-   The *eventmask* value is compatible with `poll.register`__ in the Python 
+   The *eventmask* value is compatible with `poll.register`__ in the Python
    :const:`select` module.
 
-.. method:: PCM.set_tstamp_mode([mode=PCM_TSTAMP_ENABLE])
+.. method:: PCM.set_tstamp_mode([mode=PCM_TSTAMP_ENABLE]) -> None
 
    Set the ALSA timestamp mode on the device. The mode argument can be set to
    either :const:`PCM_TSTAMP_NONE` or :const:`PCM_TSTAMP_ENABLE`.
 
-.. method:: PCM.get_tstamp_mode()
+.. method:: PCM.get_tstamp_mode() -> int
 
    Return the integer value corresponding to the ALSA timestamp mode. The
    return value can be either :const:`PCM_TSTAMP_NONE` or :const:`PCM_TSTAMP_ENABLE`.
 
-.. method:: PCM.set_tstamp_type([type=PCM_TSTAMP_TYPE_GETTIMEOFDAY])
+.. method:: PCM.set_tstamp_type([type=PCM_TSTAMP_TYPE_GETTIMEOFDAY]) -> None
 
    Set the ALSA timestamp mode on the device. The type argument
    can be set to either :const:`PCM_TSTAMP_TYPE_GETTIMEOFDAY`,
    :const:`PCM_TSTAMP_TYPE_MONOTONIC` or :const:`PCM_TSTAMP_TYPE_MONOTONIC_RAW`.
 
-.. method:: PCM.get_tstamp_type()
+.. method:: PCM.get_tstamp_type() -> int
 
    Return the integer value corresponding to the ALSA timestamp type. The
    return value can be either :const:`PCM_TSTAMP_TYPE_GETTIMEOFDAY`,
    :const:`PCM_TSTAMP_TYPE_MONOTONIC` or :const:`PCM_TSTAMP_TYPE_MONOTONIC_RAW`.
 
-.. method:: PCM.htimestamp()
+.. method:: PCM.htimestamp() -> tuple[int, int, int]
 
    Return a Python tuple *(seconds, nanoseconds, frames_available_in_buffer)*.
 
@@ -433,9 +430,16 @@ PCM objects have the following methods:
                                       update.
    =================================  ===========================================
 
+.. method:: PCM.close() -> None
+
+   Closes the PCM device.
+
+   For :const:`PCM_PLAYBACK` PCM objects in :const:`PCM_NORMAL` mode,
+   this function blocks until all pending playback is drained.
+
 **A few hints on using PCM devices for playback**
 
-The most common reason for problems with playback of PCM audio is that writes 
+The most common reason for problems with playback of PCM audio is that writes
 to PCM devices must *exactly* match the data rate of the device.
 
 If too little data is written to the device, it will underrun, and
@@ -468,12 +472,12 @@ Mixer Objects
 
 Mixer objects provides access to the ALSA mixer API.
 
-.. class:: Mixer(control='Master', id=0, cardindex=-1, device='default')
+.. class:: Mixer(control='Master', id=0, cardindex=-1, device='default') -> Mixer
 
    Arguments are:
 
    * *control* - specifies which control to manipulate using this mixer
-     object. The list of available controls can be found with the 
+     object. The list of available controls can be found with the
      :mod:`alsaaudio`.\ :func:`mixers` function.  The default value is
      ``'Master'`` - other common controls may be ``'Master Mono'``, ``'PCM'``,
      ``'Line'``, etc.
@@ -483,7 +487,7 @@ Mixer objects provides access to the ALSA mixer API.
    * *cardindex* - specifies which card should be used. If this argument
      is given, the device name is constructed like this: 'hw:*cardindex*' and
      the `device` keyword argument is ignored. ``0`` is the
-     first sound card. 
+     first sound card.
 
    * *device* - the name of the device on which the mixer resides. The default
      value is ``'default'``.
@@ -495,20 +499,20 @@ Mixer objects provides access to the ALSA mixer API.
 
 Mixer objects have the following methods:
 
-.. method:: Mixer.cardname()
+.. method:: Mixer.cardname() -> str
 
    Return the name of the sound card used by this Mixer object
 
-.. method:: Mixer.mixer()
+.. method:: Mixer.mixer() -> str
 
    Return the name of the specific mixer controlled by this object, For example
    ``'Master'`` or ``'PCM'``
 
-.. method:: Mixer.mixerid()
+.. method:: Mixer.mixerid() -> int
 
    Return the ID of the ALSA mixer controlled by this object.
 
-.. method:: Mixer.switchcap()
+.. method:: Mixer.switchcap() -> int
 
    Returns a list of the switches which are defined by this specific mixer.
    Possible values in this list are:
@@ -520,7 +524,7 @@ Mixer objects have the following methods:
    'Joined Mute'           This mixer can mute all channels at the same time
    'Playback Mute'         This mixer can mute the playback output
    'Joined Playback Mute'  Mute playback for all channels at the same time}
-   'Capture Mute'          Mute sound capture 
+   'Capture Mute'          Mute sound capture
    'Joined Capture Mute'   Mute sound capture for all channels at a time}
    'Capture Exclusive'     Not quite sure what this is
    ======================  ================
@@ -528,7 +532,7 @@ Mixer objects have the following methods:
    To manipulate these switches use the :meth:`setrec` or
    :meth:`setmute` methods
 
-.. method:: Mixer.volumecap()
+.. method:: Mixer.volumecap() -> int
 
    Returns a list of the volume control capabilities of this
    mixer. Possible values in the list are:
@@ -544,7 +548,7 @@ Mixer objects have the following methods:
    'Joined Capture Volume'   Manipulate sound capture volume for all channels at a time
    ========================  ================
 
-.. method:: Mixer.getenum()
+.. method:: Mixer.getenum() -> tuple[ str, list[str]]
 
    For enumerated controls, return the currently selected item and  the list of
    items available.
@@ -570,13 +574,13 @@ Mixer objects have the following methods:
    This method will return an empty tuple if the mixer is not an  enumerated
    control.
 
-.. method:: Mixer.setenum(index)
+.. method:: Mixer.setenum(index:int) -> None
 
    For enumerated controls, sets the currently selected item.
    *index* is an index into the list of available enumerated items returned
    by :func:`getenum`.
 
-.. method:: Mixer.getrange(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_RAW)
+.. method:: Mixer.getrange(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_RAW) -> tuple[int, int]
 
    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
@@ -590,7 +594,7 @@ Mixer objects have the following methods:
    The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`,
    :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`.
 
-.. method:: Mixer.getvolume(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE)
+.. method:: Mixer.getvolume(pcmtype:int=PCM_PLAYBACK, units:int=VOLUME_UNITS_PERCENTAGE) -> int
 
    Returns a list with the current volume settings for each channel. The list
    elements are integers whose meaning is determined by the *units* argument.
@@ -603,7 +607,7 @@ Mixer objects have the following methods:
    The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`,
    :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`.
 
-.. method:: Mixer.setvolume(volume, channel=None, pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE)
+.. method:: Mixer.setvolume(volume:int, pcmtype:int=PCM_PLAYBACK, units:int=VOLUME_UNITS_PERCENTAGE, channel:int|None) -> None
 
    Change the current volume settings for this mixer. The *volume* argument
    is an integer whose meaning is determined by the *units* argument.
@@ -620,14 +624,14 @@ Mixer objects have the following methods:
    The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`,
    :const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`.
 
-.. method:: Mixer.getmute()
+.. method:: Mixer.getmute() -> list[int]
 
    Return a list indicating the current mute setting for each channel.
    0 means not muted, 1 means muted.
 
    This method will fail if the mixer has no playback switch capabilities.
 
-.. method:: Mixer.setmute(mute, [channel])
+.. method:: Mixer.setmute(mute:bool, channel:int|None=None) -> None
 
    Sets the mute flag to a new value. The *mute* argument is either 0 for not
    muted, or 1 for muted.
@@ -637,14 +641,14 @@ Mixer objects have the following methods:
 
    This method will fail if the mixer has no playback mute capabilities
 
-.. method:: Mixer.getrec()
+.. method:: Mixer.getrec() -> list[int]
 
    Return a list indicating the current record mute setting for each channel.
    0 means not recording, 1 means recording.
 
    This method will fail if the mixer has no capture switch capabilities.
 
-.. method:: Mixer.setrec(capture, [channel])
+.. method:: Mixer.setrec(capture:int, channel:int|None=None) -> None
 
    Sets the capture mute flag to a new value. The *capture* argument
    is either 0 for no capture, or 1 for capture.
@@ -654,21 +658,21 @@ Mixer objects have the following methods:
 
    This method will fail if the mixer has no capture switch capabilities.
 
-.. method:: Mixer.polldescriptors()
+.. method:: Mixer.polldescriptors() -> list[tuple[int, int]]
 
    Returns a list of tuples of *(file descriptor, eventmask)* that can be
    used to wait for changes on the mixer with *select.poll*.
 
-   The *eventmask* value is compatible with `poll.register`__ in the Python 
+   The *eventmask* value is compatible with `poll.register`__ in the Python
    :const:`select` module.
 
-.. method:: Mixer.handleevents()
+.. method:: Mixer.handleevents() -> int
 
    Acknowledge events on the :func:`polldescriptors` file descriptors
    to prevent subsequent polls from returning the same events again.
    Returns the number of events that were acknowledged.
 
-.. method:: Mixer.close()
+.. method:: Mixer.close() -> None
 
    Closes the Mixer device.
 
@@ -707,7 +711,7 @@ The following example are provided:
 * `playbacktest.py`
 * `mixertest.py`
 
-All examples (except `mixertest.py`) accept the commandline option 
+All examples (except `mixertest.py`) accept the commandline option
 *-c <cardname>*.
 
 To determine a valid card name, use the commandline ALSA player::
@@ -722,12 +726,12 @@ or::
    >>> alsaaudio.pcms()
 
 mixertest.py accepts the commandline options *-d <device>* and
-*-c <cardindex>*. 
+*-c <cardindex>*.
 
 playwav.py
 ~~~~~~~~~~
 
-**playwav.py** plays a wav file. 
+**playwav.py** plays a wav file.
 
 To test PCM playback (on your default soundcard), run::
 
@@ -775,7 +779,7 @@ The output might look like this::
      'Mix'
      'Mix Mono'
 
-With a single argument - the *control*, it will display the settings of 
+With a single argument - the *control*, it will display the settings of
 that control; for example::
 
   $ ./mixertest.py Master
@@ -784,7 +788,7 @@ that control; for example::
   Channel 0 volume: 61%
   Channel 1 volume: 61%
 
-With two arguments, the *control* and a *parameter*, it will set the 
+With two arguments, the *control* and a *parameter*, it will set the
 parameter on the mixer::
 
   $ ./mixertest.py Master mute

echo.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+# -*- mode: python; indent-tabs-mode: t; c-basic-offset: 4; tab-width: 4 -*-
+
+import alsaaudio
+import select
+
+def echo(inpcm, outpcm):
+	q = list()
+
+	# setup the synchronous event loop
+	# See https://docs.python.org/3/library/select.html#poll-objects for background
+	reactor = select.poll()
+
+	infd, inmask = inpcm.polldecriptors()
+	outfd, outmask = outpcm.polldescriptors()
+
+	write_started = False
+
+	def write():
+		data = q.pop()
+		written = outpcm.write(data)
+		if written < len(data):
+			q.insert(0, data[written:])
+
+	reactor.register(infd, inmask)
+	reactor.register(outfd, outmask)
+
+	while True:
+		events = reactor.poll()
+		for fd, event in events:
+			if event == select.POLLIN and fd == infd:
+				data = inpcm.read()
+				q.append(data)
+				if not write_started:
+					write()
+					write_started = True
+			elif event == select.POLLOUT and fd == outfd:
+				if not q:
+					return
+				write()

loopback.py

@@ -0,0 +1,397 @@
+#!/usr/bin/env python3
+# -*- mode: python; indent-tabs-mode: t; c-basic-offset: 4; tab-width: 4 -*-
+
+import sys
+import select
+import logging
+import re
+import struct
+import subprocess
+from datetime import datetime, timedelta
+from alsaaudio import (PCM, pcms, PCM_PLAYBACK, PCM_CAPTURE, PCM_NONBLOCK, Mixer,
+	PCM_STATE_OPEN, PCM_STATE_SETUP, PCM_STATE_PREPARED, PCM_STATE_RUNNING, PCM_STATE_XRUN, PCM_STATE_DRAINING,
+	PCM_STATE_PAUSED, PCM_STATE_SUSPENDED, ALSAAudioError)
+from argparse import ArgumentParser
+
+poll_names = {
+	select.POLLIN: 'POLLIN',
+	select.POLLPRI: 'POLLPRI',
+	select.POLLOUT: 'POLLOUT',
+	select.POLLERR: 'POLLERR',
+	select.POLLHUP: 'POLLHUP',
+	select.POLLRDHUP: 'POLLRDHUP',
+	select.POLLNVAL: 'POLLNVAL'
+}
+
+state_names = {
+	PCM_STATE_OPEN: 'PCM_STATE_OPEN',
+	PCM_STATE_SETUP: 'PCM_STATE_SETUP',
+	PCM_STATE_PREPARED: 'PCM_STATE_PREPARED',
+	PCM_STATE_RUNNING: 'PCM_STATE_RUNNING',
+	PCM_STATE_XRUN: 'PCM_STATE_XRUN',
+	PCM_STATE_DRAINING: 'PCM_STATE_DRAINING',
+	PCM_STATE_PAUSED: 'PCM_STATE_PAUSED',
+	PCM_STATE_SUSPENDED: 'PCM_STATE_SUSPENDED'
+}
+
+def poll_desc(mask):
+	return '|'.join([poll_names[bit] for bit, name in poll_names.items() if mask & bit])
+
+class PollDescriptor(object):
+	'''File Descriptor, event mask and a name for logging'''
+	def __init__(self, name, fd, mask):
+		self.name = name
+		self.fd = fd
+		self.mask = mask
+
+	def as_tuple(self):
+		return (self.fd, self.mask)
+
+	@classmethod
+	def from_alsa_object(cls, name, alsaobject, mask=None):
+		# TODO maybe refactor: we ignore objects that have more then one polldescriptor
+		fd, alsamask = alsaobject.polldescriptors()[0]
+
+		if mask is None:
+			mask = alsamask
+
+		return cls(name, fd, mask)
+
+class Loopback(object):
+	'''Loopback state and event handling'''
+
+	def __init__(self, capture, playback_args, volume_handler, run_after_stop=None, run_before_start=None):
+		self.playback_args = playback_args
+		self.playback = None
+		self.volume_handler = volume_handler
+		self.capture_started = None
+		self.last_capture_event = None
+
+		self.capture = capture
+		self.capture_pd = PollDescriptor.from_alsa_object('capture', capture)
+
+		self.run_after_stop = run_after_stop.split(' ')
+		self.run_before_start = run_before_start.split(' ')
+		self.run_after_stop_did_run = False
+
+		self.waitBeforeOpen = False
+		self.queue = []
+
+		self.period_size = 0
+		self.silent_periods = 0
+
+	@staticmethod
+	def compute_energy(data):
+		values = struct.unpack(f'{len(data)//2}h', data)
+		e = 0
+		for v in values:
+			e = e + v * v
+
+		return e
+
+	@staticmethod
+	def run_command(cmd):
+		if cmd:
+			rc = subprocess.run(cmd)
+			if rc.returncode:
+				logging.warning(f'run {cmd}, return code {rc.returncode}')
+			else:
+				logging.info(f'run {cmd}, return code {rc.returncode}')
+
+	def register(self, reactor):
+		reactor.register_timeout_handler(self.timeout_handler)
+		reactor.register(self.capture_pd, self)
+
+	def start(self):
+		# start reading data
+		size, data = self.capture.read()
+		if size:
+			self.queue.append(data)
+
+	def timeout_handler(self):
+		if self.playback and self.capture_started:
+			if self.last_capture_event:
+				if datetime.now() - self.last_capture_event > timedelta(seconds=2):
+					logging.info('timeout - closing playback device')
+					self.playback.close()
+					self.playback = None
+					self.capture_started = None
+					if self.volume_handler:
+						self.volume_handler.stop()
+					self.run_command(self.run_after_stop)
+			return
+
+		self.waitBeforeOpen = False
+
+		if not self.run_after_stop_did_run and not self.playback:
+			if self.volume_handler:
+				self.volume_handler.stop()
+			self.run_command(self.run_after_stop)
+			self.run_after_stop_did_run = True
+
+	def pop(self):
+		if len(self.queue):
+			return self.queue.pop()
+		else:
+			return None
+
+	def handle_capture_event(self, eventmask, name):
+		'''called when data is available for reading'''
+		self.last_capture_event = datetime.now()
+		size, data = self.capture.read()
+		if not size:
+			logging.warning(f'capture event but no data')
+			return False
+
+		energy = self.compute_energy(data)
+		logging.debug(f'energy: {energy}')
+
+		# the usecase is a USB capture device where we get perfect silence when it's idle
+		if energy == 0:
+			self.silent_periods = self.silent_periods + 1
+
+			# turn off playback after two seconds of silence
+			# 2 channels * 2 seconds * 2 bytes per sample
+			fps = self.playback_args['rate']  * 8 // (self.playback_args['periodsize'] * self.playback_args['periods'])
+
+			logging.debug(f'{self.silent_periods} of {fps} silent periods: {self.playback}')
+
+			if self.silent_periods > fps and self.playback:
+				logging.info(f'closing playback due to silence')
+				self.playback.close()
+				self.playback = None
+				if self.volume_handler:
+					self.volume_handler.stop()
+				self.run_command(self.run_after_stop)
+				self.run_after_stop_did_run = True
+
+			if not self.playback:
+				return
+		else:
+			self.silent_periods = 0
+
+		if not self.playback:
+			if self.waitBeforeOpen:
+				return False
+			try:
+				if self.volume_handler:
+					self.volume_handler.start()
+				self.run_command(self.run_before_start)
+				self.playback = PCM(**self.playback_args)
+				self.period_size = self.playback.info()['period_size']
+				logging.info(f'opened playback device with period_size {self.period_size}')
+			except ALSAAudioError as e:
+				logging.info('opening PCM playback device failed: %s', e)
+				self.waitBeforeOpen = True
+				return False
+
+			self.capture_started = datetime.now()
+			logging.info(f'{self.playback} capture started: {self.capture_started}')
+
+		self.queue.append(data)
+
+		if len(self.queue) <= 2:
+			logging.info(f'buffering: {len(self.queue)}')
+			return False
+
+		try:
+			data = self.pop()
+			if data:
+				space = self.playback.avail()
+				written = self.playback.write(data)
+				logging.debug(f'wrote {written} bytes while space was {space}')
+		except ALSAAudioError:
+			logging.error('underrun', exc_info=1)
+
+		return True
+
+	def __call__(self, fd, eventmask, name):
+
+		if fd == self.capture_pd.fd:
+			real_mask = self.capture.polldescriptors_revents([self.capture_pd.as_tuple()])
+			if real_mask:
+				return self.handle_capture_event(real_mask, name)
+			else:
+				logging.debug('null capture event')
+				return False
+		else:
+			real_mask = self.playback.polldescriptors_revents([self.playback_pd.as_tuple()])
+			if real_mask:
+				return self.handle_playback_event(real_mask, name)
+			else:
+				logging.debug('null playback event')
+				return False
+
+class VolumeForwarder(object):
+	'''Volume control event handling'''
+
+	def __init__(self, capture_control, playback_control):
+		self.playback_control = playback_control
+		self.capture_control = capture_control
+		self.active = True
+
+	def start(self):
+		self.active = True
+		if self.volume:
+			self.volume = playback_control.setvolume(self.volume)
+
+	def stop(self):
+		self.active = False
+		self.volume = self.playback_control.getvolume(pcmtype=PCM_CAPTURE)[0]
+
+	def __call__(self, fd, eventmask, name):
+		if not self.active:
+			return
+
+		volume = self.capture_control.getvolume(pcmtype=PCM_CAPTURE)
+		# indicate that we've handled the event
+		self.capture_control.handleevents()
+		logging.info(f'{name} adjusting volume to {volume}')
+		if volume:
+			self.playback_control.setvolume(volume[0])
+
+
+class Reactor(object):
+	'''A wrapper around select.poll'''
+
+	def __init__(self):
+		self.poll = select.poll()
+		self.descriptors = {}
+		self.timeout_handlers = set()
+
+	def register(self, polldescriptor, callable):
+		logging.debug(f'registered {polldescriptor.name}: {poll_desc(polldescriptor.mask)}')
+		self.descriptors[polldescriptor.fd] = (polldescriptor, callable)
+		self.poll.register(polldescriptor.fd, polldescriptor.mask)
+
+	def unregister(self, polldescriptor):
+		self.poll.unregister(polldescriptor.fd)
+		del self.descriptors[polldescriptor.fd]
+
+	def register_timeout_handler(self, callable):
+		self.timeout_handlers.add(callable)
+
+	def unregister_timeout_handler(self, callable):
+		self.timeout_handlers.remove(callable)
+
+	def run(self):
+		last_timeout_ev = datetime.now()
+		while True:
+			# poll for a bit, then send a timeout to registered handlers
+			events = self.poll.poll(0.25)
+			for fd, ev in events:
+				polldescriptor, handler = self.descriptors[fd]
+
+				# very chatty - log all events
+				# logging.debug(f'{polldescriptor.name}: {poll_desc(ev)} ({ev})')
+
+				handler(fd, ev, polldescriptor.name)
+
+			if datetime.now() - last_timeout_ev > timedelta(seconds=0.25):
+				for t in self.timeout_handlers:
+					t()
+				last_timeout_ev = datetime.now()
+
+
+if __name__ == '__main__':
+
+	logging.basicConfig(format='%(asctime)s %(levelname)s %(message)s', level=logging.INFO)
+
+	parser = ArgumentParser(description='ALSA loopback (with volume forwarding)')
+
+	playback_pcms = pcms(pcmtype=PCM_PLAYBACK)
+	capture_pcms = pcms(pcmtype=PCM_CAPTURE)
+
+	if not playback_pcms:
+		logging.error('no playback PCM found')
+		sys.exit(2)
+
+	if not capture_pcms:
+		logging.error('no capture PCM found')
+		sys.exit(2)
+
+	parser.add_argument('-d', '--debug', action='store_true')
+	parser.add_argument('-i', '--input', default=capture_pcms[0])
+	parser.add_argument('-o', '--output', default=playback_pcms[0])
+	parser.add_argument('-r', '--rate', type=int, default=44100)
+	parser.add_argument('-c', '--channels', type=int, default=2)
+	parser.add_argument('-p', '--periodsize', type=int, default=444) # must be divisible by 6 for 44k1
+	parser.add_argument('-P', '--periods', type=int, default=2)
+	parser.add_argument('-I', '--input-mixer', help='Control of the input mixer, can contain the card index, e.g. Digital:2')
+	parser.add_argument('-O', '--output-mixer', help='Control of the output mixer, can contain the card index, e.g. PCM:1')
+	parser.add_argument('-A', '--run-after-stop', help='command to run when the capture device is idle/silent')
+	parser.add_argument('-B', '--run-before-start', help='command to run when the capture device becomes active')
+	parser.add_argument('-V', '--volume', help='Initial volume (default is leave unchanged)')
+
+	args = parser.parse_args()
+
+	if args.debug:
+		logging.getLogger().setLevel(logging.DEBUG)
+
+	playback_args = {
+		'type': PCM_PLAYBACK,
+		'mode': PCM_NONBLOCK,
+		'device': args.output,
+		'rate': args.rate,
+		'channels': args.channels,
+		'periodsize': args.periodsize,
+		'periods': args.periods
+	}
+
+	reactor = Reactor()
+
+	# If args.input_mixer and args.output_mixer are set, forward the capture volume to the playback volume.
+	# The usecase is a capture device that is implemented using g_audio, i.e. the Linux USB gadget driver.
+	# When a USB device (eg. an iPad) is connected to this machine, its volume events will go to the volume control
+	# of the output device
+
+	capture = None
+	playback = None
+	volume_handler = None
+	if args.input_mixer and args.output_mixer:
+		re_mixer = re.compile(r'([a-zA-Z0-9]+):?([0-9+])?')
+
+		input_mixer_card = None
+		m = re_mixer.match(args.input_mixer)
+		if m:
+			input_mixer = m.group(1)
+			if m.group(2):
+				input_mixer_card = int(m.group(2))
+		else:
+			parser.print_usage()
+			sys.exit(1)
+
+		output_mixer_card = None
+		m = re_mixer.match(args.output_mixer)
+		if m:
+			output_mixer = m.group(1)
+			if m.group(2):
+				output_mixer_card = int(m.group(2))
+		else:
+			parser.print_usage()
+			sys.exit(1)
+
+		if input_mixer_card is None:
+			capture = PCM(type=PCM_CAPTURE, mode=PCM_NONBLOCK, device=args.input, rate=args.rate,
+				channels=args.channels, periodsize=args.periodsize, periods=args.periods)
+			input_mixer_card = capture.info()['card_no']
+
+		if output_mixer_card is None:
+			playback = PCM(**playback_args)
+			output_mixer_card = playback.info()['card_no']
+			playback.close()
+
+		playback_control = Mixer(control=output_mixer, cardindex=int(output_mixer_card))
+		capture_control = Mixer(control=input_mixer, cardindex=int(input_mixer_card))
+
+		volume_handler = VolumeForwarder(capture_control, playback_control)
+		reactor.register(PollDescriptor.from_alsa_object('capture_control', capture_control, select.POLLIN), volume_handler)
+
+	if args.volume and playback_control:
+		playback_control.setvolume(int(args.volume))
+
+	loopback = Loopback(capture, playback_args, volume_handler, args.run_after_stop, args.run_before_start)
+	loopback.register(reactor)
+	loopback.start()
+
+	reactor.run()

mixertest.py

@@ -72,8 +72,13 @@ def show_mixer(name, kwargs):
     volumes = mixer.getvolume()
     volumes_dB = mixer.getvolume(units=alsaaudio.VOLUME_UNITS_DB)
     for i in range(len(volumes)):
-        print("Channel %i volume: %i%% (%.1f dB)" % (i, volumes[i], volumes_dB[i] / 100.0))
-        
+        print("Channel %i playback volume: %i%% (%.1f dB)" % (i, volumes[i], volumes_dB[i] / 100.0))
+
+    volumes = mixer.getvolume(pcmtype=alsaaudio.PCM_CAPTURE)
+    volumes_dB = mixer.getvolume(pcmtype=alsaaudio.PCM_CAPTURE, units=alsaaudio.VOLUME_UNITS_DB)
+    for i in range(len(volumes)):
+        print("Channel %i capture volume: %i%% (%.1f dB)" % (i, volumes[i], volumes_dB[i] / 100.0))
+
     try:
         mutes = mixer.getmute()
         for i in range(len(mutes)):
@@ -113,7 +118,7 @@ def set_mixer(name, args, kwargs):
             mixer.setmute(1, channel)
         else:
             mixer.setmute(0, channel)
-        
+
     elif args in ['rec','unrec']:
         # Enable/disable recording
         if args == 'rec':

setup.py

@@ -8,7 +8,7 @@ from setuptools import setup
 from setuptools.extension import Extension
 from sys import version
 
-pyalsa_version = '0.10.0'
+pyalsa_version = '0.10.1'
 
 if __name__ == '__main__':
     setup(
@@ -29,12 +29,12 @@ if __name__ == '__main__':
             'License :: OSI Approved :: Python Software Foundation License',
             'Operating System :: POSIX :: Linux',
             'Programming Language :: Python :: 2',
-            'Programming Language :: Python :: 3',    
+            'Programming Language :: Python :: 3',
             'Topic :: Multimedia :: Sound/Audio',
             'Topic :: Multimedia :: Sound/Audio :: Mixers',
             'Topic :: Multimedia :: Sound/Audio :: Players',
             'Topic :: Multimedia :: Sound/Audio :: Capture/Recording',
             ],
-        ext_modules=[Extension('alsaaudio',['alsaaudio.c'], 
+        ext_modules=[Extension('alsaaudio',['alsaaudio.c'],
                                libraries=['asound'])]
     )

test.py

@@ -11,6 +11,7 @@
 import unittest
 import alsaaudio
 import warnings
+from contextlib import closing
 
 # we can't test read and write well - these are tested otherwise
 PCMMethods = [
@@ -20,7 +21,7 @@ PCMMethods = [
 ]
 
 PCMDeprecatedMethods = [
-	('setchannels', (2,)), 
+	('setchannels', (2,)),
 	('setrate', (44100,)),
 	('setformat', (alsaaudio.PCM_FORMAT_S8,)),
 	('setperiodsize', (320,))
@@ -49,10 +50,10 @@ class MixerTest(unittest.TestCase):
 
 	def testMixer(self):
 		"""Open the default Mixers and the Mixers on every card"""
-		
+
 		for c in alsaaudio.card_indexes():
 			mixers = alsaaudio.mixers(cardindex=c)
-			
+
 			for m in mixers:
 				mixer = alsaaudio.Mixer(m, cardindex=c)
 				mixer.close()
@@ -73,7 +74,7 @@ class MixerTest(unittest.TestCase):
 		mixer.close()
 
 	def testMixerClose(self):
-		"""Run common Mixer methods on a closed object and verify it raises an 
+		"""Run common Mixer methods on a closed object and verify it raises an
 		error"""
 
 		mixers = alsaaudio.mixers()
@@ -133,7 +134,7 @@ class PCMTest(unittest.TestCase):
 				pcm = alsaaudio.PCM(card='default')
 			except alsaaudio.ALSAAudioError:
 				pass
-				
+
 			# Verify we got a DepreciationWarning
 			self.assertEqual(len(w), 1, "PCM(card='default') expected a warning" )
 			self.assertTrue(issubclass(w[-1].category, DeprecationWarning), "PCM(card='default') expected a DeprecationWarning")
@@ -156,5 +157,31 @@ class PCMTest(unittest.TestCase):
 				self.assertEqual(len(w), 1, method + " expected a warning")
 				self.assertTrue(issubclass(w[-1].category, DeprecationWarning), method + " expected a DeprecationWarning")
 
+class PollDescriptorArgsTest(unittest.TestCase):
+	'''Test invalid args for polldescriptors_revents (takes a list of tuples of 2 integers)'''
+	def testArgsNoList(self):
+		with closing(alsaaudio.PCM()) as pcm:
+			with self.assertRaises(TypeError):
+				pcm.polldescriptors_revents('foo')
+
+	def testArgsListButNoTuples(self):
+		with closing(alsaaudio.PCM()) as pcm:
+			with self.assertRaises(TypeError):
+				pcm.polldescriptors_revents(['foo', 1])
+
+	def testArgsListButInvalidTuples(self):
+		with closing(alsaaudio.PCM()) as pcm:
+			with self.assertRaises(TypeError):
+				pcm.polldescriptors_revents([('foo', 'bar')])
+
+	def testArgsListTupleWrongLength(self):
+		with closing(alsaaudio.PCM()) as pcm:
+			with self.assertRaises(TypeError):
+				pcm.polldescriptors_revents([(1, )])
+
+			with self.assertRaises(TypeError):
+				pcm.polldescriptors_revents([(1, 2, 3)])
+
+
 if __name__ == '__main__':
 	unittest.main()