pcm.rar_interface_pcm

/** * \file pcm/pcm.c * \ingroup PCM * \brief PCM Interface * * * PCM Interface is designed to write or read digital audio frames. A * frame is the data unit converted into/from sound in one time unit * (1/rate seconds), by example if you set your playback PCM rate to * 44100 you'll hear 44100 frames per second. The size in bytes of a * frame may be obtained from bits needed to store a sample and * channels count. * * See the \ref pcm page for more details. */ /* * PCM Interface - main file * Copyright (c) 1998 by Jaroslav Kysela <[email protected]> * Copyright (c) 2000 by Abramo Bagnara <[email protected]> * * This library is free software; you can redistribute it and/or modify * it under the terms of the GNU Lesser General Public License as * published by the Free Software Foundation; either version 2.1 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public * License along with this library; if not, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * */ /*! \page pcm PCM (digital audio) interface <P>Although abbreviation PCM stands for Pulse Code Modulation, we are understanding it as general digital audio processing with volume samples generated in continuous time periods.</P> <P>The analog signal is recorded via analog to digital converters (ADC). The digital value (de-facto a volume at a specific time) obtained from ADC can be further processed. The following picture shows a perfect sinus waveform:</P> <BR> \image html wave1.gif <P>Next image shows digitized representation:</P> <BR> \image html wave2.gif <P>As you may see, the quality of digital audio signal depends on the time (recording rate) and voltage resolution (usually in an linear integer representation with basic unit one bit).</P> <P>The stored digital signal can be converted back to voltage (analog) representation via digital to analog converters (DAC).</P> <P>One digital value is called sample. More samples are collected to frames (frame is terminology for ALSA) depending on count of converters used at one specific time. One frame might contain one sample (when only one converter is used - mono) or more samples (for example: stereo has signals from two converters recorded at same time). Digital audio stream contains collection of frames recorded at boundaries of continuous time periods.</P> \section pcm_general_overview General overview ALSA uses the ring buffer to store outgoing (playback) and incoming (capture, record) samples. There are two pointers being maintained to allow a precise communication between application and device pointing to current processed sample by hardware and last processed sample by application. The modern audio chips allow to program the transfer time periods. It means that the stream of samples is divided to small chunks. Device acknowledges to application when the transfer of a chunk is complete. \section pcm_transfer Transfer methods in UNIX environments In the UNIX environment, data chunk acknowledges are received via standard I/O calls or event waiting routines (poll or select function). To accomplish this list, the asynchronous notification of acknowledges should be listed here. The ALSA implementation for these methods is described in the \ref alsa_transfers section. \subsection pcm_transfer_io Standard I/O transfers The standard I/O transfers are using the read (see 'man 2 read') and write (see 'man 2 write') C functions. There are two basic behaviours of these functions - blocked and non-blocked (see the O_NONBLOCK flag for the standard C open function - see 'man 2 open'). In non-blocked behaviour, these I/O functions never stops, they return -EAGAIN error code, when no data can be transferred (the ring buffer is full in our case). In blocked behaviour, these I/O functions stop and wait until there is a room in the ring buffer (playback) or until there are a new samples (capture). The ALSA implementation can be found in the \ref alsa_pcm_rw section. \subsection pcm_transfer_event Event waiting routines The poll or select functions (see 'man 2 poll' or 'man 2 select' for further details) allows to receive requests/events from the device while an application is waiting on events from other sources (like keyboard, screen, network etc.), too. \ref snd_pcm_poll_descriptors can be used to get file descriptors to poll or select on (note that wait direction might be diferent than expected - do not use only returned file descriptors, but handle events member as well - see \ref snd_pcm_poll_descriptors function description for more details and \ref snd_pcm_poll_descriptors_revents for events demangling). The implemented transfer routines can be found in the \ref alsa_transfers section. \subsection pcm_transfer_async Asynchronous notification ALSA driver and library knows to handle the asynchronous notifications over the SIGIO signal. This signal allows to interrupt application and transfer data in the signal handler. For further details see the sigaction function ('man 2 sigaction'). The section \ref pcm_async describes the ALSA API for this extension. The implemented transfer routines can be found in the \ref alsa_transfers section. \section pcm_open_behaviour Blocked and non-blocked open The ALSA PCM API uses a different behaviour when the device is opened with blocked or non-blocked mode. The mode can be specified with \a mode argument in #snd_pcm_open() function. The blocked mode is the default (without #SND_PCM_NONBLOCK mode). In this mode, the behaviour is that if the resources have already used with another application, then it blocks the caller, until resources are free. The non-blocked behaviour (with #SND_PCM_NONBLOCK) doesn't block the caller in any way and returns -EBUSY error when the resources are not available. Note that the mode also determines the behaviour of standard I/O calls, returning -EAGAIN when non-blocked mode is used and the ring buffer is full (playback) or empty (capture). The operation mode for I/O calls can be changed later with the #snd_pcm_nonblock() function. \section pcm_async Asynchronous mode There is also possibility to receive asynchronous notification after specified time periods. You may see the #SND_PCM_ASYNC mode for #snd_pcm_open() function and #snd_async_add_pcm_handler() function for further details. \section pcm_handshake Handshake between application and library The ALSA PCM API design uses the states to determine the communication phase between application and library. The actual state can be determined using #snd_pcm_state() call. There are these states: \par SND_PCM_STATE_OPEN The PCM device is in the open state. After the #snd_pcm_open() open call, the device is in this state. Also, when #snd_pcm_hw_params() call fails, then this state is entered to force application calling #snd_pcm_hw_params() function to set right communication parameters. \par SND_PCM_STATE_SETUP The PCM device has accepted communication parameters and it is waiting for #snd_pcm_prepare() call to prepare the hardware for selected operation (playback or capture). \par SND_PCM_STATE_PREPARE The PCM device is prepared for operation. Application can use #snd_pcm_start() call, write or read data to start the operation. \par SND_PCM_STATE_RUNNING The PCM device has been started and is running. It processes the samples. The stream can be stopped using the #snd_pcm_drop() or #snd_pcm_drain() calls. \par SND_PCM_STATE_XRUN The PCM device reached overrun (capture) or underrun (playback). You can use the -EPIPE return code from I/O functions (#snd_pcm_writei(), #snd_pcm_writen(), #snd_pc