RAWREC(1)
RAWREC(1)



NNAAMMEE
       rawrec - buffered raw audio recording/playing


SSYYNNOOPPSSIISS
       rraawwrreecc [option]... [file]

       rraawwppllaayy [option]... [file]


DDEESSCCRRIIPPTTIIOONN
       _r_a_w_r_e_c  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.

       _r_a_w_p_l_a_y 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.

OOPPTTIIOONNSS
       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.

       _S_E_C_S arguments can have fractional parts,
       all other numerical arguments need to be integral.

       --BB _S_I_Z_E,
       ----rriinngg--bbuuffffeerr--ssiizzee=_S_I_Z_E
              explicitly  sets  the size of the big ring buffer
              to _S_I_Z_E 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c _C_H_A_N_N_E_L_S,
       ----cchhaannnneellss=_C_H_A_N_N_E_L_S
              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d _D_E_V_I_C_E,
       ----aauuddiioo--ddeevviiccee=_D_E_V_I_C_E
              use _D_E_V_I_C_E instead of the default
              /dev/dsp  to  record  from  or play to.

       --ee _S_E_C_S,
       ----eenndd--rreeccoorrdd--ttiimmee=_S_E_C_S
              directs  rawrec to put _S_E_C_S 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 _r_a_w_r_e_c 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e and --EE
              are specified, the one which will result in more
              silent  data  being  recorded will be used.
              The default is 0.

       --EE _S_A_M_P_S,
       ----eenndd--rreeccoorrdd--ssaammpplleess=_S_A_M_P_S
              directs rawrec to put _S_A_M_P_S 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e , above.
              The default is 0.

       --ff _F_M_T,
       ----ssaammppllee--ffoorrmmaatt=_F_M_T
              sets the format to be used for the samples for
              individual  chan‐ nels.  _F_M_T may be
              one of the following strings:

                 ss1166__llee      Signed 16 bit
                 little endian.

                 ss1166__bbee      Signed 16 bit
                 big endian.

                 uu1166__llee      Unsigned 16 bit
                 little endian.

                 uu1166__bbee      Unsigned 16 bit
                 big endian.

                 ss88          Signed eight bit.

                 uu88          Unsigned eight bit.

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

       --gg _F_R_A_G___S_Z,
       ----ffrraaggmmeenntt--ssiizzee=_F_R_A_G___S_Z
              explicity sets the kernel audio buffer fragment
              size to  _F_R_A_G___S_Z 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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p or --PP ) or end ( --zz or --ZZ )
              of execution.  This toggle starts off.

       --jj _S_E_C_S,
       ----ssttaarrtt--jjuummpp--ttiimmee=_S_E_C_S
       directs
              rawplay  to  skip  the first _S_E_C_S
              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j and --JJ
              are given, the one which will result in more
              data being skipped is used.  The default is 0.

       --JJ _S_A_M_P_S,
       ----ssttaarrtt--jjuummpp--ssaammpplleess=_S_A_M_P_S
              directs rawplay to skip the first _S_A_M_P_S
              samples of data it sees.  In other respects,
              this option works in the same  way  as  --jj
              , above.  The default is 0.

       --pp _S_E_C_S,
       ----ssttaarrtt--ppaauussee--ttiimmee=_S_E_C_S
              directs  rawrec/rawplay to sleep for
              _S_E_C_S 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h toggle is on.  If both
              --pp and --PP are specified, the one which
              will  result in a longer pause will be used.
              The default is 0.

       --PP _S_A_M_P_S,
       ----ssttaarrtt--ppaauussee--ssaammpplleess=_S_A_M_P_S
              directs  rawrec/rawplay  to  sleep  for
              the  time that would be required to play
              _S_A_M_P_S samples worth of data  (at  the
              sampling rate  specified).   In  other respects,
              this option works in the same way as --pp
              , above.  The default is 0.

       --rr _S_E_C_S,
       ----ssttaarrtt--rreeccoorrdd--ttiimmee=_S_E_C_S
       directs
              rawrec to put _S_E_C_S 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r  and --RR  are specified,
              the one which will result is more silent data
              being recorded will be used.  The default is 0.

       --RR _S_A_M_P_S,
       ----ssttaarrtt--rreeccoorrdd--ssaammpplleess=_S_A_M_P_S
              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r , above.  The default is 0.

       --ss _S_P_E_E_D,
       ----ssaammpplliinngg--rraattee=_S_P_E_E_D
              sets the sampling rate to _S_P_E_E_D samples
              per  second.   Generally _S_P_E_E_D  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 _S_P_E_E_D, use the --vv option.
              The default is 44100.

       --tt _S_E_C_S,
       ----ttiimmee--lliimmiitt==_S_E_C_S
              directs rawrec/rawplay to play or record
              _S_E_C_S seconds  worth  of data.
              If  neither  --tt nor --T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t and
              --T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j oorr --J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T _S_A_M_P_S,
       ----ssaammppllee--lliimmiitt==_S_A_M_P_S
              directs  rawrec/rawplay to play or record
              _S_A_M_P_S samples worth of data.  In all
              other respects this option works like --tt
              , above.

       --vv, ----vveerrbboossee
              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z _S_E_C_S,
       ----eenndd--ppaauussee--ttiimmee==_S_E_C_S
              directs rawrec/rawplay to sleep for _S_E_C_S
              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h toggle is on.  If both
              --pp and --PP  are specified,  the  one
              which will result in a longer pause will be used.
              The default is 0.

       --ZZ _S_A_M_P_S,
       ----eenndd--ppaauussee--ssaammpplleess==_S_A_M_P_S
              directs rawrec/rawplay to sleep  for  the
              time  that  would  be required  to  play
              _S_A_M_P_S samples worth of data (at the
              sampling rate specified).  In other respects,
              this option  works  in  the same way as --pp
              , above.  The default is 0.


UUSSIINNGG RRAAWWRREECC//RRAAWWPPLLAAYY
TTOO OORR FFRROOMM SSTTAANNDDAARRDD IIOO
       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.


SSIIGGNNAALL HHAANNDDLLIINNGG
       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  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.


RREESSOOUURRCCEESS
       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.


DDIIAAGGNNOOSSTTIICCSS
       rawrec/rawplay will complain and die on a variety
       of  resource  errors.  If the --v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).


EEXXAAMMPPLLEESS
       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

SSEEEE AALLSSOO
       aauummiixx(1), ccddrreeccoorrdd(1),
       ssooxx(1)


CCOOPPYYRRIIGGHHTT
       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.


BBUUGGSS
       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.


AAUUTTHHOORR
       Britton Leo Kerin (fsblk@aurora.alaska.edu)



                                  04 Jan 2006
                                  RAWREC(1)
