.TH ghostess 1 "September 5th, 2010"
.SH NAME
ghostess \- graphical DSSI plugin host
.SH SYNOPSIS
.B ghostess
[\fB-debug \fIlevel\fR] [\fB-hostname \fIhostname\fR] [\fB-projdir \fIprojdir\fR]
[\fB-uuid \fIuuid\fR] [\fB-noauto\fR] [\fB-f \fIcfgfile\fR]
[\fI-n\fR] [\fB-chan \fIc\fR] [\fB-conf \fIk\fR \fIv\fR] [\fB-prog \fIb\fR \fIp\fR]
[\fB-port \fIp\fR \fIf\fR] \fIsoname\fR[\fI:label\fR] [\fI...\fR]
.SH DESCRIPTION
.B ghostess
is a DSSI host that listens for MIDI events, delivers them to DSSI
synth plugins, and outputs the resulting audio via JACK.
.B ghostess
also supports DSSI plugins having audio inputs (effects), LADSPA
plugins, and the use of DSSI-style user interfaces with LADSPA plugins.
.B ghostess
can host up to 32 plugin instances at one time.
.PP
Depending on the compile-time configuration,
.B ghostess
will receive MIDI events from ALSA, JACK MIDI, or CoreMIDI.
Unless otherwise specified by the
.B -chan
option, each plugin instance is sequentially assigned a MIDI channel,
wrapping from 15 (zero-based) back to 0 when necessary. Unless
.B \-noauto
is specified, plugin inputs and outputs are connected sequentially to
the available JACK physical input and output ports, respectively, wrapping back
to the first port whenever the available ports are exhausted.
.PP
At startup,
.B ghostess
presents a simple GTK+ user interface.  Each plugin instance is
represented in a frame, labeled with the plugin name, and containing
a MIDI activity indicator and a \'UI\' button. Left-clicking the
\'UI\' button will start or hide the plugin's user interface (UI).
Right-clicking the \'UI\' button will allowing starting, hiding,
showing, or terminating the plugin's UI.
.PP
The \'Save Configuration...\' option of
.BR ghostess 's
\'File\' menu allows saving the current configuration of all plugins
to a file. Basically, the file is just a Bourne shell script that
can be used to recreate the configuration.
.PP
.B ghostess
comes with a minimal universal DSSI GUI,
.BR ghostess_universal_gui ,
that can be used with any DSSI or LADSPA plugin.  It does not read
RDF files or instantiate the plugin, so it's not as full-featured as
a universal GUI could be, but it does allow for adjusting
DSSI/LADSPA ports, selecting bank and program (for plugins with
select_program()), and sending test notes (for plugins with any of
the run_synth() functions). If ghostess cannot find a UI for a
plugin, and the universal GUI is in the
.BR PATH ,
.B ghostess
will launch it.
.SH OPTIONS
The following global options are available:
.TP
.BI -debug " level"
Sets bitfield flags which determine which debugging information is
printed.  The default
.I level
of 1 shows errors only, 0 shows nothing, and \-1 shows everything.
See ghostess.h for details.
.TP
.BI -hostname " hostname"
Sets
.I hostname
as the name
.B ghostess
uses for itself, for JACK and ALSA clients and GUI window titles.
If a JACK port cannot be created with that name, the PID is appended.
.TP
.BI -projdir " projdir"
Sets the project directory passed to both plugins and UIs to
.IR projdir .
The default is none.
.TP
.BI -uuid " uuid"
Sets
.I uuid
as the UUID used for JACK session management. There is probably no
reason to use this outside of a managed session.
.TP
.B -noauto
Disables automatic connection of plugin outputs to JACK physical
outputs.
.TP
.BI -f " cfgfile"
Additional configuration will be read from
.IR cfgfile ,
in the same format as command line options.
.P
For specifying plugin instances,
.B ghostess
uses a '[\-\fIrepetition-count\fR] [\fIoptions\fR]
\fIsoname\fR[:\fIlabel\fR]' format, which may be repeated for
multiple instances. The plugin-specific options are:
.TP
.BI \- n
Specifies the repitition count, or number of instances, of the
following plugin to create, where
.I n
is an integer between 1 (the default) and 32.
.TP
.BI -chan " c"
Sets the initial MIDI channel for the following plugin instance to
.IR c .
Channels are numbered 0 to 15. If the repetition count is more than
one, instances are given sequential channels beginning with
.I c
and wrapping from 15 to 0. The default is for all instances'
MIDI channels to be sequentially numbered, starting from 0.
.TP
.BI -conf " k" " " " v"
Sets configure item key
.I k
and value
.I v
for the following instance. May be repeated for multiple keys.
.TP
.BI -prog " b" " " " p"
Sets the program change bank
.I b
and program
.I p
for the following plugin (numbered from 0).
.TP
.BI -port " p" " " " f"
Sets the value of port
.I p
to floating point number
.I f
for the following plugin. May be repeated for different ports.
.TP
.I soname
The name of the DSSI or LADSPA plugin library to load, including the
\'.so\' suffix.
.I soname
may be an absolute path to the library file, or just the filename
itself, in which case the DSSI search path is searched (see
.B ENVIRONMENT
below).
.TP
.I label
The label of the DSSI or LADSPA plugin to load from the library
.IR soname .
If this is omitted, the first plugin in the library is used.
.SH ENVIRONMENT
.B ghostess
will search for plugin shared libraries in the directories specified
by the environment variable
.B DSSI_PATH,
which is a colon-separated list of directories. If
.B DSSI_PATH
is not set, a default search path of
.BR /usr/lib/dssi ,
.BR /usr/local/lib/dssi ,
and (assuming the environment variable
.B HOME
is set,)
.B $HOME/.dssi
is used. Note that while
.B ghostess
may be used to host LADSPA plugins, the environment variable
.B LADSPA_PATH
is not used to search for them.
.SH EXAMPLES
Assuming
.B DSSI_PATH
is correctly set, the command:
.PP
.EX
$ ghostess hexter.so
.EE
.PP
will start a single instance of the plugin hexter, listening on MIDI
channel 0, with its output connected to the first JACK physical
output port.
.PP
The command:
.PP
.EX
$ ghostess \-noauto \-chan 2 xsynth-dssi.so \-chan 2 xsynth-dssi.so
.EE
.PP
will start two instances of Xsynth-DSSI, both listening on MIDI
channel 2, but will not automatically connect the plugin outputs to
JACK output ports.
.PP
The command:
.PP
.EX
$ ghostess \-debug \-1 \-hostname fuzzy \-projdir /tmp/proj \-2 \-conf load
mypatches \-prog 0 4 \-port 7 0.45 effects.so:fuzz
.EE
.PP
will start two instances of the \'fuzz\' plugin within the
.B effects.so
library, using
.B /tmp/proj
as the project directory, pass configure key \'load\' with value
\'mypatches\' to both instances, set bank 0 and program 4, and set
port 7 to 0.45. Assuming it is some sort of effect, the plugins\'
inputs and outputs will be automatically connected to the first JACK
physical inputs and outputs. Full debugging information will be
printed, and
.B fuzzy
will be used as the JACK client name.
.SH AUTHOR
.B ghostess
was written by Sean Bolton, who mercilessly mangled code originally
written by Chris Cannam and Steve Harris. This manual page was
adapted by Sean Bolton from the jack-dssi-host manual page
originally by Mark Hymers.