From 436c31f9fdc45f7ae1fea8921433a6c53d095abd Mon Sep 17 00:00:00 2001 From: Ville Viinikka Date: Tue, 20 Feb 2024 19:31:53 +0200 Subject: [PATCH] Add nominal_bits and physical_bits info Adds the information discussed in pull request #144 --- alsaaudio.c | 16 +++++++++ doc/libalsaaudio.rst | 81 +++++++++++++++++++++++--------------------- doc/terminology.rst | 15 ++++++++ 3 files changed, 74 insertions(+), 38 deletions(-) diff --git a/alsaaudio.c b/alsaaudio.c index d3c15f2..d3b15d9 100644 --- a/alsaaudio.c +++ b/alsaaudio.c @@ -598,6 +598,12 @@ alsapcm_dumpinfo(alsapcm_t *self, PyObject *args) val = snd_pcm_hw_params_get_sbits(hwparams); printf("significant bits = %d\n", val); + val = snd_pcm_format_width(self->format); + printf("nominal bits = %d\n", val); + + val = snd_pcm_format_physical_width(self->format); + printf("physical bits = %d\n", val); + val = snd_pcm_hw_params_is_batch(hwparams); printf("is batch = %d\n", val); @@ -778,6 +784,16 @@ alsapcm_info(alsapcm_t *self, PyObject *args) PyDict_SetItemString(info,"significant_bits", value); Py_DECREF(value); + val = snd_pcm_format_width(self->format); + value=PyLong_FromUnsignedLong((unsigned long) val); + PyDict_SetItemString(info,"nominal_bits", value); + Py_DECREF(value); + + val = snd_pcm_format_physical_width(self->format); + value=PyLong_FromUnsignedLong((unsigned long) val); + PyDict_SetItemString(info,"physical_bits", value); + Py_DECREF(value); + val = snd_pcm_hw_params_is_batch(hwparams); value=PyBool_FromLong((unsigned long) val); PyDict_SetItemString(info,"is_batch", value); diff --git a/doc/libalsaaudio.rst b/doc/libalsaaudio.rst index 2dd90a0..de78c1b 100644 --- a/doc/libalsaaudio.rst +++ b/doc/libalsaaudio.rst @@ -205,44 +205,49 @@ PCM objects have the following methods: the hardware, possibly depending on other properties. Those properties' descriptions are prefixed with "hw:" below. - =========================== ============================= ================================================================== - 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) - =========================== ============================= ================================================================== + =========================== ==================================== ================================================================== + 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* [#tss]_ integer (negative indicates error) + nominal_bits *nominal bits in sample* [#tss]_ integer (negative indicates error) + physical_bits *sample width in bits* [#tss]_ 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) + =========================== ==================================== ================================================================== +.. [#tss] More information in the :ref:`terminology section for sample size ` + +.. The italicized descriptions give a summary of the "full" description as can be found in the diff --git a/doc/terminology.rst b/doc/terminology.rst index 532863e..a0ae53d 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -85,6 +85,21 @@ Period size each write should contain exactly 32 frames of sound data, and each read will return either 32 frames of data or nothing at all. +.. _term-sample-size: + +Sample size + Each sample takes *physical_bits* of space. *nominal_bits* tells + how many least significant bits are used. This is the bit depth + in the format name and sometimes called just *sample bits* or + *format width*. *significant_bits* tells how many most significant + bits of the *nominal_bits* are used by the sample. This can be thought + of as the *sample resolution*. This is visualized as follows:: + + MSB |00000000 XXXXXXXX XXXXXXXX 00000000| LSB + |--significant--| + |---------nominal---------| + |-------------physical--------------| + Once you understand these concepts, you will be ready to use the PCM API. Read on.