1\documentclass[12pt,a4paper]{article} 2 3 4% ------------------------------------------------------------------------- 5% import common LaTeX settings 6% ------------------------------------------------------------------------- 7 8\usepackage{import} 9 10\subimport{../}{CommonLaTeXSettings} 11 12 13% ------------------------------------------------------------------------- 14\begin{document} 15% ------------------------------------------------------------------------- 16 17%\noindent 18 19\title{ 20Introduction to \mxml\\[5pt] 21\large {Notensatz-Konferenz, Salzburg Mozarteum, January 17-18, 2020} 22} 23 24\newsavebox{\authorBox} 25\sbox{\authorBox}{ 26\raisebox{-0.35em}{ 27\begin{minipage}{\textwidth} 28\footnotesize% 29Former lecturer in computer science at Centre Universitaire d'Informatique,\\ 30University of Geneva, Switzerland 31\end{minipage} 32} 33} 34 35\author{ 36Jacques Menu 37\footnote{ 38\usebox{\authorBox} 39} 40} 41 42%\date {\normalsize \today\ version} 43\date {} 44 45\maketitle 46\thispagestyle{fancy} % right after \maketitle to apply it to the first page too 47 48\abstract { 49This document presents a basic view of \mxml\ and a couple of short examples illustrating how \mxml\ represents a music score. Our goal is to give a flavor of what \mxml\ definitions and data look like from a musician's point of view. We use a combination of formal definitions from the \mxml\ DTD and free text explanations. 50 51\sep 52 53All the examples mentioned can be downloaded from \url{https://github.com/grame-cncm/libmusicxml/tree/lilypond/files/samples/musicxml}. They are grouped by subject in subdirectories, such as \mxmlfile{basic/HelloWorld.xml}. 54 55\sep 56 57The contents of this document is verbose... because \mxml\ itself is! 58} 59 60% ------------------------------------------------------------------------- 61% ------------------------------------------------------------------------- 62\section{Software tools used} 63% ------------------------------------------------------------------------- 64% ------------------------------------------------------------------------- 65 66\mxml\ files have been named with a '{\tt .xml}' suffix for years, until it was decided rather recently that this should be changed to '{\tt .musicxml}'. There are GUI applications that filter the file names in their '{\tt open}' or '{\tt import}' dialogs and don't know that change yet, though. We will thus stick to the '{\tt .xml}' suffix convention. 67 68\sep 69 70The scores fragments shown in this document have been produced by translating the '{\tt .xml}' file to \lily\ syntax, and then creating the graphical score with \lily. 71 72\sep 73 74The translations have been done by \xmlToLy, a prototype tool developed by this author. \xmlToLy\ and some of the specific examples presented in this document are this author's contribution to \lib, an open-source C++ library created and maintained by Dominique Fober at Grame, Lyon, France. 75 76The home page to \lib\ is \url{https://github.com/grame-cncm/libmusicxml}, and \xmlToLy\ is in the '{\tt lilypond}' branch. 77 78\sep 79 80The reader is invited to handle the '{\tt .xml}' file examples with their own software tools to compare the results with the ones herein. 81 82\sep 83 84Other score editing applications are mentioned in this document, namely \sib, 85\fin\ and \muse\ (\url{https://musescore.org}), which is open-source. 86This author doesn't own licenses for other commercial applications such as Dorico\texttrademark\ or Capella\texttrademark. 87 88\sep 89 90\mxmlToLy\ is mentioned too: this translator of \mxml\ to \lily\ is supplied with \lily. The design goals of \xmlToLy\ are to perform at least as well as \mxmlToLy, while providing as many options as needed to avoid too much editing of the \lcg. 91 92\sep \sep 93 94 95% ------------------------------------------------------------------------- 96% ------------------------------------------------------------------------- 97\section{Overview of \mxml\ } 98% ------------------------------------------------------------------------- 99% ------------------------------------------------------------------------- 100 101% ------------------------------------------------------------------------- 102\subsection{What is \mxml?} 103% ------------------------------------------------------------------------- 104 105\mxml\ ({\it Music eXtended Markup Language}, \url{https://www.musicxml.com}) is a specification language meant to represent western notation music scores by texts, readable both by humans and computers, and to help sharing music score files between applications, through export and import mechanisms.. 106 107It has been invented by Michael Good and initially developed by Recordare LLC, which was bought by MakeMusic in 2011, and finally transferred to the W3C Music Notation Community Group (\url{https://www.w3.org/community/music-notation/}) in 2015. See \url{https://en.wikipedia.org/wiki/MusicXML} for more historical details. 108 109\sep 110 111\mxml\ data contains very detailed information about the music score, and it is {\it quite verbose} by nature. This makes creating such data by hand very difficult, and this is done by applications actually. 112 113% ------------------------------------------------------------------------- 114\subsection{Part-wise vs. measure-wise descriptions} 115% ------------------------------------------------------------------------- 116 117\mxml\ allows the score to be represented as a sequence of parts, each containing a sequence of measures, or as a sequence of measures, each containing a sequence of parts, i.e. data describing the contents of the corresponding measure in a part. 118 119\sep 120 121It seems that measure-wise descriptions have been very little used and then abandoned, and we shall stick to part-wise \mxml\ data in this document. 122 123As a historical note, an XSL/XSLT script was supplied in the early days of \mxml\ to convert between part-wise and measure-wise representations. 124 125% ------------------------------------------------------------------------- 126\subsection{\mxml's formal definition} 127\mylabel{formalDefinition} 128% ------------------------------------------------------------------------- 129 130As a member of the *XML family of languages, \mxml\ is defined by a DTD ({\it Document Type Definition}), to be found at \url{https://github.com/w3c/musicxml/tree/v3.1}. 131 132\sep 133 134An *XML DTD defines: 135\begin{itemize} 136\item {\it elements}, used to structure the data since they can be nested; 137\item {\it attributes}, that attach named values to the elements; 138\item {\it entities}, which are names of groups of elements, such as '{\tt layout-tenths}' and '{\tt start-stop}'. There are used to structure the DTD itself when those elements occur at multiple places in the DTD, and make the latter more readable and easier to update. 139\end{itemize} 140 141\sep 142 143For example, consider: 144\begin{lstlisting}[language=XML] 145 <part id="P1"> 146 <measure number="1" width="464.29"> 147 <!-- ... ... ... ... ... --> 148\end{lstlisting} 149 150We see that: 151\begin{itemize} 152\item the '{\tt <part>}' element contains a nested '{\tt <measure>}' element; 153\item the '{\tt <part>}' element has an '{\tt id}' attribute containing the name of the part, '{\tt P1}'; 154\item the '{\tt <measure>}' element's attributes contain measure number '{\tt 1}'and width '{\tt 464.29}'. 155\end{itemize} 156 157Some elements contain a single unnamed data item, such as durations and voice and staff numbers: 158\begin{lstlisting}[language=XML] 159 <duration>4</duration> 160 <voice>2</voice> 161 <staff>1</staff> 162\end{lstlisting} 163 164\sep 165 166The \subdir{dtds/3.1/schema} subdirectory contains '{\tt *.mod}' text files defining the various concepts. The file \schemafile{common.mod} contains definitions used in other '{\tt *.mod}' files: 167\begin{lstlisting}[language=XML] 168<!-- 169 This file contains entities and elements that are common 170 across multiple DTD modules. In particular, several elements 171 here are common across both notes and measures. 172--> 173\end{lstlisting} 174 175\sep 176 177For example, \schemafile{note.mod} defines the '{\tt <backup>}' and {\tt <forward>}' markups this way: 178\begin{lstlisting}[language=XML, caption={'{\tt <backup>}' and '{\tt <forward>}' definition}] 179<!-- 180 The backup and forward elements are required to coordinate 181 multiple voices in one part, including music on multiple 182 staves. The forward element is generally used within voices 183 and staves, while the backup element is generally used to 184 move between voices and staves. Thus the backup element 185 does not include voice or staff elements. Duration values 186 should always be positive, and should not cross measure 187 boundaries or mid-measure changes in the divisions value. 188--> 189<!ELEMENT backup (duration, %editorial;)> 190<!ELEMENT forward 191 (duration, %editorial-voice;, staff?)> 192\end{lstlisting} 193 194An example of their use is: 195\begin{lstlisting}[language=XML, caption={'{\tt <backup>}' and '{\tt <forward>}' example}] 196 <forward> 197 <duration>4</duration> 198 <voice>2</voice> 199 <staff>1</staff> 200 </forward> 201 <backup> 202 <duration>8</duration> 203 </backup> 204\end{lstlisting} 205 206\sep 207 208In DTDs, sub-elements can be followed by one of these characters, which mean, as is usual in computer science: 209\begin{itemize} 210\item'{\tt ?}': 0 or 1 occurence, i.e. optional; 211\item'{\tt *}': 0 or more occurrences; 212\item'{\tt +}': 1 or more occurrences. 213\end{itemize} 214 215One can see in the definition of the '{\tt <forward>}' element that the '{\tt <duration>}' element is mandatory, while the '{\tt <staff>}' element is optional. The text in the DTD tells that staff 1 in implied if it not specified. 216 217\sep 218 219In a DTD, '{\tt CDATA}' means {\it Character Data}. Such data is not analyzed by the software that reads the \mxml\ data, it is merely passed over verbatim to whoever asked the data to be read in. 220 221In the same vein, '{\tt PCDATA}' means {\it Parsed Character Data}, that is, mixed content XML data that are analyzed by software tools. 222 223\sep 224 225The current version of the \mxml\ DTD is~3.1, and there are discussions about version~3.2. 226 227\sep 228 229The syntactical aspects of \mxml\ are quite simple and regular, which makes it easy to handle \mxml\ data with algorithms. 230 231\page 232 233% ------------------------------------------------------------------------- 234\subsection{Markups} 235% ------------------------------------------------------------------------- 236 237\mxml\ data is made of so-called markups (the 'M' in 'XML'), delimited by an {\it start-tag} and a {\it stop-tag}. 238 239The start-tag is introduced by a '{\tt <}' and closed by a '{\tt >}', as in '{\tt <part-list>}'. The stop-tag is introduced by a '{\tt </}' and closed by a '{\tt >}', as in '{\tt </part-list>}'. 240 241\sep 242 243Markups go by pairs, as in: 244\begin{lstlisting}[language=XML] 245 <duration>4</duration> 246\end{lstlisting} 247 248The spaces and end of lines between markups are ignored. 249 250\sep 251 252It is possible to contract an element that contains nothing between its start-tag and stop-tag, such as: 253\begin{lstlisting}[language=XML] 254 <dot></dot> 255\end{lstlisting} 256which can be written: 257\begin{lstlisting}[language=XML] 258 <dot /> 259\end{lstlisting} 260 261\sep 262 263We shall call {\it sub-element} and element nested into another one. '{\tt <part-name>}' is thus a sub-element of element '{\tt <score-part}' above. 264 265\sep 266 267The values of attributes can be double-quoted characters strings and integer or floating point numbers. 268 269Some attributes are mandatory such as '{\tt id}' in '{\tt <score-part>}', while others are optional. 270 271\sep 272 273Comments can be used in \mxml\ data. They start with a '{\tt <!--}' start-tag and end with a '{\tt -->}' stop-tag, as in: 274\begin{lstlisting}[language=XML] 275<!--=========================================================--> 276 <measure number="1"> 277 <!-- A very minimal MusicXML example, part P1, measure 1 --> 278\end{lstlisting} 279 280Comments can span several lines. 281 282\sep 283 284\hand {\mxml\ is a representation of HOW TO DRAW a score, which has implications on the kind of markups available, in particular '{\tt <forward>}' and '{\tt <backup>}', which are presented at \mylink{multipleVoices}. 285} 286 287The syntax of \mxml\ data quite regular and simple, and it is easy to program lexical/syntactical analyzers for it. 288 289% ------------------------------------------------------------------------- 290\subsection{Overall structure of \mxml\ data} 291% ------------------------------------------------------------------------- 292 293\mxml\ data consists of: 294\begin{itemize} 295\item a '{\tt <?xml>}' element indicating the characters encoding used; 296\item a '{\tt <!DOCTYPE>}' element telling that the contents is in '{\tt score-partwise}' mode; 297\item a '{\tt <score-partwise>}' element indicating the \mxml\ DTD number that the forthcoming data complies to, and that contains: 298 299\item a score header containing: 300 \begin{itemize} 301 \item an optional '{\tt <work>}' element, containing sub-elements such as '{\tt <work-number>}', \\ 302 '{\tt <work-title>}' and '{\tt <opus>}'; 303 304 \item optional '{\tt <movement-number>}', '{\tt <movement-title>}', '{\tt <identification>}' and \\ 305 '{\tt <defaults>}' sub-elements; 306 307 \item 0 or more '{\tt <credit>}' elements; 308 309 \item a '{\tt <part-list>}' element containing the various '{\tt <score-part>}'s in the score; 310 \end{itemize} 311 312\item a sequence of '{\tt <part>}' elements in the order they appear in the score, each one containing the measures in the given part, in order. 313\end{itemize} 314 315\page 316 317Here is how the score header is actually defined in \schemafile{score.mod}: 318\begin{lstlisting}[language=XML] 319<!-- 320 The score-header entity contains basic score metadata 321 about the work and movement, score-wide defaults for 322 layout and fonts, credits that appear on the first page, 323 and the part list. 324--> 325<!ENTITY % score-header 326 "(work?, movement-number?, movement-title?, 327 identification?, defaults?, credit*, part-list)"> 328\end{lstlisting} 329 330% ------------------------------------------------------------------------- 331\subsection{What is the semantics of \mxml\ data?} 332% ------------------------------------------------------------------------- 333 334We have seen in section \mylink{formalDefinition}, that not specifying the staff number in a '{\tt <forward>}' element implies a value of one. 335 336It is very difficult to define the semantics -- the meaning of the sentences -- of an artificial language in a complete and consistent way, i.e. without omitting anything and without contradictions. 337 338\mxml\ is no exception to this rule: there are things unsaid in the DTD, which leaves room to interpretation by the various applications that create or handle \mxml\ data. 339 340\sep 341 342For example, clefs are defined in \schemafile{attributes.mod}, starting with: 343\begin{lstlisting}[language=XML] 344<!-- 345 Clefs are represented by the sign, line, and 346 clef-octave-change elements. Sign values include G, F, C, 347 percussion, TAB, jianpu, and none. Line numbers are 348 counted from the bottom of the staff. Standard values are 349 ... ... ... ... ... 350\end{lstlisting} 351 352What is a '{\tt none}' clef? Is the clef currently in use still to be used from now on, merely hiding the '{\tt none}' clef, or should an implicit, default treble clef be used? As it turns out, various applications don't agree on the answer to this question, see the next-to-last measure of \mxmlfile{clefs/Clefs.xml}. 353 354\sep 355 356This author has found \mxml\ files that contain '{\tt PERCUSSION}': is this to be accepted and handled as '{\tt percussion}'? This point is not mentioned in the DTD either. 357 358 359% ------------------------------------------------------------------------- 360% ------------------------------------------------------------------------- 361\section{A complete example} 362% ------------------------------------------------------------------------- 363% ------------------------------------------------------------------------- 364 365As is usual in computer science, this minimal example is named \mxmlfile{basic/HelloWorld.xml}. It is displayed below, together with the resulting graphic score. 366 367\sep 368 369The first line specifies the character encoding of the contents below, here UTF-8. Then the '{\tt !DOCTYPE}' element at lines 2 to 4 tells us that this file contains partwise data conforming to DTD 3.0. 370 371Then the '{\tt <part-list>}' element at lines 7 to 11 contains a list of '{\tt <score-part>}'s with their '{\tt id}' attribute, here '{\tt P1}' alone. 372 373After this, we find the sequence of '{\tt part}'s with their '{\tt id}' attribute, here '{\tt P1}' alone, and, inside it, the single '{\tt <measure>}' sub-element whose attribute '{\tt number}' contains '{\tt 1}'. 374 375\sep 376 377The nesting of elements, such as '{\tt <key>}' containing a '{\tt <fifths>}' element, leads the structure of a \mxml\ representation to be a tree. The way the specification is written conforms to the computer science habit of drawing trees with their root at the top and their leaves at the bottom. 378 379%\begin{figure} 380%\caption{Contents of \mxmlfile{basic/Helloworld.xml}\mylabel{helloworld} 381\includegraphics{HelloWorld.png} 382 383\begin{lstlisting}[language=XML, caption={\tt HelloWorld.xml}] 384<?xml version="1.0" encoding="UTF-8" standalone="no"?> 385<!DOCTYPE score-partwise PUBLIC 386 "-//Recordare//DTD MusicXML 3.0 Partwise//EN" 387 "http://www.musicxml.org/dtds/partwise.dtd"> 388<score-partwise version="3.0"> 389 <work> 390 <work-title>Hello World!</work-title> 391 </work> 392 <!-- A very minimal MusicXML example --> 393 <part-list> 394 <score-part id="P1"> 395 <part-name>Music</part-name> 396 </score-part> 397 </part-list> 398 <part id="P1"> 399<!--=========================================================--> 400 <measure number="1"> 401 <!-- A very minimal MusicXML example, part P1, measure 1 --> 402 <attributes> 403 <divisions>1</divisions> 404 <key> 405 <fifths>0</fifths> 406 </key> 407 <time> 408 <beats>4</beats> 409 <beat-type>4</beat-type> 410 </time> 411 <clef> 412 <sign>G</sign> 413 <line>2</line> 414 </clef> 415 </attributes> 416 <!-- A very minimal MusicXML example, part P1, measure 1, before first note --> 417 <note> 418 <pitch> 419 <step>C</step> 420 <octave>4</octave> 421 </pitch> 422 <duration>4</duration> 423 <type>whole</type> 424 </note> 425 </measure> 426<!--=========================================================--> 427 </part> 428</score-partwise> 429\end{lstlisting} 430%\end{figure} 431 432\page 433 434% ------------------------------------------------------------------------- 435% ------------------------------------------------------------------------- 436\section{Measurements} 437% ------------------------------------------------------------------------- 438% ------------------------------------------------------------------------- 439 440% ------------------------------------------------------------------------- 441\subsection{Geometrical lengths} 442% ------------------------------------------------------------------------- 443 444\mxml\ represents lengths by 10$^{th}$ of an interline space, i.e. the distance between lines in staves. This relative measure unit has the advantage that it allows all lengths to be represented independantly of the actual size of the score. 445 446\sep 447 448In \schemafile{common.mod} we find: 449 450\begin{lstlisting}[language=XML,caption={Relative lengths}] 451<!-- 452 The tenths entity is a number representing tenths of 453 interline space (positive or negative) for use in 454 attributes. The layout-tenths entity is the same for 455 use in elements. Both integer and decimal values are 456 allowed, such as 5 for a half space and 2.5 for a 457 quarter space. Interline space is measured from the 458 middle of a staff line. 459--> 460<!ENTITY % tenths "CDATA"> 461<!ENTITY % layout-tenths "(#PCDATA)"> 462\end{lstlisting} 463 464\sep 465 466In order to obtain absolute lengths for drawing, \mxml\ specifies how many tenths are equal to how many millimeters in the '{\tt <scaling>}' element, defined in \schemafile{layout.mod}: 467 468\begin{lstlisting}[language=XML,caption={Abolute lengths}] 469<!-- 470 Version 1.1 of the MusicXML format added layout information 471 for pages, systems, staffs, and measures. These layout 472 elements joined the print and sound elements in providing 473 formatting data as elements rather than attributes. 474 475 Everything is measured in tenths of staff space. Tenths are 476 then scaled to millimeters within the scaling element, used 477 in the defaults element at the start of a score. Individual 478 staves can apply a scaling factor to adjust staff size. 479 When a MusicXML element or attribute refers to tenths, 480 it means the global tenths defined by the scaling element, 481 not the local tenths as adjusted by the staff-size element. 482--> 483 484<!-- .................. --> 485 486<!-- 487 Margins, page sizes, and distances are all measured in 488 tenths to keep MusicXML data in a consistent coordinate 489 system as much as possible. The translation to absolute 490 units is done in the scaling element, which specifies 491 how many millimeters are equal to how many tenths. For 492 a staff height of 7 mm, millimeters would be set to 7 493 while tenths is set to 40. The ability to set a formula 494 rather than a single scaling factor helps avoid roundoff 495 errors. 496--> 497<!ELEMENT scaling (millimeters, tenths)> 498<!ELEMENT millimeters (\#PCDATA)> 499<!ELEMENT tenths %layout-tenths;> 500\end{lstlisting} 501 502\page 503 504This leads for example to: 505\begin{lstlisting}[language=XML, caption={Scaling example}] 506 <scaling> 507 <millimeters>7.05556</millimeters> 508 <tenths>40</tenths> 509 </scaling> 510\end{lstlisting} 511 512% ------------------------------------------------------------------------- 513\subsection{Notes durations} 514% ------------------------------------------------------------------------- 515 516\mxml\ uses a quantization of the duration with the '{\tt <divisions>}' element, which tells how many divisions there are in a quarter note: 517\begin{lstlisting}[language=XML] 518 <divisions>2</divisions> 519\end{lstlisting} 520 521\sep 522 523This example means that there are '{\tt 2}' divisions in a quarter note, i.e. the duration measure unit is an eigth note. Let's borrow from physics and MIDI terminology and call this a {\it quantum}. 524 525Any multiple of this quantum can be used in the \mxml\ data after that specification, but there's no way to express a duration less than an eigth node. 526 527The quantum value has to be computed from the shortest note in the music that follows this element, taking tuplets into account, see section \mylink{tuplets}. 528 529\sep 530 531Is it possible to set the quantum to other values in multiple places in the \mxml\ data at will if needed? The DTD doesn't mentions that, and in practice, all applications support this feature. 532 533\sep 534 535Notes prolongation dots are specified with as many '{\tt <dot>}' elements as needed: 536\begin{lstlisting}[language=XML] 537<!-- 538 One dot element is used for each dot of prolongation. 539 The placement element is used to specify whether the 540 dot should appear above or below the staff line. It is 541 ignored for notes that appear on a staff space. 542--> 543<!ELEMENT dot EMPTY> 544<!ATTLIST dot 545 %print-style; 546 %placement; 547> 548\end{lstlisting} 549 550 551% ------------------------------------------------------------------------- 552\subsection{Graphics and sound} 553% ------------------------------------------------------------------------- 554 555\mxml\ has to account for the possible difference between the drawn head note and the duration of that note, as is the case in tuplets. 556 557In a tuplet containing 3 sixteenth notes, the duration of each such note is one third of that of an eigth note, but the drawn head note's graphical duration is half of that of the latter. 558See section \mylink{tuplets}, for an example of how this is represented. 559 560Some elements in \mxml\ data are specifically meant for MIDI support: they refer to the sound durations only. 561 562 563% ------------------------------------------------------------------------- 564% ------------------------------------------------------------------------- 565\section{Measures} 566\mylabel{mesures} 567% ------------------------------------------------------------------------- 568% ------------------------------------------------------------------------- 569 570The '{\tt <measure>}' elements can contain many other elements, depending on the music. 571 572Full measures are usually numbered from '{\tt 1}' up, but these numbers are actually character strings, {\it not integers}: this allows for special measure numbers such as '{\tt X1}', for example, in the case of cue staves. 573 574\sep 575 576Anacruses are best specified "the purist way", with '{\tt 0}' as their number and the '{\tt implicit}' attribute set to '{\tt yes}', which specifies that this measure number should not be printed. One sees cases where the number is '{\tt 1}' for anacruses, though: 577\begin{lstlisting}[language=XML] 578 <measure number="0" implicit="yes" width="129.48"> 579\end{lstlisting} 580 581\sep 582 583Measures can be irregular, i.e. with less total duration as the current time signature, or much longer that the usual time signatures, see \mylink{lyrics}, for an example. 584 585% ------------------------------------------------------------------------- 586% ------------------------------------------------------------------------- 587\section{Elements attachment decisions} 588% ------------------------------------------------------------------------- 589% ------------------------------------------------------------------------- 590 591The \mxml\ designers had to decide what element a given element should be attached to. Should a '{\tt <dynamics>}' element or '{\tt <metronome>}' element be attached to a note or be placed at the '{\tt <measure>}' level? Is so, should it occur in the data before or after the note over or below which it should be displayed? 592 593\sep 594 595\mxml\ defines a {\it direction} as a musical indication that is not necessarily 596 attached to a specific note. Two or more directions may be combined to 597 indicate the start and stop of wedges, dashes, and so on. 598 599\sep 600 601For example, '{\tt <dynamics>}' elements are placed outside of '{\tt <note>}' elements in a '{\tt <direction>}' element, at the measure level: 602\begin{lstlisting}[language=XML] 603 <direction placement="below"> 604 <direction-type> 605 <dynamics> 606 <ffff/> 607 </dynamics> 608 </direction-type> 609 <staff>1</staff> 610 </direction> 611\end{lstlisting} 612 613\sep 614 615The elements attached to notes are placed inside a '{\tt <notations>}' element, itself placed inside a '{\tt <note>}' element. Notations are defined in \schemafile{note.mod}: 616\begin{lstlisting}[language=XML, caption={Notations definition}] 617<!-- 618 Notations are musical notations, not XML notations. Multiple 619 notations are allowed in order to represent multiple editorial 620 levels. The print-object attribute, added in Version 3.0, 621 allows notations to represent details of performance technique, 622 such as fingerings, without having them appear in the score. 623--> 624<!ELEMENT notations 625 (%editorial;, 626 (tied | slur | tuplet | glissando | slide | 627 ornaments | technical | articulations | dynamics | 628 fermata | arpeggiate | non-arpeggiate | 629 accidental-mark | other-notation)*)> 630<!ATTLIST notations 631 %print-object; 632 %optional-unique-id; 633> 634\end{lstlisting} 635 636\page 637 638% ------------------------------------------------------------------------- 639% ------------------------------------------------------------------------- 640\section{Score description structure} 641% ------------------------------------------------------------------------- 642% ------------------------------------------------------------------------- 643 644\mxml\ data contains a mix of legal informations, score geometry and musical contents. Some aspects of this are presented in this section. 645 646% ------------------------------------------------------------------------- 647\subsection{Identification, rights and credits} 648% ------------------------------------------------------------------------- 649 650The '{\tt <identification>}' element is defined in \schemafile{identity.mod}: 651\begin{lstlisting}[language=XML] 652<!-- 653 Identification contains basic metadata about the score. 654 It includes the information in MuseData headers that 655 may apply at a score-wide, movement-wide, or part-wide 656 level. The creator, rights, source, and relation elements 657 are based on Dublin Core. 658--> 659<!ELEMENT identification (creator*, rights*, encoding?, 660 source?, relation*, miscellaneous?)> 661\end{lstlisting} 662 663\sep 664 665For example, \mxmlfile{xmlsamples3.1/ActorPreludeSample.xml} contains: 666\begin{lstlisting}[language=XML,caption={Identification and rights example}] 667 <identification> 668 <creator type="composer">Lee Actor</creator> 669 <rights>© 2004 Polygames. All Rights Reserved.</rights> 670 <encoding> 671 <software>Finale v25 for Mac</software> 672 <encoding-date>2017-12-12</encoding-date> 673 <supports attribute="new-system" element="print" type="yes" value="yes"/> 674 <supports attribute="new-page" element="print" type="yes" value="yes"/> 675 <supports element="accidental" type="yes"/> 676 <supports element="beam" type="yes"/> 677 <supports element="stem" type="yes"/> 678 </encoding> 679 </identification> 680\end{lstlisting} 681 682\sep 683 684The '{\tt <credit>}' element, defined in \schemafile{score.mod}, represents various legal informations about the score. It contains placement indication such as page number and alignment, as well as fonts information. 685 686\sep 687 688For example, one finds in \mxmlfile{xmlsamples3.1/ActorPreludeSample.xml}: 689\begin{lstlisting}[language=XML,caption={Credits example}] 690 <credit page="1"> 691 <credit-type>title</credit-type> 692 <credit-words default-x="1447" default-y="3477" font-size="19.5" justify="center" valign="top">Prelude to a Tragedy</credit-words> 693 </credit> 694 <credit page="1"> 695 <credit-type>composer</credit-type> 696 <credit-words default-x="2718" default-y="3387" font-size="7.8" justify="right" valign="top">Lee Actor (2003)</credit-words> 697 </credit> 698 <credit page="1"> 699 <credit-type>rights</credit-type> 700 <credit-words default-x="1447" default-y="45" font-size="7.8" justify="center" valign="bottom" xml:space="preserve">© 2004 Polygames. All Rights Reserved.</credit-words> 701 </credit> 702 <credit page="2"> 703 <credit-type>page number</credit-type> 704 <credit-words default-x="1412" default-y="45" font-size="7.8" halign="center" valign="bottom">- 2 -</credit-words> 705 </credit> 706 <credit page="3"> 707 <credit-type>page number</credit-type> 708 <credit-words default-x="1447" default-y="45" font-size="7.8" halign="center" valign="bottom">- 3 -</credit-words> 709 </credit> 710 <credit page="4"> 711 <credit-type>page number</credit-type> 712 <credit-words default-x="1412" default-y="45" font-size="7.8" halign="center" valign="bottom">- 4 -</credit-words> 713 </credit> 714\end{lstlisting} 715 716\sep 717 718We see the '{\tt <credit-words>}' element in the example above. In \mxml, '{\tt words}' means text, as defined in \schemafile{direction.mod}: 719\begin{lstlisting}[language=XML] 720<!-- 721 The words element specifies a standard text direction. 722 Left justification is assumed if not specified. 723 Language is Italian ("it") by default. Enclosure 724 is none by default. 725--> 726<!ELEMENT words (#PCDATA)> 727<!ATTLIST words 728 %text-formatting; 729 %optional-unique-id; 730> 731\end{lstlisting} 732 733% ------------------------------------------------------------------------- 734\subsection{Score geometry} 735% ------------------------------------------------------------------------- 736 737The dimensions and margins of the graphics score can be specified with the '{\tt <page-layout>}' element, as in \mxmlfile{basic/ClefKeyTime.xml}: 738\begin{lstlisting}[language=XML, caption={Page layout example}] 739 <defaults> 740 <scaling> 741 <millimeters>7.05556</millimeters> 742 <tenths>40</tenths> 743 </scaling> 744 <page-layout> 745 <page-height>1683.36</page-height> 746 <page-width>1190.88</page-width> 747 <page-margins type="even"> 748 <left-margin>56.6929</left-margin> 749 <right-margin>56.6929</right-margin> 750 <top-margin>56.6929</top-margin> 751 <bottom-margin>113.386</bottom-margin> 752 </page-margins> 753 <page-margins type="odd"> 754 <left-margin>56.6929</left-margin> 755 <right-margin>56.6929</right-margin> 756 <top-margin>56.6929</top-margin> 757 <bottom-margin>113.386</bottom-margin> 758 </page-margins> 759 </page-layout> 760 <word-font font-family="FreeSerif" font-size="10"/> 761 <lyric-font font-family="FreeSerif" font-size="11"/> 762 </defaults> 763\end{lstlisting} 764 765% ------------------------------------------------------------------------- 766\subsection{Part groups and parts} 767% ------------------------------------------------------------------------- 768 769Part groups are used to structure complex scores, mimicking the way large orchestras are organized. For example, there can be a winds group, containing several groups such as flutes, oboes, horns and bassoons. 770 771\sep 772 773A '{\tt <part-group>}' element has a '{\tt type}' attribute, whose value can be '{\tt start}' or '{\tt stop}'. A~part group is thus delimited by a pair of '{\tt <part-group>}' elements, the first one of type '{\tt start}', and the second one of type '{\tt stop}'. 774 775The '{\tt id}' attribute of the '{\tt <score-part>}' element is used to reference the part later in the \mxml\ data. Often, is has the form '{\tt Pn}', where '{\tt n}' is a number. 776 777\sep 778 779Part groups can be nested, leading to a hierarchy of groups. This is done with the '{\tt number}' attribute of the '{\tt <part-group>}' element, which indicates how '{\tt start}' and '{\tt stop}' attributes are paired together. 780 781\sep 782 783For example, \mxmlfile{partgroups/NestedPartGroups.xml} contains:\\ 784\includegraphics[scale=0.7]{NestedPartGroups.png} 785 786\begin{lstlisting}[language=XML, caption={Nested part groups example}] 787 <part-list> 788 <score-part id="P1"> 789 <part-name>Violin</part-name> 790 </score-part> 791 <part-group number="1" type="start"> 792 <group-symbol>line</group-symbol> 793 <group-barline>yes</group-barline> 794 </part-group> 795 <score-part id="P2"> 796 <part-name>Flute</part-name> 797 </score-part> 798 <part-group number="2" type="start"> 799 <group-symbol>bracket</group-symbol> 800 <group-barline>yes</group-barline> 801 </part-group> 802 <score-part id="P3"> 803 <part-name>Oboe I</part-name> 804 </score-part> 805 <score-part id="P4"> 806 <part-name>Oboe II</part-name> 807 </score-part> 808 <part-group number="2" type="stop"/> 809 <part-group number="1" type="stop"/> 810 <score-part id="P5"> 811 <part-name>English horn</part-name> 812 </score-part> 813 </part-list> 814\end{lstlisting} 815 816\sep 817 818The \mxml\ DTD states that part groups may {\it overlap}. This author suspects that this is only because Finale\texttrademark\ doesn't create \mxml\ markups in a strict first-in, last-out order. 819 820\sep 821 822Various applications handle \mxmlfile{shouldfail/OverlappingPartGroups.xml} their own way. \xmlToLy\ rejects such data for the time being, with this message: 823\begin{lstlisting}[language=XML,caption={Overlapping groups \xmlToLy\ error message}] 824 ### MusicXML ERROR ### shouldfail/OverlappingPartGroups.xml:39: 825There are overlapping part groups, namely: 826 '1' -=> PartGroup_2 ('1', partGroupName "Part group 1"), lines 15..39 827and 828 '2' -=> PartGroup_3 ('2', partGroupName "Part group 2"), lines 27..43 829 830Please contact the maintainers of libmusicxml2 (see option '-c, -contact'): 831 either you found a bug in the xml2ly translator, 832 or this MusicXML data is the first-ever real-world case 833 of a score exhibiting overlapping part groups. 834Abort trap: 6 (core dumped) 835\end{lstlisting} 836 837 838% ------------------------------------------------------------------------- 839\subsection{Staves and voices} 840% ------------------------------------------------------------------------- 841 842In \mxml, a part is composed of one or more staves, each composed of one or more voices. 843There are no structured staves nor voices as such in \mxml\ however -- that is, not the way parts and measures are. The '{\tt <stave>}' and '{\tt voice}' element only contain a number. 844 845\sep 846 847To be more precise: 848\begin{itemize} 849\item stave numbers start at '{\tt 1}' in every part, which refers to the top-most staff in the part; 850 851\item a staff number of '{\tt 1}' is implied by default, i.e. when an optional '{\tt <stave>}' element is missing, as can happen in notes descriptions; 852 853\item voice numbers start at '{\tt 1}' in every staff, and a voice number of '{\tt 1}' is implied by default, i.e. when an optional '{\tt <voice>}' element is missing; 854\end{itemize} 855 856A given voice can change staff and come back to the former one, for example in keyboard scores. 857 858\sep 859 860This author has found \mxml\ files in which the voice numbers are not contiguous, such as '{\tt 1}', '{\tt 5}' and '{\tt 9}'. The DTD doesn't preclude this, and the applications handle example \mxmlfile{multistaff/NonContiguousVoiceNumbers.xml} their own way. 861 862% ------------------------------------------------------------------------- 863\subsection{Clefs, keys and time signatures} 864% ------------------------------------------------------------------------- 865 866\mxml\ offers elements to describe the common cases: 867\begin{itemize} 868\item traditional keys are described by a '{\tt <fifths>}' element; 869 870\item simple clefs are described by '{\tt <sign>}' and '{\tt <line>}' elements; 871 872\item simple time signatures are desribed by '{\tt <beats>}' and '{\tt <beat-type>}' elements. 873\end{itemize} 874 875\page 876 877An example is found in \mxmlfile{basic/ClefKeyTime.xml}:\\ 878\includegraphics{ClefKeyTime.png} 879\begin{lstlisting}[language=XML, caption={Clef, key and time signature example}] 880 <attributes> 881 <divisions>2</divisions> 882 <key> 883 <fifths>-1</fifths> 884 </key> 885 <time> 886 <beats>2</beats> 887 <beat-type>4</beat-type> 888 </time> 889 <clef> 890 <sign>G</sign> 891 <line>2</line> 892 </clef> 893 </attributes> 894 <!-- ... ... ... ... ... --> 895 <attributes> 896 <key> 897 <fifths>1</fifths> 898 </key> 899 <time> 900 <beats>3</beats> 901 <beat-type>4</beat-type> 902 </time> 903 <clef> 904 <sign>F</sign> 905 <line>4</line> 906 </clef> 907 </attributes> 908\end{lstlisting} 909 910\sep 911 912In this example, the various sub-elements are: 913%\begin{adjustwidth}{-0.5cm}{-0.5cm} 914\begin{center} 915\footnotesize 916\def \contentsWidth{0.5\textwidth} 917\def \arraystretch{1.3} 918% 919\begin{tabular}[t]{lp{\contentsWidth}} 920\textbf{Fragment}&\textbf{Meaning} \tabularnewline[0.5ex] 921\hline\\[-3.0ex] 922% 923'{\tt <fifths>-1</fifths>}' & the number of fitfhs. A negative number is the number of flats, 0 means C major or A minor, and a positive value is the number of sharps 924\tabularnewline 925 926'{\tt <beats>2</beats>}' & the number of beats per measure \tabularnewline 927 928'{\tt <beat-type>4</beat-type>}' & the beat type, i.e. the duration of each beat expressed as a fraction of a whole note 929\tabularnewline 930 931'{\tt <sign>G</sign>}' & the clef sign to be displayed. Sign values include '{\tt G}', '{\tt F}', '{\tt C}', 932 '{\tt percussion}', '{\tt TAB}', '{\tt jianpu}', and '{\tt none}' 933\tabularnewline 934 935'{\tt <line>2</line>}' & the number of the line at which the clef is placed 936\tabularnewline 937 938\end{tabular} 939\end{center} 940%\end{adjustwidth} 941 942\sep 943 944Composite time signatures such as '{\tt 2/4 + 3/8}' and '{\tt 3+2/8}' can be specified, as well as '{\tt <senza-misura>}' for cadenzas. 945 946\page 947 948\mxml\ also supports non-traditional keys the Humdrum/Scot way. For example, the time signature at the beginning of measure 2 in \mxmlfile{keys/HumdrumScotKeys.xml} is described by:\\ 949\includegraphics{HumdrumScotKeys.png} 950 951\begin{lstlisting}[language=XML, caption={Humdrum/Scot non-traditional key example}] 952 <key> 953 <key-step>C</key-step> 954 <key-alter>-2</key-alter> 955 <key-step>G</key-step> 956 <key-alter>2</key-alter> 957 <key-step>D</key-step> 958 <key-alter>-1</key-alter> 959 <key-step>B</key-step> 960 <key-alter>1</key-alter> 961 <key-step>F</key-step> 962 <key-alter>0</key-alter> 963 <key-octave number="1">2</key-octave> 964 <key-octave number="2">3</key-octave> 965 <key-octave number="3">4</key-octave> 966 <key-octave number="4">5</key-octave> 967 <key-octave number="5">6</key-octave> 968 </key> 969\end{lstlisting} 970 971This is another example handled diffently by some applications. 972 973% ------------------------------------------------------------------------- 974\subsection{Metromone and tempo} 975% ------------------------------------------------------------------------- 976 977\mxml\ has rich support for metronome specifications. Example \schemafile{tempos/SwingTempo.xml} contains:\\ 978\includegraphics{SwingTempo.png}. 979\begin{lstlisting}[language=XML,caption={Swing tempo example}] 980 <direction placement="above"> 981 <direction-type> 982 <words>Swing</words> 983 </direction-type> 984 <direction-type> 985 <metronome parentheses="yes" default-y="30" halign="left" relative-x="26"> 986 <metronome-note> 987 <metronome-type>eighth</metronome-type> 988 <metronome-beam number="1">begin</metronome-beam> 989 </metronome-note> 990 <metronome-note> 991 <metronome-type>eighth</metronome-type> 992 <metronome-beam number="1">end</metronome-beam> 993 </metronome-note> 994 <metronome-relation>equals</metronome-relation> 995 <metronome-note> 996 <metronome-type>quarter</metronome-type> 997 <metronome-tuplet bracket="yes" show-number="actual" type="start"> 998 <actual-notes>3</actual-notes> 999 <normal-notes>2</normal-notes> 1000 <normal-type>eighth</normal-type> 1001 </metronome-tuplet> 1002 </metronome-note> 1003 <metronome-note> 1004 <metronome-type>eighth</metronome-type> 1005 <metronome-tuplet type="stop"> 1006 <actual-notes>3</actual-notes> 1007 <normal-notes>2</normal-notes> 1008 <normal-type>eighth</normal-type> 1009 </metronome-tuplet> 1010 </metronome-note> 1011 </metronome> 1012 </direction-type> 1013 </direction> 1014\end{lstlisting} 1015 1016 1017% ------------------------------------------------------------------------- 1018% ------------------------------------------------------------------------- 1019\section{Notes} 1020% ------------------------------------------------------------------------- 1021% ------------------------------------------------------------------------- 1022 1023A note is described by a '{\tt note}' element, defined in \schemafile{note.mod}: 1024\begin{lstlisting}[language=XML, caption={Note definition}] 1025<!-- 1026 Notes are the most common type of MusicXML data. The 1027 MusicXML format keeps the MuseData distinction between 1028 elements used for sound information and elements used for 1029 notation information (e.g., tie is used for sound, tied for 1030 notation). Thus grace notes do not have a duration element. 1031 Cue notes have a duration element, as do forward elements, 1032 but no tie elements. Having these two types of information 1033 available can make interchange considerably easier, as 1034 some programs handle one type of information much more 1035 readily than the other. 1036--> 1037<!ELEMENT note 1038 (((grace, ((%full-note;, (tie, tie?)?) | (cue, %full-note;))) | 1039 (cue, %full-note;, duration) | 1040 (%full-note;, duration, (tie, tie?)?)), 1041 instrument?, %editorial-voice;, type?, dot*, 1042 accidental?, time-modification?, stem?, notehead?, 1043 notehead-text?, staff?, beam*, notations*, lyric*, play?)> 1044\end{lstlisting} 1045 1046 1047\sep 1048 1049Consider \mxmlfile{basic/MinimalScore.xml}:\\ 1050\includegraphics{MinimalScore.png} 1051 1052\page 1053 1054The first note in measure 2 in this example is described by: 1055\begin{lstlisting}[language=XML, caption={Minimal score example}] 1056 <divisions>8</divisions> 1057 1058 <!-- ... ... ... ... ... --> 1059 1060 <clef> 1061 <sign>G</sign> 1062 <line>2</line> 1063 <clef-octave-change>-1</clef-octave-change> 1064 </clef> 1065 1066 <!-- ... ... ... ... ... --> 1067 1068 <note> 1069 <pitch> 1070 <step>E</step> 1071 <alter>-1</alter> 1072 <octave>4</octave> 1073 </pitch> 1074 <duration>28</duration> 1075 <voice>1</voice> 1076 <type>half</type> 1077 <dot /> 1078 <dot /> 1079 <accidental>flat</accidental> 1080 </note> 1081\end{lstlisting} 1082 1083\sep 1084 1085In this example, the various sub-elements are: 1086%\begin{adjustwidth}{-0.5cm}{-0.5cm} 1087\begin{center} 1088\footnotesize 1089\def \contentsWidth{0.5\textwidth} 1090\def \arraystretch{1.3} 1091% 1092\begin{tabular}[t]{lp{\contentsWidth}} 1093\textbf{Fragment}&\textbf{Meaning} \tabularnewline[0.5ex] 1094\hline\\[-3.0ex] 1095% 1096'{\tt <step>E</step>}' & the diatonic pitch of the note, from A to G 1097\tabularnewline 1098 1099'{\tt <alter>-1</alter>}' & the chromatic alteration in 1100 number of semitones (e.g., -1 for flat, 1 for sharp) 1101\tabularnewline 1102 1103'{\tt <octave>4</octave>}' & the absolute octave of the note, 0 to 9, where 4 indicates the octave 1104 started by middle C 1105\tabularnewline 1106 1107'{\tt <duration>28</duration>}' & the sounding duration of the note, 28 quanta, which is a double dotted half note with 4 quanta per quarter note (16+8+4) 1108\tabularnewline 1109 1110'{\tt <voice>1</voice>}' & the voice number of the note, 1 1111\tabularnewline 1112 1113'{\tt <type>half</type>}' & the display duration of the note, a half note, which determines the note head 1114\tabularnewline 1115 1116\end{tabular} 1117\end{center} 1118%\end{adjustwidth} 1119 1120Middle C is the one between the left hand and right hand staves in a typical score. Note here: octave numbers are absolute, and the treble clef is octaviated by a '{\tt <clef-octave-change>}' element! 1121 1122Voice and staff numbers are optional, in which case the default value is 1. 1123 1124\sep 1125 1126Having both a sounding and display duration specification is necessary because they do not coincide in the case of dotted notes and tuplets members, see \mylink{tuplets}, for the latter. 1127 1128\page 1129 1130Note elements can have '{\tt <stem>}' and '{\tt <beam>}' sub-elements attached to them, as in the following example. See \mylink{graceNotes} for a score containing some: 1131\begin{lstlisting}[language=XML] 1132 <note> 1133 <pitch> 1134 <step>A</step> 1135 <octave>2</octave> 1136 </pitch> 1137 <voice>3</voice> 1138 <type>16th</type> 1139 <stem>up</stem> 1140 <staff>2</staff> 1141 <beam number="1">begin</beam> 1142 <beam number="2">begin</beam> 1143 </note> 1144\end{lstlisting} 1145 1146\sep 1147 1148Before showing an example, we shall look into more detail in the elements that are attached to notes in the forthcoming sections. 1149 1150% ------------------------------------------------------------------------- 1151\subsection{Accidentals} 1152% ------------------------------------------------------------------------- 1153 1154\begin{lstlisting}[language=XML] 1155<!-- 1156 Actual notated accidentals. Valid values include: sharp, 1157 natural, flat, double-sharp, sharp-sharp, flat-flat, 1158 natural-sharp, natural-flat, quarter-flat, quarter-sharp, 1159 three-quarters-flat, three-quarters-sharp, sharp-down, 1160 sharp-up, natural-down, natural-up, flat-down, flat-up, 1161 double-sharp-down, double-sharp-up, flat-flat-down, 1162 flat-flat-up, arrow-down, arrow-up, triple-sharp, 1163 triple-flat, slash-quarter-sharp, slash-sharp, slash-flat, 1164 double-slash-flat, sharp-1, sharp-2, sharp-3, sharp-5, 1165 flat-1, flat-2, flat-3, flat-4, sori, koron, and other. 1166 ... ... ... ... ... 1167--> 1168<!ELEMENT accidental (#PCDATA)> 1169<!ATTLIST accidental 1170 cautionary %yes-no; #IMPLIED 1171 editorial %yes-no; #IMPLIED 1172 %level-display; 1173 %print-style; 1174 %smufl; 1175> 1176\end{lstlisting} 1177 1178% ------------------------------------------------------------------------- 1179\subsection{Articulations} 1180% ------------------------------------------------------------------------- 1181The \mxml\ articulation elementss are: 1182\begin{lstlisting}[language=XML] 1183<!-- 1184 Articulations and accents are grouped together here. 1185--> 1186<!ELEMENT articulations 1187 ((accent | strong-accent | staccato | tenuto | 1188 detached-legato | staccatissimo | spiccato | 1189 scoop | plop | doit | falloff | breath-mark | 1190 caesura | stress | unstress | soft-accent | 1191 other-articulation)*)> 1192<!ATTLIST articulations 1193 %optional-unique-id; 1194> 1195\end{lstlisting} 1196 1197% ------------------------------------------------------------------------- 1198\subsection{Ornaments} 1199% ------------------------------------------------------------------------- 1200 1201Ornaments are defined in \schemafile{note.mod}: 1202\begin{lstlisting}[language=XML] 1203<!ELEMENT ornaments 1204 (((trill-mark | turn | delayed-turn | inverted-turn | 1205 delayed-inverted-turn | vertical-turn | 1206 inverted-vertical-turn | shake | wavy-line | 1207 mordent | inverted-mordent | schleifer | tremolo | 1208 haydn | other-ornament), accidental-mark*)*)> 1209<!ATTLIST ornaments 1210 %optional-unique-id; 1211> 1212<!ELEMENT trill-mark EMPTY> 1213<!ATTLIST trill-mark 1214 %print-style; 1215 %placement; 1216 %trill-sound; 1217> 1218\end{lstlisting} 1219 1220% ------------------------------------------------------------------------- 1221\subsection{Dynamics} 1222% ------------------------------------------------------------------------- 1223 1224\mxml\ dynamics are defined in \schemafile{common.mod}: 1225 1226\begin{lstlisting}[language=XML] 1227<!ELEMENT dynamics ((p | pp | ppp | pppp | ppppp | pppppp | 1228 f | ff | fff | ffff | fffff | ffffff | mp | mf | sf | 1229 sfp | sfpp | fp | rf | rfz | sfz | sffz | fz | 1230 n | pf | sfzp | other-dynamics)*)> 1231<!ATTLIST dynamics 1232 %print-style-align; 1233 %placement; 1234 %text-decoration; 1235 %enclosure; 1236 %optional-unique-id; 1237\end{lstlisting} 1238 1239Other dynamics can also be specified: 1240\begin{lstlisting}[language=XML] 1241The other-dynamics element 1242 allows other dynamic marks that are not covered here, but 1243 many of those should perhaps be included in a more general 1244 musical direction element. Dynamics may also be combined as 1245 in <sf/><mp/>. 1246\end{lstlisting} 1247 1248 1249% ------------------------------------------------------------------------- 1250\subsection{An example of articulations and dynamics} 1251% ------------------------------------------------------------------------- 1252 1253The reader can see various such in \mxmlfile{articulations/ArticulationsAndOrnaments.xml}:\\ 1254\includegraphics{ArticulationsAndOrnaments.png} 1255 1256\page 1257 1258% ------------------------------------------------------------------------- 1259\subsection{Grace notes} 1260\mylabel{graceNotes} 1261% ------------------------------------------------------------------------- 1262 1263The '{\tt <grace>}' element is defined in \schemafile{note.mod}: 1264\begin{lstlisting}[language=XML] 1265<!-- 1266 The grace element indicates the presence of a grace note. 1267 The slash attribute for a grace note is yes for slashed 1268 eighth notes. The other grace note attributes come from 1269 MuseData sound suggestions. The steal-time-previous attribute 1270 indicates the percentage of time to steal from the previous 1271 note for the grace note. The steal-time-following attribute 1272 indicates the percentage of time to steal from the following 1273 note for the grace note, as for appoggiaturas. The make-time 1274 attribute indicates to make time, not steal time; the units 1275 are in real-time divisions for the grace note. 1276--> 1277<!ELEMENT grace EMPTY> 1278<!ATTLIST grace 1279 steal-time-previous CDATA #IMPLIED 1280 steal-time-following CDATA #IMPLIED 1281 make-time CDATA #IMPLIED 1282 slash %yes-no; #IMPLIED 1283> 1284\end{lstlisting} 1285 1286\sep 1287 1288For example, in \mxmlfile{gracenotes/LilyPondIssue34.xml}, the three grace notes at the beginning of the lower staff are described by:\\ 1289\includegraphics[scale=0.85]{LilyPondIssue34.png} 1290\begin{lstlisting}[language=XML,caption={Grace notes example}] 1291 <note> 1292 <grace/> 1293 <pitch> 1294 <step>A</step> 1295 <octave>2</octave> 1296 </pitch> 1297 <voice>3</voice> 1298 <type>16th</type> 1299 <stem>up</stem> 1300 <staff>2</staff> 1301 <beam number="1">begin</beam> 1302 <beam number="2">begin</beam> 1303 <notations> 1304 <slur type="start" placement="above" number="1"/> 1305 </notations> 1306 </note> 1307 <note> 1308 <grace/> 1309 <pitch> 1310 <step>C</step> 1311 <alter>1</alter> 1312 <octave>3</octave> 1313 </pitch> 1314 <voice>3</voice> 1315 <type>16th</type> 1316 <stem>up</stem> 1317 <staff>2</staff> 1318 <beam number="1">continue</beam> 1319 <beam number="2">continue</beam> 1320 </note> 1321 <note> 1322 <grace/> 1323 <pitch> 1324 <step>E</step> 1325 <octave>3</octave> 1326 </pitch> 1327 <voice>3</voice> 1328 <type>16th</type> 1329 <stem>up</stem> 1330 <staff>2</staff> 1331 <beam number="1">end</beam> 1332 <beam number="2">end</beam> 1333 </note> 1334\end{lstlisting} 1335 1336 1337% ------------------------------------------------------------------------- 1338% ------------------------------------------------------------------------- 1339\section{Ties} 1340% ------------------------------------------------------------------------- 1341% ------------------------------------------------------------------------- 1342 1343\mxml\ makes the distinction between graphics and sound, and this applied to ties: the '{\tt <tie>}' element indicates sound, and the '{\tt <tied>}' element indicates notation. In a '{\tt <tie>}', the '{\tt start}' and '{\tt stop}' values in the '{\tt type}' attribute are used to indicate the beginning and end of the tie. 1344 1345\sep 1346 1347These two elements are defined in \schemafile{note.mod}: 1348\begin{lstlisting}[language=XML] 1349<!ELEMENT tie EMPTY> 1350<!ATTLIST tie 1351 type %start-stop; #REQUIRED 1352 %time-only; 1353\end{lstlisting} 1354 1355\begin{lstlisting}[language=XML] 1356<!ELEMENT tied EMPTY> 1357<!ATTLIST tied 1358 type %tied-type; #REQUIRED 1359 number %number-level; #IMPLIED 1360 %line-type; 1361 %dashed-formatting; 1362 %position; 1363 %placement; 1364 %orientation; 1365 %bezier; 1366 %color; 1367 %optional-unique-id; 1368> 1369\end{lstlisting} 1370 1371 1372% ------------------------------------------------------------------------- 1373% ------------------------------------------------------------------------- 1374\section{Slurs} 1375% ------------------------------------------------------------------------- 1376% ------------------------------------------------------------------------- 1377 1378The '{\tt <slur>}' element is placed inside a '{\tt <notations>}' element, itself placed inside a '{\tt <note>}' element. It is defined in \schemafile{note.mod}: 1379\begin{lstlisting}[language=XML] 1380<!ELEMENT slur EMPTY> 1381<!ATTLIST slur 1382 type %start-stop-continue; #REQUIRED 1383 number %number-level; "1" 1384 %line-type; 1385 %dashed-formatting; 1386 %position; 1387 %placement; 1388 %orientation; 1389 %bezier; 1390 %color; 1391 %optional-unique-id; 1392> 1393\end{lstlisting} 1394 1395 1396% ------------------------------------------------------------------------- 1397% ------------------------------------------------------------------------- 1398\section{Tie and slur example} 1399% ------------------------------------------------------------------------- 1400% ------------------------------------------------------------------------- 1401 1402This example is in \mxmlfile{basic/TieAndSlur.xml}:\\ 1403\includegraphics{TieAndSlur.png} 1404 1405\sep 1406 1407\begin{lstlisting}[language=XML, caption={Tie and slur example}] 1408 <note> 1409 <pitch> 1410 <step>A</step> 1411 <octave>3</octave> 1412 </pitch> 1413 <duration>2</duration> 1414 <type>quarter</type> 1415 <voice>1</voice> 1416 </note> 1417 <note> 1418 <pitch> 1419 <step>B</step> 1420 <alter>-1</alter> 1421 <octave>3</octave> 1422 </pitch> 1423 <duration>1</duration> 1424 <type>eighth</type> 1425 <voice>1</voice> 1426 <accidental>flat</accidental> 1427 <tie type="start" /> 1428 <notations> 1429 <tied type="start" /> 1430 </notations> 1431 </note> 1432 <note> 1433 <pitch> 1434 <step>B</step> 1435 <alter>-1</alter> 1436 <octave>3</octave> 1437 </pitch> 1438 <duration>1</duration> 1439 <type>eighth</type> 1440 <voice>1</voice> 1441 <accidental>flat</accidental> 1442 <tie type="stop" /> 1443 <notations> 1444 <tied type="stop" /> 1445 <slur number="1" type="start" /> 1446 </notations> 1447 </note> 1448 <note> 1449 <pitch> 1450 <step>C</step> 1451 <octave>4</octave> 1452 </pitch> 1453 <duration>1</duration> 1454 <type>eighth</type> 1455 <voice>1</voice> 1456 </note> 1457 <note> 1458 <pitch> 1459 <step>B</step> 1460 <octave>3</octave> 1461 </pitch> 1462 <duration>1</duration> 1463 <type>eighth</type> 1464 <voice>1</voice> 1465 <notations> 1466 <slur number="1" type="stop" /> 1467 </notations> 1468 </note> 1469\end{lstlisting} 1470 1471 1472%% ------------------------------------------------------------------------- 1473%% ------------------------------------------------------------------------- 1474%\section{Harmonies and figured bass} 1475%% ------------------------------------------------------------------------- 1476%% ------------------------------------------------------------------------- 1477% 1478%% ------------------------------------------------------------------------- 1479%\subsection{Harmonies} 1480%% ------------------------------------------------------------------------- 1481% 1482%The '{\tt <harmony>}' element in \mxml\ goes beyond merely displaying harmonies, since it can describe harmonic analysis. i.e. harmonies functions. 1483% 1484%Here is how it is defined in \schemafile{direction.mod}: 1485%\begin{lstlisting}[language=XML] 1486%<!-- 1487% The harmony elements are based on Humdrum's **harm 1488% encoding, extended to support chord symbols in popular 1489% music as well as functional harmony analysis in classical 1490% music. 1491% 1492% If there are alternate harmonies possible, this can be 1493% specified using multiple harmony elements differentiated 1494% by type. Explicit harmonies have all note present in the 1495% music; implied have some notes missing but implied; 1496% alternate represents alternate analyses. 1497% 1498% The harmony object may be used for analysis or for 1499% chord symbols. The print-object attribute controls 1500% whether or not anything is printed due to the harmony 1501% element. The print-frame attribute controls printing 1502% of a frame or fretboard diagram. The print-style entity 1503% sets the default for the harmony, but individual elements 1504% can override this with their own print-style values. 1505% 1506% A harmony element can contain many stacked chords (e.g. 1507% V of II). A sequence of harmony-chord entities is used 1508% for this type of secondary function, where V of II would 1509% be represented by a harmony-chord with a V function 1510% followed by a harmony-chord with a II function. 1511%--> 1512%<!ENTITY % harmony-chord "((root | function), kind, 1513% inversion?, bass?, degree*)"> 1514% 1515%<!ELEMENT harmony ((%harmony-chord;)+, frame?, 1516% offset?, %editorial;, staff?)> 1517%<!ATTLIST harmony 1518% type (explicit | implied | alternate) #IMPLIED 1519% %print-object; 1520% print-frame %yes-no; #IMPLIED 1521% %print-style; 1522% %placement; 1523% %optional-unique-id; 1524%> 1525%\end{lstlisting} 1526% 1527% 1528%% ------------------------------------------------------------------------- 1529%\subsection{Figured bass} 1530%% ------------------------------------------------------------------------- 1531% 1532%The '{\tt <figured-bass>}' element is defined in \schemafile{node.mod} this way: 1533%\begin{lstlisting}[language=XML] 1534%<!-- 1535% Figured bass elements take their position from the first 1536% regular note (not a grace note or chord note) that follows 1537% in score order. The optional duration element is used to 1538% indicate changes of figures under a note. 1539% 1540% Figures are ordered from top to bottom. A figure-number is 1541% a number. Values for prefix and suffix include plus and 1542% the accidental values sharp, flat, natural, double-sharp, 1543% flat-flat, and sharp-sharp. Suffixes include both symbols 1544% that come after the figure number and those that overstrike 1545% the figure number. The suffix values slash, back-slash, and 1546% vertical are used for slashed numbers indicating chromatic 1547% alteration. The orientation and display of the slash usually 1548% depends on the figure number. The prefix and suffix elements 1549% may contain additional values for symbols specific to 1550% particular figured bass styles. The value of parentheses 1551% is "no" if not present. 1552%--> 1553%<!ELEMENT figured-bass (figure+, duration?, %editorial;)> 1554%<!ATTLIST figured-bass 1555% %print-style; 1556% %printout; 1557% parentheses %yes-no; #IMPLIED 1558% %optional-unique-id; 1559%> 1560%<!ELEMENT figure 1561% (prefix?, figure-number?, suffix?, extend?, %editorial;)> 1562%<!ELEMENT prefix (#PCDATA)> 1563%<!ATTLIST prefix 1564% %print-style; 1565%> 1566%<!ELEMENT figure-number (#PCDATA)> 1567%<!ATTLIST figure-number 1568% %print-style; 1569%> 1570%<!ELEMENT suffix (#PCDATA)> 1571%<!ATTLIST suffix 1572% %print-style; 1573%> 1574%\end{lstlisting} 1575 1576 1577% ------------------------------------------------------------------------- 1578% ------------------------------------------------------------------------- 1579\section{Chords} 1580% ------------------------------------------------------------------------- 1581% ------------------------------------------------------------------------- 1582 1583Chords are not evidenced as such in \mxml\ data. Instead, the '{\tt <chord>}' element means that the given note is part of a chord after the first note in the chord has be met. Remember:~\mxml\ is about drawing scores. Put it another way, you know there is a chord {\it only upon its second note}. 1584 1585\sep 1586 1587The code for the last three note chord in \mxmlfile{chords/Chords.xml} is shown below. 1588 1589%\begin{figure} 1590%\caption{Last chord from \mxmlfile{chords/Chords.xml}\mylabel{chords} 1591\includegraphics{Chords.png} 1592 1593\begin{lstlisting}[language=XML, caption={Chord example}] 1594 <note> 1595 <pitch> 1596 <step>B</step> 1597 <octave>4</octave> 1598 </pitch> 1599 <duration>4</duration> 1600 <voice>1</voice> 1601 <type>half</type> 1602 <notations> 1603 <articulations> 1604 <staccato /> 1605 <detached-legato /> 1606 </articulations> 1607 </notations> 1608 </note> 1609 <note> 1610 <chord /> 1611 <pitch> 1612 <step>D</step> 1613 <octave>5</octave> 1614 </pitch> 1615 <duration>4</duration> 1616 <voice>1</voice> 1617 <type>half</type> 1618 </note> 1619 <note> 1620 <chord /> 1621 <pitch> 1622 <step>F</step> 1623 <octave>5</octave> 1624 </pitch> 1625 <duration>4</duration> 1626 <voice>1</voice> 1627 <type>half</type> 1628 </note> 1629\end{lstlisting} 1630%\end{figure} 1631 1632 1633% ------------------------------------------------------------------------- 1634% ------------------------------------------------------------------------- 1635\section{Tuplets} 1636\mylabel{tuplets} 1637% ------------------------------------------------------------------------- 1638% ------------------------------------------------------------------------- 1639 1640The situation for tuplets is different than that of the chords: there is a '{\tt <tuplet>}' element, with a '{\tt type}' attribute to indicate the note upon which it starts and stops: 1641 1642\begin{lstlisting}[language=XML] 1643 <notations> 1644 <tuplet number="1" type="start" /> 1645 </notations> 1646\end{lstlisting} 1647 1648The '{\tt number}' attribute can be used to describe nested tuplets: 1649 1650The contents, i.e. the notes in the tuplet, are not nested in the latter: there are placed in sequence between the two '{\tt <tuplet>}' elements that delimitate the tuplet. 1651 1652\sep 1653 1654Each note in the tuplet has a '{\tt <time-modification>}' element, from the first one on. This element contains two elements: 1655\begin{lstlisting}[language=XML] 1656 <time-modification> 1657 <actual-notes>3</actual-notes> 1658 <normal-notes>2</normal-notes> 1659 </time-modification> 1660\end{lstlisting} 1661 1662One should play '{\tt <actual-notes>}' within the time taken by only '{\tt <normal-notes>}'. The example above is thus that of a triplet. 1663 1664\sep 1665 1666In the case of \mxmlfile{tuplets/Tuplets.xml}, shown below, the duration of the tuplets member is 20 quanta, i.e. 2/3 of a quarter note, whose duration is 30, and the 'display' duration is a quarter note. The duration of the triplet as a whole is that of a half note, i.e. 60 quanta. 1667 1668%\begin{figure} 1669%\caption{First tuplet from \mxmlfile{tuplets/Tuplet.xml}}\mylabel{tuplets} 1670\includegraphics{Tuplets.png} 1671 1672\begin{lstlisting}[language=XML, caption={Tuplet example}] 1673 <divisions>30</divisions> 1674 1675 <!-- ... ... ... ... ... --> 1676 1677 <note> 1678 <pitch> 1679 <step>B</step> 1680 <octave>4</octave> 1681 </pitch> 1682 <duration>20</duration> 1683 <voice>1</voice> 1684 <type>quarter</type> 1685 <time-modification> 1686 <actual-notes>3</actual-notes> 1687 <normal-notes>2</normal-notes> 1688 </time-modification> 1689 <notations> 1690 <tuplet number="1" type="start" /> 1691 </notations> 1692 </note> 1693 <note> 1694 <rest /> 1695 <duration>20</duration> 1696 <voice>1</voice> 1697 <type>quarter</type> 1698 <time-modification> 1699 <actual-notes>3</actual-notes> 1700 <normal-notes>2</normal-notes> 1701 </time-modification> 1702 </note> 1703 <note> 1704 <pitch> 1705 <step>D</step> 1706 <octave>5</octave> 1707 </pitch> 1708 <duration>20</duration> 1709 <voice>1</voice> 1710 <type>quarter</type> 1711 <time-modification> 1712 <actual-notes>3</actual-notes> 1713 <normal-notes>2</normal-notes> 1714 </time-modification> 1715 <notations> 1716 <tuplet number="1" type="stop" /> 1717 </notations> 1718 </note> 1719\end{lstlisting} 1720%\end{figure} 1721 1722 1723% ------------------------------------------------------------------------- 1724% ------------------------------------------------------------------------- 1725\section{Barlines and repeats} 1726% ------------------------------------------------------------------------- 1727% ------------------------------------------------------------------------- 1728 1729Repeats are not described by high-level elements in \mxml. Instead, specific barlines containing a '{\tt <repeat>}' element are used to draw the necessary delimiters. 1730 1731% ------------------------------------------------------------------------- 1732\subsection{Simple barlines} 1733% ------------------------------------------------------------------------- 1734 1735The '{\tt <barline>}' element is defined in \schemafile{barline.mod}. It has two main attributes: 1736%\begin{adjustwidth}{-0.5cm}{-0.5cm} 1737\begin{center} 1738\footnotesize 1739\def \contentsWidth{0.5\textwidth} 1740\def \arraystretch{1.3} 1741% 1742\begin{tabular}[t]{lp{\contentsWidth}} 1743\textbf{Attribute}&\textbf{Meaning} \tabularnewline[0.5ex] 1744\hline\\[-3.0ex] 1745% 1746{\tt bar-style} & Bar-style contains style information. Choices are 1747 '{\tt regular}', '{\tt dotted}', '{\tt dashed}', '{\tt heavy}', '{\tt light-light}', 1748 '{\tt light-heavy}', '{\tt heavy-light}', '{\tt heavy-heavy}', '{\tt tick}' (a 1749 short stroke through the top line), '{\tt short}' (a partial 1750 barline between the 2nd and 4th lines), and '{\tt none}'. 1751 1752 Barlines can occur within measures, as in dotted 1753 barlines that subdivide measures in complex meters; 1754\tabularnewline 1755 1756{\tt location} & If location is '{\tt left}', 1757 it should be the first element in the measure, aside from 1758 the '{\tt print}', '{\tt bookmark}', and '{\tt link}' elements. 1759 1760 If location is 1761 '{\tt right}', it should be the last element, again with the 1762 possible exception of the '{\tt print}', '{\tt bookmark}', and '{\tt link}' 1763 elements. 1764 1765 The value can be '{\tt right}', '{\tt left}' or '{\tt middle}'. 1766 If no location is specified, the default value is '{\tt right}'. 1767\tabularnewline 1768 1769\end{tabular} 1770\end{center} 1771%\end{adjustwidth} 1772 1773%The possible bar styles are defined in \schemafile{barline.mod}: 1774%\begin{lstlisting}[language=XML,caption={Existing bar styles}] 1775%<!-- 1776% Bar-style contains style information. Choices are 1777% regular, dotted, dashed, heavy, light-light, 1778% light-heavy, heavy-light, heavy-heavy, tick (a 1779% short stroke through the top line), short (a partial 1780% barline between the 2nd and 4th lines), and none. 1781%--> 1782%<!ELEMENT bar-style (#PCDATA)> 1783%<!ATTLIST bar-style 1784% %color; 1785%> 1786%\end{lstlisting} 1787% 1788 1789\sep 1790 1791In the '{\tt <bar-style>}' element, '{\tt light}' is a thin vertical line, and '{\tt heavy}'is a thick line. The final barline of a piece is thus represented by: 1792\begin{lstlisting}[language=XML, caption={Final barline}] 1793 <barline location="right"> 1794 <bar-style>light-heavy</bar-style> 1795 </barline> 1796\end{lstlisting} 1797 1798\sep 1799 1800One can see the various simple barlines in \mxmlfile{barlines/SimpleBarlines.xml}:\\ 1801\includegraphics[scale=0.85]{SimpleBarlines.png} 1802 1803% ------------------------------------------------------------------------- 1804\subsection{Repeats} 1805% ------------------------------------------------------------------------- 1806 1807The '{\tt <repeat>}' element in barline can contains these attributes, also defined in \schemafile{barline.mod}: 1808%\begin{adjustwidth}{-0.5cm}{-0.5cm} 1809\begin{center} 1810\footnotesize 1811\def \contentsWidth{0.5\textwidth} 1812\def \arraystretch{1.3} 1813% 1814\begin{tabular}[t]{lp{\contentsWidth}} 1815\textbf{Attribute}&\textbf{Meaning} \tabularnewline[0.5ex] 1816\hline\\[-3.0ex] 1817% 1818{\tt direction} & '{\tt forward}' is used at the start of a repeat, and '{\tt backward}' is used at the end of it; 1819\tabularnewline 1820 1821{\tt times} & indicates how many times the repeated section as to be played; 1822\tabularnewline 1823 1824{\tt winged} & indicates whether has winged extensions that appear above and below the barline, to make them easier to see; 1825 1826The '{\tt straight}' and '{\tt curved}' values represent single wings, while 1827 the '{\tt double-straight}' and '{\tt double-curved}' values represent double 1828 wings. The '{\tt none}' value indicates no wings and is the default. 1829\tabularnewline 1830 1831\end{tabular} 1832\end{center} 1833%\end{adjustwidth} 1834 1835%\begin{lstlisting}[language=XML,caption={Repeats barlines}] 1836%<!-- 1837% Repeat marks. The start of the repeat has a forward direction 1838% while the end of the repeat has a backward direction. Backward 1839% repeats that are not part of an ending can use the times 1840% attribute to indicate the number of times the repeated section 1841% is played. The winged attribute indicates whether the repeat 1842% has winged extensions that appear above and below the barline. 1843% The straight and curved values represent single wings, while 1844% the double-straight and double-curved values represent double 1845% wings. The none value indicates no wings and is the default. 1846%--> 1847%<!ELEMENT repeat EMPTY> 1848%<!ATTLIST repeat 1849% direction (backward | forward) #REQUIRED 1850% times CDATA #IMPLIED 1851% winged (none | straight | curved | 1852% double-straight | double-curved) #IMPLIED 1853%> 1854%\end{lstlisting} 1855% 1856 1857 1858\begin{lstlisting}[language=XML] 1859 <barline location="right"> 1860 <bar-style>light-heavy</bar-style> 1861 <repeat direction="backward" times="5"/> 1862 </barline> 1863\end{lstlisting} 1864 1865\begin{lstlisting}[language=XML] 1866 <barline location="right"> 1867 <bar-style>light-heavy</bar-style> 1868 <repeat direction="backward" winged="none"/> 1869 </barline> 1870\end{lstlisting} 1871 1872\sep 1873 1874 1875% ------------------------------------------------------------------------- 1876\subsection{A repeat example} 1877% ------------------------------------------------------------------------- 1878 1879Here is a simple example in \mxmlfile{repeats/SimpleRepeatWithAnacrusis.xml}:\\ 1880\includegraphics{SimpleRepeatWithAnacrusis.png} 1881\begin{lstlisting}[language=XML] 1882<!-- ... ... ... ... ...--> 1883 <measure number="0" implicit="yes" width="144.60"> 1884 <!-- ... ... ... ... ...--> 1885 <attributes> 1886 <divisions>1</divisions> 1887 <!-- ... ... ... ... ...--> 1888 </attributes> 1889 <note default-x="73.07" default-y="-50.00"> 1890 <pitch> 1891 <step>C</step> 1892 <octave>4</octave> 1893 </pitch> 1894 <duration>1</duration> 1895 <voice>1</voice> 1896 <type>quarter</type> 1897 <stem>down</stem> 1898 </note> 1899 </measure> 1900<!--=========================================================--> 1901 <measure number="1" width="162.29"> 1902 <note default-x="10.00" default-y="-45.00"> 1903 <pitch> 1904 <step>D</step> 1905 <octave>4</octave> 1906 </pitch> 1907 <duration>1</duration> 1908 <voice>1</voice> 1909 <type>quarter</type> 1910 <stem>up</stem> 1911 </note> 1912 <note default-x="76.96" default-y="-40.00"> 1913 <pitch> 1914 <step>E</step> 1915 <octave>4</octave> 1916 </pitch> 1917 <duration>1</duration> 1918 <voice>1</voice> 1919 <type>quarter</type> 1920 <stem>up</stem> 1921 </note> 1922 <barline location="right"> 1923 <bar-style>light-heavy</bar-style> 1924 <repeat direction="backward"/> 1925 </barline> 1926 </measure> 1927<!--=========================================================--> 1928 <measure number="2" width="96.76"> 1929 <note default-x="10.00" default-y="-35.00"> 1930 <pitch> 1931 <step>F</step> 1932 <octave>4</octave> 1933 </pitch> 1934 <duration>1</duration> 1935 <voice>1</voice> 1936 <type>quarter</type> 1937 <stem>up</stem> 1938 </note> 1939 </measure> 1940<!--=========================================================--> 1941 <measure number="3" width="143.60"> 1942 <note default-x="10.00" default-y="-30.00"> 1943 <pitch> 1944 <step>G</step> 1945 <octave>4</octave> 1946 </pitch> 1947 <duration>2</duration> 1948 <voice>1</voice> 1949 <type>half</type> 1950 <stem>up</stem> 1951 </note> 1952 <barline location="right"> 1953 <bar-style>light-heavy</bar-style> 1954 </barline> 1955 </measure> 1956\end{lstlisting} 1957 1958% ------------------------------------------------------------------------- 1959% ------------------------------------------------------------------------- 1960\section{Lyrics} 1961\mylabel{lyrics} 1962% ------------------------------------------------------------------------- 1963% ------------------------------------------------------------------------- 1964 1965% ------------------------------------------------------------------------- 1966\subsection{The '{\tt <lyric>}' element} 1967% ------------------------------------------------------------------------- 1968 1969In \mxml\, the '{\tt <lyrics>}' elements are sub-elements of the '{\tt <note>}' elements. The definition is in \schemafile{note.mod}: 1970\begin{lstlisting}[language=XML] 1971<!ELEMENT lyric 1972 ((((syllabic?, text), 1973 (elision?, syllabic?, text)*, extend?) | 1974 extend | laughing | humming), 1975 end-line?, end-paragraph?, %editorial;)> 1976<!ATTLIST lyric 1977 number NMTOKEN #IMPLIED 1978 name CDATA #IMPLIED 1979 %justify; 1980 %position; 1981 %placement; 1982 %color; 1983 %print-object; 1984 %time-only; 1985 %optional-unique-id; 1986> 1987\end{lstlisting} 1988 1989\sep 1990 1991In lyrics: 1992 1993\begin{itemize} 1994\item word extensions are represented using the '{\tt <extend>}' element; 1995 1996\item hyphenation is indicated by the '{\tt <syllabic>}' element, which can be '{\tt <single>}', 1997 '{\tt <begin>}', '{\tt <end>}', or '{\tt <middle>}'. These represent single-syllable 1998 words, word-beginning syllables, word-ending syllables, 1999 and mid-word syllables, respectively; 2000 2001\item multiple syllables on a single 2002 note are separated by '{\tt <elision>}' elements. A hyphen in the 2003 text element should only be used for an actual hyphenated 2004 word; 2005 2006\item two text elements that are not separated by an 2007 '{\tt <elision>}' element are part of the same syllable, but may have 2008 different text formatting. 2009\end{itemize} 2010 2011\sep 2012 2013The '{\tt <text>}' sub-element contains the text to be sung. It can have attributes controlling the way it is displayed: 2014\begin{lstlisting}[language=XML] 2015<!ELEMENT text (#PCDATA)> 2016<!ATTLIST text 2017 %font; 2018 %color; 2019 %text-decoration; 2020 %text-rotation; 2021 %letter-spacing; 2022 xml:lang NMTOKEN #IMPLIED 2023 %text-direction; 2024> 2025<!ELEMENT syllabic (#PCDATA)> 2026\end{lstlisting} 2027 2028 2029\sep 2030 2031For example, the first note of \mxmlfile{QuemQueritis.xml} contains the single word '{\tt Quem}':\\ 2032\includegraphics{QuemQueritis.png} 2033\begin{lstlisting}[language=XML] 2034 <note> 2035 <pitch> 2036 <step>G</step> 2037 <octave>4</octave> 2038 </pitch> 2039 <duration>2</duration> 2040 <voice>1</voice> 2041 <type>quarter</type> 2042 <stem>up</stem> 2043 <notations> 2044 <slur type="start" number="1"/> 2045 </notations> 2046 <lyric number="1"> 2047 <syllabic>single</syllabic> 2048 <text>Quem</text> 2049 </lyric> 2050 </note> 2051\end{lstlisting} 2052 2053% ------------------------------------------------------------------------- 2054\subsection{Stanzas} 2055% ------------------------------------------------------------------------- 2056 2057Stanzas are not represented in \mxml\ per se, but implicitly: the '{\tt number}' attribute of the '{\tt <lyric>}' element is used to specify the stanza number. 2058 2059\sep 2060 2061For example, in \mxmlfile{lyrics/MultipleStanzas.xml}, the first note (E\raisebox{0.35em}{$\flat$}) of the first chord in the upper staff contains the lyrics for the first syllable of all the successive stanzas, preceded by the stanza number and a dot:\\ 2062\includegraphics{MultipleStanzas.png} 2063\begin{lstlisting}[language=XML,caption={Multiple stanzas example}] 2064 <note default-x="129.06" default-y="-40.00"> 2065 <pitch> 2066 <step>E</step> 2067 <alter>-1</alter> 2068 <octave>4</octave> 2069 </pitch> 2070 <duration>1</duration> 2071 <voice>1</voice> 2072 <type>eighth</type> 2073 <stem>up</stem> 2074 <beam number="1">begin</beam> 2075 <lyric number="1"> 2076 <syllabic>single</syllabic> 2077 <text>1. Sing</text> 2078 </lyric> 2079 <lyric number="2"> 2080 <syllabic>single</syllabic> 2081 <text>2. For</text> 2082 </lyric> 2083 <lyric number="3"> 2084 <syllabic>single</syllabic> 2085 <text>3. No</text> 2086 </lyric> 2087 <lyric number="4"> 2088 <syllabic>single</syllabic> 2089 <text>4. For</text> 2090 </lyric> 2091 <lyric number="5"> 2092 <syllabic>single</syllabic> 2093 <text>5. Death</text> 2094 </lyric> 2095 <lyric number="6"> 2096 <syllabic>begin</syllabic> 2097 <text>6. Je</text> 2098 </lyric> 2099 </note> 2100 <note default-x="129.06" default-y="-30.00"> 2101 <chord/> 2102 <pitch> 2103 <step>G</step> 2104 <octave>4</octave> 2105 </pitch> 2106 <duration>1</duration> 2107 <voice>1</voice> 2108 <type>eighth</type> 2109 <stem>up</stem> 2110 </note> 2111\end{lstlisting} 2112 2113 2114% ------------------------------------------------------------------------- 2115% ------------------------------------------------------------------------- 2116\section{Multiple voices} 2117\mylabel{multipleVoices} 2118% ------------------------------------------------------------------------- 2119% ------------------------------------------------------------------------- 2120 2121Let's look in some detail at the score specified in \mxmlfile{multistaff/MultipleVoicesPerPart.xml}:\\ 2122\includegraphics{MultipleVoicesPerPart.png} 2123 2124\sep 2125 2126The first voice in upper staff '{\tt 1}' has number '{\tt 1}'. The '{\tt <forward>}' element is used because there no note in this voice upon the first beat, whose duration is '{\tt 96}' divisions. This element allows drawing to continue a bit further in the voice, without drawing rests in-between.: 2127\begin{lstlisting}[language=XML] 2128 <forward> 2129 <duration>96</duration> 2130 <voice>1</voice> 2131 <staff>1</staff> 2132 </forward> 2133 <note default-x="154"> 2134 <pitch> 2135 <step>B</step> 2136 <alter>-1</alter> 2137 <octave>4</octave> 2138 </pitch> 2139 <duration>144</duration> 2140 <voice>1</voice> 2141 <type>quarter</type> 2142 <dot/> 2143 <stem default-y="15.5">up</stem> 2144 <staff>1</staff> 2145 </note> 2146 <note default-x="225"> 2147 <pitch> 2148 <step>C</step> 2149 <octave>5</octave> 2150 </pitch> 2151 <duration>48</duration> 2152 <voice>1</voice> 2153 <type>eighth</type> 2154 <stem default-y="18">up</stem> 2155 <staff>1</staff> 2156 </note> 2157\end{lstlisting} 2158 2159\sep 2160 2161The notes in voice '{\tt 2}' in staff '{\tt 1}' can now be described, but only after a '{\tt <backup>}' element that places the "drawing position" back to the beginning of the measure: 2162\begin{lstlisting}[language=XML] 2163 <backup> 2164 <duration>288</duration> 2165 </backup> 2166 <note default-x="108"> 2167 <pitch> 2168 <step>D</step> 2169 <octave>4</octave> 2170 </pitch> 2171 <duration>96</duration> 2172 <voice>2</voice> 2173 <type>quarter</type> 2174 <stem default-y="0.5">up</stem> 2175 <staff>1</staff> 2176 </note> 2177 <note default-x="154"> 2178 <pitch> 2179 <step>F</step> 2180 <octave>4</octave> 2181 </pitch> 2182 <duration>96</duration> 2183 <voice>2</voice> 2184 <type>quarter</type> 2185 <stem default-y="-63">down</stem> 2186 <staff>1</staff> 2187 </note> 2188 <note default-x="201"> 2189 <pitch> 2190 <step>G</step> 2191 <octave>4</octave> 2192 </pitch> 2193 <duration>96</duration> 2194 <voice>2</voice> 2195 <type>quarter</type> 2196 <stem default-y="-60.5">down</stem> 2197 <staff>1</staff> 2198 </note> 2199\end{lstlisting} 2200 2201\page 2202 2203Then comes the specification of voice '{\tt 3}' in staff '{\tt 2}', again after a '{\tt <backup>}' element to place the drawing position at the beginning of the measure: 2204\begin{lstlisting}[language=XML] 2205 <backup> 2206 <duration>288</duration> 2207 </backup> 2208 <note default-x="108"> 2209 <pitch> 2210 <step>B</step> 2211 <alter>-1</alter> 2212 <octave>1</octave> 2213 </pitch> 2214 <duration>96</duration> 2215 <voice>3</voice> 2216 <type>quarter</type> 2217 <stem default-y="5.5">up</stem> 2218 <staff>2</staff> 2219 </note> 2220 <note default-x="154"> 2221 <pitch> 2222 <step>D</step> 2223 <octave>3</octave> 2224 </pitch> 2225 <duration>96</duration> 2226 <voice>3</voice> 2227 <type>quarter</type> 2228 <stem default-y="-55.5">down</stem> 2229 <staff>2</staff> 2230 </note> 2231 <note default-x="201"> 2232 <pitch> 2233 <step>E</step> 2234 <alter>-1</alter> 2235 <octave>3</octave> 2236 </pitch> 2237 <duration>96</duration> 2238 <voice>3</voice> 2239 <type>quarter</type> 2240 <stem default-y="-50.5">down</stem> 2241 <staff>2</staff> 2242 </note> 2243\end{lstlisting} 2244 2245% ------------------------------------------------------------------------- 2246% ------------------------------------------------------------------------- 2247\section{Creating \mxml\ data} 2248% ------------------------------------------------------------------------- 2249% ------------------------------------------------------------------------- 2250 2251This can be done in various ways: 2252\begin{itemize} 2253\item by hand, using a text editor: possible, but unrealistic for usual scores; 2254\item by exporting the score as an \mxml\ text file with a GUI music score editor; 2255\item by scanning a graphics files containing a ready-to-print score, with tools such as PhotoScore Ultimate\texttrademark; 2256\item by programming an application that outputs \mxml\ text. 2257\end{itemize} 2258 2259This author has performed manual text editing on some of the samples supplied with \lib\ in order to perform tests and debug \xmlToLy, but this is a particular case. 2260 2261\sep 2262 2263Exporting to \mxml\ is probably the most frequent way, and there are applications that do a good job at that. If an application supports say strings instruments scordaturas in scores, then creating a '{\tt <scordatura>}' element is not very difficult. 2264 2265\page 2266 2267Scanning graphical scores is a tough problem: how do you tell lyrics from annotations such as '{\tt cresc.}' or tempos such as '{\tt Allegro}'? One usually has to manually fix scanning errors and the category of some text fragments after scanning to get good results. And, of course, the scanning application should create quality \mxml\ data. 2268 2269\sep 2270 2271Creating \mxml\ by an application is a matter of computer programming, and requires software development skills. As an example, \lib\ supplies the necessary tools, and one can obtain: 2272 2273\begin{lstlisting}[language=XML] 2274 <attributes> 2275 <key> 2276 <fifths>-1</fifths> 2277 </key> 2278 </attributes> 2279\end{lstlisting} 2280 2281with C++ code such as: 2282 2283\begin{lstlisting}[language=C++, caption={Creating a '{\tt <key>}' element in an application}] 2284 Sxmlelement attributes = factory::instance().create(k_attributes); 2285 2286 Sxmlelement key = factory::instance().create(k_key); 2287 key->push (newElement(k_fifths, "1")); 2288 attributes->push (key); 2289\end{lstlisting} 2290 2291\sep 2292 2293Here is a score containing random 3-note chords created by \cppsamplefile{RandomChords.cpp}, a C++ small program provided as a example of using \lib\ to create \mxml\ data:\\ 2294\includegraphics{RandomChords.png} 2295 2296 2297% ------------------------------------------------------------------------- 2298% ------------------------------------------------------------------------- 2299\section{Importing \mxml\ data} 2300% ------------------------------------------------------------------------- 2301% ------------------------------------------------------------------------- 2302 2303Many GUI applications provide a way to import \mxml\ data, often with some limitations. We show some of them below. 2304 2305It is worth noting that \muse\ does a good job at issuing warnings if the \mxml\ data is not well-formed according to the DTD. 2306 2307% ------------------------------------------------------------------------- 2308\subsection{Small element, big effect} 2309% ------------------------------------------------------------------------- 2310 2311The '{\tt <harmony>}' element can contain an '{\tt <inversion>}' sub-element to indicate the number of the chord inversion. Some applications ignore this element when importing \mxml\ data, because it takes full knowledge of chords structures to compute the bass note of inverted chords. 2312 2313\sep 2314 2315Here is how \xmlToLy\ handlles the second inversion of the chord in \mxmlfile{harmonies/Inversion.xml}:\\ 2316%\begin{figure} 2317%\caption{Harmony inversion from \mxmlfile{harmonies/Inversion.xml}}\mylabel{inversion} 2318\includegraphics{Inversion.png} 2319 2320\page 2321 2322\begin{lstlisting}[language=XML, caption={Harmony inversion}] 2323 <harmony> 2324 <root> 2325 <root-step>F</root-step> 2326 <root-alter>1</root-alter> 2327 </root> 2328 <kind>major</kind> 2329 <inversion>2</inversion> 2330 </harmony> 2331\end{lstlisting} 2332%\end{figure} 2333 2334% ------------------------------------------------------------------------- 2335\subsection{Elements handled in different ways} 2336% ------------------------------------------------------------------------- 2337 2338Multi-measure rests are specified in \mxml\ with the '{\tt <multiple-rest>}' element. All measures in the sequence have to be explicitly present in the \mxml\ data. 2339 2340\sep 2341 2342For example, the first two measures of \mxmlfile{rests/MultiMeasureRests.xml} are a multi-measure rest, described by: 2343\begin{lstlisting}[language=XML] 2344 <part id="P1"> 2345 <measure number="1"> 2346 <attributes> 2347 <divisions>1</divisions> 2348 <key> 2349 <fifths>0</fifths> 2350 <mode>major</mode> 2351 </key> 2352 <time symbol="common"> 2353 <beats>4</beats> 2354 <beat-type>4</beat-type> 2355 </time> 2356 <clef> 2357 <sign>G</sign> 2358 <line>2</line> 2359 </clef> 2360 <measure-style> 2361 <multiple-rest>2</multiple-rest> 2362 </measure-style> 2363 </attributes> 2364 <note> 2365 <rest/> 2366 <duration>4</duration> 2367 <voice>1</voice> 2368 </note> 2369 </measure> 2370 <!--=======================================================--> 2371 <measure number="2"> 2372 <note> 2373 <rest/> 2374 <duration>4</duration> 2375 <voice>1</voice> 2376 </note> 2377 </measure> 2378 <!--=======================================================--> 2379\end{lstlisting} 2380 2381\sep 2382 2383This file is handled differently by various applications, as can be seen below. 2384 2385\page 2386 2387\muse\ displays it this way:\\ 2388\includegraphics[scale=0.55]{MultiMeasureRestsMuseScore.png} 2389 2390\sep \sep 2391 2392\mxmlToLy\ produces:\\ 2393\includegraphics{MultiMeasureRestsMusicxml2ly.png} 2394 2395\sep \sep 2396 2397\sib\ produces:\\ 2398\includegraphics[scale=0.525]{MultiMeasureRestsSibelius.png} 2399 2400\sep \sep 2401 2402\fin\ produces:\\ 2403\includegraphics[scale=0.8]{MultiMeasureRestsFinale.png} 2404 2405\sep \sep 2406 2407\xmlToLy\ is still experimental, and currently produces:\\ 2408\includegraphics{MultiMeasureRestsXml2ly.png} 2409 2410\page 2411 2412% ------------------------------------------------------------------------- 2413\subsection{Elements often not well handled} 2414% ------------------------------------------------------------------------- 2415 2416There are elements that are not displayed in a "standard" way by the usual music score editors. One of them is the '{\tt <beat-repeat>}', found for example in \mxmlfile{repeats/BeatRepeat.xml}. 2417 2418\sep 2419 2420\muse, \mxmlToLy, \xmlToLy\ and \sib\ produce the following, i.e. they ignore the beat repeat altogether:\\ 2421\includegraphics{BeatRepeatXml2ly.png} 2422 2423\fin\ produces:\\ 2424\includegraphics[scale=0.8]{BeatRepeatFinale.png}. 2425 2426And if one exports that score from \fin\ to \mxml, the beat repeat information is lost, see \mxmlfile{repeats/BeatRepeatExportedFromFinale.xml}. 2427 2428% ------------------------------------------------------------------------- 2429\subsection{Elements usually not handled} 2430% ------------------------------------------------------------------------- 2431 2432There are elements that are not displayed by the usual music score editors, because there is no "standard" way to do so. One of them is the scordatura used on string instrument. 2433 2434\sep 2435 2436For example, the scordatura in \mxmlfile{strings/Scordatura.xml} is the case where the sixth string of the guitar is tuned a tone down to D, which can be described by:\\ 2437\includegraphics{Scordatura.png} 2438 2439\begin{lstlisting}[language=XML, caption={Scordatura example}] 2440 <scordatura> 2441 <accord string="6"> 2442 <tuning-step>D</tuning-step> 2443 <tuning-alter>0</tuning-alter> 2444 <tuning-octave>3</tuning-octave> 2445 </accord> 2446 <accord string="5"> 2447 <tuning-step>A</tuning-step> 2448 <tuning-alter>0</tuning-alter> 2449 <tuning-octave>3</tuning-octave> 2450 </accord> 2451 <accord string="4"> 2452 <tuning-step>D</tuning-step> 2453 <tuning-alter>0</tuning-alter> 2454 <tuning-octave>4</tuning-octave> 2455 </accord> 2456 <accord string="3"> 2457 <tuning-step>G</tuning-step> 2458 <tuning-alter>0</tuning-alter> 2459 <tuning-octave>4</tuning-octave> 2460 </accord> 2461 <accord string="2"> 2462 <tuning-step>B</tuning-step> 2463 <tuning-alter>0</tuning-alter> 2464 <tuning-octave>4</tuning-octave> 2465 </accord> 2466 <accord string="1"> 2467 <tuning-step>E</tuning-step> 2468 <tuning-alter>0</tuning-alter> 2469 <tuning-octave>5</tuning-octave> 2470 </accord> 2471 </scordatura> 2472\end{lstlisting} 2473 2474 2475% ------------------------------------------------------------------------- 2476\subsection{A real challenge} 2477% ------------------------------------------------------------------------- 2478 2479The file \mxmlfile{challenging/BeethovenNinthSymphony.xml} is over 66 megabytes large -- it contains the whole score for this symphony. 2480 2481\sep 2482 2483The interested reader is urged to try and import this file into their favorite score editing sofware. This author's experience is that: 2484\begin{itemize} 2485\item \sib\ handles it alright; 2486\item \fin\ finds it well-formed, but too big to be opened; 2487\item \muse\ opens it, but then working on the file is extremely slow; 2488\item \mxmlToLy\ converts it to \lily\ syntax as of 2.19.83, and the result has some issues that should be fixed rather easily; 2489\item \xmlToLy\ converts it to \lily\ alright, but the issues in the \lcg\ show that this converter is still experimental\dots 2490\end{itemize} 2491 2492 2493% ------------------------------------------------------------------------- 2494% ------------------------------------------------------------------------- 2495\section{Conclusion} 2496% ------------------------------------------------------------------------- 2497% ------------------------------------------------------------------------- 2498 2499\mxml\ supports other score elements such as harmonies and figured bass, as well as nested repeats. There is a lot of information about \mxml\ on the Internet. And of course, plenty of targeted, ready-to-use examples can be found in \subdir{files/samples/musicxml}. 2500 2501\mxml\ has become a de facto standard for music scores data interchange between applications. The way it is exported and imported by the various applications is quite diverse though, and manual editing of the result is to be expected after import. 2502 2503\sep 2504 2505\mxml\ is not the whole story, though. The W3C Music Notation Community Group is working on MNX (\url{https://w3c.github.io/mnx}), as a successor to \mxml. One part of it is MNX-Common, which aims at being less verbose and more semantics-oriented than \mxml. 2506 2507\sep 2508 2509For example, consider: 2510\begin{lstlisting}[language=XML] 2511<score-partwise version="3.1"> 2512 <part-list> 2513 <score-part id="P1"> 2514 <part-name>Music</part-name> 2515 </score-part> 2516 </part-list> 2517 <part id="P1"> 2518 <measure number="1"> 2519 <attributes> 2520 <divisions>1</divisions> 2521 <key> 2522 <fifths>0</fifths> 2523 </key> 2524 <time> 2525 <beats>4</beats> 2526 <beat-type>4</beat-type> 2527 </time> 2528 <clef> 2529 <sign>G</sign> 2530 <line>2</line> 2531 </clef> 2532 </attributes> 2533 <note> 2534 <pitch> 2535 <step>C</step> 2536 <octave>4</octave> 2537 </pitch> 2538 <duration>4</duration> 2539 <type>whole</type> 2540 </note> 2541 </measure> 2542 </part> 2543</score-partwise> 2544\end{lstlisting} 2545 2546\sep 2547 2548In MNX-Common, this can be written in a more concise way: 2549\begin{lstlisting}[language=XML,caption={MNX-Common example}] 2550<mnx> 2551 <score> 2552 <mnx-common profile="standard"> 2553 <global> 2554 <measure> 2555 <directions> 2556 <time signature="4/4"/> 2557 </directions> 2558 </measure> 2559 </global> 2560 <part> 2561 <part-name>Music</part-name> 2562 <measure barline="regular"> 2563 <sequence> 2564 <directions> 2565 <clef sign="G" line="2"/> 2566 </directions> 2567 <event value="/1"> 2568 <note pitch="C4"/> 2569 </event> 2570 </sequence> 2571 </measure> 2572 </part> 2573 </mnx-common> 2574 </score> 2575</mnx> 2576\end{lstlisting} 2577 2578\sep 2579 2580Let's conclude with a tribute to the manual score engravers, whose skills have produced so many beautiful scores for centuries! Reaching the quality of their work is still a challenge for current music scoring software. 2581 2582 2583% ------------------------------------------------------------------------- 2584% ------------------------------------------------------------------------- 2585% postamble 2586% ------------------------------------------------------------------------- 2587% ------------------------------------------------------------------------- 2588 2589\pagebreak 2590 2591\lstlistoflistings 2592 2593%\listoffigures 2594 2595\tableofcontents 2596 2597% ------------------------------------------------------------------------- 2598\end{document} 2599% ------------------------------------------------------------------------- 2600
