hexter
                                ======
               A Yamaha DX7 modeling software synthesizer
                for the Disposable Soft Synth Interface

Introduction
============
hexter is a software synthesizer that models the sound generation of
a Yamaha DX7 synthesizer.  It can easily load most DX7 patch bank
files, accept patch editing commands via MIDI sys-ex messages (ALSA
systems only), and recreate the sound of the DX7 with greater
accuracy than any previous open-source emulation (that the author is
aware of....)

hexter operates as a plugin for the Disposable Soft Synth Interface
(DSSI).  DSSI is a plugin API for software instruments (soft synths)
with user interfaces, permitting them to be hosted in-process by
audio applications.  More information on DSSI can be found at:

  http://dssi.sourceforge.net/

hexter is written by Sean Bolton, and copyright (c)2007 under the
GNU General Public License, version 2 or later.  See the enclosed
file COPYING for details.  While this software is 'free' within the
requirements of this license, I (Sean) would appreciate any or all
of the following should you find hexter useful:
    - an email stating where you're from and how you're using
        hexter, sent to <musound /at/ jps /dot/ net>.
    - copies of or links to music you've created with hexter.
    - any favorite patches you create for hexter, or any patches
        that work on a real DX7 but not on hexter.
    - suggestions for improving hexter.

hexter is indirectly the result of cumulative effort by a large
number of contributors, see the AUTHORS file for details.

Requirements
============
hexter requires the following:

    - DSSI version 0.4 or greater, available from the 
        dssi.sourceforge.net address above.

    - liblo version 0.12 or greater (0.23 or greater recommended), a
        library implementing the Open Sound Control protocol,
        available at:

        http://plugin.org.uk/liblo/

    - pkgconfig with PKG_CONFIG_PATH set appropriately to pick up
        DSSI and liblo.

    - GTK+ version 1.2 or 2.x.

    - the LADSPA v1.x SDK.

    - the ALSA headers (DSSI plugins use ALSA structures, but not
        the actual drivers, so you don't necessarily need the
        drivers installed.)  Users of non-ALSA systems may use
        libdssialsacompat, available at:

        http://home.jps.net/~musound/

    - a working DSSI host.  hexter has been tested with the
        jack-dssi-host, available in the DSSI distribution, and with
        ghostess, available at:

        http://home.jps.net/~musound/

    - automake 1.7 and autoconf 2.57 or better if you wish to
        recreate the build files.

Installation
============
The generic installation instructions in the enclosed file INSTALL
aren't particularly helpful, so try this instead:

1. Unpack the tar file.

2. Make sure PKG_CONFIG_PATH is set correctly to locate the
    dssi.pc and liblo.pc pkgconfig files.  On many systems, this
    will be:

    $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
    $ export PKG_CONFIG_PATH

3. 'cd' into the package directory and execute './configure'.
    configure will add '-Wall' and my favorite optimizations to
    CFLAGS for you if you don't include any '-Wall' or '-O' options.
    If you're using gcc and wish to provide your own optimization
    flags, you MUST at least use '-finline' and a non-zero '-O' flag
    to get decent results.

4. Enable debugging information if you desire: edit the file
    src/hexter.h, and define DSSP_DEBUG as explained in the
    comments.
    
5. Do 'make'.  Hopefully it should build without warnings (or
    errors.)

6. 'make install' will install the following:

    <prefix>/lib/dssi/hexter/hexter_gtk
    <prefix>/lib/dssi/hexter.so
    <prefix>/lib/dssi/hexter.la
    <prefix>/share/hexter/dx7_roms.dx7
    <prefix>/share/hexter/fb01_roms_converted_12.dx7
    <prefix>/share/hexter/fb01_roms_converted_34.dx7
    <prefix>/share/hexter/fb01_roms_converted_5.dx7
    <prefix>/share/hexter/tx7_roms.dx7

Feedback on your experiences building hexter is appreciated.

Operation
=========
To run the hexter plugin under the jack-dssi-host provided
in the DSSI distribution, I do the following:

1. Start JACK.

2. Start jack-dssi-host, supplying the correct plugin path
    and filename (substitute <prefix> as appropriate):

    $ DSSI_PATH=<prefix>/lib/dssi sudo jack-dssi-host hexter.so

    jack-dssi-host should start, and moments later the hexter
    graphic user interface should appear.

3. Use qjackctl or aconnect to connect jack-dssi-host to a MIDI
   source, such as vkeybd.

4. Begin playing sounds!  If you get no response, try clicking the
    'Send Test Note' button in the hexter GUI.  This sends a note
    directly via the host to the plugin, so if you hear sound now,
    look for a problem between the host and your MIDI source.  If
    you still don't hear sound, I'd look for a problem between the
    host and your output device.  If you continue having trouble,
    you might recompile with DSSP_DEBUG bit 2 set, which will cause
    the plugin to continuously output a quiet buzz to help debug
    your outgoing signal path.

hexter starts up with a default set of sound presets, or 'patches',
that you can select either by selecting the GUI 'Patches' tab and
clicking on the patch name, or by sending a MIDI program change from
your MIDI source with the appropriate program number.

Patch Import/Export
===================
hexter can import DX7 patch bank files in several formats:

- The standard 32-voice bulk dump sys-ex format.  These are 4104
bytes long, and you can find a million of them by Googling for "dx7
patches".  hexter places no restrictions on their filenames.

- The standard single-voice (edit buffer) sys-ex format.  These are
163 bytes long.

- Raw packed patch data. These are 128 bytes per patch, and may
contain any number of patches (although hexter can only load up to
128 of them.)  Note, though, that if the file is 8192 bytes long and
has the filename suffix ".tx7" or ".TX7", the second half of the
file will be ignored (Dr. T TX7 format).

- Standard MIDI files containing either a 32-voice bulk dump sys-ex
message or a single voice dump sys-ex message.  If the file contains
more than one qualifying sys-ex message, only the first will be used.

- Voyetra SIDEMAN DX/TX format (9816 bytes long).

- Two concatenated 32-voice bulk dump sys-ex messages (8208 bytes
long.)

You may use the "Import Patch Bank..." option in the File menu to
import patches.  After selecting the filename, you will need to
specify the program number (0 to 127) at which to begin importing
the patches.

Several patch bank files are installed with hexter in
<prefix>/share/hexter/.

You may also export patch banks using the File menu "Export Patch
Bank..." option.  You can then select which of the formats to save
in, and what range of patches to export.  Finally, select the
filename to which you want to save, and click 'Ok'.

Synthesizer Configuration
=========================
On the 'Configuration' tab of the hexter GUI,  there are six
controls for configuring hexter:

- tuning: sets the tuning of this instance of the plugin,
    as Hz for A-above-middle-C.

- volume: adjusts the output volume for this instance, from -70dB to
    +20dB relative to a nominal reference level (-18.1dB per voice,
    which permits approximately 8 voice polyphony within -1.0 to
    +1.0 float.)

- polyphony (instance): Sets the maximum polyphony for this instance
    of the plugin.  If you attempt to play more notes than this
    setting, already-playing notes will be killed so that newer
    notes can be played.

- polyphony (global): Sets the maximum polyphony for all hexter
    instances running on this host.  If you are getting xruns, try
    reducing this setting.

- monophonic modes: sets poly/mono operation for this instance of
    the plugin to one of the following:
    'Off'  - polyphonic operation.
    'On'   - monophonic operation, where the envelopes are
             retriggered upon each incoming note on event. 
    'Once' - monophonic operation, where the envelopes are triggered
             only on the first note on of a legato phrase -- that
             is, if you hold one note while playing a second, the
             envelopes will not be retriggered for the second note. 
    'Both' - monophonic operation, where the envelopes are
             retriggered at each note on, and upon note off when
             other keys are still held.

- disable LFO/Mod/Perf (0.5.x compatibility): selecting this check
    box will disable the LFO, amplitude modulation, pitch
    modulation, and performance parameter enhancements provided by
    hexter 0.6.0 and later versions, forcing it to sound just like
    the 0.5.9 version.  This is provided for backward compatibility
    with existing projects that used hexter 0.5.9.

Sys-Ex Patch Editing
====================
hexter does not include a user interface for editing patches, but on
ALSA systems, it can receive MIDI system exclusive messages from you
favorite patch editor/librarian.  JSynthLib (http://www.jsynthlib.org/)
works well in combination with the ALSA virmidi device, or you can
try the ncurses-based editor included with hexter (see
extra/tx_edit.c).

Sys-ex patch editing is enabled on the 'Configuration' tab by
depressing the 'Enable Sys-Ex Editing' button.  The hexter GUI then
creates an ALSA MIDI client and displays its client and port number
in the status window below the 'Sys-Ex Receive Channel' slider.  Set
the channel appropriately and route your patch editor to this port
using aconnect or similar, and the hexter instance will be ready to
receive patch edits.

Patch edits accumulate as an 'overlay' replacing the current patch.
Clicking the 'Discard Changes' or selecting another patch from the
'Patches' tab will discard the edits.  Clicking 'Save Changes into
Patch Bank' will allow you to do just that.

Note that hexter only _receives_ MIDI sys-ex messages, and does not
send them.  Also, it only receives single patch dumps and voice
parameter changes, so any 'get patch data from synth' or 'send 32
voices to synth' functions of your librarian will not work -- any
patch you wish the edit must originate in your librarian, or you
must export it from hexter first as a file, then load it into your
librarian from that.

Performance Parameters
======================
The 'Performance' tab of the hexter GUI contains controls for the
DX7/TX7 Performance Parameters:

- pitch bend range: sets the response to MIDI pitch bend messages,
    in semitones.

- portamento time: sets the portamento time.  Note that as of
    version 0.6.1, the portamento code is still unfinished.

- mod wheel sensitivity: sets the depth of response to MIDI
    modulation wheel control change messages (MIDI control change 1).

- mod wheel assign: these three check boxes set which destinations
    the modulation wheel affects: selecting 'P' routes the LFO to
    pitch modulation (vibrato), 'A' routes the LFO to amplitude
    modulation (tremelo or wah), and 'E' routes the modulation wheel
    value itself to amplitude modulation.

- foot sensitivity, foot assign, pressure sens., pressure assign,
    breath sens., and breath assign: these set the sensitivity and
    routing as described above for the foot controller (MIDI CC 4),
    for pressure (both channel and key pressure), and for the breath
    controller (CC 2), respectively.

MIDI Controller Mapping
=======================
In addition to the performance parameter MIDI messages mentioned
above, hexter responds to MIDI volume (MIDI control change 39),
sustain pedal (MIDI CC 64), and all-sounds-off, all-notes-off, and
reset-controllers control messages (CCs 120, 123, and 121,
respectively).  The 'coarse frequency' parameter for each operator
can also be controlled in real time via the following MIDI control
change mappings:

Control change 16 (General Purpose #1 MSB) to operator 1 FC.
Control change 17 (General Purpose #2 MSB) to operator 2 FC.
Control change 18 (General Purpose #3 MSB) to operator 3 FC.
Control change 19 (General Purpose #4 MSB) to operator 4 FC.
Control change 80 (General Purpose #5)     to operator 5 FC.
Control change 81 (General Purpose #6)     to operator 6 FC.

Frequently Asked Questions
==========================
Q. The plugin seems to work fine, but the GUI never appears. Why?

A. Make sure the hostname of your machine is resolvable (if not, the
OSC messages can't be sent between host and GUI).  If your machine's
hostname is 'foo.bar.net', make sure you either have an entry for
'foo.bar.net' in /etc/hosts, or that your DNS server can resolve it.
Test this with e.g. 'ping foo.bar.net'. To test that the GUI itself
works, you can start it by itself (without a DSSI host) by giving it
the '-test' option, for example:

    $ <prefix>/lib/dssi/hexter/hexter_gtk -test

Resources:
==========
http://www.myjavaserver.com/~christopher/dx7_tx7.html
    Chris Dodunski's DX7 page, has much info as well as links to
    patch files.

http://www.maths.abdn.ac.uk/~bensondj/html/dx7.html
    Dave Benson's DX7 page, has much info as well as links to patch
    files.

http://www.synthzone.com/yamaha.htm
    The Synth Zone's collection of Yamaha link, which contains quite
    a few links to patch file collections.

Anybody know where Godric Wilkie's synth pages went?