NAME

rawrec - buffered raw audio recording/playing

SYNOPSIS

rawrec [option]... [file]

rawplay [option]... [file]

DESCRIPTION

rawrec reads raw audio data from a digital signal processor (DSP) and writes it to the given file, or to standard output if no file is given.

rawplay reads raw audio data from the given file, or from standard input if no file is given, and writes it to a DSP.

The user of this program will almost certainly want some program to set the mixer device parameters for their sound card, rawrec/rawplay don't make any attempt to do so.

OPTIONS

There are many options, but most users will probably only be interested in -t, -s, -f, -c, and possibly -v. Options may appear multiple times; those without arguments act as toggles, those with arguments have the values of their arguments overwritten by successive occurences. Any option requiring an argument may be given the special argument 'dflt', which restores the default behavior (causes rawrec/rawplay to behave exactly as if that option had not yet appeared on the command line at all). When options interact, the interaction is between the final values arrived at after all overwriting and toggling is finished. This arrangement allows full customization via alias or shell variable mechanisms without any sacrifice in flexibility.

In the following discussion, unless otherwise noted, the term "sample" is taken to mean one full set of digitized bits_per_sample-bit values, one for each channel. For example, when recording stereo (2 channel) sound in a 16 bit format, one full sample is 32 bits long.

SECS arguments can have fractional parts, all other numerical arguments need to be integral.

-B SIZE, --ring-buffer-size=SIZE: explicitly sets the size of the big ring buffer to SIZE bytes. This may be useful if the machine is heavily loaded or doesn't have a lot of physical memory. If you don't know what this is about you should probably not bother with this option. The default is 2 megabytes.
-c CHANNELS, --channels=CHANNELS: sets the number of channels. Currently, only mono (1 channel) and stereo (2 channel) modes are supported. In 2 channel mode, left channel data always precedes right channel data. The default is 2 channels.
-d DEVICE, --audio-device=DEVICE: use DEVICE instead of the default /dev/dsp to record from or play to.
-e SECS, --end-record-time=SECS: directs rawrec to put SECS seconds of silence at the end of the recording run. Note that this silent padding is added virtually instantaneously, and has little or no impact on the wall clock time rawrec takes to run. If rawrec is interrupted by a signal before the recording run is finished, this silence will never get added. This option is only applicable to rawrec, and is ignored if given to rawplay. If both -e and -E are specified, the one which will result in more silent data being recorded will be used. The default is 0.
-E SAMPS, --end-record-samples=SAMPS: directs rawrec to put SAMPS samples of silence at the end of the recording run. A sample consists of bits_per_sample * channels / 8 bytes of data. In other respects, this option works in the same way as -e , above. The default is 0.
-f FMT, --sample-format=FMT: sets the format to be used for the samples for individual channels. FMT may be one of the following strings:

s16_le Signed 16 bit little endian.

s16_be Signed 16 bit big endian.

u16_le Unsigned 16 bit little endian.

u16_be Unsigned 16 bit big endian.

s8 Signed eight bit.

u8 Unsigned eight bit.

Not all format are supported by all sound cards. The default is s16_le.

-g FRAG_SZ, --fragment-size=FRAG_SZ: explicity sets the kernel audio buffer fragment size to FRAG_SZ bytes. Smaller fragment sizes will result in lower latency, larger sizes will give better odds of getting smooth recording or playback under load. Note that the latency caused by the use of large block sizes may cause the overall run time to increase noticably, though the actual amount of data recorded will not change. Large fragment sizes also increase signal response latency in some cases. Modern kernel audio drivers do a fine job of picking a fragment size that results in smooth, low-latency audio for a given set of sampling parameters (sampling speed, bits per sample, and number of channels), the default behavior is to let it do so. If you know that you must set this option, it needs to be a power of two greater than or equal to 16.
-h: Hold the dsp device during the entire execution, even when it isn't strictly necesary. In particular, the audio device is held during any silent pausing that may occur at the beginning ( -p or -P ) or end ( -z or -Z ) of execution. This toggle starts off.
-j SECS, --start-jump-time=SECS directs: rawplay to skip the first SECS seconds worth of audio data in the argument data file or standard input. This option is only applicable to rawplay, and is ignored if given to rawrec. If both -j and -J are given, the one which will result in more data being skipped is used. The default is 0.
-J SAMPS, --start-jump-samples=SAMPS: directs rawplay to skip the first SAMPS samples of data it sees. In other respects, this option works in the same way as -j , above. The default is 0.
-p SECS, --start-pause-time=SECS: directs rawrec/rawplay to sleep for SECS seconds before recording or playing as specified by the other options. During this time, the audio dsp device is not held, unless the -h toggle is on. If both -p and -P are specified, the one which will result in a longer pause will be used. The default is 0.
-P SAMPS, --start-pause-samples=SAMPS: directs rawrec/rawplay to sleep for the time that would be required to play SAMPS samples worth of data (at the sampling rate specified). In other respects, this option works in the same way as -p , above. The default is 0.
-r SECS, --start-record-time=SECS directs: rawrec to put SECS seconds of silence at the beginning of the recording run. Note that this silent padding is added as fast as possible, and generally has little or no impact on the wall clock time rawrec takes to run. This option is only applicable to rawrec, and is ignored if given to rawplay. If both -r and -R are specified, the one which will result is more silent data being recorded will be used. The default is 0.
-R SAMPS, --start-record-samples=SAMPS: directs rawrec to put SAMPS samples of silence at the beginning of the recording run. In other respects, this option works in the same way as -r , above. The default is 0.
-s SPEED, --sampling-rate=SPEED: sets the sampling rate to SPEED samples per second. Generally SPEED will need to be a value between 8000 and 44100, but some cards may be able to handle sampling rates as low as 4000 or as high as 96000. Not all frequencies between the limits will be available, small adjustments will be made for you. If you want to determine exactly what frequency is being used when you request a given SPEED, use the -v option. The default is 44100.
-t SECS, --time-limit=SECS: directs rawrec/rawplay to play or record SECS seconds worth of data. If neither -t nor -T are specified, rawrec will record until interrupted or until its standard output breaks, and rawplay will play its entire argument file, or until its standard input ends. If both -t and -T are specified, the one which will result in more data being recorded or played will be used. If when playing a data file there is not enough data available to skip (with -j or -J ) and play the requested amount of data, the entire file will be played. If standard input ends without supplying sufficient data, an error will pe printed when the input ends. By default, there is no time limit, and execution will proceed until one of the above occurs.
-T SAMPS, --sample-limit=SAMPS: directs rawrec/rawplay to play or record SAMPS samples worth of data. In all other respects this option works like -t , above.
-v, --verbose: enables verbose errors and warnings. For example, when the exact sampling frequency requested is unavailable, and a nearby frequency is picked instead, there is no warning given unless verbose is on. This option is genally good to use when you need to know what's going on under the hood. This toggle starts off.
-z SECS, --end-pause-time=SECS: directs rawrec/rawplay to sleep for SECS seconds after recording or playing as specified by the other options. Note that if execution was interruped by a signal during the run, this pause will never be performed. During the pause, the audio dsp device is not held, unless the -h toggle is on. If both -p and -P are specified, the one which will result in a longer pause will be used. The default is 0.
-Z SAMPS, --end-pause-samples=SAMPS: directs rawrec/rawplay to sleep for the time that would be required to play SAMPS samples worth of data (at the sampling rate specified). In other respects, this option works in the same way as -p , above. The default is 0.

USING RAWREC/RAWPLAY TO OR FROM STANDARD IO

rawrec/rawplay can be used effectively in pipelines to act as the sound card interface for a wide variety of other programs. However, unlike many classical command line utilities, rawrec and rawplay place soft real time demands on the programs they connect to. There is no way for rawrec/rawplay to ensure that these programs will behave well in this capacity, or perform consistently if the system is heavily loaded.

SIGNAL HANDLING

rawrec and rawplay respond to most signals by aborting immediately. This means that anything that the command line invocation indicated should happen at the end of the run (silent padding with -e or -E, end pausing with -z or -Z) won't. The job control signal SIGTSTP (normally associated with terminal input Ctrl-Z) is ignored, as there is no reasonable way to handle it until Linux Threads become fully POSIX conformant with respect to signal handling. There can be a significant delay (like one second or more) between the time a process-terminating signal is delivered to a rawrec or rawplay process and the time that the threads spawned by that process finally die. This would only be irritating if it wasn't for the fact that the process in which the initial thread runs reports itself as having died immediatly, even though child threads are still happilly playing or recording away and hogging the dsp device. Special handling is in place for the SIGTERM and SIGINT signals which corrects this problem.

RESOURCES

rawrec/rawplay obviously needs access to a dsp device. It is best if the rawrec executable is installed setuid root; if it isn't, it can't lock down important parts of its memory space or modify the priority or scheduling policy of time critical threads, in other words, it can't provide any good gaurantee of decent performance if the system load is high or fluctuates. rawrec uses root authority only while doing the above things, and never uses strcpy at all.

DIAGNOSTICS

rawrec/rawplay will complain and die on a variety of resource errors. If the -v option is used, warnings will also be issued for a variety of non-fatal conditions of potential interest.

If when playing the ring buffer used to move data between the argument file or stdio and the audio device becomes empty, the audio output may halt momentarily, but this is not considered a fatal error.

rawrec always aborts immediately with a diagnostic if it finds that the ring buffer has become full.

If you are trying to play data from standard input, and rawplay dies complaining about 'too many empty ring buffer segments', it means that the standard input didn't provide enough data fast enough for rawplay to play at the requested rate, sample resolution, and number of channels. This could for example happen if you try to run some really expensive (normal gunzip works fine) decompression algorithm as the input to rawplay, or if the system load got heavy and caused a normally affordable decompression algorithm to get slow (since the decompression probably isn't running at elevated priority).

EXAMPLES

These examples assume that you have your mixer channels set up correctly (i.e. set up so that you can record from some live source and can audibly play back sampled streams).

Record CD quality (44100 sample per second, 2 channel signed 16 bit little endian) audio into foo.raw until interrupted:


     rawrec foo.raw

Record 100 seconds of half speed unsigned 8 bit mono data, and issue a warning if the sampling rate can't be set exactly as desired or some other unexpected thing happens:


     rawrec -t 100 -s 22050 -f u8 -c 1 -v bar.raw

Play back the data just recorded, at a speed that will make us sound like maniacal chipmunks (the point here being that rawrec and rawplay deal in raw data, its up to the user to make it make sense):


     rawplay -s 44100 -f u8 -c 1 -v bar.raw

Record some CD quality sound, then have the sox program pack it up as a .cdr file, ready for CD mastering with cdrecord or the like:


     rawrec -t 100 | sox -t sw -r 44100 -c 2 - -t cdr foobar.cdr

Play back the .cdr file:


     sox -t cdr foobar.cdr -t sw -r 44100 -c 2 - | rawplay -t 100

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

BUGS

When playing, if the exact sample rate can't be set as desired, the rate may get adjusted up, possibly causing there to suddenly not be enough data in the data file to play for the length of time and with the jump requested, even if the math on the command line is correct. This is not really a bug so much as an unfortunate consequence of sound card inconsistency. The use of -v can help explain this behavior.

The situation where the standard output of rawrec gets connected to the standard input of some really slow process has not been investigated properly.

AUTHOR

Britton Leo Kerin (fsblk@aurora.alaska.edu)