Library: vsa-templates per genre × toon¶

Werkmap per formule. Gedeelde afspraken staan hier; per combinatie staat alles onder <genre>-toon-<n>/.

Mapstructuur¶

library/
  README.md                 ← dit bestand (geldt voor alle formules)
  tropaar-toon-4/
    template.yaml           ← canonieke formule
    template.mscz           ← formuleblad MuseScore (één bestand, geen .mscx)
    template.mxl            ← formule MusicXML (delen)
    README.md               ← kort: status, bron, pijplijn
    examples/corpus/        ← .vsa + afgeleide .mscz/.mxl
    notes/                  ← corpus, mappinglessen, besluiten
  …

Invalid schema-cases blijven in examples/invalid/ (geen formule-werkmap).

Gedeelde afspraken¶

Onderwerp	Afspraak
Architectuur	VSA→template-instance: S uit VSA, A/T/B uit template (synchroon)
MusicXML-balken	2 partijen: P1 `S/A` (G), P2 `T/B` (F); per partij voice1=S of T, voice2=A of B; `backup`
Maatsoort	bij voorkeur `senza-misura`; 4/4 tolereren in MuseScore-exports
Optionele noten	YAML `optional: true` ↔ MusicXML notehead parentheses
Pitches	PDF/PNG = featurebron; menselijke MuseScore-edit → YAML
Renderer	`python scripts/render_vsa_template_musicxml.py --all` (hulp, niet bron)
Validatie	`vsa template validate <pad>`

Formuleblad vs instance¶

Artefact	Rol	In git?	Regenereren
`template.yaml`	formule-bron	ja	handmatig
`template.mscz`	formule MuseScore	ja (afgeleid)	`render_tropaar_toon4_corpus.py --template`
`template.mxl`	formule MusicXML	ja (afgeleid)	idem / `render_vsa_template_musicxml.py --all`
`template.pdf`	formule print	nee	`--template --pdf`
corpus `.vsa`	zangstuk-bron	ja	curated
corpus `.mscz` / `.mxl`	instance	ja (afgeleid)	`render_tropaar_toon4_corpus.py`
corpus `*.pdf`	print	nee	`--pdf` / `--pdf-only`

Formuleblad: ankers, frase-ids, cycle-frames, ||O|| zonder VSA-lyrics. Instance: VSA-lyrics, recite-collapse, geen formulelabels; titel = frontmatter-title (anders bestandsstem). Coria-MXL = instance zonder collapse. Details: rendering-pitfalls.md.

Geen template-from-yaml.mscx/.mscz meer (één formule-MSCZ volstaat). MuseScore-rommel (.mscbackup/, Thumbnails/, losse META-INF/, …) niet committen.

MuseScore-authoring (conventies)¶

Deze symbolen zijn onze semantiek; MuseScore zelf kent geen “recite”.

In MuseScore	Betekenis in template
Tekst `1`, `2`, `3`, … of `laatste` (cirkel, rechthoek, of zonder)	frase-id (formulelabel)
Brevis-kop (`\| \| O \| \|`), stemloos, halfnoot (2 tellen)	reciteertoon (`role: recite`)
Notehead met haakjes	`optional: true`
Staff text `e. st.` / `l. st.` / `vl. st.` + pijl eronder naar de noot	frase-anker (formulelabel)
Staff text `\\|\\|: 1, 2 :\\|\\| laatste` of VBox onderaan	cycle-notatie (YAML `cycle`/`final`)
Duur quarter / half / whole	ELM `~` / `_` / `__`

YAML-ankers zijn zonder spaties (l.st.); op het blad mét spaties (l. st.). De pijl is hulpgrafiek, geen tweede formulelabel.

Formuleblad (`.mscz`)¶

Het gegenereerde template.mscz dient voor twee dingen:

Controle — YAML en MuseScore in de pas houden terwijl de formule op orde komt.
Koorprintje — dezelfde partituur als printbare bron (PDF lokaal via --template --pdf).

Die tweede rol wint bij layoutkeuzes. Extra G-sleutels moeten weg. Extra witruimte van verborgen rusten is ongewenst.

Geen measure-padding. De maatlengte is de som van de echte nootduren.

YAML → MuseScore + MXL (tropaar toon 4):

cd /d C:\Git\orthodox-ronl\VSA-tooling
python scripts\render_tropaar_toon4_corpus.py --template
python scripts\render_tropaar_toon4_corpus.py --template --pdf

Overschrijf nooit de gebruikersoriginelen (Template - Tropaar (Toon 4).mscz / .musicxml / .mxl).

Sleutels¶

Geen <Clef> in maat 1 (dat tekende een tweede sleutel op het blad). SA: G-sleutel via instrumentdefault. TB: bas-sleutel via <defaultConcertClef>F</defaultConcertClef> en <defaultTransposingClef>F</defaultTransposingClef> op de Part-Staff, plus <clef>F</clef> in het instrument. MuseScore 4 leest de zichtbare sleutel uit die staff-defaults; alleen Instrument-<clef> gaf nog een G-sleutel op TB. Verborgen TimeSig 4/4 mag blijven. KeySig op beide balken is correct.

Frames na de laatste maat¶

Vanuit lezersperspectief, na de laatste maat (cycle-form):

lege horizontale frame (HBox, spacer) — schuift de cycle-tekst ongeveer naar het midden (MuseScore centreert HBox-tekst niet betrouwbaar);
horizontale frame met cycle-tekst (||: 1, 2 :|| laatste).

Als de laatste template-frase niet alleen op een systeem staat, of te breed is (meer dan CYCLE_HBOX_MAX_LAST_QUARTERS kwartnoten), valt de renderer terug op één verticale frame (VBox) onder de partituur.

Formulelabels (frase-id en frase-anker)¶

Alles wat een cijfer is of precies laatste, telt als frase-id — ongeacht enclosure (cirkel, vierkant, geen). Rehearsal mark of staff text: beide oké. De vorm van het kader is geen extra id.

Frase-ids en anker-afkortingen samen: formulelabels. In het .mscx staan ze op één vaste hoogte (y="-4.5", boven de noten, autoplace uit, DejaVu Sans Condensed 12pt). Bij een frase-anker hoort extra een pijl op y="-1.3" (onder het formulelabel); die pijl is geen tweede label. In de bibliotheek wijst geen anker naar een recite-event (anker en recite zijn altijd aparte events).

Cycle-regel op het blad¶

Op de PDF staat vaak ||: 1, 2 :|| laatste. Open template.mscz: daar staat de regel in een HBox na de laatste maat (met lege spacer-HBox ervoor), DejaVu Sans Condensed 14pt — of in een VBox als er te weinig ruimte is. MusicXML/MXL kan MuseScore-Style/HBox/VBox niet round-trippen. YAML-cycle/final blijft leidend.

Laatste systeem niet uitrekken¶

In het .mscz staan de MuseScore-stijlen: enableVerticalSpread=0, maxPageFillSpread=0, en lage gelijke minSystemDistance/maxSystemDistance (anders vult MuseScore tot het maximum, ook met vertical spread uit). lastSystemFillLimit=1 op het formuleblad (100% — laatste systeem rekt niet horizontaal). MusicXML kan die stijl niet dragen.

Reciteertoon (||O||)¶

Op het blad is de reciteertoon een brevis-kop (het symbool ||O||) — zonder teken erboven (zoals in het toonboek/PDF). In het .mscx:

durationType half (2 tellen afspelen én ruimte in de maat);
<headType>breve</headType>;
stok verborgen (<noStem>1</noStem>) op alle stemmen;
geen fermata of decoratief symbool boven de noot.

YAML: role: recite. Mapping naar syllaben gebruikt later vooral de rol.

Herhalingstekens (cycle-form)¶

Bij cycle + final in YAML zet de renderer in het .mscx:

<startRepeat/> op de maat van het eerste cycle-frase-id;
<endRepeat>N</endRepeat> op de maat van het laatste cycle-frase-id (N = aantal ids in cycle, bijv. 2 voor 1, 2).

Dat correspondeert met ||: 1, 2 :|| op het blad. De cycle-tekst blijft in de trailing HBox (of VBox als fallback).

Ankers plaatsen¶

Twee opeenvolgende staff texts op de noot die het anker heeft (niet op de maat): eerst de afkorting (l. st.), daaronder de pijl. Eén keer op de S/A-partij volstaat.

Tips tegen MuseScore-“intelligentie”¶

Insert-modus bij ritmewijzigingen. Geen extra maatlengte of verborgen rusten: de MSCX is ook koorprint.
Split/merge van formuleslots alleen als het blad dat zo heeft; VSA-tekst splitst later (instance).
Eerst S, dan A (voice 2), dan TB.

Formules aanwezig¶

Map	Vorm	Opmerking
`tropaar-toon-1`	cycle
`tropaar-toon-3`	sequence
`tropaar-toon-4`	cycle	Elia-mapping + corpus
`tropaar-toon-5`	`same_as`	→ stichier-toon-5
`stichier-toon-5`	cycle	ook als tropaar
`vers-toon-1`	cycle
`vers-toon-5`	cycle

Normatieve syntax/semantiek: map erboven (../README.md).