forked from auracaster/pyalsaaudio
assorted improvements (#123)
* fix draining/closing, take 2 commit8abf06beintroduced a pause() prior to draining, in an attempt to work around clearly broken pulseaudio client behavior for capture streams (drain() is supposed to imply a stop). but as the workaround was also applied to playback streams, it would cause nasty "clicks", as the stream would (obviously) stop before being resumed for draining. but draining is actually pointless for capture streams, as we're closing right afterwards, so the samples are lost anyway. what's more, destructors are not supposed to wait for anything, so draining in alsapcm_dealloc() was wrong to start with. so we remove it. note that this is a minor behavior change, which is reflected by the adjustment of the playback test to have an explicit close() at the end. finally, close() was also affected by the pulseaudio bug (which was not addressed before), so there we make draining exclusive to playback streams. * fix memory leaks in *_polldescriptors() the calloc'd pollfd arrays were not freed. * fix memory handling in mixer access error paths in case of error, alsamixer_new() would leak the object, while alsamixer_list() might crash due to a null pointer. as a drive-by, make alsamixer_gethandle() `static`. * fix crashes when accessing already closed devices PCM.htimestamp() gets the usual exception emission, Mixer.close() gets a "double invocation" check like PCM.close() has. * fix deprecation warning about PyEval_InitThreads() PyEval_InitThreads is a no-op in since python 3.9. * fix deprecation warning about PyUnicode_AsUnicode() converting to ascii for the purpose of comparison is inefficient. * remove redundant snd_pcm_hw_params_any() call we just called it (and even error-checked it) a few lines above. * add new high-speed samples rates closes #89 (but alsa doesn't support 768khz yet). * drop some pointless comments from the tex => sphinx conversion amends5c2a00655. * remove bogus markup from the documentation the poll objects are linked properly in a different way, and the footnote appears outdated. * unify line spacing in .rst files one empty line, except for high-level sections, which get two. while at it, trim whitespace on otherwise empty lines. * formatting/language fixes in introduction document * improve terminology document mention xruns, and rework the definition of periods: concentrate on relevant information, and remove the misinformation about period size reduction being not that bad (pedantically, an application could run somewhat asynchronously to the interrupts by using some timer, and therefore actually save some of the overhead, but why would one use a small period size in the first place then?). also, language and formatting fixes. * add missing and update incorrect/outdated documentation for clarity, this includes docs which were previously omitted (presumably) intentionally, but mark them as comments. the getrec() and getmute() functions' docs are moved around, so they appear in pairs with their set*() counterparts, like the *volume() ones already did. notably, this also fixes the docu of PCM_FORMAT_U8, which closes #104. * add some best practices to the docu addresses #110, among other things. * purge pydoc from the source it's been obsolete for a *long* time, and having it redundantly to the rst sources is bad hygiene. it still contained some useful info, which has been transplanted to the rst source in the previous commit. * use data types closer to those of ALSA this removes lots of casts around snd_pcm_hw_params_get_*() calls we could go further with that to make the code clean if we enabled all the warnings, but it doesn't seem worth the effort. * reduce scope of GIL releases it's pointless to enclose snd_pcm_close() and snd_pcm_pause(), as these calls don't sleep. * reshuffle XRUN recovery somewhat perform it prior to invoking read()/write() if necessary, not right after a failure event. this makes things more uniform and predictable. we don't use snd_pcm_recover() any more, as we used it only for the EPIPE case anyway, which boils down to snd_pcm_prepare() exactly. handling ESTRPIPE as well might be desirable, but that's a separate consideration. * bump (minor) version we're about to add new features. * make period count configurable the period count is just as important for playback latency as the period size, so it makes no sense to have only one of them configurable. as a drive-by, fix up the handling of periods in info() & dumpinfo(). * add PCM.drain() for playback, this allows making sure that all written frames are played, without using an external delay. in principle, it's also usable for capture, but there isn't really a practical reason to do so, as simply discarding excess captured frames has no real cost. * add PCM.state() and associated enum values in principle, the state is already available from info(), but that's a rather heavy function for something one might want to query often. a practical use case might be checking whether a playback stream is done draining, for example.
This commit is contained in:
Oswald Buddenhagen
committed by
GitHub
GitHub
parent
19c9ba3ed9
commit
196ca87a05
705
alsaaudio.c
705
alsaaudio.c
File diff suppressed because it is too large
Load Diff
@@ -1,8 +1,3 @@
|
||||
.. alsaaudio documentation documentation master file, created by
|
||||
sphinx-quickstart on Thu Mar 30 23:52:21 2017.
|
||||
You can adapt this file completely to your liking, but it should at least
|
||||
contain the root `toctree` directive.
|
||||
|
||||
alsaaudio documentation
|
||||
===================================================
|
||||
|
||||
@@ -18,15 +13,13 @@ Download
|
||||
========
|
||||
|
||||
* `Download from pypi <https://pypi.python.org/pypi/pyalsaaudio>`_
|
||||
|
||||
|
||||
|
||||
Github
|
||||
======
|
||||
|
||||
* `Repository <https://github.com/larsimmisch/pyalsaaudio/>`_
|
||||
* `Bug tracker <https://github.com/larsimmisch/pyalsaaudio/issues>`_
|
||||
|
||||
|
||||
Indices and tables
|
||||
==================
|
||||
|
||||
@@ -34,5 +27,3 @@ Indices and tables
|
||||
* :ref:`modindex`
|
||||
* :ref:`search`
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -5,38 +5,15 @@
|
||||
.. module:: alsaaudio
|
||||
:platform: Linux
|
||||
|
||||
|
||||
.. % \declaremodule{builtin}{alsaaudio} % standard library, in C
|
||||
.. % not standard, in C
|
||||
|
||||
.. moduleauthor:: Casper Wilstrup <cwi@aves.dk>
|
||||
.. moduleauthor:: Lars Immisch <lars@ibp.de>
|
||||
|
||||
.. % Author of the module code;
|
||||
|
||||
|
||||
|
||||
The :mod:`alsaaudio` module defines functions and classes for using ALSA.
|
||||
|
||||
.. % ---- 3.1. ----
|
||||
.. % For each function, use a ``funcdesc'' block. This has exactly two
|
||||
.. % parameters (each parameters is contained in a set of curly braces):
|
||||
.. % the first parameter is the function name (this automatically
|
||||
.. % generates an index entry); the second parameter is the function's
|
||||
.. % argument list. If there are no arguments, use an empty pair of
|
||||
.. % curly braces. If there is more than one argument, separate the
|
||||
.. % arguments with backslash-comma. Optional parts of the parameter
|
||||
.. % list are contained in \optional{...} (this generates a set of square
|
||||
.. % brackets around its parameter). Arguments are automatically set in
|
||||
.. % italics in the parameter list. Each argument should be mentioned at
|
||||
.. % least once in the description; each usage (even inside \code{...})
|
||||
.. % should be enclosed in \var{...}.
|
||||
|
||||
|
||||
.. function:: pcms(pcmtype=PCM_PLAYBACK)
|
||||
|
||||
List available PCM devices by name.
|
||||
|
||||
|
||||
Arguments are:
|
||||
|
||||
* *pcmtype* - can be either :const:`PCM_CAPTURE` or :const:`PCM_PLAYBACK`
|
||||
@@ -62,7 +39,13 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
|
||||
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`
|
||||
instead.
|
||||
|
||||
|
||||
..
|
||||
Omitted by intention due to being superseded by cards():
|
||||
|
||||
.. function:: card_indexes()
|
||||
.. function:: card_name()
|
||||
|
||||
.. function:: mixers(cardindex=-1, device='default')
|
||||
|
||||
List the available mixers. The arguments are:
|
||||
@@ -72,12 +55,14 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
|
||||
the `device` keyword argument is ignored. ``0`` is the first hardware sound
|
||||
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'``.
|
||||
|
||||
**Note:** For a list of available controls, you can also use ``amixer`` on
|
||||
the commandline::
|
||||
|
||||
|
||||
$ amixer
|
||||
|
||||
To elaborate the example, calling :func:`mixers` with the argument
|
||||
@@ -91,7 +76,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
|
||||
$ amixer -D foo
|
||||
|
||||
*Changed in 0.8*:
|
||||
|
||||
|
||||
- The keyword argument `device` is new and can be used to
|
||||
select virtual devices. As a result, the default behaviour has subtly
|
||||
changed. Since 0.8, this functions returns the mixers for the default
|
||||
@@ -101,6 +86,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA.
|
||||
|
||||
Return a Python string containing the ALSA version found.
|
||||
|
||||
|
||||
.. _pcm-objects:
|
||||
|
||||
PCM Objects
|
||||
@@ -110,7 +96,7 @@ 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, 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)
|
||||
|
||||
This class is used to represent a PCM device (either for playback and
|
||||
recording). The arguments are:
|
||||
@@ -123,7 +109,7 @@ following arguments:
|
||||
* *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.
|
||||
The default value is :const:`PCM_FORMAT_S16_LE`.
|
||||
|
||||
|
||||
========================= ===============
|
||||
Format Description
|
||||
========================= ===============
|
||||
@@ -156,7 +142,11 @@ following arguments:
|
||||
``PCM_FORMAT_U24_3BE`` Unsigned 24 bit samples for each channel (Big Endian byte order in 3 bytes)
|
||||
========================= ===============
|
||||
|
||||
* *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 :ref:`the meaning of periods <term-period>`.
|
||||
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 :func:`pcms`). The default value is
|
||||
``'default'``.
|
||||
@@ -165,14 +155,20 @@ following arguments:
|
||||
the `device` keyword argument is ignored.
|
||||
``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`.
|
||||
|
||||
*Changed in 0.8:*
|
||||
|
||||
|
||||
- The `card` keyword argument is still supported,
|
||||
but deprecated. Please use `device` instead.
|
||||
|
||||
@@ -180,8 +176,7 @@ following arguments:
|
||||
|
||||
The `card` keyword is deprecated because it guesses the real ALSA
|
||||
name of the card. This was always fragile and broke some legitimate usecases.
|
||||
|
||||
|
||||
|
||||
PCM objects have the following methods:
|
||||
|
||||
.. method:: PCM.info()
|
||||
@@ -235,17 +230,43 @@ PCM objects have the following methods:
|
||||
Returns the type of PCM object. Either :const:`PCM_CAPTURE` or
|
||||
:const:`PCM_PLAYBACK`.
|
||||
|
||||
|
||||
.. method:: PCM.pcmmode()
|
||||
|
||||
Return the mode of the PCM object. One of :const:`PCM_NONBLOCK`,
|
||||
:const:`PCM_ASYNC`, or :const:`PCM_NORMAL`
|
||||
|
||||
|
||||
.. method:: PCM.cardname()
|
||||
|
||||
Return the name of the sound card used by this PCM object.
|
||||
|
||||
..
|
||||
Omitted by intention due to not really fitting the c'tor-based setup concept:
|
||||
|
||||
.. method:: PCM.getchannels()
|
||||
|
||||
Returns list of the device's supported channel counts.
|
||||
|
||||
.. method:: PCM.getratebounds()
|
||||
|
||||
Returns the card's minimum and maximum supported sample rates as
|
||||
a tuple of integers.
|
||||
|
||||
.. method:: PCM.getrates()
|
||||
|
||||
Returns the sample rates supported by the device.
|
||||
The returned value can be of one of the following, depending on
|
||||
the card's properties:
|
||||
* Card supports only a single rate: returns the rate
|
||||
* Card supports a continuous range of rates: returns a tuple of
|
||||
the range's lower and upper bounds (inclusive)
|
||||
* Card supports a collection of well-known rates: returns a list of
|
||||
the supported rates
|
||||
|
||||
.. method:: PCM.getformats()
|
||||
|
||||
Returns a dictionary of supported format codes (integers) keyed by
|
||||
their standard ALSA names (strings).
|
||||
|
||||
.. method:: PCM.setchannels(nchannels)
|
||||
|
||||
.. deprecated:: 0.9 Use the `channels` named argument to :func:`PCM`.
|
||||
@@ -255,13 +276,42 @@ PCM objects have the following methods:
|
||||
.. deprecated:: 0.9 Use the `rate` named argument to :func:`PCM`.
|
||||
|
||||
.. method:: PCM.setformat(format)
|
||||
|
||||
|
||||
.. deprecated:: 0.9 Use the `format` named argument to :func:`PCM`.
|
||||
|
||||
.. method:: PCM.setperiodsize(period)
|
||||
|
||||
.. 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()
|
||||
|
||||
Dumps the PCM object's configured parameters to stdout.
|
||||
|
||||
.. method:: PCM.state()
|
||||
|
||||
Returs the current state of the stream, which can be one of
|
||||
:const:`PCM_STATE_OPEN` (this should not actually happen),
|
||||
:const:`PCM_STATE_SETUP` (after :func:`drop` or :func:`drain`),
|
||||
:const:`PCM_STATE_PREPARED` (after construction),
|
||||
:const:`PCM_STATE_RUNNING`,
|
||||
:const:`PCM_STATE_XRUN`,
|
||||
:const:`PCM_STATE_DRAINING`,
|
||||
:const:`PCM_STATE_PAUSED`,
|
||||
:const:`PCM_STATE_SUSPENDED`, and
|
||||
:const:`PCM_STATE_DISCONNECTED`.
|
||||
|
||||
*New in 0.10*
|
||||
|
||||
.. method:: PCM.read()
|
||||
|
||||
In :const:`PCM_NORMAL` mode, this function blocks until a full period is
|
||||
@@ -294,17 +344,42 @@ PCM objects have the following methods:
|
||||
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.
|
||||
|
||||
.. method:: PCM.pause([enable=True])
|
||||
|
||||
If *enable* is :const:`True`, playback or capture is paused.
|
||||
Otherwise, playback/capture is resumed.
|
||||
|
||||
.. method:: PCM.drop()
|
||||
|
||||
Stop the stream and drop residual buffered frames.
|
||||
|
||||
*New in 0.9*
|
||||
|
||||
.. method:: PCM.drain()
|
||||
|
||||
For :const:`PCM_PLAYBACK` PCM objects, play residual buffered frames
|
||||
and then stop the stream. In :const:`PCM_NORMAL` mode,
|
||||
this function blocks until all pending playback is drained.
|
||||
|
||||
For :const:`PCM_CAPTURE` PCM objects, this function is not very useful.
|
||||
|
||||
*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()
|
||||
|
||||
Returns a tuple of *(file descriptor, eventmask)* that can be used to
|
||||
wait for changes on the PCM with *select.poll*.
|
||||
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
|
||||
:const:`select` module.
|
||||
@@ -347,7 +422,7 @@ PCM objects have the following methods:
|
||||
``PCM_TSTAMP_TYPE_MONOTONIC_RAW`` Monotonic time from an unspecified starting
|
||||
time using only the system clock.
|
||||
================================= ===========================================
|
||||
|
||||
|
||||
The timestamp mode is controlled by the tstamp_mode, as described in the table below.
|
||||
|
||||
================================= ===========================================
|
||||
@@ -358,9 +433,6 @@ PCM objects have the following methods:
|
||||
update.
|
||||
================================= ===========================================
|
||||
|
||||
|
||||
__ poll_objects_
|
||||
|
||||
**A few hints on using PCM devices for playback**
|
||||
|
||||
The most common reason for problems with playback of PCM audio is that writes
|
||||
@@ -396,11 +468,10 @@ Mixer Objects
|
||||
|
||||
Mixer objects provides access to the ALSA mixer API.
|
||||
|
||||
|
||||
.. class:: Mixer(control='Master', id=0, cardindex=-1, device='default')
|
||||
|
||||
Arguments are:
|
||||
|
||||
|
||||
* *control* - specifies which control to manipulate using this mixer
|
||||
object. The list of available controls can be found with the
|
||||
:mod:`alsaaudio`.\ :func:`mixers` function. The default value is
|
||||
@@ -416,30 +487,27 @@ Mixer objects provides access to the ALSA mixer API.
|
||||
|
||||
* *device* - the name of the device on which the mixer resides. The default
|
||||
value is ``'default'``.
|
||||
|
||||
|
||||
*Changed in 0.8*:
|
||||
|
||||
|
||||
- The keyword argument `device` is new and can be used to select virtual
|
||||
devices.
|
||||
|
||||
|
||||
Mixer objects have the following methods:
|
||||
|
||||
.. method:: Mixer.cardname()
|
||||
|
||||
Return the name of the sound card used by this Mixer object
|
||||
|
||||
|
||||
.. method:: Mixer.mixer()
|
||||
|
||||
Return the name of the specific mixer controlled by this object, For example
|
||||
``'Master'`` or ``'PCM'``
|
||||
|
||||
|
||||
.. method:: Mixer.mixerid()
|
||||
|
||||
Return the ID of the ALSA mixer controlled by this object.
|
||||
|
||||
|
||||
.. method:: Mixer.switchcap()
|
||||
|
||||
Returns a list of the switches which are defined by this specific mixer.
|
||||
@@ -460,7 +528,6 @@ Mixer objects have the following methods:
|
||||
To manipulate these switches use the :meth:`setrec` or
|
||||
:meth:`setmute` methods
|
||||
|
||||
|
||||
.. method:: Mixer.volumecap()
|
||||
|
||||
Returns a list of the volume control capabilities of this
|
||||
@@ -476,7 +543,7 @@ Mixer objects have the following methods:
|
||||
'Capture Volume' Manipulate sound capture volume
|
||||
'Joined Capture Volume' Manipulate sound capture volume for all channels at a time
|
||||
======================== ================
|
||||
|
||||
|
||||
.. method:: Mixer.getenum()
|
||||
|
||||
For enumerated controls, return the currently selected item and the list of
|
||||
@@ -503,48 +570,43 @@ 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.getmute()
|
||||
For enumerated controls, sets the currently selected item.
|
||||
*index* is an index into the list of available enumerated items returned
|
||||
by :func:`getenum`.
|
||||
|
||||
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.getrange(pcmtype=PCM_PLAYBACK)
|
||||
.. method:: Mixer.getrange(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_RAW)
|
||||
|
||||
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 :const:`PCM_PLAYBACK` or
|
||||
:const:`PCM_CAPTURE`, which is relevant if the mixer can control both
|
||||
playback and capture volume. The default value is :const:`PCM_PLAYBACK`
|
||||
if the mixer has playback channels, otherwise it is :const:`PCM_CAPTURE`.
|
||||
|
||||
The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`,
|
||||
:const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`.
|
||||
|
||||
.. method:: Mixer.getrec()
|
||||
|
||||
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.getvolume(pcmtype=PCM_PLAYBACK)
|
||||
.. method:: Mixer.getvolume(pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE)
|
||||
|
||||
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 :const:`PCM_PLAYBACK` or
|
||||
:const:`PCM_CAPTURE`, which is relevant if the mixer can control both
|
||||
playback and capture volume. The default value is :const:`PCM_PLAYBACK`
|
||||
if the mixer has playback channels, otherwise it is :const:`PCM_CAPTURE`.
|
||||
|
||||
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)
|
||||
.. method:: Mixer.setvolume(volume, channel=None, pcmtype=PCM_PLAYBACK, units=VOLUME_UNITS_PERCENTAGE)
|
||||
|
||||
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
|
||||
@@ -555,6 +617,16 @@ Mixer objects have the following methods:
|
||||
playback and capture volume. The default value is :const:`PCM_PLAYBACK`
|
||||
if the mixer has playback channels, otherwise it is :const:`PCM_CAPTURE`.
|
||||
|
||||
The optional *units* argument can be one of :const:`VOLUME_UNITS_PERCENTAGE`,
|
||||
:const:`VOLUME_UNITS_RAW`, or :const:`VOLUME_UNITS_DB`.
|
||||
|
||||
.. method:: Mixer.getmute()
|
||||
|
||||
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])
|
||||
|
||||
Sets the mute flag to a new value. The *mute* argument is either 0 for not
|
||||
@@ -565,6 +637,12 @@ Mixer objects have the following methods:
|
||||
|
||||
This method will fail if the mixer has no playback mute capabilities
|
||||
|
||||
.. method:: Mixer.getrec()
|
||||
|
||||
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])
|
||||
|
||||
@@ -578,20 +656,22 @@ Mixer objects have the following methods:
|
||||
|
||||
.. method:: Mixer.polldescriptors()
|
||||
|
||||
Returns a tuple of *(file descriptor, eventmask)* that can be used to
|
||||
wait for changes on the mixer with *select.poll*.
|
||||
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
|
||||
:const:`select` module.
|
||||
|
||||
__ poll_objects_
|
||||
|
||||
.. method:: Mixer.handleevents()
|
||||
|
||||
Acknowledge events on the *polldescriptors* file descriptors
|
||||
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()
|
||||
|
||||
Closes the Mixer device.
|
||||
|
||||
**A rant on the ALSA Mixer API**
|
||||
|
||||
The ALSA mixer API is extremely complicated - and hardly documented at all.
|
||||
@@ -614,8 +694,6 @@ Unfortunately, I'm not able to create such a HOWTO myself, since I only
|
||||
understand half of the API, and that which I do understand has come from a
|
||||
painful trial and error process.
|
||||
|
||||
.. % ==== 4. ====
|
||||
|
||||
|
||||
.. _pcm-example:
|
||||
|
||||
@@ -657,6 +735,7 @@ To test PCM playback (on your default soundcard), run::
|
||||
|
||||
recordtest.py and playbacktest.py
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**recordtest.py** and **playbacktest.py** will record and play a raw
|
||||
sound file in CD quality.
|
||||
|
||||
@@ -678,7 +757,7 @@ Without arguments, **mixertest.py** will list all available *controls* on the
|
||||
default soundcard.
|
||||
|
||||
The output might look like this::
|
||||
|
||||
|
||||
$ ./mixertest.py
|
||||
Available mixer controls:
|
||||
'Master'
|
||||
@@ -726,9 +805,3 @@ argument::
|
||||
Capabilities: Playback Volume Playback Mute
|
||||
Channel 0 volume: 61%
|
||||
Channel 1 volume: 61%
|
||||
|
||||
.. rubric:: Footnotes
|
||||
|
||||
.. [#f1] ALSA also allows ``PCM_ASYNC``, but this is not supported yet.
|
||||
|
||||
.. _poll_objects: http://docs.python.org/library/select.html#poll-objects
|
||||
|
||||
@@ -7,33 +7,19 @@ Introduction
|
||||
|
||||
.. |release| replace:: version
|
||||
|
||||
.. % At minimum, give your name and an email address. You can include a
|
||||
.. % snail-mail address if you like.
|
||||
|
||||
.. % This makes the Abstract go on a separate page in the HTML version;
|
||||
.. % if a copyright notice is used, it should go immediately after this.
|
||||
.. %
|
||||
|
||||
|
||||
.. _front:
|
||||
|
||||
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.
|
||||
|
||||
.. % Copyright statement should go here, if needed.
|
||||
|
||||
.. % The abstract should be a paragraph or two long, and describe the
|
||||
.. % scope of the document.
|
||||
|
||||
|
||||
.. topic:: Abstract
|
||||
|
||||
This package contains wrappers for accessing the ALSA API from Python. It is
|
||||
currently fairly complete for PCM devices and Mixer access. MIDI sequencer
|
||||
support is low on our priority list, but volunteers are welcome.
|
||||
|
||||
If you find bugs in the wrappers please use thegithub issue tracker.
|
||||
If you find bugs in the wrappers please use the github issue tracker.
|
||||
Please don't send bug reports regarding ALSA specifically. There are several
|
||||
bugs in this API, and those should be reported to the ALSA team - not me.
|
||||
|
||||
@@ -64,8 +50,8 @@ More information about ALSA may be found on the project homepage
|
||||
ALSA and Python
|
||||
===============
|
||||
|
||||
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
|
||||
@@ -106,6 +92,7 @@ And then as root: --- ::
|
||||
|
||||
# python setup.py install
|
||||
|
||||
|
||||
*******
|
||||
Testing
|
||||
*******
|
||||
@@ -130,7 +117,7 @@ with ``Ctl-C``.
|
||||
|
||||
Play back the recording with::
|
||||
|
||||
$ python playbacktest.py-d <device> <filename>
|
||||
$ python playbacktest.py -d <device> <filename>
|
||||
|
||||
There is a minimal test suite in :code:`test.py`, but it is
|
||||
a bit dependent on the ALSA configuration and may fail without indicating
|
||||
|
||||
@@ -19,7 +19,7 @@ Sample
|
||||
|
||||
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
|
||||
@@ -28,9 +28,9 @@ Frame
|
||||
|
||||
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
|
||||
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
|
||||
@@ -38,7 +38,7 @@ Rate
|
||||
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
|
||||
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
|
||||
@@ -46,24 +46,40 @@ Data rate
|
||||
|
||||
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.
|
||||
|
||||
.. _term-period:
|
||||
|
||||
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.
|
||||
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
|
||||
:mod:`alsaaudio` the period size is set directly, and it is
|
||||
This is the size of each period in frames. *Not bytes, but frames!*
|
||||
In :mod:`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
|
||||
|
||||
@@ -49,5 +49,5 @@ if __name__ == '__main__':
|
||||
while data:
|
||||
out.write(data)
|
||||
data = f.read(320)
|
||||
|
||||
out.close()
|
||||
|
||||
|
||||
Reference in New Issue
Block a user