The Music Encoding Initiative (MEI) is an open-source effort to define a system for encoding musical documents in a machine-readable structure. MEI brings together specialists from various music research communities, including technologists, librarians, historians, and theorists in a common effort to define best practices for representing a broad range of musical documents and structures. The results of these discussions are formalized in the MEI Source and customizations, a core set of rules for recording physical and intellectual characteristics of music notation documents expressed in TEI’s ODD language (One Document Does-it-all, cf. amongst others: Viglianti, 2019). As such, the MEI Source contains both, the specifications that can be compiled to schema formats for validating XML files, and documentation in prose, the MEI Guidelines, which provide detailed explanations of the components of the MEI model and best practices suggestions.
The MEI Source is not a schema in itself; rather, it can be used to build customized schemas, such as mei-CMN, mei-Mensural, mei-all, etc. (also see Customizing MEI). This repository already includes several customizations. While these can form an ideal starting point for creating your own customizations, you should also understand customization and building processes.
In this document, you will learn how to contribute to the development of MEI by building the schema and guidelines (you should also consider consulting the tutorial on "Understanding ODD"). For the pre-built schemas of the latest release of MEI, please consult the "schemas" section of the music-encoding website.
This repository contains all the source code of the MEI Schema and Guidelines:
- .github: Configuration files for GitHub Actions workflows.
- customizations: TEI ODD files that allow you to build customized MEI schemata.
- source: Contains the source code, as expressed in TEI ODD. This includes the source code for the MEI Guidelines and the MEI schema modules.
- submodules: A container for Git Submodules: third-party developments that are needed, e.g., for building this repository's contents, but which are not part of our codebase.
- tests: Unit tests for the MEI Schemata.
- utils: Helper scripts e.g. for compiling schemata and guidelines from this repository.
Important
For the sake of the continuous integration (CI) workflow, the build artifacts of the schemata and guidelines are no longer included in this repository, but are generated on every commit to the develop branch and automatically pushed to their dedicated repositories. For more information please see the section Additional Resources below.
Nevertheless, it is possible to build any customization locally in your working copy of this repository.
One of the core strengths of the MEI Schema is that it allows an individual to validate an MEI file against an XML Schema to ensure the MEI file conforms to expected encodings and behaviors. To validate an MEI file you need an XML validation engine. XML Authoring tools, such as oXygen, might have built-in validation tools. There are also several command line utilities, including xmllint and jing.
For example, you might validate an MEI file from the sample-encodings project using the xmllint command line tool:
xmllint --noout --relaxng schemata/mei-CMN.rng "sample-encodings/MEI 3.0/Music/Complete\ examples/Bach_Ein_festeBurg.mei"Or, the same command using jing.
jing schemata/mei-CMN.rng "sample-encodings/MEI 3.0/Music/Complete\ examples/Bach_Ein_festeBurg.mei"The MEI model may be customized to express and validate different types of music documents. Customizations are configured with individual ODD files. This repository already includes several customizations:
- mei-CMN: Validates MEI files that express common Western music notation.
- mei-Mensural: Validates MEI files that express white Mensural notation (will raise validation errors if elements like "measure" exist in the MEI encoding).
- mei-Neumes: Validates MEI files that express Neume notation (like Mensural, will raise validation errors if elements that are not part of neume notation exist in an encoding.)
- mei-all: The full MEI Schema. This is the most permissive customization of MEI.
- mei-all_anyStart: A customization of mei-all, allowing every MEI element as the root element.
- mei-basic: The purpose of mei-Basic is to serve as common ground for data interchange, both between projects using different profiles of MEI, and other encoding schemes
For those who are used to having a single DTD or W3C Schema to validate music notation encodings, the customization process may seem to be a complex way of arriving at a schema to validate music notation. However, customizations are a vital part of the expressive power of MEI, and when used to their full extent, can assist organizations in ensuring the integrity and validity of their data.
When designing a music encoding system there are many contradictory and non-standardized practices associated with writing music notation. Different repertoires may have extremely different ways of expressing pitch or rhythm; for example, rhythm in Mensural notation is incompatible with the later systems developed in common Western notation.
Most attempts at addressing this complexity restrict a schema to only a certain subset of music notation and do not attempt to accurately represent the semantics of music notation that falls outside of its defined scope. So, for example, a system designed for common Western notation that depends on the existence of measures, duration, note shapes, or even staves, cannot semantically represent notations that do not have these features.
The MEI takes a different approach. With the customization system, schemas may be generated from an existing ‘library’ of well-defined musical behaviors, but each behavior may be mixed and matched according to the needs of the notation. In this sense, the MEI source functions more as a ‘library’ of music encoding tools by which many different types of notation can be expressed and not just a single monolithic schema.
The build process of MEI can produce several artifacts, as listed below. Depending on what artifacts you want to build, the build system has to meet additional requirements.
| Artifacts | Technologies | Tools |
|---|---|---|
| Compiled ODD | XInclude, XSLT 3.0 | Saxon HE with Xerces |
| Schemata | XInclude, XSLT 3.0 | Saxon HE with Xerces |
| Guidelines HTML | XInclude, XSLT 3.0, MEI to SVG | Saxon HE with Xerces, Verovio Toolkit |
| Guidelines PDF | XInclude, XSLT 3.0, MEI to SVG, HTML to PDF | Saxon HE with Xerces, Verovio Toolkit, Prince XML |
While it is possible to build the artifacts with other tools, the above are tested and thus recommended. Moreover, we try to support the building process on the most common operating systems (Microsoft Windows, Apple macOS and Linux), and currently have the following documented ways of building the artifacts:
- command line: If your build system meets the prerequisites as described in Building MEI on the command line, you can build the artifacts natively.
- Docker: MEI maintains a Docker image that meets all the prerequisites and can be used for building the artifacts via the command line. How to use the Docker image is described in the README of the docker-mei repository.
- oXygen XML Editor: When the command line is not your preferred tool and you do not want to build the Guidelines PDF, you might consider using alternative environments, such as Synchrosoft’s oXygen XML software family. A description of how to set up corresponding transformation scenarios can be found in Building MEI with oXygen XML Editor.
A live version of the MEI Guidelines is available on the MEI Website in the ’Documentation‘ menu:
In addition to the source files for MEI in this repository, there are other useful resources in other MEI repositories. The prebuilt release and development versions of:
- MEI Schema files: https://github.com/music-encoding/schema
- MEI Guidelines: https://github.com/music-encoding/guidelines
And moreover
- MEI Sample Encodings: https://github.com/music-encoding/sample-encodings
- MEI Encoding Tools: tools for modifying MEI files and conversion of MEI to/from other encoding formats https://github.com/music-encoding/encoding-tools
- Viglianti, R. (2019). One Document Does-it-all (ODD): A language for documentation, schema generation, and customization from the Text Encoding Initiative. Symposium on Markup Vocabulary Customization, Washington, DC. https://doi.org/10.4242/BalisageVol24.Viglianti01
Copyright 2017–2024 by the Music Encoding Initiative (MEI) Board (formerly known as "MEI Council")
Licensed under the Educational Community License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://opensource.org/licenses/ECL-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
This is a derivative work based on earlier versions of the schema © 2001–2006 Perry Roland and the Rector and Visitors of the University of Virginia; licensed under the Educational Community License version 1.0.
CONTACT: info@music-encoding.org