TSE3 documentation | Version 0.3.1 | Index API Version Structure

# Cakewalk .ins files

### Introduction

The `Instrument` class provides support for instrument definitions (i.e. textual representations of the program/bank/controller names). These are read from the widely available Cakewalk instrument definition format files. (Cakewalk is a PC sequencing package).

### File format

These files generally have a `.ins` suffix and are of a textual nature.

Unfortunately, the file format is not documented anywhere by Cakewalk, so I have produced my own interpretation of the file format. If anyone knows of any better descriptions I'd love to know!

# Pete's interpretation of the Cakewalk .ins instrument file format

### Overview

The file conists of a number of sections which begin with the following lines (they are generally found in this order, I doubt this is important):

Section name | Description
".Patch Names" | Describes groups of patches
".Note Names" | Describes note names for some patch
".Controller Names" | Describes all controller names for some device
".RPN Names" | Describes RPN values for some device
".NRPN Names" | Describes NPRN values for some device
".Instrument Definitions" | Describes instruments based on above sections

### Section contents

General file conventions:

- Within each of these sections are subsections delimited by "[" and "]".
- Subsection names and other text values may contain spaces.
- Comments begin with a ";" and go to the end of the line. They may occur at any point in a line.
- Subsections may reference other subsections - case is sensitive.
- Patch values default to "0-127" rather than "1-128".

The first 5 sections have practically identical format, and contain a number of subsections. These subsections define a mapping of number (0-127) to textual representation. All or only some of the numbers may be given a mapping. Unspecified entries default to an empty string.

- Each subsection is introduced "[SomeSectionName]".
- The next line may be "BasedOn=" in which case this group of values refers to the named subsection. Any values from the 'base' may be later redefined in this section. The BasedOn 'base' subsection definition may be after of before this subsection in the file.
- There follows any number of lines of the format "X=SomeName" where X is a value 0-127 and SomeName is the text associated with that value.

There are inbuilt patch names "0..127" and "1..128" which are defined as just the numbers.

### The ".Instrument Definitions" section

The ".Instrument Definitions" section is different; it describes instruments based on the information in the previous sections.

- There is a subsection for each instrument defined, the subsection name is the instrument name. The subsection heading is in the format "[SomeInstrument]".
- The definition consists of the following sections, which if removed have the indicated defaults. Each entry is described below.

Name | Default
"UseNotesAsControllers=1" | =0
"Control=" | No controllers for this instrument.
"RPN=" | No RPNs defined
"NRPN=" | No NRPNs defined
"BankSelMethod=" | =0
"Patch[#]=" | No patch for #
"Key[#,%]=" | No key definitions for #,%
"Drum[#,%]=1" | Drum[#,%]=0
Notes "#" represents a bank select value. This is a composite value based on the bank select MSB and LSB which is equal to (MSB<<7)+LSB. "%" represents a program change value.

- The controller names definied for an instrument are given by the "Control=" line. Following the "=" is a subsection name from the ".Controller Names" section.
- The instrument patch names for a given bank value are defined by the "Patch[#]=" line. If # is a "*" then this matches for every bank select. There may be more than one "Patch[#]=" line.
- The "Key[#,%]=" line defines key names for a particular patch on a particular bank select.
- If the "Drum[#,%]=" line sets the drum flag for a patch/bank select value then the editor should default to a drum editor for this voice.
- "BankSelMethod=" takes a value from 0 to 3. These mean

Value | Meaning
0 | Normal - bank select MSB and LSB matter
1 | Only the MSB is used and defined
2 | Only the LSB is used and defined
3 | Only program changes are used and defined

- The "UseNamesAsController=" line denotes useage as for the "Mackie OTTO-1604". I have no idea what this means ;-)

© Pete Goodliffe, 2001-2003 | Copyright | Psalm 150