Netbeans RCP: LazyPlugin and LazyPluginFactory

In working with the  Netbeans Rich Client Platform in building Blue, I have created a number of plugin types for the program.  Following a standard Netbeans convention, I have implemented plugin registration by having plugins register themselves with the System Filesystem. This is done either through XML (layer.xml) or through annotations I have created for each plugin type.

This works very well, but over time, I found two things I wanted to address:

  1. I was using a lot of boilerplate code for loading plugins and wanted to encapsulate that into an API to simplify things.
  2. I needed a way to lazily load the plugins, such that each are only instantiated only when they are requested for use.

To those ends, I wanted to share a couple of classes I have recently worked on: LazyPlugin and LazyPluginFactory. The code for these two are as follows:

LazyPlugin:

package blue.ui.nbutilities.lazyplugin;

import java.util.HashMap;
import java.util.Map;
import org.openide.filesystems.FileObject;
import org.openide.filesystems.FileUtil;

/**
 * Lazy Plugin class that wraps a NB FileObject.  
 * 
 * @author stevenyi
 */
public class LazyPlugin<T extends Object> {
    private final String displayName;
    private final String path;
    private final Class clazz;
    private final Map<String, Object> metaData;

    
    public LazyPlugin(FileObject fObj, Class c) {
        this.displayName = (String) fObj.getAttribute("displayName");
        this.path = fObj.getPath();
        this.clazz = c;
        metaData = new HashMap<>();
    }

    public String getDisplayName() {
        return displayName;
    }
    
    public T getInstance() {
        return (T) FileUtil.getConfigObject(path, clazz);
    }
   
    public Object getMetaData(String key) {
        return metaData.get(key);
    }

    public void setMetaData(String key, Object value) {
        metaData.put(key, value);
    }
}

LazyPluginFactory:

package blue.ui.nbutilities.lazyplugin;

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import org.openide.filesystems.FileObject;
import org.openide.filesystems.FileUtil;

/**
 *
 * @author stevenyi
 */
public class LazyPluginFactory {

    private LazyPluginFactory() {
    }

    public static <T> List<LazyPlugin<T>> loadPlugins(String folder, Class z) {
        return loadPlugins(folder, z, null, null);
    }

    public static <T> List<LazyPlugin<T>> loadPlugins(String folder, Class z, MetaDataProcessor processor) {
        return loadPlugins(folder, z, processor, null);
    }


    public static <T> List<LazyPlugin<T>> loadPlugins(String folder, Class z, Filter filter) {
        return loadPlugins(folder, z, null, filter);
    }
    
    public static <T> List<LazyPlugin<T>> loadPlugins(String folder, Class pluginClass,
            MetaDataProcessor processor, Filter f) {
        List<LazyPlugin<T>> plugins = new ArrayList<>();

        FileObject files[] = FileUtil.getConfigFile(
                folder).getChildren();

        List<FileObject> orderedFiles = FileUtil.getOrder(
                    Arrays.asList(files), true);

        for (FileObject fObj : orderedFiles) {

            if(fObj.isFolder()) {
                continue;
            }

            if(f != null && !f.accept(fObj)) {
                continue;
            }
            
            LazyPlugin<T> plugin = new LazyPlugin<>(fObj, pluginClass);

            if (processor != null) {
                processor.process(fObj, plugin);
            }

            plugins.add(plugin);
        }

        return plugins;
    }

    public static interface Filter {
        public boolean accept(FileObject fObj);
    }
    
    public static interface MetaDataProcessor {
        public void process(FileObject fObj, LazyPlugin plugin);
    }
}

LazyPlugin encapsulates the plugin and defers loading until the plugin user calls getInstance().  This allows the plugin’s displayName to be used for displaying to the end-user (i.e. “Add GenericScore” for a GenericScore plugin).  There is also a metadata map that is useful for storing additional properties.  To note, the class does not itself hold on to any references of the FileObject.

The LazyPluginFactory is used by giving a folder name to load plugins from, as well as the type of plugin to load.  This then returns a List<LazyPlugin<T>> of the plugins found.  The loadPlugins() method does allow taking in a Filter as well as MetaDataProcessor.  The Filter class can be used to inspect a FileObject and skip over it or not.  (I have a pre-made AttributeFilter class that checks if a given attribute name is set to true. I also have a pre-made ClassAssociationProcessor that reads an attribute string assumed to be a fully qualified class name, loads the class, and adds to the LazyPlugin’s metadata as “association”.)

Having LazyPlugin as a class has–in my opinion–made my code a little clearer.  It’s easy for me to see the code and say “Oh, I’m dealing with plugins here, and I’m lazily loading them.”  The classes are also generic enough that I can handle two scenarios that appear in my program:

  1. I need to lazily load plugins that are model classes.
  2. I need to lazily load plugins at are view/controller classes and need to have an association with the model class. (i.e. this is an editor for class X)

Using generated XML, the following are two fragments, one for a model class, the other for a view/controller class:

Model:

            <file name="blue-orchestra-BlueSynthBuilder.instance">
                <!--blue.orchestra.BlueSynthBuilder-->
                <attr intvalue="50" name="position"/>
                <attr name="displayName" stringvalue="BlueSynthBuilder"/>
            </file>

View/Controller:

<file name="blue-ui-core-orchestra-editor-BlueSynthBuilderEditor.instance">
                <!--blue.ui.core.orchestra.editor.BlueSynthBuilderEditor-->
                <attr name="instrumentType" stringvalue="blue.orchestra.BlueSynthBuilder"/>
            </file>

When loaded within the program, I would get a LazyPlugin<Instrument> and a LazyPlugin<InstrumentEditor>.  The former would get used when adding an instance of an Instrument to the project’s main model class. The latter is used when the Instrument is selected. Note the metadata for the LazyPlugin has an association class loaded via a ClassAssociationProcessor that reads in classes using “instrumentType”. It has enough information then to setup the application’s cache of editors for instruments without having to load the actual editor until requested.

So far I have been happy with this design and it has served all of the use cases I currently have.  I imagine these classes may get further refined in the future as other uses cases come up.  I hope others may find these classes useful in the Netbeans RCP programs.

Announce: New Score Library in Clojure

Hi All,

I’d like to announce a score generation library written in Clojure called “score”:

https://github.com/kunstmusik/score

This library is currently a work in progress. I am planning to put all general composition functions that I use or plan to explore within this library.

Some notes:

The library currently offers two styles of score generation. One is styled after SuperCollider’s Patterns. Patterns in SC generate values without context, and map directly to standard Clojure sequences. gen-notes and gen-score in src/score/core.clj are functions for use with the score generation style. With this it is simple enough to emulate any feature in SC Patterns using standard Clojure sequence-related functions.

The other score generation style is CMask-based. In CMask, rather than have sequences, generator functions are used that function within a context of time. (The start time of the current event being generated is passed-in as an argument.) That difference of having time as an argument allows to express things like time-varying masks, frequencies, etc. So far, I have completed porting all of the features of CMask and have done light testing.

As for the future of this library, I will be using this in my pieces moving forward, and expect to maintain this library, adding features as required. I would warn that the library is still a little volatile, so functions may move namespaces and users may need to update code between these early versions. I hope to clean up and stabilize the API soon so backwards compatibility can be maintained. (The library is version 0.1.0 at the moment; it will be bumped to 1.0.0 when the API is stable.)

Also to note, the library is purposely designed to be generic. I am targeting Csound score generation at the moment, but the core of the library works to generate simply lists of lists (see core.clj, and note the difference between gen-notes and gen-score, or gen-notes2 and gen-score2). This allows the library to be used beyond Csound. For example, you could always create a formatting function to send the notes as MIDI, OSC, etc. (I have some plans to do some interesting event exploration using score with a Clojure music system I’m working on.)

For examples, I have some demo clj files I used while developing within a REPL (https://github.com/kunstmusik/score/tree/master/src/score/demo).They show a bit of what using the library would look like.

Comments and contributions would be very welcome.

Thanks!
steven

Clojure and Blue/Csound Example

I have started to work on a new composition and wanted to move from using Python to Clojure as the scripting language for my music.  I was experimenting yesterday and was pleased to be able to write a score generation function that was fairly flexible, allowing for easily using hardcoded values as well as any sequence for filling in p-fields of generated Csound Score.

From my work session I came up with some fairly condensed code I was happy with:

(require '[clojure.string :refer  [join]])

(defn pch-add  [bpch interval]
      (let  [scale-degrees 12
                       new-val  (+  (* scale-degrees  (first bpch))
                                                      (second bpch) interval)]
                [(quot new-val scale-degrees)
                          (rem new-val scale-degrees)]))

(defn pch->sco  [[a b]] 
      (format "%d.%02d" a b ))

(defn pch-interval-seq  [pch & intervals] 
    (reduce  (fn  [a b]  (conj a  (pch-add  (last a) b)))  [pch] intervals))

(defn pch-interval-sco  [pch & intervals] 
    (map pch->sco  (apply pch-interval-seq pch intervals)))

(defn score-arg  [a]
      (if  (number? a)
                (repeat a)
                a))

(defn gen-score  [& fields]
      (let  [pfields  (map score-arg fields)]
                (join "\n"
                                  (apply map (fn [& args] (join " " args)) (repeat "i") pfields))))

;; EXAMPLE CODE

(def score 
      (gen-score 1 0 1 
                         (pch-interval-sco  [6 0] 12 8 6 2 6)
                         (pch-interval-sco  [6 0] 12 8 6 2 6)
                         (range -10 -100 -1) 0 1))

(print score)

The output from the print statement is:

i1    0.0    1    6.00    6.00    -10    0    1
i1    0.0    1    7.00    7.00    -11    0    1
i1    0.0    1    7.08    7.08    -12    0    1
i1    0.0    1    8.02    8.02    -13    0    1
i1    0.0    1    8.04    8.04    -14    0    1
i1    0.0    1    8.10    8.10    -15    0    1

The key part is the gen-score function.  It can take in either a number or a sequence as arguments.  If a number is given, it will be repeated for each note.  For a sequence, they can be infinite or finite. The only important part of using gen-score is that the at least one of the arguments given is a finite list.

This is fairly similar to SuperCollider’s Pattern system, though it uses standard abstractions found in Clojure. To me, it is a bit simpler to think in sequences to generate events than to think about the Pattern library’s object-oriented abstractions, but that is just my own preference.  Also, the Pattern system in SC is designed for real-time scheduling and also has an option for a delta-time generator.  I think the delta-time aspect could be added fairly easily using an optional keyword-argument to gen-score.

As for making this work in realtime, gen-score would have to be rewritten to not format the strings but instead return the list of p-field values. A priority-queue could then be used to check against the time values of the notes and pause and wait to generate new notes when the scheduling time demands it.

Ultimately, I was very pleased with the short amount of time required to write this code, as well as the succinctness of it.  One thing that has been on my mind is whether to use a CMask/PMask kind of approach to the p-field sequence generators.  In those systems, what would be comparable to the sequence generators–I think they’re just called Fields in those systems–actually take in a time argument.  That gives the generators some context about what to generate next and allows the ability to mask values over time.  I am fairly certain I will need to update or create an alternative to the gen-score function to allow generator functions.  I’ll have to consider whether to use a Clojure protocol, but I may be able to get away with just testing if the argument to gen-score is a function, sequence, or number and act appropriately.  (Something to look at next work session. 🙂 )

Julian Parker Ring Modulator

I wanted to share an implementation of Julian Parker’s digital model of a Ring Modulator. The paper he wrote from DAFx 2011 [1][2] was also used by the BBC Radiophonic Workshop in the “Recreating the sounds of the BBC Radiophonic Workhop using the Web Audio API” [3].

I’ve implemented the ringmodulator as a UDO, available here:

Blue Project and CSD (ringmod.zip) 

To run the CSD on the commandline, you can use:

csound -i adc -o dac -b 128 -B 512 ringmod.csd

The Blue project has knobs you can use to adjust the carrier’s amp and frequency. In the generated CSD, you can adjust gk_blue_auto0 for amp and gk_blue_auto1 for frequency, or just modify the poscil line in instr 1.

Note, the paper suggests using a high amount of oversampling (32x; 8x or 16x being reasonable for using sinusoidal carrier). This implementation does not do oversampling, which I believe the BBC version does do not as well.

As far as I’ve checked, the implementation matches the BBC one with the exception of using a limiter instead of a compressor. Also, I did one optimization to the wavetable generation to extract out a constant in the part where v > vl, but this is a minimal optimization as the wavetable generation is done only once really.

  • [1] – http://www.acoustics.hut.fi/publications/papers/dafx11-ringmod/
  • [2] – http://recherche.ircam.fr/pub/dafx11/Papers/66_e.pdf
  • [3] – http://webaudio.prototyping.bbc.co.uk/ring-modulator/

UPDATE (2015-04-07):  I found a coding bug in the table generation in the original version I posted.  The zip file above has been updated with the corrected code.

 

NoteParse – code for shorthand Csound score creation

noteParse – 2012.10.27

As part of my composition work lately I’ve been developing some new
scripts. Some are custom to the piece I’m working on, while others
have been a bit more generic.  I thought I’d share this NoteParse
Python code as I thought others might find it useful.

One of the things I’ve wanted is a shorthand for creating scores.  I’m
aware of a number of different approaches for this (microcsound,
lilypond, abc, mck/mml), but wanted something that worked more closely
to my own personal style.  I found I was able to write something
fairly quickly that is simple but flexible enough.

Attached are two python scripts.  The first works with standard
python, while the other requires being used within blue as it depends
on my python orchestra library that comes with blue.  Both use the
basic syntax I created, while the blue version allows score modifiers.
An example of the syntax with modifiers:

def stoccato(n):
    n.duration = n.duration * .5

modifiers = {"stoccato": stoccato }

a = "m:stoccato 8.00d.25a-12 4 m:clear 3d.5 2 1 0d1a-8"
notes = parseOrchScore(a, modifiers)

generates the following:

i x               0.0             0.125           8.00            8.00 -12.0           0   0
i x               0.25            0.125           8.04            8.04 -12.0           0               0
i x               0.5             0.5             8.03            8.03 -12.0           0               0
i x               1.0             0.5             8.02            8.02 -12.0           0               0
i x               1.5             0.5             8.01            8.01 -12.0           0               0
i x               2.0             1.0             8.00            8.00 -8.0            0               0

(disregard that x is used for p1, these notes get further processed by
performers and performerGroup objects in my composition library).

The things I’d like to point out:

1. The score line is:

a = "m:stoccato 8.00d.25a-12 4 m:clear 3d.5 2 1 0d1a-8"

Disregarding the m: statements, the line looks like:

a = "8.00d.25a-12 4 3d.5 2 1 0d1a-8"

How the library works is that the first note becomes a template note
that carries over values to the next note.  So, for the first note, it
uses pch 8.00, has a duration of .25, and amplitude of -12.  The next
note, which is just a 4, means scale degree four for the same octave
as previously given, so the next generated note has a pch of 8.04, a
duration of .25, and amplitude of -12.  The third note uses
scaleDegree 3, but now has a duration of .5, and carries over the
amplitude.

2. The use of modifiers is completely customizable.  To use modifiers,
supply a map that has the name of the modifier together with a
single-arg function that will process the note.  When an m: statement
is encountered, it will look up that modifier and set it as the
current modifier.  If an m:clear is found, it will set the modifier
function to None.  What I like about this is that a standard set of
modifiers could be created, but it’d be easy to create a custom one
while working on a new piece that might be very specific to that
piece.

The non-blue version attached to this email currently just returns a
list of lists of values that one can then process to generate notes
that work with the individual instrument’s p-field signatures (i.e.
your instrument may have 5 p-fields, or 10, etc. and you’d just apply
a transform to the list to generate the notes you want).

I’m still debating on other features to add, and my current plan is to
add this to my orchestra composition library that comes with blue.  My
thought is that the code is fairly small and useful to my own
composition method, but might be easy for others to take and modify
for their own use pretty easily.