.. _moduleConverter:

music21.converter
=================

.. WARNING: DO NOT EDIT THIS FILE: AUTOMATICALLY GENERATED. Edit the .py file directly

.. module:: music21.converter


music21.converter contains tools for loading music from various file formats,
whether from disk, from the web, or from text, into
music21.stream.:class:`~music21.stream.Score` objects (or
other similar stream objects).


The most powerful and easy to use tool is the :func:`~music21.converter.parse`
function. Simply provide a filename, URL, or text string and, if the format
is supported, a :class:`~music21.stream.Score` will be returned.


This is the most general public interface for all formats.  Programmers
adding their own formats to the system should provide an interface here to
their own parsers (such as humdrum, musicxml, etc.)


The second and subsequent times that a file is loaded it will likely be much
faster since we store a parsed version of each file as a "pickle" object in
the temp folder on the disk.




>>> from music21 import *
>>> s = converter.parse('d:/mydocs/schubert.krn')
>>> s
<music21.stream.Score ...>




.. function:: parse(value, *args, **keywords)


    Given a file path, encoded data in a Python string,
    or a URL, attempt to parse the item into a Stream.
    Note: URL downloading will not happen automatically unless
    the user has set their Environment "autoDownload"
    preference to "allow".


    Keywords can include `number` which specifies a piece number
    in a file of multipiece file.


    `format` specifies the format to parse the line of text or the file as.

    A string of text is first checked to see if it is a
    filename that exists on disk.  If not it is searched
    to see if it looks like a URL.  If not it is processed
    as data.


    The data is normally interpreted as a line of TinyNotation
    with the first argument being the time signature:


    TODO: SHOW FILE
    TODO: SHOW URL





    >>> from music21 import *
    >>> s = converter.parse("tinyNotation: 3/4 E4 r f# g=lastG trip{b-8 a g} c")
    >>> s.getElementsByClass(meter.TimeSignature)[0]
    <music21.meter.TimeSignature 3/4>
    ⁠ 
    >>> s2 = converter.parse("E8 f# g#' G f g# g G#", "2/4")
    >>> s2.show('text')
    {0.0} <music21.meter.TimeSignature 2/4>
    {0.0} <music21.note.Note E>
    {0.5} <music21.note.Note F#>
    {1.0} <music21.note.Note G#>
    {1.5} <music21.note.Note G>
    {2.0} <music21.note.Note F>
    {2.5} <music21.note.Note G#>
    {3.0} <music21.note.Note G>
    {3.5} <music21.note.Note G#>




.. function:: parseFile(fp, number=None, format=None, forceSource=False)

    Given a file path, attempt to parse the file into a Stream.



.. function:: parseData(dataStr, number=None, format=None)

    Given musical data represented within a Python string, attempt to parse the data into a Stream.



.. function:: parseURL(url, number=None, format=None, forceSource=False)

    Given a URL, attempt to download and parse the file into a Stream. Note: URL downloading will not happen automatically unless the user has set their Environment "autoDownload" preference to "allow".



.. function:: freeze(streamObj, fmt=None, fp=None)

    Given a StreamObject and a file path, serialize and store the Stream to a file.

    This function is based on the :class:`~music21.converter.StreamFreezer` object.

    The serialization format is defined by the `fmt` argument; 'pickle' (the default), 'jsonpickle' or 'jsonnative' are presently supported.

    If no file path is given, a temporary file is used.

    The file path is returned.



    >>> from music21 import *
    >>> c = converter.parse('c4 d e f', '4/4')
    >>> c.show('text')
    {0.0} <music21.meter.TimeSignature 4/4>
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D>
    {2.0} <music21.note.Note E>
    {3.0} <music21.note.Note F>
    >>> fp = converter.freeze(c, fmt='pickle')
    >>> fp
    '/tmp/music21/sjiwoe.p'

    The file can then be "defrosted" back into a Stream using the :func:`~music21.converter.unfreeze` method.



    >>> d = converter.unfreeze(fp)
    >>> d.show('text')
    {0.0} <music21.meter.TimeSignature 4/4>
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D>
    {2.0} <music21.note.Note E>
    {3.0} <music21.note.Note F>



.. function:: unfreeze(fp)

    Given a file path of a serialized Stream, defrost the file into a Stream.

    This function is based on the :class:`~music21.converter.StreamFreezer` object.

    See the documentation for :meth:`~music21.converter.freeze` for demos.



.. function:: freezeStr(streamObj, fmt=None)

    Given a StreamObject and a file path, serialize and return a serialization string.

    This function is based on the :class:`~music21.converter.StreamFreezer` object.

    The serialization format is defined by the `fmt` argument; 'pickle' (the default), 'jsonpickle' or 'jsonnative' are presently supported.



    >>> from music21 import *
    >>> c = converter.parse('c4 d e f', '4/4')
    >>> c.show('text')
    {0.0} <music21.meter.TimeSignature 4/4>
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D>
    {2.0} <music21.note.Note E>
    {3.0} <music21.note.Note F>
    >>> data = converter.freezeStr(c, fmt='pickle')
    >>> len(data) > 20 # pickle implementation dependent
    True
    >>> d = converter.unfreezeStr(data)
    >>> d.show('text')
    {0.0} <music21.meter.TimeSignature 4/4>
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D>
    {2.0} <music21.note.Note E>
    {3.0} <music21.note.Note F>




.. function:: unfreezeStr(strData)

    Given a serialization string, defrost into a Stream.

    This function is based on the :class:`~music21.converter.StreamFreezer` object.



Converter
---------



.. class:: Converter()


    A class used for converting all supported data formats into music21 objects.

    Not a subclass, but a wrapper for different converter objects based on format.



    **Converter** **attributes**

        Attributes without Documentation: `validHeaderFormats`

    **Converter** **properties**

        .. attribute:: stream

            All converters have to have a stream property or attribute.



    **Converter** **methods**

        .. method:: formatFromHeader(dataStr)


            if dataStr begins with a text header such as  "tinyNotation:" then
            return that format plus the dataStr with the head removed.

            Else, return (None, dataStr) where dataStr is the original untouched.

            Not case sensitive.



            >>> from music21 import *
            >>> c = converter.Converter()
            >>> c.formatFromHeader('tinynotation: C4 E2')
            ('tinyNotation', 'C4 E2')
            ⁠ 
            >>> c.formatFromHeader('C4 E2')
            (None, 'C4 E2')



        .. method:: parseData(dataStr, number=None, format=None, forceSource=False)

            Given raw data, determine format and parse into a music21 Stream.



        .. method:: parseFile(fp, number=None, format=None, forceSource=False)


            Given a file path, parse and store a music21 Stream.


            If format is None then look up the format from the file
            extension using `common.findFormatFile`.




        .. method:: parseURL(url, format=None, number=None)

            Given a url, download and parse the file
            into a music21 Stream stored in the `stream`
            property of the converter object.

            Note that this checks the user Environment
            `autoDownlaad` setting before downloading.

            As a convenience method, links to Wikifonia main
            page for a piece are redirected to the musicxml
            (n.b., it is up to you to determine if any piece
            on Wikifonia is in or out of copyright in your
            juristiction).


            Demonstration of rewrite ability for URLs.
            Actual URL is http://static.wikifonia.org/4391/musicxml.xml
            but the URL below is what's shown on the browser, so either
            is accepted.




            >>> from music21 import *
            >>> jeanieLightBrownURL = 'http://www.wikifonia.org/node/4391'
            >>> c = converter.Converter()
            >>> c.parseURL(jeanieLightBrownURL)
            >>> jeanieStream = c.stream




ConverterMusicXML
-----------------



.. class:: ConverterMusicXML(forceSource)

    Converter for MusicXML



    **ConverterMusicXML** **properties**

        .. attribute:: stream

            No documentation.


    **ConverterMusicXML** **methods**

        .. method:: getPartNames()

            No documentation.


        .. method:: load()

            Load all parts from a MusicXML object representation.
            This determines the order parts are found in the stream



        .. method:: parseData(xmlString, number=None)

            Open MusicXML data from a string.


        .. method:: parseFile(fp, number=None)

            Open from a file path; check to see if there is a pickled
            version available and up to date; if so, open that, otherwise
            open source.




ConverterHumdrum
----------------



.. class:: ConverterHumdrum()

    Simple class wrapper for parsing Humdrum data provided in a file or in a string.



    **ConverterHumdrum** **attributes**

        Attributes without Documentation: `stream`

    **ConverterHumdrum** **methods**

        .. method:: parseData(humdrumString, number=None)

            Open Humdrum data from a string



            >>> humdata = '**kern\n*M2/4\n=1\n24r\n24g#\n24f#\n24e\n24c#\n24f\n24r\n24dn\n24e-\n24gn\n24e-\n24dn\n*-'
            >>> c = ConverterHumdrum()
            >>> s = c.parseData(humdata)



        .. method:: parseFile(filepath, number=None)

            Open Humdram data from a file path.



ArchiveManager
--------------



.. class:: ArchiveManager(fp, archiveType='zip')

    Before opening a file path, this class can check if this is an archived file collection, such as a .zip or or .mxl file. This will return the data from the archive.



    Only archive type supported now is zip.



    **ArchiveManager** **methods**

        .. method:: getData(name=None, format='musicxml')

            Return data from the archive by name. If no name is given, a default may be available.

            For 'musedata' format this will be a list of strings. For 'musicxml' this will be a single string.



        .. method:: getNames()

            Return a list of all names contained in this archive.



        .. method:: isArchive()

            Return True or False if the filepath is an archive of the supplied archiveType.




ConverterABC
------------



.. class:: ConverterABC()

    Simple class wrapper for parsing ABC.



    **ConverterABC** **properties**

        .. attribute:: stream

            No documentation.


    **ConverterABC** **methods**

        .. method:: parseData(strData, number=None)

            Get ABC data, as token list, from a string representation. If more than one work is defined in the ABC data, a  :class:`~music21.stream.Opus` object will be returned; otherwise, a :class:`~music21.stream.Score` is returned.



        .. method:: parseFile(fp, number=None)

            Get MIDI data from a file path. If more than one work is defined in the ABC data, a  :class:`~music21.stream.Opus` object will be returned; otherwise, a :class:`~music21.stream.Score` is returned.

            If `number` is provided, and this ABC file defines multiple works with a X: tag, just the specified work will be returned.




ConverterMidi
-------------



.. class:: ConverterMidi()

    Simple class wrapper for parsing MIDI.



    **ConverterMidi** **properties**

        .. attribute:: stream

            No documentation.


    **ConverterMidi** **methods**

        .. method:: parseData(strData, number=None)

            Get MIDI data from a binary string representation.



        .. method:: parseFile(fp, number=None)

            Get MIDI data from a file path.



ConverterMuseData
-----------------



.. class:: ConverterMuseData()

    Simple class wrapper for parsing MuseData.



    **ConverterMuseData** **properties**

        .. attribute:: stream

            No documentation.


    **ConverterMuseData** **methods**

        .. method:: parseData(strData, number=None)

            Get musedata from a string representation.




        .. method:: parseFile(fp, number=None)






ConverterNoteworthy
-------------------



.. class:: ConverterNoteworthy()


    Simple class wrapper for parsing NoteworthyComposer data provided in a file or in a string.


    Gets data with the file format .nwctxt


    Users should not need this routine.  The basic format is




    >>> from music21 import *
    >>> paertPath = converter.parse('d:/desktop/arvo_part_o_weisheit.nwctxt')
    >>> paertStream = converter.parse(paertPath)
    >>> len(paertStream.parts)
    4


    For developers: see the documentation for :meth:`parseData` and :meth:`parseFile`
    to see the low-level usage.




    **ConverterNoteworthy** **attributes**

        Attributes without Documentation: `stream`

    **ConverterNoteworthy** **methods**

        .. method:: parseData(nwcData)

            Open Noteworthy data from a string or list



            >>> nwcData = "!NoteWorthyComposer(2.0)\n|AddStaff\n|Clef|Type:Treble\n|Note|Dur:Whole|Pos:1^"
            >>> c = ConverterNoteworthy()
            >>> c.parseData(nwcData)
            >>> c.stream.show('text')
            {0.0} <music21.stream.Part ...>
                {0.0} <music21.stream.Measure 0 offset=0.0>
                    {0.0} <music21.clef.TrebleClef>
                    {0.0} <music21.note.Note C>



        .. method:: parseFile(fp, number=None)


            Open Noteworthy data (as nwctxt) from a file path.





            >>> from music21 import *
            >>> paertPath = converter.parse('d:/desktop/arvo_part_o_weisheit.nwctxt')
            >>> c = ConverterNoteworthy()
            >>> c.parseFile(filePath)
            >>> c.stream.show()




ConverterRomanText
------------------



.. class:: ConverterRomanText()

    Simple class wrapper for parsing roman text harmonic definitions.



    **ConverterRomanText** **properties**

        .. attribute:: stream

            No documentation.


    **ConverterRomanText** **methods**

        .. method:: parseData(strData, number=None)





        .. method:: parseFile(fp, number=None)






ConverterTinyNotation
---------------------



.. class:: ConverterTinyNotation()

    Simple class wrapper for parsing TinyNotation data provided in a file or in a string.



    **ConverterTinyNotation** **attributes**

        Attributes without Documentation: `stream`

    **ConverterTinyNotation** **methods**

        .. method:: parseData(tnData, number=None)

            Open TinyNotation data from a string or list



            >>> tnData = ["E4 r f# g=lastG trip{b-8 a g} c", "3/4"]
            >>> c = ConverterTinyNotation()
            >>> s = c.parseData(tnData)



        .. method:: parseFile(fp, number=None)

            Open TinyNotation data from a file path.



PickleFilter
------------



.. class:: PickleFilter(fp, forceSource=False)

    Before opening a file path, this class can check if there is an up
    to date version pickled and stored in the scratch directory.

    If the user has not specified a scratch directory, a pickle path will
    not be created.



    Provide a file path to check if there is pickled version.

    If forceSource is True, pickled files, if available, will not be
    returned.



    **PickleFilter** **methods**

        .. method:: status()

            Given a file path specified with __init__, look for an up to date pickled version of this file path. If it exists, return its fp, other wise return the original file path.

            Return arguments are file path to load, boolean whether to write a pickle, and the file path of the pickle.




StreamFreezer
-------------



.. class:: StreamFreezer(streamObj=None)

    This class is used to freeze a Stream, preparing it for serialization and providing conversion routines.

    In general, use the :func:`~music21.converter.freeze` and :func:`~music21.converter.unfreeze` functions for serializing to a file. Use the :func:`~music21.converter.unfreeze`



    >>> from music21 import *
    >>> s = stream.Stream()
    >>> s.repeatAppend(note.Note('C4'), 8)
    >>> temp = [s[n].transpose(n, inPlace=True) for n in range(len(s))]
    ⁠ 
    >>> sf = StreamFreezer(s) # provide a Stream at init
    >>> data = sf.writeStr(fmt='pickle') # pickle is default format; jsonpickle
    >>> sfOut = StreamFreezer()
    >>> sfOut.openStr(data)
    >>> s = sfOut.stream
    >>> s.show('t')
    {0.0} <music21.note.Note C>
    {1.0} <music21.note.Note D->
    {2.0} <music21.note.Note D>
    {3.0} <music21.note.Note E->
    {4.0} <music21.note.Note E>
    {5.0} <music21.note.Note F>
    {6.0} <music21.note.Note G->
    {7.0} <music21.note.Note G>




    **StreamFreezer** **attributes**

        Attributes without Documentation: `stream`

    **StreamFreezer** **methods**

        .. method:: open(fp)

            For a supplied file path to a pickled stream, unpickle



        .. method:: openStr(fileData)

            Open a String as a pickle



        .. method:: write(fmt=None, fp=None)

            For a supplied Stream, write a serialized version.



        .. method:: writeStr(fmt=None)

            Return a pickled as String




