Toggle navigation

Flow+ technical documentation

Version 1.0

Scope of this document is to describe the data structure that is behind the engine of Flow+ application.

Data is encoded in JSON format and is located under the data folder included in the Flow+ folder.

Inside the data folder there is a number of folders which contains the structural data used to create content in the app. The folder structure looks like this:

The following sections contains a description of the data model of each of those objects, following this logical order:

  1. system
  2. midi events
  3. folders
  4. vendors
  5. faders
  6. instruments
  7. quick controls
  8. libraries
  9. tracks
  10. articulations
  11. expressionMaps
  12. macros

All the json data model contains the following two attributes

"version": "1.0.0",
"copyright": "www.artificialharmonics.com"

 

Liked it? Take a second to support on Patreon!

This folder contains static data that is used by other objects.

There are three types of data included:

  1. Sections
  2. Types
  3. Groups

The union of those three object is a unique identifier of a folder in Cubase, in the following order

section_id + type_id+ group_id

1.1. Section

The section object identifies the first category of the naming of a folder.

It represents large group of the template like Strings, Brass, Synths…

File must be named flow2-sections.json and contain all the sections

Attributes


objectIdentifier string

same as id


name string

name of the section


code string

a short code of one character


folderRef string

a reference to a folder id


order int

an integer used to order the objects


color string

hex code of the color assigned to this section


 

 

{
    "STRINGS": {
        "name": "Strings",
        "code": "s",
        "folderRef": "(s)",
        "order": 50,
        "color": "#1A5D1F",
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

1.2. Type

The type object identifies the second category level of the naming of a folder.

It identifies different types of instruments within one single Section like Ensemble, Solo, SFX…

File must be named flow2-types.json and contain all the sections

Attributes


objectIdentifier string

same as id


name string

name of the section


code string

a short code of one character


order int

an integer used to order the objects

{
    "ENSEMBLE": {
        "name": "Ensemble",
        "code": "e",
        "order": 10,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

 

1.3. Group

The group object identifies the third and last category level of the naming of a folder.

It identifies different groups of instruments within one single Section and Type like High, Low, Drums, Metal…

File must be named flow2-groups.json and contain all the sections

Attributes


objectIdentifier string

same as id


name string

name of the section


code string

a short code of one character


order int

an integer used to order the objects

{    
    "HIGH": {
        "name": "High",
        "code": "h",
        "order": 10,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

 

Midi events are used to define action linked to a specific object type. For this reason midi events are always referred within other objects.
In this section we will look at the standard definition of those events, which in the end simply describes the midi message that has to be sent to activate a specific action. This could be an action which has been declared in a generic remote of Cubase.

In the example below we can see the declaration of different types of midi events, in this case related to the folder object. The structure of those midi events is the following.

Attributes


objectIdentifier string

There are four types of midi events that can be sent

  1. SHOW: triggers in Cubase a logical preset to show this specific object
  2. HIDE: triggers in Cubase a logical preset to hide this specific object
  3. COLLAPSE: triggers in Cubase a logical preset to close this object (only for folders)
  4. EXPAND: triggers in Cubase a logical preset to open this object (only for folders)
  5. FILTER_NOT: triggers in Cubase a logical preset that hide all the tracks that do not match the name of this object

host string

since Cubase allows only Midi connection this is always set to “midi”


port string

the midi port to which this action will be mapped


address string

the type of midi message to be sent by open stage control, all the possible values can be found here https://openstagecontrol.ammd.net/docs/midi/midi-messages/


channel int

the midi channel of the action


value1 string

the value of the midi message

 

 

{
    "FILTER_NOT": {
        "host": "midi",
        "port": "flow1",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 2,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    },
    "HIDE": {
        "host": "midi",
        "port": "flow1",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 3,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    },
    "SHOW": {
        "host": "midi",
        "port": "flow1",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 4,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    },
    "COLLAPSE": {
        "host": "midi",
        "port": "flow1",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 0,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    },
    "EXPAND": {
        "host": "midi",
        "port": "flow1",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 1,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The folder object defines the folder as shown in Cubase and are used to interact with those.

Each object must be declared in one separate JSON file with a name ending with -f.json

Attributes


objectIdentifier string

same as id


id string

unique id of the folder following the naming convention

([section_code][type_code][group_code])


sectionRef string

reference to the id of a section


typeRef string

reference to the id of a type


groupRef string

reference to the id of a group


order int

an integer used to order the objects


midiEvents array

list of midi events attached to this folder, all of these are mandatory

  • SHOW
  • HIDE
  • COLLAPSE
  • EXPAND
  • FILTER_NOT

 

{
    "(b)": {
        "id": "(b)",
        "sectionRef": "BRASS",
        "typeRef": null,
        "groupRef": null,
        "order": "400000",
        "midiEvents": {
            "FILTER_NOT": {
                ...
            },
            "HIDE": {
                ...
            },
            "SHOW": {
                ...
            },
            "COLLAPSE": {
                ...
            },
            "EXPAND": {
                "...
            }
        },
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The vendor object defines a vendor node to which then several libraries might be attached. Its code must be composed by 2 characters.

Each object must be declared in one separate JSON file with a name ending with -v.json

Attributes


objectIdentifier string

same as id


id string

unique id of the vendor with two characters, must not contain space and must be all uppercase


name string

name of the vendor


order int

an integer used to order the objects


midiEvents string

list of midi events attached to this folder, all of these are mandatory

  • SHOW
  • HIDE
  • FILTER_NOT

 

{
    "SA": {
        "id": "SA",
        "name": "Spitfire Audio",
        "order": 10,
        "midiEvents": {
            "FILTER_NOT": {
                ...
            },
            "HIDE": {
                ...
            },
            "SHOW": {
                ...
            }
        },
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The fader object defines the mapping with one specific controller that can be controlled via a fader, typically used for quick controls, microphones and generic vst faders.

Each object must be declared in one separate JSON file with a name ending with -f.json

Attributes


objectIdentifier string

same as id


id string

unique id of the fader following naming convention, must not contain space and must be all uppercase

for fader: CC[number of controller]_[id of the fader]

for mics: CC[number of controller]M_[id of the fader]


name string

name of the fader


cc int

number of controller to trigger


defaultValue string

default value of the fader from 0 to 1.0


isMicrophone boolean

true if is a microphone


{
    "CC11_EXPRESSION": {
        "id": "CC11_EXPRESSION",
        "name": "Expression",
        "cc": 11,
        "defaultValue": 1.0,
        "isMicrophone": false,
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The instrument object defines an instrument node which can be linked to tracks.

Each object must be declared in one separate JSON file with a name ending with -i.json

Attributes


objectIdentifier string

same as id


id string

unique id of the instrument following naming convention

[section_code].[name of instrument]


name string

name of the instrument


sectionRef string

referene to a section id


order int

an integer used to order the objects


midiEvents array

list of midi events attached to this folder, all of these are mandatory

  • SHOW
  • HIDE
  • FILTER_NOT
{
    "b.Horn": {
        "id": "b.Horn",
        "name": "Horn",
        "sectionRef": "BRASS",
        "order": "40040",
        "midiEvents": {
            "FILTER_NOT": {
                ...
            },
            "HIDE": {
                ...
            },
            "SHOW": {
                ...
            }
        },
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The quick control object defines the settings for the quick control fader and is used within the library object.

For each library there must be 8 of it defined.

Attributes


order int

the order of the quick control from 1 to 8


faderRef string

reference to a fader id

{
    "order": 1,
    "faderRef": "CC1_DYNAMICS",
    "version": "1.0.0",
    "copyright": "www.artificialharmonics.com"
}

The library object defines the library node, there must be one for each library.

Each object must be declared in one separate JSON file with a name ending with -l.json

Attributes


objectIdentifier string

same as id


id string

a 4 character unique identifier of the library


name string

the name of the library


vendorRef string

reference to a vendor id


sectionRef string

reference to a section id


order int

an integer used to order the objects


instrumentsRef array

an array containing references to instruments id which are part of the library


cubaseTrackRef array

an array containing references to the cubase track id that are part of the library


quickControls array

an array containing a list of quick control objects


midiEvents array

list of midi events attached to this folder, all of these are mandatory

  • SHOW
  • HIDE
  • FILTER_NOT

{
    "SAL1": {
        "id": "SAL1",
        "name": "Spitfire Albion One",
        "vendorRef": "SA",
        "sectionRef": "ORCHESTRA",
        "order": "20100015",
        "instrumentsRef": ["w.Woodwinds_High", "w.Woodwinds_Low", ...],
        "cubaseTrackRef": ["01_000_060", "01_000_061", ...],
        "quickControls": [{
                "order": 1,
                "faderRef": "CC1_DYNAMICS",
                "version": "1.0.0",
                "copyright": "www.artificialharmonics.com"
            }, {
                "order": 2,
                "faderRef": "CC11_EXPRESSION",
                "version": "1.0.0",
                "copyright": "www.artificialharmonics.com"
            }, {
                "order": 3,
                "faderRef": "CC21_VIBRATO",
                "version": "1.0.0",
                "copyright": "www.artificialharmonics.com"
            }, ...
        ],
        "midiEvents": {
            "FILTER_NOT": {
                ...
            },
            "HIDE": {
                ...
            },
            "SHOW": {
                ...
            }
        },
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The track object defines the track node and is mapped to one single midi track in Cubase.

Each object must be declared in one separate JSON file with a name ending with -t.json

Attributes


objectIdentifier string

a concatenation of the midi channel + value 1 + value 2 as defined in the midi send 1 of the cubase track. Please note that there must always be exactly 8 digits


id string

a unique identifier of the track, does not have to contain space following naming convention

[library_id]_[track name]


name string

the name of the track


dawTrackName string

the name of the track as shown in the DAW


libraryRef string

reference to a library id


folderRef string

reference to a folder id


order int

an integer used to order the objects


micsRef array

an array containing references to faders id which are all microphones


fadersRef array

an array containing references to faders id


instrumentsRef array

an array containing a list of instruments id


midiEvents array

list of midi events attached to this folder, all of these are mandatory

  • SHOW

{
    "01_000_060": {
        "id": "SAL1_Woodwinds_High",
        "name": " Woodwinds High",
        "dawTrackName": "(weh).SAL1 Woodwinds High",
        "libraryRef": "SAL1",
        "folderRef": "(weh)",
        "order": "301010010",
        "micsRef": ["CC22M_CLOSE", "CC23M_TREE", "CC24M_AMBIENT", "CC25M_OUTRIGGER"],
        "fadersRef": ["CC1_DYNAMICS", "CC11_EXPRESSION", "CC17_RELEASE", "CC18_TIGHTNESS", "CC19_REVERB", "CC7_VOLUME"],
        "instrumentsRef": ["w.Woodwinds_High"],
        "midiEvents": {
            "SHOW": {
                ...
            }
        },
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The articulation object defines an articulation that can be reused within multiple expression maps.

Each object must be declared in one separate JSON file with a name ending with -av.json

Attributes


objectIdentifier string

same as id


id string

unique id of the articulation, name must not contain space


shortName string

short name of the articulation


longName string

long name of the articulation


order int

an integer used to order the objects, this order will be used in the expression map


type String

can be one of these two values

  • Direction: articulations that refers to a way of playing like con sordina, sul ponticello
  • Attribute: articulations that are set on the note, like spiccato, staccato
{
    "LEGATO": {
        "id": "LEGATO",
        "shortName": "Leg",
        "longName": "Legato",
        "order": "00200000",
        "type": "Direction",
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The expression map object defines the expression map assigned to each track

Each object must be declared in one separate JSON file with a name ending with -x.json

Attributes


objectIdentifier string

same as id


id string

unique id of the expression map following the naming convention

[library_id]_[track name]


name string

name of the expression map


slots array

array of slots object, each slot object is composed of the following properties


   remote int

an incremental number starting from 0 mapped to the remote id in Cubase expression map


   articulationRef string

reference to an articulation id


   outputMapping object

an object that contains the information of the mapping to cc or keyswitch to change the articulation.

The object is composed of the following properties:


      type string

can be one of these values:

  • Controller
  • Note-On

      data1 string

value of data1 as defined in Cubase expression map


      data2 string

value of data2 as defined in Cubase expression map

{
    "SAL1_Woodwinds_High": {
        "id": "SAL1_Woodwinds_High",
        "name": "SAL1 Woodwinds High",
        "slots": [{
                "remote": 0,
                "color": 11,
                "outputMapping": [{
                        "type": "Controller",
                        "data1": "32",
                        "data2": "20"
                    }],
                "articulationRef": "LEGATO"
            }, {
                "remote": 1,
                "color": 9,
                "outputMapping": [{
                        "type": "Controller",
                        "data1": "32",
                        "data2": "1"
                    }],
                "articulationRef": "LONG"
            }, {
                "remote": 2,
                "color": 9,
                "outputMapping": [{
                        "type": "Controller",
                        "data1": "32",
                        "data2": "2"
                    }],
                "articulationRef": "LONG_ARRANGED"
            }, {
                "remote": 3,
                "color": 7,
                "outputMapping": [{
                        "type": "Controller",
                        "data1": "32",
                        "data2": "40"
                    }],
                "articulationRef": "STACCATO"
            }, {
                "remote": 4,
                "color": 7,
                "outputMapping": [{
                        "type": "Controller",
                        "data1": "32",
                        "data2": "21"
                    }],
                "articulationRef": "STACCATO_ARRANGED"
            }],
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

The articulation object defines an articulation that can be reused within multiple expression maps.

Each object must be declared in one separate JSON file with a name ending with -m.json

Attributes


objectIdentifier string

name of the macro, this name must be equal to the name of the logical preset that will be triggered


host string

since Cubase allows only Midi connection this is always set to “midi”


port string

the midi port to which this action will be mapped


address string

the type of midi message to be sent by open stage control, all the possible values can be found here https://openstagecontrol.ammd.net/docs/midi/midi-messages/


channel int

the midi channel of the action


value1 string

the value of the midi message


category string

the category of this macro, one tab will be created in the UI per each category declared here


order int

an integer used to order the macros within the UI


name string

name of the macro


label string

label as shown in the UI, can be one from https://fontawesome.com/ just put ^ character before the name


color string

the color used to render the macro


next string

can be one of these two values

  • link: the macro will be linked to the next one
  • space: the macro will not be linked to the next one
{
    "All_tracks_Collapse_All": {
        "host": "midi",
        "port": "flow3",
        "address": "KEY_PRESSURE",
        "channel": 1,
        "value1": 0,
        "category": "All tracks",
        "order": "000001",
        "name": "Collapse All",
        "label": "^folder",
        "color": "#4E5255",
        "next": "link",
        "version": "1.0.0",
        "copyright": "www.artificialharmonics.com"
    }
}

To create a new library you should start creating content following the order described in this document.

Whenever possible you should reuse existing json data instead of creating copies of it.