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:

system
midi events
folders
vendors
faders
instruments
quick controls
libraries
tracks
articulations
expressionMaps
macros

All the json data model contains the following two attributes

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

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

There are three types of data included:

Sections
Types
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

SHOW: triggers in Cubase a logical preset to show this specific object
HIDE: triggers in Cubase a logical preset to hide this specific object
COLLAPSE: triggers in Cubase a logical preset to close this object (only for folders)
EXPAND: triggers in Cubase a logical preset to open this object (only for folders)
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.

Flow+ technical documentation

1. System

1.1. Section

1.2. Type

1.3. Group

2. Midi Events

3. Folders

4. Vendors

5. Faders

6. Instruments

7. Quick controls

8. Libraries

9. Tracks

10. Articulations

11. Expression maps

12. Macros

13. Starting up