RAWREC manual page
Table of Contents
rawrec - buffered raw audio recording/playing
rawrec [option]... [file]
rawplay [option]... [file]
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.
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.
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.
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.
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.
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).
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
aumix(1), cdrecord(1), sox(1)
rawrec/rawplay are Copyright (C) 2006 Britton Leo Kerin
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.
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.
Britton Leo Kerin (fsblk@aurora.alaska.edu)