1. Getting Started

In most cases ZynAddSubFX is used it will not alone, and it will be linked with other programs.

1.1. MIDI

MIDI can be used to connect other applications to ZynAddSubFX. Under ALSA on Linux the standard tool to connect ZynAddSubFX’s MIDI is aconnect.

ZynAddSubFX has one incomming MIDI port. Once another application is connected to this port, then it should be able to send information on notes, pitches, and modulations to ZynAddSubFX. For more specific information see INSERT CHAPTER NAME HERE.

1.2. JACK

JACK can be used to connect the output of ZynAddSubFX to other applications.

2. Filters

In ZynAddSubFX filters can be used at several different stages to increase or decrease a defined set of frequencys.

2.1. Types

ZynAddSubFX currently supports a wide set of filters that it can provide

images/filter0.png

2.2. Values

Each of these filters will be affected by their Q values, number of poles, and cutoff values.

The folowing diagram shows the frequency response under different Q values:

images/filter1.png

The folowing diagram shows the frequency response under a different number of poles:

images/filter2.png

2.3. User Interface

A picture of the UI will go here

3. LFO

3.1. Introduction

"LFO" means Low Frequency Oscillator. These oscillators are not used to make sounds by themselves, but they changes somes parameters (like the frequencies, the amplitudes or the filters).

The LFOs has some basic parameters:

  • Delay: This parameter sets how much time takes since the start of the note to the start of the LFO

  • Start Phase: The possition that a LFO will start at

  • Frequency: How fast the LFO is (i.e. how fast the parameter’s controlled by the LFO changes)

  • Depth: The amplitude of the LFO (i.e. how much the parameter’s controlled by the LFO changes)

images/lfo0.png

Another important LFO parameter is the shape. There are many LFO Types according to the shape. ZynAddSubFX supports the folowing LFO shapes:

images/lfo1.png

Another parameter is the LFO Randomness. It modifies the LFO amplitude or the LFO frequency at random. In ZynAddSubFX you can choose how much the LFO frequency or LFO amplitude changes by this parameter. In the folowing images are shown some examples of randomness and how changes the shape of a triangle LFO.

images/lfo2.png

Other parameters are:

  • Continous mode: If this mode is used, the LFO will not start from "zero" on each new note, but it will be continuous. This is very usefull if you apply on filters to make interesting sweeps.

  • Stretch: It controlls how much the LFO frequency changes according to the note’s frequency. It can vary from negative stretch (the LFO frequency is decreased on higher notes) to zero (the LFO frequency will be the same on all notes) to positive stretch (the LFO frequency will be increased on higher notes).

3.2. User Interface

In ZynAddSubFX, LFO parameters are shown as:

images/uilfo.jpg

Theese parameters are:

  • Freq: LFO Frequency

  • Depth: LFO Depth

  • Start: LFO Start Phase - If this knob is at the lowest value, the LFO Start Phase will be random.

  • Delay: LFO Delay

  • A.R.: LFO Amplitude Randomnes

  • F.R.: LFO Frequency Randomness

  • C.: LFO Continous Mode

  • Str.: LFO Stretch - in the image above the LFO stretch is set to zero

4. Envelopes

4.1. Introduction

Envelopes control how the amplitude, the frequency, or the filter changes over time.

4.2. Amplitude Envelopes

These envelopes controls the amplitude of the sound. In ZynAddSubFX, amplitude envelopes can be linear or logarithmic. In the next image, it is shown the differences between these envelopes.

Alt text

The amplitude envelope is divided into:

  • Attack: Begins at the Note On. The volume starts from 0 to the maximum. In ZynAddSubFX, the attack is always linear.

  • Decay: The volume drops from the maximum value to a level called "Sustain level"

  • Sustain: The volume remains constant until the key is depressed (Note Off). After this, the last stage take place.

  • Release: The volume drops to zero

4.3. Frequency Envelopes

These envelopes controls the frequency (more exactly, the pitch) of the oscillators. The following picture draws the stages of these envelopes.

Alt text

The dotted line represents the real pitch of the sound without the envelope.

The frequency envelopes are divided into 3 stages:

  • Attack: Begins at the Note On. The frequency starts from a certain value and glides to the real frequency of the note.

  • Sustain: The frequency is the same on over the sustain period

  • Release: This stage begins on Note Off and glides the frequency of the note to a certain value

4.4. Filter Envelopes

These envelopes controls the cutoff frequency of the filters and are divided into

Alt Text

  • Attack: Begins at the Note On. The cutoff frequency starts from a certain value and glides to another value

  • Decay: The cutoff frequency continues to glide to the real cutoff frequency value of the filter (dotted line)

  • Sustain: the cutoff frequency is the same on over the sustain period (dotted line)

  • Release: this stage begins on Note Off and glides the filter cutoff frequency of the note to a certain value

4.5. Freemode Envelopes

For all envelope there is a mode that allows the user to set an arbitrary number of stages and control points. This mode is called Freemode.

Alt Text

Only stage that always remains defined is the Sustain, where the envelopes freezes until a Note Off event.

4.6. User Interface

All the envelope types has some common controls:

  • E: Shows a window that you can view the real envelope shape or convert to free mode to edit it

  • Stretch: How the envelope is stretched according the note. On the higher notes the envelopes are shorter than lower notes. In the leftmost value, the stretch is zero. The rightmost use a stretch of 200%; this means that the envelope is stretched about 4 times/octave.

  • frcR: Forced release. This means that if this option is turned on, the release will go to the final value, even if the sustain stage is not reached. Usually, this must be set.

The parameters for Amplitude Envelopes for ZynAddSubFX are:

Alt Text

  • A.dt: Attack duration

  • D.dt: Decay duration

  • S.Val: Sustain value

  • R.dt: Release time

  • L: If this option is set, the envelope is linear, otherwise, it will be logarithmic

For Frequency Envelopes the interface has the following parameters:

Alt Text

  • A.val: Attack value

  • A.dt: Attack duration

  • R.dt: Release time

  • R.val: Release value

Filter Envelopes has the parameters:

Alt Text

  • A.val: Attack value

  • A.dt: Attack duration

  • D.val: Decay value

  • D.dt: Decay time

  • R.dt: Release time

  • R.val: Release value

The Freemode envelopes has a separate window to set the parameters and controls:

images/uienvelope0.jpg

  • Control points: You can move the points using the mouse. In the right on the windows, it is shown the total duration of the envelope. If the mouse button will be pressed on a control point, it will be shown the duration of the stage where the point is.

  • FreeMode: this button activates or deactivates the freemode mode.

  • Add Point: Adds the point next to the current selected point. You can select a point by clicking on it.

  • Delete point: Removes the point from the envelope.

  • Sust.: Set the sustain point. It is shown using the yellow line.

  • Str.: Envelope stretch

5. Add Synth

Additive Synthesis is one of the three major synthesis engines available in ZynAddSubFX. Overall it adds together several voices with an oscillator as their sound source.

5.1. High Level (Global)

From a high level perspective, Add synth can be understood with this block diagram:

gen/ad-note.png

The red/yellow nodes are controllable with the main adsynth window.

images/ad-global.png

The sum of the voices are passed through filters and amplification to produce the final sound. This could lead one to think that ad-note is just a bunch of minor postprocessing and at this level much of the sound generation is hidden.

5.2. Voices

The voice gives access to a similar setup to the global parameters and then some more, such as the modulator, oscillator, and unison features.

images/ad-voice.png

5.2.1. Modulation

Within the options for modulation, one can select: * Morph * Ring Modulation * Phase Modulation * Frequency Modulation * Disabled

5.2.2. Unison

6. Controller

./images/uicontroller.png

6.1. General

  • ModWh: Modullation Wheel depth

  • Exp MWh: Exponental Modulation Wheel (changes modulation scale to exponental)

  • BwDpth: Bandwidth Depth

  • Exp BW: Exponental Bandwidth (changes badwidth scale to exponental)

  • PanDpth: Panning Depth

  • FltQ: Filter Q (ressonance) depth

  • FltCut Filter Cutoff frequency depth

  • Expr: enable/disable expression

  • Vol: enable/disable receiving volume controller

  • FMamp: enable/disable receiving Modulation Amplitude controller (76)

  • Sustain: enable/disable sustain pedal

  • PWheelB.Rng (cents): Pitch Wheel Bend Range (cents; 100 cents = 1 halftone)

6.2. Portamento

  • Rcv.: If the part receives portamento On/Off (65) controller

  • time: The duration of the portamento

  • thresh: The threshold of the portamento. It represents the minimum or the maximum number of halftones (or hundried cents) required to start the portamento. The difference is computed between the last note and current note.

  • th.type: The threshold type. Checked means that the portamento activates when the difference of frequencies is above the threshold ("thresh"); not checked is for below the threshold.

Note
 The threshold refers to the frequencies and not to MIDI notes (you should consider this if you use microtonal scales).

6.2.1. Proportinal Portamento

  • Propt.: If the portamento is proportinal to ratio of frequencies

  • Prp. Rate: Ratio needed to double the time of portamento

  • Prp. Dpth: The divergence from

6.3. Resonance

  • CFdpth: resonance center controller depth

  • BWdpth: resonance bandwidth controller depth

7. NRPN (Non Registered Parameters Number)

NRPNs can control all system and insertion effect parameters. For example, you may change the reverb time when playing to keyboard or flanger’s lfo frequency. You can disable the NRPN receiving by deselecting the "NRPN" checkbox from the main window (near "Master Keyshift" counter). The controls can be sent on any midi channel (the midi channels numbers are ignored).

The parameters are:

  • NRPN coarse (99 or 0x63)sets the system/insertion effects (4 for system effects or 8 for insertion effects)

  • NRPN fine (98 or 0x62)sets the number of the effect (first effect is 0)

  • Data entry coarse (6) sets the parameter number of effect to change(see below)

  • Data entry fine (26) sets the parameter of the effect

You have to send NRPN coarse/fine before sending Data entry coarse/fine. If the effect/parameter doesn’t exists or is set to none, then the NRPN is ignored.

Example(all values in this example are hex):

B0 63 08 // Select the insertion effects
B0 62 01 // Select the second effect (remember: the first is 00 and not 01)
B0 06 00 // Select the effect parameter 00
B0 26 7F // Change the parameter of effect to the value 7F (127)
Warning
 Changing of some of the effect parameters produces clicks when sounds passes thru these effects. I advise you to change only when the sound volume that passes thru the effect to be very low (or silence). Some parameters produce clicks when are changed very fast.

Here are the effects parameter number (for Data entry coarse). The parameters that produces clicks are written in red and have (AC) after their entry (always clicks). The parameter that produces clicks only when they are changed fast are written in orange and have a (FC) after the entry (Fast Clicks). Most parameters has the range from 0 to 127. When parameters have another range, it is written as [low…high] .

7.1. Reverb

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - Reverb Time
03 - Initial Delay (FC)
04 - Initial Delay Feedback
05 - reserved
06 - reserved
07 - Low Pass
08 - High Pass
09 - High Frequency Damping [64..127] 64=no damping
10 - Reverb Type [0..1] 0 - Random, 1 - Freeverb (AC)
11 - Room Size (AC)

7.2. Echo

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - Delay (AC)
03 - Delay between left and right (AC)
04 - Left/Right Crossing (FC)
05 - Feedback
06 - High Frequency Damp

7.3. Chorus

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - LFO Frequency
03 - LFO Randomness
04 - LFO Type [0..1]
05 - LFO Stereo Difference
06 - LFO Depth
07 - Delay
08 - Feedback
09 - Left/Right Crossing (FC)
10 - reserved
11 - Mode [0..1] (0=add, 1=subtract) (AC)

7.4. Phaser

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - LFO Frequency
03 - LFO Randomness
04 - LFO Type [0..1]
05 - LFO Stereo Difference
06 - LFO Depth
07 - Feedback
08 - Number of stages [0..11] (AC)
09 - Let/Right Crossing (FC)
10 - Mode [0..1] (0=add, 1=subtract) (AC)
11 - Phase

7.5. AlienWah

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - LFO Frequency
03 - LFO Randomness
04 - LFO Type [0..1]
05 - LFO Stereo Difference
06 - LFO Depth
07 - Feedback
08 - Delay [0..100]
09 - Left/Right Crossing (FC)
10 - Phase

7.6. Distorsion

00 - Volume or Dry/Wet (FC)
01 - Pan (FC)
02 - Left/Right Crossing
03 - Drive (FC)
04 - Level (FC)
05 - Type [0..11]
06 - Invert the signal (negate) [0..1]
07 - Low Pass
08 - High Pass
09 - Mode [0.1] (0=mono,1=stereo)

7.7. EQ

00 - Gain (FC)

All other settings of the EQ are shown in a different way. The N represent the band ("B." setting in the UI) and the first band is 0 (and not 1), like it is shown in the UI. Change the "N" with the band you like. If you want to change a band that doesn’t exist, the NRPN will be ignored.

10+N*5 - Change the mode of the filter [0..9] (AC)
11+N*5 - Band’s filter frequency
12+N*5 - Band’s filter gain
13+N*5 - Band’s filter Q (bandwidth or resonance)
14+N*5 - reserved

Example of setting the gain on the second band:

  1. The bands start counting from 0, so the second band is 1 ⇒ N=1.

  2. The formula is 12+N*5 ⇒ 12+1*5=17, so the number of effect parameter

  3. (for Data entry coarse) is 17.

8. Persistence

As with most applications ZynAddSubFX allows for one to ave your work and reload it.

8.1. Saving it all

One of the simplest ways to save your work is to save the entire session. This can be done through the File menu and will result in the creation of an .xmz file. Once created, this file will hold the settings for all settings within that session, such as microtonal tunings, all patches, system effects, insertion effects, etc…

8.2. Saving Parts

In many cases saving everything is not what is desired. Saving a patch later on is one such example.

8.2.1. Patches

In order to save a patch, one can either save it from the instruments menu or through the bank window.

With the instrument menu, one can just save the file to any given location with the .xiz extension.

With the banks menu, one can assign a patch to a given slot with a bank. This instrument will remain here for future use until it is deleted. To see the physical location of the .xiz file, one should check the File→Settings→Bank_Root_Dirs window to see the paths for banks.

Note
 You need to have write permissions to add instruments to the bank.

8.2.2. Presets

Have a favorite setting for an envelope, a difficult to reproduce oscillator? Then presets are for you. Presets allow for one to save the settings for any of the components which support copy/paste operations. This is done with preset files (.xpz), which get stored in the folders indicated by File→Settings→Preset_Root_Dirs.

8.3. Summary

Extension Summary
xmz Everything
xiz Instrument
xsz Scale Settings
xpz Presets

9. Appendex A: MIDI Defaults

Default MIDI Connections
001 - Modulation Wheel
007 - Volume
010 - Pan
011 - Expression
064 - Sustain
065 - Portamento Enable
071 - Filter Q
074 - Filter Cutoff
075 - Bandwidth(*)
076 - Modulation Amplitude(*)
077 - Resonance Center Frequency(*)
078 - Resonance Bandwidth(*)
120 - All Sounds Off
121 - Reset All Controllers
123 - All Notes Off

The entries with (*) are not within the General Midi specification

10. Appendix B: Building ZynAddSubFX

10.1. Introduction to CMake

Note: This section is mostly copied from the OpenSceneGraph wiki, at: http://www.openscenegraph.org/projects/osg/wiki/Build/CMake

ZynAddSubFX uses CMake as its unified build system. CMake is able to read simple build scripts from the source tree and create from this a platform-specific build system. This build system can be in the form of VisualStudio project files, Unix Makefiles or XCode project files. CMake is able to automatically locate external dependencies, and allows you to toggle on/off module compilation and configure various build options.

The use of a unified build system has allowed to avoid build breakages that were common in the previous build method of maintaining three separate build targets for VisualStudio, Unix "make" and XCode. It also reduces the maintenance burden for core developers and contributors. Taken together usage of CMake should result in better consistency and more stable builds across all platforms for end users and a greater productivity in development of new versions. Hopefully with greater consistency of builds across platforms it will be easier for developers to use the development version of ZynAddSubFX and help contribute to its testing and refinement, leading to a high-quality code base.

10.2. Quick start guide

For the impatient ones, here is a quick guide on how to immediately build ZynAddSubFX from source.

Note: This assumes that you already have a copy of the source.

#enter the source directory
cd zynaddsubfx

#make a directory for an out-of-source build
mkdir build
cd build

#generate a cmake build project here from the cmake root, which is
#found in the directory below the current one
cmake ..

#OPTIONAL: Adjust compile variables in the Cache file:
ccmake .

#And finally, build as usual using make
make

11. Appendix C: Getting ZynAddSubFX

Usually there are several methods to obtain a copy of ZynAddSubFX.

SourceForge

http://sourceforge.net/projects/zynaddsubfx/files/

Distribuition

apt/yum/others

Git

git://zynaddsubfx.git.sourceforge.net/gitroot/zynaddsubfx/zynaddsubfx

11.1. Introduction to Git

For those who want to live on the bleeding edge or who want to assist with making sure that the next release has fewer bugs, you will want to get aquanted with git. Git is used to manage the source code for this project and can be used to quickly and easily get an up-to-date copy of the source code.

11.1.1. Getting the Source Code

In order to get a copy of the ZynAddSubFX source code, all that needs to be done is:

git clone git://zynaddsubfx.git.sourceforge.net/gitroot/zynaddsubfx/zynaddsubfx

cd zynaddsubfx

You should now be in the directory of the source code.

For simple steps on building, please see Appendix B of the manual.

11.1.2. Checking out a branch

Lets say that development has extended into the creation of a new feature that you want to preview. For the sake of this guide, lets assume that the name of the branch that the feature is on is foo.

#checkout the foo branch from sourceforge
git checkout --track -b foo origin/foo

#lets checkout the primary branch again
git checkout master

#hop back to the other branch
git checkout foo

Now one should be able to change branches and go into the build directory (as described in Appendix B) and recompile ZynAddSubFX.

Note
 When using branches other than the master be aware that stability may suffer