com.softsynth.jsyn
Class Synth

java.lang.Object
  extended by com.softsynth.jsyn.Synth

public class Synth
extends java.lang.Object

Provides general control over synthesizer, constants. Provides a shared synthesis context.

Version:
JSyn Version 0144
Author:
(C) 1997-2007 Phil Burk, SoftSynth.com, All Rights Reserved
See Also:
SynthUnit, SynthSample, SynthEnvelope, SynthTable

Field Summary
static java.lang.String copyright
           
static int DEBUG_GET_ALLOCS
           
static int DEBUG_REPORT
           
static int DEBUG_THREAD
           
static double DEFAULT_FRAME_RATE
           
static int FLAG_AUTO_STOP
          FLAG_AUTO_STOP is used with SynthEnvelopeQueue and SynthSampleQueue to make an instrument stop automatically when the data is finished.
static int FLAG_DISABLE_OUTPUT
          FLAG_DISABLE_OUTPUT turns off the audio output feature for machines that do not support full duplex recording.
static int FLAG_ENABLE_INPUT
          FLAG_ENABLE_INPUT turns on the audio capture feature.
static int FLAG_LOOP_IF_LAST
          FLAG_LOOP_IF_LAST is used with SynthEnvelopeQueue and SynthSampleQueue to request that the last block of data queued be looped until another block is queued.
static int FLAG_NON_REAL_TIME
          Request that the synthesis occur as fast as possible, which may be slower or faster than real-time.
static int FLAG_SKIP_IF_OTHERS
          FLAG_SKIP_IF_OTHERS is used with SynthEnvelopeQueue and SynthSampleQueue.
static int NO_DEVICE
          Use with start() when no device desired.
static int NUM_SIGNAL_TYPES
          Number of signal types supported.
static int openCount
          Is engine started?
static int PRIORITY_HIGH
           
static int PRIORITY_LOW
          Priority for SynthUnit execution.
static int PRIORITY_MEDIUM
           
static int RATE_AUDIO
           
static int SIGNAL_TYPE_FULL_RANGE
          General signal type for full range scalars.
static int SIGNAL_TYPE_HALF_LIFE
          Halflife in seconds.
static int SIGNAL_TYPE_OSC_FREQ
          Oscillator frequency in Hertz in the range of +/- Samplerate/2
static int SIGNAL_TYPE_RAW_SIGNED
          Signed signal in the range of -1.0 to +1.0
static int SIGNAL_TYPE_RAW_UNSIGNED
          UNSigned signal in the range of 0.0 to +2.0
static int SIGNAL_TYPE_SAMPLE_RATE
          Sample reader rate in the range of 0.0 to Samplerate*2
static int SIGNAL_TYPE_SVF_FREQ
          Frequency for StateVariableFilter in Hertz.
static int SIGNAL_TYPE_TIME
          Time in seconds.
static int SILENT
          Value for verbosity, no debug output.
static int TERSE
          Value for verbosity, sparse debug output.
static int timeAdvance
          Variable that can be used by applications to schedule algorithmically generated events a minimum time in the future.
static int VERBOSE
          Value for verbosity, full debug output.
static int verbosity
          Deprecated. Use setTrace() instead.
static int VERSION
          Version of the Java code for JSyn that you compiled with.
 
Constructor Summary
Synth()
           
 
Method Summary
static void checkEngineErrors()
          Used by sleep routines to keep FIFOs clear.
static int debug()
           
static int debug(int command, int data)
           
static java.lang.String errorCodeToString(int errorCode)
           
static int getExpirationDate()
           
static int getFrameCount()
          Returns index of last calculated frame.
static double getFrameRate()
          Rate that frames are generated, typically 44100.0.
static int getFramesPerTick()
           
static int getObjectCount()
           
static SynthContext getSharedContext()
           
static int getTickCount()
          Get current time in ticks.
static double getTickRate()
           
static int getTrace()
           
static double getUsage()
          Returns the fraction of critical resources used by synthesis context.
static int getVersion()
          Version of the Java code in the JSyn JAR file.
static int hashName(java.lang.String name)
          Convert a String to a hash value that is used internally in CSyn for fast name lookup.
static void initialize()
          Initialize Library.
static void requestVersion(int requestedVersion)
          If the existing version is earlier than the requested version, then the user will be instructed to upgrade to the latest version of JSyn.
static void setTrace(int mask)
          Set trace flags for debugging.
static void sleepForTicks(int ticks)
          Sleep for the specified number of ticks.
static void sleepUntilTick(int tick)
          Sleep until the specified tick is reached.
static void start(int flags)
           
static void start(int flags, double frameRate)
           
static void start(int flags, double frameRate, int inputDeviceID, int numInputChannels, int outputDeviceID, int numOutputChannels)
          Starts execution of process that performs synthesis.
static void startEngine(int flags)
          Starts execution of process using default frameRate.
static void startEngine(int flags, double frameRate)
          Calls initialize() and start( flags, frameRate ).
static void stop()
          Stops execution of process that performs synthesis.
static void stopEngine()
          Stops execution of process that performs synthesis.
static void terminate()
          Terminate library.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

VERSION

public static final int VERSION
Version of the Java code for JSyn that you compiled with. Note that if you compile a reference to this then it will be compiled inline. If you then use a later JAR file with a different VERSION number your compiled code will still have the old number that you compiled with. Use the getVersion() method to return the actual version of the code in the JSyn JAR file.

See Also:
getVersion(), Constant Field Values

copyright

public static final java.lang.String copyright
See Also:
Constant Field Values

openCount

public static int openCount
Is engine started?


SILENT

public static final int SILENT
Value for verbosity, no debug output.

See Also:
Constant Field Values

TERSE

public static final int TERSE
Value for verbosity, sparse debug output.

See Also:
Constant Field Values

VERBOSE

public static final int VERBOSE
Value for verbosity, full debug output.

See Also:
Constant Field Values

verbosity

public static int verbosity
Deprecated. Use setTrace() instead.
Set Synth.verbosity to Synth.SILENT, TERSE, or VERBOSE for increasing levels of debug output.


RATE_AUDIO

public static final int RATE_AUDIO
See Also:
Constant Field Values

PRIORITY_LOW

public static final int PRIORITY_LOW
Priority for SynthUnit execution.

See Also:
Constant Field Values

PRIORITY_MEDIUM

public static final int PRIORITY_MEDIUM
See Also:
Constant Field Values

PRIORITY_HIGH

public static final int PRIORITY_HIGH
See Also:
Constant Field Values

SIGNAL_TYPE_RAW_SIGNED

public static final int SIGNAL_TYPE_RAW_SIGNED
Signed signal in the range of -1.0 to +1.0

See Also:
Constant Field Values

SIGNAL_TYPE_RAW_UNSIGNED

public static final int SIGNAL_TYPE_RAW_UNSIGNED
UNSigned signal in the range of 0.0 to +2.0

See Also:
Constant Field Values

SIGNAL_TYPE_OSC_FREQ

public static final int SIGNAL_TYPE_OSC_FREQ
Oscillator frequency in Hertz in the range of +/- Samplerate/2

See Also:
Constant Field Values

SIGNAL_TYPE_SAMPLE_RATE

public static final int SIGNAL_TYPE_SAMPLE_RATE
Sample reader rate in the range of 0.0 to Samplerate*2

See Also:
Constant Field Values

SIGNAL_TYPE_HALF_LIFE

public static final int SIGNAL_TYPE_HALF_LIFE
Halflife in seconds.

See Also:
Constant Field Values

SIGNAL_TYPE_TIME

public static final int SIGNAL_TYPE_TIME
Time in seconds.

See Also:
Constant Field Values

SIGNAL_TYPE_SVF_FREQ

public static final int SIGNAL_TYPE_SVF_FREQ
Frequency for StateVariableFilter in Hertz.

See Also:
Constant Field Values

SIGNAL_TYPE_FULL_RANGE

public static final int SIGNAL_TYPE_FULL_RANGE
General signal type for full range scalars.

See Also:
Constant Field Values

NUM_SIGNAL_TYPES

public static final int NUM_SIGNAL_TYPES
Number of signal types supported.

See Also:
Constant Field Values

NO_DEVICE

public static final int NO_DEVICE
Use with start() when no device desired.

See Also:
Constant Field Values

FLAG_NON_REAL_TIME

public static final int FLAG_NON_REAL_TIME
Request that the synthesis occur as fast as possible, which may be slower or faster than real-time. Actual synthesis will occur during calls to sleepUntilTick();

See Also:
Constant Field Values

FLAG_LOOP_IF_LAST

public static final int FLAG_LOOP_IF_LAST
FLAG_LOOP_IF_LAST is used with SynthEnvelopeQueue and SynthSampleQueue to request that the last block of data queued be looped until another block is queued. This is useful for sustained waveforms, or LFOs made from envelope sections.

See Also:
Constant Field Values

FLAG_AUTO_STOP

public static final int FLAG_AUTO_STOP
FLAG_AUTO_STOP is used with SynthEnvelopeQueue and SynthSampleQueue to make an instrument stop automatically when the data is finished.

See Also:
Constant Field Values

FLAG_ENABLE_INPUT

public static final int FLAG_ENABLE_INPUT
FLAG_ENABLE_INPUT turns on the audio capture feature.

See Also:
Constant Field Values

FLAG_DISABLE_OUTPUT

public static final int FLAG_DISABLE_OUTPUT
FLAG_DISABLE_OUTPUT turns off the audio output feature for machines that do not support full duplex recording.

See Also:
Constant Field Values

FLAG_SKIP_IF_OTHERS

public static final int FLAG_SKIP_IF_OTHERS
FLAG_SKIP_IF_OTHERS is used with SynthEnvelopeQueue and SynthSampleQueue. If a block is queued with this flag, then any subsequently queued blocks will cause this block to be skipped.

See Also:
Constant Field Values

DEBUG_REPORT

public static final int DEBUG_REPORT
See Also:
Constant Field Values

DEBUG_THREAD

public static final int DEBUG_THREAD
See Also:
Constant Field Values

DEBUG_GET_ALLOCS

public static final int DEBUG_GET_ALLOCS
See Also:
Constant Field Values

timeAdvance

public static int timeAdvance
Variable that can be used by applications to schedule algorithmically generated events a minimum time in the future. Is not used internally by JSyn.


DEFAULT_FRAME_RATE

public static final double DEFAULT_FRAME_RATE
See Also:
Constant Field Values
Constructor Detail

Synth

public Synth()
Method Detail

getVersion

public static int getVersion()
Version of the Java code in the JSyn JAR file.

See Also:
VERSION

getSharedContext

public static SynthContext getSharedContext()

debug

public static int debug()

debug

public static int debug(int command,
                        int data)

getExpirationDate

public static int getExpirationDate()

getUsage

public static double getUsage()
Returns the fraction of critical resources used by synthesis context. A value of 0.5 would be 50%.

Returns:
fraction of resources used.

getObjectCount

public static int getObjectCount()
Returns:
Number of units, samples, tables and other objects allocated.

getFrameCount

public static int getFrameCount()
Returns index of last calculated frame. The frame index will tend to jump upwards because frames are calculated in large blocks by a high priority process.

Returns:
Index of last calculated frame.

getTickCount

public static int getTickCount()
Get current time in ticks. This is the basic clock use for scheduling in JSyn.

Returns:
Count of synthesis ticks.

getFramesPerTick

public static int getFramesPerTick()
Returns:
Number of audio frames per clock tick.

getFrameRate

public static double getFrameRate()
Rate that frames are generated, typically 44100.0.

Returns:
Number of audio frames per second.

getTickRate

public static double getTickRate()
Returns:
Number of clock ticks per second.

sleepUntilTick

public static void sleepUntilTick(int tick)
                           throws SynthException
Sleep until the specified tick is reached.

Throws:
SynthException - If timer not running.

checkEngineErrors

public static void checkEngineErrors()
                              throws SynthException
Used by sleep routines to keep FIFOs clear.

Throws:
SynthException

sleepForTicks

public static void sleepForTicks(int ticks)
                          throws SynthException
Sleep for the specified number of ticks.

Throws:
SynthException - If timer not running.

startEngine

public static void startEngine(int flags,
                               double frameRate)
                        throws SynthException
Calls initialize() and start( flags, frameRate ).

Parameters:
frameRate - Calculation rate in Hertz, typically 44100.0.
Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

start

public static void start(int flags,
                         double frameRate,
                         int inputDeviceID,
                         int numInputChannels,
                         int outputDeviceID,
                         int numOutputChannels)
                  throws SynthException
Starts execution of process that performs synthesis. This must be called before performing any synthesis. Because the device IDs are passed explicitly, the flags Synth.FLAG_ENABLE_INPUT and Synth.FLAG_DISABLE_OUTPUT are ignored.

Parameters:
flags - used to select options. Legal flags are Synth.FLAG_NON_REAL_TIME, Synth.FLAG_ENABLE_INPUT, Synth.FLAG_DISABLE_OUTPUT.
frameRate - Calculation rate in Hertz, typically 44100.0.
inputDeviceID - PortAudio hardware audio device ID for input, Synth.NO_DEVICE for no input.
numInputChannels - Number of input channels to use. Typically 0 or 2.
outputDeviceID - PortAudio hardware audio device ID for output, Synth.NO_DEVICE for no output.
numOutputChannels - Number of output channels to use. Typically 0 or 2.
Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

start

public static void start(int flags,
                         double frameRate)
                  throws SynthException
Throws:
SynthException

start

public static void start(int flags)
                  throws SynthException
Throws:
SynthException

startEngine

public static void startEngine(int flags)
                        throws SynthException
Starts execution of process using default frameRate.

Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

stopEngine

public static void stopEngine()
                       throws SynthException
Stops execution of process that performs synthesis.

Throws:
SynthException - If engine cannot be stopped.

stop

public static void stop()
                 throws SynthException
Stops execution of process that performs synthesis.

Throws:
SynthException - If engine cannot be stopped.

requestVersion

public static void requestVersion(int requestedVersion)
If the existing version is earlier than the requested version, then the user will be instructed to upgrade to the latest version of JSyn.


initialize

public static void initialize()
                       throws SynthException
Initialize Library. This must be called before any other synthesis functions. Resets AudioInputPermission. This allocates a shared SynthContext if one does not already exist.

Throws:
SynthException - If engine cannot be started or if plugin is an old version, or expired.

terminate

public static void terminate()
                      throws SynthException
Terminate library.

Throws:
SynthException - If engine cannot be stopped.

errorCodeToString

public static java.lang.String errorCodeToString(int errorCode)

hashName

public static int hashName(java.lang.String name)
Convert a String to a hash value that is used internally in CSyn for fast name lookup. This must match the algorith used in "gen_hash.c".


setTrace

public static void setTrace(int mask)
Set trace flags for debugging.


getTrace

public static int getTrace()