You are on page 1of 22

A small guide for Overtures VST XML writers

Introduction
Hello, Nice members in GenieSoft users 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 dont 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.11; Feb/22/2007 Version 0.2; Feb/26/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

1/22

A small guide for Overtures VST XML writers

Brief overview
A VST definition XML file consists of these seven sections below. 1. 2. 3. 4. 5. 6. 7. XML header section Articulation section Key switch section Controller section Note name section Instrument section Sub section; Switch list section for Articulation, etc.

Very simple it is. You dont 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 Overtures menu and its dialog-boxes. Right, XML changes Overtures default settings, for example, Score/Set up Track menu, Score/Articulations menu, Edit expression dialog-box and so on. Lets 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.

2/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 XMLs 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.
<VSTNameDocument> <Version>1</Version> <Author>GenieSoft,Inc.</Author> <Device name="Garritan Personal Orchestra">

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

Dos and Don'ts You must name XMLs 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?

3/22

2. Articulation section
Articulation section sets various values to Articulation symbols.
<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" />

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.

4/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 SForzando Dot Staccato Down Bow Arpeggio Tremolo Thirty Seconds Marcato Dot SForzando Dot Inverted Tenuto Up Bow Inverted Tremolo Eighths Tremolo Sixty Fourths Heavy Attack Staccatissimo Up Bow Down Bow Inverted Tremolo Sixteenths 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)" />

5/22

Words in XML which represent Overtures items, No.1 In XML In Overture velocityAdd Change velocity with Add to velocity velocityPct Change velocity with Scale velocity by ctrlNum ctrlValue ctrlOffValue durationPct keySwitch attackFrom attackTo tremoloNotes onOffset Send Controller Send Controller (at note On) Value Send Controller (at note Off) Value Change duration to % of notated value Send Key Switch Change attack from Change attack to Measured tremolo (number of beams) Send Offset by clocks

Value sample 0, 10,20,127 0,.,100 0,1,2,.,127 0, 10,20,127 0, 10,20,127 0,.,100 C0,D0, F2

1,2,3, 10, -10

There may be more reserved words which I dont know.

6/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.
<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>

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.
<Section name="Section Strings" portamento="on" clef="treble"> <UsesArticulationSwitchList name="Strings" /> <UsesKeySwitchList name="Section Strings" /> <UsesControllerSwitchList name="Section Strings" /> </Section>

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

7/22

But sorry to say, we cant 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.
<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>

I dont 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.
<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>

In addition, there are two cc=64 in above quotation from GPO XML. Perhaps this might be a mistake, or Overtures feature might be altered at some point. At the drop-down menu of controller, later Damping off is effective, and Damping on isnt displayed at any dialog-box. There can be only one name against any
8/22

given cc#, and its value= sentence doesnt 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. Youll 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.

9/22

5. Note name section


Note name section seems to exist as Drum map definition.
<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>

b-3 means note B0 if you set middle C to C3 at Overtures Option/Preference menu, or it means B1 if you set middle C to C4. -3 is relative value with middle Cs octave. This picture is Setup Track window for Percussion track. I think this Note name section isnt working well now, although Percussion Instrument section has a statement <UsesNoteNameList name="GM Drum Sounds" />. Do I get it wrong?

10/22

6. Instrument section
Instrument section may look very complicate, but it is simple. This section has a tree structure.
VST Device

Woodwinds Section

Brass Section

XXX Section

Flutes Group
English horn Plr.1 Instrument

Oboe and Eng. Horn Group


English horn Plr.2 Instrument Oboe modern Plr.1 Instrument

You can also see the same structure at Overtures Track Properties dialog-box. This dialog-box shows us what we defined at Instrument section in XML document.

11/22

This is a short abstract from Instrument 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" </Group> </Section> </Instruments> abbr="AFl. 1" lownote="g3" highnote="c7" ksoctave="3" transpose="5" />

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.

12/22

Words in XML which represent Overtures items, No.2 In XML In Overture Instrument name (is shown at Track Properties) title Main abbr Abbr lownote Ranges Low Note highnote Ranges High Note ksoctave (to substitute KS octave variable) transpose Transpose Part clef Starting Clef? pitch Transpose Playback, Pitch

Value sample Alto Flute 1 AFL.1 g3 c7 3 2 alt, bass -12

velocity

legato =off portamento

(to use velocity as hairpins volume on controller not MIDI controller change, when playback) (to cancel Articulation name legato) N.A on, off

This table is uncompleted.

13/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.

<ControllerNames> <ControllerSwitchList name="Woodwinds"> <controller name="Vibrato Speed" cc="17" /> <controller name="Vibrato Level" cc="131" /> </ControllerSwitchList> </ControllerNames>

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.
<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" />

14/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.
<VSTNameDocument> <Version>1</Version> <Author>GenieSoft,Inc.</Author> <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>

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> <Version>1</Version> <Author>GenieSoft,Inc.</Author> <Device name="Kontakt2 Library"> <ArticulationNames> <Articulation name="Marcato" velocityAdd="10" durationPct="90" />

15/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.
<Section name="Keyboards" lownote="a0" highnote="c8" clef="treble" legato="off" velocity="on"> <Instrument name="Steinway Piano" title="Piano" abbr="Pf." /> </Section>

If you want to use MIDI CC to control volume, you dont 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?

16/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.

17/22

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

<VSTNameDocument> <Version>1</Version> <Author>___________</Author> <Device name="__________________________"> <ArticulationNames> <Articulation ctrlNum="nnn" durationPct="nnn" /> <ArticulationSwitchList name="_________"> <Articulation ctrlNum="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" /> </ControllerSwitchList> </ControllerNames> <NoteNames> <NoteNameList name="________Drum Sounds"> <NoteName name="_____________" pitch="b-3" /> </NoteNameList> </NoteNames> name="_________" ctrlValue="nnn" velocityAdd="nnn" ctrlOffValue="nnn" name="_________" ctrlValue="nnn" velocityAdd="nnn" ctrlOffValue="nnn"

durationPct="nnn" />

18/22

<Instruments> <Section name="__________" transpose="nn" lownote="a0" pitch="-nn" highnote="c8" legato="off" clef="treble" velocity="on"> <UsesArticulationSwitchList name="__________" /> <UsesControllerSwitchList name="__________" /> <UsesKeySwitchList name="___________" /> <UsesControllerValueList name="__________" /> <UsesNoteNameList name="______Drum Sounds" /> <Group legato="off" _______ " > <Instrument name="_________" title="_______" abbr="______" ksoctave="3" lownote="g3" highnote="c7" transpose="5" name ="__________" lownote="a0"

highnote="c8" clef="treble" transpose="nn" pitch="-nn" velocity="on" Articulation="_______,

Articulation="_______, _______, " /> <UsesArticulationSwitchList name="_______" /> <UsesControllerSwitchList name="________" /> <UsesKeySwitchList name="__________" /> <UsesControllerValueList name="_________" /> <UsesNoteNameList name="__Drum Sounds" /> (</Instrument>) </Group> </Section> </Instruments> </Device> </VSTNameDocument>

19/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 dont 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.
20/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 dont 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 doesnt 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.

21/22

Thanks for your reading.

22/22

You might also like