jMEI

Java bindings for the Music Encoding Initiative (MEI). MEI is a document schema for encoding many different musical notation formats. More information can be found at http://music-encoding.org

Author

Written by Alastair Porter, based on ideas from libmei

Compilation / Installation

jMEI uses Maven. To compile, simply

mvn package

and grab the file built to target/

If you want to use this file in another maven project you can run mvn install and use the following dependency block:

    <dependency>
        <groupId>ca.mcgill.music.ddmal</groupId>
        <artifactId>jmei</artifactId>
        <version>0.1</version>
    </dependency>

Usage

jMEI closely follows the XML DOM, so provides a number of object creation and manipulation methods that are inspired from XML.

See the example file in src/main/example for a running demo of these features.

Create a Document, and add a root element to it

MeiDocument d = new MeiDocument();
MeiElement root = new MeiElement("mei");
d.setRootElement(root);

Create elements and add attributes to them

MeiElement note = new MeiElement("note");
note.addAttribute("pname", "c");

// If you need to add an attribute with a different namespace,
// you can do it manually
MeiNamespace ns = new MeiNamespace("http://www.w3.org/1999/xlink", "xlink");
MeiAttribute a = new MeiAttribute(ns, "title", "My image");
MeiElement graphic = new MeiElement("graphic");
graphic.addAttribute(a);

Add elements as children

root.addChild(note);
root.addChild(graphic);

Access ID information

// jmee automatically makes an ID for you. It's stored in the xml:id
//  attribute of the tag.
MeiElement n1 = new MeiElement("note");
String n1Id = n1.getId();
MeiElement n2 = new MeiElement("note");
String n2Id = n2.getId();

MeiElement tie = new MeiElement("tie");
tie.addAttribute("startid", n1Id);
tie.addAttribute("endid", n2Id);

You can navigate the tree

// Find by id - given a document like this:
//  <note xml:id="anote" />
//  <note xml:id="anothernote"/>
//  <tie xml:id="atie" startid="anote" endid="anothernote">
// you can ask for specific elements in the document
MeiElement tie = document.getElementById("atie");
MeiElement note1 = document.getElementById(tie.getAttribute("startid"));

// Find a surrounding element (e.g. a note's parent staff):
//  <staff>
//    ...
//      <note xml:id="anote" pname="d" />
//  </staff>
MeiElement note = document.getElementById("anote");
MeiElement staff = note.getAncestor("staff");

Read MEI documents from XML

File f = new File("example.mei");
MeiDocument doc = MeiXmlImport.import(f);
// Any xml:id that was set in the XML file is now stored
// as the id field on an MeiElement
MeiElement note = doc.getElementById("mynote");
note.getId(); // is "mynote"

Future plans

Tie objects into XML tree so that standard navigation tools (e.g. xpath) can be used
Create an Enum for tag types to prevent invalid tags from being created
Only let valid attributes and children be added to elements
Validate against the MEI schema
Automatically create a valid skeleton document (e.g. with meiversion attribute)
Don't use xml:id when not needed
Map of elements in the document for getById. Needs to auto-update when elements are added and removed.

License

jMEI is released under the MIT License

Bug Reports / Patches

Issues and patches are welcome on GitHub: https://github.com/alastair/jmei