Re: Doc: NR section 3.5.x MIDI file creation tidy up (issue 120480043 by address@hidden)

[ht . lilypond . development]

Some comments based on looking through the articulate.ly script code
(after having made similar observations about the accuracy of the
supported/unsupported lists as Trevor Daniels did).

Since the default behavior of articulations is about to change in the
next release (issue 3664), I'm worried that this could make it even more
difficult to describe the behavior of articulate.ly accurately, and
compare its features with the new default behavior.

(My preferred choice would in this case to have in the NR enough details
about both the default behavior and the articulate.ly script's features
so that the differences could be understood without going to the source
code.  I attempt to mention some of the details which I consider
relevant in my comments.)



https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely
File Documentation/notation/input.itely (left):

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#oldcode2890
Documentation/notation/input.itely:2890: @end itemize
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> This information seems to have been lost or erroneously moved into the
section
> on articulate.ly.

Perhaps the information about what is supported or unsupported in MIDI
with or without the articulate.ly script could be collected from lists
into a table?

(This is possibly not a good suggestion, as I don't really see a way to
describe the behavior and differences more accurately than in a list
without using a lot of footnotes, but maybe this idea could be developed
further...)

          without \articulate   with \articulate
Pitches        x                      x
Microtones     x                      x
...
Staccato       x (1) (2) (3)          x (2)
Staccatissimo  x (1) (2) (3)          x (2)
Tenuto                                x (2)
Portato        x (2) (3)
Accent         x (1) (3)
Marcato        x (1) (3)
Mordent                               x (4)
Prall                                 x (4)
Trill                                 x (4)
Turn                                  x (4)
...
(1) Volume of articulated notes will be altered.
(2) Duration of articulated notes will be altered.
(3) Only applicable to single notes, not chords.
(4) The pitches cannot be customized.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#oldcode2899
Documentation/notation/input.itely:2899: @end itemize
On 2014/10/03 21:23:30, Trevor Daniels wrote:
> Note that these are the only entities modified by articulate.ly.

I agree.  Looking through the articulate.ly script code, the full list
of articulations and ornaments the script appears to support is
 * staccato,
 * staccatissimo,
 * tenuto,
 * mordent,
 * prall,
 * trill and
 * turn.

Notes with staccato, staccatissimo, or tenuto articulation, and notes
without any articulation, are shortened by customizable factors, unless
the notes occur within slurs or phrasing slurs; mordents, pralls, trills
and turns are expanded. These expansions do not support customizing the
pitches to be used, however, so the expansion may in some cases produce
incorrect results; see, for example,
<http://lists.gnu.org/archive/html/lilypond-user/2014-05/msg00399.html>.
No changes are made in MIDI volume.

Tempo changes are implemented by matching text scripts attached to notes
against a hard-coded dictionary of strings ("rit.", "accel.", or "tempo
I", for example).

----

Since 2.18, LilyPond has gained support also for handling some
articulations without \articulate (issue 3664): accent, marcato,
staccato, staccatissimo and portato, together with breath marks (which
also shorten notes).

The new default behavior of the articulations is also a bit different
from how the \articulate script would handle them as, without
\articulate, both the length *and* the MIDI volume of the notes may be
altered.

The new behavior is (to my understanding) nevertheless disabled in music
processed through \articulate - based on the code review discussion on
issue 3664, this appears to be intentional, to not interfere with the
old behavior of \articulate.  However, this means that with the new
default behavior of the articulations, using \articulate on a piece of
music may remove some volume effects.  Also, unlike the \articulate
script, which appears to be able to apply articulations (such as
staccato or staccatissimo) to chords as well, the new default behavior
appears to work only for articulations attached to single notes.

The details about the new, more complex default behavior of
articulations (and how to customize it) are currently described only in
the Changes document.  I believe this information should be available in
some form also in the NR as with further releases, it will become much
more difficult to find.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#oldcode2991
Documentation/notation/input.itely:2991: default in the Voice context.
It is possible to control the overall
This removed sentence reminds me of an issue which, in my opinion,
should deserve a mention at least as a "Known issue" in the NR since I
think the fact that every Voice has its own separate Dynamic_performer
by default can be a source of surprising behavior (especially with
temporary voices) where the MIDI volume does not appear to match what
could be expected by looking at the typeset output.

(This behavior was one of the main reasons that originally led me to
study LilyPond's implementation to understand why the MIDI output volume
didn't match the expectations.  Users still seem to be hit by this issue
every now and then without necessarily being aware of it, see, for
example,
<http://lists.gnu.org/archive/html/lilypond-user/2014-05/msg00460.html>.)

Specifically, since
 (1) the introduction of a new Voice also initializes a new
     Dynamic_performer for MIDI output (which initially has a
     "default" volume), and
 (2) it's the responsibility of the Dynamic_performer to assign a volume
     to each MIDI note,
it follows that the MIDI volume of the notes in the new Voice context
will in effect get "reset" to the new Dynamic_performer's "default"
volume level regardless of any "previous" MIDI volume, unless there's an
explicit absolute dynamic event at the start of the new Voice.

Example:

\score {
  \new Staff {
    \new Voice {
      % ... a long monophonic passage
      c'1\ppppp
      <<
        \new Voice {
          c''2\> % starts at the default velocity, not \ppppp
          g'2\!
        }
        \new Voice {
          c'1    % this note also gets the default velocity
        }
      >>
      % ... continue with a single Voice
    }
  }
  \layout { }
  \midi { }
}

I'd suggest adding the following entry in the "Known issues" list at the
end of the "Setting MIDI volume" subsection:

  Known issue: MIDI dynamics are implemented by the Dynamic_performer,
  which lives by default in the Voice context.  This means that every
  new Voice context, such as one created for a temporary polyphonic
  passage (NR 1.5.2), will have an independent Dynamic_performer
  initialized with a "default" volume level that will be used for the
  notes in the new voice.  If it is inappropriate to use the default
  volume level for the new voice, make sure to start the voice with an
  explicit dynamic marking, or move the Dynamic_performer from the
  Voice context to the higher-level Staff context.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely
File Documentation/notation/input.itely (right):

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#newcode2898
Documentation/notation/input.itely:2898: @item Tempo changes entered as
annotations without tempo markings.
"tempo markings" should possibly be "metronome marks" (NR 1.2.3).

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#newcode2901
Documentation/notation/input.itely:2901: @item Tremolos entered with
@address@hidden:address@hidden
It appears that articulate.ly actually supports also these tremolos (by
unfolding them) since
<http://git.savannah.gnu.org/gitweb/?p=lilypond.git;a=commit;h=51146a320837b3d2f673c8ce0493e33038babc18>.

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#newcode2912
Documentation/notation/input.itely:2912: of dynamic markings and the
relative volume of different instruments.
I'd consider moving text from the end of this section to expand the
introduction:

   Dynamic marks translate automatically into volume levels in the
available
   MIDI volume range whereas crescendi and decrescendi vary the volume
   linearly between their two extremes.  It is possible to control the
relative
   volume of dynamic markings, and the overall volume levels of
different
   instruments.

Also, if the goal is to give a complete list about what LilyPond does to
MIDI volume automatically, the new default behavior of some
articulations (issue 3664) is relevant also here:

   Also, the articulations \accent, \marcato, \staccatissimo and
\staccato
   increase the MIDI volume of the note to which they are attached (in
music
   not processed using the articulate.ly script).

https://codereview.appspot.com/120480043/diff/180001/Documentation/notation/input.itely#newcode3108
Documentation/notation/input.itely:3108: @rinternals{Dynamic_performer}.
This paragraph can be removed if the information is moved to the
beginning of the subsection about dynamics.

https://codereview.appspot.com/120480043/