blog.humaneguitarist.org

discoveries in digital audio, music notation, and information encoding

MXMLiszt

without comments

MXMLiszt 0.9.0 (beta)

TERMS:

MXMLiszt is licensed under the BSD software license.


MXMLiszt

Copyright (c) 2010, Nitin Arora.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of Nitin Arora nor the names of his contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents

Introduction

Installation

List of primary files and folders

How it works/Getting Started

Troubleshooting

FAQ

Future Work

Live Demo

Acknowledgments

Introduction

MXMLiszt is a web-based delivery and search/retrieval environment for MusicXML files and their manifestations.

MXMLiszt is currently known to work on the following 32-bit Windows servers.

Successfully tested for production and hosting on Windows XP Home Edition, Service Pack 3.

Successfully tested for production and hosting on Windows 7, Professional.

Successfully tested for hosting on Windows Server 2003.

MXMLiszt 0.9.0 was written by Nitin Arora.

MXMLiszt was created in order to complete a Master's in Library and Information Science at the University of Alabama under the direction of Dr. Steven L. MacCall.

The accompanying research paper, “Beyond Images: Encoding Music for Access and Retrieval” can be accessed at http://blog.humaneguitarist.org/uploads/MXMLiszt/Beyond_Images__Encoding_Music_for_Access_and_Retrieval.pdf.

MXMLiszt uses the following open-source applications:

Musescore: version 0.9.5

MusicXML Library: version 2.0

ImageMagick: version 6.6.1-5

Xenoage Player: version 0.4.1*

Saxon-HE: version 9.2

BaseX: version 6

*As of 2010-02, the Xenoage Player is no longer supported. However, the newest version, Zong!, is still in an early alpha stage, hence the decision to use the Xenoage Player in conjunction with MXMLiszt. Future versions of MXMLiszt will hopefully incorporate both the Zong! Player as well as the developmental MusicXML viewer, Zong! Viewer.

On the name "MXMLiszt":

MXMLiszt = MusicXML List.

MXMLiszt is pronounced [mak-suh-muh-list].

MXMLiszt references the great musical maximalist, Franz Liszt.

Installation (Windows 32-bit, home-based server)

You need an Apache server that supports PHP and Java. You probably have the Java Runtime Environment already installed; if not, you can find it here.

  1. If you don't have an Apache/PHP setup, XAMPP Lite is an excellent choice to get started:

    • Extract xampplite-win32-1.7.3.zip.

    • Unzip the file to wherever you like. I like to rename the root XAMPP folder to “www”.

    • Run setup_xampp.bat and setup your server.

    • For security reasons you might want to delete the phpMyAdmin and mysql folders and all files/folders in htdocs. You assume all risks regarding security, etc.

    • Create a "bin" folder inside the root XAMPP folder.

    • Because some of the scripts take a lot of time to run, increase the maximum execute time in php.ini to more than the default of 60 seconds. I used “3600”.

  2. Download the MXMLiszt-0.9.0.zip file.

    • Extract the files/folders and place the root MXMLiszt folder inside XAMPP's “htdocs” folder.

    • Open adminPanel.php and change line 14 (below) to replace the default Administrator password from “tausig” to your own password.

      • $validPassword = "tausig"

  3. Download the Xenoage player from http://www.xenoage.com/downloads/xenoplay/xenoplay-0-4-1-src.zip.

    • Extract the two .jar files into the htdocs/MXMLiszt folder.

  4. Download MuseScore from http://sourceforge.net/projects/mscore/files/mscore/mscore-0.9.5/MuseScore-0.9.5.exe/download.

  • Install MuseScore inside the “bin” folder. Rename the folder to simply “MuseScore”.

    • The program executable is now located at bin/MuseScore/bin/mscore.exe

  • Run mscore.exe and go to Edit>Preferences>Export and uncheck “Screen shot function”.

  • Hit “Apply” and close the program.

  1. Download the MusicXML Library from http://sourceforge.net/projects/libmusicxml/files/libmusicxml-win32/libmusicxml-2.00-win32/libmusicxml-2.00-win32.zip/download.

  • Create a folder called “libmusicxml” inside your “bin” folder and place all the MusicXML Library files in that folder as such:

    1. Download ImageMagick from http://www.imagemagick.org/download/binaries/ImageMagick-6.6.1-5-Q16-windows-dll.exe.

    • Install ImageMagick inside the “bin” folder. Rename the folder to simply “ImageMagick”.

      • The “convert” executable is now located at bin/ImageMagick/convert.exe

    1. Download BaseX6.jar from http://sourceforge.net/projects/basex/files/basex/6.0/BaseX6.jar/download.

    • Place it in the “bin” folder.

    1. Download saxonhe9-2-1-1j.zip from http://sourceforge.net/projects/saxon/files/Saxon-HE/9.2/saxonhe9-2-1-1j.zip/download.

    • Extract the saxon9he.jar file to the “bin” folder.

    1. To get things started, run “xampp-control.exe” from the root XAMPP folder and start only the Apache module:

    You should now be able to go to “http://localhost/MXMLiszt/” from your browser and see the MXMLiszt welcome page:

    List of primary files and folders

    File

    Type

    Path (relative to MXMLiszt root)

    Description

    style.css

    style sheet

    .

    controls the HTML display

    adminMenu.html

    module

    .

    lists administrator scripts to be executed

    documentation.html

    document

    ./documentation

    MXMLiszt documentation

    footer.html

    module

    .

    contains closing "body" and "html" tags

    index.html

    document

    .

    framed view of MXMLiszt; standardizes view across various display resolutions

    menu.html

    module

    .

    navigation menu

    adminLogin.php

    script

    .

    requests password for administrator access

    adminLogo.php

    module

    .

    displays image of Franz Liszt if administrator is logged on

    adminPanel.php

    script

    .

    displays "adminMenu.html" if administrator is logged on; note: editing the value of the "$validPassword" variable will change the administrator password. The default password is “tausig”.

    concatMODS.php

    script

    .

    concatenates all files in "/mods"; allows XQuery over one file rather then several separate files

    concatMXML.php

    script

    .

    concatenates all files in "/musicXML"; allows XQuery over one file rather then several separate files

    displayMODS.php

    module

    .

    displays MODS in browser per the" mods.xls" stylesheet

    galleryMXML.php

    script

    .

    allows user to browse images of the first page of each piece in "/musicXML"

    generateGallery.php

    module

    .

    generates HTML code to displays preview of the first page of each piece in "/musicXML"

    generateIndex.php

    module

    .

    generates HTML code to displays index view of each piece in "/musicXML"

    generateMODS.php

    script

    .

    generates preliminary MODS metadata using the Saxon XSLT processor and the "mxml2mods.xsl" XSL transformation sheet

    generatePDF.php

    script

    .

    calls Musescore to generate PDFs for all files in "/musicXML"

    generatePNG.php

    script

    .

    calls Musescore to generate PNGs for all files in "/musicXML"; deletes all PNGs for pages > page 1; calls ImageMagick to resize the image

    indexMXML.php

    script

    .

    allows user to browse list of each piece in "/musicXML"

    iniSet.php

    module

    .

    sets maximum execution time for time-intensive scripts like "generatePNG.php"; default is 1 hour

    inputMIR.php

    script

    .

    allows user to send XQueries to BaseX via the web

    inputXQ.php

    script

    .

    allows user to send XQueries to BaseX via the web

    loadMODSasDC.php

    module

    .

    filters down MODS names/titles to Dublin Core creator/title for index and gallery views

    normalizeMXML.php

    script

    .

    calls Musescore to open and close all files in "/musicXML" to theoretically normalize the MusicXML output

    outputMIR.php

    script

    .

    displays XQuery results from "inputMIR.php" entered via the "Faust" terminal

    outputXQ.area.php

    script

    .

    displays XQuery results from "inputXQ.php" if user used the "Dante" terminal

    outputXQ.mods.php

    script

    .

    displays XQuery results from "inputXQ.php" if user used the query box

    processXQ.php

    module

    .

    writes queries to temp file and writes BaseX results to another temp file

    purgeTEMP.php

    script

    .

    administrator script to delete all files in "/temp" directory

    reportMODS.php

    script

    .

    separates remediated and unremediated MODS files into two lists; unremediated MODS files have as the last line the commented-out phrase: "<!–Preliminary MusicXML to MODS metadata created via XSLT–>", metadata librarians must delete that last line when they have remediated the MODS metadata for the file to be considered remediated

    setup.php

    module

    .

    contains the paths and arguments to the open-source applications that MXMLiszt relies on. Changing these values is necessary only if you use a different folder structure than prescribed in the installation instructions.

    showAccess.php

    script

    .

    displays Apache access.log file; purges contents of access.log

    transmuteMXML.php

    script

    .

    allows user to access manifestations of MusicXML files

    transposeXML.php

    script

    .

    calls MusicXML Library to transpose MusicXML file; allows user to access manifestations of transposed MusicXML files

    welcome.php

    module

    .

    home page of MXMLiszt

    sampleMIR.txt

    document

    .

    contains some Music Information Retrieval queries that the user can paste into "inputMIR.php"

    mods.xsl

    XSL

    .

    displays MODS metadata files as HTML

    mxml2mods.xsl

    XSLT

    .

    determines what elements in MusicXML to map to MODS metadata

    concat

    folder

    .

    contains concatenated MODS and MusicXML files

    images

    folder

    .

    contains images needed by the website for pleasant display

    mods

    folder

    .

    contains all MODS metadata

    musicXML

    folder

    .

    contains all MusicXML files; all files must be in root folder

    pdf

    folder

    .

    contains all PDF files

    png

    folder

    .

    contains all PNG preview files

    temp

    folder

    .

    contains all temporary files

    BaseX6.jar

    executable

    ..\..\bin\

    XQuery processor

    saxon9he.jar

    executable

    ..\..\bin\

    XSLT processor

    skin.jar

    skin

    .

    skin files for Xenoage Player; this applet skin must be placed in "htdocs/MXMliszt"

    xenoplay.jar

    executable

    .

    Xenoage MusicXML audio player; this applet must be placed in "htdocs/MXMliszt"

    bin

    folder

    ..\..\

    contains ImageMagick, MusicXML Library, Musescore, BaseX, and Saxon.

    ImageMagick

    folder

    ..\..\bin\

    contains ImageMagick files\folders

    libmusicxml

    folder

    ..\..\bin\

    contains MusixXML Library files\folders

    MuseScore

    folder

    ..\..\bin\

    contains MuseScore files\folders

    convert

    executable

    ..\..\bin\ImageMagick\

    resizes PNG files

    xmltranspose

    executable

    ..\..\bin\libmusicxml\

    transposes MusicXML files

    mscore

    executable

    ..\..\bin\MuseScore\bin\

    normalizes MusicXML files; generates PDF and PNG files; can generate sound files as well (not implemented in MXMLiszt 0.9.0)

     

    How it works/Getting Started

    Screencasts coming soon – these will hopefully be the best and easiest way to see how MXMLiszt works.

    MXMLiszt works on the principle that while the MusicXML encoding for a given composition is itself a manifestation of a work (i.e. the “composition”), the MusicXML file itself can function as a sub-work capable of birthing derivative image and audio files; manifestations also include musical transpositions in MusicXML format, thus allowing the the transpositions to serve as sub-sub-works also capable of spawning new image and audio content.

    The following graphic attempts to depict the essential overall framework of the platform.

    Initial Setup

    It is by first running administrative PHP scripts that the MXMLiszt collection and search environment is created for one or many pre-existing MusicXML files on the server.

    By describing the completion of an administrative "cycle" for a MusicXML file called "foo.xml", it is simpler to demonstrate via example the process depicted in the diagram above.

    Administrative scripts available are as follows:

    Setup Scripts

    • Normalize MusicXML

    • Generate MODS

    • Generate PDF

    • Generate PNG

    Search Related Scripts

    • Concatenate MODS

    • Concatenate MusicXML

    Reporting Script

    • MODS remediation list

    a. Setup Scripts

    Once MusicXML files are placed on the server's “MXMLiszt/musicXML” folder, setup scripts prepare the platform so that a user may browse the collection and have access to images and audio of the compositions.

    1. Normalize MusicXML

    Variations occurs between MusicXML files exported from different notation software packages. Due to this variation, it seems necessary to "normalize" each MusicXML. That is to say, it seems necessary to import each MusicXML file – irrespective of which notation software it was generated from – and export it from the same application, namely MuseScore. This helps to standardize the MusicXML files, allowing for more consistency in regard to subsequent image creation by MuseScore and metadata creation via XSLT.

    In a real working environment our test file "foo.xml" would now have been opened and re-saved by MuseScore.

    MXMLiszt's "index view" option would now result in displaying the following:

    Prematurely clicking on the link above would be less than ideal in that no descriptive metadata is yet available. Also, since no PDF is readily available one would have be be created "on the fly", slowing down the user experience:

    Nevertheless, preliminary functionality exists at this point allowing the user to see and hear the original composition as well as access transpositions of the piece.

    1. Generate PDF

    Though scripts A2 through A4 may be run in any sequence, it is best to generate PDFs first otherwise PDFs will be generated by user activity, adding to the amount of time a user has to wait before being able to view the PDF file.

    This script simply would instruct MuseScore to open "foo.xml" and render a file called "foo.pdf" in the “pdf” folder. If this PDF already exists, no new file will get rendered.

    It should be notated that this script can be fairly time intensive for large amounts of MusicXML files in the collection.

    1. Generate PNG

    Though not necessary and strictly an added "feature" of the platform, this script would call MuseScore to output a PNG image file of each page of each MusicXML file in the “png” folder. It would then delete all but the first page. The ImageMagick software is then called to resize all remaining PNG files to a near thumbnail image, leaving a smaller preview image, "foo.pre.png". If this PNG file already exists, no new PNG files will get rendered for “foo.xml”.

    This preview image can be viewed by hovering over a selection in the "index view" of the platform:

    or by using the "gallery view" of the platform (i.e. visual browsing):

    The usefulness of this feature is more evident in cases where the online collection contains more than one MusicXML file:

    The rational behind this feature was to emulate some print editions of sets of musical compositions in which the user is provided a "visual table of contents", a page containing the first measure or so of each composition within the edition, the "incipient", so that traits such as primary key signature and music texture can be gleaned for each composition within the edition without having to flip through the entire manuscript.

    Given the additional processing, this script is naturally even more time consuming than the previous PDF script.

    1. Generate MODS

    As stated prior, it is via XSLT that one is able to automatically crosswalk descriptive metadata elements in MusicXML to MODS while remaining in the domain of XML technologies, as opposed to using a scripting language such as PHP, Python, etc. to achieve the same results.

    The XSL transformation sheet used by the platform is called "mxml2mods.xsl" and seeks to create MODS XML files for the following primary descriptive properties about the composition:

    titles (primary, alternate)

    creators (composer, lyricist, arranger)

    instrumentation

    Additional elements include the unique, such as the URI identifier, and the fairly generic, such as the Library of Congress Subject Heading "sheet music". The encoding date of the normalized MusicXML file is also captured.

    Running the Generate MODS script would create a file entitled "foo.mods.xml"

    The "index view" of the platform would now show descriptive metadata as such:

    The Gallery view of the of the platform would show the metadata encapsulated in a top-centered yellow box only when the user hovers over the preview image of the composition:

    Note that the metadata, though MODS, is showing up on these pages as Simple Dublin Core, with the "DC" prefix. This was done for two reasons: 1) Ease of programming, given that the platform exists solely for the purpose of demonstration to the library community and 2) because it seemed simpler from a mere browse perspective to have the metadata be fairly "filtered down" to Dublin Core.

    Clicking on the selection from either the Index or Gallery views will, however, now reveal the MODS record as shown below:

    MXMLiszt uses an XSL stylesheet to display the MODS record in a user-friendly way as above, though librarians and information specialists can open the MODS record in a separate browser tab and view the page's source code to view the full MODS XML record.

    At this point, everything is ready from a user browse perspective as they will have access to MusicXML, descriptive metadata, and image files. The Xenoage player will produce sound in real-time and thus no sound files need to be made.

    b. Search Related Scripts

    The two scripts related to preparing the platform for search/retrieval and Music Information Retrieval (MIR) can be run in any order.

    1. Concatenate MODS

    In order to create an adequate search environment for the descriptive metadata (MODS) on the platform, a "virtual" database file for all descriptive metadata is created via this script. In other words, the data from all MODS files are concatenated into one "super" file as such:

    <hyperMODS>

    <hypoMODS file="foo.xml">

    1st MODS document

    </hypoMODS>

    <hypoMODS file="foo2.xml">

    2nd MODS document

    </hypoMODS>

    …

    <hyperMODS>

    It is this hyperMODS file that is access via XQuery searching and the BaseX XQuery processor. This allows for the processor to access only one XML file as opposed to iterating through all individual MODS files on the platform, as the latter option would yield unbearable long retrieval times.

    1. Concatenate MXML

    Similarly, this script concatenates the data for all MusicXML files on the server for quicker search and retrieval in regard to MIR functionality. Given how much larger MusicXML files are in contrast to MODS files, this concatenated "super" MusicXML file can be extremely large, depending on the amount of MusicXML files in the online collection.

    Note the similar structure to the hyperMODS file above:

    <hyperMXML>

    <hypoMXML file="foo.xml">

    1st MusicXML document

    </hypoMXML>

    <hypoMXML file="foo2.xml">

    2nd MusicXML document

    </hypoMXML>

    …

    </hyperMXML>

    By using administrative scripts to prepare these large concatenated XML files the platform is initialized for search/retrieval and MIR across the entire online collection.

    The descriptive metadata can be searched by a user-friendly drop-down box or by manual entry of valid XQuery syntax into a terminal style input box – nicknamed "Dante" for one of Liszt's symphonic works. In fact, MIR searches can also be initiated via terminal input, however this terminal is fairly restrictive in that query results must return only MusicXML filenames so that the platform can display the results in either the Index or Gallery view styles.

    A less restrictive terminal ("Faust", also for one of Liszt's symphonies) allows advanced users to perform MIR (and even descriptive metadata) searches and return results in the output style of their choosing. Currently, intermediate users can access a link to a plain text file with pre-written MIR queries that can be cut and paste into the terminal.

    Obviously, both terminal input boxes are primarily intended for advanced users who understand both XQuery fundamentals and the file and folder structure of the MXMLiszt platform. Ideally future versions of the platform would support graphics-based input of musical information, such as pitches and durations.

    c. Reporting Script

    As mentioned, the XLS transformation that produces initial MODS records from the the MusicXML files ends the outputted MODS file with a commented-out line that reads:

    <!–Preliminary MusicXML to MODS metadata created via XSLT–>

    The "MODS remediation list" script simply reports to interested administrators (i.e. metadata librarians) which MODS files within the platform do and do not contain this line, the principle being that remediation (improvement) of MODS records by librarians would include the removal of this line, hence allowing subsequent remediated MODS records to be reported as remediated.

    Troubleshooting

     

    Administrator errors:

    1. generateMODS.php not working

    • Make sure Java is installed.

    • You must have a live internet connexion for Saxon to perform XSLT operations due to xsd/schema needs.

     

    User errors:

    1. Xenoage Player not working

    • Make sure Java is installed.

    • Make sure you've installed the Java Soundbank.

    • Occassionally, there are MusicXML files Xenoage cannot play. I plan to contact the programmers and ask why this might happen from time to time.

    1. Some of the PDFs have very odd spacing and page layout issues.

    • I think this is an issue with MuseScore. I own Finale Notepad and it seems to do a better job with MusicXML import. But, I really don't know yet why these things happen from time to time with certain pieces.

    FAQ

    1. Why are you using the Xenoage player? MuseScore can create OGG files from free SoundFonts and the audio can be embedded in the HTML 5 <audio> tag.

    • I'm not clear on the licensing situation with SoundFonts even though there are many "free" ones available. Also, Xenoage doesn't require OGG files to be written and saved to the server, so the Xenoage applet saves storage space as well.

    • I have thought about adding an OGG/<audio> tag option as a backup for MusicXML files that Xenoage is not able to play.

    Future Work

    • As of 2010-07, a permanent URL to the manifestations of "foo.xml" would look like this: /MXMLiszt/transmuteMXML.php?fname=musicXML%2Ffoo.xml.
      • I'd like to make these prettier, for example: /MXMLiszt/foo/
      • This tutorial on URL redirecting might have the answers I need in order to accomplish that.
      • This isn't really a programming issue, but more a server management issue. Still, it's better digital library practice to have tinier URLs.

    Live Demo

    As of June, 2010 the live demo of MXMLiszt can be accessed at:

    http://opensourcelibrarian.org/MXMLiszt

    Acknowledgments

    Thanks to the following people:

    Dr. Steven L. MacCall,

    Jody DeRidder,

    Tonio Loewald,

    “Playingwithbrushes” for the great background used by MXMLiszt,

    everyone responsible for the open-source applications and scripting languages used by MXMLiszt,

    everyone responsible for all the great SMR/MIR tools, research, and resources on the Web,

    Michael Good for MusicXML,

    and Franz “The Man” Liszt.

    Written by nitin

    June 13th, 2010 at 10:20 am

    Posted in General

    Tagged with

    Leave a Reply