====== Introduction to MEI and XML Schema ======

===== Why MEI? =====

The **Music Encoding Initiative (MEI)** is a framework for representing music notation in a structured, machine-readable way. It is based on **XML**, which means that MEI files are plain text files with a clear hierarchical structure.

For musicologists, this is useful because it allows us to:
  * describe notation precisely
  * document editorial decisions
  * process musical data computationally
  * validate encodings automatically
  * exchange data between tools and projects

For the official documentation, see the [[https://music-encoding.org/guidelines/v5/content/introduction.html|MEI Guidelines: Introduction]].

===== Very short version =====

You can think of MEI like this:

  * **music notation** = the thing we want to describe
  * **XML** = the language used to write that description
  * **schema** = the rulebook that says what is allowed
  * **MEI** = a music-specific XML vocabulary

So MEI is not "just XML".  
It is a **specialized XML language for music notation**.

===== What is XML? =====

XML stands for **eXtensible Markup Language**.

For absolute beginners, the easiest way to understand XML is:

> XML is a way of writing structured information using labeled elements.

Example:

<code xml>
<note pname="c" oct="4" dur="4"/>
</code>

This means:
  * the element is called ''note''
  * it has a pitch name: ''c''
  * it has an octave: ''4''
  * it has a duration: ''4''

XML is made of **elements** and **attributes**.

==== Elements ====

Elements are the named building blocks, for example:
  * ''<measure>''
  * ''<staff>''
  * ''<layer>''
  * ''<note>''
  * ''<rest>''

Some elements have opening and closing tags:

<code xml>
<measure>
  ...
</measure>
</code>

Some are empty and written in a short form:

<code xml>
<note pname="c" oct="4" dur="4"/>
</code>

==== Attributes ====

Attributes add information to an element.

Example:

<code xml>
<note pname="f" oct="5" dur="2"/>
</code>

Here:
  * ''pname'' = pitch name
  * ''oct'' = octave
  * ''dur'' = duration

A useful beginner distinction is:

  * **element** = what kind of thing this is
  * **attribute** = extra information about that thing

===== What is a schema? =====

A **schema** is a set of rules for an XML language.

For beginners, the most useful mental model is:

> A schema is like a grammar or rulebook for XML.

It tells us things like:
  * which elements are allowed
  * where they are allowed
  * which attributes they may have
  * which values are valid

Without a schema, you could write almost anything.
With a schema, a computer can check whether your file follows the rules.

So a schema helps answer questions like:
  * Is a ''<note>'' allowed here?
  * May a ''<measure>'' contain a ''<staff>''?
  * Is ''pname="h"'' valid?
  * Does this link point to an existing element?

===== Why schema matters =====

For editorial and research work, schema is important because it helps us avoid errors.

It can catch problems such as:
  * invalid element names
  * misplaced elements
  * missing required information
  * invalid attribute values
  * broken references

So schema validation is one of the reasons MEI is useful in scholarly work:
  * it makes encodings more consistent
  * it makes collaboration safer
  * it improves interoperability

===== How this works in MEI =====

MEI is an XML-based encoding framework.  
Its rules are not invented separately by each project. Instead, MEI defines a structured vocabulary for music notation.

For beginners, the important point is simply:

  * XML gives the syntax
  * MEI gives the music-specific elements and attributes
  * the schema checks whether the encoding is valid

===== A very simple MEI example =====

<code xml>
<measure n="1">
  <staff n="1">
    <layer n="1">
      <note pname="c" oct="4" dur="4"/>
      <note pname="d" oct="4" dur="4"/>
      <note pname="e" oct="4" dur="4"/>
      <note pname="f" oct="4" dur="4"/>
    </layer>
  </staff>
</measure>
</code>

You can read this as:

  * one measure
  * containing one staff
  * containing one layer
  * containing four notes

===== Basic structure in MEI =====

A very common beginner structure is:

<code>
score
└── section
    └── measure
        └── staff
            └── layer
                └── note / rest / chord / etc.
</code>

A practical way to understand this is:

  * ''score'' = the whole musical object
  * ''measure'' = one bar
  * ''staff'' = one staff in that measure
  * ''layer'' = one musical stream or voice on that staff
  * ''note'' = one event inside that layer

===== Score definition and staff definition =====

Two important elements are:

  * ''<scoreDef>''
  * ''<staffDef>''

These do not usually encode the individual notes themselves.
Instead, they define the notational environment.

You can think of them like this:

  * ''scoreDef'' = settings that can apply to the whole score
  * ''staffDef'' = settings for a particular staff

These are often used for things such as:
  * clef
  * key signature
  * meter
  * staff properties

A useful beginner idea is that these elements often act like **defaults**:
they remain in force until they are changed later.

===== Basic notation in MEI =====

===== Notes =====

In Common Music Notation (CMN), MEI defines a note through three basic parameters:

  * ''pname'' = pitch name
  * ''oct'' = octave
  * ''dur'' = duration

Example:

<code xml>
<note pname="c" oct="4" dur="4"/>
</code>

This means:
  * pitch name = C
  * octave = 4
  * duration = quarter note

===== Pitch =====

Pitch in beginner MEI examples is usually encoded with:
  * ''pname''
  * ''oct''

Example:

<code xml>
<note pname="g" oct="5" dur="2"/>
</code>

This means G5 as a half note.

So the basic pitch information is split into:
  * note name
  * octave

===== Accidentals =====

A written accidental can be encoded with the ''accid'' attribute.

Example:

<code xml>
<note pname="f" oct="4" dur="4" accid="s"/>
</code>

This means an F sharp quarter note.

For beginners, the important idea is:

  * ''pname'' gives the diatonic pitch name
  * ''accid'' adds the written accidental

In other words:
  * ''pname="f"'' = F
  * ''accid="s"'' = sharp sign written on that note

===== Duration =====

Duration is encoded with ''dur''.

Common beginner values include:

  * ''1'' = whole note
  * ''2'' = half note
  * ''4'' = quarter note
  * ''8'' = eighth note

Example:

<code xml>
<note pname="a" oct="4" dur="8"/>
</code>

===== Measures =====

Measures are encoded with ''<measure>''.

Example:

<code xml>
<measure n="12">
  ...
</measure>
</code>

Here:
  * ''measure'' identifies the bar
  * ''n'' stores the measure number or label

The measure acts as a container for the musical material belonging to that bar.

===== Staves and layers =====

Inside a measure, notes are usually organized through:
  * ''<staff>''
  * ''<layer>''

Example:

<code xml>
<measure n="1">
  <staff n="1">
    <layer n="1">
      <note pname="c" oct="4" dur="4"/>
    </layer>
  </staff>
</measure>
</code>

For beginners:
  * ''staff'' tells us which staff this is
  * ''layer'' tells us which musical stream or voice on that staff

===== Key signatures =====

Key signatures are generally defined at the score or staff level, often through:
  * ''<scoreDef>''
  * ''<staffDef>''
  * the ''keysig'' attribute

Example:

<code xml>
<scoreDef keysig="1s"/>
</code>

A beginner reading of this is:
  * ''keysig'' stores the written key signature
  * ''1s'' means one sharp

Similarly:

<code xml>
<scoreDef keysig="2f"/>
</code>

means two flats.

For beginners it is enough to understand that:
  * the key signature is usually a **context-setting property**
  * it applies to the following music until changed

===== Meter =====

Meter is also typically defined in ''scoreDef'' or ''staffDef''.

The most common beginner attributes are:
  * ''meter.count'' = top number
  * ''meter.unit'' = bottom number

Example:

<code xml>
<scoreDef meter.count="4" meter.unit="4"/>
</code>

This means 4/4.

Another example:

<code xml>
<scoreDef meter.count="3" meter.unit="8"/>
</code>

This means 3/8.

===== Clef =====

Clefs are usually part of the score or staff definition as well.

Typical attributes are:
  * ''clef.shape''
  * ''clef.line''

Example:

<code xml>
<staffDef n="1" clef.shape="G" clef.line="2"/>
</code>

This gives a treble clef on line 2.

===== Why ''xml:id'' is especially important =====

One of the most important attributes in MEI is:

<code>
xml:id
</code>

This gives an element a **unique identifier** inside the document.

Example:

<code xml>
<note pname="g" oct="4" dur="4" xml:id="n42"/>
</code>

The key idea is:

> ''xml:id'' gives this exact note its own identity.

That matters because other elements can refer to it.

===== What ''xml:id'' does =====

For beginners, ''xml:id'' does three important things:

  * it makes an element uniquely identifiable
  * it allows linking
  * it helps keep references stable

This is especially useful when we want to say:
  * a dynamic starts at this note
  * a slur begins here and ends there
  * this annotation belongs to that symbol
  * this facsimile zone corresponds to this note

===== Example: linking a dynamic to a note =====

<code xml>
<measure n="10">
  <staff n="1">
    <layer n="1">
      <note pname="f" oct="4" dur="4"/>
      <note pname="g" oct="4" dur="4" xml:id="n10_2"/>
      <note pname="a" oct="4" dur="4"/>
      <note pname="c" oct="5" dur="4"/>
    </layer>
  </staff>

  <dynam startid="#n10_2">f</dynam>
</measure>
</code>

Here:
  * the second note has ''xml:id="n10_2"''
  * the dynamic uses ''startid="#n10_2"''
  * the ''#'' means "point to the element with this id"

So the dynamic is explicitly attached to that note.

===== Why this is important in editorial work =====

For editorial and analytical work, ''xml:id'' is crucial because it lets us refer to specific musical objects.

That is important when:
  * encoding slurs, ties, dynamics, and other control elements
  * linking notation to facsimile zones
  * attaching annotations
  * documenting editorial intervention
  * aligning musical data across tools

In practical terms:
  * the note is no longer just "the third note in bar 10"
  * it becomes a uniquely addressable object

===== A helpful mental model =====

A good beginner analogy is:

  * the element itself is the musical object
  * ''xml:id'' is its name tag
  * another element can point to that name tag

Without ''xml:id'', references are harder.
With ''xml:id'', you can point exactly to one specific note or symbol.

===== Do all notes need ''xml:id''? =====

Not always.

In principle, a note can be encoded without ''xml:id''.

Example:

<code xml>
<note pname="c" oct="4" dur="4"/>
</code>

But as soon as you want to point to that note from elsewhere, a unique identifier becomes extremely useful, and often necessary in practice.

For editorial workflows, it is often a very good idea to assign stable ''xml:id'' values systematically.

===== Beginners should remember these core ideas =====

  * MEI is an XML language for music notation
  * XML consists of elements and attributes
  * a schema is the rulebook for valid XML
  * notes in MEI are often defined by ''pname'', ''oct'', and ''dur''
  * measures group the music into bars
  * ''scoreDef'' and ''staffDef'' define context such as clef, key, and meter
  * ''xml:id'' gives a specific element a unique identity
  * other elements can point to that identity using attributes like ''startid'' and ''endid''

===== Minimal example bringing things together =====

The following snippet shows the core musical logic of notes, accidentals, meter, key signature, and ''xml:id''.

However, it is still only a score fragment.  
A complete MEI document usually requires a larger outer structure, which is explained in the next section.

<code xml>
<score>
  <scoreDef keysig="1s" meter.count="4" meter.unit="4"/>
  <section>
    <measure n="1">
      <staff n="1">
        <layer n="1">
          <note pname="g" oct="4" dur="4" xml:id="m1n1"/>
          <note pname="a" oct="4" dur="4" accid="s" xml:id="m1n2"/>
          <note pname="b" oct="4" dur="4" xml:id="m1n3"/>
          <note pname="c" oct="5" dur="4" xml:id="m1n4"/>
        </layer>
      </staff>
      <dynam startid="#m1n2">f</dynam>
    </measure>
  </section>
</score>
</code>

This example shows:
  * a score definition with key and meter
  * one measure
  * one staff
  * one layer
  * notes with pitch, octave, and duration
  * one accidental
  * unique ''xml:id'' values
  * a dynamic linked to a specific note

===== The overall structure of a complete MEI file =====

So far, many examples in this introduction have shown only small fragments, such as a single measure or a short score passage.

That is useful for learning individual elements, but it is important to understand that a **complete MEI file** normally needs a larger structure around those fragments.

A beginner should think of MEI on two levels:

  * **document level** = the whole file
  * **music level** = the encoded notation inside the file

===== The usual top-level structure =====

A normal MEI document usually has this overall form:

<code>
mei
├── meiHead
└── music
    └── body
        └── mdiv
            └── score
                └── section
                    └── measure
                        └── staff
                            └── layer
                                └── note / rest / chord / etc.
</code>

This can be read as:

  * ''<mei>'' = the whole MEI document
  * ''<meiHead>'' = metadata about the document
  * ''<music>'' = the musical content
  * ''<body>'' = the main musical body
  * ''<mdiv>'' = a musical division, for example a movement or other large unit
  * ''<score>'' = the score representation
  * ''<section>'' = a segment of music
  * ''<measure>'' = one measure
  * ''<staff>'' = one staff
  * ''<layer>'' = one layer or voice stream
  * ''<note>'' = one musical event

===== Why the earlier example was incomplete =====

This earlier example:

<code xml>
<score>
  <scoreDef keysig="1s" meter.count="4" meter.unit="4"/>
  <section>
    <measure n="1">
      <staff n="1">
        <layer n="1">
          <note pname="g" oct="4" dur="4" xml:id="m1n1"/>
          <note pname="a" oct="4" dur="4" accid="s" xml:id="m1n2"/>
          <note pname="b" oct="4" dur="4" xml:id="m1n3"/>
          <note pname="c" oct="5" dur="4" xml:id="m1n4"/>
        </layer>
      </staff>
      <dynam startid="#m1n2">f</dynam>
    </measure>
  </section>
</score>
</code>

is useful as a **score fragment**, but it is not yet a complete MEI document.

In practice, tools such as Verovio often expect a fuller MEI wrapper around the score data.

===== A fuller MEI example =====

The following example shows the same musical idea inside a more complete MEI structure:

<code xml>
<mei xmlns="http://www.music-encoding.org/ns/mei" meiversion="5.1">
  <meiHead>
    <fileDesc>
      <titleStmt>
        <title>Minimal MEI example</title>
      </titleStmt>
      <pubStmt/>
    </fileDesc>
  </meiHead>

  <music>
    <body>
      <mdiv>
        <score>
          <scoreDef keysig="1s" meter.count="4" meter.unit="4">
            <staffGrp>
              <staffDef n="1" lines="5" clef.shape="G" clef.line="2"/>
            </staffGrp>
          </scoreDef>

          <section>
            <measure n="1">
              <staff n="1">
                <layer n="1">
                  <note pname="g" oct="4" dur="4" xml:id="m1n1"/>
                  <note pname="a" oct="4" dur="4" accid="s" xml:id="m1n2"/>
                  <note pname="b" oct="4" dur="4" xml:id="m1n3"/>
                  <note pname="c" oct="5" dur="4" xml:id="m1n4"/>
                </layer>
              </staff>
              <dynam startid="#m1n2">f</dynam>
            </measure>
          </section>
        </score>
      </mdiv>
    </body>
  </music>
</mei>
</code>

**Important:** In a normal five-line staff, ''<staffDef>'' should usually include ''lines="5"''.
Without this, some renderers may not display the staff correctly.

You can try to render this score yourself via [[https://editor.verovio.org/|Verovio Editor]]

===== How to read this complete example =====

This example now includes the parts that were missing before:

  * ''<mei>'' as the document root
  * ''xmlns'' to declare the MEI XML namespace
  * ''meiversion'' to indicate the MEI version
  * ''<meiHead>'' for metadata
  * ''<music>'' for the musical content
  * ''<body>'' and ''<mdiv>'' as structural containers around the score
  * ''<scoreDef>'' and ''<staffDef>'' to define the notational context

Only inside this larger wrapper do we get to the actual note material.

===== The role of ''meiHead'' =====

The ''<meiHead>'' element contains metadata.

For beginners, it is enough to understand that this is where information about the encoded object and the encoding can be stored, for example:
  * title
  * source information
  * editorial responsibility
  * encoding notes
  * revision history

In small teaching examples, the header may be very short.
In research projects, it can become much more detailed.

===== The role of ''body'' and ''mdiv'' =====

Inside ''<music>'', the musical content is usually placed inside ''<body>''.

Inside the body, ''<mdiv>'' represents a musical division.
Depending on the source, this may represent:
  * a whole piece
  * a movement
  * an act
  * a scene
  * another large formal division

For simple teaching examples, one ''<mdiv>'' is usually enough.

===== A practical beginner rule =====

When writing MEI for testing or rendering, it is safest to think in this order:

  - start with ''<mei>''
  - add ''<meiHead>''
  - add ''<music>''
  - inside music, add ''<body>''
  - inside body, add ''<mdiv>''
  - inside mdiv, add ''<score>''
  - inside score, add ''<scoreDef>'' and ''<section>''
  - inside section, add measures, staves, layers, and notes

This avoids the impression that a musical fragment by itself is already a complete MEI file.

===== Simplified memory aid =====

A useful memory formula is:

  * **MEI document** = metadata + music
  * **music** = body + divisions + score content
  * **score content** = sections + measures + staves + layers + events


===== Reference =====

For the official reference documentation, see:
  * [[https://music-encoding.org/guidelines/v5/content/introduction.html|MEI Guidelines: Introduction]]