The Manifest

The App/Manifest.js file defines the internal structure of an expansion. Every field it contains is optional based on the requirements of the project. The file contains a single JSON object called Manifest.

How it’s Used

The Manifest is used in several parts of Rhapsodist. Most importantly it is used by the Configuration Handler and the Component Handler.

If you need custom configuration values for your own scripts you can extend the Manifest as needed to accommodate that.

Configuration Handler

The Configuration Handler is a script module that sits below the Interface in the module tree.

It is responsible for updating the settings of other modules when an expansion loads, the patch changes, or an articulation is activated.

Component Handler

The Component Handler is included in the Interface as part of Core.js. It is responsible for updating the state of the user interface when the patch changes, or an articulation is activated.

When one of these events occurs it reads the values from the Manifest and applies them to the UI.

Levels

The configuration is separated into three levels: Expansion, Patch, and Articulation.

Expansion level values apply to the entire expansion, including every patch and articulation.

Patch level values apply to each patch and their articulations.

The articulation level values affect only individual articulations.

Expansion Level

Typically at this level the Manifest will specify the sample maps and sampler or sound generator settings used by the expansion.

This is also a good place to define default articulation settings, if the same articulations are used by multiple patches.

A Manifest can only contain one set of expansion level settings.

Patch Level

A Manifest can contain one or more patches. A patch defines a set of values that are loaded based on the value of the hidden knbPatch knob.

Typically patches are used to define different instruments within an expansion. For example a brass library might contain separate patches for trumpet, trombone, french horn, and tuba. However, it doesn’t have to be strictly used for this purpose.

Common values for the patch level are sample maps, key ranges, and gain level.

Articulation Level

Each patch can contain one or more articulations. An articulation is another set of configuration values, this time applied based on the value of the hidden knbArticulation knob.

This is typically used with key switches to allow a user to switch articulations. For example, a trumpet patch might contain separate articulations for sustain, staccato, and trills.

At the articulation level it’s not possible to specify sample maps, because samples cannot be swapped in real-time.

Common settings for articulations are a sampler’s active group, effects values, round robin settings, and enabling or disabling UI components.

Articulations can be defined at the expansion level when they are shared by multiple patches. This reduces the repetition of defining the same articulation for each patch.

A Defaults articulation can be defined with fallback values that are used as defaults by all articulations. Individual articulations can then override these defaults. The Defaults articulation is not displayed in the articulation list.

One use case for Defaults is toggling a UI component that is used by only some articulations. For example a trumpet patch might enable a Dynamics crossfade knob for its sustain articulation but disable it for all other articulations.

Manifest Property Schema

The Manifest is a single JSON style object that contains sets of key/value pairs. In many cases the values are themselves are arrays of objects.

Common keys include scripts/modulators/effects/samplers with values that are arrays of {id, properties} objects.

Each entry unbypasses its target module and applies every key in properties as an attribute. Most property names match the target module’s own attribute names, but a few are special-cases:

Example Usage

Here is an example Manifest with comments describing what each part does. This is an abridged version of the Manifest used by the Bell and Bone expansion.

It contains two patches, Trombone and Trumpet. Each of which has its own settings.

At the expansion level it defines effects settings and articulations that are used by both patches.

The trumpet patch also defines some additional articulations that are unique to it.

const Manifest = { // Manifest object
  effects: [ // Expansion level effects values - can be overridden by patches and articulations
    {
      id: "convolutionReverb0", // ID of the effect in the module tree
      properties: {Ignore: true} // Property and value to set
    }
  ],
  articulations: [ // Expansion level articulations - shared by all patches
    {
      id: "Defaults", // ID is "Defaults" this is the fallback that can be overridden by individual articulations
      components: [ // Component values
        {
          id: "knbVibratoRate", // ID of the UI component
          properties: {enabled: false} // Property and values to set
        },
        {
          id: "knbVibratoDepth",
          properties: {enabled: false}
        },
        {
          id: "knbDynamics",
          properties: {enabled: false}
        }
      ]
    },
    {
      id: "Performance", // Performance articulation
      muters: [0], // Which MIDI muters to keep enabled (unmuted) - every other muter is muted. Used by the Configuration Handler.
      components: [ // Component properties for this articulation. Overrides those set in "Defaults"
        {
          id: "knbVibratoRate",
          properties: {enabled: true}
        },
        {
          id: "knbVibratoDepth",
          properties: {enabled: true}
        },
        {
          id: "knbDynamics",
          properties: {enabled: true}
        }
      ]
    },
    {
      id: "Staccato Fall", // Staccato articulation
      gain: -3, // Set a gain offset for this articulation. This will be used by the Articulation Gain module which should be added in the master chain.
      muters: [1],
      scripts: [ // Script (MIDI Processor) settings
        {
          id: "sampler1RoundRobin", // ID of script processor
          properties: {FirstGroup: 1, Count: 4, Borrowed: true} // Properties/values
        }
      ]
    },
    {
      id: "Shakes", // Shakes articulation
      muters: [1],
      scripts: [
        {
          id: "sampler1RoundRobin",
          properties: {FirstGroup: 17, Count: 2, Borrowed: false}
        }
      ]
    }
  ],
  patches: [ // Patch configurations
    {
      id: "Trombone", // Name of patch
      gain: 3, // Gain applied to the patchGain effect in the master chain
      keyranges: [ // Key colour ranges
        {loKey: 24, hiKey: 29, colour: "keyswitch"}, // Colour names (keyswitch/playable/etc) are defined in Styles.js
        {loKey: 40, hiKey: 72, colour: "playable"}
      ],
      firstKs: 24, // Keyswitches are added sequentially for each articulation starting from firstKs
      samplers: [ // Sampler settings
        {
          id: "sampler0", // Sampler ID
          properties: { // Sampler properties for this patch
            VoiceAmount: 96,
            VoiceLimit: 64,
            SampleMap: "trombone_sustain" // Sample map to load - no .xml required.
          }
        },
        {
          id: "sampler1",
          properties: {
            VoiceAmount: 64,
            VoiceLimit: 32,
            SampleMap: "trombone_articulations"
          }
        }
      ],
      scripts: [ // Patch level script (MIDI processor) settings
        {
          id: "sampler0Legato",
          properties: {XfadeTm: 100, BendMinUp: 50, BendMinDn: 50, BendTm: 125}
        },
        {
          id: "noteRangeFilter",
          properties: {LowNote: 40, HighNote: 72}
        }
      ],
      modulators: [ // Patch level modulator settings
        {
          id: "sampler0GroupXFTable", // Modulator ID
          properties: {Attack: 500} // Settings to use
        }
      ]
    }, // End of Trombone Patch
    {
      id: "Trumpet", // Trumpet patch
        keyranges: [ // Different key colour ranges to the trombone
          {loKey: 24, hiKey: 30, colour: "keyswitch"},
          {loKey: 52, hiKey: 84, colour: "playable"}
      ],
      firstKs: 24,
      samplers: [
        {
          id: "sampler0",
          properties: {VoiceAmount: 96, VoiceLimit: 64, SampleMap: "trumpet_sustain"}
        },
        {
          id: "sampler1",
          properties: {VoiceAmount: 64, VoiceLimit: 32, SampleMap: "trumpet_articulations"}
        }
      ],
      articulations: [ // Articulations used only by the trumpet
        {
          id: "Doit",
          ks: 84, // Set a specific keyswitch
          program: 22, // Set a specific program change number
          muters: [1],
          scripts: [
            {
              id: "sampler1RoundRobin",
              properties: {FirstGroup: 13, Count: 4, Borrowed: false}
            }
          ]
        },
        {
          id: "Rips",
          muters: [1],
          scripts: [
            {
              id: "sampler1RoundRobin",
              properties: {FirstGroup: 19, Count: 2, Borrowed: false}
            }
          ]
        }
      ],
      scripts: [
        {
          id: "sampler0Legato", // Trumpet has different legato settings
          properties: {XfadeTm: 80, BendMinUp: 50, BendMinDn: 60, BendTm: 80}
        },
        {
          id: "noteRangeFilter",
          properties: {LowNote: 52, HighNote: 84}
        }
      ],
      modulators: [
        {
          id: "sampler0GroupXFTable",
          properties: {Attack: 750}
        }
      ]
    }
  ]
};