/ Reference / Extending Fiddle

Here, we assume that you are familiar with Fiddle Runtime concepts and are interested in adding capabilities yourself.

As a Fiddle extender you may wish to share your work with collaborators or even the community at large. To minimize hassles associated with your creations, we advise that you adopt a short, unique-ish prefix for your global class/node names.

Fiddle Extension Types

ChucK Source

ChucK source-code, in .ck files, is the primary means to extend the Fiddle Runtime. Whether your .ck files extend the Fiddle Runtime classes or you develop your own custom runtime, the semantics of ChucK's VM loader require that extensions be loaded in a dependencies-first order. Fiddle's solution to this problem of transitive loading is to punt it onto the end-user's shoulders by loading a single .ck file, named _bootstrap.ck, from their workspace directories. There they can define an orderly loading of additional .ck files like this:

// chuckExtensions/_bootstrap.ck
me.dir() => string path;
<<<"Loading extensions from", path>>>;
Machine.add(path + "efSineTest.ck");
Machine.add(path + "efMulti.ck");

The bootstrapping process occurs every time ChucK starts. If you are the kind of programmer that puts errors into your code, you'll find that the ChucK Panel's Start and Stop buttons will get lots of use during development.

We'll provide some guidance on extending the Fiddle Runtime below, but the general topic of ChucK Programming is more than we can cover here.

YAML

YAML is the file syntax used to register Fiddle extensions for inclusion in the Graph Editor. If you want to to extend the Graph Editor, you need to provide one or more YAML files which describe your custom extensions.

For the curious, YAML was selected over .xml and .json because of its focus on human readability. For example, support for comments is a very helpful feature for this use-case.

So, for every graph-node-type, there is a YAML node. The Fiddle Extension YAML Schema supports multiple YAML nodes in a single .yaml file. Each node provides Fiddle with parameter enumerations, UI hints, helpful descriptions, etc. The best way to understand our simple schema is simply to inspect an assortment of built-in extensions (more below).

.yaml extension files are loaded whenever a new Graph Editor is created. This makes it possible to iteratively develop a .yaml extension file without having to restart Fiddle. Happily, there are no inherent requirements that these extensions are loaded in a particular order and they are loaded in the order determined by your filesystem.

Briefly, a Fiddle extension file includes an array named FiddleNodes. Here's a working example with a single node, efMulti. We present it here mostly to draw attention to the basic structure and will avoid getting into the weeds on the minutiae.

# an example Fiddle extension 
FiddleNodes:
  - RegistryName: efMulti
    DisplayName: ef Multi
    Description: >-
      Adaptation of Eli Fieldsteels multi example instrument.
      From his SuperCollider tutorial 4.
    Categories:
      # guides which menu to appear in
      - instrument
    IsInstanceable: true # support for multiple instances with shared wiring
    Inputs:
      - name: EnvDur
        type: dur
        default: '10::ms'
        description: 'Duration of the key-down/up envelope'
        range:
          - 10
          - 500
          - 10
        forceEmit: true # ensures that codegen always emits this value
      - name: VoiceDetuning
        type: float
        default: 5
        description: 'The cluster radius of voices around the target note'
        range:
          - 0
          - 40
          - 1
        forceEmit: true # ensures that codegen always emits this value
      - name: Controller
        type: Controller
      - name: OSCId 
        type: NodeID
        description: "OSC communication Id"
        visibility: 
          port: false
          inspector: false 
    Outputs:
      - name: outlet
        type: UGen
      - name: self
        type: Instrument
        asSelf: true

VST3

Fiddle supports VST3 Plugins by:

1. scanning the standard VST3 locations on your computer and producing YAML files into your workspace fiddleExtensions directory for each VST3 plugin it finds. A VST3 plugin can contain multiple "modules" but usually there is a one-to-one correspondance between VST3 plugin and YAML. A custom CLI tool, dumpVST3, is used to produce the YAML files. It is included with Fiddle and can be found in the resources/tools directory of the application bundle.
2. auto-generating .ck code which leverages the DbVST3 chugin to activate VST3-plugin functionality within ChucK.

Fiddle Extension Locations

Built-In "extensions" live within the Fiddle application bundle. A user's extensions are found relative to the current workspace directories. This opens the possibility of per-workspace extension configurations.

The Built-In Components

Built-in components are found in the Fiddle application bundle below:

Fiddle.app/Contents/Resources/Fiddle/chuckruntime (MacOS)

Fiddle/resources/Fiddle/chuckruntime (Windows, Linux)

There you'll find the file _bootstrap.ck and multiple subdirectories full of the .ck extensions that make up the Fiddle Runtime.

A specially named subdirectory, _registry/, houses all the .yaml files for the Fiddle Runtime.

Both file-dumps serve as excellent documentation for extension developers. A common extension strategy is to find an existing node that you can pattern your new extension after. Now it's a small matter of copy+paste+modify to achieve success. Be careful not to modify any files in the application bundle as this will break the code signatures and may render Fiddle inoperable.

Your Custom Extensions

Custom extensions are located relative to your current workspace. Should you find the need to have different extensions for different projects, you can accomplish this with multiple workspaces.

Load Chuck Extensions

To find your .ck extensions, Fiddle searches for the file chuckExtensions/_bootstrap.ck below each root directory known to your workspace. As desribed above, _bootstrap.ck can load any number of additional .ck files. and this bootstrapping occurs each time you start ChucK.

Load YAML Files for Interface Hints

To find your .yaml extensions, Fiddle scans the contents of fiddleExtensions/ within each root directory known to your workspace. Each .yaml file can define multiple extensions/nodes and this loading mechanism is repeated each time you open or create a new Graph Editor.

Extending the Fiddle Runtime

With your new-found mastery of the mechanics for extending Fiddle you can now focus on the creative aspects of building Fiddle extensions. Fiddle Runtime gives a class-hierarchy tour and ChucK code snippets to help you on your way.

Keep in mind that there is more than one way to skin a cat. You can:

• use .ck and .yaml to extend the Fiddle runtime by subclassing Instrument, NoteStream, FX.
• write a ChuGin in C++ and wrap it with a combination of .ck and .yaml.
• write a VST3 plugin in C++, Fiddle will auto-gen both the .ck and .yaml for you.