+@node Controlling MIDI dynamics
+@subsection Controlling MIDI dynamics
+
+MIDI dynamics are implemented by the Dynamic_performer which lives
+by default in the Voice context. It is possible to control the
+overall MIDI volume, the relative volume of dynamic markings and
+the relative volume of different instruments.
+
+@unnumberedsubsubsec Dynamic marks
+
+Dynamic marks are translated to a fixed fraction of the available
+MIDI volume range. The default fractions range from 0.25 for
+@notation{ppppp} to 0.95 for @notation{fffff}. The set of dynamic
+marks and the associated fractions can be seen in
+@file{../scm/midi.scm}, see @rlearning{Other sources of information}.
+This set of fractions may be changed or extended by providing a
+function which takes a dynamic mark as its argument and returns the
+required fraction, and setting
+@code{Score.dynamicAbsoluteVolumeFunction} to this function.
+
+For example, if a @notation{rinforzando} dynamic marking,
+@code{\rfz}, is required, this will not by default
+have any effect on the MIDI volume, as this dynamic marking is not
+included in the default set. Similarly, if a new dynamic marking
+has been defined with @code{make-dynamic-script} that too will not
+be included in the default set. The following example shows how the
+MIDI volume for such dynamic markings might be added. The Scheme
+function sets the fraction to 0.9 if a dynamic mark of rfz is
+found, or calls the default function otherwise.
+
+@lilypond[verbatim,quote]
+#(define (myDynamics dynamic)
+ (if (equal? dynamic "rfz")
+ 0.9
+ (default-dynamic-absolute-volume dynamic)))
+
+\score {
+ \new Staff {
+ \set Staff.midiInstrument = "cello"
+ \set Score.dynamicAbsoluteVolumeFunction = #myDynamics
+ \new Voice {
+ \relative c'' {
+ a\pp b c-\rfz
+ }
+ }
+ }
+ \layout {}
+ \midi {}
+}
+@end lilypond
+
+Alternatively, if the whole table of fractions needs to be
+redefined, it would be better to use the
+@notation{default-dynamic-absolute-volume} procedure in
+@file{../scm/midi.scm} and the associated table as a model.
+The final example in this section shows how this might be done.
+
+@unnumberedsubsubsec Overall MIDI volume
+
+The minimum and maximum overall volume of MIDI dynamic markings is
+controlled by setting the properties @code{midiMinimumVolume} and
+@code{midiMaximumVolume} at the @code{Score} level. These
+properties have an effect only on dynamic marks, so if they
+are to apply from the start of the score a dynamic mark must be
+placed there. The fraction corresponding to each dynamic mark is
+modified with this formula
+
+@example
+midiMinimumVolume + (midiMaximumVolume - midiMinimumVolume) * fraction
+@end example
+
+In the following example the dynamic range of the overall MIDI
+volume is limited to the range 0.2 - 0.5.
+
+@lilypond[verbatim,quote]
+\score {
+ <<
+ \new Staff {
+ \key g \major
+ \time 2/2
+ \set Staff.midiInstrument = #"flute"
+ \new Voice \relative c''' {
+ r2 g\mp g fis ~
+ fis4 g8 fis e2 ~
+ e4 d8 cis d2
+ }
+ }
+ \new Staff {
+ \key g \major
+ \set Staff.midiInstrument = #"clarinet"
+ \new Voice \relative c'' {
+ b1\p a2. b8 a
+ g2. fis8 e
+ fis2 r
+ }
+ }
+ >>
+ \layout { }
+ \midi {
+ \context {
+ \Score
+ tempoWholesPerMinute = #(ly:make-moment 72 2)
+ midiMinimumVolume = #0.2
+ midiMaximumVolume = #0.5
+ }
+ }
+}
+@end lilypond