  NAME

  discord - Generate binaural, chronaural, or phase beats to 
  soundcard or file for use in brain wave entrainment.

  SYNOPSIS

  discord [flags] script_filename [script filename] ...
  discord [flags] {-l|--listfile=}filename [flags] [script filename] ...

  DESCRIPTION

  Discord is a command line program used to generate binaural, phase,
  and chronaural beats mixed with tones, noise, or sound files of the
  users choice.  The default is to play the files via the computer's
  sound card, but they can be written to an output file instead.  Only
  file formats available in libsndfile can be used as input or output.
  Those formats do not include mp3 at this time, and probably won't
  until the patents expire.  Some common formats available are wav,
  FLAC, ogg, au, aiff, and raw.  If an input sound file has a different
  sample rate than that selected for the output, it will automatically
  be resampled to the requested rate using the highest quality available
  in libsamplerate.  This can take a long time.  If you are going to use
  the same file again and again, a copy can be retained in the same
  directory as it was found with the new rate appended to the filename
  by specifying the -k/--keep option.

  While all of the options below can be used on the command line, the
  sequences to play must be defined in a script file.  Options on the
  command line override options in a script file.  Script files are
  named with a .discord extension by convention.  You can, however,
  use whatever name you want for your script files.  All of the
  options can also be set in a configuration file in your home
  directory called .discordrc.  This file contains options identical
  to those in a script file or on the command line.  The options found
  here have the lowest priority and will be overridden by either a
  script file or the command line.  There is a sample .discordrc
  included, so you can move it to your $HOME directory if you want.

  While discord is very complex, that is part of its purpose.  To
  allow the exploration of auditory beats in new ways, perhaps leading
  to greater efficacy or new effects.  It also means that there are
  bugs still lurking in the code because not all combinations have
  been tested.

  There are twelve voice types in discord.  These are binaural,
  chronaural, pulse (a variation of chronaural), phase, fm (a
  variation of phase or vice versa), bell, noise, stoch (stands for
  stochastic), sample, repeat, once, and silence.

  Voice type description

  binaural

  Generate a pair of tones separated by a beat frequency at a specific
  carrier frequency and amplitude.  Optionally vary the amplitude of
  the left and right channels at a specified frequency and by a
  specified percent.  Binaural tones are allowed to slide into the
  next binaural on carrier, beat, amplitude, amplitude beat, and
  amplitude beat variation amount.

  chronaural

  Generate a periodic tone at a specified frequency and amplitude.
  The period is the beat in this case.  In addition, the split or pan
  of the tone can be specified to vary between set values at a rate
  specified.  Chronaural tones are allowed to slide into the next
  chronaural on carrier, beat, amplitude, phase,split beat, and sin
  threshold.  You could think of these tones as equivalent to high
  tech drum beats, a method human beings have used to enter altered
  states of consciousness for thousands of years.

  pulse

  Generate a periodic tone at a specified frequency and amplitude.
  The period is the beat in this case.  In addition, the split or pan
  of the tone can be specified to vary between set values at a rate
  specified.  Pulse tones are allowed to slide into the next pulse on
  carrier, beat, amplitude, phase, time, and split beat.  The
  difference between this and chronaural is the way the duration is
  specified.  Unlike chronaural, where tone shape may be selected,
  pulse is fixed as using a square wave.  You could think of these
  tones as equivalent to high tech drum beats, a method human beings
  have used to enter altered states of consciousness for thousands of
  years.

  phase

  Generate a beat by shifting the phase of the carrier tone at a specified
  beat frequency and to a specified phase offset between 0 and a positive
  number of degrees.  Phase tones are allowed to slide into the next phase on
  carrier, beat, amplitude, phase, and split beat.  This uses the doppler
  effect to get the attention of the brain.  It seems like something is coming
  towards and going away from us.  The way it differs from fm is that there is
  always the drone of the original unshifted carrier also present in the sound
  stream.  The phase shifted tone is split between the channels as determined
  by the split requested.  The drone tone is split between channels in the
  conjugate of the shifted tone.  So each channel is always at the same
  amplitude, disregarding any effects of amplitude beat.

  fm

  Fm stands for frequency modulation.  Generate a beat by shifting the
  frequency at a specified beat frequency and to a specified frequency offset
  called the band.  Fm tones are allowed to slide into the next fm on carrier,
  beat, amplitude, band, phase, and split beat.  This uses the doppler effect
  to get the attention of the brain.  It seems like something is coming
  towards and going away from us.  Because the shift is determined by the
  frequency band, phase here means the phase difference between the channels,
  as both channels are shifted by the band amount.  Unlike phase, there is no
  drone of the original carrier here.


  bell

  Generate a tone at a specified frequency and amplitude.  The tone
  may be fixed periodic or occur at randomly generated times between
  selected upper and lower limits.  Decay or enhance for the tone can
  also be set.  Bells can interrupt each other before they are
  finished playing.  Bell voices are allowed to slide into the next voice 
  on min and max amplitude.

  noise

  Generate a group of tones within a specified frequency and amplitude
  range.  The tones may be fixed periodic or occur at randomly
  generated times between selected upper and lower limits.  Decay or
  enhance for the tone can also be set.  Noise tones don't interrupt
  each other before they are finished playing.  No slide is available
  for noise.  Noise voices are allowed to slide into the next voice on
  min and max amplitude.


  stoch

  Play a user supplied sound file at either fixed intervals or random
  intervals within specified times.  Pan and amplitude can vary for
  each play, or remain fixed depending on options specified.  Stoch
  voices are allowed to slide into the next voice on min and max
  amplitude.


  sample

  Play a randomly selected fixed time slices of a user supplied sound
  file continuously.  Pan and amplitude can vary with each sample or
  remain fixed, depending on the options specified.  Sample voices are
  allowed to slide into the next voice on min and max amplitude.


  repeat

  Play a user supplied sound file continuously.  Pan and amplitude can
  vary with each repeat or remain fixed, depending on the options
  specified.  Repeat voices are allowed to slide into the next voice
  on min and max amplitude.


  once

  Play a user supplied sound file once at a specified time.  Pan and
  amplitude can be randomly chosen or be fixed, depending on the
  options specified.

  silence

  Placeholder for voice and in scripts for synchronization.  As the
  name implies it does nothing.  It can't be used to slide to or from.

  All internal processing is done in double format so the tones are
  very precise. The user specified sound files are stored in memory
  for fast access while generating sound, so you should have lots of
  memory or use small sound files.  They are stored only once, no
  matter how many times they are used in the script file that
  specifies the time sequence.

  OPTIONS

  -a, --audio_device

    Specify the audio device to use for playback in alsa plug format.
    Discord will automatically create a plughw alsa plugin from the
    default audio device if this is not specified.  Discord uses alsa to
    do format conversion from internal program representation to what
    the card requires, but locks the sample rates to be only those
    supported by the card hardware.  This prevents resampling with
    consequent distortion and slowdown.  If you try to use a direct
    hardware link like "hw:0,0" here it will cause a segmentation fault.
    To implement direct hardware writing discord would have to
    incorporate all of the format conversion.  This seems
    counterproductive.  The first number is the card number, the second
    is the device number, both starting at 0.  See the alsa
    documentation at www.alsa-project.org for a fuller explanation.
    Default is plughw:0,0.  There can be issues here with pulseaudio, as
    it takes over the hardware and doesn't let any other application
    have it.  Because pulseaudio is becoming so integrated into the OS
    and GUI, I have resorted to having a sound device that I give to it.
    I then use the pulseaudio volume control to turn off the actual
    device I want to use with discord, so I can communicate directly
    with alsa.  In future, I might build in the ability to use
    pulseaudio, but I don't like the fact that it does on the fly rate
    conversion because it has to merge all the sound streams it uses.
    
    Examples
      --audio_device=plughw:0,0  
      -a plughw:0,2

  -b, --bit_accuracy

    bit accuracy of sound generated, 16i, 24i, 32i, 32f, 64f, i=int and
    f=float.  Only applies if you are sending to a file.  Default is
    16i.  For ogg, it is not necessary to specify this because it
    doesn't really have meaning there.  If you want to you can specify
    it as vorbus.  Note that older audio players might not be able to
    play anything but 16i.
    
    Examples
      --bit_accuracy=16i
      -b 24i

  -c, --compensate

    compensate for human hearing, low and high freqs need to be
    louder, max 32 adjustment points are allowed.  The compensation
    points can all be on the same line or on multiple lines, but each
    line must start with the option name.  If this is correct, a sound
    at the compensated frequency sounds the same loudness as any other
    sound at its compensated frequency.  i.e. It linearizes the range.
    This is individual, depends on your hearing, so the above is only
    a starting point for you to play with and tweak.  For most people,
    sounds from about 800 Hz to 4000 Hz are the loudest and about
    equivalent.  Hearing falls off at either end so that the amplitude
    has to be higher in order for the sound to have the same loudness
    to the ear.  There is dispute about whether sounds outside the
    range of hearing have any effect.  If you use compensation, set
    all amplitudes to a constant value for binaural, chronaural, bell,
    and noise.  Or whatever ratio between the loudness you want them
    to have, as if linear.  The stoch, sample, repeat, and once voices
    are not compensated so should be set at the amplitude you want.
    Default is no compensation.

    Examples  (see also the test script files)
      --compensate=5=9'''3000=1'''',13000=3,,,,20000=11.0
      -c 5=10'''2530=1''',13128=3.5,,,,20000=10.0

  -d, --display_only

    display only, don't actually play any sequences.  Default is play.

  -e, --every

    display status every x seconds, decimal value > 0.  If you use
    values that are too small here, you will get a lot of underruns.
    Small values are probably best by redirecting output to a file for
    future analysis.  e.g. discord test.discord > save.output 2>&1
    Make sure you also write the sound to a file using -b, -o, -w.
    Default is 5 seconds.

    Examples
      --every=10   
      -e 5.391

  -f, --fast

    fast, move through at multiple of time, 60 ==> 1min becomes 1 sec
    so a 1 hour play sequence will play in 1 minute.  Good for
    testing a new sequence for correctness, though obviously the
    effect won't be the same.  Bell has been tweaked so that the pitch
    doesn't change while using this.  Default is 1.

    Examples
      --fast=60
      -f 10

  -h, --help

    display short help list for options

  -k, --keep

    keep any files generated by resampling.  Default is to delete the
    files when they are no longer needed.

  -l, --listfile

    read this file as a list of discord script files.  It will then
    play each of these files in parallel.  The file can have relative
    paths or absolute paths for the included scripts.  Comments using
    hash marks, #, are allowed, as are blank lines.  A sample listfile
    is included in the scripts directory of the package, called
    sample.chorus.  You can mix these files with command line script
    files as well.  Options from script files in listfiles are not
    parsed however.  You should use either a .discordrc in your home
    directory or command line options, though you can just accept the
    defaults in the program.  By convention, these are named with a
    .chorus extension though that isn't necessary.

    Examples
      --listfile=/home/xkdi/discord_scripts/composition.chorus
      -l  /home/xkdi/discord_scripts/composition.chorus

  -m, --modify

    specify that every carrier and beat for binaural, chronaural,
    pulse, phase, and fm voices will be modified from the value in the
    input script.  The value is the percent band within which the
    random modification will occur, half above the input value, and
    half below.  For a carrier of 200 with a modification of 2 per
    cent, the modified value will be a random value between 198 and
    202.  For a beat of 4 with a modification of 1 per cent, the
    modified value will be a random value between 3.98 and 4.02.  The
    maximum modification is less than 200, which means a possible
    value somewhere between almost zero and twice the input.  This is
    a fast way to modify a script without editing.  Default is no
    modification.
    
    Examples 
      --modify=2 
      -m 0.5

  -o, --out_format

    output file format, w:wav, f:flac, r:raw, o:ogg.  Default is wav.

    Examples
      --out_format=w
      -o w

  -q, --quiet

    quiet, don't display status or any other output while running.
    Default is to display status every 5 seconds.

  -r, --rate

    frame rate per second, whatever your card can do, 44100 is CD
    quality.  Higher rates might be beneficial on binaurals at high
    frequencies, say 15000 Hz and above, or very low beats, < 0.1.
    For normal frequencies, 44100 will be just fine.  Note that higher
    rates won't do any harm, they will just make the cpu and sound
    card work harder.  From Nyquist theory, the sample rate has to be
    greater than equal to twice the highest frequency in the sound
    being played in order to reproduce it exactly.  Since human
    hearing theoretically maxes out for most people at 20 kHz and cd
    quality at 44100 frames/second allows up to 22 kHz perfect
    reproduction, this isn't really a problem if your sound card has a
    decent digital analog converter.  While discord is only pretending
    to sample and doesn't exactly meet the criteria, it should be
    within small tolerances of perfect.  I think the place where any
    change might be noticeable is dynamics.  If your sound card does
    internal processing in 16 bit integers, that allows a variation of
    32,767 gradations of amplitude.  You will lose a slight amount of
    exactness from the doubles that discord uses internally.  If your
    card uses 24 bit or 32 bit internally, any change from conversion
    will be unnoticeable.  Whatever the rate you select here, discord
    will use the closest hardware supported rate to prevent any
    resampling, a major source of distortion, far greater than effects
    from sample rate or bit representation of amplitude unless you are
    using a sample rate of 22 kHz or less or an 8 bit sound card.
    Default is 44100.
    
    Examples 
      --rate=44100 
      -r 96000

  -s, --shift

    specify that every carrier and beat for binaural, chronaural,
    pulse, phase, and fm voices will be shifted from the value in the
    input script.  The value is the percent of modification which will
    occur.  For a carrier of 200 with a shift of 2 per cent, the
    modified value will be 204.  For a beat of 4 with a modification
    of -1 per cent, the modified value will be 3.96.  The minimum
    shift is greater than -100, which means a possible value somewhere
    between almost zero and whatever positive value the computer will
    handle.  This is a fast way to shift a script in synchrony without
    editing.  Default is no shift.
    
    Examples 
      --shift=2 
      -s -.5

  -t, --thread

    use nonblocking thread to play sound instead of a blocking
    function call.  This allows more throughput, but because the
    thread runs with user priority, during heavy cpu usage it can
    result in breaks in the sound while other tasks block it.  The
    blocking function call is more robust in this situation.  Under
    light usage, either is fine.  This only affects threading for
    playing sound or writing sound to a file.  Default is no
    threading.

  -v, --verbose

    when writing a status line while playing, use the detailed format
    instead of the summary format that is the default. 

  -w, --write

    write to this file instead of the default, playing via sound
    card 0.  You can use this without setting the -b/--bit_rate and
    -o/--out_format variables, but you will then get the default of 16
    bit and wav format.

    Examples
      --write=/home/xkdi/mindbending.flac
      -w  /home/xkdi/mindblowing.wav

  -y, --vbr_quality

    specify the quality for an ogg vorbis output stream that is being
    written to file.  The allowable values are 0 to 1, floating point.
    A value of zero is approximately 64 Kbits/second and a value of 1 is
    approximately 500 Kbits/second.  If this isn't specified, a default
    value of .5 is used, corresponding to approximately 160
    Kbits/second.  Using -y because I am running out of letters.  Soon
    I'll have to go to long options only.  As stated, default is .5.
    
    Examples 
      --vbr_quality=.95 
      -y .3


  CONFIGURATION FILE

  You may optionally place a configuration file called .discordrc in
  your $HOME directory.  It may contain only options, in the same
  format as in a script file or on the command line.  These options
  will be overridden by a script file or the command line.  A sample
  is provided.


  SCRIPT FILE

  Any text after a # is disregarded, whether at the start of a line or
  after meaningful text.

  Options may be set in a script file, in fact it is easier to
  do so, but they must be before any time sequences in that file.

  A time sequence may span multiple lines, but a voice (binaural,
  bell, noise, etc.)  cannot be split across lines.

  Time Sequences

  A time sequence always starts with a duration in the format
  hh:mm:ss.  This may be followed with a fade indicator of less than
  sign "<" for fade in or greater than sign ">" for fade out. e.g.
  00:02:03''''< means to fade in for 2 minutes and 3 seconds.  The
  duration is followed by the voices that will play during that time
  period, each voice on its own line.
 
  Separators allowed are | , ; ' = and ascii space 0x20, multiples are
  allowed mixed with singles, any combination of separators even
  within a voice.  However, every voice must be joined by separators.
  No tabs are allowed.
  
  The greater than sign ">" after a binaural, chronaural, pulse,
  phase, or fm voice is a slide, and will continuously adjust fields
  that are allowed to slide for that voice so that they match the
  corresponding field's value at the start of the next binaural,
  chronaural, pulse, phase, or fm voice that they slide to.  For
  slides to work, the binaural, chronaural, pulse, phase, or fm voices
  must be in the same relative position in the time sequences.  There
  is no other way to know that there is a link between the voices.  So
  the first voice in the sequence will always look to the first voice
  in the next sequence to slide to, etc.  Only beat voices have the
  option to slide.

  One alternative slide format is the step slide.  Instead of using a
  greater than sign ">" to indicate a slide, use an ampersand "&".
  Instead of sliding smoothly to the next time sequence, the slide
  will occur in a series of steps with slides between them.  The
  ampersand is followed by three fields separated by any combination
  of the allowed separators: number of steps, time for slide joins in
  seconds, and fuzz in per cent.  Number of steps is the number of
  step-slide sequences that you want in the time period.  The time for
  slide join is how long to make the slides that bridge the steps in
  seconds.  And the fuzz is the percent of the interval that the
  constant tone can occur in, if it is 10 per cent, then it will be
  the fixed frequency +/- 5 per cent.  The time for slide join
  determines the length of the constant step as the total time for the
  period minus all of the slides has to equal the number of steps.
  The first step or constant tone is always the starting frequency.
  Time to entrain varies and you should make sure that the step time
  is above this for you.  For some, this will work better than a
  continuous slide because it allows time for the brain to entrain
  between each slide.

  Another alternative slide format is the vary slide.  Instead of
  using a greater than sign ">" to indicate a slide, use a tilde "~".
  Instead of sliding smoothly to the next time sequence, the slide
  will occur in a series of steps with slides between them.  The tilde
  is followed by two fields separated by separators:  number of steps
  and time for slide joins in seconds.  Number of steps is the number
  of step-slide sequences that you want in the time period.  The time
  for slide join is how long to make the slides that bridge the steps
  in seconds.  The time for slide join determines the length of the
  constant step as the total time for the period minus all of the
  slides has to equal the number of steps.  The first step or constant
  tone is always the starting frequency.  Time to entrain varies and
  you should make sure that the step time is above this for you.  This
  varies from the step slide in that the steps are random in their
  ordering; they can be anywhere between the starting voice and the
  voice being slid to.  The last slide will always be to the
  corresponding voice of the next time sequence.  This is a great way
  to experience a lot of frequencies in a range.

  All amplitudes are in percentages, 0 is none, 100 is max.  And the
  amplitude is for each channel.  So if you have an amplitude of 10%,
  each channel will have an amplitude of 10% (except where split can
  distribute it differently, say 13% and 7%).

  All splits are expressed as fraction for left channel.  e.g. .3
  means .3 left channel, .7 right channel 
  
  All durations in voices are expressed as seconds.  e.g. .3 = .3
  second, 20 = 20 seconds, 1200 = 20 minutes 

  For any fields with a minimum and maximum range, setting them the
  same makes it a constant value.  Any time they are different, a
  random selection in the range will be made.

  Fields for binaural are name, carrier frequency, beat frequency, and
  amplitude.  Optional fields are a left and right amplitude frequency
  variation and a left and right percentage to vary.  Optional fields
  must be at the end, before the slide indicator if they are present.
  The + or - on the beat frequency indicates whether the left ear is
  higher + or lower -.  The beat is centered on the carrier frequency,
  so 200  +4 results in L 202 and R 198.

  Examples

    binaural''''400.0''''+10.01''''2.9
      |          |         |        |
    name        carrier  beat     amplitude  right left percent vary
      |          |         |       |            |       |
    binaural''''60.0''''+10.01''''1.0''''0.5''''0.5''''10.0''''10.0'>
             |                            |                    |    |
         field separators            left amplitude beat     right  |
          |     |                                               slide
    &''''8''''30'''',,,,10  (slide with & instead of >)
    |    |    |         |
    | steps slide time  fuzz percent
    step slide
    ~,,,,5''''20  (slide with ~ instead of >)
    |    |    |
    | steps slide time
    vary slide

  Fields for chronaural are name, carrier, beat, amplitude, phase, sin
  threshold, beat amplitude behavior, beginning split, ending split,
  lowest split allowed, highest split allowed, split beat, and slide.
  Beat is the frequency through time of the occurrence of the carrier
  tone.  Phase is the phase difference in degrees between the left and
  right channel, from 0 to 360.  If the beat is positive, the right
  channel leads and will be phase shifted.  If the beat is negative,
  the left channel leads and will be phase shifted.  Sin threshold is
  the value the sin function has to have before the tone is played,
  [0.0, 1.0).  The closer this is to 1.0, the shorter the tone will
  be.  There is a one millisecond fade out on all chronaural tones to
  prevent crackle in the sound stream so you cannot use a sin
  threshold such that the length of the tone is less than one
  millisecond or it will fade immediately.  e.g. at a frame rate of
  48000/sec and chronaural beat frequency of 20 Hz the maximum
  amplitude fraction is slightly above 0.9975.  at a frame rate of
  96000/sec and chronaural beat frequency of 5 Hz the maximum
  amplitude fraction is slightly above 0.9999.  Behavior for beat
  amplitude is as follows:

  1 sin wave - tone is multiplied by sin value
  2 square wave - tone is either on or off
  3 dirac delta approximation - tone is multiplied by fifth power of sin 
  4 extreme dirac delta approximation - tone is multiplied by fifteenth 
                                        power of sin 

  If beginning split or ending split are -1, they are set randomly
  between lowest split and highest split.  Split beat is the frequency
  through time of the oscillation between the left and right split.
  Slide indicator must be present or no slide will occur.

  Example
             carrier         phase     begin split     split beat  slide
               |               |          |                     |      |
  chronaural''145.0''4.0''1.0''5''.00''3''0.0''0.5''.050''.950''1.200''>
    |       |        |     |       |   |        |    |      |
   name     |        | amplitude   | amp behave | low split |
        separators beat     sin threshold      end split    high split
          |     |
  &''''8''''30'''',,,,10  (slide with & instead of >)
  |    |    |         |
  | steps slide time  fuzz percent
  step slide
  ~,,,,5''''20  (slide with ~ instead of >)
  |    |    |
  | steps slide time
  vary slide

  Fields for pulse are name, carrier, amplitude, beat, phase, time,
  beginning split, ending split, lowest split allowed, highest split
  allowed, split beat, and slide.  Beat is the frequency through time
  of the occurrence of the carrier tone.  Phase is the phase
  difference in degrees between the left and right channel, from 0 to
  360.  If the beat is positive, the right channel leads and will be
  phase shifted.  If the beat is negative, the left channel leads and
  will be phase shifted.  Time is the duration of the pulse beat in
  seconds.  There is a one millisecond fade out on all pulse tones to
  prevent crackle in the sound stream so you cannot use a pulse beat
  such that the length of the tone is less than one millisecond or it
  will begin to fade immediately.  If the time is longer than the
  period of the beat frequency, greater than 1/beat, the tone will
  sound continuously.  So at a beat of 20 Hz, the time has to be less
  than .05 and if you don't want immediate fade, greater than .001.
  If beginning split or ending split are -1, they are set randomly
  between lowest split and highest split.  Split beat is the frequency
  through time of the oscillation between the left and right split.
  Slide indicator must be present or no slide will occur.

  Example
         carrier            time   begin split   high split  slide
           |                  |       |               |          |
  pulse''145.0''4.0''1.0''5''.02''''0.0''0.5''.050''.950''1.200''>
    |   |       |     |   |               |    |            |
   name |      beat   |   phase           | low split    split beat
   separators     amplitude          end split             
    |     |
  &''''8''''30'''',,,,10  (slide with & instead of >)
  |    |    |         |
  | steps slide time  fuzz percent
  step slide
  ~,,,,5''''20  (slide with ~ instead of >)
  |    |    |
  | steps slide time
  vary slide

  Fields for phase are name, carrier frequency, beat, amplitude,
  phase, beginning split, ending split, lowest split allowed, highest
  split allowed, and split beat.  Optional fields are a left and right
  amplitude beat frequency and a left and right percentage to vary.
  Optional fields must be at the end, before the slide indicator if
  they are present.  Phase is the maximum phase difference in degrees
  between the base carrier tone, the drone, and the phase shifted
  tone, from 0 to a positive number.  The amount of the shifted tone
  in each channel is determined by the split.  The drone tone is
  distributed as the conjugate of the split.  Unlike the fm voice,
  there is no way to change the phase relationship between the left
  and right channels.

  Examples

  name   carrier  beat  amplitude  phase    end split  max split
   |       |       |      |        |           |         |
  phase'''400''''10.01''''2.9''''180''''.5''''.5''''0''''1''''0
                                         |          |         |
                                    begin split  min split  split beat

  Line below split for expository reasons, has to be single in script.

                     amplitude   phase  begin split                                            
  name   carrier  beat    |        |     | end split  split beat
   |         |       |    |        |     |     |              |
  phase''''60.0''''12.01''1.0''''150''''.4''''.6''''0''''1''''0.2
        |        |                                  |    |     
       field separators                      min split  max split
                                                             
    right amplitude beat    right percent vary
                 |               |
      ''''0.5''''0.5''''10.0''''10.0'''''''''>
            |             |                  |
    left amplitude beat  left percent vary   slide
        
  &''''8''''30'''',,,,10  (slide with & instead of >)
  |    |    |         |
  | steps slide time  fuzz percent
  step slide
  ~,,,,5''''20  (slide with ~ instead of >)
  |    |    |
  | steps slide time
  vary slide

  Fields for fm are name, carrier frequency, beat, amplitude, band,
  phase, beginning split, ending split, lowest split allowed, highest
  split allowed, and split beat.  Optional fields are a left and right
  amplitude frequency variation and a left and right percentage to
  vary.  Optional fields must be at the end, before the slide
  indicator if they are present.  Band is the frequency that defines
  the upper limit of the range that the frequency modulation will use.
  The frequency will oscillate between carrier and carrier plus band
  at the beat rate.  Phase is the maximum phase difference in degrees
  between the left and right channel, from -360 to 360.  If the phase
  is positive, the right channel leads and will be phase shifted
  between 0 and the phase at the beat rate.  If the phase is negative,
  the left channel leads and will be phase shifted between 0 and the
  phase at the beat rate.  If beginning split or ending split are -1,
  they are set randomly between lowest split and highest split.  Split
  beat is the frequency through time of the oscillation between the
  begin and end split.  Phase shift and split are somewhat similar in
  their effect.  The sound will be perceived to come from the
  direction where the phase shift is leading.  Split creates the same
  effect using amplitude differential, the sound will seem to come
  from the louder direction.
    
  Examples

  name  carrier beat  amplitude band  phase    end split  max split
   |    |       |      |        |      |            |         |
  fm'''400''''10.01''''2.9''''10.0''''180''''.5''''.5''''0''''1''''0
                                              |          |         |
                                    begin split  min split  split beat

  Line below split for expository reasons, has to be single in script.

                  amplitude      phase  begin split                                            
  name  carrier  beat  |   band      |     | end split  split beat
   |       |       |   |      |      |     |     |              |
  fm''''60.0''''12.01''1.0'''17'''-150''''.4''''.6''''0''''1''''0.2
     |                                                |    |     
    field separators                          min split  max split
                                                             
    right amplitude beat    right percent vary
                 |               |
      ''''0.5''''0.5''''10.0''''10.0'''''''''>
            |             |                  |
    left amplitude beat  left percent vary   slide
        
  &''''8''''30'''',,,,10  (slide with & instead of >)
  |    |    |         |
  | steps slide time  fuzz percent
  step slide
  ~,,,,5''''20  (slide with ~ instead of >)
  |    |    |
  | steps slide time
  vary slide

  Fields for bell are name, frequency, minimum start amplitude, maximum
  start amplitude, beginning split, ending split, lowest split allowed,
  highest split allowed, minimum time allowed to ring, maximum time
  allowed to ring, minimum time till next ring, maximum time till next
  ring, and decay pattern for the ring, 1 through 5.  

  1 decrease linearly to 0 
  2 decrease linearly to .5, 
  3 constant, 
  4 increase linearly to 1.1 
  5 decrease quadratically to 0  (this is the most natural sounding) 

  The minimum and maximum time till next play are relative to the
  beginning of the last play. i.e. unlike noise, bell will interrupt
  itself.  The bell can start ringing again before the current ring
  has finished.  It displaces the currently ringing bell.  If
  beginning split or ending split are -1, they are set randomly
  between lowest split and highest split.

  Example
      frequency        begin split   high split  max time     decay
        |                  |              |         |            |
  bell'900.0'0.153'1.063'-1.0'-1.0'.050'.950'1.300'3.500'1.8'4.8'5'''>
    | |     |  |     |          |   |          |         |     |     |
  name|     |min amp |          | low split    |  min next  max next |
      separators   max amp   end split     min time              slide          

  Fields for noise are name, minimum start frequency, maximum start
  frequency, minimum start amplitude, maximum start amplitude, beginning
  split, ending split, lowest split allowed, highest split allowed,
  minimum time allowed to play, maximum time allowed to play, minimum
  time till next play, maximum time till next play, minimum decay
  pattern for the play, 1 through 21.  maximum decay pattern for the
  play, 1 through 21, and the number of repeats.  

  1 decrease linearly to 0 
  2 decrease linearly to .5, 
  3 constant, 
  4 increase linearly to 1.1 
  5 decrease linearly  to 1.25 
  6 increase sinusoidally from .25 to 1.25 and back down to .25
  7 decrease sinusoidally from 1.0 to 0.5 and back up to 1.0
  8-14 same as above with 10% drop in carrier frequency during each play
  15-21 same as above with 10% rise in carrier frequency during each play
  
  If beginning split or ending split are -1, they are set randomly between
  lowest split and highest split.  Minimum decay has to be less than maximum
  decay or unpredicable behavior results.  The minimum and maximum time till
  next play are relative to the end of the last play. i.e. unlike bell, noise
  will never interrupt itself.  The next voice in a slot will never start
  playing until after the current voice has finished.  If there is no repeat
  on the end, 1 is the default.  To reduce crackle there is a 10ms fade in
  and fade out on the noise voice.

  Example - line split for expository reasons, has to be single in script
  separators  max frequency  max amplitude    end split
        |             |                |              | 
  noise''''360.0''''420.0''''0.50''''0.80''''-1.0''''-1.0''''.050''
    |       |                  |               |               |
  name  min frequency  min amplitude  begin split  min allowed split

  max allowed split  max time to play  max time to next play
      |                  |                  |
  ''.950''''2.3000''''5.7000''''.10000''''.20000''''2''''4''''5''''>
              |                    |                |    |    |    |
    min time to play  min time to next play  min decay   | repeats |
                                                   max decay   slide

  Fields for stoch are name, file name, minimum amplitude, maximum
  amplitude, beginning split, ending split, lowest split allowed,
  highest split allowed, minimum time till next play, maximum time till
  next play.  If beginning split or ending split are -1, they are set
  randomly between lowest split and highest split.
  Example
                                               max time to next play
      file to play  max amplitude  end split  max allowed split   |
               |              |           |             |         |
  stoch'''trig.aiff'''2.20'''3.303'''-1'''-1'''.050'''.950'''.5''3.9'>
   |                  |              |           |            |      |
  name     min amplitude    begin split  min allowed split    |  slide
                                              min time to next play

  Fields for sample are name, file name, minimum amplitude, maximum
  amplitude, beginning split, ending split, lowest split allowed,
  highest split allowed, and length of the sample (constant in seconds).
  If beginning split or ending split are -1, they are set randomly
  between lowest split and highest split.

  Example
      file to play  max amplitude  end split  max allowed split
               |              |           |             |
  sample'''trig.aiff'''1.20'''2.30'''-1'''-1'''.050'''.950'''1.0'''>
   |                  |              |           |            |    |
  name     min amplitude    begin split  min allowed split    |slide
                                                length of sample

  Fields for repeat are name, file name, minimum amplitude, maximum
  amplitude, beginning split, ending split, lowest split allowed,
  highest split allowed.  If beginning split or ending split are -1,
  they are set randomly between lowest split and highest split.

  Example
      file to play  max amplitude  end split  max allowed split
               |              |           |             |
  repeat'''trig.aiff'''1.20'''3.30'''-1'''-1'''.050'''.950''''''>
   |                  |              |           |              |
  name     min amplitude    begin split  min allowed split   slide

  Fields for once are name, file name, minimum amplitude, maximum
  amplitude, beginning split, ending split, lowest split allowed,
  highest split allowed, when to play.  If beginning split or ending
  split are -1, they are set randomly between lowest split and highest
  split.
  
  Example
      file to play  max amplitude  end split  max allowed split
               |              |         |            |
  once'''trig.aiff'''1.20'''3.30'''-1'''-1'''.050'''.950'''20.8
   |                  |            |           |            |
  name     min amplitude    begin split  min allowed split  |
                                                   when to play

  Field for silence is name.
  
  Example

  silence
   |
  name  

  There are test script files called binaural_test.discord,
  chronaural_test.discord, pulse_test.discord, phase_test.discord,
  bell_test.discord, noise_test.discord, stoch_test.discord,
  sample_test.discord, repeat_test.discord, once_test.discord,
  step_test.discord, vary_test.discord, and
  frequency_loudness_test.discord and several script files for actual
  usage.  A python script to do a crude conversion of  sbagen .sbg
  files to discord script files is also included.  It is called, what
  else, convert_sbg_to_discord.py.

QUESTIONS AND ANSWERS

  Q Why is the program called discord?

  A  Because binaural beats are mental artifacts created by a
  discordancy between what the left and right ears hear.

  Q  Why do I call it chronaural beat?

  A  Chron for time and aural for sound.  The beat comes via sounds
  distributed in the time dimension, thus chronaural.

  Q  Do the exact frequencies matter?

  A  In my opinion they do not.  Because everyone is unique, the
  specific frequencies that give someone else an effect might not have
  the same effect for you.  General frequency ranges do correspond
  with similar effects in different people, so I think it is better to
  experience many different frequencies in a range.  That is why there
  is randomness available in the voices.  You never have to listen to
  the same sequence twice, though you can.

  Q  Will brainwave entrainment cause me to have lucid dreams or OOBEs?

  A  Yes and no.  The answer here is not straightforward.  In my
  opinion, entrainment itself won't create such effects unless you are
  capable of them already.  What it will do over time is free psychic
  energy, making it easier for you to have such experiences.  You will
  still have to make the mental effort, but you will have a higher
  chance of success than you would have had otherwise.

  Q  Does it matter when you listen to the beats?

  A  No.  However, it is easiest to listen for longer periods of time
  in the evening as entrainment tends to relax you and this is a time
  when there aren't any urgent matters pending.  It also gives you the
  rest of the night to process.

  Q  Does the loudness of the beats matter?

  A  Not really.  Some like them below the threshold of noticeable
  hearing, some like them just audible, some like them loud.  Whatever
  you feel comfortable with that allows you to entrain is the right
  loudness.

  Q  Are beats better with or without accompaniment?

  A  Again, this is a matter of personal taste.  However you feel
  comfortable listening that still allows you to entrain is the
  right way.

  Q  Which is better, binaural or chronaural beats?

  A  Research I've seen on the internet suggests that chronaural beats
  are much more effective than binaural beats.  Personally, I like
  mixing them and find both effective with a preference for binaural.
  And the phase voices seem, with limited experience, to also be
  effective.  Experiment using each with different carrier and beat
  frequencies and see which works best for you.  I think it is
  possible for the brain to entrain to any stimulus that is periodic,
  though I don't have scientific evidence for that belief beyond my
  own experience.  Obviously, the many ways to create beats in discord
  is a consequence of that belief. 

  Q  What is the maximum amount you should listen per day?

  A  This is individual.  For some, an hour a day will bring on
  overwhelm.  For others, two hours or more a day will be just fine.
  Start with half an hour to an hour.  Then if you want to listen
  more, adjust by a half hour a day.  Because listening makes you feel
  good, you will want to listen as much as possible.  And this is OK
  as long as it doesn't lead to overwhelm.  I find that if I listen
  too much I stop wanting to listen at all.  And that too much gets
  longer with experience.

  Q  How does this work?

  A  I'll give you my opinion, but you should search the web and come
  to your own conclusions.  I think that by triggering waves of
  neurons firing in the brain you do two things: stimulate stored
  memories that haven't been accessed recently and trigger the brain
  to create new neuronal links.  By accessing old memories through new
  pathways and creating new pathways for processing you alter the
  emotional content of memories and allow your brain to integrate
  those memories differently.  This also increases the processing
  power of your brain and makes it/you more flexible.

  Q  Is there a best way to do this?

  A  Remember, this is all my opinion.  I think two general rules
  apply.  If you are less experienced it will take you longer to
  entrain with any given beat, and slides have to be slower for your
  brain to follow along.  If you are less experienced it is easier for
  you to entrain with higher carriers and higher beats.  As you gain
  experience you are able to utilize lower carriers and lower beats,
  and use faster slides.  These are general rules and might not apply
  to you.  Experiment.  It is good to mix it up, entrain with lots of
  different frequencies rather than any specific frequency.  It is the
  repetition and the beat range that matter and every little bit of
  listening adds to your skill.  Lots of people seem to gain benefit
  from listening to the same sequence for long periods of time,
  though, so I could be wrong.  This is a new frontier with lots of
  exploration yet to be done, and all of the above could just be part
  of a larger picture not yet discovered.  

  Q  That EFT thing seems kind of flaky.  Talk to me.

  A  Think of your subconscious brain as an operating system.  The
  pattern of your current situation is used as a fuzzy key into a hash
  table looking for a response.  All hits are stored in a list.  The
  scheduler scans the list looking for the closest match with the
  highest emotional intensity.  The preconfigured response for that
  match is run.  If there are no hits on the hash table then conscious
  logic is used to figure out what to do.  You couldn't function in
  the world if there wasn't some fast lookup/response mechanism.  What
  EFT does is change the scheduling priority for a memory in the
  subconscious.  It does this by having the memory loaded/active and
  then reducing (the tapping) the charge on the emotion.  My theory is
  that the tapping points are like direct lines into your neural
  machinery, and allow you to 'turn the knobs' that lower the
  intensity.  The good part of this is that you aren't actually in the
  situation so you can deal with the response a lot better.  

  Brain wave entrainment, in my opinion, bypasses the lookup and
  triggers unrelated memories directly in a random manner, thus
  diffusing the response.  The memory isn't changed, the meaning of it
  is transformed.  In future when the memory is accessed through the
  scheduler, it is different because of this random triggering.
  Occasionally, the random triggering might cause a repressed memory
  to become accessible for scheduling before it has had its response
  altered.  That is when you need a technique to remove the emotional
  intensity.

  If you just can't get EFT working for you, if it is just too far
  outside your belief system to use, here are some other methods that
  do the same thing in different ways and are effective.

  1. The Sedona Method.    
  2. Neuro Linguistic Programming (NLP).
  3. Hypnosis.
  4. Clean language.
  5. Core transformation.

  Once you understand the way the brain processes experience it is not
  EFT that seems flaky but conventional therapies.  They don't address
  the cause of the problem, the emotional intensity, but instead try
  to get you to 'understand it' consciously.  Maybe this will reduce
  the emotional intensity through some chance happening, but probably
  won't as emotion comes out of the subconscious.  In all likelihood
  the problem actually becomes worse, because you are triggering the
  response over and over and over so you get really good at it.  Thus
  you end up being in therapy for years with no resolution.  EFT or
  the above alternatives take anywhere from seconds/minutes through
  hours to weeks and address the actual problem, the emotional
  intensity, directly.  Once they work the problem is gone.
    
BUGS

  Have to use Control-C to end the program while it is running.

AUTHOR
  discord is by Stan Lysiak <stanlk@users.sourceforge.net>
  This document is by Stan Lysiak <stanlk@users.sourceforge.net>

COPYRIGHT
  Discord is copyright (C) 2007-2009 by Stan Lysiak 
  <stanlk@users.sourceforge.net>
