README

PHASEX-0.14.97:

-------------------------------------------------------------------------------
[P]hase [H]armonic [A]dvanced [S]ynthesis [EX]periment
-------------------------------------------------------------------------------

Welcome to the latest and greatest of PHASEX!

PHASEX is an experimental MIDI softsynth for Linux/ALSA/JACK with a
synth engine built around flexible phase modulation and flexible
oscillator/LFO sources.  Modulations include AM, FM, offset PM, and
wave select.  PHASEX comes equipped with multiple filter types and
modes, a stereo crossover delay and chorus with phaser, ADSR envelopes
for both amplifier and filter, realtime audio input processing
capabilities, and more.  Inspirations come from a variety of analog
and early digital MIDI synthesizers from the '80s and '90s.

-------------------------------------------------------------------------------


GOALS:
-------------------------------------------------------------------------------

* C Hacker Friendly.  PHASEX is written entirely in C.  No C++.  No
  assembly.  From the very beginning, the program framework (now
  a much larger application framework) has existed to support a synth
  engine written in good ol' C.  Now the application framework is well
  on its way to serving as a basic platform for developing new
  instruments written in... you guessed it... C.

* Reliability.  Whether playing music on stage, working in the studio,
  or writing music on a laptop in a coffee shop, the instruments and
  tools need to function properly and consistently in order to achieve
  good results.  Musicians need to be able to focus on the music, not
  shortcomings of the toolset.

* Compatibility, starting with full JACK and ALSA API support (and
  eventually support for additional audio / MIDI libraries), allowing
  PHASEX to be used in any pro audio workflow on a modern Linux
  distribution.  The standalone application design was partially
  chosen for this reason -- not all sequencers and DAWs support all
  instrument plugin formats.  For this reason, PHASEX will most likely
  see support for features such as ALSA channel mapping, JACK
  Freewheel, and even Non Session Manager (NSM) before seeing support
  for DSSI or LV2?  Why?  PHASEX already runs side by side with
  Ardour, MusE, Rosegarden, Qtractor, Seq24, or any other sequencer
  supporting JACK MIDI or the ALSA sequencer interface, no matter what
  plugin APIs these sequencers do or do not happen to support.  In the
  future, adding support for plugin formats may be deemed necessary
  for making PHASEX more useful in certain situations.  For now, the
  development effort will focus on fine-tuning and extending the usage
  of the APIs already supported.

* Stage friendly.  Low MIDI latency and low timing jitter.  Run with
  or without the GUI.  Ability to specify alternate config files
  (just be sure you have a backup of your ~/.phasex/on-stage.cfg...).
  With decent hardware running PHASEX and a recent -rt kernel with
  proper permissions, priority tuning, hardware tuning (BIOS settings,
  PCI latencies, etc.), and audio buffer tuning, MIDI-audio latencies
  of under 10ms should be well within reach for audio hardware capable
  of running with 128 sample buffer periods or better.

* Studio friendly.  Focus on workflow.  The recent development work
  has been aimed at making PHASEX easier to use and efficient to
  manage (quick configuration, built in session management, MIDI
  connections in the menus, etc.).  Again, the focus should be on the
  music, not on remembering how to make the instrument jump through a
  bunch of hoops just to do it's job.  PHASEX development will
  continue in this direction with new session management features
  based on community feedback.

* Great sound.  This one is of course, quite subjective, but it still
  comes down to the same juggling act on the programming end:  Choosing
  the "right" algorithms, making resource usage vs. sound quality
  decisions, calculation speed vs. accuracy decisions, and of course,
  decisions about how much programming time is spent on what features
  (hmmm... is it worth the time to do the math and write and debug the
  code for nifty-feature-x, or is time better spent fixing
  broken-feature-y?).  At this point, a lot of these decisions have
  been made and the synth engine as a whole is very stable, but these
  things are not necessarily set in stone.  There is always room for
  improvement by researching new ways of doing the math and learning
  new DSP tricks for solving some of the flaws inherent in the current
  methods.  So, how does it sound?  Decide for yourself.


FEATURES:
-------------------------------------------------------------------------------

* GTK Interface:

    PHASEX has a GUI with switchable color themes, knobs and buttons
    for all 150+ patch parameters, preferences dialog for easy
    configuration, patch bank and session bank, MIDI connections from
    the main menu, and more.  True fullscreen mode, notebook,
    one-page, and widescreen layouts, and select-able fonts and knob
    sizes allow PHASEX to fit into any amount of screen real-estate
    (now able to squeeze into sizes smaller than 800x600, or more
    comfortably sit in a 1920x1080 desktop).

* Polyphonic:

    PHASEX is polyphonic.  In poly mode, voices are allocated
    dynamically up to the runtime configurable voice limit.  
    Oscillators and filters function independently per-voice.  LFOs,
    however, function on a per-part basis.  In addition to Poly mode,
    the three legacy Mono modes are still supported: Mono Smooth mode
    puts new notes back into sustain if playing legato.  Mono Multikey
    mode maps the keys played, in order, round-robin style to all
    oscillators based on MIDI note frequencies in use.  In Mono
    Retrigger mode, envelopes and oscillator init phases are
    retriggered every time a note is played.

* Multitimbral:

    Many parts of PHASEX were re-architected during the v0.14.x
    development phase.  This release is now fully multitimbral, with
    each part running in its own thread.  The number of parts (and
    thus engine threads) is determined at compile time, and has been
    tested rigorously with 8 voices on a quad-core q6600.  Part
    switching in the GUI is clean and efficient.  Session handling
    support takes the fuss out of keeping track of session patches.

* ALSA Audio:

    PHASEX supports native ALSA for flawless xrun free audio playback.
    Sample rate and buffer size are easily configurable to achieve the
    lowest possible latencies for your system.

* JACK Audio:

    PHASEX has supported JACK audio from the beginning of the public
    MIDI enabled releases.  Any sample rate or buffer size used by
    jackd can be utilized.  Both single- and multi- stereo-pair
    routings are supported.  Basic Transport is supported, but as of
    this time, the tempo and LFO sync are largely untested and may
    still need some fine-tuning.

* ALSA MIDI:

    The ALSA sequencer interface has been with PHASEX since its first
    public release.  As of v0.14.x, the ALSA raw MIDI interface is
    also supported, offering lower timing jitter when controlling
    PHASEX via hardware MIDI.

* JACK MIDI:

    JACK MIDI provides 100% sample-accurate timing by design.  PHASEX
    has embraced this design, and the new underlying MIDI system is
    the result.

* Generic MIDI:

    Generic MIDI (/dev/midi) support is provided for communicating
    with MIDI devices or drivers that use a standard POSIX interface
    supporting open/close/poll/read/fcntl on a named pipe, socket, or
    device file.  The generic MIDI support has only been tested with
    ALSA's /dev/midi* and /dev/snd/midiC?D? device files (which are
    accessed through the POSIX interface, not the alsa-lib API), but
    should perform the same with any MIDI device interface as long as
    additional system and library calls are not needed.  Currently,
    compatibility with serial to MIDI converters is unknown, so please
    send feedback (positive or negative) if you attempt to use a
    serial to MIDI converter.

* MIDI Control:

    All parameters are quickly mappable and ready for full realtime
    control.  Parameter names are right clickable for quick and easy
    MIDI controller assignments.  Each MIDI controller can be mapped
    to up to 15 parameters.  Velocity sensitivity and key aftertouch
    can modulate the amp and the filter, or used as raw oscillators of
    LFOs.  MIDI maps may be saved and later restored to facilitate
    switching between different working environments.

* Realtime MIDI Clock:

    Addresses the issue of how to accurately synchronize MIDI events
    with individual frame positions within a buffer period instead of
    quantizing the timing to whatever the audio buffer period happens
    to be.  Typical audio hardware supports stable realtime operation
    at anywhere from 2-20 milliseconds latency.  With no additional
    synchronization, this audio latency becomes a self-imposed
    quantization factor on event timing, adding MIDI timing jitter
    roughly equal to the duration of one audio buffer processing
    period, hence the need for a MIDI clock:

    A timerless, tickless audio / MIDI timing synchronization system.
    The clock latches onto the audio buffer processing periods and
    generates a high-precision MIDI clock reference, with much less
    jitter than timing based on when the audio processing cycle
    actually wakes up (which can really be anywhere within the
    period).  This clock is agnostic to the specific audio and MIDI
    drivers being used and requires no timer interrupts.  In essence,
    the timing accuracy achieved is only dependent on the MIDI
    hardware/software and realtime scheduling latencies of the system.
    With decent professional MIDI and audio hardware, sub-millisecond
    timing accuracy is available with total MIDI event latency under
    10ms, accurate and responsive enough for most professional sound
    sound engineers and musicians.

* Multithreaded:

    PHASEX uses separate threads with realtime scheduling for audio
    output, MIDI input, and the synth engine.  The GTK UI runs in its
    own thread at normal scheduling priority.

* 4 Oscillators:

    Each oscillator features wave shape selection (including sampled
    and generated waveforms), bipolar or unipolar output, frequency
    source selection (midi note, tempo based, tempo based w/ phase
    trigger, audio input, or velocity/aftertouch), mix modulation
    supporting standard or AM mixing, per-osc transpose and
    pitchbender amounts, and select-able modulation sources for AM, FM,
    phase offset, and waveshape modulation.  For all but waveshape
    modulation, both oscillators and LFOs are available as modulation
    sources.

* 4 LFOs:

    The dedicated per-osc LFOs have been replaced with generic
    per-part LFOs.  The LFOs are identical to the oscillators with the
    following exceptions:  They are per-part instead of per-voice,
    they do not accept other modulation sources (yet), they are not
    transposed by the master transpose parameter, and when sourced to
    velocity, aftertouch data is ignored.  New routing capabilities
    have been added with the Voice AM, LFO-1 Rate, Cutoff, and LFO-3
    Rate per-LFO dedicated function parameters.

* ADSR Envelopes:

    PHASEX comes equipped with standard ADSR envelopes for the
    amplifier and filter.  Duration times follow a parabolic curve.
    The amplitude of the amplifier envelope follows a logarithmic
    curve.  The filter envelope is linear with respect to the musical
    scale.  Both envelopes can also be used as oscillator and LFO
    sources.

* Filter:

    The first filter style is a Chamberlin filter (2-pole 12db/octave)
    hacked up so it doesn't destabilize at high cutoff or resonance
    values.  Low pass, high pass, band pass, and band stop modes are
    available, as well as four combo modes.  The filter has it's own
    ADSR envelope (identical to amplifier envelope with the added
    option of switching to negative polarity).  One of the LFOs may be
    mapped to modulate filter cutoff.  Cutoff controller values map
    directly to MIDI note numbers.  Optional keyfollow mode allows
    cutoff to follow the key played for the MIDI note, or the lowest,
    highest, or most recent key in play.  The filter is per-voice in
    Poly mode.

    As of v0.14.x, a 4-pole 24db/octave Stilson/Smith style Moog
    filter has been added.  In PHASEX style, cutoff frequency is
    adjusted in halfstep increments, and both a distorted and a
    clean version are available.

    The 3-pole filter is experimental, and might not be included in
    future versions.  Future plans include fixing the frequency
    calculation and turning this into a proper 303 style filter.

* Chorus:

    The PHASEX stereo crossover chorus (inspired by the chorus on the
    old Akai S-series samplers) adds depth and that extra bit of
    stereo separation for an even wider stereo field.

* Delay:

    The delay sports the normal mix and feedback controls, along with
    a channel crossover option.  A dedicated LFO allows modulation of
    playback position, great for flange-like effects (or really
    messing with people's heads at longer delay times).  Delay times
    are select-able based on tempo, in both 1/64th and 1/48th
    increments.

* Input Processing:

    Up to two JACK input channels (as mono, dual mono, or stereo) may
    be used as audio sources for both oscillators and LFOs.  An input
    envelope follower and input boost allow for sources like guitar or
    vocals to be processed with ease.

* Stereo Width:

    The width of the stereo image is adjustable via a MIDI controller
    from pure mono to pure stereo.  Can be used during sound design to
    help create patches that sound very different when a center
    playback channel is present.  Very useful for getting patches to
    sit in the mix properly.

* Velocity Sensitivity:

    Velocity of Note-On events can modify the filter or amplifier, and
    can also be routed through the LFOs.

* Session Handling:

    For multitimbral builds, PHASEX comes equipped with a session bank
    which operates much like the existing patch bank.  In addition to
    the new native session handling, LASH and JACK Session supported
    as well.

-------------------------------------------------------------------------------


MAJOR CHANGES SINCE v0.12.x:
-------------------------------------------------------------------------------

In addition to new major features listed above, all parts of the
PHASEX source code have been overhauled, with some important changes:

* New synth patch file format:  This decision was not made lightly,
  and there are many reasons for this:  The behavior of some
  parameters has changed (anything dealing with velocity curves,
  envelope curves, offset of negative envelopes), new parameters have
  been added, new parameter values have been added, and the old patch
  parser code grew into an almost unmanageable mess.  Starting with
  v0.14.x, parameter values in patch files reflect the values shown in
  the GUI instead of _mostly_ reflectling MIDI values, which should be
  better for human readability.  Improperly named parameters have been
  renamed to avoid confusion as well.  A patch conversion script is
  provided to convert patches from v0.12.x to v0.14.x, and should work
  well in most cases.  With the new synth engine improvements, a lot
  of old patches can be modified to sound better with very little
  effort, so please don't fret when old patches don't sound _exactly_
  the same.  If there is one apology that needs to be made with the
  new PHASEX release, this is it.  If converting all your old patches
  into the new format really throws a monkeywrench into the works, I
  do apologize.

* GUI and engine are (almost) fully separated.  Engine parameters and
  GUI parameters now have separate callback paths.  The GUI queues
  parameter change events for the engine instead of modifying engine
  parameters directly.  GUI-initiated patch changes are still
  performed by the GUI (hence 'almost separated').  Current plans
  include separating this out as well.  Cleaning up this aspect of the
  GUI has helped tremendously, allowing all the weird hacks and
  workarounds for parameter state handling to be replaced with a
  design that works efficiently and dependably.  Since the engine and
  MIDI code no longer have to be aware of the GUI, phasex can now be
  started without the GUI.

* Lock-free buffer synchronization:  The pthreads mutexes in the
  buffer processing code been removed in favor of lock-free buffering
  and for the engine, clock_nanosleep() based adaptive sleep timing.
  Moving away from the old broken design means fewer context switches,
  fewer (if any) priority inversion problems, a better guarantee that
  engine threads can fill buffers on time, and most important of all:
  no more "bad PHASEX sound" from engine and audio losing sync.

* New MIDI queue:  Single-reader.  Multiple-writer.  Multiple events
  per frame.  Monotonic.  Reliable.  Used by GUI and all MIDI drivers
  to queue events for the engine.  Queue data format is designed to
  hold 2 and 3 byte MIDI messages.  Event types not defined in the
  MIDI spec are used for internal non-MIDI events (currently 0x01
  through 0x04).

* MIDI Reference Clock:  All of the MIDI event queuing and realtime
  buffer synchronization between audio, engine, and MIDI threads is
  built around the new MIDI reference clock.  All synchronization
  events (engine waking up, audio waking up, timestamping MIDI events,
  and updating audio,engine, and MIDI buffer indices) happen at a time
  relative to the begininng of a MIDI period (equal in time to an
  average audio buffer period, but starting some configurable amount
  of time earlier).

* There's plenty more if you're curious.  Have a look at the
  ChangeLog, or just go straight to the source.

-------------------------------------------------------------------------------


REQUIREMENTS:
-------------------------------------------------------------------------------

Required:
  * ALSA >= 1.0.18
  * JACK (JACK or JACK2/jackdmp should work).
  * libsamplerate
  * GTK-2 (version 2.8 or later recommended).
  * Realtime Linux Kernel (latest 3.0.x-rt or newer recommended).
  * 1.6 GHz or faster CPU (multiple core, 64-bit preferred).

Optional:
  * LASH >= 0.5.4.
  * libuuid (required by LASH).

-------------------------------------------------------------------------------


COMPILING AND INSTALLING PHASEX:
-------------------------------------------------------------------------------

For a standard, multitimbral configuration optimized for your CPU,
run the following:

    cd phasex
    aclocal && autoconf && automake && autoheader
    ./configure --enable-arch=native --enable-parts=2
    make
    make install

Other useful configure flags are --enable-debug=, --enable-32bit,
--enable-cpu-power=, and --without-lash.

See INSTALL for full compilation and installation instructions.

-------------------------------------------------------------------------------


RUNNING PHASEX:
-------------------------------------------------------------------------------

Usage:  phasex [options] [<patch>[,<patch>[,<patch>[,...]]]]

  -c, --config-file=     Alternate config (takes precedence over default
                             config file and command line options.
  -A, --audio-driver=    Audio driver:  alsa or jack.
  -a, --audio-device=    ALSA device name (hw:x,y format).
  -r, --sample-rate=     Audio sample rate (ALSA only).
  -p, --latency-periods= Number of buffer latency periods (ALSA only).
  -s, --period-size=     Buffer period size (power of 2, ALSA only).
  -M, --midi-driver=     MIDI driver:  jack, alsa-seq, alsa-raw, generic.
  -m, --midi-port=       MIDI input port or device name (driver specific).
  -f, --fullscreen       Start GUI in fullscreen mode.
  -x, --maximize         Start GUI with main window maximized.
  -b, --bpm=             Override BPM in patch bank and lock BPM parameter.
  -t, --tuning=          Base tuning frequency for A4 (default 440 Hz).
  -i, --input=           Comma separated pair of audio input matches.
  -o, --output=          Comma separated pair of audio output matches.
  -O, --oversample       Use double the sample rate for internal math.
  -U, --undersample      Use half the sample rate for internal math.
  -G, --no-gui           Run PHASEX without starting the GUI.
  -D, --session-dir=     Set directory for loading initial session.
  -u, --uuid=            Set UUID for JACK Session handling.
  -d, --debug=           Debug class (Can be repeated. See debug.c).
  -l, --list             Scan and list audio and MIDI devices.
  -v, --version          Display version and exit.
  -h, --help             Display this help message and probe ALSA hardware.

LASH Options:
  -P, --lash-project=    LASH project name.
  -S, --lash-server=     LASH server address.
  -I, --lash-id=         LASH client ID.
  -L, --disable-lash     Disable LASH completely for the current session.

Please note that unless an alternate config file is used, all command
line options take precedence over settings saved in the config file.

If using phasex with JACK, make sure jackd is running (and configured
for your system) before running phasex.  If jackd is not running,
PHASEX will fall back to using the ALSA drivers.  If you use software
like qjackctl to handle your audio and MIDI patchbay, then the command
line port connection options aren't necessary.  The -i and -o options
accept comma separated substring pairs to match on JACK audio port
names.  The -m option takes a comma separated list of MIDI ports (X:Y
for ALSA Seq, hw:X,Y for ALSA Raw, or device file for generic raw
MIDI).  For example:

    phasex -A jack -i _1,_2 -o _1,_2 -M alsa-seq -m 16:0,20:0

will match JACK ports alsa_pcm:capture_1 and alsa_pcm:capture_2 for
input, alsa_pcm:playback_1 and alsa_pcm:playback_2 for output, and the
first two ALSA sequencer hardware MIDI input ports with relatively
recent versions of JACK and ALSA.  (Jack2/jackdmp uses 'system'
instead of 'alsa_pcm'.  ALSA port designations vary from system to
system.)

To view a full technical description of any parameter, simply
middle-click on the parameter label.  Similarly, a right-click on any
parameter label allows on-the-fly mapping of any MIDI controller to
any parameter (up to 15 parameters may be mapped to a single MIDI
controller).  All remaining features are directly visible and
accessible through the GUI and its (very short) menus.

Patch bank storage works like it does on just about any modern
hardware synth, with one exception: Patches themselves are stored by
name in the filesystem, which are then mapped by program number in the
patch bank.  The individual program slots in the patch bank simply
reference the stored patches by name.  In Autosave mode, a patch is
automatically saved before a new patch is loaded during a program
change without any user intervention.  Autosave mode is intended for
use during sound design sessions (and should be avoided the rest of
the time to keep from overwriting patches).  In Warn mode, warnings
will be issued will be issued when unsaved modifications to the patch
will be lost.  In Protect mode, program changes always take effect
immediately, so any patch modifications are quietly discarded and
patches never get (re)saved unless they are saved explicitly.

-------------------------------------------------------------------------------

In the event of catastrophic failure, and PHASEX fails to start, edit
~/.phasex/phasex.cfg and look for the last settings change, or simply
remove phasex.cfg (but not any directories) and PHASEX will start with
the default config and auto-detect your setup all over again.

-------------------------------------------------------------------------------


LICENSING AND COPYRIGHT:
-------------------------------------------------------------------------------

PHASEX is distributed under the terms of the GNU Public License,
version 3.  See LICENSE for details.

    Copyright (C) 1999-2013 William Weston <whw@linuxmail.org>.

With portions of and contributions to the PHASEX source:

    Copyright (C) 2010 Anton Kormakov.
    Copyright (C) 2007 Peter Shorthose.
    Copyright (C) 2004 Sean Bolton.
    Copyright (C) 1999 Tony Garnock-Jones.

See AUTHORS for details.

-------------------------------------------------------------------------------


OBTAINING PHASEX:
-------------------------------------------------------------------------------

Currently, PHASEX dev sources are only available via git:

	git clone https://github.com/williamweston/phasex.git

RPM and .tar.gz packages will be made available with the
upcoming v0.15.0 stable release.

-------------------------------------------------------------------------------


CONTACTING THE AUTHOR:
-------------------------------------------------------------------------------

The primary goal of the PHASEX project is to offer a free software
synthesizer for GNU/Linux/ALSA/JACK systems that is useful in a MIDI
production environment.  Please send any kind of feedback you will for
PHASEX.

What do you like about PHASEX?
What don't you like about PHASEX?
What features do you think are missing?
What would you do differently?
What are you looking for in a UI?
Is there anything preventing you from using PHASEX dependably on stage?
Is there anything preventing you from using PHASEX dependably in the studio?

Anything you say can only influence me to make PHASEX better.


Kind Regards,

--William Weston <whw@linuxmail.org>

-------------------------------------------------------------------------------