Fixed: Tuplet rework

[ahankinson]

I may have gotten some things wrong, so please review closely.

As part of this I have also had the Verovio rendering code re-worked. Primarily this was done to support the 'annotated tuplet' example provided, but it is also more flexible and resilient to encoding errors.

Fixes #123

[github-actions]

PR Preview Action v1.6.3
🚀 View preview at https://rism-digital.github.io/pae-code-spec/pr-preview/pr-195/
Built to branch gh-pages at 2026-05-28 08:48 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[ahankinson]

I have tried to resolve all the comments.

• There is (at least to me) mental model of a tuplet that has "metadata" and "data". Tuplet metadata is set off from the data by the use of semicolons.
• An optional "musical duration" segment can be added at the start of a tuplet. This effectively moves an encoding like 4(... to (4;...). It seemed better to place that at the start, since it meant we could keep the "label" side of the metadata (the end) from needing to use any punctuation to separate out the concerns.
• Having the musical duration inside of the parentheses clears the way for implied durations and duration patterns, since 8884(... becomes 888(4;... and resolves the confusion that we had with the previous encoding method.
• The label side of the tuplet is separated from the body also with a semicolon. (CCC;3). This can take a simple number or a ratio, e.g., (CCC;3:2). This is largely unchanged.
• I used the term "musical duration" to distinguish it from the "written duration" of the notes. In a tuplet, an eighth note is not actually an eighth note, it's just written with that shape. I found terminology like "full" or "total" to be ambiguous. (A full measure? A full note?). I tried to expand this concept in a note.

I hope this keeps everyone happy (including me.)

[lpugin]

This looks good, thanks!

One general comment for the use of "musical duration", which I find confusing. Since we are maintaining the value mostly for backward compatibility, I would suggest sticking with "total duration" used in v1, which I think was not really a problem. Another option could be "sounding duration", but I would not oppose "musical" with "written".

FWIW, MuseScore uses the term "entire duration [of the tuplet group]".

[ahankinson]

“Full” or “total” isn’t really a definition though, it’s a description. Full in reference to what? The measure? The beat? What is it the total of?

“Musical” and “written” is trying to evoke the same ideas as “logical” and “visual” (since that’s basically what is happening here) without also needing to bring in all of that baggage. The “logical” duration is 4, but the “written” durations are three eighth notes.

[lpugin]

For me

A duration MAY immediately follow the opening parenthesis (. This value encodes the total duration of the tuplet group.

is pretty much the wording we had in v1 and would be perfectly clear. Why would it be in reference to the measure? or to the beat?

"logical" would be better than "musical" IMO. Or "effective duration"? Or "actual duration"? I leave it to @BaMikusi and @jenniferward to decide.

[lpugin]

Maybe

This value encodes the duration the tuplet group occupies.

?

[BaMikusi]

For me, too, the adjective "musical" seemed problematic at first sight, an that feeling of unease didn't go away after repeated readings, either. I guess partly because, if "musical" appears as the opposite of "written," my mind starts to wonder in the realm of performance details, like a rubato -- thus, in the comparison the "written" side will seem the solid and measurable one, and the "musical" the unstable and fluctuating factor. With that in mind, any of the alternatives suggested by Laurent would seem a better choice to me -- so it should arguably be the one that Andrew can best live with.

[ahankinson]

I don’t have much time to work on this in the next few days, but I have specifically avoided “full” or “total” because there is ambiguity for what it is the “full”’or “total” of. Measure? Beat? If it’s an eighth note tuplet in 4/4, in what sense is that “full” or “total”?

[BaMikusi]

[...] there is ambiguity for what it is the “full”’or “total” of. Measure? Beat? If it’s an eighth note tuplet in 4/4, in what sense is that “full” or “total”?

I don't see either, why anyone would want to think of a meaasure here. It's the total value of the tuplet, i.e., of the stuff that's written in the parentheses after this duration reference.

[ahankinson]

It's the total value of the tuplet, i.e., of the stuff that's written in the parentheses after this duration reference

it isn’t, though. If you add up the durations inside the tuplet you would get a different number than the number you provide at the beginning.

[BaMikusi]

Ah, so you would add it up so literally -- that indeed won't work. Then you might indeed want to have a refence point outside of the code itself and speak of the tuplet's, say, "sounding" duration.

[ahankinson]

Exactly. “Full” or “total” implies some form of addition, but there is nothing to add together to make the first duration number.

[lpugin]

It seems to me we all agree that this value is not needed since we agreed to make it optional. We keep it for backward compatibility for projects that have used it in the PAE encoding - which is not the case of (at least) most RISM incipits. I can say more why I think this is a limiting approach to tuplet encoding if needed.

If we want to remove "full" duration that we had in v1, then we can do so, but we need something else than "musical" because - as we can see from this discussion - that creates confusion.

I would suggest simply saying that "this value encodes the duration the tuplet group occupies.", which does not have "full" nor "total" but also avoid qualifying what this duration is - it seems to me we do not need to.

If that is not good, then when can use "logical duration", "effective duration", "sounding duration", "realised duration", or something along these lines, which I all find less good than just "occupied", but that would be OK for me.

[lpugin]

PS Since we already have a definition for "Written pitch" vs "Sounding pitch", it seems that a good compromise might be "sounding duration". We could say "this value encodes the corresponding sounding duration of the tuplet group."

Any thoughts?

[ahankinson]

That’s ok with me, but we should add the duration entries to the terminology sections, and link to them in the text.

[BaMikusi]

As is evident from my ealier comment

(...) Then you might indeed want to have a refence point outside of the code itself and speak of the tuplet's, say, "sounding" duration.

I am also happy with "sounding duration."

Amen.

[lpugin]

I think the first sentence should be removed, and the second one attached to the previous paragraph.

[lpugin]

That is actually confusing because the two tuplets are the same. So if the varying duration is about the varying duration of the notes inside (which I think it is), we should have only one tuplet.

[lpugin]

PS I was expecting something like (4;'4D8E)(2;'4D8E)

[lpugin]