ArtiCluster 1.1.1

ArtiCluster

ArtiCluster is conversion and management tool that supports articulation mapping files across DAWs.

Overview

We define a DAW-independent intermediate format (referred to as “Universal Definition” in ArtiCluster) and convert it into key switch and articulation definition files for each DAW.

I have published the files I converted myself in the GitHub repository below.

https://github.com/r-koubou/ArticulationMappingFiles

This software is the successor to KeySwitchManager and was redesigned from scratch to address several issues.

Supported DAW

• Cubase / Nuendo (*.expressionmap)
• Cakewalk / Sonar (*.artmap)
• Logic Pro (*.plist)
• Studio Pro / Studio One (*.keyswitch)

Requirements

• .NET 10

Installation and Update

Installation

dotnet tool install --global ArtiCluster

Update

dotnet tool update --global ArtiCluster

Uninstall

dotnet tool uninstall --global ArtiCluster

ArtiCluster Command Usage

Usage:
  articluster [command] [options]

Options:
  -v, --verbose   Enables verbose logging output
  -?, -h, --help  Show help and usage information
  --version       Show version information

Commands:
  new <path/to/name>                Create a Universal Definition file
  convert <input-dir> <output-dir>  Convert to DAW-specific format.

new command

Usage:
  articluster new <path/to/name> [options]

Arguments:
  <path/to/name>

Options:
  -?, -h, --help  Show help and usage information

convert command

Usage:
  articluster convert <input-dir> <output-dir> [options]

Arguments:
  <input-dir>
  <output-dir>

Options:
  -o, --overwrite                     Overwrite output directory if it already
                                      exists.
  -m, --output-markdown-list-dir <m>  When specifying this option, please
                                      provide the directory path managed by the
                                      static site generator. The same applies
                                      to specifying the directory path for
                                      `output-dir`.
  -?, -h, --help                      Show help and usage information

Getting Started

1. Create a Universal Definition file using the new command.

articluster new ./MyInstrument

2. Edit the generated Universal Definition file to define your articulations and MIDI messages.

You can use any text editor to edit the YAML file. The file structure is defined by the schema, which specifies the required fields and their formats.

We also offer tools that can be edited online.

https://articluster-editor.pages.dev/

3. Use the convert command to generate DAW-specific articulation mapping files from your Universal Definition files.

articluster convert ./input-directory ./output-directory

About Universal Definition (*.yaml)

The Universal Definition is an intermediate format used to convert data into keyswitch and articulation definition files for each DAW.

The following is a sample Universal Definition File.

FormatVersion: 0
Id: f806389c-4e8e-4ede-adde-922e40548c9f
Author: Example Author
ManufacturerName: Example Manufacturer
ProductName: Example Product
PatchName: Example Patch
Description: Example Description
ArticulationGroups:
  - Name: Main
    Articulations:
      - Name: Articulation Name
        MidiMessages:
          - Status: 144
            Data1: 60
            Data2: 100
  - Name: FX
    Articulations:
      - Name: Articulation Name
        MidiMessages:
          - Status: 144
            Data1: 61
            Data2: 100

---

Schema file

• docs/universal-definition/v1-draft/universal-definition-schema.json

Universal Definition Schema

Definition of the Universal Definition v1 file format (DRAFT)

Type: object(?)

---

Definitions

UniversalDefinition

The root of articulation

Examples

FormatVersion: 0
Id: 34023d3f-30b0-4646-90e8-5d2978d09d43
Author: R-Koubou
ManufacturerName: Acme Corp
ProductName: Super Guitar
PatchName: Guitar 1
Description: Guitar 1 articulation.
ArticulationGroups:
- Name: Main
  Articulations:
  - Name: Idle
    MidiMessages: []
  - Name: Sustain
    MidiMessages:
    - Status: 144
      Data1: 64
      Data2: 100
    Extra:
      Extra.Custom.Key: Custom Value
  - Name: Bridge Mute
    MidiMessages:
    - Status: 144
      Data1: 66
      Data2: 100
    Extra:
      Extra.Custom.Key: Custom Value

Type: object

⚠️ Additional properties are not allowed.

Property	Type	Required	Possible values	Deprecated	Default	Description	Examples
FormatVersion	integer	✅	integer			Universal File Format Version	0
Id	string	✅	Format: uuid			Unique identifier for this Universal Definition	259fda39-6197-49e8-aee1-ab1e568635ad
Author	string	✅	string			Author name of this Universal Definition	Your Name
ManufacturerName	string	✅	string			Name of the manufacturer
ProductName	string	✅	string			Name of the product
PatchName	string	✅	string			Name of the patch	Guitar, Bass, Violin
ArticulationGroups	array	✅	ArticulationGroup			List of articulation groups in this Universal Definition. In the case of DAWs that support grouping, this means exporting the articulations defined in this group into a single file. In the case of DAWs that do not support grouping, the groups are ignored, and a file is exported for each articulation within the group.
Description	string		string			Description of this Universal Definition file
Extra	object		Extra

ArticulationGroup

Defines an articulation group with its name and associated articulations

Examples

Name: Main
Articulations:
- Name: Idle
  MidiMessages: []
- Name: Sustain
  MidiMessages:
  - Status: 144
    Data1: 64
    Data2: 100
  Extra:
    Extra.Custom.Key: Custom Value
- Name: Bridge Mute
  MidiMessages:
  - Status: 144
    Data1: 66
    Data2: 100
  Extra:
    Extra.Custom.Key: Custom Value

Name: FX
Articulations:
- Name: Pick Scrape
  MidiMessages:
  - Status: 144
    Data1: 67
    Data2: 100
  Extra:
    Extra.Custom.Key: Custom Value
- Name: Stop
  MidiMessages:
  - Status: 144
    Data1: 68
    Data2: 100
  Extra:
    Extra.Custom.Key: Custom Value

Type: object

⚠️ Additional properties are not allowed.

Property	Type	Required	Possible values	Deprecated	Default	Description	Examples
Name	string	✅	string			A Group name	Main, FX
Articulations	array	✅	Articulation			List of articulations in this group
Extra	object		Extra

Articulation

Defines an articulation with its name and associated MIDI messages

Examples

Name: Sustain
MidiMessages:
- Status: 144
  Data1: 64
  Data2: 100
Extra:
  Extra.Custom.Key: Custom Value

Type: object

⚠️ Additional properties are not allowed.

Property	Type	Required	Possible values	Deprecated	Default	Description	Examples
Name	string	✅	string			Name of the articulation	Sustain, Bridge Mute
MidiMessages	array	✅	MidiMessage
Extra	object		Extra

MidiMessage

A MIDI message within the articulation, consisting of a status byte and two data bytes

Examples

Status: 144
Data1: 64
Data2: 100

Status: 144
Channel: 0
Data1: 64
Data2: 100

Type: object

⚠️ Additional properties are not allowed.

Property	Type	Required	Possible values	Deprecated	Default	Description	Examples
Status	integer	✅	integer			MIDI Status Byte
Channel	integer		-1 <= x <= 15			MIDI Channel (0-15). If -1 or not defined, it will be ignored in conversion
Data1	integer		0 <= x <= 127			MIDI Data Byte 1 (0-127). If not defined, it will be ignored in conversion
Data2	integer		0 <= x <= 127			MIDI Data Byte 2 (0-127). If not defined, it will be ignored in conversion

Extra

Reserved for future use. Can be used to store additional metadata as key-value pairs.

Examples

Extra.Custom.Key: Custom Value

Type: object