Plugins

The SynthEdit Music Plugin Standard (SEM for short) is an advanced API for MIDI and Audio plugins.

SEM Version 3 is a clean modern API designed for power and simplicity. SEM is easy to use yet more powerful than other plugin standards. SEM V3 is supported in the upcoming SynthEdit Version 1.1, this is not officially available finished yet but you can try the preview.

Download SynthEdit 1.1 preview [03-Jul-08] ALPHA V 1.113

Download SEM V3 SDK

Get MS C++ 2005 Runtime files (only if SE 1.1 fails to run)

WARNING: SynthEdit preview version is not fully tested.

The program may corrupt your SynthEdit projects (*.se1) please back them up first. Loading a project into SE 1.1 upgrades it (irreversiby) it will no longer load in previous versions. Please do not load any valuable .se1 projects into this version.
Please report any bugs, please send Jeff your suggestions for improvements to the SDK, or better - post and discuss on the SDK group. Initial SDK documentation is below, please feel free to ask any questions on the SDK group, I am happy to help.
I suggest you retain your existing SynthEdit version for serious work ( e.g. before installing preview, rename C:\Program Files\SynthEdit -> SynthEdit_V1 ).
NOTE: When using two versions please copy the SE 1.1 SEMS to your regular modules folder and copy the 1.1 prefabs to your regular prefabs folder.
This version is not officially in beta stage yet, several small features need completing. Thanks, Jeff.

Windows 2000 users

To enable runtime support for Visual Studio V8, you will need to download these dlls: MFC80U.DLL MSVCR80.DLL MSVCP80.DLL. Put them in C:\Program Files\SynthEdit\

DEV C++ Compiler Notes
Istall DEV C++, Install gcc V4.1 (or better) from Tools menu. 3.4 don't support templates very well.

File, New Project, DLL, Add module files (Gain.cpp, Gain.h)
Project-Project Options - Directories - Include Directories - Add se_sdk3 folder

SE Launcher

Written by Andreas, the SE_Launcher is a small helper application that can be used to keep to different Synthedit Installations apart that run on the the same computer. This utility aims to make testing of Synthedit 1.1 a bit easier by removing or at least reducing problems that can occur when Synthedit 1.0 is used on the same computer.

Download SE Launcher.

SE 1.1 FAQ

When a module isn't found, I get the following error message: "Sorry, can't upgrade this project without the following SEM modules. They may be available from the internet: (list of modules)"

I understand that's a hassle. This message is one-time thing when first opening an older project. SynthEdit 1.1 stores much more information about each module inside the project file, so that (in future) when you open a project without having a required module - SE can show the missing module correctly (with all the right plug names and stuff). i.e. the intention of this feature is to make it easier to open a project without some modules. The downside is SE 1.1 needs (just once) to extract some info from all modules referenced in the project file.

Why change the directions of pins of existing sub-controls?

Just to clarify: the pins still behave the same. They are only drawn 'flipped' left-to-right.
You can revert to the old look from the File-Properties screen.

The reason for this is to make GUI pins more intuitive. For example GUI DR_IN pins (previously drawn on the left) are actually "masters":
- They can have multiple connections.
- They have higher precedence over DR_OUT, i.e. at load time it's these pins that are set first, thereby overriding any connected pins.
This behavior is like a grey (DSP) Output pin. It's makes sense to draw these pins on the right.

Likewise GUI DR_OUT pins are 'slaves' (previously drawn on the right) and can have only one connection, behavior more like an input pin.

SynthEdit's GUI pins have caused a lot of confusion and frustration, partly because of that un-intuitive, inconsistent behavior. The fix is that SDK2 Modules now draw with the GUI pins swapped. DR_IN on the right, DR_OUT on the left. I was much divided in my own mind as to whether to change the appearance. In the end I decided that the long-term usability improvement outweighed the short-term pain, and also the backward-compatible GUI pins option will help ease the transition.

See menu... File->Properties->Reverse GUI pins. - draws GUI pins and wires same as SE 1.0

Sub Control 'Style' pin

SynthEdit's updated Sub Controls don't use 'List' type pins. Instead of a 'Style' pin to selection font styles, there is now a Text Style pin. Instead of selecting the style from a list, enter the style name directly. e.g. 'Heading 1'. the list of available styles is in the /skins/default/global.txt file.

Container 'Skin' property

This item has been moved. To select skins, right click the Panel View and Select 'Skin...".

Container module's 'Controls on Parent'

In previous SynthEdit versions, 'Controls on Parent' was on the left side. This was a mistake because it wasn't possible to connect a standard patch-memory module directly to the pin.

SE 1.1 fixes this by providing 'Controls on Parent' on the right...

To allow old projects to function, the old pin is also still available. if you load a project that uses the old left-side pin, SynthEdit provides two pins, one on each side...

Note: The above screenshots taken with 'Reverse GUI pins' ON (like SE 1.0).

Feedback path to Patch Automator

The Patch Automator is a special module. It supervises all the other control modules (sliders etc). Because of this, you can't place any control 'upstream' of it. SynthEdit 1.0 made an exception where you could have a List-Entry connected to it's 'Channel' pin. This is no longer allowed...

Use instead the new 'Channel' sub-control pin...

Side-by-side MIDI-CVs

This shows two Containers, each having a 'MIDI to CV', but no 'Patch Automator'. Unfortunatly, due to an unintended behaviour of the new polyphonic automation system, this will crash SynthEdit 1.1. The workarround is to put a 'Patch Automator' in each container.

SDK Version 3 Documentation

Code generator

To help convert your modules to the new SDK, SE includes a simple code generator. On your existing module... Right-click->Build Code Skeleton. This creates the template code for your module in the folder "C:\SE\My Projects\modules_source" - you need to create that folder first. The template doesn't do any processing, it's just a non-functioning module with the pins and module-name etc setup for you, to save you typing the boring bits. NOTE - SE SDK3 does not yet support auto-duplicating pins, and does support GUI DT_ENUM pins. Avoid any modules with those for the time being.

SEM Logos

large version

Types of Windows

SynthEdit supports two types of windows.

1 - Standard Microsoft Window (Native)

These are the plain regular windows as used in most applications. They are always rectangular and always obscure any window 'behind' them.

Advantages

Fast to draw (CPU efficient).
Support for entire Microsoft Windows Graphics API, and for OS functions that require a real window-handle (HWND) e.g. timers.

Disadvantages

No transparancy.

2 - SynthEdit Composited Windows

Created to support non-rectangular shapes, these are still actually rectangular but support transparent pixels. Here the red circle is partially transparent.

Advantages:

transparancy.
non-rectangualr shapes.
anti-aliased edges.

Disadvantages

Slower to draw (more CPU).
Support only basic windows messages. e.g. no scrollwheel support.

Specify which type by deriving your from the appropriate base class. In your graphics class header file, and also in your XML file...

For a native window...

MyPluginGui.h

            class MyGui : public
            SeGuiWindowsGfxBase

            {

            MyPlugin.xml

            <Plugin id="SynthEdit Scope3" 
            graphicsApi="Composited">

For a composited window...

            class MyGui : public
            SeGuiCompositedGfxBase

            {

             
            <Plugin id="SynthEdit Scope3" 
            graphicsApi="HWND">

Customizing the popup context menu

You can customize SynthEdit's right-click context menu.

In your .h file...

                virtual int32_t MP_STDCALL onCreateContextMenu();

                virtual int32_t MP_STDCALL onContextMenu(
            int32_t selection );

In your .cpp file...

            // Add custom items to right-click menu.

            int32_t MyGui::onCreateContextMenu()

            {

                getHost()->addContextMenuItem( L"Cat",
            0, 0 );

                getHost()->addContextMenuItem( L"Dog",
            1, 0 );

                return gmpi::MP_OK;

            }

            // act on user slelecting right-click item.

            int32_t MyGui::onContextMenu( int32_t selection )

            {

                switch( selection )

                {

                case 0:

                    // 'Cat' selected

                    break;

                case 1:

                    // 'Dog' selected

                    break;

                };

                return gmpi::MP_OK;

            }

Right-click handler

To override SynthEdit's right-click handler. NOTE: If possible please avoid doing this as it disables SynthEdit's pop up menu system.

In your .h file...

                // This handles the Windows message loop.

                // Add here to override right-click behaviour.

                virtual LRESULT MsgProc( HWND hwnd,
            UINT message, WPARAM wParam, LPARAM lParam );

                int32_t onRButtonDown( UINT flags, POINT point );

                int32_t onRButtonUp( UINT flags, POINT point );

In your .cpp file...

            // Test overriding right-click handling.

            // WARNING: This will disable SynthEdit's right-click menu. 
                If possible please avoid taking

            // right-click for your own use.

            LRESULT MyGui::MsgProc( HWND hwnd, UINT message, WPARAM wParam, LPARAM
            lParam )

            {

                switch (message)

                {

                    case (WM_RBUTTONDOWN):

                        {

                            POINT p;

                            p.x = MAKEPOINTS(lParam).x;
        
                            p.y = MAKEPOINTS(lParam).y;
        
                            onRButtonDown( (UINT) wParam,
            p );

                        }

                        return
            1;

                        break;

                    case (WM_RBUTTONUP):

                        {

                            POINT p;

                            p.x = MAKEPOINTS(lParam).x;
        
                            p.y = MAKEPOINTS(lParam).y;
        
                            onRButtonUp( (UINT) wParam,
            p );

                        }

                        return
            1;

                        break;

                    default:

                        return
            SeGuiWindowsGfxBase::MsgProc( hwnd, message, wParam, lParam );

                        break;

                }

            }

            int32_t MyGui::onRButtonDown( UINT flags, POINT point )

            {

                return gmpi::MP_OK;

            }

            int32_t MyGui::onRButtonUp( UINT flags, POINT point )

            {

                return gmpi::MP_OK;

            }

SEM XML

The old SEM SDK described modules and pins in code...

                // describe the pins (plugs)

                bool Module::getPinProperties (long
                index, SEPinProperties* properties)

                {

                    switch( index )     
                                       
                  // !!TODO!! list your in / out plugs

                    {

                        // typical input plug (inputs
                    are listed first)

                    case 0:

                        properties->name         
                      = "Input";

                        properties->variable_address    = &input1_buffer;

                        properties->direction      
                    = DR_IN;

                        properties->datatype         
                  = DT_FSAMPLE;

                        properties->default_value      
                = "8";

                        break;

SDK3 introduces an easier, compact format based on XML...

                    <Audio>

                      <Pin id="0" 
                            name="Input" direction="in" 
                datatype="float" 
                        rate="audio" default="8"/>

This new method results in smaller executable files and is easier to add new features without breaking old code.

XML Plugin Properties

id
name
category
helpUrl
graphicsApi{HWND,composited,none}
polyphonicSource{ true, false }
polyphonicAggregator{ true, false }
cloned{ true, false }
voiceMonitorIgnore{ true, false }
GUI
Parameters
Pins

XML Pin Properties

id
name
datatype {float, int, text, blob, midi, bool, enum (DSP only. not fully supported)}
default
direction {in,out}
rate {audio} - float pins only.
private{ true, false }
autoRename{ true, false }
isFilename{ true, false }
linearInput{ true, false }
ignorePatchChange{ true, false }
autoDuplicate{ true, false }
isMinimised{ true, false }
isPolyphonic{ true, false }
autoConfigureParameter{ true, false }
parameterId
parameterField{ Value, writeable only in SynthEdit environment -ShortName , MenuItems,MenuSelection,RangeMinimum,RangeMaximum,EnumList,FileExtension
IgnoreProgramChange,Private,Automation,Automation Sysex,Default,Grab,Normalized }
metadata
notes
hostConnect

SEM Supported Features

Cross platform. Written in standard C++. Also useable from C.
Arbitrary number of Audio, MIDI, and Control inputs and outputs.
support arbitrary sample rates.
No plugin functions are re-entrant or asynchronous. Plugins require no locks or thread-aware code. Communication between Audio and Graphics code is abitrated by the host.
audio data processed in blocks of sample frames.
Implement a time-stamped, sample-accurate event system. Events are how realtime signals, including control changes, are represented.
GMPI must provide a music-time clock.
Changes to music-time variables, such as tempo and meter , transport state, playback location are delivered as timestamped events.
Provides a performance optimization mechanism for handling silent audio streams.
Parameters support at the following parameter datatypes:
- float
- integer
- string
- filename
- enumerated list
- boolean value
- opaque data
Parameters support both natural value and normalized value.
Parameters support metadata (maximum value, minimum value etc).
Parameters can be marked as either hidden or visible. Hidden parameters should not be represented in UIs.
parameter maybe either stateful or non-stateful.
All parameters are automatable.
It is possible to have many listeners for parameter changes. Managing listeners is the host's responsibility.
NEW IN SEM - Polyphonic parameters are supported.
Patch-change and Patch load/save provided by host. No plugin code required.
Plugins may have zero or more UIs, including GUIs. New in SEM - UI's may control 1 or more plugins.
Host supports plugins with no UI.
Allows arbitrary toolkits (including platform-specific) UIs via plug-in UI interfaces.
Supports out-of-process UIs. Decoupled design supports UI over network.
All communication between UI and plugin is via standard control signals.
GUIs are able to set parameters, read parameters (value and metadata), be notified when a parameter changes, store and recall programs, tell the host to load and save banks/patches, and tell the host to apply "MIDI learn" to a parameter.
Hosts are not required to support any external music control protocol, including MIDI. However MIDI is fully supported including SYSEX.
plugins can act as MIDI receivers, processors, and/or senders. Multiple MIDI in/out supported.
Plugins which intend their parameters to be driven by MIDI can expose a mapping of MIDI messages to parameters. New in SEM - including polyphonic MIDI messages to polyphonic parameters.
Instrument plugins should be fundamentally no different than effects plugins.
Provides a note control mechanism beyond MIDI. This includes the ability to turn specific notes on and off. Note control provides the ability to turn on the same note pitch more than once, and identify exactly which instance of a note an event is intended for.
Fractional pitch numbers are supported.
Voice management is the domain of the instrument. All that the host sees is a voice ID.
Instrument can define an arbitrary set of parameters that applies to each voice.
Plugins are dynamically loadable in their host environments.
Each plugin (dynamically loadable) file may contain more than one plugin.
Installing a plugin is possible by simply unpacking and copying the plugin bundle to a directory. Plugin vendors may require additional steps (such as registration or unlocking) for their own plugins to be functional.
Plugins may self-categorize into a set of GMPI defined categories via their metadata.
plugins are localizable. TODO The host must expose the current language preferences to plugins.
String encoding currently 16 bit wide char, could be made platform specific.
The GMPI API must be versioned. TODO.
Plugins are uniquely identifiable by URI or other string. Does not rely on a central authority for ID assignments.
support wrapper plugins for other plugin APIs. TODO test this.
sample plugins available.
TODO sample host code .
The SDK is released under a BSD license and are freely available in source form to any interested party no licensing fees apply.
Provides a way for a plugin to obtain information about the host it runs in. This information must contain at least a unique host identification and a host version number.
64 bit float and integer parameter types.

SEM is an implementation of GMPI (Generalized Music Plugin Interface) with a few extensions for SynthEdit. Some less crucial GMPI features are not supported yet.

GMPI requirements not supported

NO cross platform library. Many man-years already spent creating cross-platform toolkits. Use those. VSTGUI etc.
No offline support. Offline plugins require multi-pass processing and random access into the audio and MIDI stream. This is a completely different model than a realtime plugin. Rather than bloat or compromise, SEM keeps it simple.
Plugins must be able to indicate non-support of a sample rate. Possible future enhancement.
GMPI must support ramped or smoothed events. Ramping or smoothing must be supported on controls with a real number datatype, at minimum. No, Proved problematic.
GMPI must support grouping events into 'gestures'. Partly supported, Possible future enhancement.
GMPI must provide access to a system-global clock (UST) which is compatible with the OpenML definition of UST. No provided, possibly available direct from OS.
GMPI must provide a way for plugins to accurately convert between the various timelines. Possible future enhancement.
All connections between plugins must be bundles of channels. Not supported. Possible future enhancement.
In-place processing (reusing an input buffer as an output buffer) must be supported by GMPI. Not critical, in fact VST has removed this feature. Possible future enhancement.
must be able to provide a parameter-specific method for producing a string representation of a parameter. Possible future enhancement.
must be able to provide a parameter-specific method for incrementing/decrementing a parameter . Possible future enhancement.
Plugins must be able to expose inter-parameter linkages. Possible future enhancement (actor).
Plugins must be able to perform seemingly spontaneous parameter changes. Possible future enhancement (Actor).
GMPI must support dynamic parameter sets. Proved problematic. Changing the parameter set trashes pre-recorded host automation data.
GMPI plugins must report their latency when queried by the host. TODO.
Plugins must be able to change their latency. Problematic in real-time. Possible future enhancement.
GMPI must define a simple file format for storing plugin state independently of any host or project. Possible future enhancement.
Plugin GUIs must be able to expose static and configurable keybindings to the host. Possible future enhancement.
It must be possible for non-privileged users to install plugins for their own use on platforms which support non-privileged users. Not sure Vista supports that.
The GMPI SDK must provide a tool or suite of tools to perform basic plugin validation. Possible future enhancement.