2.3 Fonctions musicales

@translationof Music functions

Les fonctions musicales sont des procédures Scheme capables de créer automatiquement des expressions musicales ; elles permettent de grandement simplifier un fichier source.

2.3.1 Définition de fonctions musicales

@translationof Music function definitions

Une fonction musicale se définit ainsi :

fonction =
#(define-music-function
     (arg1 arg2…)
     (type1? type2?…)
   corps)

de manière similaire aux fonctions Scheme. La plupart du temps, le corps sera constitué d’un bloc de code LilyPond.

Les différents types des prédicat sont recensés à l’annexe (notation)Types de prédicats prédéfinis section ‘Types de prédicats prédéfinis’ dans Manuel de notation.

Voir aussi

Manuel de notation : (notation)Types de prédicats prédéfinis section ‘Types de prédicats prédéfinis’ dans Manuel de notation.

Fichiers d’initialisation : ‘lily/music-scheme.cc’, ‘scm/c++.scm’, ‘scm/lily.scm’.

2.3.2 Utilisation de fonctions musicales

@translationof Music function usage

Une « fonction musicale » doit impérativement renvoyer une expression répondant au prédicat ly:music?. Ceci a pour conséquence d’autoriser l’appel à une fonction musicale en tant qu’argument de type ly:music? dans le cadre de l’appel à une autre fonction musicale.

Certaines restrictions s’appliqueront selon le contexte où une fonction musicale est utilisée, de telle sorte que l’analyse syntaxique soit sans ambiguïté.

• Dans une expression musicale de haut niveau, aucun postévénement n’est toléré.
• Lorsqu’une fonction musicale – contrairement à une fonction événementielle – renvoie une expression de type postévénement, LilyPond requiert son introduction par un indicateur de positionnement – à savoir -, ^ ou _ – de telle sorte que le postévénement produit par l’appel à cette fonction s’intègre correctement dans l’expression environnante.
• En tant que partie d’un accord, l’expression musicale renvoyée doit être du type rhythmic-event, et plus particulièrement un NoteEvent.

Des fonctions « polymorphes » telles que \tweak peuvent s’appliquer aux postévénements, constituants d’accord et expressions de haut niveau.

2.3.3 Fonctions de substitution simple

@translationof Simple substitution functions

Une fonction de substitution simple renvoie une expression musicale écrite au format LilyPond et contient des arguments au format de l’expression résultante. Vous en trouverez une description détaillée à la rubrique (notation)Exemples de fonction de substitution section ‘Exemples de fonction de substitution’ dans Manuel de notation.

2.3.4 Fonctions de substitution intermédiaires

@translationof Intermediate substitution functions

Une fonction de substitution intermédiaire est une fonction dont l’expression musicale résultante mélangera du code Scheme au code LilyPond.

Certaines commandes \override nécessitent un argument supplémentaire constitué d’une paire de nombres, appelée cons cell en Scheme – que l’on pourrait traduire par « construction de cellule ».

Cette paire peut se mentionner directement dans la fonction musicale à l’aide d’une variable pair? :

manualBeam =
#(define-music-function
     (beg-end)
     (pair?)
   #{
     \once \override Beam.positions = #beg-end
   #})

\relative c' {
  \manualBeam #'(3 . 6) c8 d e f
}

Autre manière de procéder, les nombres formant la paire sont transmis comme arguments séparés ; le code Scheme chargé de créer la paire pourra alors être inclus dans l’expression musicale :

manualBeam = #(define-music-function (beg end) (number? number?) #{ \once \override Beam.positions = #(cons beg end) #}) \relative c' { \manualBeam #3 #6 c8 d e f }

L’entretien des propriétés peut se voir comme un empilement par propriété par objet par contexte. Les fonctions musicales peuvent nécessiter des dérogations pour une ou plusieurs propriétés pour la durée de la fonction, puis de revenir aux valeurs précédentes avant de quitter. Néanmoins, une dérogation normale va retirer de la pile – ou dépiler – et supprimer le sommet de la pile de la propriété avant d’y ajouter quoi que ce soit – ou empiler – ; la valeur précédente de la propriété est de fait perdue. Lorsque la valeur antérieure doit être préservée, l’instruction \override devra être préfixée d’un \temporary, comme ceci :

\temporary \override …

L’utilisation d’un \temporary a pour effet d’effacer la propriété pop-first (commence par dépiler normalement activée) de la dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile de la propriété avant d’y empiler la nouvelle valeur. Lorsqu’un \revert viendra par la suite supprimer la valeur dérogatoire temporaire, réapparaitra la valeur antérieure.

En d’autres termes, un \revert qui suit un \temporary \override pour la même propriété n’apporte rien. Ce principe est aussi valable pour un couple \temporary et \undo sur la même musique contenant des dérogations.

Voici un exemple de fonction musicale utilisant cette fonctionnalité. La présence du \temporary permet de s’assurer qu’en sortant de la fonction, les propriétés cross-staff et style retrouveront les valeurs qu’elles avaient avant que ne soit appelée la fonction crossStaff. En l’absence de \temporary, ces propriétés auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.

crossStaff =
#(define-music-function (notes) (ly:music?)
  (_i "Create cross-staff stems")
  #{
  \temporary \override Stem.cross-staff = #cross-staff-connect
  \temporary \override Flag.style = #'no-flag
  #notes
  \revert Stem.cross-staff
  \revert Flag.style
#})

2.3.5 De l’usage des mathématiques dans les fonctions

@translationof Mathematics in functions

Une fonction musicale peut requérir, en plus d’une simple substitution, une part de programmation en Scheme.

AltOn = #(define-music-function (mag) (number?) #{ \override Stem.length = #(* 7.0 mag) \override NoteHead.font-size = #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #}) AltOff = { \revert Stem.length \revert NoteHead.font-size } \relative { c'2 \AltOn #0.5 c4 c \AltOn #1.5 c c \AltOff c2 }

Cette fonction pourrait tout à fait être réécrite de telle sorte qu’elle s’applique à une expression musicale :

withAlt = #(define-music-function (mag music) (number? ly:music?) #{ \override Stem.length = #(* 7.0 mag) \override NoteHead.font-size = #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #music \revert Stem.length \revert NoteHead.font-size #}) \relative { c'2 \withAlt #0.5 { c4 c } \withAlt #1.5 { c c } c2 }

2.3.6 Fonctions dépourvues d’argument

@translationof Functions without arguments

Dans la plupart des cas, une fonction dépourvue d’argument devrait être créée à l’aide d’une variable :

dolce = \markup{ \italic \bold dolce }

Il peut, dans certains cas particuliers, s’avérer utile de créer une fonction sans argument comme ici,

displayBarNum =
#(define-music-function
     ()
     ()
   (if (eq? #t (ly:get-option 'display-bar-numbers))
       #{ \once \override Score.BarNumber.break-visibility = ##f #}
       #{#}))

de manière à pouvoir afficher les numéros de mesure grâce à un appel à cette fonction. En pareil cas, vous devrez invoquer lilypond en respectant la syntaxe

lilypond -d display-bar-numbers MONFICHIER.ly

2.3.7 Fonctions musicales fantômes

@translationof Void music functions

Une fonction musicale doit renvoyer une expression musicale. Toutefois, une fonction musicale peut n’être exécutée que dans le but d’en retenir les effets annexes ; vous devrez alors utiliser une procédure define-void-function. Il peut cependant arriver que vous ayez besoin d’une fonction qui, selon le cas, produise ou non (comme dans l’exemple de la rubrique précédente) une expression musicale. L’utilisation d’un #{ #} vous permettra de renvoyer une expression musicale void.

Ce document a été généré le le 13 juillet 2020 par gub en utilisant texi2html 1.82.

Autres langues : English, deutsch, español.
À propos de la sélection automatique de la langue.