cardindex - the card index. If this argument is given, the device name
is constructed as: ‘hw:cardindex’ and
the device keyword argument is ignored. 0 is the first hardware sound
-card.
+card.
+
Note: This should not be used, as it bypasses most of ALSA’s configuration.
+
device - the name of the device on which the mixer resides. The default
is 'default'.
@@ -110,13 +112,13 @@ device, not the mixers for the first card.
This class is used to represent a PCM device (either for playback and
recording). The arguments are:
@@ -130,10 +132,6 @@ recording). The arguments are:
The default value is PCM_FORMAT_S16_LE.
-
-
-
-
Format
Description
@@ -144,7 +142,7 @@ The default value is
Signed 8 bit samples for each channel
PCM_FORMAT_U8
-
Signed 8 bit samples for each channel
+
Unsigned 8 bit samples for each channel
PCM_FORMAT_S16_LE
Signed 16 bit samples for each channel Little Endian byte order)
@@ -223,17 +221,27 @@ The default value is
-
-
periodsize - the period size in frames. Each write should consist of periodsize frames. The default value is 32.
+
+
periodsize - the period size in frames.
+Make sure you understand the meaning of periods.
+The default value is 32, which is below the actual minimum of most devices,
+and will therefore likely be larger in practice.
+
periods - the number of periods in the buffer. The default value is 4.
device - the name of the PCM device that should be used (for example
a value from the output of pcms()). The default value is
'default'.
cardindex - the card index. If this argument is given, the device name
is constructed as ‘hw:cardindex’ and
the device keyword argument is ignored.
-0 is the first hardware sound card.
+0 is the first hardware sound card.
+
Note: This should not be used, as it bypasses most of ALSA’s configuration.
+
This will construct a PCM object with the given settings.
+
Changed in 0.10:
+
+
Added the optional named parameter periods.
+
Changed in 0.9:
Added the optional named parameters rate, channels, format and periodsize.
@@ -249,6 +257,159 @@ name of the card. This was always fragile and broke some legitimate usecases.
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 (\(\mu s\))
+
+
period_size
+
PCM():period_size
+
integer (frames)
+
+
buffer_time
+
buffer time
+
integer (\(\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. “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():”.
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) ‘.
Returs the current state of the stream, which can be one of
+PCM_STATE_OPEN (this should not actually happen),
+PCM_STATE_SETUP (after drop() or drain()),
+PCM_STATE_PREPARED (after construction),
+PCM_STATE_RUNNING,
+PCM_STATE_XRUN,
+PCM_STATE_DRAINING,
+PCM_STATE_PAUSED,
+PCM_STATE_SUSPENDED, and
+PCM_STATE_DISCONNECTED.
In PCM_NONBLOCK mode, the call will return immediately, with a
return value of zero, if the buffer is full. In this case, the data
should be written at a later time.
+
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.
@@ -340,12 +536,37 @@ should be written at a later time.
Otherwise, playback/capture is resumed.
For PCM_PLAYBACK PCM objects, play residual buffered frames
+and then stop the stream. In PCM_NORMAL mode,
+this function blocks until all pending playback is drained.
+
For PCM_CAPTURE PCM objects, this function is not very useful.
Returns a tuple 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
+
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
select module.
@@ -385,10 +606,6 @@ return value can be either
-
-
-
-
Timestamp Type
Description
@@ -411,10 +628,6 @@ time using only the system clock.
The timestamp mode is controlled by the tstamp_mode, as described in the table below.
-
-
-
-
Timestamp Mode
Description
@@ -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.
-
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
+units argument.
The optional pcmtype argument can be either PCM_PLAYBACK or
PCM_CAPTURE, which is relevant if the mixer can control both
playback and capture volume. The default value is PCM_PLAYBACK
if the mixer has playback channels, otherwise it is PCM_CAPTURE.
Returns a list with the current volume settings for each channel. The list
-elements are integer percentages.
+elements are integers whose meaning is determined by the units argument.
The optional pcmtype argument can be either PCM_PLAYBACK or
PCM_CAPTURE, which is relevant if the mixer can control both
playback and capture volume. The default value is PCM_PLAYBACK
if the mixer has playback channels, otherwise it is PCM_CAPTURE.
+
The optional units argument can be one of VOLUME_UNITS_PERCENTAGE,
+VOLUME_UNITS_RAW, or VOLUME_UNITS_DB.
Change the current volume settings for this mixer. The volume argument
-controls the new volume setting as an integer percentage.
+is an integer whose meaning is determined by the units argument.
If the optional argument channel is present, the volume is set
only for this channel. This assumes that the mixer can control the
volume for the channels independently.
@@ -658,6 +861,16 @@ volume for the channels independently.
PCM_CAPTURE, which is relevant if the mixer can control both
playback and capture volume. The default value is PCM_PLAYBACK
if the mixer has playback channels, otherwise it is PCM_CAPTURE.
+
The optional units argument can be one of VOLUME_UNITS_PERCENTAGE,
+VOLUME_UNITS_RAW, or VOLUME_UNITS_DB.
Acknowledge events on the polldescriptors file descriptors
+
Acknowledge events on the polldescriptors() file descriptors
to prevent subsequent polls from returning the same events again.
Returns the number of events that were acknowledged.
The ALSA mixer API is extremely complicated - and hardly documented at all.
alsaaudio 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.
This software is licensed under the PSF license - the same one used by the
majority of the python distribution. Basically you can use it for anything you
wish (even commercial purposes). There is no warranty whatsoever.
The older Linux sound API (OSS) which is now deprecated is well supported from
-the standard Python library, through the ossaudiodev module. No native ALSA
+
The older Linux sound API (OSS) – which is now deprecated – is well supported
+by the standard Python library, through the ossaudiodev module. No native ALSA
support exists in the standard library.
There are a few other “ALSA for Python” projects available, including at least
two different projects called pyAlsa. Neither of these seem to be under active
@@ -90,7 +89,7 @@ appreciated.
Note: the wrappers link with the alsasound library (from the alsa-lib package)
and need the ALSA headers for compilation. Verify that you have
/usr/lib/libasound.so and /usr/include/alsa (or similar paths) before building.
In order to use PCM devices it is useful to be familiar with some concepts and
terminology.
@@ -49,47 +48,53 @@ they can be big endian byte integers, little endian byte integers, or
floating point numbers.
Musically, the sample size determines the dynamic range. The
dynamic range is the difference between the quietest and the
-loudest signal that can be resproduced.
+loudest signal that can be reproduced.
Frame
A frame consists of exactly one sample per channel. If there is only one
channel (Mono sound) a frame is simply a single sample. If the sound is
stereo, each frame consists of two samples, etc.
-
Frame size
-
This is the size in bytes of each frame. This can vary a lot: if each sample
-
is 8 bits, and we’re handling mono sound, the frame size is one byte.
Similarly in 6 channel audio with 64 bit floating point samples, the frame
-size is 48 bytes
-
-
-
-
+
Frame size
This is the size in bytes of each frame. This can vary a lot: if each sample
+is 8 bits, and we’re handling mono sound, the frame size is one byte.
+For six channel audio with 64 bit floating point samples, the frame size
+is 48 bytes.
Rate
PCM sound consists of a flow of sound frames. The sound rate controls how
often the current frame is replaced. For example, a rate of 8000 Hz
means that a new frame is played or captured 8000 times per second.
-
Data rate
This is the number of bytes, which must be recorded or provided per
+
Data rate
This is the number of bytes which must be consumed or provided per
second at a certain frame size and rate.
8000 Hz mono sound with 8 bit (1 byte) samples has a data rate of
8000 * 1 * 1 = 8 kb/s or 64kbit/s. This is typically used for telephony.
At the other end of the scale, 96000 Hz, 6 channel sound with 64
bit (8 bytes) samples has a data rate of 96000 * 6 * 8 = 4608
-kb/s (almost 5 MB sound data per second)
+kb/s (almost 5 MB sound data per second).
+
If the data rate requirement is not met, an overrun (on capture) or
+underrun (on playback) occurs; the term “xrun” is used to refer to
+either event.
-
Period
When the hardware processes data this is done in chunks of frames. The time
-interval between each processing (A/D or D/A conversion) is known
-as the period.
-The size of the period has direct implication on the latency of the
-sound input or output. For low-latency the period size should be
-very small, while low CPU resource usage would usually demand
-larger period sizes. With ALSA, the CPU utilization is not impacted
-much by the period size, since the kernel layer buffers multiple
-periods internally, so each period generates an interrupt and a
-memory copy, but userspace can be slower and read or write multiple
-periods at the same time.
+
+
+
Period
The CPU processes sample data in chunks of frames, so-called periods
+(also called fragments by some systems). The operating system kernel’s
+sample buffer must hold at least two periods (at any given time, one
+is processed by the sound hardware, and one by the CPU).
+
The completion of a period triggers a CPU interrupt, which causes
+processing and context switching overhead. Therefore, a smaller period
+size causes higher CPU resource usage at a given data rate.
+
A bigger size of the buffer improves the system’s resilience to xruns.
+The buffer being split into a bigger number of smaller periods also does
+that, as it allows it to be drained / topped up sooner.
+
On the other hand, a bigger size of the buffer also increases the
+playback latency, that is, the time it takes for a frame from being
+sent out by the application to being actually audible.
+
Similarly, a bigger period size increases the capture latency.
+
The trade-off between latency, xrun resilience, and resource usage
+must be made depending on the application.
-
Period size
This is the size of each period in Hz. Not bytes, but Hz!. In
-alsaaudio the period size is set directly, and it is
+
Period size
This is the size of each period in frames. Not bytes, but frames!
+In alsaaudio the period size is set directly, and it is
therefore important to understand the significance of this
number. If the period size is configured to for example 32,
each write should contain exactly 32 frames of sound data, and each
@@ -145,7 +150,7 @@ on.