* Copyright (C) 2005 James McDermott
 * jamesmichaelmcdermott@gmail.com
 *
 * This program is derived from jack-dssi-host 
 * (Copyright 2004 Chris Cannam, Steve Harris and Sean Bolton).
 *
 * 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
 * MERCHANTABILITY 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 01222-1307
 * USA


cli-dssi-host:
-------------
A command-line DSSI host.


Installation:
------------
$ ./configure
$ make
$ sudo make install


Usage:
-----
$ cli-dssi-host 
A command-line DSSI host.
Usage:
$ cli-dssi-host <dssi_plugin.so>[:<label>]
  [-p [<bank>:]<preset>] (use -p -1 for default port values;
           -p -2 for random values; omit -p to read port values from stdin)
  [-l <length>] (in seconds, between note-on and note-off; default is 1s)
  [-r <release_tail>] (in seconds: amount of data to allow after note-off;
           default waits until silence (up to a maximum of 15s))
  [-f <output_file.wav>] (default == "output.wav")
  [-c <no_channels>] (default == 1; use -c -1 to use plugin's channel count)
  [-n <midi_note_no>] (default == 60)
  [-v <midi_velocity>] (default == 127)
  [-d <project_directory>]
  [-k <configure_key>=<value>] ...
  [-b] (clip out-of-bounds values, including Inf and NaN, to within bounds
       (calls exit()) if -b is omitted)


Synopsis:
--------

cli-dssi-host writes a short .wav file with audio generated by sending
1 note-on and then 1 note-off to a DSSI plugin. You can specify the
length and the MIDI note and velocity. Things like presets, labels
within dlls, multiple channels and configure key-value pairs seem to
work!

Examples:
--------

$ cli-dssi-host simple.so -p -1

(which uses default values for all control-in ports);

$ cli-dssi-host less_trivial_synth.so < lts.prs

(where lts.prs is a text file containing one argument for each
control-in port);

$ cli-dssi-host xsynth-dssi.so -p 0:3

(which loads program (aka preset) 3 in bank 0);

$ cli-dssi-host trivial_sampler.so:stereo_sampler -p -1 -k load=snare.wav -c -1

(where load=snare.wav is a configure key-value pair, and -c -1
tells the program to write as many channels as the stereo_sampler
plugin has audio outputs).

Bugs/things to do:
-----------------

The -l arg specifies length in seconds between note-on and note-off.
(or nearly - would have to set the note-off.time.tick exactly for that.)
But it's not ideal, since we still have to record the release tail.
Maybe an extra arg to specify absolute length.

The function which calculates when the release tail is finished could
probably be improved - e.g. by stopping at a zero-crossing, as well
as waiting for a low-power frame.