Re: articulate.ly: update documentation, add support for portato (issue 260040043 by address@hidden)

[ht . lilypond . development]

On 2015/08/09 13:35:35, Dan Eble wrote:
> I'm not sure I understand you properly; is the entire motivation for
this
> change?  It sounds like "Because there can be two ways to do things,
there
> should be."

> My response is to question whether it is worth maintaining two ways.
Does
> articulate.ly somehow disable the built-in articulations? If so,
shouldn't the
> goal be to make them work together rather than to enlarge them
separately?

> Regards,
> Dan

I certainly wouldn't be opposed to having only a single, customizable,
and fully documented mechanism for altering LilyPond's MIDI output for
performance purposes, however unifying the existing mechanisms is just
too big a task for me to handle as I've not participated in the design
or implementation of either of the existing mechanisms.

Perhaps because the project has lacked an experienced core developer
with good enough knowledge about the MIDI code to be able to "manage"
the contributions to the code by non-core developers each "scratching
their own itch" (myself included...) to keep the emerging design
consistent, the current state of affairs is that there in fact exist
two partially overlapping mechanisms for altering MIDI output in the
current development version, but, feature-wise, neither of them can be
used as a direct replacement for the other because both of them have
also unique features.

The purpose of this change is to actually bring the feature sets again
(a tiny bit) closer together.

Let me summarize the feature history (which started before my own
introduction to LilyPond, so I may be wrong on some details about
the early history) as I've experienced it from a user's point of view:

 * Up to and including LilyPond 2.12, the official LilyPond releases
   did not include any mechanisms for altering the basic MIDI output
   for performance purposes.  Apart from the fact that all
   articulations were simply ignored for MIDI output, the note output
   was otherwise close to "what you write is what you get", that is,
   the durations of notes were kept intact, and no implicit
   velocity (dynamic) changes were applied to any notes on the basis
   of single note articulations, unless such changes were explicitly
   written in the input file.

 * The articulate script originally appeared as a separate project [1],
   [2] that was hosted at <http://www.nicta.com.au/articulate/>.  This
   script introduced the \articulate function, which alters its input
   music expression by "shortening" the notes in the expression using
   information about slurs and the articulations (missing from, or)
   attached to the notes, by "unfolding" trills, pralls, and mordents,
   and translating certain text elements attached to notes
   automatically to tempo changes.

 * The articulate.ly script was subsequently included in the official
   source tree [3], and released as part of LilyPond first in LilyPond
   2.14.  The script has since been mentioned also in the Notation
   Reference (in NR 2.14, it appeared as the "The Articulate script"
   subsection at the end of the section on MIDI).

 * To my understanding, the articulate.ly script was still the only
   readily available option to improve the handling of articulations
   in MIDI output even in the latest stable 2.18 release.

 * In November 2013, a new patch appeared to "Support articulations,
   slurs and breaths in MIDI" [4] without the need to use the
   articulate.ly script.  This patch changed the internal LilyPond
   implementation to handle articulations attached to notes (with
   some added features, such as breath marks) in MIDI "natively"
   without a need to include the articulate.ly script.  Apparently
   the questions about the relation of this new functionality and
   the functionality provided by the articulate.ly script, and
   whether LilyPond should keep supporting both of these, were
   probably not considered at the time.  Quoting the developer of
   the patch [5],

     "This change doesn't interfere with articulate.ly, since
      the [articulate.ly] script's output doesn't contain any
      articulations [which would be then processed again by
      the new functionality]."

 * As a result, the current development version now includes two
   different implementations to modify the MIDI output, each of them
   supporting features not available (in the exact same way, or at
   all) in the other implementation.  (See the review discussion [6]
   to get a sample of the questions which arise because of the
   different implementations when it comes to documenting the
   features supported by LilyPond in MIDI.)

   Currently, the NR documentation on MIDI output lacks detail
   about how the new functionality added in issue #3664 will
   change the MIDI output to handle articulations, and does not
   include documentation or examples on how this behavior can be
   customized.  The item which mentions the feature change about
   handling articulations in the v2.19 Changes document refers to
   added properties which don't actually exist (at least not by the
   names given in that document), and the examples (that is, changes
   to ly/script-init.ly) referred to in the Changes item look like
   Scheme definitions, the semantics of which doesn't seem to be
   described any user-level document.

As a matter of fact, having initially learned the "what you write is
what you get, excluding all articulations" default MIDI output
behavior that LilyPond still had in v2.18, I didn't find the new
behavior that is now enabled by default a welcome change when I
originally noticed it (sadly, it was already too late for me to take
part in the review discussion), but it's of course possible that new
users to LilyPond will prefer it.

I've actually come to like the fact that, when using the articulate
script, the decision of altering the MIDI output for a piece of
music must be made explicitly (by applying the \articulate function
to the music) - I'd probably have a more positive opinion about the
new default behavior if its default parameters had been chosen
conservatively so that they wouldn't by default affect the MIDI
output, requiring explicit (and intentional) customization of the
parameters to "enable" changing the MIDI output.  This is because
how articulations "should" be rendered by default is probably
largely a matter of opinion - for example, does the "staccato"
articulation necessarily imply also a small accent (added velocity)
on the articulated note?

In my opinion, the most significant differences between the features
provided by the articulate.ly script and the new default behavior are
as follows:

 * The articulate.ly script by default shortens also all notes without
   any articulation.  I'm not sure whether this is possible to do with
   the new native behavior.

 * Due to the shortening of notes without any articulation, the
   articulate.ly script also renders slurred notes differently from
   non-slurred ones (by _not_ shortening slurred notes, so that they
   get their entire length as written).  This is not to say that this
   is the "proper" way to handle slurs, but just that as a result,
   slurred notes will be rendered differently from non-slurred ones...

 * In addition to shortening notes with articulations, the articulate.ly
   script also expands trills, pralls, and mordents, and modifies
   the interpretation of appoggiaturas and grace notes.  The
   script also translates certain text strings attached to notes
   automatically to tempo changes.  (This list is just a statement
   about what the script supports in comparison with the new native
   behavior, and not about whether I find these features
   particularly important.)

 * articulate.ly does NOT support accents or breath marks.

 * articulate.ly does NOT make any velocity (volume) changes to
   articulated notes.

 * There are explanations of the parameters supported by the
   articulate.ly script (and a description on how the script works)
   in the script itself.  The parameters of the new native
   implementation are currently not as well documented, which I
   think is the main reason why I'd personally still recommend
   trying articulate.ly for a user interested in trying to
   "improve" the MIDI output automatically.


All that said, my patch was intended for other users like me which
still prefer to use articulate.ly :-) -- it's just the case that the
articulate script didn't (historically) used to handle the "portato"
articulation, and it was simple to make the script support it (to
remove an unnecessary difference in the set of articulations
supported in MIDI with and without articulate.ly).

Regards,
Heikki


[1] Announcement of the articulate script on the lilypond-user mailing
list:

<http://lists.gnu.org/archive/html/lilypond-user/2008-06/msg00403.html>
[2] The articulate script source code release announcement:

<http://lists.gnu.org/archive/html/lilypond-user/2008-08/msg00108.html>
[3] Rietveld issue announcement for handling the inclusion of the
    articulate.ly script in the official releases:

<https://lists.gnu.org/archive/html/lilypond-devel/2011-04/msg00065.html>
[4] Google Code issue for supporting articulations natively in LilyPond:
    <https://code.google.com/p/lilypond/issues/detail?id=3664>
[5] Patch announcement for issue #3664
    <https://codereview.appspot.com/26470047#msg1>
[6] "Doc: NR section 3.5.x MIDI file creation tidy up" (Rietveld review
    discussion), <https://codereview.appspot.com/120480043/#ps240001>


https://codereview.appspot.com/260040043/