.. Lento documentation master file, created by
   sphinx-quickstart on Fri May 31 17:18:47 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

.. image:: pic/logo.png
   :width: 300
   :alt: Lento

Lento is a highly minimalist and Pythonic package for compiling Lilypond sheet music. The entire API consists of only 2 objects: a class ``Part`` which represents a single instrument, and a main processing function ``proc`` which generates the final outputs (See :ref:`quick examples<quickexamples>` below)!

Installation
------------

Lento requires Python 3.5 or later:

.. code-block::

    ~$ python --version
    Python 3.10.12

Lento requires LilyPond for compiling the final sheet music.
Make sure `Lilypond <http://lilypond.org/download.html>`_ is installed and callable from the commandline:

.. code-block::

    ~$ lilypond --version
    GNU LilyPond 2.22.2


Lento is on `Pypi <https://pypi.org/project/lento/>`_, so simply use pip to install it:

.. code-block::

    ~$ python -m pip install lento
    ~$ python -c "import lento; print(lento.version)"
    '190624'


.. _quickexamples:

First Impressions
-----------------

Start Python, import Lento and print some notes:

.. code-block::

    from lento import *

    proc(Part({"note": range(60, 72), "onset": range(12)}))

.. image:: pic/readme-example.jpg

If you want to use two instruments instead of just one, simply pass a list of parts to the processor function:

.. code-block::

    proc(
        [
            Part({"note": range(72, 84), "onset": range(12)}),
            Part({"note": range(67, 79), "onset": range(12)})
        ]
    )

.. image:: pic/readme-example2.jpg

We can also assign specific durations to each onset, if the durations should not be the difference between two neighbor onsets:

.. code-block::

    from random import choices

    ds = choices([pow(x, -1) for x in range(1, 7)], k=12)
    print("Durations:", ds)

    proc(
        [
            Part({
                "note": range(72, 84),
                "onset": range(12),
                # Every onset gets the duration of a sixteenth note
                "duration": {o: 0.25 for o in range(12)}
            }),
            Part({
                "note": range(67, 79),
                "onset": range(12),
                # Randomly chosen duration for each onset
                "duration": {o: ds[o] for o in range(12)}
            })
        ]
    )

    Durations: [0.2, 0.25, 0.5, 0.5, 0.2, 0.3333333333333333, 0.2, 1.0, 0.16666666666666666, 1.0, 0.5, 0.3333333333333333]

.. image:: pic/quick-examples-random-durations.jpg

To have more than one voice in each part, pack multiple pitch and onset collections in a list:

.. code-block::

    proc(
        [
            Part({"note": [range(72, 84), range(65, 77)], "onset": [range(12)] * 2}),
            Part({"note": [range(60, 72), range(67, 79)], "onset": [range(12)] * 2})
        ]
    )

.. image:: pic/readme-example3.jpg

Simple and pythonic!

.. toctree::
   :maxdepth: 2

   doc
   examples
   Repository <https://codeberg.org/lento>

`Lento is hosted on Codeberg. <https://codeberg.org/Lento>`_