diff --git a/README.md b/README.md index f0cfdbb..504a882 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ For documentation, see http://larsimmisch.github.io/pyalsaaudio/ -> Author: Casper Wilstrup (cwi@aves.dk) +> Author: Casper Wilstrup (cwi@aves.dk) > Maintainer: Lars Immisch (lars@ibp.de) This package contains wrappers for accessing the @@ -45,12 +45,12 @@ First, get the sources and change to the source directory: $ git clone https://github.com/larsimmisch/pyalsaaudio.git $ cd pyalsaaudio ``` - + Then, build: ``` $ python setup.py build ``` - + And install: ``` $ sudo python setup.py install diff --git a/doc/README.md b/doc/README.md index 7b1f1df..8b26e3b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -26,7 +26,7 @@ Don't forget to update the documentation. The documentation is published through the `gh-pages` branch. To publish the documentation, you need to clone the `gh-pages` branch of this repository into -`doc/gh-pages`. In `doc`, do: +`doc/gh-pages`. In `doc`, do: git clone -b gh-pages git@github.com:larsimmisch/pyalsaaudio.git gh-pages diff --git a/doc/libalsaaudio.rst b/doc/libalsaaudio.rst index a55e02a..2dd90a0 100644 --- a/doc/libalsaaudio.rst +++ b/doc/libalsaaudio.rst @@ -17,7 +17,7 @@ The :mod:`alsaaudio` module defines functions and classes for using ALSA. Arguments are: * *pcmtype* - can be either :const:`PCM_CAPTURE` or :const:`PCM_PLAYBACK` - (default). + (default). **Note:** @@ -102,12 +102,12 @@ following arguments: recording). The constructor's 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`. ========================= =============== @@ -206,19 +206,19 @@ PCM objects have the following methods: descriptions are prefixed with "hw:" below. =========================== ============================= ================================================================== - 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 @@ -241,7 +241,7 @@ 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 @@ -346,7 +346,7 @@ PCM objects have the following methods: 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 @@ -422,7 +422,7 @@ PCM objects have the following methods: 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.polldescriptors_revents(descriptors) @@ -485,7 +485,7 @@ PCM objects have the following methods: **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 @@ -523,7 +523,7 @@ Mixer objects provides access to the ALSA mixer API. 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. @@ -533,7 +533,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'``. @@ -570,7 +570,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 ====================== ================ @@ -709,7 +709,7 @@ Mixer objects have the following methods: 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() @@ -757,7 +757,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 *. To determine a valid card name, use the commandline ALSA player:: @@ -772,12 +772,12 @@ or:: >>> alsaaudio.pcms() mixertest.py accepts the commandline options *-d * and -*-c *. +*-c *. playwav.py ~~~~~~~~~~ -**playwav.py** plays a wav file. +**playwav.py** plays a wav file. To test PCM playback (on your default soundcard), run:: @@ -825,7 +825,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 @@ -834,7 +834,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 diff --git a/doc/pyalsaaudio.rst b/doc/pyalsaaudio.rst index 42e1126..3f033ff 100644 --- a/doc/pyalsaaudio.rst +++ b/doc/pyalsaaudio.rst @@ -81,7 +81,7 @@ and need the ALSA headers for compilation. Verify that you have Naturally you also need to use a kernel with proper ALSA support. This is the default in Linux kernel 2.6 and later. If you are using kernel version 2.4 you -may need to install the ALSA patches yourself - although most distributions +may need to install the ALSA patches yourself - although most distributions ship with ALSA kernels. To install, execute the following: --- :: diff --git a/doc/terminology.rst b/doc/terminology.rst index 3c16d19..532863e 100644 --- a/doc/terminology.rst +++ b/doc/terminology.rst @@ -6,7 +6,7 @@ In order to use PCM devices it is useful to be familiar with some concepts and terminology. Sample - PCM audio, whether it is input or output, consists of *samples*. + PCM audio, whether it is input or output, consists of *samples*. A single sample represents the amplitude of one channel of sound at a certain point in time. A lot of individual samples are necessary to represent actual sound; for CD audio, 44100 samples @@ -22,8 +22,8 @@ Sample 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 + 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 @@ -33,7 +33,7 @@ Frame size is 48 bytes. Rate - PCM sound consists of a flow of sound frames. The sound rate controls how + 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. diff --git a/isine.py b/isine.py index 3cc764d..5629b38 100644 --- a/isine.py +++ b/isine.py @@ -44,18 +44,18 @@ def generate(frequency, duration = 0.125): # total number of frames size = cycle_size * factor - + sine = [ int(32767 * sin(2 * pi * frequency * i / sampling_rate)) \ for i in range(size)] - + if channels > 1: sine = list(itertools.chain.from_iterable(itertools.repeat(x, channels) for x in sine)) return struct.pack(str(size * channels) + pack_format, *sine) - + class SinePlayer(Thread): - + def __init__(self, frequency = 440.0): Thread.__init__(self, daemon=True) self.device = alsaaudio.PCM(channels=channels, format=format, rate=sampling_rate) @@ -75,7 +75,7 @@ class SinePlayer(Thread): buf = generate(f) self.queue.put(buf) - + def run(self): buffer = None while True: @@ -86,7 +86,7 @@ class SinePlayer(Thread): if buffer: if self.device.write(buffer) < 0: print("Playback buffer underrun! Continuing nonetheless ...") - + isine = SinePlayer() isine.start() diff --git a/playbacktest.py b/playbacktest.py index 8551fe8..a102974 100755 --- a/playbacktest.py +++ b/playbacktest.py @@ -51,4 +51,4 @@ if __name__ == '__main__': print("Playback buffer underrun! Continuing nonetheless ...") data = f.read(320) out.close() - + diff --git a/recordtest.py b/recordtest.py index f84865d..3e92533 100755 --- a/recordtest.py +++ b/recordtest.py @@ -40,7 +40,7 @@ if __name__ == '__main__': f = open(args[0], 'wb') - # Open the device in nonblocking capture mode in mono, with a sampling rate of 44100 Hz + # Open the device in nonblocking capture mode in mono, with a sampling rate of 44100 Hz # and 16 bit little endian samples # The period size controls the internal number of frames per period. # The significance of this parameter is documented in the ALSA api. @@ -49,8 +49,8 @@ if __name__ == '__main__': # This means that the reads below will return either 320 bytes of data # or 0 bytes of data. The latter is possible because we are in nonblocking # mode. - inp = alsaaudio.PCM(alsaaudio.PCM_CAPTURE, alsaaudio.PCM_NONBLOCK, - channels=1, rate=44100, format=alsaaudio.PCM_FORMAT_S16_LE, + inp = alsaaudio.PCM(alsaaudio.PCM_CAPTURE, alsaaudio.PCM_NONBLOCK, + channels=1, rate=44100, format=alsaaudio.PCM_FORMAT_S16_LE, periodsize=160, device=device) loops = 1000000