.. This is part of the Zrythm Manual.
   Copyright (C) 2020 Alexandros Theodotou <alex at zrythm dot org>
   See the file index.rst for copying conditions.

.. _piano-roll:

Piano Roll
==========

The piano roll is the main editor for editing MIDI regions.

.. image:: /_static/img/piano-roll.png
   :align: center

It consists of the toolbar discussed in :ref:`editor-toolbar`
at the very top, a smaller space containing extra controls, the
ruler discussed in :ref:`editor-ruler`, the piano roll keys
on the left, the piano roll (MIDI) arranger on the right
and the MIDI note velocity editor at the bottom.

Additional Controls
-------------------
The piano roll contains the following additional controls.

.. image:: /_static/img/piano-roll-controls.png
   :align: center

Drum view
  Enabling this will change the display of the arranger into
  a drum editor view, where each MIDI note is drawn as a
  diamond and the piano roll keys display the name of each
  drum.

.. note:: The drum view is not operational at the moment.

Listen to notes
  Enabling this will play back each note as you drag it inside
  the piano roll. This is useful if you want to `hear` what
  you are doing.

.. _piano-roll-keys:

Piano Roll Keys
---------------
These are the keys corresponding to each key found on a piano.

.. image:: /_static/img/piano-roll-keys.png
   :align: center

Clicking on each key allows you to listen to it, much like
pressing a key on a real piano.

A label for each key is shown on the left side of the
black/white keys, in addition to any highlighting
(if selected).
See :ref:`chord-highlighting` for more information.

.. tip:: The zoom level can be changed by holding down
  :zbutton:`Ctrl` and :zbutton:`Shift` and scrolling.

MIDI Arranger
-------------
The MIDI arranger refers to the arranger section of the piano
roll.

.. image:: /_static/img/midi-arranger.png
   :align: center

The MIDI arranger contains MIDI notes drawn as rectangles
from their start position to their end position. Zrythm
will send a MIDI note on signal when the start position
of a note is reached, and a note off signal when the end
position of a note is reached.

Editing inside the MIDI arranger is covered in
:ref:`edit-modes` and :ref:`common-operations`.

Velocity Editor
---------------
There is another arranger at the bottom of the MIDI arranger
for editing the velocity of each note.

.. image:: /_static/img/velocity-editor.png
   :align: center

Velocity refers to the force with which a note is played.
Each instrument handles various velocities for the same note
differently, but generally a higher velocity will result in
a louder or `stronger` note. Velocities are useful for adding
expression to melodies.

The velocity of each note is drawn as a bar, where higher
means a larger value. Clicking and dragging the tip of each
velocity bar allows you to change it.

.. tip:: You can also edit multiple velocities at once by
  selecting multiple MIDI notes before editing a velocity
  bar.

The :ref:`ramp-mode` can also be used in the velocity editor to
`ramp` velocities.

.. image:: /_static/img/ramp-tool.png
   :align: center

Context Menu
------------
TODO

Event Viewer
------------
The event viewer in the piano roll is similar to the
timeline event viewer discussed in
:ref:`timeline-event-viewer`.

.. image:: /_static/img/event-viewer-piano-roll.png
   :align: center

It displays information about each MIDI note in the MIDI
arranger.
