auracaster/sw_pyalsaaudio
3
0
Fork 0
forked from auracaster/pyalsaaudio
Code Pull Requests Activity

First version documentation PCM.info() method. (#119)

Browse Source 
* First version documentation PCM.info() method.

* Add reference to documentation to docstring for PCM.info() method.

* Add extra fields to info dict:
  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
and update documentation accordingly.

Co-authored-by: Ronald van Elburg <Ronald@SoundAppraisal.eu>
This commit is contained in:
Ronald van Elburg
2022-11-26 19:08:32 +01:00
committed by GitHub
parent 6317d9addc
commit b2f0466dd2
2 changed files with 81 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
alsaaudio.c
View File

@@ -510,7 +510,7 @@ alsapcm_new(PyTypeObject *type, PyObject *args, PyObject *kwds)
if (res >= 0) {
res = alsapcm_setup(self);
}
if (res >= 0) {
self->cardname = strdup(device);
}
@@ -674,6 +674,9 @@ alsapcm_info(alsapcm_t *self, PyObject *args)
snd_pcm_hw_params_alloca(&hwparams);
snd_pcm_hw_params_current(self->handle,hwparams);
snd_pcm_info_t * pcm_info;
snd_pcm_info_alloca(&pcm_info);
if (!PyArg_ParseTuple(args,":info"))
return NULL;
@@ -688,6 +691,20 @@ alsapcm_info(alsapcm_t *self, PyObject *args)
PyDict_SetItemString(info,"name",value);
Py_DECREF(value);
snd_pcm_info(self->handle, pcm_info);
value = PyLong_FromLong((long) snd_pcm_info_get_card(pcm_info));
PyDict_SetItemString(info,"card_no",value);
Py_DECREF(value);
value = PyLong_FromUnsignedLong((unsigned long) snd_pcm_info_get_device(pcm_info));
PyDict_SetItemString(info,"device_no",value);
Py_DECREF(value);
value = PyLong_FromUnsignedLong((unsigned long) snd_pcm_info_get_subdevice(pcm_info));
PyDict_SetItemString(info,"subdevice_no",value);
Py_DECREF(value);
value=PyUnicode_FromString(snd_pcm_state_name(snd_pcm_state(self->handle)));
PyDict_SetItemString(info,"state",value);
Py_DECREF(value);
@@ -847,6 +864,9 @@ PyDoc_STRVAR(pcm_info_doc,
Returns a dictionary with the alsa device parameters as it is realized. \n\
Keys are retrieved from the alsa library if they can be accessed, if not \n\
they represent values stored by pyalsaaudio and they are prefixed with ' (call value) '. \n\
\n\
For a complete overview of all keys produced see the documentation on PCM.info at: \n\
https://larsimmisch.github.io/pyalsaaudio/libalsaaudio.html#pcm-objects \n\
");
@@ -899,7 +919,7 @@ alsapcm_set_tstamp_mode(alsapcm_t *self, PyObject *args)
if (!PyArg_ParseTuple(args,"|i:set_tstamp_mode", &mode))
return NULL;
if (!self->handle)
{
PyErr_SetString(ALSAAudioError, "PCM device is closed");
@@ -939,7 +959,7 @@ alsapcm_get_tstamp_mode(alsapcm_t *self, PyObject *args)
if (!PyArg_ParseTuple(args,":get_tstamp_mode"))
return NULL;
if (!self->handle)
{
PyErr_SetString(ALSAAudioError, "PCM device is closed");
@@ -976,7 +996,7 @@ alsapcm_set_tstamp_type(alsapcm_t *self, PyObject *args)
if (!PyArg_ParseTuple(args,"|i:set_tstamp_type", &type))
return NULL;
if (!self->handle)
{
PyErr_SetString(ALSAAudioError, "PCM device is closed");
@@ -1015,7 +1035,7 @@ alsapcm_get_tstamp_type(alsapcm_t *self, PyObject *args)
if (!PyArg_ParseTuple(args,":get_tstamp_type"))
return NULL;
if (!self->handle)
{
PyErr_SetString(ALSAAudioError, "PCM device is closed");
@@ -1108,7 +1128,7 @@ alsapcm_getratemaxmin(alsapcm_t *self, PyObject *args)
PyErr_SetString(ALSAAudioError, "Cannot get maximum supported bitrate");
return NULL;
}
PyObject *minp=PyLong_FromLong(min);
PyObject *maxp=PyLong_FromLong(max);
return PyTuple_Pack(2, minp, maxp);
@@ -1135,7 +1155,7 @@ alsapcm_getrates(alsapcm_t *self, PyObject *args)
PyErr_SetString(ALSAAudioError, "Cannot get hardware parameters");
return NULL;
}
unsigned min, max;
if (snd_pcm_hw_params_get_rate_min(params, &min, NULL) <0 ) {
PyErr_SetString(ALSAAudioError, "Cannot get minimum supported bitrate");
@@ -1145,7 +1165,7 @@ alsapcm_getrates(alsapcm_t *self, PyObject *args)
PyErr_SetString(ALSAAudioError, "Cannot get maximum supported bitrate");
return NULL;
}
if (min == max) {
return PyLong_FromLong(min);
}
@@ -1376,7 +1396,7 @@ alsapcm_setformat(alsapcm_t *self, PyObject *args)
if (!PyArg_ParseTuple(args,"i:setformat", &format))
return NULL;
if (!self->handle)
{
PyErr_SetString(ALSAAudioError, "PCM device is closed");
@@ -1433,8 +1453,8 @@ alsapcm_setperiodsize(alsapcm_t *self, PyObject *args)
PyErr_Format(ALSAAudioError, "%s [%s]", snd_strerror(res),
self->cardname);
return NULL;
}
@@ -1514,7 +1534,7 @@ alsapcm_read(alsapcm_t *self, PyObject *args)
if (res > 0 ) {
sizeout = res * self->framesize;
}
if (size != sizeout) {
#if PY_MAJOR_VERSION < 3
/* If the following fails, it will free the object */
@@ -1526,7 +1546,7 @@ alsapcm_read(alsapcm_t *self, PyObject *args)
return NULL;
#endif
}
res_obj = PyLong_FromLong(res);
if (!res_obj) {
Py_DECREF(buffer_obj);
@@ -1693,7 +1713,7 @@ static PyObject *alsapcm_drop(alsapcm_t *self)
return NULL;
}
res = snd_pcm_prepare(self->handle);
if (res < 0)
{
@@ -1702,7 +1722,7 @@ static PyObject *alsapcm_drop(alsapcm_t *self)
return NULL;
}
return PyLong_FromLong(res);
}

46
doc/libalsaaudio.rst
View File

@@ -184,6 +184,52 @@ following arguments:
PCM objects have the following methods:
.. method:: PCM.info()
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
=========================== ============================= ==================================================================
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
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_name PCM():format string
format_description PCM():format string
subformat_name *name of PCM subformat* string
subformat_description *description of subformat* string
channels PCM():channels integer
rate PCM():rate integer (Hz)
period_time *period duration* integer (:math:`\mu s`)
period_size PCM():period_size integer (frames)
buffer_time *buffer time* integer (:math:`\mu s`) (negative indicates error)
buffer_size *buffer size* integer (frames) (negative indicates error)
get_periods *approx. periods in buffer* integer (negative indicates error)
rate_numden *numerator, denominator* tuple (integer (Hz), integer (Hz))
significant_bits *significant bits in sample* integer (negative indicates error)
is_batch *hw: double buffering* boolean (True: hardware supported)
is_block_transfer *hw: block transfer* boolean (True: hardware supported)
is_double *hw: double buffering* boolean (True: hardware supported)
is_half_duplex *hw: half-duplex* boolean (True: hardware supported)
is_joint_duplex *hw: joint-duplex* boolean (True: hardware supported)
can_overrange *hw: overrange detection* boolean (True: hardware supported)
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)
=========================== ============================= ==================================================================
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()
Returns the type of PCM object. Either :const:`PCM_CAPTURE` or