======Release Notes for DrumGizmo-0.9.17======
Roadmap: [[roadmap:features_roadmap#version_0917]]\\

In this release we tried to jam in as many of our planned changes to the xml as possible. There are still a few more to go but this release has brought us a large step closer to our feature-complete xml format.
Quite a few other major features has also found their way into this release, which will be much more visible (and audible) to the users.

Highlights:
  * Improved sample selection algorithm.
  * Clicky-kit feature.
  * Midnam support.
  * Directed choke functionality.
  * Drumkit metadata support.
  * Experimental Cocoa UI support for MacOSX.

Also some bug fixes and a lot of code refactoring (replaced eXpat with pugixml for one).

====Improved Sample Selection Algorithm====

On a high level DrumGizmo works as follows: It gets a MIDI note as input which consists of a note value (pitch) and the hardness of the hit (velocity). The pitch tells us which instrument (e.g., snare, bass drum, hi-hat, ...) should be played and the velocity tells us which of all the samples we have for this instrument should be played. Our aim is to make the drums sound as realistic as possible, and therefore we want to make sure that we select "the right" sample.

Until now, DrumGizmo's sample selection method unfortunately did not perform as well as we hoped and it was time to implement a new one. So, let us first think about what "the right sample" has to fulfil:

  * //Close:// It should be pretty close to the velocity that we actually want.
  * //Diverse:// However, it also shouldn't be a sample that we selected very recently, as this would sound unrealistic.
  * //Random:// Even if it selects different samples, it shouldn't have any repeating patterns in the selected samples. Thus, it should be somewhat randomized.
  * //Equal Probability:// Intuitively, the more samples a drumkit has, the more realistic it should sound. However, for this to be true, we also have to use all of the samples that are available. Thus, if two samples have a similar velocity, then we want them to be equally likely to be selected.

While we always want the last point to be true, there is a trade-off between the first three points. Therefore, you can control them in the new sample selection panel! Here is how it looks:

{{ :changelog:sample_selection_frame.png?400 |}}

Now, let us have a listen to how differently the old and new algorithm sound when the input is a midi file with snare hits at the same velocity:

Old:

{{https://drumgizmo.org/media/0.9.17/old.ogg}}

New:

{{https://drumgizmo.org/media/0.9.17/new.ogg}}

That should be enough to convince you. :)

A last note: By setting the power value of groups of samples to the same value when creating a drumkit, and then turning //Close// all the way up and //Diverse// a little bit up when using it, we obtain a round robin drumkit.

{{ :changelog:sample_selection_frame_rr.png?400 |}}

So, our sample selection algorithm is more general and can thus be used very flexibly. Now, try it out and tell us what you think! Especially, we are happy about any feedback that helps us to improve it. :)

Read a more in-depth description of the new algorithm and how it works its <del>magic</del>math in [[documentation:the_sample_selection_algorithm|this]] document. //Note:// This document is work in progress and will be continuously updated.
====Clicky-Kit Feature====
The clicky-kit feature adds the option to audition (and even play) the loaded drumkit.
Not all kits supports this feature yet and the "Drumkit" tab will only show up in the plugin UI if the drumkit contains a clickmap. If a map area is clicked with the mouse the corresponding instrument will be activated. The velocity can be controlled by using the scroll-wheel. The current value can be seen at the bottom left of the window. While the mouse is hovering the mapped area it will light up and the name of the instrument will be shown next to the velocity at the bottom of the window.

{{ :changelog:clicky-kit.png?600 |}}

In order to support this feature in new drumkits an image tag must be present in the metadata section.
If only the ''src'' attribute is specified the "Drumkit" tab will simply show that image but not be clickable.
In order to add click-map data a second image must be constructed with the same dimensions as the source image with clickable areas coloured with a unique colour of the authors choice.
Each colour can then be specified in the ''clickmap'' tags as RGB hex codes alongside with the name of the instrument it must trigger.
This approach makes it possible to trigger on virtually anything in the image.
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  <metadata>
    ...
    <image src="DrumkitImage.png" map="DrumkitImageClickMap.png">
      <clickmap colour="ff08a2" instrument="China"/>
      <clickmap colour="a218d7" instrument="HihatClosed"/>
    </image>
  </metadata>
  ...
</drumkit>
</code>

This png files referred from the xml could look something like this:

''DrumkitImage.png''
{{ :changelog:crocellkit01.png?direct&250 |}}

''DrumkitImageClickMap.png''
{{ :changelog:crocellkit01_map.png?direct&250 |}} 

====Midnam Support in LV2====
The LV2 standard has a midnam extension which enables the plugins to (among other things) give names to the midi-notes. This make it possible for DrumGizmo to tell the LV2 host the names of the instruments in the midimap file which the host then can show on the piano-roll or inside the midi-editor. The example below is taken from Ardour.

This particular feature was conceived by great help from Robin Gareus.

{{ :changelog:midnam.png?600 |}}

====Directed Choke Functionality=====
This feature expands on the instrument group feature from the previous versions. Choking is the option for one instrument to perform a (controlled) mute another when activated.
The old groups were simply used to tie together instruments in the drumkit file so that when one instrument were being played in the group all others would be muted.
Consider for example the three instruments "Hihat Open", "Hihat Closed" and "Hihat Foot" - putting all of these into the "Hihat" group would then make "Hihat Closed" stop any playing "Hihat Open" samples thereby simulating a real hihat.
This feature proved to be rather limited since all instruments in the group would always be affected and we therefore decided to introduce "directed chokes" to give more control over which instruments are being affected and when.

Directed chokes adds a list of "choke instruments" to each instrument node that will be choked when the instrument is being played but not the other way around.

Example; Consider again the three instruments "Hihat Open", "Hihat Half Open" and "Hihat Foot".
We can then have "Hihat Foot" choke "Hihat Open" and "Hihat Half Open" without "Hihat Open" and "Hihat Half Open" affecting each other as they would have if they were simply put into a group.
Futhermore it is possible to set the ''choketime'' on a pr. choke basis. Leaving the ''choketime'' attribute out will use the default choke-time which is 68ms.
The XML for the choke section of the above example could look something like this:
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  ...
  <instruments>
    ...
    <instrument name="Hihat Open" file="HihatOpen/HihatOpen.xml">
      ...
    </instrument>
    <instrument name="Hihat Half Open" file="HihatHalfOpen/HihatHalfOpen.xml">
      ...
    </instrument>
    <instrument name="Hihat Foot" file="HihatFoot/HihatFoot.xml">
      <chokes>
        <!-- override the default 68ms with 100ms -->
        <choke instrument="Hihat Half Open" choketime="100"/>
        <choke instrument="Hihat Open"/>
      </chokes>
      ...
    </instrument>
    ...
  </instruments>
</drumkit>
</code>

=====Drumkit Metadata=====
It is now possible to add all sorts of meta information to the drumkits. Most of it is not yet used by the engine but it will be in the coming releases.
Expect for example to see the logo in the UI and the drumkit URL as a direct link in the UI.
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  <metadata>
    <version>1.2.3</version>
    <title>Test Kit</title>
    <logo src="LogoFile.png"/>
    <description>This is the description of the drumkit</description>
    <license>Creative Commons</license>
    <notes>These are general notes concerning anything of relevance for this particular version of the drumkit</notes>
    <author>Author of the drumkit</author>
    <email>author@email.org</email>
    <website>http://www.drumgizmo.org</website>
    <image src="DrumkitImage.png" map="DrumkitImageClickMap.png">
      <clickmap colour="ff08a2" instrument="China"/>
      <clickmap colour="a218d7" instrument="HihatClosed"/>
    </image>
  </metadata>
  <channels>
   <channel name="AmbL">
     <title>Ambience left</title>
   </channel>
   ...
  </channels>
  ...
</drumkit>
</code>

=====Experimental Cocoa UI support for MacOSX=====
Well; an image says more than a 1000 words ;)

{{ :changelog:cocoa_ui_support.png?600 |}}

Because this feature is still highly experimental we will not yet supply binary .dmg files for OSX.
Users who would like to give try DrumGizmo on OSX will therefore have to compile the VST themselves.

Detailed instructions on how to do this can be found at [[dev:macosx_building_howto|our development pages]]. Any questions can as usual be directed to our [[https://kiwiirc.com/client/irc.freenode.net:+/#drumgizmo|irc channel]] or our linuxmusicians.com [[https://linuxmusicians.com/viewforum.php?f=55|subforum]].

=====Other Minor Changes and Bugfixes=====
====Set Default Path====
A new button, "Set default path" ,has been added to the filebrowser.
Clicking this button will store the path of the current directory in the global plugin settings and new instances of the plugin will then open the file browser at this location. This should make it much faster to browse to a drumkit if for example all drumkits are stored in a common drumkit folder.

{{ :changelog:set_as_default.png?400 |}}

====Compile-time Configure Number of Outputs====
When compiling drumgizmo from sources it is now possible to control how many outputs are exposed by the engine using an argument to the configure step:
<code>
  --enable-custom-channel-count=count
                          Compile with specified number of output channels
                          [default=16]
</code>
This will make it possible to make customized versions of the plugin exposing for example more than 16 channels. The default remains 16.

====dgvalidator - drumkit validation tool====
A new tool, dgvalidator, has been added for performing xml, semantic and audiofile validation of a drumkit from the commandline.

Simply run it like this:
<code>
dgvalidator MyDrumkit.xml
</code>
It will report any errors found to the terminal and return non-zero value (''$?'' in bash) if errors were found.

Expect many more checks as well as more elaborate console error reporting to be added to this tool in the future.

====Fix Cache Limit Storage====
In previous versions when setting the disk-stream cache limit above 2GB it would erroneously be set to unlimited when reloading the session.
This bug has now been fixed.