.. _usersGuide_08_installingMusicXML: .. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. PLEASE EDIT THE .py FILE DIRECTLY. User’s Guide, Chapter 8: Installing MusicXML Readers and File Formats (1) ========================================================================= Music21 can import and export many different musical data formats, including MusicXML and MIDI. Pieces in many of these formats are distributed with music21 as part of the corpus module (see :ref:`moduleCorpus`); look at :ref:`referenceCorpus` to see them all. In general, to load a file from disk, call :func:`music21.converter.parse`, which can handle importing all supported formats. (For complete documentation on file and data formats, see :ref:`moduleConverter`.) If you want to convert a file from the corpus just use :func:`music21.corpus.parse`: .. code:: ipython3 from music21 import * .. code:: ipython3 b = corpus.parse('bach/bwv66.6') b = b.measures(0, 5) #_DOCS_HIDE b.show() # I've altered this so it's much shorter than it should be... .. image:: usersGuide_08_installingMusicXML_3_0.png :width: 708px :height: 725px Okay, so say you’re having some problems seeing things. The first things to ask are: - Do you have Finale, Sibelius, or MuseScore installed? - Will you go to https://musescore.org/en and get a Free copy? Once you have one of these three (or others such as Dorico) installed, we can move on. (It *is* possible to use ``music21`` with Lilypond alone, but that’s much harder to get configured properly, so please try this first) Run this command (after the ``from music21 import *``): .. code:: ipython3 #_DOCS_SHOW configure.run() You can say “no” to everything that is “Yes/No”, but make sure that it is finding your copy of MuseScore, Finale, or Sibelius. Parsing Files in General ------------------------ You can parse a file on your hard drive by calling :func:`music21.converter.parse`. This returns a :class:`~music21.stream.Score` usually, though sometimes :class:`~music21.stream.Part` (for a format that only handles single parts) or :class:`~music21.stream.Opus` (for multiple scores bound together) comes back instead. You won’t do much with that unless you assign it to a variable, such as ``c``: .. code:: ipython3 #_DOCS_SHOW c = converter.parse('/Users/cuthbert/Desktop/myXML.xml') If you’re on a PC, one of the things to notice is that you can use forward slashes, as in: .. code:: ipython3 #_DOCS_SHOW c = converter.parse('C:/Users/cuthbert/Desktop/myXML.xml') Or you can use backslashes, as long as you put an ``r`` before the quote before the file name: .. code:: ipython3 #_DOCS_SHOW c = converter.parse(r'C:\Users\cuthbert\Desktop\myXML.xml') If you’re in the directory of the file, you can just use the local filename (for instance if you start in ``/Users/cuthbert/`` you could just use ``'Desktop/myXML.xml'``. If the file you want is on the web, we can give a URL to the :func:`music21.converter.parse` function that points to the desired file. Assuming proper system configuration (which we will get to further in :ref:`Chapter 24 `), the file will be downloaded and parsed. .. code:: ipython3 url = 'https://kern.ccarh.org/cgi-bin/ksdata?l=cc/bach/cello&file=bwv1007-01.krn&f=xml' sAlt = converter.parse(url) sAlt.measures(1, 5).show() # show first 5 measures .. image:: usersGuide_08_installingMusicXML_16_0.png :width: 782px :height: 429px Usually, the file format can be guessed from the filename, but if the filename does not have a suffix *(as sometimes happens on macOS!)* or the URL has the wrong suffix, you can give a ``format="FORMAT"`` parameter to the file: .. code:: ipython3 #_DOCS_SHOW c = converter.parse('/Users/cuthbert/Desktop/myXML', format='musicxml') One of the things you’ll notice over time is that once you parse a file into ``music21`` once, the next time you parse it it’ll be between 2 and 5 times faster. That’s because we save an optimized version of the file the first time you create a file, and subsequent times you open it it will check to see if the original file has changed, and if it hasn’t, it will read the optimized version instead. For most people, this will work 100% of the time. But if you’ve done something sneaky (like changed the file without changing its modification time) or you’ve changed the format of the ``music21`` parser, or if something’s not right, or if you just want to do things slower, you can put a ``forceSource=True`` keyword into the ``parse`` format. .. code:: ipython3 #_DOCS_SHOW c = converter.parse('/Users/cuthbert/Desktop/myXML.xml', forceSource=True) By the way…if you’ve read any really old ``music21`` publications, you might see ``parseWork`` mentioned instead of ``parse``. It’s the same thing, so anywhere you see ``parseWork``, type ``parse`` instead. File types available to ``music21`` ----------------------------------- ``Music21`` can read and write a lot of different file formats. Some of them are pretty obscure. Some of them are world standards. The ``converter`` module’s capital-c-``Converter`` object can give a list of some of them. Each tool to work with one format is called a ``subConverter``. Here are the formats that ``music21`` can read: .. code:: ipython3 converter.Converter().subConvertersList('input') .. parsed-literal:: :class: ipython-result [music21.converter.subConverters.ConverterABC, music21.converter.subConverters.ConverterCapella, music21.converter.subConverters.ConverterClercqTemperley, music21.converter.subConverters.ConverterHumdrum, music21.converter.subConverters.ConverterMEI, music21.converter.subConverters.ConverterMidi, music21.converter.subConverters.ConverterMuseData, music21.converter.subConverters.ConverterMusicXML, music21.converter.subConverters.ConverterNoteworthy, music21.converter.subConverters.ConverterNoteworthyBinary, music21.converter.subConverters.ConverterRomanText, music21.converter.subConverters.ConverterScala, music21.converter.subConverters.ConverterTinyNotation, music21.converter.subConverters.ConverterVolpiano] And the formats that it can write: .. code:: ipython3 converter.Converter().subConvertersList('output') .. parsed-literal:: :class: ipython-result [music21.converter.subConverters.ConverterBraille, music21.converter.subConverters.ConverterLilypond, music21.converter.subConverters.ConverterMidi, music21.converter.subConverters.ConverterMusicXML, music21.converter.subConverters.ConverterRomanText, music21.converter.subConverters.ConverterScala, music21.converter.subConverters.ConverterText, music21.converter.subConverters.ConverterTextLine, music21.converter.subConverters.ConverterVexflow, music21.converter.subConverters.ConverterVolpiano] To output a file, either call ``.show("format")`` on the stream (where format can be ``musicxml``, ``braille``, ``midi``, etc.) or to keep the file on disk, use ``.write("format", "filename")``. Some of the available formats will be listed below; the most important ones for now are the output formats (since music21 will figure out inputs automatically). They are ``braille``, ``lilypond``, ``midi``, ``musicxml``, ``scala``, ``text``, and ``vexflow``. Some formats have sub-formats, for instance both ``musicxml`` and ``lilypond`` have a ``.png`` subformat which converts directly to a ``.png`` file. To use that, call ``.show("musicxml.png")``. Some formats have abbreviations also, so ``musicxml`` is also ``xml``, ``lilypond`` is ``lily``, and (for ease of typing), ``text`` is ``t``. Getting and working with MusicXML Files --------------------------------------- A whole bunch of MusicXML files can be found at the following URLs. - https://musescore.com/ - https://www.gutenberg.org/ MusicXML files sometimes have the extension ``.xml`` or ‘.musicxml’ or ``.mxl``. The last is the suffix for a compressed MusicXML file; it loads in the same manner. The format for musicxml, is, of course, ``musicxml``. **SECURITY WARNING:** MusicXML, like all XML formats, has certain security issues which are built into the Python ElementTree library. If you are parsing MusicXML files from an untrusted source (like the Internet or from a user upload in the case of using ``music21`` in a server environment), we strongly urge the use of additional security libraries, such as `defusedxml `__. To have ``music21`` use ``defusedxml`` by default, call ``import defusedxml; defusedxml.defuse_stdlib()`` before importing music21. Getting and working with Humdrum Files -------------------------------------- Humdrum is a file format developed by David Huron at Ohio State University which is great at encoding works for computational analysis. The Humdrum format includes many subformats (“spine classes”) of which ``music21`` supports the general class, the ``kern`` format, and the ``dynam`` dynamics format. Parsing Humdrum files is exactly as parsing other data formats. Simply call the music21.converter.parse() function on the desired file path or URL. .. code:: ipython3 sBach = converter.parse('https://kern.ccarh.org/cgi-bin/ksdata?' + 'l=users/craig/classical/bach/cello&file=bwv1007-01.krn&f=kern') Over one hundred thousand Kern files can be found at the following URL. https://kern.humdrum.org/ Getting and working with ABC Files ---------------------------------- ABC is a text-based format that can encode lots of musical types, but is especially great for monophonic songs, such as folk songs. If you’re in the folk song world, you’ll love working with ABC. Parsing ABC files is exactly as parsing other data formats. Simply call the :func:`music21.converter.parse` function on the desired file path or URL. .. code:: ipython3 #_DOCS_SHOW o = converter.parse('/Users/cuthbert/Documents/Music21/praludium.abc') Large collections of ABC are available from numerous on-line repositories. The following links are just a few of the many resources available. https://abcnotation.com http://www.serpentpublications.org/drupal7/ ABC Opus files ~~~~~~~~~~~~~~ Note that many ABC files define more than one complete musical work. If an ABC file defines more than one work, an :class:`~music21.stream.Opus` object is returned. Opus objects, a Stream subclass, provide convenience methods for accessing multiple Score objects. You can get a whole bunch of pieces together just by parsing the file. For instance, here’s an Opus: .. code:: ipython3 o = corpus.parse('josquin/ovenusbant') o .. parsed-literal:: :class: ipython-result Reference work numbers (e.g., the “X:” metadata tag in ABC) are stored in :class:`~music21.metadata.Metadata` objects in each contained Score. Access to these numbers from the Opus is available with the :meth:`music21.stream.Opus.getNumbers` method. Additionally, the :class:`~music21.stream.Score` object can be directly obtained with the :meth:`~music21.stream.Opus.getScoreByNumber` method. .. code:: ipython3 o = corpus.parse('josquin/ovenusbant') o.getNumbers() .. parsed-literal:: :class: ipython-result ['1', '2', '3'] .. code:: ipython3 s = o.getScoreByNumber(2) s.metadata.title .. parsed-literal:: :class: ipython-result 'O Venus bant' Direct access to Score objects contained in an Opus by title is available with the :meth:`~music21.stream.Opus.getScoreByTitle` method. .. code:: ipython3 o = corpus.parse('essenFolksong/erk5') s = o.getScoreByTitle('Vrienden, kommt alle gaere') s .. parsed-literal:: :class: ipython-result .. code:: ipython3 s.metadata.title .. parsed-literal:: :class: ipython-result 'Vrienden, kommt alle gaere' Some ABC files, such as those in ``corpus/essenFolksong`` have hundreds or thousands of files. The way we’ve been doing things before is to parse all of them and then select the one we want. If you know the number of the file you want, however, you can pass to ``converter.parse`` or ``corpus.parse`` a ``number=X`` attribute to get just that one. It will return a ``Score`` object .. code:: ipython3 s = corpus.parse('essenFolksong/erk5', number=2) s .. parsed-literal:: :class: ipython-result ABC single-part Opus files ~~~~~~~~~~~~~~~~~~~~~~~~~~ In some cases an ABC file may define individual parts each as a separate score, sort of like a Renaissance partbook. When parsed, these parts can be combined from the Opus into a single Score with the :meth:`music21.stream.Opus.mergeScores` method. For instance, here is Josquin’s “Mille Regretz” (spelled with an s) stored as four individual parts each as its own score: .. code:: ipython3 o = corpus.parse('josquin/milleRegrets') len(o.scores) .. parsed-literal:: :class: ipython-result 4 .. code:: ipython3 len(o.scores[0].parts) .. parsed-literal:: :class: ipython-result 1 .. code:: ipython3 o.scores[0].show() .. image:: usersGuide_08_installingMusicXML_52_0.png :width: 708px :height: 680px So, that’s not too helpful. We can run ``mergeScores`` to bring them into a single score with four parts. .. code:: ipython3 s = o.mergeScores() s.metadata.title .. parsed-literal:: :class: ipython-result 'Mille regrets' .. code:: ipython3 len(s.parts) .. parsed-literal:: :class: ipython-result 4 .. code:: ipython3 s.measures(1, 10).show() .. image:: usersGuide_08_installingMusicXML_56_0.png :width: 674px :height: 371px Parsing Musedata Files ---------------------- Musedata is a format devised by Walter Hewlett (yes, of HP lineage) in the 1980s that is highly memory efficient. Probably not the best format for modern computers, but there’s a huge collection of Musedata files out on the net of many standard repertory pieces. Both stage 1 (limited encoding) and stage 2 (rich encoding) Musedata file formats are supported by Music21. Multi-part Musedata (stage 2) files, zipped archives, and directories containing individual files for each part (stage 1 or stage 2) can be imported with the :func:`music21.converter.parse` function on the desired file path or URL. Note that access restrictions prevent demonstrating Musedata conversion. Downloading or using Musedata files requires sending a written access agreement to the owners. Parsing MIDI Files ------------------ MIDI input and output is handled in the same was other formats. Simply call the :func:`music21.converter.parse` function on the desired file path or URL. Remember (or learn if you haven’t yet), that MIDI has no information about enharmonic spelling (C# and Db are the same), and that detecting the lengths of notes can be difficult. ``Music21`` does very well with MIDI files that were created in notation software or sequencing software, but has a harder time handling MIDI files created by recording live input. For those files, we suggest converting the MIDI files in software such as Finale that has a more sophisticated MIDI to MusicXML conversion routine. Conclusion ---------- One of ``music21``\ ’s core strengths is the number of different file formats it handles. Some people who don’t use ``music21`` for anything else use it as a format converter. We’re happy about that, but think, hey, there’s a lot more that you can do with it than that. Let’s move on in the next chapter to one of the tools that ``music21`` has for analysis that almost nothing else out there has: :ref:`Chapter 9: Chordify ` which reduces scores to chordal collections.