======Directed Choke Functionality Design Document======

Directed choke is the possibility to have one instrument choke another when triggered but not the other way.

The current instrument groups can be considered as a by-directional choke between all instruments in the group.

Consider the instrument:
  * Ride
  * RideBell
  * RideGrab

Ride and RideBell should not choke each other but RideGrab should choke both Ride and RideBell.

The implementation in the engine is rather straight forward so this is not described here.

IRC discussions with HJ about this feature:
  * [[https://www.drumgizmo.org/irc-logs/drumgizmo.log.2018_08_05|irc log 10:48]]
  * [[https://www.drumgizmo.org/irc-logs/drumgizmo.log.2018_08_31|irc log 19:57]]
  * [[https://www.drumgizmo.org/irc-logs/drumgizmo.log.2018_09_05|irc log 17:51]]

=====XML proposal=====
Like the current instrument group feature the directed choke should be expressed in the drumkit file:

====Proposal 1====
Comma separated list of instruments. This requires that instrument names in themselves do not contain command which currently is not a requirement, so this option may break backwards compatibility.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  ...
  <instruments>
    <instrument name="Ride" ...>
    </instrument>
    <instrument name="RideBell" ...>
    </instrument>
    <instrument name="RideGrab" ... chokes="Ride,RideBell">
    </instrument>
    ...
  </instruments>
</drumkit>
</code>

====Proposal 2====
Adding the choke attribute multiple times to create a list. This approach is not technically a problem (our parser supports it) but having multiple identical attributes is not normally present in XML so it may be confusing to some users.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  ...
  <instruments>
    <instrument name="Ride" ...>
    </instrument>
    <instrument name="RideBell" ...>
    </instrument>
    <instrument name="RideGrab" ... chokes="Ride" chokes="RideBell">
    </instrument>
    ...
  </instruments>
</drumkit>
</code>

====Proposal 3====
Add a chokelist xml tag containing the list. This approach is more like what would be expected in XML but (in my opinion) looks rather ugly. This approach may however make it possible to add more control to the choking, like for example setting the ramp-down time or curve pr. choke which may be useful.

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<drumkit ...>
  ...
  <instruments>
    <instrument name="Ride" ...>
    </instrument>
    <instrument name="RideBell" ...>
    </instrument>
    <instrument name="RideGrab" ...>
      <chokes>
        <choke instrument="Ride"/>
        <choke instrument="RideBell" choketime="150" chokecurve="linear"/>
      </chokes>
    </instrument>
    ...
  </instruments>
</drumkit>
</code>