JMSL Tutorial: JSyn and JMSL, writing a JMSL Instrument that controls your SynthCircuit

We have designed a SynthCircuit from scratch, called SineCircuit. We will show you how to play this SynthCircuit with a custom JMSL Instrument.  We will extend InstrumentAdapter and override some methods.

We can write quick and dirty Instruments that simply bang a JSyn circuit in play(), or we can be more rigorous and follow some good design principles that will extend the life and utility of your instruments.

 Good JMSL Instrument design  follows the following principles:

  1. Keep the instantiation of device-specific objects out of the constructor (in our case, no JSyn in the constructor!)
  2. Specify the Instrument's MusicDevice in constructor
  3. Specify the Instrument's Mixer classname in constructor
  4. Define the Instrument's DimensionNameSpace in constructor
  5. implement AttributeBuildable and do all device-specific  building in the buildFromAttributes() method (in our case, build the JSyn circuit)
  6. Bang your circuit in play()
 The idea is that you should be able to instantiate a new Instrument while its MusicDevice (in our case JSyn) is closed.
 You should be able to query this new Instrument for its MusicDevice, and open() the device, without ever knowing what kind of MusicDevice it really is.
 Then you should be able to add this instrument to a JMSLMixerContainer, again witout knowing the details of which Mixer implementation it uses.  Pan/Amp controls will be then be available for your instrument.
 Some of the support classes that reward these design principles include JMSL Score, SimpleXMLLoader, and SimpleXMLSaver

Now for the nuts and bolts:  Instrument's most important method is play().  This is called by MusicShape for example, as it iterates through all its elements, handing each to its instrument's play() method, and waiting for the time returned by play() before proceeding to the next element.  So the task we have to accomplish is bang SineCircuit in the Instrument's play() method.
Check the source for SineInstrument here. Read it carefully.  Use it as a template for your own JSyn Instrument design.  But we reiterate here, that if you just want to use a SynthNote and play it with full control over each of its SynthInputs, you can just use JMSL's SynthNoteAllPortsInstrument.  If you don't care about note-by-note timbral control, just use JSynInsFromClassName.  Only design your own Instruments from scratch if the definition of what it does truly falls outside the paradigm of applying a parameter list to a synthesizer's inputs and banging it.

Next, we will have the great satisfaction of building a MusicShape, handing it one of our SineInstruments, and starting it up.
Previous Tutorial Index Tutorial Contents Next

  (C) 2003 Nick Didkovsky, All Rights Reserved