Overture4 VST XML Guide

1/22

A small guide for Overture’s VST XML writers

Introduction

Hello, Nice members in GenieSoft user’s forum.

I said “I will write something like a manual about making VST XML for Overture

4 in past days at this forum. Writing XML seems difficult to approach at the first

glance, but it is not so hard. I myself wrote an XML document last year for the

first time without reading any manuals. If you watch one or two XML files in the

folder,

“C:\Programfiles\Geniesoft\Overture4.0\VSTDevices\”, you would instantly

understand how to write XML for VST. You can read and edit XML with

Notepad.exe or ordinary text editing software.

So, I decided to write mainly what XML will affect in your score. VST XML

changes various settings of tracks and symbols, although I don’t understand

mechanisms perfectly. I hope you to enjoy this journey with me, and please tell

me what I misunderstood about them at the forum. I believe this document is full

of mistakes. ☺

Version 0.1; Feb/20/2007



Version 0.21; Mar/05/2007

-----------------------------------------------------------------------------------

Tatsu Nagao

http://www.acidplanet.com/artist.asp?songs=331238&T=9191

Thinkpad T43, T41, YAMAHA P-120, Fender JP ST58-70TX,

Overture4, Kontakt2, Cubase Studio4

2/22

A small guide for Overture’s VST XML writers

Brief overview

A VST definition XML file consists of these seven sections below.

1. XML header section

2. Articulation section

3. Key switch section

4. Controller section

5. Note name section

6. Instrument section

7. Sub section; Switch list section for Articulation, etc.

Very simple it is. You don’t have to be worry about reading and writing XML.

Provably you are very familiar with these words such as Articulation, Key switch

and Controller, and in this document, you will find other words which are used at

Overture’s menu and its dialog-boxes. Right, XML changes Overture’s default

settings, for example, Score/Set up Track menu, Score/Articulations menu, Edit

expression dialog-box and so on.

Let’s see what the XML for Garritan Personal Orchestra describes, and see

which menu or dialog-box it changes. This XML is very well-written. Thanks

Joseph, its author and the dedicated volunteer.

3/22

1. XML header section

XML needs a header section to tell software that this file is written in XML. By

ordinary, the first line of XML declares XML’s specification version and its

character set, but this XML for GPO has version and author. And, you have to

write this “Device name” just as same as the name which you see at VST

instrument rack. It is not necessarily the case that device name is identical

with the name of its plug-in dll file.

For example, the plug-in filename of GPO is “PersonalOrchestra.dll”, but

“Device name” in the XML is “Garritan Personal orchestra”.

And also, the filename of this XML must be “Garritan Personal orchestra.xml”.

Dos and Don'ts

You must name XML’s file-name just all the same as the name of VST

which is shown at VST instrument rack or Track Window (Ctrl + Shift + T).

And, please read 8-1. How do I name VST device when I use

Kontakt2?

<VSTNameDocument>

<Version>1</Version>

<Author>GenieSoft,Inc.</Author>

<Device name="Garritan Personal Orchestra">

4/22

2. Articulation section

Articulation section sets various values to Articulation symbols.

Please read a sentence on the third line, and compare it with the picture below.

This is the picture of “Score / Articulation / Marcato dot” menu. You will find a

general rule. All of the contents in the sentence are reflected in the values of this

dialog-box.

<ArticulationNames>

<Articulation name="Marcato" velocityAdd="30" />

<Articulation name="Marcato Dot" velocityAdd="30"

ctrlNum="21" ctrlValue="30" ctrlOffValue="64"

durationPct="50" />

<Articulation name="Heavy Attack" velocityAdd="30"

durationPct="100" />

5/22

By the way, where is <ctrlOffValue=”64”>? It will be found in this picture.

This table shows some of Articulation names which you can use in your

Articulation section.

Words which you can define at Articulation section in XML documents

Marcato Marcato Dot Heavy Attack

SForzando Dot SForzando Dot Inverted Staccatissimo

Staccato Tenuto Up Bow

Down Bow Up Bow Inverted Down Bow Inverted

Arpeggio Tremolo Eighths Tremolo Sixteenths

Tremolo Thirty Seconds Tremolo Sixty Fourths legato *1

*1 legato represents slur symbol (arc).

And, you can also define these Expression words at Articulation section.

pizz arco

Sentences are like these in this case.

<Articulation name="pizz" keySwitch="F(x)" />

<Articulation name="arco" keySwitch="C(x)" />

6/22

Words in XML which represent Overture’s items, No.1

In XML In Overture Value sample

velocityAdd Change velocity with

Add to velocity

0, 10,20,127

velocityPct Change velocity with

Scale velocity by

0,….,100

ctrlNum Send Controller 0,1,2,….,127

ctrlValue Send Controller (at note On)

Value

0, 10,20,127

ctrlOffValue Send Controller (at note Off)

Value

0, 10,20,127

durationPct Change duration to % of notated value 0,….,100

keySwitch Send Key Switch C0,D0, F2

attackFrom Change attack from

attackTo Change attack to

tremoloNotes Measured tremolo (number of beams) 1,2,3,

onOffset Send Offset by clocks 10, -10

There may be more reserved words which I don’t know.

7/22

3. Key switch section

You can define a key switch name list for each instrument, for each group, for

each section and for whole of VST instrument as you want.

In these sentences, variable “(x)” represents octave height, and it will work with

word “ksoctave=” which is described later. You can also define it with a fixed

value like “C#2”. And you have to give instructions as follows at Instrument

section. This need is applicable to Articulation and Controller.

As a result, you will be able to see key switch names at Articulation dialog-box.

<KeySwitchList name="Section Strings">

<KeySwitch name="Sust+Short" key="C(x)" />

<KeySwitch name="Sust+Short Mutes" key="C#(x)" />

<KeySwitch name="Upbows" key="D#(x)" />

<KeySwitch name="Downbows" key="E(x)" />

<KeySwitch name="Pizzicato" key="F(x)" />

</KeySwitchList>

<Section name="Section Strings" portamento="on" clef="treble">

<UsesArticulationSwitchList name="Strings" />

<UsesKeySwitchList name="Section Strings" />

<UsesControllerSwitchList name="Section Strings" />

</Section>

8/22

But sorry to say, we can’t see the names at Edit Expression dialog-box. And

there is no Expression section in XML documents.

4. Controller section

What you write in this section will effect in Controller pull-down menu at

Articulation dialog-box and Edit Expression dialog-box like Key switch names list

as mentioned above.

I don’t understand very well about ““on=127” and “off=0” at “<Controller

name=”Legato/Sustain”>”. These values, 127 and 0 are not reflected in the

controller value box of Articulation Playback dialog-box.

Each instrument or group or section can have unique definition for itself as you

saw at Key Switch section.

In addition, there are two “cc=64” in above quotation from GPO XML. Perhaps

this might be a mistake, or Overture’s feature might be altered at some point. At

the drop-down menu of controller, later “Damping off” is effective, and “Damping

on” isn’t displayed at any dialog-box. There can be only one name against any

<ControllerNames>

<Controller name="Volume (Mod Wheel)" cc="1" />

<Controller name="(Optional) Volume" cc="7" />

<Controller name="(Optional) Panning" cc="10" />

<Controller name="Legato/Sustain" cc="64" on="127" off="0" />

<Controller name="Legato Notation Set" cc="68" />

</ControllerNames>

<ControllerSwitchList name="Percussion"

<controller name="Aggressive Hits (Bass Drum Only)" cc="16" />

<controller name="BDFund (Bass Drum Only)" cc="20" />

<controller name="Damping on" cc="64" value="127" />

<controller name="Damping off" cc="64" value="0" />

</ControllerSwitchList>

9/22

given cc#, and its “value=” sentence doesn’t work.

By the way, for example, after you insert a sentence,

<UsesControllerSwitchList name="Percussion" />

into Instrument section, above Controller switch list name definition becomes

effective. You’ll see things about Instrument section later in this document.

As a result, you can see Controller names at Articulation Playback dialog-box on

Percussion track.

10/22

5. Note name section

Note name section seems to exist as Drum map definition.

“b-3” means note B0 if you set middle C to C3 at Overture’s Option/Preference

menu, or it means B1 if you set middle C to C4. “-3” is relative value with middle

C’s octave.

This picture is Setup Track window for Percussion track. I think this Note name

section isn’t working well now, although “Percussion” Instrument section has a

statement “<UsesNoteNameList name="GM Drum Sounds" />”. Do I get it wrong?

<NoteNames>

<NoteNameList name="GM Drum Sounds">

<NoteName name="Acoustic Bass Drum" pitch="b-3" />

<NoteName name="Bass Drum 1" pitch="c-2" />

<NoteName name="Side Stick" pitch="c#-2" />

<NoteName name="Acoustic Snare" pitch="d-2" />

……..

<NoteName name="Open Hi-Hat" pitch="a#-1" />

<NoteName name="Low-Mid Tom" pitch="b-2" />

</NoteNameList>

</NoteNames>

11/22

6. Instrument section

Instrument section may look very complicate, but it is simple. This section has a

tree structure.

You can also see the same structure at Overture’s Track Properties dialog-box.

This dialog-box shows us what we defined at Instrument section in XML

document.

VST

Device

Woodwinds

Section

Brass

Section

XXX

Section

Flutes

Group

Oboe and Eng. Horn

Group

English horn Plr.1

Instrument

English horn Plr.2

Instrument

Oboe modern Plr.1

Instrument

12/22

This is a short abstract from Instrument section.

Thankfully, you can write enormous numbers of <Section name-> & </Section>,

<Group name=> & </Group> and <Instrument name= …………………….. /> in

this section.

I think things written in Instrument section should change values at Setup Track

dialog-box, but do not change them in fact. There may be a rational reason.

<ksoctave=”3”> in above <Instrument name=> sentence substitutes its value 3

to the variable (x) in <KeySwitch name="Vibrato" key="C(x)" /> for

example, as mentioned at 3. Key switch section.

<Instruments>

<Section name="Woodwinds" clef="treble" portamento="on">

<UsesControllerSwitchList name="Woodwinds" />

<Group name="Flutes" title="Flute">

<UsesKeySwitchList name="Flutes" />

<Instrument name="Alto Flute Plr. 1" title="Alto Flute

1" abbr="AFl. 1" lownote="g3" highnote="c7"

ksoctave="3" transpose="5" />

</Group>

</Section>

</Instruments>

13/22

Words in XML which represent Overture’s items, No.2

In XML In Overture Value sample

Instrument name (is shown at Track Properties)

title Main Alto Flute 1

abbr Abbr AFL.1

lownote Ranges Low Note g3

highnote Ranges High Note c7

ksoctave (to substitute KS octave variable) 3

transpose Transpose Part 2

clef Starting Clef? alt, bass

pitch Transpose Playback, Pitch -12

velocity (to use velocity as hairpin’s volume

controller not MIDI controller change,

when playback)

on

legato =”off” (to cancel Articulation name “legato”)

portamento N.A on, off

This table is uncompleted.

14/22

7. Switch list section for Articulation, etc.

Each section or each group or each instrument has its unique articulations,

controllers, notes, and key switches. By using Switch list section, you can write

instrument-proprietary definitions.

And then, if you write <Uses____SwitchList name="____" /> in Section name

or Group name or Instrument name section, it will come into effect for exclusive

use.

<ControllerNames>

<ControllerSwitchList name="Woodwinds">

<controller name="Vibrato Speed" cc="17" />

<controller name="Vibrato Level" cc="131" />


</ControllerNames>

<Instruments>

<Section name="Woodwinds" clef="treble" portamento="on">

<UsesControllerSwitchList name="Woodwinds" />

<Group name="Flutes" title="Flute">

<UsesKeySwitchList name="Flutes" />

<Instrument name="Alto Flute Plr. 1" title="Alto

Flute 1" abbr="AFl. 1" lownote="g3" highnote="c7"

ksoctave="3" transpose="5" />

15/22

8. Miscellaneous

8-1. How do I name VST device when I use Kontakt2 (or GVI)?

At first, open “Kontakt2.xml” and make an entry of library name which you want

to add by using <Include name=”_____________”> sentence.

Next, make a new XML file which name is the same as added in above

“Kontakt2.xml”. In this case, new file name must be “Kontakt2 Library.xml”. The

device name in the following XML must be “Kontakt2 Library” as which you wrote

in the above XML in this case

<VSTNameDocument>



<Device name="Kontakt2">

<Include name="Kontakt2 Library" />

<Include name="Bela D Media Diva" />

<Include name="Bela D Media Lyrical Distortion" />

<Include name="EWQL Platinum Winds" />

<Include name="Garritan Personal Orchestra" />

<Include name="Garritan Jazz and Big Band" />

<Include name="Post Musical Instruments" />

<Include name="Precision Sounds" />

<Include name="Primesounds" />

</Device>

</VSTNameDocument>

<VSTNameDocument>



<Device name="Kontakt2 Library">

<ArticulationNames>

<Articulation name="Marcato" velocityAdd="10"

durationPct="90" />

16/22

8-2. Controlling dynamics with velocity or MIDI CC

Some sound libraries, for example, piano and percussion libraries use velocity

data to control volume and tone color, and others use MIDI CC such as

modulation(CC#1), volume(CC#7) and expression(CC#11) to do so.

If you want to use velocity to control volume, you have to write <velocity=”on” />

at Instrument section.

If you want to use MIDI CC to control volume, you don’t have to write that.

I have a question about how to assign a specific CC# to volume controller. How

does Overture know which CC# to assign at Edit Dynamic dialog-box?

<Section name="Keyboards" lownote="a0" highnote="c8" clef="treble"

legato="off" velocity="on">

<Instrument name="Steinway Piano" title="Piano" abbr="Pf." />

</Section>

17/22

8-3. How can I analyze and edit XML more effectively

I use “XML Editor”, a freeware like this. It enables me to edit XML as if I use

spread sheet software.

http://www15.plala.or.jp/hayashiyui/index.html

And Microsoft provides us a freeware “XML notepad 2007”.

18/22

8-4. Is there a template for VST XML?

<VSTNameDocument>


<Author>___________</Author>

<Device name="__________________________">

<ArticulationNames>

<Articulation name="_________" velocityAdd="nnn"

ctrlNum="nnn" ctrlValue="nnn" ctrlOffValue="nnn"

durationPct="nnn" />

<ArticulationSwitchList name="_________">

<Articulation name="_________" velocityAdd="nnn"

ctrlNum="nnn" ctrlValue="nnn" ctrlOffValue="nnn"

durationPct="nnn" />

</ArticulationSwitchList>

</ArticulationNames>

<KeySwitchNames>

<KeySwitchList name="________">

<KeySwitch name="_______" key="C(x)" />

</KeySwitchList>

</KeySwitchNames>

<ControllerNames>

<Controller name="Volume (Mod Wheel)" cc="1" />

<ControllerSwitchList name="____________">

<Controller name="___________" cc="nnn" />


</ControllerNames>

<NoteNames>

<NoteNameList name="________Drum Sounds">

<NoteName name="_____________" pitch="b-3" />

</NoteNameList>

</NoteNames>

19/22

<Instruments>

<Section name="__________" lownote="a0" highnote="c8"

clef="treble" transpose="nn" pitch="-nn" legato="off"

velocity="on">

<UsesArticulationSwitchList name="__________" />

<UsesControllerSwitchList name="__________" />

<UsesKeySwitchList name="___________" />

<UsesControllerValueList name="__________" />

<UsesNoteNameList name="______Drum Sounds" />

<Group name ="__________" lownote="a0"

highnote="c8" clef="treble" transpose="nn" pitch="-nn"

legato="off" velocity="on" Articulation="_______,

_______ " >

<Instrument name="_________" title="_______"

abbr="______" lownote="g3" highnote="c7"

ksoctave="3" transpose="5"

Articulation="_______, _______, " />

<UsesArticulationSwitchList name="_______" />

<UsesControllerSwitchList name="________" />

<UsesKeySwitchList name="__________" />

<UsesControllerValueList name="_________" />

<UsesNoteNameList name="__Drum Sounds" />

(</Instrument>)

</Group>

</Section>

</Instruments>

</Device>

</VSTNameDocument>

20/22

9. Remaining issues

9-1. Automatic chasing function

Overture has useful Automatic Chasing function when you use VST XML for

sound libraries. For example, just after an expression word “pizz” automatically

hit a key switch, when you stop playback and replay from the top of the score,

Overture makes “arco” sound automatically.

On this occasion, how does Overture know the default key switch or controller

value for that library to initialize its sound?

9-2. Words and sentences which we can use

We analyzed existing XML files in the “VSTDevices” folder, but we don’t

completely understand words and sentences which we can use in XML. We

hope Don will disclose a dictionary on VST XML when he has free time.

9-3. Articulation symbols which we can assign in XML

It seems that symbols which we can define in XML documents are limited to

those displayed at Score/Articulation Playback dialog-box. We ardently hope

Overture will lift the restrictions on the availability of articulation symbols,

especially on “Pedal Down” and “Pedal Up”.

9-4. “Set up Track” dialog-box

As I wrote at “6.Instrument section”, I see that the contents <transpose=> and

<pitch=> written in the XML document are not reflected in Set up Track

dialog-box correctly. Maybe, I misunderstand.

21/22

9-5. Volume Controlling, velocity or controller change

We know experientially that a sentence “<velocity=”on” /> in Instrument names

section will assign velocity to volume controller at Edit Dynamic dialog-box.

But we don’t know how to assign a specific CC# to volume controller.

9-6. Automatic Remapping

Overture has its unique feature, “Automatic Remapping”. It dose automatically

change settings at some dialog-boxes such as instrument name, articulation and

dynamic in accordance with the change of track property. But, it doesn’t seem to

do without fail. For example, please test switching from “Section Strings” to

“Keyboards” and the reverse using Track Properties dialog-box. Do you make

certain of having this “Do you wish to replace….” message?

9-7. Automatic XML creating

VST XML has simple structure, so it seems easy for Overture to create XML

automatically like Cubase4 creates XML for VST plug-in settings automatically.

If so, we can save settings for VST without our writing XML. To implement this

feature, Overture would need some more user interfaces such as Edit/Controller

menu, Edit/Expression menu and Edit/Dynamic menu, etc, but I hope coming

Overture 5 will implement this feature.

22/22

Thanks for your reading.

Documents

Overture4 VST XML Guide