tones(1)                      Linux System Manual                     tones(1)



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  mix
       tures  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 wave
       form), 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  immedi
       ately preceding note is B2! The first Octave is from C0 to C1.

       Several frequencies/notes can be played at once, by specifying the fre
       quencies/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 (',') seperated 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 fre
       quencies 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 com
              mand 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 buf
              fers. This forces subsequant  generation  of  multiple  frequen
              cies/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 sig
       nal accuracy.

       The dB levels indicate the relative power levels.  -3dB being at a rel
       ative 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 spec
       ify -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  out
       put 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  speci
       fied.  If  you have a mixture of 3Hz and 5Hz samples, then the frequen
       cies generated will be a mixture of 3 and 5 times the frequency  speci
       fied. 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 frequen
              cies) 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 speci
              fications are actioned before the input file is read.

       -l     play the tone sequence repetitively. Forced off if writing  sam
              ples 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  con
              tains  details  of whether the data is 8 or 16 bits and the sam
              pling 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 interupted.

       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 ampli
              tude 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 wave
              form called trap and then plays 1 seconds each of first a 1000Hz
              triangle wave, then a 500Hz trap waveform and finally both wave
              forms 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), sgen(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 per
       mission notice identical to this one.

       Permission is granted to copy and distribute translations of this  man
       ual into another language, under the above conditions for modified ver
       sions, except that this permission notice may be included  in  transla
       tion instead of in the original English.

AUTHOR
       Jim Jackson

       Email: jj@franjam.org.uk



Release 2.3                       20 Feb 1998                         tones(1)
