Provided by: siggen_2.3.10-6build1_amd64 bug

NAME

       tones - a sequential tone generator program

SYNOPSIS

       tones [options] [waveform] T freq(s)|notes(s)|command_file(s)

DESCRIPTION

       tones  generates one or more tones of various types (waveforms) and duration (T millisecs)
       of the specified frequencies or notes, or mixtures of frequencies or notes.  See  tones -h
       for  a  list  of possible waveforms. The waveforms should include sine, cosine (90 degrees
       out of phase to sine), square (50% mark/space ratio), sawtooth (a ramp waveform), triangle
       and  noise.   Sine  is the default. Besides the inbuilt waveforms, waveforms can be loaded
       from suitable WAV files - see below LOADABLE WAVEFORMS.

       T is the default number of  millisecs  that  each  tone  is  to  be  played.   Frequencies
       (freq(s))  are  specified  in  Hertz  as  integers. A frequency of 0 causes T millisecs of
       silence to be played. Notes are specified as the musical note letter with an optional  '#'
       to  sharpen  the note, then an octave number. Octaves run from C to C. Middle C is C3, the
       immediately preceding note is B2! The first Octave is from C0 to C1.

       Several frequencies/notes can be played  at  once,  by  specifying  the  frequencies/notes
       required joined by a ',' character (but no spaces!).

       e.g.   1000,1500,2000 specifies that the three frequencies are played together, all at the
       same relative level. See AMPLITUDES sections below for a discussion of how to set absolute
       amplitude levels or differing relative amplitudes for notes played together or serially.

       Each freq specification can optionally contain a duration, by appending ':T', where 'T' is
       the duration in millisecs. This duration overrides the default. Also the default  duration
       can be changed by using a the ':T' format on it's own - not appended to a freq spec.

       e.g.  1200,600:1000 play the two freqs for 1 sec

       e.g.  c3,e3,g3 play the C major chord

       e.g.  :250 set the default tone duration to 250ms

       Waveforms  can  be  specified/altered  at  anytime.  A single waveform name specifies that
       waveform to be used for all channels.  Alternatively  a  comma  (',')  separated  list  of
       waveforms  can  be  given  to  specify  or  alter the waveform to use for a given channel.
       Ommitting a waveform in a list, means that the previous waveform is left unchanged.

       e.g.  square,,triangle specifies using square waves for chan 1, chan 2 is left  unchanged,
       and triangular waves are used for channel 3.

       The  digital  samples  (either  8  or 16 bits) are played by default to the Linux /dev/dsp
       device at a samplerate of 22050 samples per second, in mono mode. (see CONFIGURATION FILES
       section below)

       Fractional Hertz frequencies are not supported. Of course, only frequencies less than half
       the samplerate (number of samples/sec)  can  be  accurately  generated;  but  the  program
       doesn't check this.

       Instead  of  playing  the  output  to /dev/dsp the samples can be written to a file as raw
       samples (-o file) or written in WAV format (-w wavfile). These  data  files  can  then  be
       played back quickly with a raw data or WAV file player (e.g. wavplay) without the overhead
       of actually generating the samples.

       There are some special 'commands' that can be specified,  that  may  be  useful  in  input
       files.

       N      Set default tone duration to N millisecs

       @N     Set base amplitude level of tones when in absolute amplitude mode

       absolute
              Set absolute amplitude mode (see below)

       echo   The  rest  of the line of the input file, or the rest of the command line parameter
              (NB to use quotes where necessary) is output to stdout.

       relative
              Set relative amplitude mode (see below)

       reset|resync
              All generator points are reset to the start of the waveform  buffers.  This  forces
              subsequant generation of multiple frequencies/waveforms to be in phase.

       Further,  if  the word is not one of the above, then tones checks to see if a file of that
       name exists, and if it does then the file is assumed to be a file of tones commands  which
       are executed.

       e.g.   tones -v :100 tune1 tune2      will  interpret and play the tones commands in files
       tune1 and tune2.  This file processing is recursive. Files of commands can  execute  other
       files of commands etc. As usual, '-' can be used to specify stdin.

RELATIVE AMPLITUDES

       tones  by  default works in a 'relative' amplitude mode, where the output level and sample
       range are maximally maintained. This ensures the best signal accuracy.

       When specifying multiple frequencies/notes  to  be  played  together,  then  the  relative
       amplitudes can be specified in deciBells by appending "@db" to the note.

       e.g.   440,880@-12,1760@-30  specifies  a  mixture with 880Hz -12dB down, and 1760Hz -30dB
       down relative to the level of 440Hz. The mixed signal samples will span the full 16  or  8
       bit range permitted for maximal signal accuracy.

       The dB levels indicate the relative power levels.  -3dB being at a relative power level of
       0.5, -20dB being at a relative power level of 0.01 . However power levels are proportional
       to  the square of the signal amplitude. So a signal at -6dB (quarter power) will only have
       its amplitude down by half. To reduce a signal amplitude by 1/10 then specify -20dB,  i.e.
       a power level down by a factor of a hundredth.

       dB levels can be specified as decimal values.

ABSOLUTE AMPLITUDES

       tones  can  work in an absolute amplitude mode, where signal power levels are specified in
       deciBells (dB) relative to a 0dB level that indicates a peak value of +32767/-32768 for 16
       bit signed samples, and 255/0 for 8 bit unsigned values. Hence any signal at a positive dB
       level will be clipped. Signals at a negative dB level will attentuated.  If  no  level  is
       specified then 0dB is assumed.

       e.g.   500@-20,750@-6,1000,-12  gives  500Hz  at  -20db  (amplitude  0.1),  750Hz  at -6db
       (amplitude 0.5), and 1000Hz at -12dB (amplitude 0.25). The final mixed signal will have an
       amplitude of 0.1 + 0.5 + 0.25 = 0.85 or -1.4dB.

       As  can  be  seen,  there is no "hands-free" in absolute mode. You have to work out the dB
       levels yourself and ensure that the resultant mixed signal does not go above 0dB  and  get
       clipped.  Remember  also  that  a sine wave at -80dB down (amplitude 1/10000th) only has 6
       digital levels and is a pretty poor representation of a sine wave, not suitable  for  post
       amplification and use!

       In  absolute  mode  the  base  'zero'  level  can be altered at any time by use of the @dB
       command. All subsequent dB levels specified will have this base level added to them.

       e.g.  @-20 1000,1200@+6,1400@-6 is the same as 1000Hz at -20dB, 1200Hz at -14dB and 1400Hz
       at -26dB.

LOADABLE WAVEFORMS

       Given  that the generation method used by tones to generate a waveform of FHz is simply to
       sequentially select every Fth sample from a buffer containing S samples  of  one  complete
       waveform  at  a  frequency  of  1Hz  (treating  the  buffer  as  circular,  the  beginning
       conceptually joined to the end), where S is the  number  of  samples  per  second,  it  is
       possible  to  load a customised waveform from a WAV file containing the S samples of a 1Hz
       waveform. See the -load WavFile and -lw N options below. The name of the waveform is taken
       as the basename of the WavFile, i.e. with any trailing '.suffix' and leading path removed.
       Each loaded waveform should hence have this name unique, and different  from  the  inbuilt
       waveform names.

       The  samples  in  WavFile  should be 16 bit, mono, of the same number of samples as tones'
       playing samplerate, e.g. if tones is playing at 32000 samples per  sec  then  the  WavFile
       should  contain  32000  16  bit  samples.  16  bit samples are needed, because tones works
       internally with 16 bit samples, even if it is feeding 8 bit samples to the sound  card  or
       output  file.  Ideally  the  samples should span one complete wavelength, i.e. represent 1
       second of a 1Hz signal.  However this can be varied if used with  some  intelligence.  If,
       say,  1  seconds worth of 5Hz of the waveform is used, then the output frequency will be 5
       times higher than specified. If you have a mixture  of  3Hz  and  5Hz  samples,  then  the
       frequencies  generated  will be a mixture of 3 and 5 times the frequency specified. I hope
       that is all understandable!

       See the tones.eg directory for some examples of loadable modules and how tones itself  can
       be used to generate the loadable waveforms.

OPTIONS

       -8 | -b 8
              set 8 bit unsigned data samples

       -16 | -b 16
              set 16 bit signed little-endian data samples.

       -abs|-absolute
              set absolute amplitude mode

       -a     when used in conjunction with the -o option, data is appended to the file.

       -C file
              use "file" as the local configuration file (see below).

       -c CHANNELS
              set the maximum number of channels (concurrent played frequencies) to CHANNELS. The
              default number is 4. There is some virtue in keeping the number of  channels  to  a
              minimum.

       -f     when  used  in conjunction with the -o or -w options, any existing file is silently
              overwritten.

       -h     display usage and help info

       -i file
              read frequencies/waveforms to generate from file 'file'.  Reads from standard input
              if  filename  is '-'. Any command line specifications are actioned before the input
              file is read.

       -l     play the tone sequence repetitively. Forced off if writing samples to a  file  with
              the -o or -w options.

       -loop N
              play the tone sequence N times.

       -o file
              write  out  samples  to a raw data file. You will have to remember the data format,
              e.g. samplerate and 8/16 bit.

       -rel|-relative
              set relative amplitude mode

       -s samplerate
              set the number of samples  per  second  to  samplerate.  For  many  simple  uses  a
              samplerate of 8000 is sufficient, making any saved data files smaller.

       -w wavfile
              write  samples  out  in  WAV  format to wavfile. The WAV header contains details of
              whether the data is 8 or 16 bits and the sampling rate. You cannot use  the  append
              (-a) option with WAV files.

       -v     be verbose

       -lw N  Specify the number of loadable waveforms allowed, the default is 4

       -load WavFile
              Load the waveform from the WavFile.

EXAMPLES

       tones 50 1000 700,1200 800,1100,1300
              generates  3  50  millisecs  sine  tones,  the first consisting of only 1000Hz, the
              second of 700Hz and 1200Hz and the third of 800Hz, 1100Hz and 1300Hz

       tones -loop square 200 700 900 400 500
              generates a sequence of 4 200 millisecs square wave tones which is  repeated  until
              the program is interrupted.

       tones -w seq.wav 70 1016 1200 1080 1150 1016
              generates  a sequence of 5 70 millisecs sine tones, and instead of playing them the
              samples are stored in WAV format in seq.wav which can be played  by  any  WAV  file
              player.

       tones -w trap.wav :1000 triangle absolute 1@6
              Generates a WAV file trap.wav consisting of a trapezoid waveform where the rise and
              fall slopes take up half the wavelength. A sawtooth is  generated  with  a  maximum
              that  has  twice  the  amplitude  of  the maximum sample sizes allowed, hence it is
              clipped flat for half the waveform period making a trapezoid shape.

       tones -load trap.wav :1000 triangle 1000 trap 500 triangletrap 1000500
              Will load the trapezoid waveform generated above as a new waveform called trap  and
              then  plays  1  seconds  each  of  first  a 1000Hz triangle wave, then a 500Hz trap
              waveform and finally both waveforms played together.

       See also the tones.eg directory in the siggen distribution.

CONFIGURATION FILES

       Three possible configuration files can be used: a LOCAL config file  (usually  in  current
       directory), a HOME config file in user's $HOME directory and a GLOBAL config file.

       All the siggen suite of programs are compiled with the names of the config files built in.
       By default the configuration files are:

       ./.siggen.conf
              is the LOCAL config file.

       $HOME/.siggen.conf
              is the HOME config file.

       /etc/siggen.conf
              is the GLOBAL config file.

       tones -h
              will indicate which config files will be searched for.

       The config files do not have to exist. If they exist and are readable by the program  they
       are used, otherwise they are simply ignored.

       The  config  files  are always searched for configuration values in the order LOCAL, HOME,
       GLOBAL. This allows a scheme where the sysadmin sets  up  default  config  values  in  the
       GLOBAL  config  file,  but  allows a user to set some or all different values in their own
       HOME config file, and to  set  yet  more  specific  values  when  run  from  a  particular
       directory.

       If  no configuration files exist, the program provides builtin default values, and most of
       these values can be set by appropriate command line switches and flags.

       See siggen.conf(5) for details of the configuration files.

       tones looks for configuration values CHANNELS, DACFILE, SAMPLERATE,  SAMPLESIZE,  VERBOSE,
       LOADABLE_WAVEFORMS.

       CHANNELS
              sets the number of channels, see '-c' option.

       DACFILE
              allows the name of the DAC/DSP/PCM device to be changed from /dev/dsp

       LOADABLE_WAVEFORMS
              specifies the allowable number of loadable waveforms

       SAMPLERATE
              sets the number of samples/sec for the DAC device

       SAMPLESIZE
              sets whether 8 or 16 bit samples to be generated

       VERBOSE
              sets whether or not to run in verbose mode.

SEE ALSO

       siggen.conf(5), signalgen(1), swgen(1)

BUGS


COPYING

       Copyright 1995-2008 Jim Jackson

       The  software  described  by  this  manual  is  covered by the GNU General Public License,
       Version 2, June 1991, issued by :

              Free Software Foundation, Inc.,
              675 Mass Ave,
              Cambridge, MA 02139, USA

       Permission is granted to make and distribute verbatim copies of this manual  provided  the
       copyright notice and this permission notice are preserved on all copies.

       Permission  is  granted  to copy and distribute modified versions of this manual under the
       conditions for verbatim copying, provided  that  the  entire  resulting  derived  work  is
       distributed under the terms of a permission notice identical to this one.

       Permission  is  granted  to  copy  and distribute translations of this manual into another
       language, under the above conditions for modified versions, except  that  this  permission
       notice may be included in translation instead of in the original English.

AUTHOR

       Jim Jackson

       Email: jj@franjam.org.uk