RAWREC(1)RAWREC(1)NAMErawrec - buffered raw audio recording/playing
SYNOPSISrawrec [option]... [file]
rawplay [option]... [file]
DESCRIPTIONrawrec 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 val‐
ues arrived at after all overwriting and toggling is finished. This
arrangement allows full customization via alias or shell variable mech‐
anisms 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 chan‐
nels. 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 record‐
ing 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 raw‐
play 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 sup‐
plying 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 exe‐
cution 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 HANDLINGrawrec 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 rea‐
sonable way to handle it until Linux Threads become fully POSIX confor‐
mant 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 irri‐
tating 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 chan‐
nels. 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 cor‐
rectly (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
SEE ALSOaumix(1), cdrecord(1), sox(1)COPYRIGHT
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 MER‐
CHANTABILITY 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)
04 Jan 2006 RAWREC(1)
