.. _installIPython:

.. WARNING: DO NOT EDIT THIS FILE:
   AUTOMATICALLY GENERATED.
   PLEASE EDIT THE .py FILE DIRECTLY.


Using ``music21`` with the Jupyter (iPython) Notebook
=====================================================

Setting up the Jupyter environment
----------------------------------

To get ``music21`` to work it's best to have a good pip installation
first. Then you should be able to simply install jupyter (and IPython if
you don't have it):

``$ sudo pip install jupyter $ sudo pip install ipython``

Using the web-based Jupyter Notebook
------------------------------------

Start jupyter in a directory you want to save files by typing.

```$ jupyter notebook```

Now in the webbrowser you can type commands such as the ones below:

.. code:: python

    from music21 import *

.. code:: python

    c = chord.Chord("C4 E4 G4")
    c.isConsonant()




.. parsed-literal::
   :class: ipython-result

    True



All other normal ``music21`` commands will work as they should

Displaying graphics inline
--------------------------

By default, you cannot just call .show() because you'll open up your
MusicXML reader locally...

.. code:: python

    c.show()




.. parsed-literal::
   :class: ipython-result

    <music21.ipython21.objects.IPythonPNGObject at 0x1054dcf60>



Nor does just generating a lilypond PNG or PDF work as you'd like --
this will display it on the screen but not in your browser:

.. code:: python

    c.show('lily.pdf')

Instead do this:

.. code:: python

    %load_ext music21.ipython21

Now this will work:

.. code:: python

    c.show()




.. image:: installIPython_18_0.png



If you don't want to do that, then instead do this...

.. code:: python

    from IPython.core.display import Image
    #_DOCS_SHOW Image(filename=c.write('lily.png'))

SVG is much faster, but it doesn't work, sadly...

.. code:: python

    Image(filename=c.write('lily.svg'))


::


    ---------------------------------------------------------------------------

    ValueError                                Traceback (most recent call last)

    <ipython-input-9-a78ad09b705c> in <module>()
    ----> 1 Image(filename=c.write('lily.svg'))
    

    /Users/cuthbert/anaconda/lib/python3.4/site-packages/IPython/core/display.py in __init__(self, data, url, filename, format, embed, width, height, retina, unconfined, metadata)
        731 
        732         if self.embed and self.format not in self._ACCEPTABLE_EMBEDDINGS:
    --> 733             raise ValueError("Cannot embed the '%s' image format" % (self.format))
        734         self.width = width
        735         self.height = height


    ValueError: Cannot embed the 'svg' image format


Whole pieces will show properly also now that the extension module is
loaded

.. code:: python

    b = corpus.parse('bach/bwv66.6')
    b.show()




.. image:: installIPython_24_0.png



And that is basically it! We use ``sphinx`` for interwiki links, which,
sadly, won't show up on the notebook, but should render properly.

But I did make a sphinx-markdown Notebook extension. When it's ready,
I'll put it up. Make a directory "sphinx-markdown" in a "usability"
directory in "nbextensions" (mine is at
"~/Library/Jupyter/nbextensions"). And put this file there as "main.js":
[https://gist.github.com/mscuthbert/6411762f98f3536712e0]

Check to see if it exists:

.. code:: python

    import notebook
    notebook.nbextensions.check_nbextension('usability/sphinx-markdown', user=True)




.. parsed-literal::
   :class: ipython-result

    True



Load it with:

.. code:: python

    E = notebook.nbextensions.EnableNBExtensionApp()
    E.enable_nbextension('usability/sphinx-markdown/main')

Save, and reload. Then test it with a markdown cell like:

For more information, see, :ref:`installing IPython/Jupyter for Music21 <installIPython>`.

And you should get this output:

For more information, see,
:ref:`installing IPython/Jupyter for Music21 <installIPython>`. :-)