manual.docbook

<?xml version="1.0" encoding="UTF-8"?> <!-- -*- mode:nxml; indent-tabs-mode:nil; fill-column:80; -*- -->
  <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
                      "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book id="Hydrogen-manual" lang="en">

  <bookinfo>
    <title>Hydrogen v1.2.3 Manual</title>
    <authorgroup>
      <author>
        <firstname>Antonio</firstname>
        <surname>Piraino</surname>
      </author>
      <author>
        <firstname>Alessandro</firstname>
        <surname>Cominu</surname>
      </author>
      <author>
        <firstname>Thijs</firstname>
        <surname>Van Severen</surname>
      </author>
      <author>
        <firstname>Sebastian</firstname>
        <surname>Moors</surname>
      </author>
      <author>
	    <firstname>Colin</firstname>
        <surname>Evans</surname>
      </author>
      <author>
	    <firstname>Philipp</firstname>
        <surname>Müller</surname>
      </author>
    </authorgroup>

    <subtitle>2024-01-12</subtitle>

    <abstract>
      <para>Hydrogen is a software synthesizer which can be used alone,
      emulating a drum machine based on patterns, or via an external <abbrev>MIDI</abbrev>
      keyboard/sequencer software. Hydrogen runs on Linux, Mac OS X and Windows.</para>
    </abstract>
  </bookinfo>

  <part id="part.1">
    <title>Introduction</title>

    <chapter id="chpt.download">
      <title>Download</title>

      <para>
        You can download Hydrogen from 
        <ulink url="http://www.hydrogen-music.org">http://www.hydrogen-music.org</ulink>.  
        On the <ulink url="http://hydrogen-music.org/downloads/">Downloads</ulink>
        page you can find several binaries (installers) for macOS, Windows, and
        Linux. 
      </para>

      <note>
        <para>
          From <emphasis role="bold">MacOS Big Sur</emphasis> onwards you may
          require some extra steps to run Hydrogen on you computer. <ulink url="https://github.com/hydrogen-music/hydrogen/wiki/Running-Hydrogen-on-macOS">This
          page</ulink>
          of the Hydrogen Wiki will guide you through this process step by step.
        </para>
      </note>
    </chapter>

    <chapter id="chpt.compilation">
      <title>Build</title>

      <para>
        As operation systems and build environments change more often and
        totally independent from Hydrogen, all build instructions can be found
        in our (more dynamic) Github Wiki:
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="https://github.com/hydrogen-music/hydrogen/blob/master/INSTALL.md">
                Linux
              </ulink>
            </emphasis>
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="https://github.com/hydrogen-music/hydrogen/wiki/Building-Hydrogen-from-Source-(macOS)">
                macOS
              </ulink>
            </emphasis>
          </para>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">
              <ulink url="https://github.com/hydrogen-music/hydrogen/wiki/Building-Hydrogen-from-source-(Windows)">
                Windows
              </ulink>
            </emphasis>
          </para>
        </listitem>
      </itemizedlist>
      
      <tip>
        <para>
          These instructions may not be cutting-edge or might even fail on your
          particular system and setup. That is most likely because the
          development team uses and has access to just a small subset of
          systems.
        </para>
        <para>
          The <ulink
          url="https://github.com/hydrogen-music/hydrogen/blob/master/.appveyor.yml">
          AppVeyor build pipelines</ulink> used to create the Hydrogen releases
          might get you back on track. But you can always use the issues or
          discussions on Github or our mailing list to ask questions.
        </para>
      </tip>

    </chapter>

    <chapter id="chpt.keyboard_and_mouse">
      <title>Keyboard and Mouse</title>
      <para>
        The Hydrogen user interface is designed so that it can be
        used entirely with the mouse, with the exception of text entry.
      </para>

      <para>
        Most actions are performed with the left mouse button (or mouse wheel)
        and implement what should be the most obvious behaviour for any
        control. The right mouse button may sometimes perform an alternate
        action or brings up a context menu. Some common controls also have
        alternate actions accessed by clicking while holding a modifier key:
      </para>

      <itemizedlist>
	    <listitem>
	      <para>
	        <keycap>Ctrl</keycap> + <emphasis>left click</emphasis> : restore default value of knob or fader.
          </para>
        </listitem>
        <listitem>
	      <para>
	        <keycap>Shift</keycap> + <emphasis>left click</emphasis> : bind a
	        <link linkend="chpt.midi.controlling.events"><abbrev>MIDI</abbrev>
	        Event</link> to <abbrev>MIDI</abbrev>-learnable widget (see <xref
	        linkend="chpt.midi.controlling.learnable"/>).
          </para>
        </listitem>
        <listitem>
	      <para>
	        <keycap>Shift</keycap> + <emphasis>mouse wheel</emphasis>|<keycap>↑</keycap>|<keycap>↓</keycap> : change values of rotaries and faders at a faster pace.
          </para>
        </listitem>
      </itemizedlist>

      <para>
        All rotaries and faders can also be set by using the keyboard. First, you have to click the widget for it to be focussed, indicated by a coloured highlight (orange per default). Now, you can enter numerical input via your keyboard. All numbers and dots are concatenated. If you want to reset your input or start a different one you can either press <keycap>ESC</keycap> or wait a couple of seconds.
      </para>

      <sect1>
        <title>
          Keyboard usage in Editors
        </title>
        
        <para>
          The keyboard can also be used for navigating and editing in
          the <link linkend="chpt.pattern_editor">Pattern</link> and <link linkend="chpt.song_editor">Song Editors</link>, using a combination of 
          <itemizedlist>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap></emphasis> : move the
                keyboard input cursor's position, or adjust values under
                the cursor.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>Shift</keycap> + <keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap></emphasis> :
                can be used to make selections of notes or pattern
                groups as if the mouse had been dragged over them.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>Enter</keycap> and <keycap>Return</keycap></emphasis> : generally
                performs the same action as a mouse click, but can also
                start or end a move (or copy) of items in the same way
                a mouse drag would.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>Tab</keycap> and <keycap>Shift</keycap> + <keycap>Tab</keycap></emphasis> : move
                between the Pattern, Song and Note Property Editor.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>Delete</keycap></emphasis> :
                delete notes or patterns.
              </para>
            </listitem>
            <listitem>
              <para>
                <emphasis role="bold"><keycap>Esc</keycap></emphasis> :
                cancels an ongoing selection, move or copy.
              </para>
            </listitem>
          </itemizedlist>
        </para>

        <note>
	      <para>
            The keyboard input cursor is hidden from view until one of
            the above keys is pressed. This keeps the display clear and
            uncluttered when using the mouse. You can alter this default behavior in the <link linkend="chpt.preferences.general_tab">General tab</link> of the Preferences.
	        
          </para>
        </note>
        <para>
          Most other keys on the keyboard can be used to play <link
          linkend="def.sample">samples</link> (see <xref
          linkend="chpt.overview.virtual_keyboard"/>).
        </para>
      </sect1>
    </chapter>


</part>

<part id="part.using_hydrogen">
    <title>Using Hydrogen</title>

    <chapter id="chpt.overview">
      <title>Overview</title>

      <sect1 id="chpt.overview.gui">
        <title>Main User Interface</title>
        
        <figure id="fig.UI_overview">
          <title>The Main UI in Single Pane mode</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/GUI_Sections_0.9.5_v2.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The Main UI comes in 2 flavors : the (classic) Single Pane mode (ideal for
        large- and medium size screens), and the Tabbed mode (optimized for netbook screen 
        sizes).
        </para>

        <tip>
	      <para>
	        You can switch between these two modes in the <link linkend="chpt.preferences.appearance_tab.interface">Interface</link> tab of the Appearance tab in the Preferences.
          </para>
        </tip>

        <para>
          Below you can see the main UI split up in 5 parts: the <link linkend="chpt.main_menu">Main Menu</link>, <link linkend="chpt.main_toolbar">Main 
          Toolbar</link>, <link linkend="chpt.song_editor">Song Editor</link>, <link linkend="chpt.pattern_editor">Pattern Editor</link> and the <link linkend="chpt.instrument_editor">Instrument</link> and <link linkend="chpt.sound_library">Sound Library Editor</link>.
          These sections will be explained in detail further down in this
          manual.
        </para>
        
        <figure id="fig.tabbed_UI_overview">
          <title>The Main UI in Tabbed mode</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/MainUI_tabbed.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </sect1>
      
      <sect1 id="chpt.overview.drumkits" xreflabel="Drumkit Concept">
        <title>Drumkit Concept</title>
        
        <para>Let's start with a little history on the concept of Drumkits within in Hydrogen. It began as a
        dedicated drum machine but has evolved into a versatile <link linkend="def.sample">sample</link>-based sound synthesizer/sequencer 
        that is capable of generating and manipulating all sorts of sounds. Hence the original 
        "Drumkit" terminology is slightly misleading. You can load any kind of sound into a
        "Drumkit" and manipulate that sound just like playing a regular synthesizer. This is 
        also the main reason why the <link linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link> was introduced.
        </para>

        <para>
          To sum it up, nowadays a Drumkit is a collection of a number
          of instruments (snare, kick, sampled voice, bass sound ...), using one or more <link linkend="def.component">components</link> which each can consist of multiple
        <link linkend="def.layer">layered</link> samples.
        </para>

        <tip>
	      <para>
	        In case you are not familiar with the world of sound synthesis, you can check out the <link linkend="glossary">Glossary</link> for a number of useful definitions.
          </para>
        </tip>

        <para>
          Drumkits can most easily be loaded by right-clicking their name in the <link linkend="chpt.sound_library">Sound Library</link>. Once loaded its name will be displayed in the <link linkend="chpt.pattern_editor">Pattern Editor</link>. All changes done to the kit, like altering parameters and adding or removing samples or instruments, are stored in the current song. They need to be <link linkend="sect.main_menu.drumkits.save">saved</link> to the drumkit in case you want them to persist and to be applicable to other songs as well. The actions available in the <link linkend="sect.main_menu.drumkits">Drumkits</link> section of the main menu do act on the kit associated with the current song. All options available through the Sound Library on the other hand soley apply to the stock kits. So, reloading the current drumkit will overwrite your local changes in the song using the default parameters stored in the kit's <filename>drumkit.xml</filename> file and altering the current kit's properties via the Sound Library does only affect the stock kit and <emphasis>not</emphasis> the one associated with your current song.
        </para>

      </sect1>

      <sect1 id="chpt.overview.virtual_keyboard" xreflabel="Virtual Keyboard">
	    <title>Virtual Keyboard</title>

        <para>
	      For quick checks and recording (or in case you do not have a
	      <abbrev>MIDI</abbrev> device at hand), you can also use Hydrogen's
	      Virtual Keyboard. It emulates note triggering via
	      <abbrev>MIDI</abbrev> <emphasis>NOTE_ON</emphasis> events (see <xref
	      linkend="chpt.midi.note"/>).
        </para>

        <note>
          <para>
            Key strokes of the Virtual Keyboard don't trigger <link
            linkend="chpt.midi.controlling">Actions</link> associated with
            <emphasis>NOTE_ON</emphasis> events.
          </para>
        </note>
        
        <para>
          The figure below depicts which keyboard key is associated with which
          instrument number in Input Mode <option>Drumkit</option> or instrument
          pitch in Input Mode <option>Instrument</option>.
        </para>

        <informalfigure id="fig.letters_keyboard">
          <mediaobject>
            <textobject>
              <phrase>
                Picture illustrating the mapping of Hydrogen's Virtual Keyboard to
                the layout of the computers' keyboard.
              </phrase>
            </textobject>
            <imageobject>
              <imagedata fileref="virtual_keyboard.png" format="PNG" width="100%"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <note>
          <para>
            When using German or French keyboard layout the overall mapping is still the same.
          </para>
        </note>

      </sect1>

      <sect1 id="chpt.overview.recording">
	    <title>Recording in Hydrogen</title>

        <para>
          In addition to manually program patterns using mouse and keyboard you
          can also record one or multiple patterns. You can do so using an
          external <link linkend="chpt.midi.note"><abbrev>MIDI</abbrev>
          device</link>, like an e-drum, or use the <link
          linkend="chpt.overview.virtual_keyboard">Virtual Keyboard</link>
          provided by Hydrogen.
        </para>

        <para>
          In order to start recording, first activate the record button 
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey record button with a red circle in its center.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/playerControlRecordButton.png" format="PNG"/>
          </imageobject>
         </inlinemediaobject>
in the <link linkend="sect.main_toolbar.transport_control">Main Toolbar</link> and afterwards press the 
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey play and pause button containing two vertical black lines
              (left) and a black triangle (right) pointing to the right.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/playerControlPlayButton.png" format="PNG"/>
          </imageobject>
          </inlinemediaobject>
          button located right next to it (like in a classical tape recorder). 
        </para>

        <para>
	      Using the playback mode of the <link linkend="chpt.song_editor">Song
	      Editor</link> you can choose between the following two scenarios. When
	      in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern
	      Mode</link> all inserted notes will be added to the pattern currently
	      selected in the <link
	      linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song
	      Editor. When, on the other hand, in <link
	      linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link> the
	      input notes will be added to the active pattern (the one the playhead
	      is located in and is currently used for playback). If several patterns
	      are selected in a single row, the input notes will only be added to
	      the pattern at the bottom.
        </para>

        <tip>
          <para>
            By <link linkend="chpt.song_editor.main_controls.pattern_editor_lock">locking</link> the Pattern Editor in Song Mode Hydrogen will automatically select the pattern recorded notes will be inserted to.
          </para>
        </tip>

        <note>
	      <para>
	        The incoming notes will be added in a non-destructive way. This means when attempting to add a notes at a position already containing one of equal pitch, the new note will be discarded and the old one kept.
          </para>
        </note>

        <informalfigure id="fig.overview.recording.punch_in">
          <mediaobject>
            <textobject>
              <phrase>
                Song ruler with a red rectangle indicating the punch in area.
              </phrase>
            </textobject>
            <imageobject>
              <imagedata fileref="punch_in.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>
          You can also limit patterns new notes will be recorded to by defining a continuous <emphasis role="bold">punch in</emphasis> area via right click and dragging the cursor to the right in the ruler of the <link linkend="chpt.song_editor">Song Editor</link>.
        </para>
        
      </sect1>
      
      <sect1 id="chpt.overview.session_management">
        <title>Session Management</title>

        <para>
          With Session Management you can easily restore complex sessions involving numerous applications including their particular state. Hydrogen does support some Session Management systems too.
        </para>

        <warning>
	      <para>
	        All the supported Session Management protocols are Linux only. There is no (tested) support for MacOS and Windows yet.
          </para>
        </warning>
        
        <itemizedlist>
	      <listitem>
	        <para>
	          <emphasis role="bold"><abbrev>NSM</abbrev></emphasis>:
              <ulink url="http://non.tuxfamily.org/nsm/API.html">Non Session Manager (<abbrev>NSM</abbrev>)</ulink> is of 2021 the de facto standard in Session Management tools within the Linux audio community and Hydrogen does over full support and compliance to its API.

              <tip>
	            <para>
	              We highly recommend using this protocol for Session Management.
                </para>
              </tip>
            </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold"><abbrev>LASH</abbrev></emphasis>:
              Hydrogen provides a basic support for <ulink url="http://lash.nongnu.org">LASH Audio Session Handler (<abbrev>LASH</abbrev>)</ulink>. This covers recalling the song used within the session but, unlike the NSM support, no recalling of the <abbrev>JACK</abbrev> connections and no per-session preferences.

              <note>
	            <para>
	              You have to activate <abbrev>LASH</abbrev> support in the <link linkend="fig.preferences.general_tab">General</link> tab of the Preference dialog in order to use it.
                </para>
              </note>
            </para>
          </listitem>
        </itemizedlist>

        <sect2 id="chpt.overview.session_management.nsm">
	      <title>NSM</title>

          <para>
            Hydrogen will be under session management if you start it via a <abbrev>NSM</abbrev> server application, like <ulink url="https://github.com/Houston4444/RaySession">RaySession</ulink>. You can easily check whether Hydrogen is aware of the session by checking out the <option>Project</option> option of the <link linkend="chpt.main_menu">Main Menu</link> as some action will have changed in order to comply to the <abbrev>NSM</abbrev> API.
          </para>
          
          <itemizedlist>
	        <listitem>
              <para>
	            <emphasis role="bold">Replace With New Song</emphasis>
                instead of <link linkend="sect.main_menu.projects.new">New</link>. Replaces the song associated with the session by an empty one.
              </para>
            </listitem>
	        <listitem>
              <para>
	            <emphasis role="bold">Import Into Session</emphasis>
                instead of <link linkend="sect.main_menu.projects.open">Open</link>. Replaces the song associated with the session by a song of your choice.
              </para>
            </listitem>
	        <listitem>
              <para>
	            <emphasis role="bold">Import Recent Info Session</emphasis>
                instead of <link linkend="sect.main_menu.projects.open_recent">Open Recent</link>. Replaces the song associated with the session by one of the recently used songs.
              </para>
            </listitem>
	        <listitem>
              <para>
	            <emphasis role="bold">Export From Session As</emphasis>
                instead of <link linkend="sect.main_menu.projects.save_as">Save As</link>. Stores the song associated with the session at a location of your choice as <link linkend="chpt.file_types.h2song">.h2song</link> file.

                <note>
	              <para>
	                In contrast to the <emphasis>Save As</emphasis> command the underlying path of the current song will not be changed. All subsequent <emphasis>Save</emphasis> actions will store the current state of the song to the file in the session folder and <emphasis role="bold">not</emphasis> to the path of the exported file.
                  </para>
                </note>
              </para>
            </listitem>
          </itemizedlist>

          <para>
	        Both the song and the preferences associated with the session will be stored in a session folder called <filename>Hydrogen.*</filename>. In addition, the drumkit (and its samples) used with the song will linked into the session folder as well. If the link is replaced by a folder containing a valid drumkit, this one will be used over the system and user drumkits.

            <tip>
	          <para>
	            This allows you to create fully self sufficient backups of your Hydrogen session using <command>tar -chf</command>. These can even be ported and used on systems which do not have the required drumkits installed.
              </para>
            </tip>

            <warning>
              <para>
                Note that only the stock <link linkend="chpt.overview.drumkits">drumkit</link> loaded last will be linked in the session folder. In case you only alter instrument parameters or delete instruments or samples this will work perfectly fine. But as soon as you add instruments from other drumkits or external samples, the linked drumkit folder won't contain all samples required by your current song anymore. You need to <link linkend="sect.main_menu.drumkits.save">saved</link> the kit (or create a new one) in order to ensure consistency.
              </para>
            </warning>
          </para>
        </sect2>
      </sect1>

      <sect1 id="chpt.overview.cli">
	    <title>Command-line Options</title>

        <para>
	      After <link linkend="chpt.download">installing</link> Hydrogen on your system you can invoke it from the command-line with a number of different options.
      <screen>
<command>-h, --help                  Displays this help.</command>
<command>-v, --version               Displays version information.</command>
<command>-d, --driver &#60;Audiodriver&#62;  Use the selected audio driver (auto, jack, pulseaudio, ...)</command>
<command>-p, --playlist &#60;File&#62;       Load a playlist (*.h2playlist) at startup</command>
<command>-s, --song &#60;File&#62;           Load a song (*.h2song) at startup</command>
<command>-k, --kit &#60;DrumkitName&#62;     Load a drumkit at startup</command>
<command>-i, --install &#60;File&#62;        Install a drumkit (*.h2drumkit)</command>
<command>-V, --verbose &#60;Level&#62;       Level, if present, may be None, Error, Warning, Info, Debug</command>
<command>-L, --log-file &#60;Path&#62;       Alternative log file path</command>
<command>-T, --log-timestamps        Add timestamps to all log messages</command>
<command>-P, --data &#60;Path&#62;           Use an alternate system data path</command>
<command>    --config &#60;Path&#62;         Use an alternate config file</command>
<command>    --layout &#60;Layout&#62;       UI layout ('tabbed' or 'single')</command>
<command>-O, --osc-port &#60;int&#62;        Custom port for OSC connections</command>
<command>-n, --nosplash              Hide splash screen</command>
      </screen>

      <note>
        <para>
          Which audio drivers are supported depends on both your platform and its installed packages. Your local help message will display all available options.
        </para>
      </note>
      
        </para>
      </sect1>
    </chapter>

    <chapter id="chpt.preferences" xreflabel="Preferences">
      <title>Preferences</title>

      <para>Using this window most of the configuration options and customization can be altered. The Preferences Dialog can be accessed via the <parameter>Options</parameter> element in the <link linkend="chpt.main_menu">Main Menu</link>.</para>
      
      <sect1 id="chpt.preferences.general_tab">
        <title>General</title>
        
        <figure id="fig.preferences.general_tab">
          <title>The General Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/PreferencesGeneral_V3.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <itemizedlist>
	      <listitem>
	        <para>
	          <emphasis role="bold">Language</emphasis>:
              chooses one of the translations Hydrogen is available in.            
              <note>
	            <para>
	              For this setting to take effect you have to restart Hydrogen.
                </para>
              </note>

              <tip>
	            <para>
	              If your mother tongue is not available or the corresponding translation is flawed or incomplete, you would have an accessible way to contribute to Hydrogen at hand. Please see the <link linkend="sect.main_menu.info">About</link> dialog in the Info option of the Main menu for information of how to contact the Hydrogen dev team.
                </para>
              </tip>
  

            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Reopen last used song</emphasis>:
              determines whether Hydrogen will open the last used song during startup or an empty song instead.
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Reopen last used playlist</emphasis>:
              determines whether the last used <link linkend="chpt.playlist_editor">Playlist</link> will be loaded during startup or none at all.
              <tip>
	            <para>
	              This can come in handy when you are using Hydrogen live.
                </para>
              </tip>
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Use relative paths for playlist</emphasis>:
              specifies whether the paths stored in a <link linkend="chpt.file_types.h2playlist">.h2playlist</link> file will be absolute or relative to the <filename role="directory">playlist</filename> folder in the Hydrogen data
              directory (usually <filename role="directory">$HOME/.hydrogen/data/</filename>).

              <tip>
	            <para>
	              Using relative paths might be handy when using your playlist on different computers or user profiles.
                </para>
              </tip>
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Hide keyboard input cursor</emphasis>:
              hides the keyboard cursor until you press a key on you keyboard (see <xref linkend="chpt.keyboard_and_mouse" />). By enabling this feature you can switch to the look and feel of the interaction with the <link linkend="chpt.pattern_editor">Pattern Editor</link> and <link linkend="chpt.song_editor">Song Editor</link> prior to Hydrogen v1.1.
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Use LASH</emphasis>:
              enables <abbrev>LASH</abbrev> (<abbrev>LASH</abbrev> Audio Session Handler) support within Hydrogen. This allows you to recover a particular song associated with a session.

              <tip>
	            <para>
	              You may consider using the more advanced <link linkend="chpt.overview.session_management.nsm">NSM</link> support of Hydrogen which gives you many additional features, like restoring all <abbrev>JACK</abbrev> connections or creating a per-session configuration.
                </para>
              </tip>
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Beat counter drift compensation in 1/10 ms</emphasis>:
              allows you to compensate for system latency. The provided number will be added to each consecutive triggering of the <link linkend="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">Beat Counter</link>. The allowed range is from <option>-200</option> to <option>200</option>.

              <tip>
	            <para>
	              This is quite handy if you are using different sound cards or external <abbrev>MIDI</abbrev> devices, like a keyboard or an e-drum, with mismatching clocks.
                </para>
                <para>
	              In order to find useful values for these, you will need to take some
        time to play with it.  Also, you may want different values depending on
        the speed of your hardware, audio devices, drivers, etc.  Using the
        Beat Counter effectively requires practice.
                </para>
              </tip>
              
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Beat counter start offset in ms</emphasis>:
              sets the time between the
              Beat Counter's last input stroke and when the song starts playing. Its allowed range is from <option>-500</option> to <option>500</option>.

              <note>
	            <para>
	              The Beat Counter has to be set to <emphasis role="bold">Set <abbrev>BPM</abbrev> and play</emphasis> - 
                  <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing a "P".
            </phrase>
          </textobject>
                    <imageobject>
                      <imagedata fileref="generated_en/btn_bc_set_play_on.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
          should be displayed in the bottom right corner - for this setting to take effect.
                </para>
              </note>
              
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Maximum number of bars</emphasis>:
              sets the maximum number of supported bars/patterns for a single song. Its allowed range is from <option>1</option> to <option>800</option>.
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Maximum number of layers</emphasis>:
              sets the maximum number of <link linkend="def.layer">layers</link> for a single instrument. Its allowed range is from <option>16</option> to <option>8192</option>.
              <note>
	            <para>
	              For this setting to take effect you have to restart Hydrogen.
                </para>
              </note>
            </para>
            
          </listitem>
	      <listitem id="chpt.preferences.general_tab.autosaves">
	        <para>
	          <emphasis role="bold">Numbers of autosaves per hour</emphasis>:
              sets how often Hydrogen will generate a backup of your current song in case it contains any unsaved modifications. In case there is an autosave file with a more recent timestamp next to a song, Hydrogen will ask you upon opening whether to restore the unsaved changes or to load the raw song.

              <note>
                <para>
                  These autosave files will be hidden and contain an additional suffix "autosave". E.g. if your current song is called <filename>example.h2song</filename> the backup will be stored in <filename>.example.autosave.h2song</filename> within the same directory. But you do not need to be careful when chosing a song name. Hydrogen will take care of finding a filename for the backup not existing yet.
                </para>
              </note>
            </para>
            
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Path to the Rubberband command-line utility</emphasis>:
              sets the absolute path to the <command>rubberband</command> command line interface (CLI) Hydrogen will use for stretching samples in the <link linkend="chpt.sample_editor.pitch">Sample Editor</link>.
              <note>
	            <para>
	              This option is only available if your version of Hydrogen does <emphasis>not</emphasis> already has Rubber Band support compiled into it. If it does and the option is hot shown, everything is already configured and you don't have to worry about Rubber Band at all.
                </para>
              </note>

              <tip>
	            <para>
	              If you are using Ubuntu, you can install Rubber Band from the Software Center 
                  via the package <option>rubberband-cli</option>.  For other Linux distros please check your package manager and for other platforms
                  please check <ulink url="http://breakfastquay.com/rubberband/">the Rubber Band site
                  </ulink>.
                </para>
              </tip>

              <tip>
	            <para>
                  If Rubber Band is installed and configured correctly, you will see an extra button
                  <inlinemediaobject>
          <textobject>
            <phrase>
              Grey vertical button containing the characters "R", "U", and "B"
              in adjacent lines.
            </phrase>
          </textobject>
                    <imageobject>
                      <imagedata fileref="generated_en/playerControlRubberbandButton.png" format="PNG" />
                    </imageobject>
                  </inlinemediaobject>
          button in the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Main Toolbar</link>. You can use this behavior to verify your configuration.
                </para>
              </tip>
          
            </para>
          </listitem>
        </itemizedlist>

      </sect1>

      <sect1 id="chpt.preferences.audio_tab">
        <title>Audio System</title>

        <figure id="fig.preferences.audio_tab">
          <title>The Audio System Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/PreferencesAudioSystem_V3.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <itemizedlist>
	      <listitem>
	        <para>
	          <emphasis role="bold">Audio System</emphasis>: let's you choose the audio driver used by Hydrogen to connect to your computer's sound card.
            </para>

            <para>
	          Available options:
            </para>
            <itemizedlist>

              <listitem>
                <para><option>Auto</option>: Hydrogen will try a
                number of different drivers in a predetermined, OS-dependent order, choose the
                first working one, and display the result.

                <tip>
	              <para>
	                This option is recommended for beginners.
                  </para>
                </tip>
                
                </para>
              </listitem>

              <listitem id="sect.preferences.jack">
                <para><option>JACK</option>: The <abbrev>JACK</abbrev> driver is a
                professional audio server which permits very low lag and exchanges
                with other audio software. The <abbrev>JACK</abbrev>
                server will start automatically if not already running.
                </para>
              </listitem>
              <listitem>
                <para><option>ALSA</option>: The widely adopted
                Linux standard audio driver.</para>
              </listitem>

              <listitem>
                <para><option>OSS</option>: The <abbrev>OSS</abbrev> audio driver
                uses <filename>/dev/dsp</filename> and it's based on the <abbrev>OSS</abbrev> interface which is supported
                by the vast majority of sound cards available for Linux; this said,
                the use of this audio driver blocks <filename>/dev/dsp</filename> until Hydrogen is
                closed i.e. unusable by any other software. Use it as last
                resort.
                </para>
              </listitem>

              <listitem>
                <para><option>PortAudio</option>: An open-source
                multi platform audio driver interface layer.</para>
              </listitem>

              <listitem>
                <para><option>CoreAudio</option>: A driver for MacOS.</para>
		      </listitem>

              <listitem>
                <para><option>PulseAudio</option>: A driver for the cross platform
                PulseAudio sound server.</para>
		      </listitem>
            </itemizedlist>

          </listitem>


          <listitem>
            <para>
              <emphasis role="bold">Host API</emphasis> (PortAudio only): some
              systems (notably Windows) have more than one native
              way for applications to interact with audio hardware (APIs), and not all audio
              devices are supported by all APIs. If you don't find
              your sound device in the device list, try changing the
              Host API setting.
            </para>
          </listitem>

          <listitem>
	        <para>
	          <emphasis role="bold">Device</emphasis>:
              specifies the particular sound card the audio driver will use.
            </para>
            <note>
              <para>
                The Preferences dialog does not support hot plugging. In case
                you connected your device while the dialog was already opened,
                be sure to close and reopen it again.
              </para>
            </note>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Buffer size</emphasis>:
              specifies the size of the batch of time Hydrogen will
              process in one run. Supported values are from
              <option>100</option> to <option>5000</option>, although
              this can vary depending on audio system and sound
              device.
                </para>
                <para>
                  In general, selecting a smaller buffer size will
                  allow the audio system to reduce latency (the lag
                  between hitting a key and the sound being played),
                  but can lead to increased likelihood of audio
                  glitches.
                </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Sample rate</emphasis>:
              specifies the number of data points the audio signal will contain within one second.
              <note>
	            <para>
	              If you are using the <abbrev>JACK</abbrev> audio driver, the sample rate can not be altered from within Hydrogen and the audio driver
            configuration should happen before starting the <abbrev>JACK</abbrev> server.
                </para>
              </note>
            </para>
          </listitem>
          
          <listitem id="sect.preferences.jack.track_output">
            <para><emphasis role="bold">Track output</emphasis>: determines which audio settings will be applied to the outgoing
            audio of the per-instrument <abbrev>JACK</abbrev> output ports.</para>

            <para><option>Post-Fader</option>:</para>
            <itemizedlist>
              <listitem><para>note <link linkend="chpt.pattern_editor.note_properties.velocity">velocity</link> and <link linkend="chpt.pattern_editor.note_properties.pan">pan</link></para></listitem>
              <listitem><para><link linkend="chpt.instrument_editor.layers.controls.layer_gain">layer gain</link></para></listitem>
              <listitem><para>component <link linkend="chpt.instrument_editor.layers.controls.component_gain">gain</link> and <link linkend="chpt.mixer.component_strips.fader_and_lcd">volume</link></para></listitem>
              <listitem><para>instrument <link
              linkend="chpt.instrument_editor.gain_and_mute_group">gain</link>, <link
              linkend="chpt.instrument_editor.general.sustain">sustain</link>,
              <link linkend="chpt.mixer.channel_strips.pan">pan</link>, and
              <link
                  linkend="chpt.mixer.channel_strips.fader_and_lcd">volume</link></para></listitem>
              <listitem>
                <para>
                  <link linkend="sect.song_editor.automation_path">automation
                  path</link> and <link
                  linkend="chpt.mixer.master_fader_strip">velocity humanization</link>
                </para>
              </listitem>
            </itemizedlist>
            <para><option>Pre-Fader</option>:</para>
            <itemizedlist>
              <listitem><para>note <link linkend="chpt.pattern_editor.note_properties.velocity">velocity</link> and <link linkend="chpt.pattern_editor.note_properties.pan">pan</link></para></listitem>
              <listitem><para><link linkend="chpt.instrument_editor.layers.controls.layer_gain">layer gain</link></para></listitem>
              <listitem>
                <para>instrument <link
                linkend="chpt.instrument_editor.general.sustain">sustain</link>
                </para>
              </listitem>
              <listitem>
                <para>
                  <link linkend="sect.song_editor.automation_path">automation
                  path</link> and <link
                  linkend="chpt.mixer.master_fader_strip">velocity humanization</link>
                </para>
              </listitem>
            </itemizedlist>

            <note>
              <para>
                This option is only available if the <abbrev>JACK</abbrev> audio driver was selected and it will only take effect if the <emphasis role="bold">Connect to default <abbrev>JACK</abbrev> output ports</emphasis> option is checked.
              </para>
            </note>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Connect to default <abbrev>JACK</abbrev> output
            ports</emphasis>: connects the main stereo <abbrev>JACK</abbrev> output ports of the <link linkend="chpt.mixer.master_fader_strip">Master Fader Strip</link> to
            the default <abbrev>JACK</abbrev> input ports of your system
            (<emphasis>system:playback_1</emphasis> and
            <emphasis>system:playback_2</emphasis>). This will be done every time Hydrogen
            starts up or the <abbrev>JACK</abbrev> audio driver is restarted.</para>

            <note>
              <para>
                This option is only available if the <abbrev>JACK</abbrev> audio driver was selected.
              </para>
            </note>

          </listitem>
          <listitem id="sect.preferences.jack.per_instrument_outs">
            <para><emphasis role="bold">Create per-instrument
            <abbrev>JACK</abbrev> output ports</emphasis>: in addition to the main stereo output
            Hydrogen will register <abbrev>JACK</abbrev> output ports for every single
            instrument.
            </para>

            <tip>
	          <para>
	            This can be useful if you want to add effects to a
            single instrument with jack-rack for example.
              </para>
            </tip>

            <note>
              <para>
                This option is only available if the <abbrev>JACK</abbrev> audio driver was selected.
              </para>
            </note>
            
            <warning>
              <para>
	            There are no <abbrev>JACK</abbrev> output ports for the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link> and the <link linkend="chpt.song_editor.playbackTrack">Playback Track</link>. Their audio is only available via the main stereo output ports of Hydrogen.
              </para>
            </warning>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Enable <link
	          linkend="sect.main_toolbar.jack_control"><abbrev>JACK</abbrev>
	          Timebase support</link></emphasis>: whether Hydrogen will respond to
	          or ignore the incoming tempo and bar, beat, tick (BBT) position
	          information sent by the <abbrev>JACK</abbrev> server.

              <tip>
	            <para>
	              Some <abbrev>JACK</abbrev> clients are not well written or have fallen into despair. As a result Hydrogen could receive nuisance signals messing up its playback. If you encounter weird jumps in the transport position and/or Hydrogen is out of sync after relocating the transport position, you might try to uncheck this option.
                </para>
              </tip>
              
            <note>
              <para>
                This option is only available if the <abbrev>JACK</abbrev> audio driver was selected.
              </para>
            </note>
            </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Apply and restart output</emphasis>:
              restarts the audio driver and makes all settings specified above take effect without closing and reopening the entire Preferences dialog.
            </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Polyphony</emphasis>:
              specifies the maximum number of notes played simultaneously. Supported values are from <option>1</option> to <option>512</option>.
              <tip>
	            <para>
	              Depending on your CPU Hydrogen might be overrunning your audio driver due to this parameter.
                </para>
              </tip>
            </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Metronome volume</emphasis>:
              sets the volume of the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link>. Supported values are from <option>1</option> to <option>100</option>.
            </para>
          </listitem>
          <listitem>
	        <para>
	          <emphasis role="bold">Interpolate resampling</emphasis>:
              specifies the type of resampling applied if a <link linkend="def.sample">sample</link> does not use the same Sample Rate as Hydrogen.
            </para>
          </listitem>
        </itemizedlist>
        
      </sect1>

      <sect1 id="chpt.preferences.midi_tab">
        <title>MIDI System</title>

        <figure id="fig.preferences.midi_tab">
          <title>The MIDI System Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/MidiSystem_V2.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <itemizedlist>
	      <listitem>
	        <para>
	          <emphasis role="bold"><abbrev>MIDI</abbrev> driver</emphasis>:
              selects the <abbrev>MIDI</abbrev> driver Hydrogen will use to
              receive and send <abbrev>MIDI</abbrev> messages.
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Input</emphasis>:
              selects the device/port Hydrogen will expect <abbrev>MIDI</abbrev>
              messages to receive from (see <xref linkend="chpt.midi.input"/>).
            </para>
            

            <note>
              <para>
                For now the list of available <emphasis
                role="bold">Input</emphasis> and <emphasis
                role="bold">Output</emphasis> MIDI devices/ports is compiled for
                the current MIDI driver when opening the Preferences dialog. If
                you switch to another driver or connect a device while the
                dialog is already open, be sure to close and reopen it again in
                order to have an updated list.
              </para>
            </note>
          </listitem>
	      <listitem id="chpt.preferences.midi_tab.output">
	        <para>
	          <emphasis role="bold">Output</emphasis>:
              selects the device/port Hydrogen will send <abbrev>MIDI</abbrev>
              messages to (see <xref linkend="chpt.midi.output"/>).
            </para>
          </listitem>
	      <listitem id="chpt.preferences.midi_tab.channel">
	        <para>
	          <emphasis role="bold">Channel</emphasis>: specifies whether
	          Hydrogen should listen to <emphasis
	          role="bold">incoming</emphasis> <abbrev>MIDI</abbrev> messages on
	          one particular channel out of the 16 available ones or on all of
	          them.
            </para>
            <para>
              Outgoing <abbrev>MIDI</abbrev> traffic is not affected. The
              corresponding channels are set on a per-instrument basis in the
              <link
              linkend="chpt.instrument_editor.midi_out_settings">Instrument
              Editor</link>.
            </para>
          </listitem>
	      <listitem id="chpt.preferences.midi_tab.ignore_note_off">
	        <para>
	          <emphasis role="bold">Ignore note-off</emphasis>:
              specifies whether Hydrogen will respond to the <emphasis>NOTE_OFF</emphasis> <abbrev>MIDI</abbrev> messages.
              <note>
	            <para>
                  This makes better use of the drumkit samples used in Hydrogen when working with certain external <abbrev>MIDI</abbrev> devices. But it may also discard <emphasis>Cymbal choke</emphasis> messages in some e-drums.
                </para>
              </note>
            </para>
          </listitem>
	      <listitem>
	        <para>
	          <emphasis role="bold">Enable <abbrev>MIDI</abbrev> feedback</emphasis>:
              specifies whether Hydrogen will send a message about updated
              values every time a certain parameter is changed (see <xref linkend="chpt.midi.output.feedback"/>).
            </para>
          </listitem>
	      <listitem id="chpt.preferences.midi_tab.discard_messages">
	        <para>
	          <emphasis role="bold">Discard <abbrev>MIDI</abbrev> messages after action has been triggered</emphasis>:
              specifies whether a <abbrev>MIDI</abbrev> note - after performing the <link linkend="chpt.midi.controlling.actions">Actions</link> associated with it - should be played back or be discard.
            </para>
          </listitem>
	      <listitem id="chpt.preferences.midi_tab.input_as_output">
	        <para>
	          <emphasis role="bold">Use output note as input note</emphasis>:
              if checked the instrument mapped to an incoming
              <abbrev>MIDI</abbrev> note is determined by its <link
              linkend="chpt.instrument_editor.midi_out_settings"><abbrev>MIDI</abbrev>
              Out Settings</link> in the Instrument Editor. Otherwise, the <link
              linkend="chpt.midi.note.mapping">default <abbrev>MIDI
              mapping</abbrev></link> (based on the instrument order in the
              <link linkend="chpt.pattern_editor">Pattern Editor</link>) will be
              used (see <xref linkend="chpt.midi.note.mapping"/>).
              <note>
	            <para>
	              This option only takes effect if <emphasis role="bold">Input Mode</emphasis> in the <link linkend="sect.main_menu.options">Options</link> tab of the Main Menu is set to <option>Drumkit</option>.
                </para>
              </note>
            </para>
          </listitem>
        </itemizedlist>

        <para>
	      Using the table in the lower part of the tab you can associate <link linkend="chpt.midi.controlling.actions">Actions</link> provided by Hydrogen with incoming <abbrev>MIDI</abbrev> messages. How this is done will be explained in the <xref linkend="chpt.midi.controlling.actions"/>.
        </para>
        
     </sect1>

      <sect1 id="chpt.preferences.osc_tab">
        <title>OSC</title>

        <figure id="fig.preferences.osc_tab">
          <title>The OSC Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/PreferencesOSC.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

        <para>The <abbrev>OSC</abbrev> tab (<xref linkend="fig.preferences.osc_tab"/>) let's
        you modify all options associated with <abbrev>OSC</abbrev> (Open Sound Control) (see
        chapter <link linkend="chpt.osc">OSC API</link> for details).

        <note>
	      <para>
	        In order to see and access the <emphasis role="bold">Enable OSC feedback</emphasis> and <emphasis role="bold">Import port</emphasis> option, <emphasis role="bold">Enable OSC support</emphasis> has to be checked first.
          </para>
        </note>
        
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Enable OSC support</emphasis>: Allows
            Hydrogen to receive <abbrev>OSC</abbrev> commands send by external programs.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Enable OSC feedback</emphasis>: Hydrogen
            will broadcast <abbrev>OSC</abbrev> messages to all registered clients each time does
            change. A client can register to receive <abbrev>OSC</abbrev> messages by sending
            a message to Hydrogen previously. The <emphasis role="bold">state broadcast as feedback</emphasis> is
            composed of the following <abbrev>OSC</abbrev> paths:
            
            <itemizedlist>
              <listitem>
                <para><link linkend="chpt.osc.command.master_volume_absolute">/Hydrogen/<emphasis role="bold">MASTER_VOLUME_ABSOLUTE</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.toggle_metronome">/Hydrogen/<emphasis role="bold">TOGGLE_METRONOME</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.mute_toggle">/Hydrogen/<emphasis role="bold">MUTE_TOGGLE</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.strip_volume_absolute">/Hydrogen/<emphasis role="bold">STRIP_VOLUME_ABSOLUTE/X</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.strip_volume_relative">/Hydrogen/<emphasis role="bold">STRIP_VOLUME_RELATIVE/X</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.pan_absolute">/Hydrogen/<emphasis role="bold">PAN_ABSOLUTE/X</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.strip_mute_toggle">/Hydrogen/<emphasis role="bold">STRIP_MUTE_TOGGLE/X</emphasis></link></para>
              </listitem>
              <listitem>
                <para><link linkend="chpt.osc.command.strip_solo_toggle">/Hydrogen/<emphasis role="bold">STRIP_SOLO_TOGGLE/X</emphasis></link></para>
              </listitem>
            </itemizedlist>

            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Incoming port</emphasis>: Specifies the
            <abbrev>OSC</abbrev> port Hydrogen will be register to. Values up to <option>20000</option> are supported.</para>
          </listitem>
        </itemizedlist>
        </para>
        <note>
          <para>If the chosen <abbrev>OSC</abbrev> port is already occupied, Hydrogen will pick
          an alternative one on startup and displays it via a popup as well as
          in the <abbrev>OSC</abbrev> tab of the Preferences Dialog.
          </para>
        </note>
      </sect1>

      <sect1 id="chpt.preferences.appearance_tab">
        <title>Appearance</title>

        <para>
          The settings available in the <emphasis>Appearance</emphasis> tab let you modify the look of Hydrogen and are treated differently than the ones found in other tabs. While the latter are stored in the <filename>hydrogen.conf</filename> file in Hydrogen's data folder, the appearance is stored in <link linkend="chpt.file_types.h2theme">.h2theme</link> files in the dedicated <filename role="directory">theme</filename> subfolder. The idea is that while the remaining settings are tailored to your local setup, a theme is something that is easily portable. E.g. you can create a custom dark theme and share it with the Hydrogen community without them having to adopt it to their local setup.
        </para>

        <para>
          This can be done using the
          <inlinemediaobject>
            <textobject>
              <phrase>
                Grey record button with label "Export Theme".
              </phrase>
            </textobject>
            <imageobject>
              <imagedata fileref="generated_en/preferencesExportThemeButton.png" format="PNG"/>
            </imageobject>
          </inlinemediaobject>

          and
          
          <inlinemediaobject>
            <textobject>
              <phrase>
                Grey record button with label "Import Theme".
              </phrase>
            </textobject>
            <imageobject>
              <imagedata fileref="generated_en/preferencesImportThemeButton.png" format="PNG"/>
            </imageobject>
          </inlinemediaobject>
          
          buttons. All changes applied to a theme (unless indicated otherwise in the dialog) will take effect immediately. If you are satisfied with the result, accept the dialog by clicking the OK button to save it. If you, however, want to reset all options to their state encountered when opening the dialog or importing last theme, hit the 
          
          <inlinemediaobject>
            <textobject>
              <phrase>
                Grey record button with label "Reset Appearance Tab".
              </phrase>
            </textobject>
            <imageobject>
              <imagedata fileref="generated_en/preferencesResetThemeButton.png" format="PNG"/>
            </imageobject>
          </inlinemediaobject>

          button or close the dialog.
        </para>

        <sect2 id="chpt.preferences.appearance_tab.interface">
          <title>Interface</title>

          <figure id="fig.preferences.appearance_tab.interface">
            <title>The Interface Tab</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/preferencesInterfaceTab.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </figure>
          
          <para>
            The <emphasis>Interface</emphasis> tab covers the overall appearance of Hydrogen.
          </para>

          <itemizedlist>
	        <listitem>
	          <para>
	            <emphasis role="bold">Style</emphasis>:
                specifies a certain look of GUI elements, like menus, scrollbars, and dialog windows.

                <tip>
	              <para>
	                Using this option you might be able to better integrate Hydrogen into your operating system.
                  </para>
                </tip>
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Meters falloff speed</emphasis>:
                specifies how fast the visual update of the peak values shown in the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link>, <link linkend="chpt.mixer.component_strips">Component Channel Strips</link>, and <link linkend="chpt.mixer.master_fader_strip">Master Fader Strip</link> will be done.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Default interface layout</emphasis>:
                specifies whether the GUI of Hydrogen will be arranged in <link linkend="fig.UI_overview">Single Pane mode</link> or <link linkend="fig.tabbed_UI_overview">Tabbed mode</link> (see <link linkend="chpt.overview.gui">Main User Interface</link> for details).
                <note>
	              <para>
	                In order for this setting to take effect, Hydrogen has to be restarted.
                  </para>
                </note>
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">High-resolution display scaling</emphasis>:
                specifies whether the underlying bitmap graphics of the GUI should be scaled to larger sizes by Qt in order for Hydrogen to look nice with your system's resolution settings.
                <note>
	              <para>
	                In order for this setting to take effect, Hydrogen has to be restarted.
                  </para>
                </note>
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Icon color</emphasis>:
                while the color of all button labels can be set in the <link linkend="chpt.preferences.appearance_tab.colors">Colors</link> tab, the icons hold the color used in the corresponding <abbrev>SVG</abbrev> file and can not be altered freely. To still allow you to change the overall colors conveniently, Hydrogen is shipped with all icons available in either <option>Black</option> and <option>White</option> color.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Coloring method for Song Editor elements</emphasis>:
                determines the coloring of the grid boxes indicating the presence of a pattern in the <link linkend="chpt.song_editor">Song Editor</link>. The options available are:
              </para>
              <itemizedlist>
	            <listitem>
	              <para>
	                <option>Automatic</option>:
                    uses as many colors as there are patterns in the song.
                  </para>
                </listitem>
	            <listitem>
	              <para>
	                <option>Custom</option>:
                    uses a certain number of colors in a repeated way.
                  </para>
                </listitem>
              </itemizedlist>

              <para>
                By chosing <option>Custom</option> two more settings will become available:
              </para>
              
              <itemizedlist>
	            <listitem>
	              <para>
	                <emphasis role="bold">Number of colors in Song Editor</emphasis>:
                    how many different colors should be used.
                  </para>
                </listitem>
	            <listitem>
	              <para>
	                <emphasis role="bold">Selected colors</emphasis>:
                    a list of color buttons. Clicking one will open a dialog allowing you to change its color.
                  </para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </sect2>
        
        <sect2 id="chpt.preferences.appearance_tab.colors">
          <title>Colors</title>

          <figure id="fig.preferences.appearance_tab.colors">
            <title>The Colors Tab</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/preferencesColorsTab.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </figure>

          <para>
            The <emphasis>Colors</emphasis> tab exposes most of the colors used within Hydrogen.
          </para>

          <para>
            You can select a color by clicking its name in the tree you find on the left side. It is grouping the individual colors into
            
            <itemizedlist>
              <listitem>
                <para>
                  <emphasis role="bold">General</emphasis>:
                  basic Qt colors. Most of them are used in many parts of the GUI. But some of them might be not used at all. So, don't worry in case altering one of these does not result in visual changes.
                </para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="bold">Widgets</emphasis>:
                  colors in small and interactive elements of the GUI, like buttons or combo boxes.
                </para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="bold">Song Editor</emphasis>:
                  colors specific to the <link linkend="chpt.song_editor">Song Editor</link>.
                </para>
              </listitem>
              <listitem>
                <para>
                  <emphasis role="bold">Pattern Editor</emphasis>:
                  colors specific to the <link linkend="chpt.pattern_editor">Pattern Editor</link>.
                </para>
              </listitem>
            </itemizedlist>
          </para>

          <para>
            Once selected you can change a color by either clicking the large colored rectangle in the upper right part of the tab (which opens a color dialog) or by using the spinboxes and sliders in the lower right part. The latter represent the colors components according to the <abbrev>RGB</abbrev> as well as the <abbrev>HSV</abbrev> color model.
          </para>
          
        </sect2>

        <sect2 id="chpt.preferences.appearance_tab.font">
          <title>Font</title>

          <figure id="fig.preferences.appearance_tab.font">
            <title>The Font Tab</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/preferencesFontTab.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </figure>

          <para>The <emphasis>Font</emphasis> tab contains all options affecting strings, characters, and numbers displayed in the GUI.
          </para>

          <itemizedlist>
	        <listitem>
	          <para>
	            <emphasis role="bold">Application font</emphasis>:
                specifies the font family used for headings, larger labels, and most parts of the dialogs and popups.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Item font</emphasis>:
                specifies the font family used for smaller elements, like the name of patterns in the <link linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song Editor or the name of the samples in the <link linkend="chpt.instrument_editor.layers">Layers view</link> of the Instrument Editor.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Widget font</emphasis>:
                specifies the font family used for small and interactive elements of the GUI, like buttons.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Font size</emphasis>:
                accessibility option to increase or decrease the overall font size of Hydrogen.
              </para>
            </listitem>
          </itemizedlist>
          
        </sect2>
        
      </sect1>

    </chapter>
    
    <chapter id="chpt.main_menu">
      <title>Main Menu</title>

      <figure id="fig.main_menu">
        <title>The Main Menu</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/MainMenu.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <sect1 id="sect.main_menu.projects">
        <title>Project</title>
        <para>This menu offers file
        related functions.</para>

        <note>
	      <para>
	        If you are using Hydrogen within a <abbrev>NSM</abbrev> session, some of the options below will be called and behave differently (see <xref linkend="chpt.overview.session_management.nsm" /> for details).
          </para>
        </note>

        <itemizedlist>
          <listitem id="sect.main_menu.projects.new">
            <para><emphasis role="bold">New</emphasis>: creates a new and empty song.</para>

            <note>
              <para>
                Prior to version 1.2 of Hydrogen new songs were based on <filename>DefaultSong.h2song</filename> in Hydrogen's data folder and all <link linkend="chpt.preferences.general_tab.autosaves">backups</link> of unsaved changes were associated with it. This had the unfortunate downside that it was quite easy to lose all changes made in a new song in case you forget to change it.
              </para>
              <para>
                Since 1.2 new songs are not associated with any file anymore and Hydrogen makes sure the backup file generated does not exist yet and no data gets overwritten. In addition, when working on a newly created song and closing the application without saving the changes, e.g. due to a power outage, Hydrogen is now capable of restoring these changes from the backup file and prompts you at the beginning of the next session whether it should do so.
              </para>
              <para>
                If you are used to altering the <filename>DefaultSong.h2song</filename> and use it as a template, you can still do the same by <link linkend="sect.main_menu.projects.open">opening</link> and <link linkend="sect.main_menu.projects.save_as">saving</link> it using a different name.
              </para>
            </note>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Song Properties</emphasis>: sets general properties of the
            song such as name, author, <link linkend="chpt.license">license</link>, and generic notes.</para>
          </listitem>
          <listitem id="sect.main_menu.projects.open">
            <para><emphasis role="bold">Open</emphasis>: opens an existing song (a <link linkend="chpt.file_types.h2song">.h2song</link> file).</para>
          </listitem>
          <listitem id="sect.main_menu.projects.open_demo">
            <para><emphasis role="bold">Open Demo</emphasis>: opens one of the demo songs shipped with Hydrogen.

            <note>
	          <para>
	            The demo songs are stored in <filename role="directory">$INSTALL_PATH/share/hydrogen/data/demo_songs</filename>).
              </para>
            </note>
            </para>
          </listitem>
          <listitem id="sect.main_menu.projects.open_recent">
            <para><emphasis role="bold">Open Recent</emphasis>: opens a menu showing the last used songs (ordered from most recent to least recent).</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Save</emphasis>: saves changes to current song.</para>
          </listitem>
          <listitem id="sect.main_menu.projects.save_as">
            <para><emphasis role="bold">Save As</emphasis>: saves current song as <link linkend="chpt.file_types.h2song">.h2song</link> file to a path of your choice.

            <tip>
	          <para>
	            In order for Hydrogen to automatically list it in the <link linkend="sect.sl.songs">Songs section of the Sound Library</link>, you have to store it in the <filename role="directory">songs</filename> subfolder of Hydrogen data directory (<filename role="directory">$HOME/.hydrogen/data/songs/</filename>).
              </para>
            </tip>
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Open Pattern</emphasis>: opens a pattern (a <link linkend="chpt.file_types.h2pattern">.h2pattern</link> file)
            belonging to the current drumkit.</para>
          </listitem>
          <listitem id="sect.main_menu.projects.export_pattern_as">
            <para><emphasis role="bold">Export Pattern As</emphasis>: saves a
            pattern as a <link linkend="chpt.file_types.h2pattern">.h2pattern</link> file.

            <tip>
	          <para>
	            In order for Hydrogen to automatically list it in the <link linkend="sect.sl.patterns">Patterns section of the Sound Library</link>, you have to store it in
            <filename>$HOME/.hydrogen/data/patterns/drumkit_name/</filename>.
              </para>
            </tip>
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Export MIDI File</emphasis>: exports the current song in
            <abbrev>MIDI</abbrev> format.</para>
          </listitem>
          <listitem id="sect.main_form.export_song" xreflabel="Export Song">
            <para><emphasis role="bold">Export Song</emphasis>: exports the current song into an audio file.</para>
            
            <para>The <emphasis role="bold">Export mode</emphasis> option <option>Export to a single track</option> will export one stereo downmix of your song - the master output. <option>Export to separate tracks</option> will create files for each 
              instrument/track. <option>Both</option> will create a stereo downmix as well as audio files for all individual
              instruments.
              </para>
              <para>
                For audio formats <emphasis>FLAC</emphasis>,
                <emphasis>Ogg/Vorbis</emphasis>, <emphasis>Ogg/Opus</emphasis>,
                and <emphasis>MP3</emphasis> the option <option>Compression
                Level</option> instead of <option>Samplerate</option> and
                <option>SampleDepth</option> is available. For
                <emphasis>FLAC</emphasis> it trades off export time against
                resulting file size. For all other formats (all lossy
                compression ones) it trades off audio quality against resulting
                file size.
              </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Export LilyPond File</emphasis>: exports the current song to LilyPond.</para>
            <warning>
	          <para>
            It has the following limitations: Only the <emphasis>GMRockKit</emphasis> and no triplets are supported.</para>
            </warning>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Quit</emphasis>: exits Hydrogen.</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.undo">
        <title>Undo</title>
        
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Undo</emphasis>: lets you undo your last action.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Redo</emphasis>: lets you redo the last undone action.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Undo History</emphasis>: gives you an overview of your previous
            actions.</para>
          </listitem>
        </itemizedlist>
      </sect1>
      
      <sect1 id="sect.main_menu.drumkits">
        <title>Drumkits</title>
        <itemizedlist>
          <listitem id="sect.main_menu.drumkits.new">
            <para><emphasis role="bold">New</emphasis>: creates a new and empty <link linkend="chpt.overview.drumkits">drumkit</link> by clearing all the instruments of the current one.
            </para>
          </listitem>
          <listitem id="sect.main_menu.drumkits.open">
	        <para>
	          <emphasis role="bold">Open</emphasis>:
              opens one of the registered drumkits and replaces the currently loaded one.

              <note>
	            <para>
	              Using this option you can only load drumkits that have been already imported into Hydrogen. If you just received a new one from an external source, be sure to use the <link linkend="sect.main_form.import_drumkit">Import</link> option described below.
                </para>
              </note>
            </para>
          </listitem>
          <listitem id="sect.main_menu.drumkits.properties">
	        <para>
	          <emphasis role="bold">Properties</emphasis>:
              sets general properties of the drumkit associated with the current song, such as name, author, <link linkend="chpt.license">license</link>, general information, image, and image license.
            </para>
          </listitem>
          <listitem id="sect.main_menu.drumkits.save">
            <para><emphasis role="bold">Save</emphasis>: saves all settings of the drumkit associated with the current (including those of their instruments and sound samples).

            <tip>
              <para>
                See <xref linkend="chpt.overview.drumkits"/> and <xref linkend="chpt.license"/> for further information.
              </para>
            </tip>
            </para>
          </listitem>
          <listitem id="sect.main_menu.drumkits.save_as">
            <para><emphasis role="bold">Save As</emphasis>: saves all settings of the current drumkit (including those of their instruments and sound samples) as new drumkit.

            <note>
	          <para>
	            The new drumkit will be a physical copy of the old one and is stored into the <filename role="directory">$HOME/.hydrogen/data/drumkits/</filename> folder.
              </para>
            </note>
            
            <tip>
              <para>
                See <xref linkend="chpt.overview.drumkits"/> and <xref linkend="chpt.license"/> for further information.
              </para>
            </tip>
            </para>
          </listitem>
          <listitem id="sect.main_form.export_drumkit">
            <para><emphasis role="bold">Export</emphasis>: compresses and stores all instrument samples and settings of the current drumkit into a folder of your choice as <link linkend="chpt.file_types.h2drumkit">.h2drumkit</link> file.

            <note>
	          <para>
	            For compatibility reasons you can also export your drumkit in a format used in older versions ( &#60;= 0.9.6 ) of Hydrogen. By doing so you need to select a single <link linkend="def.component">component</link> to export since having multiple ones was not supported back than.
              </para>
            </note>
            </para>
          </listitem>
          <listitem id="sect.main_form.import_drumkit">
            <para><emphasis role="bold">Import</emphasis>: imports a drumkit (a <link linkend="chpt.file_types.h2drumkit">.h2drumkit</link> file) from the local filesystem.
            </para>
          </listitem>
          
          <listitem id="sect.main_form.online_import_drumkit">
            <para><emphasis role="bold">Online Import</emphasis>: imports another drumkit from a remote location
            through a <abbrev>XML</abbrev> feed. The <abbrev>XML</abbrev> file that should be provided is <emphasis
            role="bold">NOT</emphasis> <abbrev>RSS</abbrev> compliant (see <ulink
            url="http://www.hydrogen-music.org/feeds/drumkit_list.php" >Hydrogen
            website</ulink> for an example).
            </para>

            <para>
              <figure id="fig.import_drumkit">
                <title>Import Drumkit</title>
                <mediaobject>
                  <imageobject>
                    <imagedata fileref="generated_en/Sound_Library_import.png" format="PNG" />
                  </imageobject>
                </mediaobject>
              </figure>

              The Import window will pop up with the <emphasis>Internet</emphasis> tab selected.
              By default the link to the drumkit list (on <ulink url="http://hydrogen-music.org"/>) will be filled in, 
              and after pressing the <emphasis role="bold">Update list</emphasis> button you will get a complete list of all
              drumkits that are available for download. In the <emphasis>Status</emphasis> column on the you can see
              if a kit is installed or not.
            </para>

        <para>
        If you select one of the drumkits you will see info about this kit in the right
        pane of the Import window: name, description, author and also the
        <link linkend="chpt.license">license</link>.
        </para>
       <para>
         You can install a drumkit by selecting it and clicking <emphasis role="bold">Download and Install</emphasis>.
         
    
       <informalfigure id="fig.downloading_soundlibrary">
         <mediaobject>
          <textobject>
            <phrase>
              Widget with progress bar popping up during the download of a drumit.
            </phrase>
          </textobject>
           <imageobject>
             <imagedata fileref="Downloading_SoundLibrary.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </informalfigure>
    
       Once the kit has been downloaded it will be available in the <link linkend="chpt.sound_library.drumkits">Sound Library</link> under <emphasis>User drumkits</emphasis>.

       </para>
       <note>
         <para>
           In the rare case a drumkit or one of its contained sample files
           features <emphasis role="bold">UTF-8</emphasis> encoded characters
           but your system's locale is not properly set up to handle these,
           those characters will be omitted. For the kit itself it just means it
           will carry a slightly different name. But renamed sample files can't
           be found by Hydrogen anymore when loading the kit. In case you see a
           popup dialog during installation complaining about encoding, be sure
           to check the instruments of the imported kit and reassign missing
           samples using the <link
           linkend="chpt.instrument_editor.layers.layers">Instrument
           Editor</link>.
         </para>
         <para>
           A description of <emphasis
           role="bold">how to fix encoding issues on Windows</emphasis> can be found in our <ulink
           url="https://github.com/hydrogen-music/hydrogen/wiki/Fix-encoding-issues-on-Windows">Wiki</ulink>.
         </para>
       </note>

        
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.instruments">
        <title>Instruments</title>
        <para>This menu offers
        instruments functions.</para>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Add Instrument</emphasis>: adds a new instrument to the current drumkit.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Clear All</emphasis>: deletes all instruments from the current drumkit leaving only an empty one.</para>
          </listitem>
          <listitem>       
            <para><emphasis role="bold">Add Component</emphasis>: adds a <link linkend="def.component">component</link> to the current drumkit.</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.view">
        <title>View</title>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Playlist Editor</emphasis>: opens the <link linkend="chpt.playlist_editor">Playlist Editor</link> window.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Director</emphasis>: opens the <link linkend="chpt.director">Director</link> window.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Mixer</emphasis>: opens the <link linkend="chpt.mixer">Mixer</link> window.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Instrument Rack</emphasis>: shows or hides the widget of the main window containing both the <link linkend="chpt.instrument_editor">Instrument Editor</link> and the <link linkend="chpt.sound_library">Sound Library</link>.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Automation Path</emphasis>: shows or hides the <link linkend="sect.song_editor.automation_path">Automation Path</link>
            panel.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Timeline</emphasis>: shows or hides the <link linkend="chpt.song_editor.timeline">Timeline</link> panel.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Playback Track</emphasis>: shows or hides the <link linkend="chpt.song_editor.playbackTrack">Playback Track</link> panel.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Full screen</emphasis>: maximises the window size to the whole screen area.</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.options">
        <title>Options</title>
        <itemizedlist>
          <listitem id="sect.main_menu.options.input_mode">
            <para>
              <emphasis role="bold">Input mode</emphasis>: sets the current
              <link linkend="chpt.midi.note.input_mode">Input Mode</link>.
            </para>
          </listitem>
          
          <listitem>
            <para><emphasis role="bold">Preferences</emphasis>: opens the main preferences
            window (see <xref linkend="chpt.preferences"/> for details).</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.debug">
        <title>Debug</title>

        <para>Tools mainly for debugging
        and monitoring Hydrogen.</para>

        <note>
          <para>
            The Debug option is only available if Hydrogen was compiled with 
            debug support.
          </para>
        </note>


        <itemizedlist>
          <listitem id="chpt.preferences.audio_engine_tab">
            <para><emphasis role="bold">Show Audio Engine Info</emphasis>: opens a window that shows
            various stats about Hydrogen and the audio driver.

            <figure id="fig.preferences.audio_engine_tab">
              <title>The Audio Engine View</title>
              <mediaobject>
                <imageobject>
                  <imagedata fileref="generated_en/AudioEngineInfoDialog.png" format="PNG"/>
                </imageobject>
              </mediaobject>
            </figure>

            <note>
	          <para>
                In case <abbrev>JACK</abbrev> is used,
                buffer and sampling rate should be set in the configuration of the <abbrev>JACK</abbrev>
                server before starting Hydrogen (<abbrev>JACK</abbrev> automatically starts when an
                application tries to connect).
              </para>
            </note>
            </para>
          </listitem>
          
          <listitem id="chpt.main_menu.debug.show_filesystem_info">
            <para><emphasis role="bold">Show Filesystem Info</emphasis>:
            opens a window that shows you the paths to the user and system data directory as well as to the folder used to create temporary files.
            </para>
          </listitem>
          <listitem id="chpt.main_menu.debug.log_level">
	        <para>
	          <emphasis role="bold">Log Level</emphasis>:
              specifies which log messages will be written into the log file.
              <itemizedlist>
	            <listitem>
	              <para>
                    <option>None</option>: No messages will be written at all.
                  </para>
                </listitem>
	            <listitem>
	              <para>
                    <option>Error</option>: Only messages concerning critical errors will be written out.
                  </para>
                </listitem>
                <listitem>
	              <para>
	                <option>Warning</option>: Like <option>Error</option> but in addition also general warnings about potential bugs or inconsistencies will be written out.
                  </para>
                </listitem>
                <listitem>
	              <para>
	                <option>Info</option>: Like <option>Warning</option> but also all info messages indicating the correct behavior of Hydrogen will be written out.
                  </para>
                </listitem>
                <listitem id="chpt.main_menu.debug.log_level.info">
	              <para>
	                <option>Debug</option>: Like <option>Info</option> but also internal help messages used for developing will be written out.
                  </para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem id="chpt.main_menu.debug.open_log_file" xreflabel="Open Log File">
            <para><emphasis role="bold">Open Log File</emphasis>:
            opens Hydrogen's log in either the terminal the application was started in or in a new terminal instance.</para>
          </listitem>
        </itemizedlist>
      </sect1>

      <sect1 id="sect.main_menu.info">
        <title>Info</title>

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">User Manual</emphasis>: opens a window with a version of this manual installed on your local computer.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">About</emphasis>: the usual window with license
            information, acknowledgments, etc.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Report Bug</emphasis>: opens the <ulink url="https://github.com/hydrogen-music/hydrogen/issues">Hydrogen issue page at github.com</ulink> in your default Internet browser.
            You can open a new issue to communicate a bug here (first search if there exists already an issue about it).</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Donate</emphasis>: make a donation to developers/maintainers.</para>
          </listitem>
        </itemizedlist>
      </sect1>
    </chapter>

    <chapter id="chpt.main_toolbar">
      <title>Main Toolbar</title>
      
      <figure id="fig.main_toolbar">
        <title>The Main Toolbar</title>
        
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/MainToolbar_V2.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <para>Before analyzing the two main frames of Hydrogen, let's take a quick
      look at the main toolbar and its components.</para>
      
      <sect1 id="sect.main_toolbar.transport_control">
        <title>
          Transport Control
        </title>

        <informalfigure id="fig.main_toolbar.transport_control">
          <mediaobject>
          <textobject>
            <phrase>
              Part of the Main Toolbar responsible for the transport
              control. From left to right: rewind, record, pause and play, stop,
              fast forward, and loop button.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/background_Control_V2.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>Using these buttons you can <emphasis role="bold">start</emphasis>
        
        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlPlayButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        
        (also bound to <keycap>Space</keycap>, see <xref linkend="chap.shortcuts" /> for further related shortcuts) and <emphasis role="bold">stop</emphasis>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlStopButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject> playback, <emphasis role="bold">record</emphasis>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlRecordButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        new patterns (see <xref linkend="chpt.overview.recording" /> for details), <emphasis role="bold">fast forward</emphasis>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlForwardButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        
        and <emphasis role="bold">rewind</emphasis>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlRewindButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        transport position, and <emphasis role="bold">loop</emphasis>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlLoopButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        playback.</para>

          <para>In addition, you can switch between <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlSongModeButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

          and <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlPatternModeButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

          .</para>

          <tip>
            <para>
	          When using the <link linkend="chpt.keyboard_and_mouse">Keyboard</link> to navigate in the <link linkend="chpt.song_editor">Song Editor</link> and <link linkend="chpt.pattern_editor">Pattern Editor</link> the shortcut <keycap>Ctrl</keycap> + <keycap>Space</keycap> (or <keycap>Alt</keycap> + <keycap>Space</keycap> on MacOS) will change the mode to the one corresponding to the editor. In addition, it will move the current transport position to either the note (Pattern Editor) or the pattern (Song Editor) focused by the cursor and starts the playback.
            </para>
          </tip>
      </sect1>

      <sect1 id="sect.main_toolbar.tap_tempo_beat_counter">
        <title>Tap Tempo and Beat Counter</title>

        <informalfigure id="fig.main_toolbar.beat_counter">
          <mediaobject>
          <textobject>
            <phrase>
              Part of the Main Toolbar responsible for the tempo settings using
              the Beat Counter. In the center there is a display showing to the
              left the beat type and to the right on top the current mode of the
              Beat Counter and the value of the Countdown Counter below. To the
              left and right of the display there are buttons to decrease or
              increase the beat type (left) and Countdown Counter value (right).
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/MeasureSettings.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>This section covers how to interactively change tempo using the <emphasis>Beat Counter</emphasis>. Due to conceptional similarities the <emphasis>Tap Tempo</emphasis> will be covered as well which itself is not related to the widget displayed above.</para>

        <sect2 id="sect.main_toolbar.tap_tempo_beat_counter.tap_tempo">
          <title>Tap Tempo</title>
	      
          <para>The Tap Tempo allows you to change the tempo at any time - with transport rolling or stopped - within Hydrogen. To change the tempo, hit the
          <keycap>\</keycap> key in the tempo you want.
          </para>

          <para>
            After two keystrokes the tempo will be first changed according to the time difference between the two taps. With each addition keystroke the tempo will be changed again to the rolling average of the last up to eight hits of the <keycap>\</keycap> button. If you tap
          accidentally, or if you wait too long between taps, the Tap Tempo
          counter will start over.</para>

          <note>
	        <para>
	          The widget shown above is the one of the Beat Counter. The Tap Tempo itself does neither have a dedicated widget nor any option to be set by the user.
            </para>
          </note>
        </sect2>
        
        <sect2 id="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">
          <title>Beat Counter</title>

          <para>The Beat Counter is essentially a Tap Tempo on steroids.  By default the Beat Counter widget is not
          visible.  To see the Beat Counter widget click the 
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey vertical button containing the characters "B" and "C" in
              adjacent rows.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/btn_bc_off.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          button or simply press <keycap>,</keycap>.</para>

          <para>The tempo that you tap will be considered to correspond to even beats of the song's 
          beat type.  The beat type can be set to 1/8 (for eight-note beats), 1/4 (for
          quarter-note beats), 1/2 (for half-note beats), and 1/1 (for whole-note
          beats).  To change the beat type use the left <keycap>+</keycap> / <keycap>-</keycap> buttons.  To change
          the Countdown Counter value, use the right <keycap>+</keycap> / <keycap>-</keycap> buttons.  The Countdown 
          Counter value can be set between 2 and 16 beats.  (I.e. if you set the beat to 6, you will
          have to tap 6 times before the new tempo is computed and set.)  When the
          display shows an <parameter>R</parameter>, it means that the Beat Counter
          is ready to start from 0.  When you tap <keycap>,</keycap>, the <parameter>R</parameter> will change to
          1, and will increment with every keystroke until it reaches the Countdown 
          Counter value (shown just below the <parameter>R</parameter>).</para>

          <para>The button in the bottom right-hand controls the auto-start
          feature, and it toggles between 
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a "S".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/btn_bc_set_play_off.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          and
          <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing a "P".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/btn_bc_set_play_on.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          .  When it shows the latter (for <emphasis>Play</emphasis>), the song will set the new tempo and
          automatically start to play after you tap the right number of beats (if
          it's not already playing, of course).  This way, if you have the
          Beat Counter set up for 4/4, you can tap 1-2-3-4, and start playing on
          the next beat.  When it shows
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a "S".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_bc_set_play_off.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
          (for <emphasis>Set BPM</emphasis>), the auto-start is disabled.</para>

          <para>For example: Suppose you have a live band, Hydrogen, and a
          softsynth that is controlled by <command>Seq24</command>)... and you want them all to start
          at the same time.  Set the beat type to 1/4 and the number of beats to
          4.  Enable auto-start (button shows
          <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing a "P".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/btn_bc_set_play_on.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          ).  Count off
          the band 1-2-3-4 (while tapping the <keycap>,</keycap> key) and everyone
          starts on 1.</para>

          <para>Another example: Same situation, but the song doesn't require
          Hydrogen or synths until some point later.  During that time, a human
          (e.g. guitar player) will be setting the tempo.  On the measure before
          Hydrogen is supposed to play, tap the comma key 1-2-3-4 with the
          beat... and you're in on the next beat (at the right tempo).</para>

          <tip>
            <para>An temporal offset when starting the playback after setting the tempo and a latency compensation for the Beat Counter can be configured in the <link linkend="chpt.preferences.general_tab">General tab</link> of the Preferences Dialog.
          </para>
        </tip>

        <note>
          <para>
            If you are using <abbrev>JACK</abbrev> transport in the presence of
            an <link
            linkend="sect.main_toolbar.jack_control.timebase_red">external
            <abbrev>JACK</abbrev> Timebase controller</link>, Hydrogen will use
            the provided tempo and both Tap Tempo and Beat Counter will be
            disabled. If Hydrogen itself is <link
            linkend="sect.main_toolbar.jack_control.timebase_blue">in control of <abbrev>JACK</abbrev>
            Timebase</link>, tempo changes from Hydrogen will be broadcasted to other
            <abbrev>JACK</abbrev> clients.
          </para>
        </note>
      </sect2>
      
      </sect1>
      <sect1 id="sect.main_toolbar.bpm_control_and_metronome">
        <title>BPM Control and Metronome</title>

        <informalfigure id="fig.main_toolbar.bpm_control_and_metronome">
          <mediaobject>
          <textobject>
            <phrase>
              Part of the Main Toolbar responsible for the tempo settings. To
              the left there are on top two buttons for decreasing and
              increasing the tempo and below one to activate the metronome. To
              the right and covering most of the area is a display showing the
              current BPM. At the far right there is a tall button activating
              the recalculation of samples processed by Rubber Band at tempo changes. 
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/background_BPM.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>Set the speed of the song in the range from <option>10</option> to <option>400</option> bpm (beats per minute).
        </para>

          <para>You can use
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing black outlines of a classical metronome.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/btn_metronome_off.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          to toggle the metronome.</para>

        <tip>
	      <para>
	        The volume of the metronome can be adjusted in the <link linkend="chpt.preferences.audio_tab">Audio tab</link> of the Preferences.
          </para>
        </tip>

        <para>
	      If either Rubber Band support is compiled into your current version of Hydrogen or correctly configured in the <link linkend="chpt.preferences.general_tab">General tab</link> of the Preferences, you will also find the
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey vertical button containing the characters "R", "U", and "B"
              in adjacent lines.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/playerControlRubberbandButton.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          button next to the BPM widget. Activating it will enable recalculation of all sample pitches using Rubber Band whenever the tempo of the song will be changed (see <xref linkend="chpt.sample_editor.pitch" /> for details).
        </para>
        
      </sect1>

      <sect1 id="sect.main_toolbar.cpu_usage_midi_in">
        <title>CPU Usage and MIDI in</title>

        <informalfigure id="fig.main_toolbar.cpu_usage_midi_in">
          <mediaobject>
          <textobject>
            <phrase>
              A block horizontal line in the upper part will contain a meter
              showing the load of the CPU. Below a small LED-like symbol next to
              the text "MIDI-IN" will indicated when there is
              <abbrev>MIDI</abbrev> input.
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/MidiIN_CPU.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>The <abbrev>CPU</abbrev> bargraph gives you an indication of the <abbrev>CPU</abbrev> load. The <abbrev>MIDI</abbrev> led lights up every time Hydrogen receives a <abbrev>MIDI</abbrev> message.</para>

        <tip>
	      <para>
	        The <abbrev>MIDI</abbrev> settings can be adjusted in the <link linkend="chpt.preferences.midi_tab"><abbrev>MIDI</abbrev> tab</link> of the Preferences.
          </para>
        </tip>

        <para>
          In case a <abbrev>XRUN</abbrev> event occurs (<abbrev>CPU</abbrev> load is so large that audio processing could not be finished in time) the outlines of the <abbrev>CPU</abbrev> bargraph will be colored red for a couple of seconds.
        </para>
        
      </sect1>
      
      <sect1 id="sect.main_toolbar.jack_control">
        <title>JACK Control</title>
        
        <informalfigure id="fig.main_toolbar.jack_control">
          <mediaobject>
          <textobject>
            <phrase>
              Part of the Main Toolbar responsible for the <abbrev>JACK</abbrev>
              configuration. The left button is titled "J.Trans" and the right
              one "Timebase".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/JackTrans_Timebase.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </informalfigure>

        <para>Clicking
        
        <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the text "J.Trans".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/playerControlJackTransportButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        will enable <abbrev>JACK</abbrev> transport. If disabled, Hydrogen will still use the <abbrev>JACK</abbrev> driver and registered audio ports. But it decouples its own transport state from the one of the <abbrev>JACK</abbrev> server and will not be in sync with other clients anymore.
        </para>
        <para>
          The
          <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the text "Timebase".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/JackTimebaseOff.png"
                         format="PNG" />
            </imageobject>
          </inlinemediaobject>
          button indicates the current state of <abbrev>JACK</abbrev> Timebase
          support. Via this protocol one JACK cilent - registered as Timebase
          <emphasis>controller</emphasis> - can share its tempo and position
          information as beat, bar, and tick with other JACK clients supporting
          this protocol - Timebase <emphasis>listeners</emphasis>. When pressing
          the button Hydrogen will attempt to take control of Timebase.
          </para>
          <tip>
            <para>
              When using <abbrev>JACK</abbrev> Timebase transport relocations
              should always be done within the Timebase controller application.
              Otherwise, you could end up at unexpected positions due to the
              limitations of that protocol.
            </para>
          </tip>
          <note>
            <para>
          The JACK Timebase API uses other terms for these two classes of
          clients we do not repeat in here.
            </para>
          </note>
          <itemizedlist>
            <listitem id="sect.main_toolbar.jack_control.timebase_off">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Grey button containing the text "Timebase".
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/JackTimebaseOff.png"
                               format="PNG" />
                  </imageobject>
                </inlinemediaobject>
                - Timebase support itself is activated but neither
              Hydrogen nor an external application is currently in control.
              Hydrogen will use its internal tempo.
              </para>
            </listitem>
            <listitem id="sect.main_toolbar.jack_control.timebase_blue">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Blue button containing the text "Timebase".
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/JackTimebaseBlue.png"
                               format="PNG" />
                  </imageobject>
                </inlinemediaobject>
                - Hydrogen is in control of <abbrev>JACK</abbrev> Timebase, uses
                its internal tempo, and boardcasts it to other
                <abbrev>JACK</abbrev> clients.
              </para>
            </listitem>
            <listitem id="sect.main_toolbar.jack_control.timebase_red">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Red button containing the text "Timebase".
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/JackTimebaseRed.png"
                               format="PNG" />
                  </imageobject>
                </inlinemediaobject>
                - An external application is registered as Timebase controller.
                Hydrogen will disregard its local tempo - <link
                linkend="sect.main_toolbar.bpm_control_and_metronome">BPM
                widget</link>, <link
                linkend="sect.main_toolbar.tap_tempo_beat_counter.tap_tempo">Tap
                Tempo</link>, <link
                linkend="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">Beat
                Counter</link>, <link
                linkend="chpt.song_editor.timeline">Timeline</link> - and,
                instead, adopts tempo and position provided by the controller.
              </para>
            </listitem>
            <listitem id="sect.main_toolbar.jack_control.timebase_disabled">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Grey button containing the greyed-out text "Timebase".
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/JackTimebaseDisabled.png" format="PNG" />
                  </imageobject>
                </inlinemediaobject>
                - <abbrev>JACK</abbrev> Timebase support was
              disabled in the <link linkend="chpt.preferences.audio_tab">Audio
              tab</link> of the Preferences.
              </para>
              <tip>
	              <para>
                  This can be useful in the presence of a controller with a
                  faulty Timebase implementation or in case of a bug in
                  Hydrogen's own implementation.
                </para>
              </tip>
            </listitem>
          </itemizedlist>
      </sect1>
      
        <sect1 id="sect.main_toolbar.gui_state">
          <title>GUI State</title>

          <informalfigure id="fig.main_toolbar.gui_state">
            <mediaobject>
          <textobject>
            <phrase>
              In the upper part there are two buttons. The smaller one to the left
              is titled "Mixer" and the larger one "Instrument rack". Below
              there is a large blue display showing the default message of Hydrogen
              after startup "Hydrogen Ready.".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/mixer-instrrack_btn.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>
            Toggles the <link linkend="chpt.mixer">Mixer</link> window and the Instrument Rack (containing both the <link linkend="chpt.instrument_editor">Instrument Editor</link> and the <link linkend="chpt.sound_library">Sound Library</link>).
          </para>
          <para>
            The line below displays status messages telling what Hydrogen is up to. Clicking it will open a popup menu showing the last 100 messages.
          </para>
        </sect1>
    </chapter>

    <chapter id="chpt.song_editor">
      <title>Song Editor</title>

      <para>
      <figure id="fig.song_editor">
        <title>The Song Editor</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/songEditorBackground.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
      </para>

      <para>
        The Song Editor gives an overview of the whole song
        (e.g. intro, verse, bridge, chorus and so on).  Each
        colored square on this panel represents a playing pattern.
        It gives you complete freedom to add/remove
        patterns to the song and to move or copy any part of your
        song.
      </para>
      <para>
        Columns represent time periods within the song. While they're
        shown as the same width in the Song Editor, the length of time
        taken to play through a column is set by the length of the
        pattern or patterns which are active and playing during that
        time slot.
      </para>
      <para>
        Multiple patterns can be active at the same time in a
        column, and they will play simultaneously. This allows
        instrument parts to be separated out into different patterns,
        or to add ornamentation or fills on top of basic patterns
        without duplicating the basics into both patterns.
      </para>
      <para>
        In the case of multiple patterns of different lengths in one
        column only the largest one(s) will be represented by a
        square. The shorter patterns are indicated by rectangles whose
        width indicate their length relative to the longest one.
      </para>
      <tip>
	    <para>
	      You can alter the colors of the squares using the <link linkend="chpt.preferences.appearance_tab.interface">Interface</link> tab in the Appearance tab of the Preferences.
        </para>
      </tip>

      <informalfigure id="fig.song_editor.song_ruler">
        <mediaobject>
          <textobject>
            <phrase>
              Picture of a part of the Song Ruler used for naviagation. It
              indicates the position of certains bars by their number - "1",
              "5", "9", "13", "17". All remaining bars are indicated with a
              vertical line - "|".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/songEditorPositionRuler.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </informalfigure>
      
      <para>
	    In addition to the transport control provided in the <link linkend="sect.main_toolbar.transport_control">Main Toolbar</link> you can use the <emphasis role="bold">Song Ruler</emphasis> to navigatw. This is the area above the grid and right of the <link linkend="chpt.song_editor.main_controls">Main Controls</link>. The position clicked will be rounded to the nearest pattern beginning (indicated by the faint playhead shown upon hovering) and transport will be relocated there.
        <note>
	      <para>
            Navigation in Hydrogen is always quantized. It is only possible to move forward / backwards or locate to whole patterns.
          </para>
        </note>

        <tip>
	      <para>
	        You can also locate the keyboard cursor (see <xref linkend="chpt.keyboard_and_mouse" />) to a desired pattern and press <link linkend="chap.shortcuts.ctrl_space"><keycap>Ctrl</keycap> + <keycap>Space</keycap></link> to relocate to this position.
          </para>
        </tip>
      </para>


     <sect1 id="chpt.song_editor.main_controls">
       <title>Main Controls</title>

       <informalfigure id="fig.song_editor.main_controls">
         <mediaobject>
          <textobject>
            <phrase>
              Main Controls for the Song Editor. From left to right: larger
              button bearing the text "CLEAR" for deleting all patterns, new
              pattern button, two buttons to move the selected pattern down and
              up, two buttons to activate the Draw and the Select mode, and the
              button to switch between Selected Pattern Mode and Stacked Pattern Mode.
            </phrase>
          </textobject>
           <imageobject>
             <imagedata fileref="generated_en/bg_topPanel.png" format="PNG"/>
           </imageobject>
         </mediaobject>
       </informalfigure>

      <itemizedlist>

        <listitem>
          <para><inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the text "CLEAR".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_clear_off.png" format="PNG"/>
            </imageobject></inlinemediaobject> : deletes all patterns
            (asks for confirmation!).
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a plus sign.
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_new_on.png" format="PNG" />
            </imageobject></inlinemediaobject> : creates a new pattern (and asks for a name).
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject>
          <textobject>
            <phrase>
              Two grey button vertically aligned. The lower one contains a black
              arrow tip pointing downwards and the upper one pointing upwards.
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_updown.png" format="PNG" />
            </imageobject></inlinemediaobject> : moves currently selected pattern
            up or down.
          </para>
          
          <tip>
            <para>
              You can also <emphasis>drag-and-drop</emphasis> a pattern up/down in
              the pattern list.
            </para>
          </tip>
        </listitem>

        <listitem>
          <para>
            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button containing a black brush.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_select.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>
            : indicates that Hydrogen is in <link linkend="chpt.song_editor.editor_modes.draw">Draw Mode</link> or
            
            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button with pointer and dashed rectangle.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_draw.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>
             : in <link linkend="chpt.song_editor.editor_modes.select">Select Mode</link>.
          </para>
          
        </listitem>

        <listitem id="chpt.song_editor.main_controls.pattern_editor_lock">
          <para>
            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button if a black lock.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_lock.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>
            : locks the <link linkend="chpt.pattern_editor">Pattern Editor</link>.
          </para>

          <para>
            If the Pattern Editor is locked, the user won't be able to select a pattern using the <link linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song Editor. Instead, Hydrogen will automatically select the currently playing pattern. In case there is more than one pattern present in the current row, the bottom-most one will be chosen.
          </para>

          <tip>
            <para>
              This becomes quite handy when <link linkend="chpt.overview.recording">recording</link> notes in Song Mode. Hydrogen will always select the pattern recorded notes will be inserted to.
            </para>
          </tip>

          <note>
            <para>
              This button is only enabled in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>. In <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link> recorded notes are always added to the currently selected pattern.
            </para>
          </note>
        </listitem>

        <listitem id="chpt.song_editor.main_controls.selected_vs_stacked" xreflabel="Selected and Stacked Pattern Mode">
          <para><inlinemediaobject>
          <textobject>
            <phrase>
              Grey button with a horizontal black line.
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_pattern_mode.png" format="PNG"/>
            </imageobject></inlinemediaobject> : indicates that Hydrogen is in <emphasis>Selected Pattern Mode</emphasis> or 
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button with three horizontal black lines stacked vertically.
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_stacked_mode.png" format="PNG"/>
            </imageobject></inlinemediaobject>
            : in <link linkend="chpt.song_editor.editor_modes.stacked">Stacked Pattern Mode</link>.
          </para>

          <note>
            <para>
              These two buttons will only be enabled in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link>. In <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link> playing patterns are solely determined by the grid in the Song Editor.
            </para>
          </note>

        </listitem>
      </itemizedlist>

     </sect1>

           <sect1 id="chpt.song_editor.editor_modes">
        <title>Song Editor modes</title>
        <para>
          The Song Editor has two different <emphasis>interaction modes</emphasis>. The
          default <link linkend="chpt.song_editor.editor_modes.select"><emphasis role="bold">Select Mode</emphasis></link> allows
          pattern blocks to be set, cleared, selected, moved and
          copied. The <link linkend="chpt.song_editor.editor_modes.draw"><emphasis role="bold">Draw Mode</emphasis></link>
          instead allows pattern sequences to be drawn freehand.
        </para>

        <para>
          In both modes, you can perform basic editing: clicking an
          empty square activates the pattern in that time slot, and
          clicking again will deactivate it.
        </para>

        <para>
          They keyboard can also be used for editing. The arrow keys
          <keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap>
          will move the keyboard input cursor, and pressing
          <keycap>Return</keycap> will activate or deactivate the
          pattern in the current column.
        </para>

        <para>
	      In addition, there are two major <emphasis>playback modes</emphasis>, <link linkend="chpt.song_editor.editor_modes.song_mode"><emphasis role="bold">Song Mode</emphasis></link> and <link linkend="chpt.song_editor.editor_modes.pattern_mode"><emphasis role="bold">Pattern Mode</emphasis></link> (with two minor submodes <link linkend="chpt.song_editor.editor_modes.pattern_mode"> <emphasis role="bold">Selected Pattern mode</emphasis></link> and <link linkend="chpt.song_editor.editor_modes.stacked"><emphasis role="bold">Stacked Pattern Mode</emphasis></link>). These will determine which parts of the song you will listen to during playback.
        </para>
        <note>
	      <para>
	        While Select Mode, Draw Mode, Selected Pattern Mode, and Stacked Pattern Mode are activated via the <link linkend="chpt.song_editor.main_controls">Main Controls</link> of the Song Editor, Song Mode and Pattern Mode are activated via the <link linkend="sect.main_toolbar.transport_control">Transport Control</link> section of the Main Toolbar.
          </para>
        </note>

        <sect2 id="chpt.song_editor.editor_modes.select">
          <title>Select Mode</title>
          <para>
            This mode is enabled if the
            
            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button with pointer and dashed rectangle.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_draw.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>

            button is shown in the <link linkend="chpt.song_editor.main_controls">Controls</link> of the Song Editor and allows
            you to select multiple patterns in the Song Editor and
            delete/move/copy them.
          </para>
	  <para>
            Once you have selected a part of your song you can
            <emphasis role="bold">delete</emphasis> it by pressing
            <keycap>Delete</keycap>.  You can <emphasis
            role="bold">move</emphasis> it by simply <emphasis>dragging</emphasis> your
            selection to another location with your mouse, or by
            cutting (<keycap>Ctrl</keycap> + <keycap>x</keycap>) and
            pasting (<keycap>Ctrl</keycap> + <keycap>v</keycap>) using
            your keyboard. You can also <emphasis
            role="bold">copy</emphasis> your selection by either
            holding <keycap>Ctrl</keycap> while <emphasis>dragging</emphasis> it to a new
            location, or by copying (<keycap>Ctrl</keycap> +
            <keycap>c</keycap>) and pasting (<keycap>Ctrl</keycap> +
            <keycap>v</keycap>) using your keyboard.
          </para>
          <para>
            Selections can be modified by holding <keycap>Ctrl</keycap> while clicking to select
            additional blocks, or to remove selected blocks from the
            selection.
          </para>
          <para>
            The arrow keys on the keyboard can also be used, along
            with <keycap>Return</keycap>, to <emphasis
            role="bold">select</emphasis>, <emphasis
            role="bold">move</emphasis> and <emphasis
            role="bold">copy</emphasis> parts of the
            song:

            <itemizedlist>
              <listitem>
                <para><keycap>Shift</keycap> +
                <keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap>
                can be used to make selections using the keyboard</para>
              </listitem>
              <listitem>
                <para><keycap>Return</keycap> over a selected block
                will begin a move or copy</para>
              </listitem>
              <listitem>
                <para><keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap> to
                move the selected cells into position</para>
              </listitem>
              <listitem>
                <para><keycap>Return</keycap> to move the selected
                blocks into place</para>
              </listitem>
              <listitem>
                <para><keycap>Ctrl</keycap> + <keycap>Return</keycap> to
                <emphasis role="bold">copy</emphasis> the selected
                blocks into place</para>
              </listitem>
            </itemizedlist>

          </para>
          <para>
            Pressing <keycap>Esc</keycap> will cancel an editing operation that's in
            progress, or clear any selection.
          </para>
        </sect2>

        <sect2 id="chpt.song_editor.editor_modes.draw">
          <title>Draw Mode</title>
          <para>
            This mode is enabled if the
            
            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button containing a black brush.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_select.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>

            button is shown in the <link linkend="chpt.song_editor.main_controls">Controls</link> of the Song Editor and allows you to insert patterns by drawing -
            holding the left button while moving the mouse - blocks on
            the song canvas.
          </para>
          <para>
            Clicking a square on the song canvas will add a pattern
            (the square will turn colorful) and clicking it again will
            remove it. Holding the mouse button down will continue
            either adding or removing patterns from under the mouse
            cursor.
          </para>
          <para>
            Using the arrow keys on the keyboard, and the <keycap>Return</keycap>,
            will also add and remove patterns from the song.
          </para>

          <note>
	    <para>
              The keyboard input cursor is usually hidden unless you press one
              of the keys listed in <xref linkend="chpt.keyboard_and_mouse" />.
              You can alter this default behavior in the <link
              linkend="chpt.preferences.general_tab">General tab</link> of the
              Preferences.
            </para>
          </note>

        </sect2>

        <sect2 id="chpt.song_editor.editor_modes.song_mode">
	      <title>Song Mode</title>
          <para>
	        When <emphasis>Song Mode</emphasis>

            <inlinemediaobject>
              <imageobject>
                <imagedata fileref="generated_en/playerControlSongModeButton.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
            
            is selected in the <link linkend="sect.main_toolbar.transport_control">Transport Controls</link> of the Main Toolbar Hydrogen will play the sequence of patterns you have created in the Song Editor from left to right until it reaches the end of the song.
          </para>

          <tip>
	        <para>
	          By enabling <link linkend="sect.main_toolbar.transport_control">Loop Mode</link>

              <inlinemediaobject>
                <imageobject>
                  <imagedata fileref="generated_en/playerControlLoopButton.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>

              in the Transport Controls, the playback will move seamlessly to the beginning again after reaching the end of the song.
            </para>
          </tip>
        </sect2>

        <sect2 id="chpt.song_editor.editor_modes.pattern_mode">
	      <title>Selected Pattern Mode</title>
          <para>
	        When <emphasis>Pattern Mode</emphasis>

            <inlinemediaobject>
              <imageobject>
                <imagedata fileref="generated_en/playerControlPatternModeButton.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
            
            is selected in the <link linkend="sect.main_toolbar.transport_control">Transport Controls</link> of the Main Toolbar and

            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button with a horizontal black line.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_pattern_mode.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>

            is shown in the <link linkend="chpt.song_editor.main_controls">Controls</link> of the Song Editor
            
            Hydrogen will play the pattern that is currently selected in the Song Editor and displayed 
          in the <link linkend="chpt.pattern_editor">Pattern Editor</link>.
          </para>

          <note>
	        <para>
	          When referring to <emphasis role="bold">Pattern Mode</emphasis> in this manual the described context works with both <emphasis>Selected Pattern Mode</emphasis> and <emphasis>Stacked Pattern Mode</emphasis>.
            </para>
          </note>
        </sect2>

        <sect2 id="chpt.song_editor.editor_modes.stacked">
          <title>Stacked Pattern Mode</title>
          <para>
	        When <emphasis>Pattern Mode</emphasis>

            <inlinemediaobject>
              <imageobject>
                <imagedata fileref="generated_en/playerControlPatternModeButton.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
            
            is selected in the <link linkend="sect.main_toolbar.transport_control">Transport Controls</link> of the Main Toolbar and

            <inlinemediaobject>
              <textobject>
                <phrase>
                  Grey button with three horizontal black lines stacked vertically.
                </phrase>
              </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_stacked_mode.png" format="PNG"/>
              </imageobject>
            </inlinemediaobject>

            is shown in the <link linkend="chpt.song_editor.main_controls">Controls</link> of the Song Editor <emphasis>Stacked Pattern Mode</emphasis> is used.
          </para>

          <para>
            Normally when composing a pattern and editing it, you'll
            listen to that single pattern looping over and over again
            while working on it. Sometimes, however, it's useful to
            hear that pattern in the context of other patterns (for
            example, other instrument parts) while working on it.
          </para>
          <para>
            Stacked Pattern Mode will play multiple patterns simultaneously,
            on a loop. You can select or unselect a pattern by
            <keycap>Ctrl</keycap> + <emphasis>left clicking</emphasis> the
            pattern's name or by clicking the empty triangle in the <link linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song Editor. Patterns currently playing are indicated by green triangles while those about to start and stop when playback is looped to the beginning again are indicated using yellow and red ones respectively.
          </para>

          <tip>
            <para>
              You can alter the colors of the indicators in the <link linkend="chpt.preferences.appearance_tab.colors">Colors</link> tab of the Preferences.
            </para>
          </tip>
          
          <note>
	        <para>
	          When referring to <emphasis role="bold">Pattern Mode</emphasis> in this manual the described context works with both <emphasis>Selected Pattern Mode</emphasis> and <emphasis>Stacked Pattern Mode</emphasis>.
            </para>
          </note>
        </sect2>

      </sect1>

     <sect1 id="chpt.song_editor.sidebar">
       <title>Sidebar</title>

       <para>
	     The Sidebar of the Song Editor allows you to interact with and arrange the patterns of your song.
       </para>
      <para><emphasis>Left-clicking</emphasis> selects a pattern, <emphasis>double-clicking</emphasis> allows you to rename a pattern, <emphasis>drag-and-dropping</emphasis> allows you to rearrange the patterns, and <emphasis>right-clicking</emphasis> will show you a menu 
      where you can change a number of things:</para>
      
     <figure id="fig.song_editor.virtualPattern.selectedMenu">
        <title>The Pattern Options menu</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/Virtual_patterns_menu.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
      
      
      <itemizedlist mark="opencircle">
        
        <listitem>
          <para><emphasis role="bold">Duplicate</emphasis>: will copy the selected pattern to a new pattern in your song.
          </para>
          <note>
            <para>
              Note that patterns with the same name are not allowed.
            </para>
          </note>
        </listitem>
        
        <listitem>
          <para><emphasis role="bold">Delete</emphasis>: will completely remove the selected pattern from the song.
          </para>
        </listitem>
        
        <listitem>
          <para><emphasis role="bold">Fill/Clear</emphasis>: will open a window that allows you to fill/clear a 
          part of the song with the selected pattern by entering the start- and end bar.
           <informalfigure id="fig.fill_clear_pattern">
            <mediaobject>
          <textobject>
            <phrase>
              Dialog appearing when filling or clearing a pattern. To the left
              either "Fill" or "Clear" (below) can be checked and to the right
              the numerical text input form "From" and "To" (below) indicate the
              range of the operation. At the bottom there are "Cancel" (left)
              and "OK" (right) buttons.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/fill_clear_pattern.png" format="PNG" />
              </imageobject>
            </mediaobject>
            </informalfigure>
          </para>
        </listitem>
        
        <listitem id="chpt.song_editor.sidebar.properties">
          <para><emphasis role="bold">Properties</emphasis>: will open a window where you can change 
          the name of the pattern and also assign it to a certain category. Using the latter you can group pattern in the <link linkend="sect.sl.patterns">Sound Library</link>.
          </para>
          <figure id="fig.pattern_properties">
            <title>The Dialog to Change the Pattern Properties</title>
            <mediaobject>
          <textobject>
            <phrase>
              Dialog appearing when changing the properties of a pattern. At the
              top text input one specifies the "New Pattern Name". In the larger
              one below the "Pattern description". Underneath one can select the
              "Pattern category". At the bottom there are "Cancel" (left)
              and "OK" (right) buttons.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/pattern_properties.png" format="PNG" />
              </imageobject>
            </mediaobject>
           </figure>
           
          <note>
            <para>
              Note that you can choose one of the existing categories from the dropdown list,
          but you can also enter a new category name in the Pattern Category
          box.
            </para>
          </note>
        </listitem>
        
        <listitem>
          <para><emphasis role="bold">Load Pattern</emphasis>: will
          load a pattern from a saved pattern file.
          </para>
        </listitem>
        
        <listitem id="chpt.song_editor.sidebar.save_pattern">
          <para><emphasis role="bold">Save Pattern</emphasis>: stores the
          pattern in the <filename role="directory">patterns</filename> folder
          within the Hydrogen data directory (usually <filename
          role="directory">$HOME/.hydrogen/data/</filename>).
          </para>
        </listitem>
        
        <listitem id="chpt.song_editor.sidebar.export_pattern">
          <para><emphasis role="bold">Export Pattern</emphasis>: stores the
          pattern at a location determined via a file browser.
          </para>
        </listitem>
        
        <listitem id="chpt.song_editor.sidebar.virtual_pattern">
          <para><emphasis role="bold">Virtual Pattern</emphasis>: will
          open the virtual pattern editor.
          </para>
          <para>
	        Virtual patterns are a convenient way of grouping patterns together. 
          For example, say you have a song in which three patterns are always 
          played together at the start of each bar. Previously, the way to do this 
          in the pattern matrix was to explicitly enable the three patterns at each bar.
         </para>
         <para>
        	With virtual patterns we can assign a pattern to be a sort of meta-pattern 
	        that implicitly invokes these three patterns together when the new virtual pattern 
	        is enabled in the pattern matrix. This way, we only need to set one pattern every 
	        bar, instead of three.
         </para>
         <para>
        	Virtual patterns provide a function that's similar to the regular pattern editor, and one could argue that 
	        since a virtual pattern is also a regular pattern, we could have just merged the three 
	        patterns into this new one. However, the advantage that virtual patterns provide is that 
	        if one of the original three patterns changes, the virtual pattern automatically inherits 
        	the change. A virtual pattern can also invoke other virtual patterns.	
         </para>
        </listitem>        
      </itemizedlist>
     </sect1>
      
     <sect1 id="chpt.song_editor.timeline">
       <title>Timeline</title>

       <informalfigure id="fig.tempo_bar">
         <mediaobject>
          <textobject>
            <phrase>
              Picture showing the Timeline above the Song Ruler.
            </phrase>
          </textobject>
           <imageobject>
             <imagedata fileref="generated_en/songEditorTimeline.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </informalfigure>
        
       <para>The majority of songs consist of several parts (intro, verse, chorus ...) and
       often these parts will have a different tempo.  Hydrogen provides an easy way
       to let you change the tempo at the beginning of any column.  This is 
       done by adding <emphasis>Tempo Markers</emphasis> to your song.</para>
       <para>To add a Tempo Marker, you first need to show the Timeline by clicking the
       <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "P".
            </phrase>
          </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_view_playbackTrack.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>
       button at the bottom of the Song Editor or via the <link linkend="sect.main_menu.view">View</link> element of the Main Menu and enable it using the
       <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "Timeline".
            </phrase>
          </textobject>
         <imageobject>
           <imagedata fileref="generated_en/songEditorTimelineButton.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>
       button.
       </para>
       
       <note>
         <para>
         Please note that the Timeline is neither available in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link> nor in the presence of a <link linkend="sect.main_toolbar.jack_control.timebase_red"><abbrev>JACK</abbrev> Timebase controller</link>.
         </para>
       </note>
       
       <para>
       Now, simply <emphasis>left-click</emphasis> this widget in the middle or upper part and a
       window will pop up where you can enter the new tempo.
         
        <informalfigure id="fig.add_tempo_change">
         <mediaobject>
          <textobject>
            <phrase>
              Dialog for entering/altering a BPM Marker. In the two text inputs
              in at the upper half of the dialog one can specify the "BPM" (top)
              and the "Bar" (below). Underneath there is a large button titled
              "Delete BPM Marker". At the bottom there are "Cancel" (left)
              and "OK" (right) buttons.
            </phrase>
          </textobject>
           <imageobject>
             <imagedata fileref="generated_en/add_tempo_change.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>
            
       Once you have entered the new tempo and clicked OK, the tempo change will 
       show up on the Timeline. If you click the Tempo Marker again you can edit 
       the tempo, change the bar, or delete it.
       </para>

       <note>
         <para>
           When disabling the Timeline using the
           
           <inlinemediaobject>
             <textobject>
               <phrase>
                 Grey button containing the black characters "Timeline".
               </phrase>
             </textobject>
             <imageobject>
               <imagedata fileref="generated_en/songEditorTimelineButton.png" format="PNG" />
             </imageobject>
           </inlinemediaobject>

           button, the tempo resets to the previous value used before enabling the Timeline. This one will also be used for all parts of the song located prior to the first Tempo Marker. To indicate this behavior a special, faint Tempo Marker is shown at the first column that can <emphasis>not</emphasis> be removed by the user. You can, however, overwrite it with your custom tempo by clicking it and placing a regular Tempo Marker on top of it.
         </para>
       </note>

     </sect1>
     
     <sect1 id="chpt.song_editor.tag">
       <title>Tags</title>

       <para>
         In addition to altering the tempo when the song switches from e.g. intro into verse, 
         it is also very handy to have a clear indication of more general changes or special events in the song. For this purpose you can also add <emphasis>Tags</emphasis> to the song.
         These Tags are short text messages you can add at the beginning of a column. They will be shown in the <link linkend="chpt.director">Director</link> whenever the playhead passes them.
       </para>
       
       <para>
         To add a Tag, you can either <emphasis>left-click</emphasis> the bottom of the <link linkend="fig.tempo_bar">Timeline</link> or <emphasis>middle-click</emphasis> Timeline or <link linkend="fig.song_editor.song_ruler">Song Ruler</link>. A dialog will pop up that allows you to add text for any bar.
         
         <figure id="fig.add_tag">
           <title>Dialog Window for Adding Tags</title>
           <mediaobject>
             <imageobject>
               <imagedata fileref="generated_en/add_tag.png" format="PNG" />
             </imageobject>
           </mediaobject>
         </figure>

         Once you are done you will see a small <parameter>T</parameter> at the bottom of the Timeline and can view its content by hovering over it.
       </para>
     </sect1>

     <sect1 id="chpt.song_editor.playbackTrack">
	   <title>Playback Track</title>

	   <informalfigure id="fig.playbackTrack">
		 <mediaobject>
          <textobject>
            <phrase>
              Figure showing the Playback track on top of the Song Editor. At the
              left side there are several controls: the upper half consists of a
              larger fader and an "EDIT" (middle) and "MUTE" (right) button. The
              lower half contains the Main Controls of the Song Editor. The
              right half is made up by an dark-blue area may will contain the
              waveform of the Playback track but is empty in this example.
            </phrase>
          </textobject>
		   <imageobject>
			 <imagedata fileref="generated_en/PlaybackTrack.png" format="PNG" />
		   </imageobject>
		 </mediaobject>
	   </informalfigure>

       
	   <para>
         Using the Playback Track you can program your song alongside an existing audio file, for example a guitar track.
		 </para>

		 <note>
	       <para>
			 When a Playback Track is loaded, it will be played back every time audio transport in Hydrogen is rolling and <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link> is activated. 
           </para>
         </note>

		 <para>
		   To add a playback track to your song, you need to enable the playback
           track view. This can be done by either pressing
           <inlinemediaobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_view_playbackTrack.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
            left of the scroll bar at the bottom of the Song Editor or via the <link linkend="sect.main_menu.view">View</link> element of the Main Menu.
         </para>

         <para>
		   Left to the wave display, the controls of the Playback Track are displayed.

			 <itemizedlist>
				 <listitem>
				   <para>
                     <inlinemediaobject>
                       <textobject>
                         <phrase>
                           Grey button containing the text "Edit".
                         </phrase>
                       </textobject>
                       <imageobject>
                         <imagedata fileref="generated_en/songEditorPlaybackTrackEditButton.png" format="PNG"/>
                       </imageobject>
                     </inlinemediaobject>
                   : loads an audio file.</para>
                   <tip>
	                 <para>
	                   As an alternative, you can load an audio file by <emphasis>dragging</emphasis> it into Hydrogen and dropping over the Playback Track.
                     </para>
                   </tip>
                 </listitem>
                 <listitem>
				   <para>
                     <inlinemediaobject>
                       <textobject>
                         <phrase>
                           Grey button containing the text "Mute".
                         </phrase>
                       </textobject>
                       <imageobject>
                         <imagedata fileref="generated_en/songEditorPlaybackTrackMuteButton.png" format="PNG"/>
                       </imageobject>
                     </inlinemediaobject>
                   : <link linkend="def.mute">mutes</link> the Playback Track.</para>
                 </listitem>
                 <listitem>
				   <para>
                     <inlinemediaobject>
                       <textobject>
                         <phrase>
                           Horizontal fader
                         </phrase>
                       </textobject>
                       <imageobject>
                         <imagedata fileref="generated_en/songEditorPlaybackTrackFader.png" format="PNG"/>
                       </imageobject>
                     </inlinemediaobject>
                   : adjusts the volume. You can think of this fader as the mixer strip of the Playback Track. The resulting audio will be passed into the <link linkend="chpt.mixer.master_fader_strip">Master section</link> of the Mixer like any other strip too.</para>
				 </listitem>
			 </itemizedlist>
         </para>
         
	 </sect1>
     
     <sect1 id="sect.song_editor.automation_path">
	   <title>Automation Path</title>

       
      <figure id="fig.automation_path">
        <title>The Automation Path Widget</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/songEditorAutomationPathView.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

       <para>
	     The Automation Path allows you to control the overall <link linkend="def.velocity">velocity</link> of all notes throughout the song. It can be viewed using the shortcut <keycap>Alt</keycap> + <keycap>A</keycap> or via the <link linkend="sect.main_menu.view">View</link> option of the Main Menu.
       </para>

       <para>
	     <emphasis>Clicking</emphasis> the graph area introduces a new point determining when and to which value the velocity will be changed. Currently only linear interpolations of the velocity between the individual points are supported. You can <emphasis>drag</emphasis> a point to move it and you can delete one by dragging another point over it and "absorbing" it.
       </para>

       <note>
	     <para>
	       Whether the Automation Path is hidden or shown does not affect its activation state. It is <emphasis role="bold">always active</emphasis> and can't be disabled. But in its default setting it won't alter anything. In its current implementation you have to reset the Automation Path to its original state manually in order to disable it.
         </para>
       </note>
       
     </sect1>
   </chapter>
    
    <chapter id="chpt.pattern_editor">
    
      <title>Pattern Editor</title>
        <figure id="fig.PatternEditor_DrumMode">
         <title>Pattern Editor in Drum Mode</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/PatternEditor_DrumMode.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>

        <para>This is where it all happens, this is where you can make music :-)</para>
        
      <para>The <emphasis>Pattern Editor</emphasis>
      allows you to create and modify the pattern selected in the <link linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song Editor by adding/removing notes and tuning 
      a number of <link linkend="chpt.pattern_editor.note_properties">per-note properties</link>, like velocity and pan.
      The Pattern Editor 
      can be used in two modes: as <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> or as <link linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link>. You can switch between these 
      two by clicking the
      <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a small piano illustration with three white
              and two black keys.
            </phrase>
          </textobject>
        <imageobject>
          <imagedata fileref="generated_en/btn_drum_piano_off.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>

      and
      
      <inlinemediaobject>
        <textobject>
          <phrase>
            Blue button with a quasi-3D display a cylinder with black
            outlines, blue sides, and a white top.
          </phrase>
        </textobject>
        <imageobject>
          <imagedata fileref="generated_en/btn_drum_piano_on.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>
              
      button (located on the top-right of the Pattern Editor).
      </para>
      
      <note>
        <para>
          If you are editing a pattern in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Selected Pattern Mode</link> you will always hear the pattern you are 
          editing when you playback is rolling.
        </para>
        <para>
          If you are working in <link linkend="chpt.song_editor.editor_modes.stacked">Stacked Pattern Mode</link> you will hear the <emphasis>active</emphasis> pattern(s),
          not necessarily the pattern you are currently editing.
        </para>
      </note>

      <sect1 id="chpt.pattern_editor.general">
        <title>General</title>

        <sect2 id="chpt.pattern_editor.general.note_types">
          <title>Note Types</title>
          <para>
            <informalfigure id="fig.NoteOff_NoteLength">
              <mediaobject>
                <textobject>
                  <phrase>
                    Four notes are displayed in one line of the Pattern Editor.
                    The one to the left is rendered as black circle. The one
                    right of it consistents of an identical black circle as well
                    as a black triangle expands over two grid cells. The third
                    one is a a semi-transparent circle and the right-most one is
                    rendered as a blue circle.
                  </phrase>
                </textobject>
                <imageobject>
                  <imagedata fileref="generated_en/NoteOff_NoteLength.png" format="PNG" />
                </imageobject>
              </mediaobject>
            </informalfigure>
            There are a couple of different notes you can create and encounter
            within the Pattern Editor. From left to right: regular, custom
            length, inaccessible, and stop-note.
          </para>

          <itemizedlist>

            <listitem id="chpt.pattern_editor.general.note_types.regular">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Solid black circle.
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/NoteType_Regular.png" format="PNG"/>
                  </imageobject>
                </inlinemediaobject>
                : <emphasis role="bold">Regular note</emphasis> (or just
                <emphasis role="bold">note</emphasis>) can be created using
                <emphasis>left-clicking</emphasis> or <keycap>Enter</keycap>.
              </para>
              <para>
                Triggers playback of a whole sample of the associated instrument.
              </para>
              <note>
                <para>
                  The inner color of the circle represents the note's velocity.
                  Black: <option>80%</option>, red: <option>100%</option>, blue:
                  <option>50%</option>, white: <option>0%</option>. But in
                  contrast to a stop-note these circles do always have a black
                  outline.
                </para>
              </note>
            </listitem>

            <listitem id="chpt.pattern_editor.general.note_types.custom_length">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Solid black circle extended to the right by a rectangle of the same color.
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/NoteType_CustomLength.png" format="PNG"/>
                  </imageobject>
                </inlinemediaobject>
                : <emphasis role="bold">Custom length note</emphasis> can be
                set by <emphasis>right-click dragging</emphasis> a regular
                note.
              </para>
              <para>
                Similar to a regular note but only plays back the sample until
                the specified point. Afterwards the <link
                linkend="chpt.instrument_editor.envelope_parameters">Release</link>
                of the instrument kicks in to cut off the sample gracefully
                (small values) or to add a fade out (larger values).
              </para>
              <note>
                <para>
                  The length of the note is specified in ticks and changes along
                  with the tempo. The sample, however, consists of a certain
                  amount of audio frames and will <emphasis>not</emphasis>
                  change with tempo (unless you activated <link
                  linkend="sect.main_toolbar.bpm_control_and_metronome">Rubberband</link>).
                </para>
              </note>
            </listitem>

            <listitem id="chpt.pattern_editor.general.note_types.inaccessible">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Semi-transparent black circle.
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/NoteType_Inaccessible.png" format="PNG"/>
                  </imageobject>
                </inlinemediaobject>
                : <emphasis role="bold">Inaccessible note</emphasis>
              </para>
              <para>
                A regular note which is <emphasis>not</emphasis> part of the
                pattern you are currently editing. Instead, it belongs to a
                different one currently played as well. This could be within the
                same column in <link
                linkend="chpt.song_editor.editor_modes.song_mode">Song
                Mode</link> while the Pattern Editor is <link
                linkend="chpt.song_editor.main_controls.pattern_editor_lock">locked</link>,
                activated in <link
                linkend="chpt.song_editor.editor_modes.stacked">Stacked Pattern
                Mode</link>, or as part of a <link
                linkend="chpt.song_editor.sidebar.virtual_pattern">Virtual
                Pattern</link>.
              </para>
            </listitem>

            <listitem id="chpt.pattern_editor.general.note_types.stop_note">
              <para>
                <inlinemediaobject>
                  <textobject>
                    <phrase>
                      Solid blue circle.
                    </phrase>
                  </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/NoteType_StopNote.png" format="PNG"/>
                  </imageobject>
                </inlinemediaobject>
                : <emphasis role="bold">Stop-note</emphasis> can be created
                using <keycap>Shift</keycap> +
                <emphasis>left-clicking</emphasis>
              </para>
              <para>
                Stops rendering of all notes associated to the corresponding
                instrument. Afterwards the <link
                linkend="chpt.instrument_editor.envelope_parameters">Release</link>
                of the instrument kicks in to cut off the samples gracefully
                (small values) or to add fade outs (larger values).
              </para>
            </listitem>

          </itemizedlist>
        </sect2>

        <sect2 id="chpt.pattern_editor.controls">
          <title>Controls</title>

          <figure id="fig.PatternEditorControls">
            <title>Pattern Editor Controls</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/PatternEditorControls.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>The top part of the Pattern Editor contains a number of controls applying to both the <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> and the <link linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link>:</para>

          <itemizedlist mark="opencircle">
            <listitem id="chpt.pattern_editor.controls.size">
              <para>
                <inlinemediaobject>
          <textobject>
            <phrase>
              Two blue combo boxes showing "4.00" and "4" and are labeled "Size".
            </phrase>
          </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/lcd_size.png" format="PNG" />
                  </imageobject>
                </inlinemediaobject>

               : lets you choose the length of the pattern (in note values).
              </para>
              <para>
                The left combo box represents the numerator of your current measure. You can enter a decimal numerator, like <option>4.5/4</option>, but since resolution in Hydrogen is limited,
                some values are not supported and can not be entered.
              </para>

              <note>
                <para>
                  Hydrogen supports (only) the following denominators (right combo box): <option>1</option>, <option>2</option>, <option>3</option>, <option>4</option>, <option>6</option>, <option>8</option>, <option>12</option>, <option>16</option>, <option>24</option>, <option>32</option>, <option>48</option>, <option>64</option>, <option>96</option>, and <option>192</option>
                  because these are the factors of the maximum resolution (192 ticks per whole note).
                </para>
              </note>

              <tip>
                <para>
                  Typing <keycap>/</keycap> within the numerator (first combo box) also you to quickly jump to the denominator.
                </para>
              </tip>

            </listitem>

            <listitem id="chpt.pattern_editor.controls.res">
              <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Blue display showing "1/16" and titled "RES".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/lcd_res.png" format="PNG" />
              </imageobject>
              </inlinemediaobject>
                 : this is the current grid resolution (<option>1/4</option> through <option>1/64</option> with triplet-based resolutions marked as <option>1/8T</option>).
              </para>

              <note>
                <para>
                  If you are working with a resolution of <option>1/16</option>
                  you can't go back to <option>1/8</option> and remove an upbeat
                  16th note by clicking it. But you can still select and remove
                  it via dragging or keyboard.</para>
              </note>
            </listitem>

            <listitem>
              <para>
                <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing a black speaker symbol.
            </phrase>
          </textobject>
                  <imageobject>
                    <imagedata fileref="generated_en/btn_hear.png" format="PNG" />
                  </imageobject>
                </inlinemediaobject>
                : when checked Hydrogen will play back notes as they are being
                added to the pattern (even if transport is not rolling).
              </para>
              <note>
	            <para>
	              When disabled you will still hear the preview sound when
	              clicking on the instrument name in the <link
	              linkend="chpt.pattern_editor.sidebar">Sidebar</link>. Be sure to
	              click at the left-most position - where the preview is silent -
	              in case you don't want to get disturbed. Or switch the currently
	              selected instrument using <keycap>↑</keycap> and
	              <keycap>↓</keycap>.
                </para>
              </note>

            </listitem>

            <listitem>
              <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button showing a black 2 by 3 grid.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_quant_off.png" format="PNG" />
              </imageobject>
            </inlinemediaobject> : enables/disables quantization.  When checked,
            notes <link linkend="chpt.overview.recording">recorded</link> using
            incoming MIDI messages or Hydrogen's <link
            linkend="chpt.overview.virtual_keyboard">Virtual Keyboard</link>
            will automatically respect the grid resolution currently applied,
            just like notes inserted by clicking. </para>

            </listitem>

            <listitem id="chpt.pattern_editor.controls.input">
              <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a small piano illustration with three white
              and two black keys.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_drum_piano_off.png" format="PNG" />
              </imageobject>
            </inlinemediaobject> /  <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button with a quasi-3D display a cylinder with black
              outlines, blue sides, and a white top.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_drum_piano_on.png" format="PNG" />
              </imageobject>
            </inlinemediaobject> : switches between <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> and <link linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link>.</para>
            </listitem>

          </itemizedlist>

        </sect2>

        <sect2 id="chpt.pattern_editor.sidebar">
	      <title>Sidebar</title>

          <figure id="fig.pattern_editor.sidebar">
            <title>The Sidebar of the Pattern Editor</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/PatternEditorInstr_V2.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </figure>

        <para>
          The section on the left shows you which drumkit was loaded last
        and below that you can see the instruments that are part of the current
        song.
        </para>
        <note>
          <para>
            Keep in mind that these are not necessarily the instruments of the
            kit associated with the displayed name! Each song has its own set of
            instruments.
          </para>
        </note>

        <para><emphasis>Left-clicking</emphasis> the box containing the instrument name will play back a sample of the instrument. Which layer will be select depends on the horizontal position of the mouse click representing zero <link linkend="def.velocity">velocity</link> to the left and maximum velocity to the right. In addition, each instrument has its own set of features that are accessible by
        <emphasis>right-clicking</emphasis> the instrument.  From the context menu that pops up you can select.</para>

        <itemizedlist mark="opencircle">
          <listitem><para><emphasis role="bold">Delete notes</emphasis>:
          removes all notes for this instrument in this pattern.  </para></listitem>
          <listitem id="chpt.pattern_editor.sidebar.fill_notes">
            <para><emphasis role="bold">Fill notes</emphasis>: this allows you to fill
            up the pattern with notes for the selected instrument.
            <note>
	          <para>
	            Depending on the choice you make (<option>fill all</option>, <option>fill 1/2</option>, <option>fill 1/4</option> ...)
                notes will be placed at all, 1/2, 1/4, etc of the note positions <emphasis role="bold">that are allowed by
                the grid setting</emphasis>.  So be careful not to mix up the 'musical' 1/2-note and the 'fill 1/2' note.
              </para>
            </note>
            </para>
          </listitem>
          <listitem><para><emphasis role="bold">Randomize velocity</emphasis>:
          automatically apply a pseudo-random velocity to each note of that
          instrument in the pattern.
          <note>
	        <para>
	          The more velocity you set on the instrument,
          the more Hydrogen will hit <quote>hard</quote> on that instrument when
          played.
            </para>
          </note>
          </para></listitem>

          <listitem>
            <para><emphasis role="bold">Select notes</emphasis>:
            will select all the notes played on this instrument in the
            current pattern. They can then be copied, moved etc. in the
            Pattern Editor main area.
            </para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Edit all patterns</emphasis>:
            this section of the menu has actions which operate on
            notes played by the instrument in <emphasis>all</emphasis>
            the patterns of the song.
            </para>

            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">Cut notes</emphasis>:
                remove <emphasis>all</emphasis> notes played on
                this instrument, in all patterns, and keep them in the
                clipboard.
                </para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">Copy notes</emphasis>:
                copy <emphasis>all</emphasis> notes played on
                this instrument, in all patterns, to the clipboard.
                </para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">Paste notes</emphasis> :
                paste a multi-pattern selection from the clipboard to
                this instrument.
                </para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">Delete notes</emphasis>:
                delete all the notes associated with this instrument,
                without affecting the clipboard.
                </para>
              </listitem>

            </itemizedlist>

            <tip>
            <para>
              These can be used together to change the instrumentation
              of a song, entirely replacing one instrument with
              another by just copy and pasting the notes to a new
              instrument.
            </para>
            </tip>

          </listitem>

          <listitem>
            <para><emphasis role="bold">Instrument</emphasis>:
            this section of the menu has actions which operate on the
            instrument as a whole:
            </para>
            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">Rename
                instrument</emphasis>:
                change the name of the instrument.
                </para>
              </listitem>

              <listitem>
                <para><emphasis role="bold">Delete
                Instrument</emphasis>: well, deletes the instrument ;-)</para>
              </listitem>

            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para>The
        <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "M".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_instrument_line_mute_off.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        button <link linkend="def.mute">mutes</link> the instrument and
        <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "S".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/btn_instrument_line_solo_off.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        solos it.
        </para>

        <para>The order of the instruments can be rearranged by simply <emphasis>dragging</emphasis> an instrument
        up/down in the list and <emphasis>dropping</emphasis> it on a new position within the drumkit.  Doing so
        will not change the sequence of notes you have created for that instrument, nor will
        it change anything about the song or pattern you are working on.</para>

        <warning>
	      <para>
	        It <emphasis role="bold"> will</emphasis>, however, have an <emphasis
	        role="bold">impact</emphasis> on the <link
	        linkend="chpt.midi.note.mapping"><abbrev>MIDI</abbrev> note
	        mapping</link>.
          </para>
        </warning>

        <warning>
	      <para>
	        Rearranging the instruments will also mess up the <link linkend="sect.preferences.jack.per_instrument_outs">per-instrument</link> <abbrev>JACK</abbrev> output ports. Be sure to have your drumkit set up before starting wiring.
          </para>
        </warning>

      </sect2>
    </sect1>

      <sect1 id="chpt.pattern_editor.drumkit">
        <title>Drum Pattern Editor</title>

        <figure id="fig.PatternEditor_drumkit">
         <title>Pattern Editor in Drum Mode</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/PatternEditor_DrumMode.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>


        <para>
          Right of the <link
          linkend="chpt.pattern_editor.sidebar">Sidebar</link> area you can see
          your selected pattern. This is where you can add notes depending on
          the used pattern <link
          linkend="chpt.pattern_editor.controls.size">size</link> and <link
          linkend="chpt.pattern_editor.controls.res">resolution</link>.
        </para>
        <para>
          As in the Song Editor, the arrow keys can also be used to move around
          individual or group of notes, and notes can be placed or removed with
          <keycap>Return</keycap> (see <xref linkend="chpt.keyboard_and_mouse"
          />).
        </para>

        <para>
          Notes can be selected by <emphasis>dragging</emphasis> over them with
          the mouse (or <keycap>Shift</keycap> +
          <keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap>)
          and subsequently be deleted with <keycap>Delete</keycap> as well as be moved by
          <emphasis>dragging</emphasis> (or <keycap>Return</keycap> followed by
          <keycap>↑</keycap>|<keycap>↓</keycap>|<keycap>←</keycap>|<keycap>→</keycap>
          movements) them to a new location. This allows notes to be moved
          between different instruments or to adjust their timing. Movement in
          the horizontal direction is constrained by the currently selected grid
          <link linkend="chpt.pattern_editor.controls.res">resolution</link>.
          However, this can be overridden by holding down <keycap>Alt</keycap>
          while moving notes.
        </para>
          
        <para>
          Moving a selection of notes with <keycap>Ctrl</keycap> held down will copy
          them to the new location rather than moving, as in the Song Editor.
        </para>

        <para>
          Selected notes can also be copied to the clipboard with <keycap>Ctrl</keycap> + <keycap>C</keycap>, and pasted with <keycap>Ctrl</keycap> + <keycap>V</keycap>. When pasting, the relative positions of the input cursor at
          the time of the Copy and Paste operation will set the new position of pasted notes.
        </para>

        <tip>
          <para>So far we have only used the mouse or keyboard editing to create a pattern. But you can also <emphasis role="bold"><link linkend="chpt.overview.recording">record</link></emphasis> your beats. This is probably
          a more musical way of creating a pattern, but it's up to you to decide what works best for you.
          </para>
        </tip>

        <tip>
	        <para>
	          Also see <xref linkend="chpt.create_song"/> for a basic
              walk-through of how the Pattern Editor works.
          </para>
        </tip>
      </sect1>
      
      <sect1 id="chpt.pattern_editor.note_properties">
        <title>Note Properties Editor</title>
        
        <figure id="fig.note_properties_ruler">
          <title>The Note Properties Ruler set to Velocity</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/notePropertiesRuler.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>

      <para>Clicking on an instrument or adding/removing a note associated 
      will select this instrument.  Once an instrument is selected all note properties 
      of its notes will be shown in the form of vertical lines in the bottom window.  
      The lines represent the values for the selected property of each note of the selected instrument.
      You can select a different note-property from the note property drop-down list (located bottom-left).
      </para>
      
      <tip>
        <para>
          The color of the vertical bar will change according to the velocity value you have defined and can be customized in the <link linkend="chpt.preferences.appearance_tab.colors">Colors</link> tab of the Preferences.
        </para>
      </tip>

      <para>
        The following note properties are available: 
      </para>
      
      <itemizedlist mark="opencircle">
        <listitem id="chpt.pattern_editor.note_properties.velocity">
          <para><emphasis role="bold"><link linkend="def.velocity">Velocity</link></emphasis>: how hard the note is
          played (the volume of the note). This property also determines which sample of the instrument will be <link linkend="chpt.instrument_editor.layers.sample_selection">selected</link>.</para>
        </listitem>
        
        <listitem id="chpt.pattern_editor.note_properties.pan">
          <para><emphasis role="bold"><link linkend="def.pan">Pan</link></emphasis>: with this property you can move
           the stereo image position of the note (how loud it will be in the
          left/right output).</para>

          <tip>
	        <para>
	          
	          For a detailed description of how this Pan value does interact with the <link linkend="chpt.mixer.channel_strips.pan">instrument Pan</link> and the <link linkend="chpt.mixer.master_fader_strip.mixer_settings">Pan Laws</link> in the Mixer please see <xref linkend="def.pan" />.
            </para>
          </tip>
        </listitem>
        
        <listitem id="chpt.pattern_editor.note_properties.lead_and_lag">
          <para>
          <emphasis role="bold">Lead/Lag</emphasis>: Lead and Lag allows a slight note
          lead or lag in respect of the actual beat. The range is ca. 5 ticks (ca. 1/10 of quarter notes) which
          equals around ca. 10 ms at a tempo of 120bpm.  Changing the lead/lag can make a huge
          difference to the way your pattern sounds and feels.  It's a groove thing ;-) 
          </para>
        </listitem>
        
        <listitem id="chpt.pattern_editor.note_properties.notekey">
          <para>
          <emphasis role="bold">NoteKey</emphasis>: if you select this note parameter the 
          area where you can modify the parameter will change into a 'piano keyboard'
          </para>
          <figure id="fig.NoteKey">
            <title>The Note Properties Ruler showing the NoteKey Property</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/NoteKey.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>
          <para>
            The striped black and white area represents a piano keyboard and in the gray
            area you can choose the octave.  By moving the dots on the
            octave scale and the 'keyboard', you can choose any note
            value.
          </para>
          <note>
            <para>
            Note that the <link linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link> can also be used to
            change the note value of existing notes.
            </para>
          </note>
        </listitem>
        <listitem>
          <para>
            <emphasis role="bold">Probability</emphasis>: changing the
            Probability property of a note provides a way for Hydrogen
            to automatically create some variation in patterns. By
            setting the probability to less than <option>1.0</option>, a note may be
            randomly skipped: a note with probability <option>1.0</option> will
            <emphasis>always</emphasis> be played, a note with
            probability of <option>0.0</option> will <emphasis>never</emphasis> be
            played.
          </para>
        </listitem>
      </itemizedlist>

      <para>
        <emphasis>Clicking</emphasis> or <emphasis>dragging</emphasis> the value lines in the Note Properties Editor will
        set the property value. But often you'll want to set the properties of
        several notes at once, so there are a few ways to do this.

        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Drawing with the mouse:</emphasis></para>
            <para>
              Pressing the mouse button over the first note's property, you can
              hold down the mouse button and <emphasis>drag</emphasis> over multiple notes. This is
              great for quickly creating a crescendo from a filled set of notes.
            </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">
              Selecting multiple notes:</emphasis>
            </para>
            <para>
              The mouse or keyboard can be used to select multiple notes, which
              can then be modified all together by <emphasis>dragging</emphasis> them together. This
              can be useful for creating really consistent quiet grace notes. Alternatively, you can use the <emphasis>mouse wheel</emphasis> for a coarse adjustment or combine it with a pressed <keycap>Ctrl</keycap> key for fine adjustments.
            </para>
          </listitem>

        </itemizedlist>
      </para>

      </sect1>

      <sect1 id="chpt.pattern_editor.piano_mode">
        <title>Piano Roll Editor</title>
        
       <figure id="fig.PatternEditor_PianoMode">
         <title>Pattern Editor in Piano Mode</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/PatternEditor_PianoMode.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>

       <para>
	     The Pattern Editor can be used as Piano Roll Editor pressing the <link linkend="chpt.pattern_editor.controls.input">Input</link> button.
       </para>
       <para>While the <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> focuses on using Hydrogen as a drum machine, you can also use it an instrument via the Piano Roll Editor.
       It gives you a complete 'piano keyboard' so you can easily put down your tunes.</para>
       <para>You can compare the Piano mode to the <link linkend="chpt.pattern_editor.note_properties.notekey">NoteKey</link> property in the Note Properties Editor. Only here you have a 
       complete piano keyboard, so you don't have to select the octave
       first.</para>

       <note>
	     <para>
	       When entering multiple notes in one column - as a chord - the corresponding symbol in the <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> will be prepended with e.g. a <option>3x</option> to indicate the presence of three separate notes. Also, to adjust the note properties of the individual notes within a chord can be done by <emphasis>right-clicking</emphasis> on the note and <emphasis>dragging</emphasis> the mouse up or down.
         </para>
       </note>
      
      </sect1>
     
    </chapter>

  <chapter id="chpt.sound_library" xreflabel="Instrument rack">
    <title>Sound Library (Drumkit/Pattern/Song Manager)</title>

      <figure id="fig.soundlibrary">
        <title>The Soundlibrary</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/SoundLibrary.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The Sound Library helps you manage your <link linkend="chpt.overview.drumkits">drumkits</link>,
      favourite patterns, and favourite songs. When making new songs or drumkits, it allows you to reuse and mix instruments as well as patterns from other kits and songs.
      </para>

      <para>
	    It is located in the Instrument Rack in the lower right corner of Hydrogen, which can be shown or hidden via the <link linkend="sect.main_menu.view">View</link> option in the Main Menu or via the <link linkend="sect.main_toolbar.gui_state">corresponding button</link> in the Main Toolbar. The Instrument Rack does either show the <link linkend="chpt.instrument_editor">Instrument Editor</link> or the Sound Library depending on what is chosen in the <link linkend="sect.main_menu.view">View</link> option in the Main Menu or the corresponding buttons at the top of the Instrument Rack.
      </para>

      <sect1 id="chpt.sound_library.drumkits">
        <title>Drumkits</title>

        <para>The list of <link linkend="chpt.overview.drumkits">drumkits</link> comprises kits present at both system and user level as well as those loaded via <link linkend="chpt.overview.cli">command-line option</link> or <link linkend="chpt.osc.command.load_drumkit">OSC command</link>.</para>
        <para>
          The <emphasis role="bold">System drumkits</emphasis> are those installed with your package manager or when <link linkend="chpt.compilation">compiling</link> Hydrogen manually. Their location is determined by the compile-time prefix. On
        Unix-like operating systems, this is usually <filename
        role="directory">/usr/share/hydrogen/data/drumkits</filename>, or
        possibly <filename
        role="directory">/usr/local/share/hydrogen/data/drumkits</filename>.
        These kits are available to all users on the system and you usually have no write access to them which is why you only have read access to the kit's properties and can not delete them. If you want to change one of these kits you have to load it via right click and <link linkend="sect.main_menu.drumkits.save_as">save</link> it first. This will add a modified copy on user level.</para>

        <para>The <emphasis role="bold">User drumkits</emphasis> are those which you can manage yourself. They
        are stored in the Hydrogen data
        directory (usually <filename role="directory">$HOME/.hydrogen/data/</filename>) within the <filename role="directory">drumkits</filename>
        subfolder. When you have
        created a new drumkit via <link linkend="sect.main_menu.drumkits.new">New</link> in the Drumkit option of the Main Menu, you can save it using <link linkend="sect.main_menu.drumkits.save_as">Save As</link> from the same menu. In addition, you can also <link linkend="sect.main_form.online_import_drumkit">Online Import</link> a number of drumkits provided by the dev team of Hydrogen.
        </para>

        <warning>
          <para>If you are using Hydrogen for creating songs or drumkits or redistribute existing ones you need to pay special attention to the
          <link linkend="chpt.license">licenses</link> of the drumkit(s) you are using.
          </para>
          <para>DISCLAIMER : Hydrogen is not responsible for the drumkits that are 
          made available for download by our users, either via the <ulink url="hydrogen-music.org">hydrogen-music.org</ulink> or
          via any other channel.</para>
       </warning>

       <para>To <emphasis role="bold">load a drumkit</emphasis> via the Sound Library, <emphasis>right-click</emphasis> the drumkit and select
       <parameter>Load</parameter>.  This will replace your current drumkit
       with the one that you selected.  To <emphasis role="bold">load a single instrument</emphasis> from that
       kit, <emphasis>left-click</emphasis> the <option>&#x25B6;</option> to the left of the
       drumkit's name to show all the instruments.  With your left mouse
       button, <emphasis>click</emphasis> and <emphasis>drag</emphasis> the instrument into your current kit.  The
       instrument will be added to the drumkit that you currently have
       loaded.
       </para>
      </sect1>

      <sect1 id="sect.sl.songs">
        <title>Songs</title>

        <para>To access songs via the Sound Library, you have to put them within the Hydrogen data
        directory (usually <filename role="directory">$HOME/.hydrogen/data/</filename>) into the <filename role="directory">songs</filename>
        subfolder.
        To remove them, remove the file from that folder.</para>
      </sect1>      
      
      <sect1 id="sect.sl.patterns">
        <title>Patterns</title>

        <para>To access patterns via the Sound Library, you have to put them within the Hydrogen data
        directory (usually <filename role="directory">$HOME/.hydrogen/data/</filename>) into the <filename role="directory">patterns</filename>
        subfolder.

        <note>
	      <para>
	        This is done automatically when using the <link linkend="chpt.song_editor.sidebar.save_pattern">Save Pattern</link> option in the Sidebar of the Song Editor but not when using <link linkend="chpt.song_editor.sidebar.export_pattern">Export Pattern</link> via the same Sidebar or <link linkend="sect.main_menu.projects.export_pattern_as">Export Pattern As</link> in the Project option of the Main Menu.
          </para>
        </note>
        </para>
        <para>Before you save a pattern, be
        sure to give it a title and a category. This can be done by <emphasis>right-clicking</emphasis> on the pattern in the Sidebar of the Song Editor, selecting
        <link linkend="chpt.song_editor.sidebar.properties">Properties</link> and entering the details.
        You can use one of the categories already
        provided, or create your own categories by simply typing in a category
        name.  The category name is important, because the patterns will be
        filed by category in the Sound Library.</para>

      </sect1>
    </chapter>

    <chapter id="chpt.instrument_editor">
      <title>Instrument Editor</title>

      <figure id="instrumenteditor.general">
        <title>The Instrument editor General view</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/Instrument_General.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
	    The Instrument Editor is located in the Instrument Rack in the lower right corner of Hydrogen, which can be shown or hidden via the <link linkend="sect.main_menu.view">View</link> option in the Main Menu or via the <link linkend="sect.main_toolbar.gui_state">corresponding button</link> in the Main Toolbar. The Instrument Rack does either show the <link linkend="chpt.instrument_editor">Instrument Editor</link> or the Sound Library depending on what is chosen in the <link linkend="sect.main_menu.view">View</link> option in the Main Menu or the corresponding buttons at the top of the Instrument Rack.
      </para>

      <sect1 id="chpt.instrument_editor.general">
        <title>General</title>
        
        <para>When clicking the <option>General</option> button in the Instrument Editor you can adjust several
        parameters that apply to the particular instrument (and all its <link linkend="def.layer">layers</link>) selected in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link> of the Pattern Editor.
        </para>

        <note>
          <para>It's important that you understand <link
          linkend="chpt.overview.drumkits">Drumkit Concepts</link> and a couple of basic concepts of sound synthesis described in the <link linkend="glossary">Glossary</link> in order to continue
          on. To ease reading, several of the latter concepts are linked in the text.</para>
        </note>
        
        <sect2 id="chpt.instrument_editor.envelope_parameters">
          <title>Envelope Parameters</title>
          
          <informalfigure id="fig.instrument_editor.envelope_parameters">
            <mediaobject>
          <textobject>
            <phrase>
              Four rotaries are displayed. From left to right: "ATTACK",
              "DECAY", "SUSTAIN", and "RELEASE".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_envelope.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>When a note associated with this instrument is triggered, its volume is run through an
          <link linkend="def.adsr">ADSR Envelope</link>. Its particular settings can be adjusted using the envelope parameters located right below the instrument name.</para>

          <itemizedlist>
            <listitem id="chpt.instrument_editor.general.attack">
              <para><emphasis role="bold"><link linkend="def.attack">Attack</link></emphasis>: the amount
              of <emphasis>time</emphasis> that the volume of the <link linkend="def.sample">sample</link> goes
              from <option>0</option> to the full <link linkend="def.velocity">velocity</link> of the note. If the value is <option>0</option>, the
              sample will play back immediately at full velocity.
              </para>
            </listitem>
            <listitem id="chpt.instrument_editor.general.decay">
              <para><emphasis role="bold"><link linkend="def.decay">Decay</link></emphasis>: the amount of
              <emphasis>time</emphasis> for the volume of the <link linkend="def.sample">sample</link> to go from
              full <link linkend="def.velocity">velocity</link> down to the sustain volume.  If the value is <option>0</option>, the
              sample will immediately skip from the full velocity to the <link linkend="def.sustain">sustain</link>
              volume.
              </para>
            </listitem>
            <listitem id="chpt.instrument_editor.general.sustain">
              <para><emphasis role="bold"><link linkend="def.sustain">Sustain</link></emphasis>: the
              <emphasis>volume</emphasis> to play the note after the <link linkend="def.decay">decay</link> phase
              is over and until the note is released.  If set to <option>0</option>, the note
              will be silent.  If set to <option>1.0</option>, the note will play at full
              <link linkend="def.velocity">velocity</link>.</para>
            </listitem>
            <listitem id="chpt.instrument_editor.general.release">
              <para><emphasis role="bold"><link linkend="def.release">Release</link></emphasis>: the
              <emphasis>time</emphasis> to fade out the note from the <link linkend="def.sustain">sustain
              volume</link> back down to <option>0</option> (silent).  If set to <option>0</option>, the note will fade
              out in the minimum amount of time (about 5 ms).  If set to <option>1</option>, it
              will fade out for the maximum time available.
              </para>
              <para>
                Note, however, that
              this only affects notes for which you set a note length smaller
              than the underlying sample length (see <xref
              linkend="chpt.pattern_editor.drumkit"/>). All other notes are
              played back till the end of the sample without reaching the
              release phase.
              </para>
            </listitem>
          </itemizedlist>
          
          <note id="fn.adsrtimes">
            <para>All transitions between the individual <abbrev>ADSR</abbrev>
            phases are done using exponential functions.
            </para>
            <para>The <link linkend="chpt.instrument_editor.general.attack">Attack</link>, <link linkend="chpt.instrument_editor.general.decay">Decay</link>, and <link linkend="chpt.instrument_editor.general.release">Release</link> parameters are all set by
            the number of <link linkend="def.sample">audio samples</link>.  This means
            that the time changes depending on the sample rate of your sound
            card.  The max time for each of them is 100,000 audio samples
            (type. 2.27 sec at 44.1 kHz).</para>
          </note>

          <para>If the <link linkend="def.sample">sample</link> is shorter than the times that you specify, the
          sample will end, regardless of which phase of the <link linkend="def.adsr">ADSR</link> it is in.  If
          the note is sustained, it does <emphasis>not</emphasis> draw out the
          note while you are holding it.  It only holds the <link linkend="def.gain">gain</link> (volume)
          parameter during that time.
          </para>

        </sect2>

        <sect2 id="chpt.instrument_editor.gain_and_mute_group">
          <title>Gain and Mute Group</title>

          <informalfigure id="fig.instrument_editor.gain_and_mute_group">
            <mediaobject>
          <textobject>
            <phrase>
              In the upper half there is a display showing "1.00" (left) next to
              a rotary titled "GAIN" (middle) and a display with corresponding
              decrease and increase buttons (right) titled "MUTE GROUP". In the
              lower part there are two checkboxes: "AUTO-STOP-NOTE" (left) and
              "APPLY-VELOCITY" (right).
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_mute_group.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>The <emphasis role="bold"><link linkend="def.gain">Gain</link></emphasis> adjusts the overall volume of all <link linkend="def.sample">samples</link> associated with this Instrument. This Gain is
          applied in addition to the one you set for each <link linkend="chpt.instrument_editor.layers.controls.layer_gain">layer</link> and before the one
          that is set in the <link linkend="chpt.mixer.channel_strips.fader_and_lcd">Instrument Channel Strips</link>.  If the
          set to <option>0</option>, the instrument will be
          silent.  If the Gain is <option>1.0</option>, the volume of the samples will not be
          adjusted.  If the Gain is set higher, the samples will be
          amplified.</para>

          <warning>
            <para>It is very easy to set the <guibutton>Gain</guibutton> too
            high, causing your sample to <link linkend="def.clipping">clip</link>.  Remember to test the Gain with
            full-<link linkend="def.velocity">velocity</link> notes.  If you clip your signal here, it will only get
            worse as Hydrogen processes it.</para>
          </warning>

          <para>Hydrogen provides more <emphasis role="bold"><link linkend="def.mutegroup">Mute Groups</link></emphasis> than you know what to do with
          (over 256).  A Mute Group is a grouping of instruments which's playback is
          mutually exclusive - only one instrument of the group may be playing at a
          time.  If one is playing and another instrument in the group is
          triggered, the former will immediately be silence (<link linkend="def.mute">muted</link>) and the latter starts playing.  This is useful, especially, for instruments like
          hi-hats where the opened and closed sound are incorporated into the drumkit as different
          instruments.</para>

          <para>If the Mute Group is set to <option>Off</option>, then the
          instrument is not part of any mute grouping.  If the Mute Group is set
          to any number, then that is the group that the instrument is a part
          of.  To set other instruments into the same grouping, set their Mute
          Group parameter to the same number.  (For example, to group all the
          high-hat instruments, you can set all their Mute Group parameters to
          <option>1</option>.  To have a snare drum Mute Group, set their Mute Group parameters
          to <option>2</option>.)
          </para>

          <para>If the <emphasis role="bold">Auto-Stop-Note</emphasis> box is checked, Hydrogen will immediately stop any playing <link linkend="def.sample">samples</link>
          belonging to this instrument whenever the instrument is re-triggered, e.g. by another note.</para>
          <para>This option is particularly useful when you are using long samples like a 
          crash or some existing audio that you have sampled (like a looped voice in a 
          dance/electro song).  For the crash you will need to use the Auto Stop-Note when 
          you are sequencing multiple notes in fast succession and want to make it sound realistic.  If you do 
          not check this option the cymbal will start to sound like multiple cymbals 
          instead of only one (since the sample of each individual hit will be played completely).
          For the voice sample this option is useful if you are trying to get that 'stuttering' effect.

          </para>
          
          <para>
             The <emphasis role="bold">Apply Velocity</emphasis> box lets the user decide whether Hydrogen should apply the note <link linkend="def.velocity">velocity</link> to the <link linkend="def.sample">sample</link> being played.
          </para>

          <tip>
	        <para>
	          The note velocity can set it the <link linkend="chpt.pattern_editor.note_properties.velocity">Note Properties Editor</link>.
            </para>
          </tip>
          
          <para>
             When activated, Hydrogen will apply the note velocity to the sample
             gain in addition to e.g. the <link linkend="chpt.instrument_editor.layers.controls.layer_gain">layer gain</link>,
             the <link linkend="chpt.instrument_editor.gain_and_mute_group">instrument gain</link>, the <link linkend="chpt.instrument_editor.layers.controls.component_gain">component gain</link>, or the <link linkend="chpt.mixer.channel_strips.fader_and_lcd">instrument volume</link>.
             (A full list of all contributions can be found in <xref linkend="def.gain"/>).
              If all the <link linkend="def.layer">layer</link> samples are <link linkend="def.normalization">normalized</link>, this option should be used.
          </para>

          <note>
	        <para>
              By default this option will be selected as this is the way older versions of Hydrogen used to work.
            </para>
          </note>
          
          <para>
              When not activated, the note velocity will only be used to <link linkend="chpt.instrument_editor.layers.sample_selection">select</link> the sample to be played,
              but the sample gain itself will not be changed.
              This is useful for set of samples that already have their gain "hard-coded".
          </para>
        </sect2>  

        <sect2 id="chpt.instrument_editor.filter">
          <title>Filter Parameters</title>

          <informalfigure id="fig.instrument_editor.filter">
            <mediaobject>
          <textobject>
            <phrase>
              From left to right: a button titled "BYP", a rotary titled
              "CUTOFF", and another one titled "RESONANCE".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_filter.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>The filter used in here is a <link linkend="def.lowpassfilter">low-pass</link> <link linkend="def.resonancefilter">resonance filter</link>.  If you don't wish to
          use is, click the <option>BYP</option> button (bypass) so that it's
          red.  If it's not red, then the filter is active.  The <link linkend="def.cutoff">cutoff</link>
          parameter adjusts the cutoff frequency for the filter.  The <link linkend="def.resonance">resonance</link>
          parameter adjusts how much to boost to provide at the cutoff frequency.  If the
          resonance is set to <option>0</option>, then the filter is just a simple low-pass
          filter.</para>

          <note>
            <para>The cutoff frequency of the filter varies with the sample rate
            of your audio card.  The range of the knob <option>0</option> to <option>1.0</option>) is optimized
            for a 48,000 kHz sample rate.</para>
            <!-- NOTE:  I tried to reverse engineer the LPRF in the
                 sampler to calculate what the cutoff frequency is.
                 I think it's *something* kind of like this:

                 f = cutoff * samplerate / 2

                 - OR MAYBE -

                 f = sqrt(cutoff) * samplerate / 2   (or / 4)

                 http://en.wikipedia.org/wiki/Low-pass_filter
                 -gabriel
            -->
          </note>
        </sect2>
        
        <sect2 id="chpt.instrument_editor.pitch_shift_parameters">
          <title>Pitch Shift Parameters</title>

          <informalfigure id="fig.instrument_editor.pitch_shift_parameters">
            <mediaobject>
          <textobject>
            <phrase>
              From left to right: a display showing the total pitch and three
              rotaries titled "PITCH", "FINE",  and "RANDOM".

            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_pitch.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>
          
          <para> The first two knobs control the pitch shift offset.
                 You can use it to change the tuning of the instrument.
                <emphasis role="bold">Pitch</emphasis> is the <emphasis>Coarse</emphasis> control and has quantized steps of half-tones from <option>-24</option> to <option>+24</option>.
                <emphasis role="bold">Fine</emphasis> is the <emphasis>Fine</emphasis> control and has quantized steps of cents of half-tones from <option>-0.50</option> to <option>+0.50</option>.
          </para>
          <para>The <emphasis role="bold">Random</emphasis> parameter allows you to randomly vary the pitch
              of the <link linkend="def.sample">sample</link> every time it is triggered.  The value is set between <option>0</option>
              and <option>1.0</option>.

              <note>
                <para>
                  The pitch change is fairly small, almost always between &#177;1 half-steps
                  &#10761; value.  Using this sparingly can help your sequences to sound
                  more like a real drummer.	              
                </para>
              </note>

          </para>
        </sect2>   
        

        <sect2 id="chpt.instrument_editor.midi_out_settings">
          <title><abbrev>MIDI</abbrev> Out Settings</title>

          <informalfigure id="fig.instrument_editor.midi_out_settings">
            <mediaobject>
          <textobject>
            <phrase>
              Two displays with corresponding decrease and increase buttons. The
              left one is titled "CHANNEL" and the right one "NOTE".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_midi_out.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>
            Hydrogen is capable of generating <abbrev>MIDI</abbrev> messages
            that you can use to trigger any external <abbrev>MIDI</abbrev>
            device or application.  To do this, you need to configure the
            <abbrev>MIDI</abbrev> output <emphasis
            role="bold">Channel</emphasis> and <emphasis
            role="bold">Note</emphasis> for an instrument.
          </para>

          <note>
            <para>
              In order to enable <abbrev>MIDI</abbrev> output, the <emphasis
              role="bold">channel</emphasis> of an instrument must be set to a
              value other than <option>off</option>, like <option>10</option>,
              and the instrument must contain at least <emphasis role="bold">one
              sample</emphasis>. Having just an empty one is fine.
            </para>
          </note>

          <para>
            From now on every time a note is played for that instrument (in the
            Hydrogen sequencer) a <abbrev>MIDI</abbrev> message will be sent to
            your external app/device and trigger a sound.  This way you can use
            Hydrogen as a pure sequencer for other apps, or combine the internal
            Hydrogen sampler with multiple external apps/devices.
          </para>

          <note>
	        <para>
	          By enabling <emphasis role="bold">Use output note as input</emphasis> in the <link linkend="chpt.preferences.midi_tab"><abbrev>MIDI</abbrev> system</link> tab of the Preferences dialog the number specified in the <emphasis role="bold">Note</emphasis> field will also be used to associate the current instrument with the corresponding incoming <abbrev>MIDI</abbrev> messages.
            </para>
          </note>
        </sect2>
        <sect2 id="chpt.instrument_editor.HH_pressure_group">
          <title>Hi-Hat Pressure Group</title>

          <informalfigure id="fig.instrument_editor.HH_pressure_group">
            <mediaobject>
          <textobject>
            <phrase>
              Three displays with corresponding decrease and increase buttons titled
              "HH PRESS. GRP", "MIN. RANGE", and "MAX RANGE" (from left to right).
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrument_editor_hihat_pressure_group.png" format="PNG"/>
              </imageobject>
            </mediaobject>
          </informalfigure>
          
            <para>The hi-hat is a particular instrument of the drumkit as its sound can be changed by pressing the foot pedal.
            </para>
            <para>For e-drum owners, the hi-hat pressure group enables to group different hi-hat instruments
                together, for example closed, half closed, fully open.
            </para>
            <para><emphasis role="bold">Pressure Group</emphasis>: you can assign more instruments to the same group.
                You can create many groups. For example one group for the different opening levels of a hi-hat when playing 
                the top of it, another group when playing the edge.
                 Another example: timpanis - create a group for each timpani and the pressure will change the note.
            </para>
            <para><emphasis role="bold">Range</emphasis>: set the minimum and maximum pressure for each instrument.
              Each instrument of a given group should seat in its own separate pressure range.
               The range will decide at what pressure level the instrument will be played.
                For example, if your closed hi-hat has range from <option>0</option> to <option>20</option>,
               when the hi-hat pedal is pressed between <option>0</option> and <option>20</option> the closed hi-hat is played.
            </para>

        </sect2>      
        
      </sect1>
      
      
      <sect1 id="chpt.instrument_editor.layers">
        <title>Layers</title>
        
        <figure id="instrumenteditor.layers">
        <title>The Instrument Editor Layers View</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/Instrument_Layers.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </figure>
        
        <para>When clicking the <option>Layers</option> button in the Instrument Editor you can adjust the <link linkend="def.sample">samples</link> and synthesizer parameters of the particular <link linkend="def.layer">layers</link> of the instrument selected in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link> of the Pattern Editor.
        </para>
        
        <sect2 id="chpt.instrument_editor.layers.components">
          <title>Components</title>

          <informalfigure id="fig.instrument_editor.layers.components">
            <mediaobject>
          <textobject>
            <phrase>
              In the center you can find the name of the Drumkit component and
              at the right end a button to open a context menu.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrumentEditorComponentName.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>
	        Right below the <option>General</option> and <option>Layers</option> button you find the name of the currently selected <link linkend="def.component">component</link>. In the drop down menu accessible by pressing
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button with a black filled triangle pointing downwards.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrumentEditorComponentDropDown.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
            you find a list of all components available in the current drumkit and can select them via a <emphasis>left click</emphasis>. Below a separator you can also find three options to <option>add</option> a new component, <option>delete</option> the current one, or <option>rename</option> the current one.
          </para>

          <warning>
	        <para>
	          The components are shared by all instruments. This means deleting it will delete it including all associated layers from a <emphasis>all</emphasis> instruments and not just the currently selected one.
            </para>
          </warning>
        </sect2>

        <sect2 id="chpt.instrument_editor.layers.layers">
          <title>Layers</title>

          <figure id="fig.instrument_editor.layers.layers">
            <title>The Layer Section of the Instrument Editor</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/instrumentEditorLayers.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
	        Next you find a listing of all layers of the current component in the selected instrument. The wave form of the sample loaded to the currently selected layer (the one enclosed by a red rectangle) is displayed below.
          </para>

          <note>
	        <para>
	          Empty layers will be displayed as <option>&#60; - &#62;</option>.
            </para>
          </note>

          <para>
            Using
              <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "LOAD LAYER".
            </phrase>
          </textobject>
                <imageobject>
                  <imagedata fileref="generated_en/loadLayer_off.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
            you can load a sample into the currently selected layer, using
              <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "DELETE LAYER".
            </phrase>
          </textobject>
                <imageobject>
                  <imagedata fileref="generated_en/deleteLayer_off.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
            you can delete the current layer, and using
              <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "EDIT LAYER".
            </phrase>
          </textobject>
                <imageobject>
                  <imagedata fileref="generated_en/editLayer_off.png" format="PNG" />
                </imageobject>
              </inlinemediaobject>
            you can open the <link linkend="chpt.sample_editor">Sample Editor</link> to customize the sample loaded to the currently selected layer.
          </para>

          <tip>
	        <para>
	          Alternatively you can also <emphasis>double-click</emphasis> the wave display to open the <link linkend="chpt.sample_editor">Sample Editor</link>.
            </para>
          </tip>

          <note>
	        <para>
	          When loading a sample it will per-default have its active area set to the whole velocity range. By checking the <emphasis role="bold">Set auto velocity</emphasis> option all layers will be assigned an equally sized velocity range corresponding to their layer number. Note, however, that this option will overwrite all existing velocity ranges.
            </para>
          </note>

          <para>
	        Above the layer listing you find boxes in different shades of grey indicating which range of note <link linkend="def.velocity">velocity</link> will trigger which sample (left: zero velocity, right: maximum velocity). <emphasis>Left-clicking</emphasis> on any of these boxes will play back the sound of associated sample modulated by the velocity corresponding to the horizontal position of the mouse cursor.

            <tip>
	          <para>
	            This will be quite handy when adjusting the velocity ranges of the layers.
              </para>
            </tip>
          </para>

          <para>
	        You might have already noticed in the picture above or for shipped drumkits in the Hydrogen GUI that a layer row contains a light blue rectangle that those not quite fill the whole row. This rectangle indicates the range in velocity the associated sample should be triggered. This way you can separate samples for soft hits, regular hits, and so on for each instrument (component). Whenever two rectangles do overlap a triggered note with a velocity within this shared range will consult the <link linkend="chpt.instrument_editor.layers.sample_selection">Sample Selection</link> to determine which sample will be played back. You can adjust the velocity ranges of each layer by <emphasis>left-clicking</emphasis> the left or right end of the light blue rectangles and <emphasis>dragging</emphasis> it to the desired position.
          </para>

          <note>
	        <para>
	          If there is a(n accidental) hole between two adjacent velocity ranges, the layer closest to the triggered velocity will be used.
            </para>
          </note>
        </sect2>
          
        <sect2 id="chpt.instrument_editor.layers.sample_selection">
          <title>Sample Selection</title>

          <informalfigure id="fig.instrument_editor.layers.sample_selection">
            <mediaobject>
          <textobject>
            <phrase>
              A display titled "SAMPLE SEL." with a button to open show the
              different choices to the right.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrumentEditorSampleSelection.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>

          <para>
            Having a set of samples containing different sample versions of similar sound for the same note velocity is a good way to make your drumkit sound more natural. After all, drummers for example never hit the drum set twice the exact same way.
          </para>

          <para>
	        Hydrogen tries to emulate this behavior by providing multiple <link linkend="chpt.instrument_editor.layers.layers">layers</link> with overlapping velocity ranges. <emphasis>How</emphasis> the selection of the resulting sample will take place is for you to decide using the <emphasis role="bold">Sample Sel.</emphasis> dropdown menu at the bottom of the Instrument Editor.
          </para>
                    
          <itemizedlist>
            <listitem>
              <para><option>First in Velocity</option>:
              will select the first sample available in the velocity set - the one of the layer most further down in the layer listing.

              <note>
	            <para>
                  This is the way previous versions of Hydrogen were working.
                </para>
              </note>
              </para> 
            </listitem>
            <listitem>
              <para><option>Round Robin</option>:
              will cycle through the different samples one after another as note a in the same velocity range are played.
              </para> 
            </listitem>
            <listitem>
              <para> <option>Random</option>:
              will select a random sample inside the velocity range for each note played.
              </para> 
            </listitem>
          </itemizedlist>
        </sect2>

        <sect2 id="chpt.instrument_editor.layers.controls">
          <title>Controls</title>

          <informalfigure id="fig.instrument_editor.layers.controls">
            <mediaobject>
          <textobject>
            <phrase>
              Four rotaries with corresponding displays: "L. GAIN" (top left),
              "C. VOLUME" (top right), "PITCH" (bottom left), and "FINE" (bottom right).
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/instrumentEditorControls.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>

          <itemizedlist>
	        <listitem id="chpt.instrument_editor.layers.controls.layer_gain">
	          <para>
	            <emphasis role="bold">Layer Gain</emphasis>:
                adds <link linkend="def.gain">Gain</link> for the currently selected layer and the associated sample.
              </para>
            </listitem>
            <listitem id="chpt.instrument_editor.layers.controls.component_gain">
	          <para>
	            <emphasis role="bold">Component Gain</emphasis>:
                adjusts the volume of all layers within the current component with respect to the ones of the other instruments.
                
                <tip>
	              <para>
	                The resulting audio from all layers of each instrument associated with a certain component can be controlled via its <link linkend="chpt.mixer.component_strips">Component Channel Strip</link> in the Mixer.
                  </para>
                </tip>
              </para>
            </listitem>
            <listitem id="chpt.instrument_editor.layers.controls.pitch">
	          <para>
	            <emphasis role="bold">Pitch</emphasis>:
                adjusts the pitch of the currently selected layer and the associated sample in quantized steps of half-tones from <option>-24</option> to <option>+24</option>.
              </para>
            </listitem>
            <listitem>
	          <para>
	            <emphasis role="bold">Fine</emphasis>:
                adjusts the pitch of the currently selected layer and the associated sample in quantized steps of cents of half-tones from <option>-0.50</option> to <option>+0.50</option>.
              </para>
            </listitem>
          </itemizedlist>
        </sect2>
        
      </sect1>
      
    </chapter>

    
      <chapter id="chpt.sample_editor">
        <title>Sample Editor</title>
        
        <figure id="sample.editor">
          <title>The Sample Editor</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="generated_en/SampleEditor_V5.png" format="PNG" />
            </imageobject>
          </mediaobject>
        </figure>

        <para>The Sample Editor allows you to tweak and manipulate your
        samples. It can be accessed by selecting a layer in the <link linkend="chpt.instrument_editor.layers">Instrument Editor</link> and clicking the
        <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "EDIT LAYER".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/editLayer_off.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
           button. It will really speed up the creation of a drumkit since
        you can do the fine-tuning of the <link linkend="def.sample">samples</link> within Hydrogen and avoid a lengthy import-test-tweak workflow using an external application. This mean less switching between Hydrogen and your audio editor
        and more time to make music!</para>
        
        <note>
        <para>The changes you make to
        your samples in the Sample Editor are <emphasis role="bold">non-destructive
        </emphasis> and are saved <emphasis role="bold">per song</emphasis>.  
        So, the original sample will not be changed,
        and you can reuse the same sample in multiple songs with different Sample Editor
        settings.</para>
        </note>
        
       
        <sect1 id="chpt.sample_editor.wave_display">
          <title>Wave Display and Region Editing</title>

          <figure id="fig.sample_editor.wave_display">
            <title>The Wave Display Section of the Sample Editor</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/SampleEditor_Wave.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>
          
          <para>
            In the <emphasis role="bold">larger (left) wave display</emphasis> you can see the wave form of the sample you are about to edit. In there you can set the start, stop, and loop point for the sample by <emphasis>dragging</emphasis> the 
            the 3 markers:
            <itemizedlist>
              <listitem id="chpt.sample_editor.wave_display.start_marker">
                <para><emphasis role="bold">Start Marker (green)</emphasis>: labeled with a <option>S</option> and indicates the beginning of the tweaked sample.</para>
              </listitem>
              <listitem id="chpt.sample_editor.wave_display.end_marker">
                <para><emphasis role="bold">End Marker (red)</emphasis>: labeled with a <option>E</option> and indicates the end of the tweaked sample.</para>
              </listitem>
              <listitem id="chpt.sample_editor.wave_display.loop_marker">
                <para><emphasis role="bold">Loop Marker (blue)</emphasis>: labeled with a <option>L</option> and determines the loop-in point of your sample.</para>
              </listitem>
            </itemizedlist>
          </para>
          
          <tip>
	        <para>
              You can easily move one of the markers by grabbing them close to the letter that marks them.
            </para>
          </tip>

          <para>
            Underneath you can find a numerical display of the position set for the individual markers as well as some further options. The position of the markers is expressed in number of
            frames from the very beginning of the sample.
          </para>
          
          <itemizedlist>
	        <listitem>
	          <para>
	            <emphasis role="bold">Start</emphasis>: position of the <link linkend="chpt.sample_editor.wave_display.start_marker">Start Marker</link>.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Loop</emphasis>: position of the <link linkend="chpt.sample_editor.wave_display.loop_marker">Loop Marker</link>.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Loop Mode</emphasis>:
                specifies the way the individual loops will be played back.
                <itemizedlist>
	              <listitem>
	                <para>
	                  <option>forward</option>: plays the <emphasis>Loop Count</emphasis> loop passages the usual way from left to right.
                    </para>
                  </listitem>
                  <listitem>
	                <para>
	                  <option>reverse</option>: plays the <emphasis>Loop Count</emphasis> loop passages the backwards (from right to left).
                    </para>
                  </listitem>
                  <listitem>
	                <para>
	                  <option>ping-pong</option>: plays the <emphasis>Loop Count</emphasis> loop passages alternatively backwards and forwards (starting with backwards).
                    </para>
                  </listitem>
                </itemizedlist>
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Loop Count</emphasis>: indicates the number of times the sample will be repeated between Loop and the End Marker. This section will therefore be played back <emphasis>Loop Count + 1</emphasis> times.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">End</emphasis>: position of the <link linkend="chpt.sample_editor.wave_display.end_marker">End Marker</link>.
              </para>
            </listitem>
	        <listitem>
	          <para>
	            <emphasis role="bold">Close</emphasis>: exits the Sample Editor.
              </para>
            </listitem>
          </itemizedlist>

          <note>
	        <para>
	          These values will change if you <emphasis>drag</emphasis> the markers,
          but you can also fine-tune the marker position by using the up/down arrows of the spinboxes, 
          the up/down keys on your keyboard, or by using your mouse scroll wheel while hovering
          above the spinboxes.
            </para>
          </note>
          
          <para>
            Whenever you move one of the markers you will see a detail
            view of the position of that marker on the <emphasis role="bold">smaller (right) wave display</emphasis> on the right, making it easy to 
            find the zero-crossings in the sample.  This detail window also has a <emphasis role="bold">slider</emphasis> next to
            it that allows you to zoom in and out on the vertical axis. Think of it as a sort of 
            volume 'zoom'.
          </para>

          <tip>
	        <para>
	          If you want to hear a preview of the tweaking you have done so far, you first need to
          press the <link linkend="chpt.sample_editor.playback_and_envelope_editor.apply_changes">Apply Changes</link> and then the <link linkend="chpt.sample_editor.playback_and_envelope_editor.play">Play</link> button (both at the bottom of the window) to
          hear the result.
            </para>
          </tip>
          
        </sect1>
        
        <sect1 id="chpt.sample_editor.pitch">
        <title>Pitch Shifting</title>

        <figure id="fig.sample_editor.pitch_shift">
          <title>The Pitch Shifting Section of the Playlist Editor</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/SampleEditor_PitchShift.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>This section of the Sample Editor allows you to use <emphasis role="bold">Rubber Band</emphasis> - a tool that can change the tempo of a sample without changing the sample's pitch (and vice versa) - to tweak your sample.</para>

          <note>
            <para>
              These options are only available if Rubber Band support was either compiled into Hydrogen or was properly configures in the <link linkend="chpt.preferences.general_tab">General</link> tab of the Preferences.
  After installing Rubber Band you should check if the path to the <command>rubberband cli</command> is 
  configured correctly (see <xref linkend="chpt.preferences.general_tab"/>). If neither is the case, all associated widgets will be disabled.
            </para>
	        <para>
	          When <emphasis role="bold">Sample length to beat</emphasis> is set to <option>off</option> the whole Rubber Band functionality will be disabled.
              </para>
            </note>
          
          <itemizedlist mark="opencircle">
            <listitem><para><emphasis role="bold">Sample length to beat</emphasis>:
            specifies the length of the resulting sample (after Rubber Band was applied to it). After choosing a value other than <option>off</option> the length ratio between the original and the resulting sample will be displayed to the right of the combo box under <emphasis role="bold">new sample length</emphasis>. To ease the process of finding a proper value, the checkbox will be highlighted <emphasis>green</emphasis> if the length is more or less the same, <emphasis>yellow</emphasis> if there are larger changes, and <emphasis>red</emphasis> if there are significant changes.

            <tip>
	          <para>
	            This should be set to the length of the part of the sample between 
                the Start and End marker, expressed in number of beats.
              </para>
            </tip>

            <note>
	          <para>
	            The beat length does dependent on the current tempo of the song. If it is changed, the samples need to be recalculated using Rubber Band again. When <link linkend="sect.main_form.export_song">exporting a song</link> all required recalculations will be done automatically. But while using standard playback the 
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey vertical button containing the characters "R", "U", and "B"
              in adjacent lines.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/playerControlRubberbandButton.png" format="PNG" />
              </imageobject>
            </inlinemediaobject>
          button in the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Main Toolbar</link> has to be activated to enable the recalculation of all samples on the fly.
              </para>
            </note>
            
          </para>
            </listitem>
            <listitem><para><emphasis role="bold">Pitch</emphasis>:
            specifies the resulting pitch of the sample, expressed in 
            <option>semitones,cent</option>.

            <note>
	          <para>
	            This pitch will affect all instances of the sample in addition to the <link linkend="chpt.instrument_editor.pitch_shift_parameters">Pitch Shift Parameters</link> in the Instrument Editor and the <link linkend="chpt.pattern_editor.note_properties.notekey">NoteKey</link> property of each individual note.
              </para>
            </note>
          </para>
            </listitem>
            <listitem><para><emphasis role="bold">Crispness</emphasis>:
            fine-tunes the processing algorithm used by Rubber Band. It does not affect tempo or pitch, but changes the way
            the sample sounds.
          </para>
            </listitem>
          </itemizedlist>
        </sect1>
        
        <sect1 id="chpt.sample_editor.playback_and_envelope_editor">
          <title>Playback and Envelope Editor</title>

          <figure id="fig.sample_editor.envelope">
            <title>The Envelope Section of the Sample Editor</title>
            <mediaobject>
              <imageobject>
                <imagedata fileref="generated_en/SampleEditor_Envelope.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </figure>

          <para>
	        The bottom part of the Sample Editor features some basic controls and the Envelope Editor.
          </para>

          <itemizedlist>
	        <listitem id="chpt.sample_editor.playback_and_envelope_editor.apply_changes">
              <para>
	            <emphasis role="bold">Apply Changes</emphasis>: applies all settings of the Sample Editor to the selected sample in a non-destructive way.
              </para>
            </listitem>
	        <listitem id="chpt.sample_editor.playback_and_envelope_editor.play">
              <para>
	            <emphasis role="bold">Play</emphasis>: plays back the underlying sample with the latest changes applied to it.
              </para>
            </listitem>
	        <listitem>
              <para>
	            <emphasis role="bold">Play original sample</emphasis>:  plays back the underlying sample (without applying any changes).
              </para>
            </listitem>
	        <listitem id="chpt.sample_editor.playback_and_envelope_editor.dropdown">
              <para>
	            <emphasis role="bold">panorama/volume</emphasis>: dropdown specifying whether the <option><link linkend="def.pan">pan(orama)</link></option> or <option>volume</option> of the sample will be tweaked in the Envelope Editor.
              </para>
            </listitem>
          </itemizedlist>
          
          <para>Using the Envelope Editor you can fine-tune both the volume and panorama (pan) of your sample.
          This is done by creating <link linkend="def.envelopegenerator">envelopes</link> by
          </para>
          
          <note>
	        <para>
	          The volume envelope is blue and the pan envelope is yellow.
            </para>
          </note>

          <procedure id="chpt.sample_editor.playback_and_envelope_editor.envelope">
            <step>
              <para>
                First select <option>volume</option> or <option>panorama</option> in the <link linkend="chpt.sample_editor.playback_and_envelope_editor.dropdown">dropdown</link> to the right.
              </para>
            </step>
            <step>
              <para>
	            <emphasis>Left-clicking</emphasis> in the Envelope Editor will add a point to the selected envelope or allows you to <emphasis>drag</emphasis> an existing one.
              </para>
            </step>
            <step>
              <para>
	          <emphasis>Right-clicking</emphasis> will delete a point.   
              </para>
            </step>
            <step>
              <para>
	            Hit <link linkend="chpt.sample_editor.playback_and_envelope_editor.apply_changes">Apply Changes</link> to make your changes take effect.
              </para>
            </step>
          </procedure>

        </sect1>
        
      </chapter>

    <chapter id="chpt.mixer" xreflabel="Mixer">
      <title>Mixer</title>

      <figure id="fig.mixer">
        <title>The Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/Mixer.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>The Mixer window can be opened by pressing <keycap>Alt</keycap> + <keycap>M</keycap>, by selecting Mixer in the <link linkend="sect.main_menu.view">View</link> option of the Main Menu, or by clicking the Mixer button on the <link linkend="sect.main_toolbar.gui_state">Main Toolbar</link>.
      </para>
      <para>The Mixer consists of 3 sections (from left to right): the one containing the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link> and <link linkend="chpt.mixer.component_strips">Component Channel Strips</link>, 
      the <link linkend="sect.fx_rack_LADSPA">FX Plugin Rack</link>, and the <link linkend="chpt.mixer.master_fader_strip">Master Fader Strip</link>. The Hydrogen Mixer works very
       much like a hardware mixer does: it lets you set the volume, pan, FX and several 
       other things for every instrument as well as the volume of all of these sources mixed together.
      </para>

    <sect1 id="chpt.mixer.channel_strips" xreflabel="Instrument Channel Strips">
      <title>Instrument Channel Strips</title>

      <figure id="fig.mixer.channel_strip">
        <title>The Instrument Channel Strip in the Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/mixerLineStrip.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <itemizedlist>
	    <listitem>
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button with a filled black triangle pointing to the right.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_play_on_mixer.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : lets you trigger the instrument at maximum velocity.
          </para>
          <tip>
	        <para>
	          This is quite handy for checking <link linkend="def.clipping">clipping</link>.
            </para>
          </tip>
          <para>
            Right-clicking the button will stop all currently playing notes of the associated instrument.
          </para>
          <tip>
            <para>
              This is especially useful when dealing with long samples and <link linkend="chpt.instrument_editor.gain_and_mute_group">Auto-Stop Note</link> is disabled.
            </para>
          </tip>
        </listitem>
	    <listitem>
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Vertical, grey LED-like object.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/led_trigger_on.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> :
              lights up whenever this instrument is triggered (e.g. by a note in a pattern).
          </para>
        </listitem>
	    <listitem>
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Horizontal, blue LED-like object.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/item_selected.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> :
              shows whether the instrument is currently selected (in both the Mixer and the Pattern Editor).

              <note>
	            <para>
	              If the <link linkend="chpt.midi.note.input_mode">Input Mode</link> is set to <option>Instrument</option>, incoming <abbrev>MIDI</abbrev> events and <link linkend="chpt.overview.virtual_keyboard">Virtual Keyboard keys</link> will trigger only (pitch shifted) sounds of the currently selected instrument.
                </para>
              </note>

              <tip>
	            <para>
	              An instrument can be selected by interacting with its Instrument Channel Strip in the Mixer, by interacting with its associated row in the Pattern Editor, or by the corresponding <link linkend="chpt.midi.controlling.actions.select_instrument"><abbrev>MIDI</abbrev></link> or <link linkend="chpt.osc.command.select_instrument"><abbrev>OSC</abbrev> command.</link>
                </para>
              </tip>
          </para>
        </listitem>
	    <listitem id="chpt.mixer.channel_strips.mute">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "M".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_mute_on.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : <link linkend="def.mute">mutes</link> all sounds related to the instrument (including the preview sound you hear when clicking on the instrument name in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link> of the Pattern Editor).
          </para>
          <note>
	        <para>
	          This button is sharing its state with the mute button of corresponding instrument in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link> of the Pattern Editor.
            </para>
          </note>
        </listitem>
	    <listitem id="chpt.mixer.channel_strips.solo">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "S".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_solo_on.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : solos the instrument.
          </para>
          <note>
	        <para>
	          This button is sharing its state with the solo button of corresponding instrument in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link> of the Pattern Editor.
            </para>
          </note>
        </listitem>
	    <listitem id="chpt.mixer.channel_strips.pan">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey rotary widget with black background. On the widget there is a
              centered black circle and a black vertical line extending from the
              topmost point of the circle to its center.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/mixer_rotary.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : sets a pan value affecting all notes played using this instrument.
          </para>
          <tip>
	        <para>
	          For a detailed description of how this pan value does interact with the <link linkend="chpt.pattern_editor.note_properties.pan">note pan</link> and the <link linkend="chpt.mixer.master_fader_strip.mixer_settings">Pan Laws</link> in the Mixer please see <xref linkend="def.pan" />.
            </para>
          </tip>
        </listitem>
	    <listitem id="chpt.mixer.channel_strips.fx_volume">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey and round widget containing a grey and centered circle as
              well as a short grey line to indicate the position.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/mixer_knob.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> :
              the four pre-fader FX send knobs that determine how much of this instrument will be sent to
      the effect plugins in the <link linkend="sect.fx_rack_LADSPA">FX Rack</link>.
          </para>
        </listitem>
	    <listitem id="chpt.mixer.channel_strips.fader_and_lcd">
	      <para>
            <emphasis role="bold">Fader</emphasis>:
              the fader next to the instrument's name allows you to adjust the volume of the instrument which will be applied on top of all the individual note velocities, layer gains etc. In the background of the fader a volume unit (VU) meter is included representing the instrument's signal level. The display above shows its peak value.
          </para>
          <tip>
	        <para>
	          You can adjust the falloff speed of the peak values in the display in the <link linkend="fig.preferences.appearance_tab.interface">Interface</link> tab of the Appearance tab in the Preferences.
            </para>
          </tip>
        </listitem>
      </itemizedlist>
      
       <note>
         <para>
           If the <link linkend="sect.preferences.jack.per_instrument_outs">Create per-instrument outputs</link> option in the Audio Engine tab of the Preferences was selected for the <abbrev>JACK</abbrev> audio driver, Hydrogen will register ports for each instrument. All the options described above will only take effect if in addition the <link linkend="sect.preferences.jack.track_output">Track output</link> option in the same tab as set to <option>Post-Fader</option>.
         </para>
         <para>
           This allows you to route the individual instruments directly into any other <abbrev>JACK</abbrev> enabled application, like Ardour, and gives you
           a lot more flexibility.
         </para>
       </note>

    </sect1>


    <sect1 id="chpt.mixer.component_strips">
      <title>Component Channel Strips</title>

      <figure id="fig.mixer.component_strip">
        <title>The Component Channel Strip in the Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/componentMixerLineStrip.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
      Right of the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link> there additional strips corresponding to the instrument <link linkend="def.component">components</link>.
      </para>
      
      <note>
	    <para>
	      These channels will not be exposed as <abbrev>JACK</abbrev> output ports when enabling the <link linkend="sect.preferences.jack.per_instrument_outs">Create per-instrument outputs</link> option in the Preferences.
        </para>
      </note>

      <itemizedlist>
	    <listitem id="chpt.mixer.component_strips.mute">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "M".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_mute_on.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : <link linkend="def.mute">mutes</link> the instrument.
          </para>
        </listitem>
	    <listitem id="chpt.mixer.component_strips.solo">
	      <para>
            <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing a black "S".
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/btn_solo_on.png" format="PNG" />
              </imageobject>
              </inlinemediaobject> : solos the instrument.
          </para>
        </listitem>
	    <listitem id="chpt.mixer.component_strips.fader_and_lcd">
	      <para>
            <emphasis role="bold">Fader</emphasis>:
              the fader next to the component's name allows you to adjust the volume of all layers (of all instruments) associated with this component. In the background of the fader a volume unit (VU) meter is included representing the instrument's signal level. The displays shows its peak value.
          </para>
          <tip>
	        <para>
	          You can adjust the falloff speed of the peak values in the display in the <link linkend="fig.preferences.appearance_tab.interface">Interface</link> tab of the Appearance tab in the Preferences.
            </para>
          </tip>
        </listitem>
      </itemizedlist>
    </sect1>
    
    <sect1 id="sect.fx_rack_LADSPA">
      <title>FX Rack and LADSPA Plugins</title>
      
      <figure id="fig.mixer.fx_strip">
        <title>The FX Rack in the Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/mixerFXRack.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

      <para>
      The FX Rack can be accessed by clicking the

      <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing the black characters "FX".
            </phrase>
          </textobject>
        <imageobject>
          <imagedata fileref="generated_en/mixerShowFXButton.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>

      button in the <link linkend="chpt.mixer.master_fader_strip">Master Fader Strip</link>.
      </para>
      <para>It has 4 slots where you can load a <abbrev>LADSPA</abbrev> effect plugin already installed on your system.</para>
        <para>There are dozens of plugins available for download from various sources:

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold"><abbrev>SWH</abbrev>-Plugins</emphasis>: available at <ulink
          url="http://plugin.org.uk">http://plugin.org.uk</ulink>. </para>
        </listitem>

        <listitem>
          <para><emphasis role="bold"><abbrev>CMT</abbrev></emphasis>: available at <ulink url="http://www.ladspa.org">http://www.ladspa.org</ulink>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold"><abbrev>TAP</abbrev></emphasis>: available at <ulink url="http://tap-plugins.sf.net">http://tap-plugins.sf.net</ulink>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold">Calf plugins</emphasis>: available at <ulink url="http://calf.sourceforge.net/">http://calf.sourceforge.net/</ulink>.</para>
        </listitem>

        <listitem>
          <para><emphasis role="bold"><abbrev>LSP</abbrev> plugins</emphasis>: available at <ulink url="https://github.com/sadko4u/lsp-plugins/">https://github.com/sadko4u/lsp-plugins/</ulink>.</para>
        </listitem>

        <listitem>
          <para> ....</para>
        </listitem>

      </itemizedlist>
        </para>

        <note>
          <para>
            Linux Audio Developer's Simple Plugin API (<abbrev>LADSPA</abbrev>) is the only plugin format supported by Hydrogen and it is tailored to be used on Linux platforms. On <emphasis role="bold">macOS</emphasis> it's rather easy to get the plugins running as most of their code works on this platform too without any changes. On <emphasis role="bold">Windows</emphasis>, however, things are not that straight forward. As of 2022 there are no packages, bundles, or other applications shipping LADSPA plugins for Windows usable within Hydrogen and you have to compile them from source too. But in contrast to Linux and macOS your have to adopt the codebase first (which is most easily done for the <abbrev>CMT</abbrev> plugins). So, it's possible to use plugins under Windows but, unfortunately, not feasible at all.
          </para>
        </note>

      <para>You can select a plugin using the FX selector opened by clicking the
      

      <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "EDIT".
            </phrase>
          </textobject>
        <imageobject>
          <imagedata fileref="generated_en/mixerFXEditButton.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>

      button.
      
      <figure id="fig.select_effect">
        <title>Select an Effect</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="MixerFXSelect.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
      
      Once you have selected a plugin you will immediately have access 
      to its parameters.
      
       
        <informalfigure id="figLADSPA_FX_Properties">
         <mediaobject>
          <textobject>
            <phrase>
              Example widget to alter the properties of a LADSPA FX. At the top
              left the name of the FX is displayed and at the top left two
              buttons - "Select FX" and "Deactivate" - are shown. In the remainder
              there are several vertical strips stacked horizontally with each
              one carrying: an display showing the current value (top), the name
              of the parameter (left), and a fader with included meter (right).
            </phrase>
          </textobject>
           <imageobject>
             <imagedata fileref="LADSPA_FX_Properties.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>
      
      <warning>
        <title>Plugins Kill</title>
        <para>A badly designed <abbrev>LADSPA</abbrev> plugin is capable of
        hanging, crashing, freezing, screeching, overflowing buffers, and even
        phoning home.  If you start having issues with Hydrogen, disable your
        plugins and see if things improve.  Some plugins are not designed for
        real-time use and some are just plain better than others.</para>
      </warning>


      You can select another plugin by clicking the <emphasis role="bold">Select FX</emphasis> button. If you quickly want to 
      enable/disable the effect click the <emphasis role="bold">Deactivate</emphasis> button (or the Bypass 

      <inlinemediaobject>
          <textobject>
            <phrase>
              Redish button containing the black characters "BYP".
            </phrase>
          </textobject>
        <imageobject>
          <imagedata fileref="generated_en/mixerFXBypassButton.png" format="PNG" />
        </imageobject>
        </inlinemediaobject>

        button in the FX Rack).
      <tip>
	    <para>
	      This can be handy for a quick A/B comparison.
        </para>
      </tip></para>
      
      <para>After you have selected the FX and tweaked it's parameters you can use the 
      <emphasis role="bold">Return</emphasis> knob in the FX Rack of the mixer to increase/decrease how much of this FX will be added to the master output.
      </para>

      <para>
        The FX itself lives in an <emphasis>aux</emphasis> channel. This means it's not directly added into the signal path of any instrument line but a copy of the audio output of each of them is sent to the FX for processing instead. The amount of signal - 0 per default - send by each can be controlled using the <link linkend="chpt.mixer.channel_strips.fx_volume">pre-fader FX knobs</link> in the corresponding instrument channel strip. The top left one refers to the top-most FX, the top right one to the second FX and so on. This means, in order to get an all wet signal (none of the original signal but just the processed one enters the mix) of an instrument, you have to ramp up the pre-fader FX knob and set the line's fader to 0.
      </para>

      <note>
        <para>
          Since the FX signal lives in an aux channel it is neither affected by <link linkend="chpt.instrument_editor.gain_and_mute_group">Auto-Stop-Note</link> nor <link linkend="chpt.instrument_editor.gain_and_mute_group">Mute Groups</link>.
        </para>
      </note>

    </sect1>
     
    <sect1 id="chpt.mixer.master_fader_strip">
      <title>Master Fader Strip</title>

      <figure id="fig.mixer.master_strip">
        <title>The Master Fader Strip in the Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="generated_en/masterMixerLine.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>

       <para>
       
         The Master Fader Strip contains the Master volume fader with volume unit (VU) meter representing the signal level, and three global humanization settings.
       </para>

       <para>
	     Using the fader you can control the volume of the resulting audio output of Hydrogen which is the sum of all the individual <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link>, the <link linkend="chpt.song_editor.playbackTrack">Playback Track</link>, and the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link>. The
         <inlinemediaobject>
          <textobject>
            <phrase>
              Grey button containing the black characters "MUTE".
            </phrase>
          </textobject>
            <imageobject>
              <imagedata fileref="generated_en/mixerMasterMuteButton.png" format="PNG" />
            </imageobject>
          </inlinemediaobject>
          button <link linkend="def.mute">mutes</link> the whole output.
       </para>

        <para>On the bottom-right of the Master section the
        <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing the black characters "FX".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/mixerShowFXButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>      
        button will show or hide the <link linkend="sect.fx_rack_LADSPA">FX Rack</link>, and the
        
        <inlinemediaobject>
          <textobject>
            <phrase>
              Blue button containing the black characters "PEAK".
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/mixerShowPeaksButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>       
        button will enable or disable the VU meters in both the Master Fader Strip and all the individual <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link> and <link linkend="chpt.mixer.component_strips">Component Channel Strips</link>.

        </para>

      <sect2 id="chpt.mixer.master_fader_strip.humanization">
        <title>Humanization</title>

        <para>
	      In order to make the resulting audio sound more natural and less artificial, Hydrogen does offer some humanization capabilities.
        </para>

        <tip>
	    <para>
	        Further humanization capabilities are provided via <link linkend="chpt.instrument_editor.pitch_shift_parameters">Random Pitch Shift Parameter</link> in the Instrument Editor. In contrast to the global nature of the humanization in the Master Fader Strip this random pitch will only be applied to notes associated with the corresponding instrument.
        </para>
        </tip>
        
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Velocity</emphasis>: adds a certain randomness to the note <link linkend="def.velocity">velocity</link> set in the <link linkend="chpt.pattern_editor.note_properties.velocity">Note Properties Editor</link>. 
            The higher you turn this knob, the bigger will be the randomness.
            </para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Timing</emphasis>: adds a certain randomness to the note timing set in the <link linkend="chpt.pattern_editor.note_properties.lead_and_lag">Note Properties Editor</link> (as Lead/Lag).
            The higher you turn this knob, the more the timing will be randomized.
            </para>
            <note><para>Notes are displaced in time
            but the pattern duration or BPM do not change.</para>
            </note>
            
          </listitem>
          
          <listitem>
            <para><emphasis role="bold">Swing</emphasis>: this knob will add a certain amount of swing to the song. Swing (a slight time delay) is applied to upbeat 16th-notes,
            and not to 8th-notes as it happens in traditional Jazz.</para>
            <para>This means for instance when setting the <link linkend="chpt.pattern_editor.controls.res">resolution</link> of a pattern to <option>1/16</option> every second note will be affected. If set to <option>1/32</option> instead, every third out of four consecutive notes will be affected. For smaller resolution the swing won't have any effect.</para>

            <note>
              <para>Please also notice that the amount of lag depends on the current speed as well. The slower the song, the larger is the offset introduced (it scales with 1/tempo).
              </para>
            </note>

          </listitem>
          
        </itemizedlist>

        <note>
	      <para>
	        In technical terms both for the <emphasis role="bold">Velocity</emphasis> and the <emphasis role="bold">Timing</emphasis> a random number will be sampled independently and identically distributed from a Gaussian distribution. The associated knobs provide a linear scaling of the variance of the underlying distribution.
          </para>
        </note>
        
      </sect2>

      <sect2 id="chpt.mixer.master_fader_strip.mixer_settings">
        <title>Mixer Settings</title>
        
        <para>Clicking the

        <inlinemediaobject id="mixerSettingsButton">
          <textobject>
            <phrase>
              Button holding the cog symbol right of the "Master" title of the
              Master Fader Strip.
            </phrase>
          </textobject>
          <imageobject>
            <imagedata fileref="generated_en/mixerSettingsButton.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

          button in the upper right corner of Master Fader Strip opens the Mixer Settings window:

          <informalfigure id="mixerSettingsDialog">
            <mediaobject>
          <textobject>
            <phrase>
              Dialog to "Select Pan Law" with a large dropdown menu in the
              middle, a text input title "db SPL Center Componensation" below,
              and the "Cancel" (left) and "OK" (right) buttons at the bottom.
            </phrase>
          </textobject>
              <imageobject>
                <imagedata fileref="generated_en/mixerSettingsDialog.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>
          Here you can select the <emphasis role="bold">Pan Law</emphasis> used by Hydrogen Mixer.
        </para>
        <para>
          The Pan Law is the relationship between the <link linkend="def.pan">Resultant Pan</link> and the separate <link linkend="def.gain">gains</link> of left and right audio outputs.
          The aim is to control the horizontal angle the sound seems to arrive from.
        </para>
        <para>
        Hydrogen features one the most customizable and accurate Pan Law set. </para>
        
        <para>
          You will find four categories: <option>linear</option>, <option>polar</option>,
          <option>ratio</option>, <option>quadratic</option>.
          Every category gives a different "scale" or "sensibility" to the pan knob:
          the same knob position will make the sound appear more lateral or central depending on the category,
          from the most lateral (<emphasis>linear</emphasis>) to the most central (<emphasis>quadratic</emphasis>).
        </para>
        
        <para>
          Then for each category you will find four options, that define a <emphasis>constraint</emphasis> between the
          gains of the two channels:     
          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">Balance Law (0dB)</emphasis>: 
              when you turn the pan knob from center to right, the right gain stays constant at maximum level
              while the left gain decreases from the maximum level to 0 (and symmetrically turning from center to left). </para>
              <para>It is ideal for balancing a DUAL-channel track. It has ZERO center compensation: the sound 
              will be <emphasis>louder</emphasis> when the pan knob is at <emphasis>center</emphasis> -
              unless channels are out of phase - so you may have to readjust the volume manually with the
              mixer fader.
              </para>
            </listitem>
            
            <listitem>
              <para> <emphasis role="bold">Constant Power (-3dB)</emphasis>: the total <emphasis>power</emphasis>
              (which is proportional to the <emphasis>square</emphasis> of the gain) is constant for any position
              of the pan knob. </para>
              <para>Compared to the Balance Law, each channel gain is divided by the square root of 2
              when the pan knob is at center (-3.0103 dB center compensation).
              In a common room, this constraint <emphasis>may</emphasis> give the general perception of uniform
              volume for any pan knob position (panning a MONO track).
              </para>
            </listitem>
            
            <listitem>
              <para> <emphasis role="bold">Constant Sum (-6dB)</emphasis>: the sum of left and right gains is
              constant for any position of the pan knob. </para>
              <para>This constraint preserves the mix volumes in mono export.
              Compared to the Balance Law, each channel gain is halved (-6.0206 dB) when the pan knob
              is at center.
              If you are in an ideal anechoic room (where there are no acoustic reflections)
              and you seat perfectly at the same distance from the speakers,
              with this constraint the volume will be really constant for any pan position, because of the linear
              <emphasis>super-position</emphasis> of sound waves (panning a MONO track).
              </para>
            </listitem>

            <listitem>
              <para><emphasis role="bold">Constant k-Norm (Custom dB center compensation)</emphasis>:
              you can experiment adjusting the center compensation to your
              taste! </para>
              <tip>
                <para>Some hi-end studio mixers - to be used in well tuned rooms -
                have center compensation between -3dB and -6dB.
                </para>
              </tip>
            </listitem>
          </itemizedlist>
        </para>

        <para>The four constraints should not change the perception of the <emphasis>stereo angle</emphasis>,
        but the <emphasis>volume</emphasis> only (depending on the pan knob).
        </para>
        <para>
          The Pan Law is something you should choose <emphasis>before</emphasis> starting the mix and keep untouched.
          Hydrogen sets the <emphasis>ratio Balance Law</emphasis> by default because it was the only available law
          until version 1.0 (so old songs and drumkits will sound the same).
          The setting is saved in the song file but not in preferences, 
          so it is NOT remembered when you create a new song.
        </para>
        <note>
          <para>Unlike in advanced mixers, Hydrogen panning makes no distinction if a track is mono or dual-channel (stereo).
          You cannot pan each channel of stereo tracks separately, nor use a balance law for them and another
          pan law for mono tracks.
          If the drumkit you are using is made of true stereo samples, you don't want a negative center compensation
          probably, so you should select a Balance Law.</para>
        </note>
      </sect2>

    </sect1>
    
  </chapter>

    
   <chapter id="chpt.director" xreflabel="Director">
     <title>Director</title>

     <para>
       <figure id="fig.director">
         <title>The Director</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/screenshot-director.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>
     </para>
     
     <para>
       The Director provides a quick overview of what Hydrogen
       is currently doing. It can be opened by pressing <keycap>Alt</keycap> + <keycap>D</keycap> or by via the <link linkend="sect.main_menu.view">View</link> option in the Main Menu. </para>
     
     <para>
       The Director shows you the song name, a visualization of the <link linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link>, and the
       <link linkend="chpt.song_editor.tag">Tags</link>. Just below the metronome you can see the latest tag, and below that
       the next upcoming tag. This way you have a nice overview of what is going on,
       and what is about to happen in the song.
     </para>

     <tip>
	   <para>
	     This comes in very handy when you are <link linkend="chpt.overview.recording">recording</link> a song, or
         if you are using Hydrogen live on stage.
       </para>
     </tip>
     
   </chapter>

   <chapter id="chpt.playlist_editor">
     <title>Playlist Editor</title>
         
     <figure id="fig.playlist_editor">
       <title>The Playlist Editor with Demo Songs loaded</title>
       <mediaobject>
         <imageobject>
           <imagedata fileref="PlaylistEditor.png" format="PNG"/>
         </imageobject>
       </mediaobject>
     </figure>

      <sect1 id="chpt.playlist_editor.main_window">
	   <title>Main Window</title>

       <sect2 id="chpt.playlist_editor.main_window.song_list">
	     <title>Song List</title>

         <para>
	       The Playlist Editor allows you to group various songs into a
           playlist and is intended to ease using Hydrogen live on stage. You can access this window via the <link linkend="sect.main_menu.view">View</link> option of the Main Menu.
         </para>

         <para>
	       Using the <link linkend="chpt.playlist_editor.menu">menu</link> you can add various songs to the playlist and you can arrange their order using the arrow buttons to the right of the widget.
         </para>

         <note>
	       <para>
	         When playback reaches the end of one song the next one won't be automatically selected and played! You can select an arbitrary song in the playlist using double <emphasis>left-clicking</emphasis>, by pressing the hotkeys <link linkend="chap.shortcuts.f5"><keycap>F5</keycap></link> and <link linkend="chap.shortcuts.f6"><keycap>F6</keycap></link>, or the corresponding <link linkend="chpt.osc.command.playlist_song">OSC</link> commands.
           </para>
           <para>
	         Also note that selecting a song won't start playback automatically.
           </para>
         </note>

       </sect2>

       <sect2 id="chpt.playlist_editor.main_window.controls">
	     <title>Controls</title>

         <informalfigure id="fig.playlist_editor.controls">
           <mediaobject>
          <textobject>
            <phrase>
              From left to right: rewind, play and pause, stop, and fast forward.
            </phrase>
          </textobject>
             <imageobject>
               <imagedata fileref="PlaylistEditorControls.png" format="PNG"/>
             </imageobject>
           </mediaobject>
         </informalfigure>

         <para>
	       At the bottom of the widget you find a couple of <emphasis role="bold">buttons</emphasis> you already know from the <link linkend="sect.main_toolbar.transport_control">Transport Control</link> in the Main Toolbar. They do have the same purposes of starting, pausing, and stopping the playback as well as moving the transport position backwards or forwards by one pattern.
         </para>

         <note>
	       <para>
	         While focusing the Playlist Editor instead of the main UI the usual <link linkend="chap.shortcuts">shortcuts</link> of Hydrogen, like <link linkend="chap.shortcuts.space"><keycap>Space</keycap></link> for starting/pausing playback, won't work.
           </para>
         </note>

       </sect2>

       <sect2 id="chpt.playlist_editor.main_window.scripts">
	     <title>Scripts</title>

         <para>
	       In addition, the Playlist Editor allows you to add <emphasis role="bold">scripts</emphasis> executed right <emphasis>before</emphasis> the
           selected song is loaded.
           
           <note>
	         <para>
	           This means that e.g. <link linkend="chpt.osc.commands.all_messages">OSC</link> commands can not be used to change the state of Hydrogen as the subsequent loading of the associated song would reset it immediately.
             </para>
           </note>

           The scripts supported in the Playlist Editor are <abbrev>BASH</abbrev> scripts and one has to both add a script to a song as well as to check the corresponding box in the <emphasis>exec Script</emphasis> column in order to have it by your computer whenever you switch to the particular song.
         </para>

         <warning>
	       <para>
	         Scripts are not supported in the Windows version of Hydrogen.
           </para>
         </warning>
       </sect2>         
     </sect1>
         
     <sect1 id="chpt.playlist_editor.menu">
	   <title>Menu</title>

       <sect2 id="chpt.playlist_editor.menu.playlist">
	     <title>Playlist</title>
         
         <itemizedlist>
	       <listitem>
	         <para>
	           <emphasis role="bold">Add song to Playlist</emphasis>:
               let's you select a song to be added to the current playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Add current song to Playlist</emphasis>:
               adds the currently loaded song to the current playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Remove selected song from Playlist</emphasis>:
               deletes the selected song from the current playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">New Playlist</emphasis>:
               creates a new and empty playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Open Playlist</emphasis>:
               opens an existing playlist (file of type <link linkend="chpt.file_types.h2playlist">.h2playlist</link>).

               <tip>
	             <para>
	               In the <link linkend="fig.preferences.general_tab">General</link> tab of the Preferences dialog you can configure Hydrogen to reload the last used playlist.
                 </para>
               </tip>
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Save Playlist</emphasis>:
               saves all changes done to the current playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Save Playlist as</emphasis>:
               saves the current playlist into a file (of type <link linkend="chpt.file_types.h2playlist">.h2playlist</link>) and location of your choice.
             </para>
           </listitem>
         </itemizedlist>
       </sect2>

       <sect2 id="chpt.playlist_editor.menu.scripts">
	     <title>Scripts</title>

         <itemizedlist>
	       <listitem>
	         <para>
	           <emphasis role="bold">Add Script to selected song</emphasis>:
               associates a <abbrev>BASH</abbrev> script (file of type <command>.sh</command>) to the currently selected song of the playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Edit selected Script</emphasis>:
               opens the selected script with your default editor (in an external window).
               <note>
	             <para>
	               When using the function for the first time Hydrogen will ask you which program to use as your default editor.
                 </para>
               </note>
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Remove selected Script</emphasis>:
               removes the selected script from the playlist.
             </para>
           </listitem>
	       <listitem>
	         <para>
	           <emphasis role="bold">Create a new Script</emphasis>:
               creates a new and empty <command>.sh</command> script at a location of your choice.

               <note>
	             <para>
	               The default one is the <filename role="directory">scripts</filename> folder in the Hydrogen data
                   directory (usually <filename role="directory">$HOME/.hydrogen/data/</filename>).
                 </para>
               </note>
             </para>
           </listitem>
         </itemizedlist>
       </sect2>
       
     </sect1>
   </chapter>
   <chapter id="chpt.midi">
     <title>MIDI</title>

     <para>
       <abbrev>MIDI</abbrev> is a standard for connecting electronic devices,
       like your edrum or keyboard and your computer. It enables them to
       exchange messages commonly used in audio synthesis, processing, and
       recording.
     </para>
     <para>
       This chapter will, firstly, feature a guide about how to connect your
       <abbrev>MIDI</abbrev> device to Hydrogen in section <xref
       linkend="chpt.midi.input"/>. Next, you will learn how to trigger sounds
       in Hydrogen using incoming <abbrev>MIDI</abbrev> events in <xref
       linkend="chpt.midi.note"/>. Section <xref linkend="chpt.midi.output"/>
       gives a short description of how to connect and send
       <abbrev>MIDI</abbrev> data from Hydrogen to other applications and,
       finally, <xref linkend="chpt.midi.controlling"/> covers how to control
       Hydrogen using incoming <abbrev>MIDI</abbrev> messages.
     </para>

     <sect1 id="chpt.midi.input" xreflabel="MIDI Input">
       <title>MIDI Input</title>
       <para>
         Before you can use Hydrogen as a <abbrev>MIDI</abbrev> synth or control
         it using its <link
         linkend="chpt.midi.controlling.actions">Actions</link>, you have to
         setup your incoming <abbrev>MIDI</abbrev> connection.
       </para>
       <procedure id="chpt.midi.input.setup">
         <step>
           <para>
             Connect your <abbrev>MIDI</abbrev> device to your computer and
             ensure all required drivers are installed.
           </para>
         </step>
         <step>
           <para>
             Open up the <link linkend="chpt.preferences.midi_tab">MIDI
             System</link> tab of the Preferences and choose the <emphasis>MIDI
             driver</emphasis> you connected your device to.
           </para>
         </step>
         <step>
           <para>
             Choose your <abbrev>MIDI</abbrev> device/port from the
             <emphasis>Input</emphasis> dropdown list.
           </para>

           <note>
             <para>
               For now the list of available input and output MIDI devices/ports
               is compiled for the current MIDI driver when opening the
               Preferences dialog. If you switch to another driver, be sure to
               click <emphasis>OK</emphasis> and reopen the Preferences dialog
               in order to have an updated list.
             </para>
           </note>

           <tip>
             <para>
               For a lot of <abbrev>MIDI</abbrev> drivers you can also
               establish connections with external tools, like <ulink
               url="https://qjackctl.sourceforge.io/">QjackCtl</ulink> for
               JACK-MIDI and ALSA-MIDI.
             </para>
           </tip>
         </step>
         <step>
           <para>
             Click <emphasis>OK</emphasis> to store all changes and restart
             Hydrogen's <abbrev>MIDI</abbrev> driver.
           </para>
         </step>
         <step>
           <para>
             Check for incoming <abbrev>MIDI</abbrev> messages in Hydrogen. Each
             time you send a <abbrev>MIDI</abbrev> message using your device the
             <link linkend="sect.main_toolbar.cpu_usage_midi_in">MIDI-in
             LED</link> in Hydrogen's Main Toolbar should light up in a blue
             color and a corresponding message should appear in the log on <link
             linkend="chpt.main_menu.debug.log_level.info">log level <emphasis>Info</emphasis></link>
             (see <xref linkend="chpt.main_menu.debug.open_log_file"/>).
           </para>
         </step>
       </procedure>
       
       <para>
         If you still do not hear any audio, check the <link
         linkend="chpt.mixer.channel_strips">Instrument strips</link> in the
         Mixer. On each <abbrev>MIDI</abbrev> event corresponding to an
         instrument the LED in its strip should light up. If so, the problem is
         most probably with your audio output setting.
       </para>
     </sect1>
     
     <sect1 id="chpt.midi.note" xreflabel="MIDI Note Rendering">
       <title>MIDI Note Rendering</title>
       <para>
         Hydrogen can be used as <abbrev>MIDI</abbrev> synth for your
         <abbrev>MIDI</abbrev> device. All settings in both <link
         linkend="chpt.instrument_editor">Instrument Editor</link> and <link
         linkend="chpt.mixer">Mixer</link> are applied but instead of notes
         picked up from patterns while playback is rolling, incoming
         <abbrev>MIDI</abbrev> messages will trigger sounds. In addition, all
         incoming <abbrev>MIDI</abbrev> notes can be <link
         linkend="chpt.overview.recording">recorded</link>.
       </para>

       <para>
         <emphasis>NOTE_ON</emphasis> type <abbrev>MIDI</abbrev> messages will
         trigger a note while <emphasis>NOTE_OFF</emphasis> will stop all note
         rendering in the corresponding instrument. This behavior might be
         exactly what you expected from an edrum but, on the other hand, also
         might be a pain when using a <abbrev>MIDI</abbrev> keyboard (since
         releasing a key will stop the note). In this case you can disable
         <emphasis>NOTE_OFF</emphasis> message handling by unchecking <link
         linkend="chpt.preferences.midi_tab.ignore_note_off">Ignore
         note-off</link> in the Preferences.
       </para>

       <para>
         Which incoming <abbrev>MIDI</abbrev> note is mapped to which particular
         instrument does depend on multiple settings. First of all, each
         <emphasis>NOTE_ON</emphasis> message is assigned a <emphasis
         role="bold">channel</emphasis> - the default one in the General
         <abbrev>MIDI</abbrev> standard is <option>10</option>. Using <link
         linkend="chpt.preferences.midi_tab.channel">Channel</link> in the
         Preferences you can set whether Hydrogen should listen to incoming
         notes on all channels or just to a single one. The second degree of
         freedom of a note is its <emphasis
         role="bold">pitch</emphasis>. Depending on the current <link
         linkend="chpt.midi.note.input_mode">Input Mode</link> it is either
         mapped to a pitch-shifted sample of the currently selected instrument
         or an instrument of the current drumkit. The latter will be discussed
         in section <link linkend="chpt.midi.note.mapping">MIDI Note
         Mapping</link> in more detail.
       </para>

       <note>
         <para>
           When <emphasis>NOTE_ON</emphasis> messages are <link
           linkend="chpt.midi.controlling.actions">mapped to Actions</link> they
           will be discarded and do <emphasis>not</emphasis> trigger sound when
           <link linkend="chpt.preferences.midi_tab.discard_messages">Discard
           MIDI messages after action has been triggered</link> is checked in
           the Preferences.
         </para>
       </note>
       
       <sect2 id="chpt.midi.note.input_mode" xreflabel="Input Mode">
         <title>Input Mode</title>
         <para>
	      Using <emphasis role="bold">Input Mode</emphasis> in <link
	      linkend="sect.main_menu.options">Options</link> within the Main Menu
	      you can choose between two different ways of triggering sounds and
	      record notes.
         </para>
         
         <para>
           <option>Drumkit</option> maps different <abbrev>MIDI</abbrev> notes
           (or <link linkend="chpt.overview.virtual_keyboard">Virtual
           Keyboard</link> strokes) to different instruments of the current
           drumkit. <option>Instrument</option>, on the other hand, maps them to
           pitch-shifted samples of the instrument currently selected in the
           <link linkend="chpt.pattern_editor">Pattern Editor</link>. You can
           use these modes to record notes into both <link
           linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link> and <link
           linkend="chpt.pattern_editor.piano_mode">Piano Roll Editor</link>
           respectively. The third property of a <abbrev>MIDI</abbrev> note, its
           <emphasis role="bold">velocity</emphasis>, will be used as <link
           linkend="def.velocity">velocity</link> for the triggered note.
         </para>
       </sect2>

       <sect2 id="chpt.midi.note.mapping" xreflabel="MIDI Note Mapping">
         <title>MIDI Note Mapping</title>

         <para>
           If <link linkend="chpt.midi.note.input_mode">Input Mode</link> was
           set to <option>Drumkit</option>, Hydrogen has two ways of dealing
           with incoming MIDI notes: order-based and output-based.
         </para>

         <para>
           Per default mapping in done <emphasis
           role="bold">order-based</emphasis>. Hydrogen maps incoming
           <abbrev>MIDI</abbrev> notes of pitch <option>36</option> and above to
           instruments of your drumkit. A <abbrev>MIDI</abbrev> note of pitch
           <option>36</option> will trigger a sample of the first instrument of
           your current drumkit, one of pitch <option>37</option> a sample from
           the second one and so forth. When choosing this option you can
           control mapping by drag-dropping the instruments into the desired
           order.
         </para>

         <para>
           Alternatively you can use <emphasis
           role="bold">output-based</emphasis> mapping by checking <link
           linkend="chpt.preferences.midi_tab.input_as_output">Use output note
           as input note</link> in the Preferences. This way an incoming
           <abbrev>MIDI</abbrev> note is mapped to the instrument which's <link
           linkend="fig.instrument_editor.midi_out_settings">MIDI Output
           Note</link> setting in the Instrument Editor matches its
           pitch.
         </para>

       </sect2>
       
     </sect1>

     <sect1 id="chpt.midi.output" xreflabel="MIDI Output">
       <title>MIDI Output</title>
       <para>
         Hydrogen allows you to send both notes encountered during playback as
         <emphasis>NOTE_ON</emphasis> and <emphasis>NOTE_OFF</emphasis> messages
         and the current state of specific controls using <link
         linkend="chpt.midi.output.feedback">MIDI Feedback</link> as
         <emphasis>CC</emphasis> messages.
       </para>

       <para>
         But first of all you have to set a <abbrev>MIDI</abbrev> <link
         linkend="chpt.preferences.midi_tab.output">Output</link> device in the Preferences.
       </para>

       <note>
         <para>
           The list of available <abbrev>MIDI</abbrev> output devices/ports is
           compiled for the current MIDI driver when opening the Preferences
           dialog. If you switch to another driver, be sure to click
           <emphasis>OK</emphasis> and reopen the Preferences dialog in
           order to have an updated list.
         </para>
       </note>

       <para>
         Now every note encountered during playback will trigger a
         <abbrev>MIDI</abbrev> note with the note's velocity and the channel and
         pitch specified in the corresponding <link
         linkend="chpt.instrument_editor.midi_out_settings">instrument</link>. In
         case the channel is set to <option>off</option>, no
         <abbrev>MIDI</abbrev> message will be sent.
       </para>

       <note>
         <para>
           To <emphasis role="bold">enable MIDI output</emphasis>, you have to
           set both an <emphasis role="bold">output device</emphasis> in the
           Preferences as well as <emphasis role="bold">all instrument
           MIDI channels</emphasis> to a dedicated value, like <option>10</option>.
         </para>
       </note>
       
       <sect2 id="chpt.midi.output.feedback" xreflabel="MIDI Feedback">
         <title>MIDI Feedback</title>
         <para>
           You can also keep other <abbrev>MIDI</abbrev>-capable applications
           posted about parameter changes in Hydrogen using
           <abbrev>MIDI</abbrev> Feedback. If one or more <emphasis
           role="bold">CC</emphasis> events are mapped to a parameter supporting
           feedback, all of its changes - also those triggered by incoming
           <abbrev>MIDI</abbrev> messages - will cause Hydrogen to send a CC
           message. This message will carry the same message parameters as the
           one mapped to the particular parameter within Hydrogen and will
           contain its value mapped to a range between <option>0</option> and
           <option>127</option>.
         </para>

         <para>
           Supported feedback parameters are
         </para>
         <itemizedlist>
           <listitem>
             <para>
               <link linkend="chpt.mixer.channel_strips.fader_and_lcd">Volume
               faders</link>, <link linkend="chpt.mixer.channel_strips.pan">Pan
               rotaries</link> as well as <link
               linkend="chpt.mixer.channel_strips.mute">Mute</link> and <link
               linkend="chpt.mixer.channel_strips.solo">Solo</link> buttons in
               the <link linkend="chpt.mixer.channel_strips">Instrument Channel
               Strips</link>.
             </para>
           </listitem>
           <listitem>
             <para>
               Volume fader and Mute button of the <link
               linkend="chpt.mixer.master_fader_strip">Master Fader
               Strip</link>.
             </para>
           </listitem>
           <listitem>
             <para>
               <link
               linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link>
               button.
             </para>
           </listitem>
         </itemizedlist>
       </sect2>
     </sect1>

     <sect1 id="chpt.midi.controlling" xreflabel="MIDI Controlling">
       <title>MIDI Controlling</title>
       <para>
         This section explains how you can change parameters in Hydrogen, start
         playback or recording, switch patterns, and many more using incoming
         <abbrev>MIDI</abbrev> messages. Firstly, we will have a look at which
         types of <abbrev>MIDI</abbrev> messages are supported in <xref
         linkend="chpt.midi.controlling.events"/>. Then we will discuss two
         different ways of mapping them to Actions: via the <link
         linkend="chpt.midi.controlling.actions">MIDI table</link> in the
         Preferences and <xref linkend="chpt.midi.controlling.learnable"/>
       </para>
       
       <sect2 id="chpt.midi.controlling.events" xreflabel="MIDI Events">
	     <title>MIDI Events</title>
         
         <para>
           There is a vast number of <abbrev>MIDI</abbrev> message types
           available. But Hydrogen only supports a selection of most common ones
           listed below.
         </para>
         
         <itemizedlist mark="opencircle">

           <listitem>
             <para>
	           <emphasis role="bold">NOTE_ON</emphasis>: an incoming note
	           triggered by a regular black/white key of a <abbrev>MIDI</abbrev>
	           keyboard or a pad of an e-drum. The note's <emphasis
	           role="bold">pitch</emphasis> will be used as event parameter and
	           its <emphasis role="bold">velocity</emphasis> as new value.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">CONTROL_CHANGE (CC)</emphasis>: controller
	           commands coming from e.g. faders or rotary controllers. These
	           ones can be used for <link
	           linkend="chpt.midi.output.feedback">MIDI Feedback</link> as well.
	         </para>
           </listitem>
           
           <listitem>
             <para>
	           <emphasis role="bold">PROGRAM_CHANGE (PC)</emphasis>: usually
	           intended to change the sound of instruments or to select
	           different sound banks. It does only contain an single event
	           parameter, e.g. the bank number, which will be interpreted as new
	           value.
             </para>
           </listitem>
	       
           <listitem>
             <para>
	           <emphasis role="bold">MMC_x</emphasis>: <ulink
	           url="http://en.wikipedia.org/wiki/MIDI_Machine_Control">MIDI
	           machine control</ulink> events coming from e.g. buttons, like
	           'play' or 'stop', on a controller. These messages carry neither
	           an event parameter nor a number which could be used as new
	           value. They are intended for triggering <link
	           linkend="chpt.midi.controlling.actions">Actions</link> expecting
	           no input arguments, like toggling mute or playback, and will use
               <option>0</option> as new value for all other Actions.
	         </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">START</emphasis>: System Realtime message
	           which is hard-coded to start playback in Hydrogen. It can
	           <emphasis>not</emphasis> be mapped to an <link
	           linkend="chpt.midi.controlling.actions">Action</link> or an
	           <abbrev>MIDI</abbrev>-learnable widget.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">CONTINUE</emphasis>: System Realtime message
               which is hard-coded to start playback in Hydrogen. It can
               <emphasis>not</emphasis> be mapped to an <link
	           linkend="chpt.midi.controlling.actions">Action</link> or an
               <abbrev>MIDI</abbrev>-learnable widget.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">STOP</emphasis>: System Realtime message
               which is hard-coded to pause playback in Hydrogen. It can
               <emphasis>not</emphasis> be mapped to an <link
	           linkend="chpt.midi.controlling.actions">Action</link> or an
               <abbrev>MIDI</abbrev>-learnable widget.
             </para>
           </listitem>
	       
         </itemizedlist>

         <para>
           Whether the <abbrev>MIDI</abbrev> event sent by the play button of
           your <abbrev>MIDI</abbrev> device corresponds to e.g. a
           <emphasis>START</emphasis> or <emphasis>MMC_PLAY</emphasis> event is
           up to the manufacturer and should be stated in the user manual.
         </para>

         <note>
           <para>
             For all message types except of the MMC_x ones the <link
             linkend="chpt.preferences.midi_tab.channel">Channel</link> set in
             the Preferences must be matched.
           </para>
         </note>
       </sect2>
       <sect2 id="chpt.midi.controlling.actions" xreflabel="Actions">
         <title>Actions</title>

         <para>
           An <abbrev>MIDI</abbrev> <emphasis role="bold">Event</emphasis>
           recognized by Hydrogen can be mapped to an <emphasis
           role="bold">Action</emphasis> using the <abbrev>MIDI</abbrev> table
           in the <link linkend="chpt.preferences.midi_tab">MIDI System</link>
           tab of the Preferences.
         </para>

         <note>
           <para>
             Only actions performed in the GUI can be undone.
             <abbrev>MIDI</abbrev>, on the other hand, can not!
           </para>
         </note>

         <figure id="midi_actions">
           <title>Actions are set in MIDI System tab of the Preferences Dialog</title>
           <mediaobject>
             <imageobject>
               <imagedata fileref="generated_en/MidiSystem_V2.png" format="PNG" />
             </imageobject>
           </mediaobject>
         </figure>

         <para>
           You can define mapping between incoming <abbrev>MIDI</abbrev> Events
           and Actions by either choosing an event type and
           parameter manually or by pressing the
           <inlinemediaobject>
             <textobject>
               <phrase>
                 Red circle.
               </phrase>
             </textobject>
             <imageobject>
               <imagedata fileref="generated_en/midiSenseButton.png" format="PNG" />
             </imageobject>
           </inlinemediaobject>
           button in the left-most column of the table.  A popup will inform you
           that Hydrogen is waiting for your input.  Press/hit/turn the
           key/pad/knob on your <abbrev>MIDI</abbrev> keyboard (or controller)
           that you want to link to the Action.  The popup will close and the
           <emphasis role="bold">Event Param.</emphasis> value will now show the
           <abbrev>MIDI</abbrev> message corresponding to the key you pressed.
           Once this is done you can select an Action from the drop-down list.
         </para>

         <para>
           The <emphasis role="bold">Action Param.</emphasis> columns to the
           right of the table specifies the parameters to the Action
           <emphasis>not</emphasis> provided by the <abbrev>MIDI</abbrev>
           message. In the example shown in the picture above the value set
           using the controller <option>70</option> of your
           <abbrev>MIDI</abbrev> device will be assigned to the pan of the third
           top-most instrument in the current drumkit.
         </para>
         <note>
           <para>
             Most Action parameters references a specific channel, instrument,
             FXsend id, ...  Keep in mind that their values are
             <emphasis>zero-based</emphasis>. So, if you want to reference
             channel 1 you have to enter <option>0</option> in the <emphasis
             role="bold">Action Param.</emphasis> field (<option>1</option> for
             channel 2, <option>2</option> for channel 3, and so on).
           </para>
         </note>

         <tip>
           <para>
             In order to <emphasis role="bold">delete a row</emphasis> in the
             <abbrev>MIDI</abbrev> table, you have to set both its
             <emphasis>Incoming Event</emphasis> and <emphasis>Action</emphasis>
             to an empty value.
           </para>
         </tip>
         
         <para>
           Available Actions:
         </para>

         <itemizedlist mark="opencircle">

           <listitem>
	         <para>
	           <emphasis role="bold">&#60;&#60;_PREVIOUS_BAR</emphasis>:
               moves the playhead to the previous pattern/bar.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">&#62;&#62;_NEXT_BAR</emphasis>:
               moves the playhead to the next pattern/bar.
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">BEATCOUNTER</emphasis>: calculates the average
             time passing between successive encounters of this commands and uses
             it to set the current tempo using the <link linkend="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">Beat Counter</link>.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.bpm_cc_relative" xreflabel="BPM_CC_RELATIVE">
             <para>
	           <emphasis role="bold">BPM_CC_RELATIVE</emphasis>: changes the tempo
	           relative to the current tempo, using a controller. Using
	           <emphasis>Action Param. <emphasis
	           role="bold">1</emphasis></emphasis> you can specify by how much the current
	           tempo will change. If the incoming Event is <option>-1</option>
	           (negative), the tempo will be increased and if it's
	           <option>1</option> (positive), it will be increased.
               <note>
                 <para>
                   This Action will have no effect if Hydrogen is both in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
                   and the <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.
                 </para>
               </note>
             </para>
           </listitem>


           <listitem><para>
             <emphasis role="bold">BPM_DECR</emphasis>: decreases the current tempo
             by the supplied value.
           </para>
           <note>
             <para>
               This Action will have no effect if Hydrogen is in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
               or <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.
             </para>
           </note>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">BPM_FINE_CC_RELATIVE</emphasis>: as <xref
	           linkend="chpt.midi.controlling.actions.bpm_cc_relative" /> but with
	           changes 100 times smaller than the value specified in
	           <emphasis>Action Param. <emphasis
	           role="bold">1</emphasis></emphasis>.
               <note>
                 <para>
                   This Action will have no effect if Hydrogen is in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
                   or <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.
                 </para>
               </note>
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">BPM_INCR</emphasis>: increases the current tempo
             by the supplied value.
           </para>
           <note>
             <para>
               This Action will have no effect if Hydrogen is in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
               or <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.
             </para>
           </note>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">CLEAR_PATTERN</emphasis>: removes all notes of the selected
               pattern.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">CLEAR_SELECTED_INSTRUMENT</emphasis>: removes all notes of the selected
               pattern associated with the currently selected instrument.
             </para>
           </listitem>

           <listitem id="chpt.midi.controlling.actions.effect_level_absolute" xreflabel="EFFECT_LEVEL_ABSOLUTE">
             <para>
               <emphasis role="bold">EFFECT_LEVEL_ABSOLUTE</emphasis>: changes
               the <link linkend="chpt.mixer.channel_strips.fx_volume" >volume
               level of an FX</link>. <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis> determines the <link
               linkend="chpt.mixer.channel_strips">Instrument Channel
               Strip</link> and <emphasis>Action Param. <emphasis
               role="bold">2</emphasis></emphasis> specifies the FX the Action
               will be applied to. </para></listitem>

           <listitem><para>
             <emphasis role="bold">EFFECT_LEVEL_RELATIVE</emphasis>:
             same as <xref linkend="chpt.midi.controlling.actions.effect_level_absolute"/> but instead mapping the incoming values directly to the FX volume <option>1</option> will increase and all other values will decrease it by 5%.
           </para></listitem>

           <listitem>
             <para>
	           <emphasis role="bold">FILTER_CUTOFF_LEVEL_ABSOLUTE</emphasis>: for
	           a value of <option>0</option> it sets the <link
	           linkend="chpt.instrument_editor.filter">Filter Cutoff</link> of the
	           instrument strip specified using the <emphasis>Action Param.
	           <emphasis role="bold">1</emphasis></emphasis> to
	           <option>0</option>. For all other values it sets the cutoff to the
	           provided number divided by 127.0.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">GAIN_LEVEL_ABSOLUTE</emphasis>: sets the
               <link
               linkend="chpt.instrument_editor.layers.controls.layer_gain">Layer
               Gain</link>. <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis> specifies the instrument,
               <emphasis>Action Param. <emphasis
               role="bold">2</emphasis></emphasis> the component, and
               <emphasis>Action Param. <emphasis
               role="bold">3</emphasis></emphasis> the layer.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">INSTRUMENT_PITCH</emphasis>: sets the <link
               linkend="chpt.instrument_editor.pitch_shift_parameters">Pitch</link>
               of the instrument specified by <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem id="chpt.midi.controlling.actions.master_volume_absolute" xreflabel="MASTER_VOLUME_ABSOLUTE"><para>
             <emphasis role="bold">MASTER_VOLUME_ABSOLUTE</emphasis>: sets the <link linkend="chpt.mixer.master_fader_strip">Master output volume</link> to the value provided by the <abbrev>MIDI</abbrev> event times 1.5 and divided by 127.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.master_volume_relative" xreflabel="MASTER_VOLUME_RELATIVE"><para>
             <emphasis role="bold">MASTER_VOLUME_RELATIVE</emphasis>: changes the <link linkend="chpt.mixer.master_fader_strip">Master output volume</link>, relative
             to its current setting. For a value of <option>0</option> it sets the volume of
             the master fader to 0. For a value of <option>1</option> it increases its
             volume by 0.05 and for all other values it decreases it by
             0.05. (<option>-1</option>: -0.05 , <option>0</option>: 0 ,<option>1</option>: +0.05)
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">MUTE</emphasis>: <link linkend="def.mute">mutes</link> the <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">MUTE_TOGGLE</emphasis>: toggles the <link linkend="def.mute">muting</link> of the
             <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.pan_absolute" xreflabel="PAN_ABSOLUTE">
             <para>
               <emphasis role="bold">PAN_ABSOLUTE</emphasis>: changes the <link
               linkend="def.pan">pan</link> of an <link
               linkend="chpt.mixer.channel_strips.pan">instrument</link>
               determined by the <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis> to the absolute value that
               the linked controller sends to Hydrogen. Incoming values from
               <option>0</option> to <option>127</option> will be mapped to pan
               values between -1 and 1.
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">PAN_ABSOLUTE_SYM</emphasis>: same as <xref linkend="chpt.midi.controlling.actions.pan_absolute"/> but supports incoming values from <option>-127</option> to <option>127</option> will be mapped.
           </para></listitem>

           <listitem>
             <para>
               <emphasis role="bold">PAN_RELATIVE</emphasis>: changes the <link
               linkend="def.pan">pan</link> of an <link
               linkend="chpt.mixer.channel_strips.pan">instrument</link>
               determined by <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis> relative to the current
               value. For a value of <option>1</option> it increase the pan by
               0.05. For all other values it decreases it by 0.05.
               (<option>-1</option>: -0.05 , <option>1</option>: +0.05).
             </para>
           </listitem>

           <listitem id="chpt.midi.controlling.actions.pause" xreflabel="PAUSE"><para>
             <emphasis role="bold">PAUSE</emphasis>: pauses playback.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.pitch_level_absolute" xreflabel="PITCH_LEVEL_ABSOLUTE">
             <para>
               <emphasis role="bold">PITCH_LEVEL_ABSOLUTE</emphasis>: sets the
               <link
               linkend="chpt.instrument_editor.layers.controls.pitch">Layer
               Pitch</link>. <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis> specifies the instrument,
               <emphasis>Action Param. <emphasis
               role="bold">2</emphasis></emphasis> the component, and
               <emphasis>Action Param. <emphasis
               role="bold">3</emphasis></emphasis> the layer.
             </para>
           </listitem>

           <listitem id="chpt.midi.controlling.actions.play" xreflabel="PLAY"><para>
             <emphasis role="bold">PLAY</emphasis>: starts playback.
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">PLAY/PAUSE_TOGGLE</emphasis>: works the same as
             <xref linkend="chpt.midi.controlling.actions.play"/> if the
             playback has not started yet and same as. 
             <xref linkend="chpt.midi.controlling.actions.pause"/> otherwise. (The playhead will not return
             to the start of the song, but will stay at its current position).
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">PLAY/STOP_TOGGLE</emphasis>: works the same as <xref linkend="chpt.midi.controlling.actions.play"/> if the
             playback has not started yet and same as.
             <xref linkend="chpt.midi.controlling.actions.stop"/> otherwise.
           </para></listitem>

           <listitem>
             <para>
	             <emphasis role="bold">PLAYLIST_NEXT_SONG</emphasis>: opens the
	             song in the current <link
	             linkend="chpt.playlist_editor">playlist</link> corresponding to
	             the song number specified in <emphasis>Action Param. <emphasis
	             role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">PLAYLIST_PREV_SONG</emphasis>:
               opens the previous song in the current <link linkend="chpt.playlist_editor">playlist</link>.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">PLAYLIST_SONG</emphasis>:
               opens the next song in the current <link linkend="chpt.playlist_editor">playlist</link>.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">RECORD/STROBE_TOGGLE</emphasis>:
               toggles <link linkend="chpt.overview.recording">recording</link> (same as pressing the <link linkend="sect.main_toolbar.transport_control">record button</link>
               in the main toolbar).
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">RECORD_EXIT</emphasis>:
               deactivates <link linkend="chpt.overview.recording">recording</link>.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">RECORD_READY</emphasis>:
               toggles <link linkend="chpt.overview.recording">recording</link> (same as pressing the <link linkend="sect.main_toolbar.transport_control">record button</link>
               in the main toolbar) if the playback has not started yet.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">RECORD_STROBE</emphasis>:
               activates <link linkend="chpt.overview.recording">recording</link>.
             </para>
           </listitem>

           <listitem>
             <para>
	           <emphasis role="bold">REDO_ACTION</emphasis>:
               redoes the previously undone GUI action (not <abbrev>MIDI</abbrev> action!).
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">SELECT_AND_PLAY_PATTERN</emphasis>: works as
             <xref linkend="chpt.midi.controlling.actions.select_next_pattern"/> combined with
             <xref linkend="chpt.midi.controlling.actions.play"/>.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.select_instrument" xreflabel="SELECT_INSTRUMENT">
             <para>
	           <emphasis role="bold">SELECT_INSTRUMENT</emphasis>:
               selects the instrument in the drumkit corresponding to the number supplied in the incoming <abbrev>MIDI</abbrev> Event.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.select_next_pattern" xreflabel="SELECT_NEXT_PATTERN">
             <para>
               <emphasis role="bold">SELECT_NEXT_PATTERN</emphasis>: selects the
               pattern specified in <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.

               <note>
                 <para>
                   If Hydrogen is in <link
                   linkend="chpt.song_editor.editor_modes.pattern_mode">Selected
                   Pattern Mode</link>, playback will be switched to the
                   selected pattern immediately. If it is, instead, in <link
                   linkend="chpt.song_editor.editor_modes.stacked">Stacked
                   Pattern Mode</link>, playback of the selected pattern will be
                   toggled next time transport is loop again. In case the
                   pattern was already playing, it will be stopped. If not, it
                   will be started.
                 </para>
	               <para>
	                 If Hydrogen is in <link
	                 linkend="chpt.song_editor.editor_modes.song_mode">Song
	                 Mode</link>, the command will have no effect.
                 </para>
               </note>
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">SELECT_NEXT_PATTERN_CC_ABSOLUTE</emphasis>:
             like <xref linkend="chpt.midi.controlling.actions.select_next_pattern" /> but the pattern to be selected is determined by the value of the <abbrev>MIDI</abbrev> message.
           </para></listitem>

           <listitem>
             <para>
               <emphasis role="bold">SELECT_NEXT_PATTERN_RELATIVE</emphasis>:
               like <xref
               linkend="chpt.midi.controlling.actions.select_next_pattern" />
               but the pattern to be selected is determined by the pattern
               number of the currently selected one plus the value specified in
               <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem id="chpt.midi.controlling.actions.select_only_next_pattern" xreflabel="SELECT_ONLY_NEXT_PATTERN">
             <para>
               <emphasis role="bold">SELECT_ONLY_NEXT_PATTERN</emphasis>:
               selects the pattern specified in <emphasis>Action Param.
               <emphasis role="bold">1</emphasis></emphasis>.

             <note>
               <para>
                 If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.stacked">Stacked Pattern Mode</link>, only the selected pattern will be played back once the transport gets looped again. For <link linkend="chpt.song_editor.editor_modes.pattern_mode">Selected Pattern Mode</link> this Action behaves as <xref linkend="chpt.midi.controlling.actions.select_next_pattern" />.
               </para>
               <para>
                 If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>, the command will have no effect.
               </para>
             </note>
             <tip>
               <para>
                 By providing a number smaller than <option>0</option> or larger than the number of available patterns all playing patterns can be stopped at once without stopping playback itself.
               </para>
             </tip>
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">SELECT_ONLY_NEXT_PATTERN_CC_ABSOLUTE</emphasis>:
             like <xref linkend="chpt.midi.controlling.actions.select_only_next_pattern" /> but the pattern to be selected is determined by the value of the <abbrev>MIDI</abbrev> message.
           </para></listitem>

           <listitem id="chpt.midi.controlling.actions.stop" xreflabel="STOP"><para>
             <emphasis role="bold">STOP</emphasis>: stops playback and moves the
             playhead to the beginning of the song.
           </para></listitem>

           <listitem>
             <para>
               <emphasis role="bold">STRIP_MUTE_TOGGLE</emphasis>: <link
               linkend="def.mute">mutes</link> the instrument specified in
               <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">STRIP_SOLO_TOGGLE</emphasis>: <link
               linkend="def.mute">mutes</link> the instrument specified in
               <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">STRIP_VOLUME_ABSOLUTE</emphasis>: see <xref
               linkend="chpt.midi.controlling.actions.master_volume_absolute"/>,
               but applies to the <link
               linkend="chpt.mixer.channel_strips">Instrument Channel
               Strip</link> specified in <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem>
             <para>
               <emphasis role="bold">STRIP_VOLUME_RELATIVE</emphasis>: see <xref
               linkend="chpt.midi.controlling.actions.master_volume_relative"/>,
               but applies to the <link
               linkend="chpt.mixer.channel_strips">Instrument Channel
               Strip</link> specified in <emphasis>Action Param. <emphasis
               role="bold">1</emphasis></emphasis>.
             </para>
           </listitem>

           <listitem><para>
             <emphasis role="bold">TAP_TEMPO</emphasis>: another command
             calculating the average time passing between successive encounters of
             this commands and uses it to set the current tempo using <link linkend="sect.main_toolbar.tap_tempo_beat_counter.tap_tempo">Tap Tempo</link>.
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">TOGGLE_METRONOME</emphasis>:
             toggles the metronome.
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">UNDO_ACTION</emphasis>:
             undoes the previous GUI action (not <abbrev>MIDI</abbrev> action!).
           </para></listitem>

           <listitem><para>
             <emphasis role="bold">UNMUTE</emphasis>: unmutes the <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).
           </para></listitem>

         </itemizedlist>
       </sect2>

       <sect2 id="chpt.midi.controlling.learnable" xreflabel="MIDI-learnable Widgets">
         <title>MIDI-learnable Widgets</title>
         <para>
           For more convenient handling some <link
           linkend="chpt.midi.controlling.actions">Actions</link> are associated
           with GUI elements and can directly be mapped to <abbrev>MIDI</abbrev>
           Events by pressing <keycap>Shift</keycap> while
           <emphasis>left-clicking</emphasis> the widget.
         </para>
         <para>Such elements are:</para>
         <itemizedlist>
           <listitem>
             <para>
               <link linkend="chpt.mixer.channel_strips.fader_and_lcd">Volume
               faders</link>, <link
               linkend="chpt.mixer.channel_strips.fx_volume">FX Colume
               knobs</link>, <link linkend="chpt.mixer.channel_strips.pan">Pan
               rotaries</link> as well as <link
               linkend="chpt.mixer.channel_strips.mute">Mute</link> and <link
               linkend="chpt.mixer.channel_strips.solo">Solo</link> buttons in
               the <link linkend="chpt.mixer.channel_strips">Instrument Channel
               Strips</link>.
             </para>
           </listitem>
           <listitem>
             <para>
               Volume fader and Mute button of the <link
               linkend="chpt.mixer.master_fader_strip">Master Fader
               Strip</link>.
             </para>
           </listitem>
           <listitem>
             <para>
               Rewind, Record, Play, Stop, and Fast Forward buttons in the <link
               linkend="fig.main_toolbar.transport_control">Transport
               Control</link> and <link
               linkend="sect.main_toolbar.tap_tempo_beat_counter">Beat Counter
               </link> as well as <link
               linkend="sect.main_toolbar.bpm_control_and_metronome">Metronome</link> button.
             </para>
           </listitem>
           <listitem>
             <para>
               Rewind, Play, Stop, and Fast Forward buttons in the <link
               linkend="chpt.playlist_editor">Playlist Editor</link>.
             </para>
           </listitem>
         </itemizedlist>

         <para>A 'Waiting for <abbrev>MIDI</abbrev> input...' popup informs you
         that Hydrogen is now waiting for you to press a key or turn/move a
         controller on your <abbrev>MIDI</abbrev> device. If successful, the new
         mapping is shown in both the tooltip of the GUI element as well as the
         <link linkend="chpt.midi.controlling.actions">MIDI table</link> in the
         Preferences.
         </para>

         <note>
           <para>If the element that does not support <abbrev>MIDI</abbrev> automation, a different popup will inform you.
           </para>
         </note>
       </sect2>

     </sect1>
   </chapter>
   
   <chapter id="chpt.osc" xreflabel="OSC">
	 <title>OSC API</title>
	 <para>Open Sound Control (<abbrev>OSC</abbrev>) is a protocol for communication among
     programs, computers, and hardware, like synthesizers or multimedia
     devices, via networking protocols such as UDP or TCP. It can be thought
     of as a replacement for the <abbrev>MIDI</abbrev> protocol with rich benefits, like
     supporting symbolic and high-resolution numerical argument data,
     providing an URL-style naming scheme in combination with a pattern
     matching language, and allowing to bundle messages for a better handling
     of timing and simultaneous processing.</para>

     <note>
       <para>
         Only actions performed in the GUI can be undone.
         <abbrev>OSC</abbrev> commands, on the other hand, can not!
       </para>
     </note>

     <sect1 id="chpt.osc.basics">
       <title>Basics</title>
	   
       <para>Hydrogen is able to receive and send <abbrev>OSC</abbrev> messages. This allows you
       to control it using various devices, like hardware <abbrev>OSC</abbrev> controllers,
       smartphones, tablets, or any PC. For Linux-based systems you can use or
       test these interactions using the command line program
       <command>oscsend</command>.</para>

       <screen>
         <prompt>$</prompt> <command>oscsend localhost 9000 /Hydrogen/NEW_SONG s /tmp/new.h2song</command>
       </screen>

       <note>
	     <para>
	       To enable <abbrev>OSC</abbrev> support in Hydrogen, open the <link linkend="chpt.preferences.osc_tab">OSC</link> tab in the Preferences dialog. Make sure that the "Enable <abbrev>OSC</abbrev>
	       support" checkbox is activated, otherwise Hydrogen will not listen for
	       incoming <abbrev>OSC</abbrev> messages.
         </para>
       </note>

       <tip>
         <para>
           Hydrogen's port number defaults to <option>9000</option> for historical reasons. Since this is also the number used in the coding examples provided by <command>liblo</command> package, you may encounter other applications trying to register the same port (which is not possible). In order to avoid hiccups in your audio setup, it's advised to set a different default port in such cases.
         </para>
       </tip>

       <warning>
	     <para>
	       <command>oscsend</command> should only be used for sparse interactive testing and control via a command-line. Using it in scripts is not recommended since every time it sends a command it will registers a new client at the <abbrev>OSC</abbrev> server. If the <emphasis role="bold">Enable <abbrev>OSC</abbrev> feedback</emphasis> option in the <link linkend="chpt.preferences.osc_tab"><abbrev>OSC</abbrev></link> tab of the Preferences dialog is checked, Hydrogen will send its current state to all registered clients causing it to become slower and slower with every <command>oscsend</command> command sent. Soon you will experience visual lags. When unchecking this option, however, using <command>oscsend</command> is fine.
         </para>
       </warning>
       
     </sect1>
     
     <sect1 id="chpt.osc.commands">
       <title>Commands</title>

       <sect2 id="chpt.osc.commands.syntax">
	     <title>Syntax</title>

         <para>The syntax for sending the commands is</para>

         <screen>
           <prompt>$</prompt> <command>oscsend localhost OSC_PORT_NUMBER COMMAND_URL COMMAND_TYPE COMMAND_ARGUMENT</command>
         </screen>

         <para>with the supported types</para>
         <itemizedlist mark="opencircle">
           <listitem><para><emphasis role="bold">' '</emphasis>: no argument required</para></listitem>
           <listitem><para><emphasis role="bold">i</emphasis>: int32</para></listitem>
           <listitem><para><emphasis role="bold">f</emphasis>: float32</para></listitem>
           <listitem><para><emphasis role="bold">s</emphasis>: <abbrev>OSC</abbrev>-string (ASCII)</para></listitem>
           
         </itemizedlist>
         <para>Detailed description of the formats and conventions used in the
         tables below</para>
         <itemizedlist mark="opencircle">
           <listitem>
             <para><emphasis role="bold">ff</emphasis>: two types placed right after each
             other indicated that the command requires two distinct
             arguments.</para>
           </listitem>
           <listitem>
             <para><emphasis role="bold">' ',[f]</emphasis>: two types separated by a comma
             indicate that two versions of the command are available. To support
             <command>TouchOSC</command> all commands expecting no parameter
             are available in an alternative version requiring a float too. In
             the latter version the argument will be ignored and it is placed in
             squared brackets <emphasis>[f]</emphasis> to indicate its
             inferiority compared to the non-parametric version.</para> 
           </listitem>
           <listitem>
             <para><emphasis role="bold">[0,]</emphasis>: limitations in possible values of the input parameters are
             indicated in the <emphasis>range</emphasis> column. For continuous
             values squared brackets
             <emphasis>[LOWER_LIMIT,UPPER_LIMIT]</emphasis> are used and a limit 
             will be left empty when it is associated with a "natural" boundary,
             like the total number of instrument or pattern.</para>
           </listitem>
           <listitem>
             <para><emphasis role="bold">{-1;0;1}</emphasis>: sets of discrete
             values are shown in curly brackets and separated semicolon
             <emphasis>{VALUE;...}</emphasis> and usually feature the most
             convenient input options.</para>
           </listitem>
           <listitem>
             <para><emphasis role="bold">1.0</emphasis>: also in order to support
             <command>TouchOSC</command> all numerical input has to be passed as type float while
             most of these numbers will be rounded to integers internally. For
             all true float inputs the <emphasis>range</emphasis> column uses a
             floating point representation of the limits, like 1.0 instead of 1.</para>
           </listitem>
           <listitem>
             <para><emphasis role="bold">X</emphasis>: all commands ending with a
             <emphasis>/X/</emphasis> require this character to be replaced by an
             integer and do affect only the corresponding instrument,
             e.g. <command>oscsend localhost 9000 /Hydrogen/PAN_ABSOLUTE/1/ f
             0.3</command>. The instrument number starts at 1 and is determined
             by the order of the instrument in the mixer and pattern
             editor.</para>
           </listitem>
         </itemizedlist>
       </sect2>

       <sect2 id="chpt.osc.commands.all_messages">
         <title>All Commands</title>
         
         <table frame='all'>
           <title>All <abbrev>OSC</abbrev> Messages</title>
           <tgroup cols='3' align='left' colsep='1' rowsep='1'>
             <colspec colname='cURL'/>
             <colspec colname='cType'/>
             <colspec colname='cDescription'/>
             <thead>
               <row>
                 <entry>URL</entry>
                 <entry>type</entry>
                 <entry>range</entry>
                 <entry>description</entry>
               </row>
             </thead>
             <tbody>
               <row id="chpt.osc.command.play" xreflabel="/Hydrogen/PLAY/">
                 <entry>/Hydrogen/<emphasis role="bold">PLAY</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Starts playback.</entry>
               </row>
               <row id="chpt.osc.command.pause" xreflabel="/Hydrogen/PAUSE/">
                 <entry>/Hydrogen/<emphasis role="bold">PAUSE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Stops playback.</entry>
               </row>
               <row id="chpt.osc.command.stop" xreflabel="/Hydrogen/STOP/">
                 <entry>/Hydrogen/<emphasis role="bold">STOP</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Stops playback and moves the playhead to the beginning
                 of the song.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PLAY_PAUSE_TOGGLE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Works the same as <xref linkend="chpt.osc.command.play"/> if the
                 playback has not started yet and same as.
                 <xref linkend="chpt.osc.command.pause"/> otherwise. (The playhead will not
                 return to the start of the song, but will stay at its current
                 position).</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PLAY_STOP_TOGGLE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Works the same as <xref linkend="chpt.osc.command.play"/> if the
                 playback has not started yet and same as.
                 <xref linkend="chpt.osc.command.stop"/> otherwise.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">RECORD_READY</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Toggles <link linkend="chpt.overview.recording">recording</link> (same as pressing the <link linkend="sect.main_toolbar.transport_control">record button</link>) if the playback has not started yet.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">RECORD_STROBE_TOGGLE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Toggles <link linkend="chpt.overview.recording">recording</link> (same as pressing the <link linkend="sect.main_toolbar.transport_control">record button</link>).</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">RECORD_STROBE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Activates <link linkend="chpt.overview.recording">recording</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">RECORD_EXIT</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Deactivates <link linkend="chpt.overview.recording">recording</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">NEXT_BAR</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Moves the playhead to the next pattern/bar.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PREVIOUS_BAR</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Moves the playhead to the previous pattern/bar.</entry>
               </row>
               <row id="chpt.osc.command.select_next_pattern" xreflabel="/Hydrogen/SELECT_NEXT_PATTERN/">
                 <entry>/Hydrogen/<emphasis role="bold">SELECT_NEXT_PATTERN</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link>,
                 switch to pattern <emphasis>f</emphasis>. If Hydrogen is in
                 <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>, the command will have no effect.</entry>
               </row>
               <row id="chpt.osc.command.select_only_next_pattern" xreflabel="/Hydrogen/SELECT_ONLY_NEXT_PATTERN/">
                 <entry>/Hydrogen/<emphasis role="bold">SELECT_ONLY_NEXT_PTTERN</emphasis>/</entry>
                 <entry>f</entry>
                 <entry></entry>
                 <entry>If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.stacked">Stacked Pattern Mode</link>,
                 play back pattern <emphasis>f</emphasis> and stop all other
                 patterns currently playing. In <link
                 linkend="chpt.song_editor.editor_modes.pattern_mode">Selected
                 Pattern Mode</link> this action behaves like <xref linkend="chpt.osc.command.select_next_pattern"/>. If Hydrogen is in
                 <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>, the command will have no effect.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SELECT_AND_PLAY_PATTERN</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>Works as <xref linkend="chpt.osc.command.select_next_pattern"/>
                 combined with <xref linkend="chpt.osc.command.play"/>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">RELOCATE</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>,
                 locates the playhead to pattern number
                 <emphasis>f</emphasis>. If Hydrogen is in <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern Mode</link>, locates the playhead to the beginning of the
                 current pattern.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">BPM</emphasis>/</entry>
                 <entry>f</entry>
                 <entry></entry>
                 <entry>Sets the current tempo to
                 <emphasis>f</emphasis>. Note that this command will have no
                 effect if Hydrogen is both in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
                 and the <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">BPM_DECR</emphasis>/</entry>
                 <entry>f</entry>
                 <entry></entry>
                 <entry>Decreases the current tempo by
                 <emphasis>f</emphasis>. Note that this command will have no
                 effect if Hydrogen is both in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
                 and the <link linkend="chpt.song_editor.timeline">Timeline</link> is activated.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">BPM_INCR</emphasis>/</entry>
                 <entry>f</entry>
                 <entry></entry>
                 <entry>Increases the current tempo by
                 <emphasis>f</emphasis>.
                 Note that this command will have no
                 effect if Hydrogen is both in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
                 and <emphasis>Tempo Marker</emphasis> has been passed.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">BEATCOUNTER</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Calculates the average time passing between successive
                 encounters of this commands and uses it to set the current
                 tempo using the <link linkend="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">Beat Counter</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">TAP_TEMPO</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Another command calculating the average time passing
                 between successive encounters of this commands and uses it to
                 set the current tempo using <link linkend="sect.main_toolbar.tap_tempo_beat_counter.tap_tempo">Tap Tempo</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">TIMELINE_ACTIVATION</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{0,1}</entry>
                 <entry>Activates the <link linkend="chpt.song_editor.timeline">Timeline</link> if <emphasis>f</emphasis> is not
                 zero and deactivates it otherwise.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">TIMELINE_ADD_MARKER</emphasis>/</entry>
                 <entry>ff</entry>
                 <entry>[0,] [10,400]</entry>
                 <entry>Adds a Tempo Marker to the <link linkend="chpt.song_editor.timeline">Timeline</link>. The first argument
                 specifies the pattern/bar to at the marker to and the second
                 its tempo.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">TIMELINE_DELETE_MARKER</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>Deletes a Tempo Marker at pattern/bar
                 <emphasis>f</emphasis> on the <link linkend="chpt.song_editor.timeline">Timeline</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">MUTE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry><link linkend="def.mute">Mutes</link> the <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">UNMUTE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Unmutes the <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).</entry>
               </row>
               <row id="chpt.osc.command.mute_toggle">
                 <entry>/Hydrogen/<emphasis role="bold">MUTE_TOGGLE</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Toggles the muting of the <link linkend="chpt.mixer.master_fader_strip">Master output</link> (sequencer keeps running).</entry>
               </row>
               <row id="chpt.osc.command.master_volume_absolute" xreflabel="/Hydrogen/MASTER_VOLUME_ABSOLUTE/">
                 <entry>/Hydrogen/<emphasis role="bold">MASTER_VOLUME_ABSOLUTE</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0.0,1.5]</entry>
                 <entry>Sets the volume of the <link linkend="chpt.mixer.master_fader_strip">Master fader</link>.</entry>
               </row>
               <row id="chpt.osc.command.master_volume_relative" xreflabel="/Hydrogen/MASTER_VOLUME_RELATIVE/">
                 <entry>/Hydrogen/<emphasis role="bold">MASTER_VOLUME_RELATIVE</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{-1;0;1}</entry>
                 <entry>Changes the <link linkend="chpt.mixer.master_fader_strip">Master output volume</link>, relative
	             to the current setting. For a value of <option>0</option> it sets the volume of
                 the master fader to 0. For a value of <option>1</option> it increases its
                 volume by 0.05 and for all other values it decreases it by
                 0.05. (<option>-1</option>: -0.05 ,<option>0</option>: 0 ,<option>1</option>: +0.05)</entry>
               </row>
               <row id="chpt.osc.command.strip_volume_absolute">
                 <entry>/Hydrogen/<emphasis role="bold">STRIP_VOLUME_ABSOLUTE/X</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0.0,1.5]</entry>
                 <entry>See <xref linkend="chpt.osc.command.master_volume_absolute"/>, but
                 applies to the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link> provided in the <abbrev>OSC</abbrev> command path
                 as <emphasis>X</emphasis>. Please not that this only affects
                 <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link>. Strip volume
                 control for <link linkend="chpt.mixer.component_strips">Component Channel Strips</link> is not implemented
                 yet).</entry>
               </row>
               <row id="chpt.osc.command.strip_volume_relative">
                 <entry>/Hydrogen/<emphasis role="bold">STRIP_VOLUME_RELATIVE/X</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{-1;0;1}</entry>
                 <entry>See <xref linkend="chpt.osc.command.master_volume_relative"/>, but
                 applies to the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link> provided in the <abbrev>OSC</abbrev> command path
                 as <emphasis>X</emphasis>. Please not that this only affects
                 <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link>. Strip volume
                 control for <link linkend="chpt.mixer.component_strips">Component Channel Strips</link> is not implemented
                 yet).</entry>
               </row>
               <row id="chpt.osc.command.pan_absolute">
                 <entry>/Hydrogen/<emphasis role="bold">PAN_ABSOLUTE/X</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0.0,1.0]</entry>
                 <entry>Sets the pan of instrument strip <emphasis>X</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PAN_RELATIVE/X</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{-1;1}</entry>
                 <entry>Changes the <link linkend="def.pan">pan</link> of the <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link>
                 <emphasis>X</emphasis>, relative to the current value. For a
                 value of <option>1</option> it increase the pan by 0.05. For all other values
                 it decreases it by 0.05. (<option>-1</option>: -0.05 , <option>1</option>: +0.05)</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">FILTER_CUTOFF_LEVEL_ABSOLUTE/X</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,127]</entry>
                 <entry>For a value of <option>0</option> it sets the <link linkend="chpt.instrument_editor.filter">Filter Cutoff</link> of the
                 <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link> <emphasis>X</emphasis> to 0. For all other
                 values it sets the cutoff to the provided number divided by
                 127.0. Please note that this parameter is not displayed
                 anywhere in the Mixer but in the Instrument Rack.</entry>
               </row>
               <row id="chpt.osc.command.strip_mute_toggle">
                 <entry>/Hydrogen/<emphasis role="bold">STRIP_MUTE_TOGGLE/X</emphasis>/</entry>
                 <entry>'',[f]</entry>
                 <entry></entry>
                 <entry>Toggles muting of <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link>
                 <emphasis>X</emphasis>. Optional input argument will be
                 ignored.</entry>
               </row>
               <row id="chpt.osc.command.strip_solo_toggle">
                 <entry>/Hydrogen/<emphasis role="bold">STRIP_SOLO_TOGGLE/X</emphasis>/</entry>
                 <entry>'',[f]</entry>
                 <entry></entry>
                 <entry>Toggles soloing of <link linkend="chpt.mixer.channel_strips">Instrument Channel Strip</link>
                 <emphasis>X</emphasis>. Optional input argument will be
                 ignored.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">INSTRUMENT_PITCH</emphasis>/</entry>
                 <entry>ff</entry>
                 <entry>[0,] [-24.5,24.5]</entry>
                 <entry>Sets the <link
                 linkend="chpt.instrument_editor.pitch_shift_parameters">Pitch</link>
                 of the instrument specified using the first parameter
                 <emphasis>f</emphasis> to the second parameter
                 <emphasis>f</emphasis>.</entry>
               </row>
               <row id="chpt.osc.command.playlist_song">
                 <entry>/Hydrogen/<emphasis role="bold">PLAYLIST_SONG</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>Opens song <emphasis>f</emphasis> of the <link linkend="chpt.playlist_editor">Playlist</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PLAYLIST_NEXT_SONG</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Opens the next song in the <link linkend="chpt.playlist_editor">Playlist</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">PLAYLIST_PREV_SONG</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Opens the previous song in the <link linkend="chpt.playlist_editor">Playlist</link>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">UNDO_ACTION</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Undoes the previous GUI action (not <abbrev>OSC</abbrev> command!).</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">REDO_ACTION</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Redoes the previously undone GUI action (not <abbrev>OSC</abbrev> command!).</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">JACK_TRANSPORT_ACTIVATION</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{0;1}</entry>
                 <entry>Deactivated the <link linkend="sect.preferences.jack"><abbrev>JACK</abbrev> transport</link> support for a value of <option>0</option>
                 and activates it for all others.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">JACK_TIMEBASE_MASTER_ACTIVATION</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{0;1}</entry>
                 <entry>Unregisters Hydrogen as <abbrev>JACK</abbrev> Timebase controller
                 for a value of <option>0</option> and registers it for all others.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SONG_MODE_ACTIVATION</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{0;1}</entry>
                 <entry>Deactivated <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link> for a value of <option>0</option> and activates it
                 for all others.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">LOOP_MODE_ACTIVATION</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>{0;1}</entry>
                 <entry>Deactivated <link linkend="sect.main_toolbar.transport_control">looped playback</link> for a value of <option>0</option> and activates it
                 for all others.</entry>
               </row>
               <row id="chpt.osc.command.toggle_metronome">
                 <entry>/Hydrogen/<emphasis role="bold">TOGGLE_METRONOME</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Toggles the <link linkend="sect.main_toolbar.bpm_control_and_metronome">metronome</link>.</entry>
               </row>
               <row id="chpt.osc.command.select_instrument">
                 <entry>/Hydrogen/<emphasis role="bold">SELECT_INSTRUMENT</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>Selects a specific instrument in the drumkit.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">NEW_SONG</emphasis>/</entry>
                 <entry>s</entry>
                 <entry></entry>
                 <entry>Creates an empty song which will be stored at the
                 absolute path <emphasis>s</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">OPEN_SONG</emphasis>/</entry>
                 <entry>s</entry>
                 <entry></entry>
                 <entry>Opens an existing song associated with the absolute
                 path <emphasis>s</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SAVE_SONG</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Saves the current song.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SAVE_SONG_AS</emphasis>/</entry>
                 <entry>s</entry>
                 <entry></entry>
                 <entry>Saves the current song to the absolute path <emphasis>s</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SAVE_PREFERENCES</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Saves the preferences.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">QUIT</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Exits Hydrogen.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">NEW_PATTERN</emphasis>/</entry>
                 <entry>s</entry>
                 <entry></entry>
                 <entry>Creates an empty pattern of name <emphasis>s</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">OPEN_PATTERN</emphasis>/</entry>
                 <entry>s</entry>
                 <entry></entry>
                 <entry>Opens an existing pattern at the absolute
                 path <emphasis>s</emphasis>.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">REMOVE_PATTERN</emphasis>/</entry>
                 <entry>f</entry>
                 <entry></entry>
                 <entry>Removes pattern number <emphasis>f</emphasis>. </entry>
               </row>
               <row id="chpt.osc.command.clear_pattern" xreflabel="/Hydrogen/CLEAR_PATTERN/">
                 <entry>/Hydrogen/<emphasis role="bold">CLEAR_PATTERN</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Removes all notes of the selected pattern.</entry>
               </row>
               <row id="chpt.osc.command.clear_selected_instrument" xreflabel="/Hydrogen/CLEAR_SELECTED_INSTRUMENT/">
                 <entry>/Hydrogen/<emphasis role="bold">CLEAR_SELECTED_INSTRUMENT</emphasis>/</entry>
                 <entry>' ',[f]</entry>
                 <entry></entry>
                 <entry>Removes all notes of the selected pattern associated with
                 the currently selected instrument.</entry>
               </row>
               <row id="chpt.osc.command.clear_instrument" xreflabel="/Hydrogen/CLEAR_INSTRUMENT/">
                 <entry>/Hydrogen/<emphasis role="bold">CLEAR_INSTRUMENT</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[0,]</entry>
                 <entry>Works as <xref linkend="chpt.osc.command.clear_selected_instrument"/>
                 but on instrument <emphasis>f</emphasis> instead.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">NOTE_ON</emphasis>/</entry>
                 <entry>ff</entry>
                 <entry>[36,127] [0.0,1.0]</entry>
                 <entry>Handled like a <link
                 linkend="chpt.midi.note"><abbrev>MIDI</abbrev> NOTE-ON</link>
                 event without triggering <link
                 linkend="chpt.midi.controlling"><abbrev>Actions</abbrev></link>.
                 The first parameter <emphasis>f</emphasis> determines the pitch
                 of the note and the second <emphasis>f</emphasis> its
                 velocity.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">NOTE_OFF</emphasis>/</entry>
                 <entry>f</entry>
                 <entry>[36,127]</entry>
                 <entry>Handled like a <link
                 linkend="chpt.midi.note"><abbrev>MIDI</abbrev> NOTE-OFF</link>
                 event. The provided parameter <emphasis>f</emphasis> determines
                 the pitch of the note.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">SONG_EDITOR_TOGGLE_GRID_CELL</emphasis>/</entry>
                 <entry>ff</entry>
                 <entry></entry>
                 <entry>Toggles a pattern in the pattern grid of the <link linkend="chpt.song_editor">Song Editor</link>. The first argument will be used as column and the second as row.</entry>
               </row>
               <row id="chpt.osc.command.load_drumkit">
                 <entry>/Hydrogen/<emphasis role="bold">LOAD_DRUMKIT</emphasis>/</entry>
                 <entry>s,sf</entry>
                 <entry></entry>
                 <entry>Loads a drumkit into the current song. <emphasis>s</emphasis> can be either the name of a drumkit already present in the <link linkend="chpt.sound_library">Sound Library Editor</link> or an absolute path pointing to an extracted drumkit folder (containing both <filename>drumkit.xml</filename> file as well as all required samples). The second argument is optional and specifies whether (<option>0</option>) or not (any other value) instruments of the old kit should be kept in case newly loaded one has less and there are note present for that particular instrument in a pattern.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">EXTRACT_DRUMKIT</emphasis>/</entry>
                 <entry>s,ss</entry>
                 <entry></entry>
                 <entry>Inflates a <link linkend="chpt.file_types.h2drumkit">compressed drumkit</link> found at the absolute path <emphasis>s</emphasis> (first argument). The second argument specifies the target path to extract the kit to. It's optional and if omitted the kit will be extracted into Hydrogen's user drumkit folder.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">VALIDATE_DRUMKIT</emphasis>/</entry>
                 <entry>s,sf</entry>
                 <entry></entry>
                 <entry>Validates a <link linkend="chpt.file_types.h2drumkit">compressed</link> or inflated drumkit found at the absolute path <emphasis>s</emphasis> against the current drumkit format. When setting the second arguent to <option>1</option> the kit will be validated against all former drumkit definitions as well.</entry>
               </row>
               <row>
                 <entry>/Hydrogen/<emphasis role="bold">UPGRADE_DRUMKIT</emphasis>/</entry>
                 <entry>s,ss</entry>
                 <entry></entry>
                 <entry>Upgrades a <link linkend="chpt.file_types.h2drumkit">compressed</link> or inflated drumkit found at the absolute path <emphasis>s</emphasis> to the latest drumkit format. The second argument specifies the target path to upgraded kit will be stored in. It's optional and if omitted the kit will be upgraded inplace.</entry>
               </row>
             </tbody>
           </tgroup>
         </table>
       </sect2>
	 </sect1>
   </chapter>
 </part>

 <part id="part.demos">
   <title>Examples</title>

   <chapter id="chpt.create_song">
     <title>A New Song</title>
     
     <para>
       This chapter provides a quick-and-dirty walkthrough to Hydrogen. Refer to the
       tutorials and the technical <xref linkend="part.using_hydrogen" /> of this document for a more detailed overview.
     </para>
     
     <sect1 id="sect.song_vs_pattern">
       <title>Song Mode and Pattern Mode</title>

       <para>Hydrogen has two main modes: <link linkend="chpt.song_editor.editor_modes.pattern_mode">Pattern mode</link> and <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>. When
       <emphasis>Pattern Mode</emphasis> is activated the current pattern is continuously repeated.
       This mode is very well suited to tweak your pattern until it's just right, since the 
       pattern you are working on is constantly repeated. This way you can immediately 
       hear the changes you have made. In <emphasis>Song Mode</emphasis> the whole song is played.  
       This is useful when putting together the patterns to create the structure of the song.</para>
     </sect1>

     <sect1 id="sect.create_pattern">
       <title>A New Pattern</title>
       <para>We'll start from the empty song with an empty pattern created when
       Hydrogen starts up: <emphasis>Pattern Mode</emphasis> should be selected by default. Now
       let's click on the
       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey play and pause button containing two vertical black lines
             (left) and a black triangle (right) pointing to the right.
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/playerControlPlayButton.png" format="PNG"/>
         </imageobject>
       </inlinemediaobject>
       button in the <link linkend="sect.main_toolbar.transport_control">Main Toolbar</link>, and while the pattern is playing
       let's add notes by <emphasis>left-clicking</emphasis> in the grid of the <link linkend="chpt.pattern_editor">Pattern Editor</link> 
       (see <xref linkend="fig.pattern_editor.2"/>). Adjust the <link linkend="chpt.pattern_editor.controls.res">grid resolution</link> and <link linkend="sect.main_toolbar.bpm_control_and_metronome">tempo</link> if needed.

       <note>
	     <para>
           Remember some constraints of the grid: if you are
           working with a resolution of <option>1/16</option>, you can't go back to <option>1/8</option> and remove a
           16th note; same thing happens if you are working with a resolution of
           <option>1/8</option> and you try to insert a note in the middle of two bars (looking for
           a 16 bars precision): they will be placed on the previous or on the
           following 8th bar (unless you choose <option>off</option> from the Grid Resolution combo box in which case
           you're free to place notes wherever you prefer). <emphasis role="bold">Be
           sure to select the correct pattern in the <link linkend="chpt.song_editor.sidebar">Sidebar</link> of the Song Editor before adding notes
           in the Pattern Editor!</emphasis>
         </para>
       </note>
       </para>

       <figure id="fig.pattern_editor.2">
         <title>The Pattern Editor</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/PatternEditor.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>
     </sect1>

     <sect1 id="sect.create_sequence">
       <title>A New Sequence</title>

       <para>Once patterns are created (<xref linkend="fig.insert_patterns"/>), we
       can copy/paste/delete them using the <link linkend="chpt.song_editor.editor_modes.select">Select Mode</link>.
       </para>

       <figure id="fig.insert_patterns">
         <title>Inserting Patterns in the Song Sequence</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/SongEditor.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>

     </sect1>
     <sect1 id="sect.create_song.adjust_mixer">
       <title>Adjust from the Mixer</title>

       <para>Of course we can always use the <link linkend="chpt.mixer">Mixer</link> window, either when creating
       or playing patterns.</para>

       <para>The Mixer (see <xref linkend="fig.mixer.2"/>) is made of a number
       independent <link linkend="chpt.mixer.channel_strips">Instrument Channel Strips</link>, each of these is bound to an instrument, plus a
       <link linkend="chpt.mixer.master_fader_strip">Master Fader Strip</link> and a 
       <inlinemediaobject>
         <textobject>
           <phrase>
             Blue button containing the black characters "FX".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/mixerShowFXButton.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>
       button to show and hide the 
       <link linkend="sect.fx_rack_LADSPA">FX Plugin Rack</link>.
       Every line features 3 buttons (

       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button with a filled black triangle pointing to the right.
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_play_on_mixer.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>

       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing a black "S".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_solo_on.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>

       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing a black "M".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_mute_on.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>

       ), current maximum peak, FX volume control knobs, volume fader, and name of the track. Clicking on

       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing a black "S".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_solo_on.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>

       will play the selected instrument, cutting the others. The Mute button

       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing a black "M".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/btn_mute_on.png" format="PNG" />
         </imageobject>
       </inlinemediaobject>

       , simply <link linkend="def.mute">mute</link> <emphasis>that</emphasis> instrument. The maximum peak
       indicates the maximum volume reached from the instrument.   The peak must
       be in a range of <option>0.0</option> and <option>1.0</option> (in <xref linkend="fig.mixer.2"/> you can
       see a few volumes too loud). For a full description of the Mixer and its elements please see <xref linkend="chpt.mixer" />.

       <tip>
	     <para>
	       Peaks outside that range will get distorted 
           (especially with <abbrev>OSS</abbrev> audio driver). Keep an eye on each VU meter and
           if distortion appears, turn the volume down for that instrument.
         </para>
       </tip>
       </para>

       <figure id="fig.mixer.2">
         <title>The Mixer</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="generated_en/Mixer.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>
     </sect1>
   </chapter>
   <chapter id="chpt.examples.drumkit">
	 <title>Create a New Drumkit</title>
     
     <sect1 id="chpt.examples.drumkit.new_kit">
       <title>Creating a New Drumkit</title>
       <para>In this chapter we will show you how to create a complete drumkit. Be sure to have a look at the <link linkend="chpt.overview.drumkits">conceptional design of a drumkit</link> first.
       Keeping this in mind
       we will use a top-down approach, so we will start at the Drumkit level and work our way 
       down to the <link linkend="def.sample">samples</link>.</para> 
       
       <para>Creating a <link linkend="sect.main_menu.drumkits.new">new drumkit</link> with Hydrogen is done with the <link linkend="chpt.instrument_editor">Instrument
       Editor</link>.  You can load samples, set envelope
       parameters, set the gain, and other advanced features like mute groups, a low-pass resonance filter, and pitch randomization.</para>

       <tip>
         <para>
           Instead of creating your own drumkit, you can also <link linkend="sect.main_menu.drumkits.open">open</link> or <link linkend="sect.main_form.online_import_drumkit">download</link> an existing one.
         </para>
       </tip>

       <para>Let's make a brand new drum kit:</para>
       <procedure>
         <step><para>in the <link linkend="chpt.main_menu">Main Menu</link> select
         <menuchoice>
           <guimenu>Drumkits</guimenu>
           <guimenuitem>New</guimenuitem>
           </menuchoice>. This will give you a single blank instruments. To add more instruments,
           select
           <menuchoice>
             <guimenu>Instruments</guimenu>
             <guimenuitem>Add instrument</guimenuitem>
             </menuchoice> and to delete one, <emphasis>right-click</emphasis> a instrument and select
             <emphasis>Delete Instrument</emphasis>.  
           </para>
         </step>


         <step>
           <para>Select an instrument to start editing it.  This is done by
           <emphasis>left-clicking</emphasis> on the name of the instrument in the <link linkend="chpt.pattern_editor.sidebar">Sidebar</link>.  You will notice that the name of the instrument in the
           Instrument Editor matches the one that you clicked.</para>
         </step>
         
         <step>
           <para>Once you have your drumkit working the way you want, select

           <menuchoice>
             <guimenuitem>Drumkits</guimenuitem>
             <guimenuitem>Save As</guimenuitem>
           </menuchoice>

           .  You will be prompted for the name of the kit to save.  If you wish to
           <emphasis>overwrite</emphasis> an existing kit, you will need to type in
           the same name as the kit that you want to replace.</para>
         </step>

         <step>
           <para>Drumkits are automatically stored in the <filename
           class="directory">data</filename> directory (i.e. <filename
           class="directory">$HOME/.hydrogen/data/drumkits</filename>).</para>
         </step>

         <step>
           <para>In order to share your drumkit with others, you have to export it using

           <menuchoice>
             <guimenuitem>Drumkits</guimenuitem>
             <guimenuitem>Export</guimenuitem>
           </menuchoice>

           from the <link linkend="chpt.main_menu">Main Menu</link>.  Select the drum kit that you wish to export, and give it
           a file name to save it to.</para>
         </step>
       </procedure>

     </sect1>

     <sect1 id="chpt.examples.drumkit.new_instrument">
       <title>Creating a New Instrument</title>
       
       <para>For each instrument in a drum kit, you can load several <link linkend="def.sample">samples</link>
       and set different synthesizer parameters.  This section will step you
       through how to create a new instrument and load the samples. For details about the individual parameters please refer to <xref linkend="chpt.instrument_editor.general" />.</para>

       <para>To begin creating an instrument, select
       <menuchoice>
         <guimenu>Instruments</guimenu>
         <guimenuitem>Add instrument</guimenuitem>
         </menuchoice>.  This will give you a blank
       instrument to start from.</para>

       <para>Now, you need two samples (see <link
       linkend="def.sample">Sample</link> for a list of supported formats).
       Hydrogen provides several in the <filename
       class="directory">data/drumkits</filename> folder in the Hydrogen data
       directory (usually <filename
       role="directory">$HOME/.hydrogen/data/</filename>).</para>

       <para>In the Instrument Editor, click on <link linkend="chpt.instrument_editor.layers">Layers</link>.
       You can layer several samples into the instrument.  Which one is played
       depends on the <link linkend="def.velocity">velocity</link> of the incoming note.  Click 
       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing the black characters "LOAD LAYER".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/loadLayer_off.png" format="PNG"/>
         </imageobject>
         </inlinemediaobject> and point the <emphasis>Audio File Browser</emphasis> to
         your sample.
       </para>
       <note>
         <para>
           The <emphasis>Audio File Browser</emphasis> will
           allow you to preview the sample before you load it.  It will also allow
           you to load more than one sample at a time.  But for now, only load
           one.
         </para>
       </note>

       <para>After you load the sample, you'll see that there is now a
       <guilabel>1</guilabel> at the top, and the topmost rectangle has turned
       light blue.  To load a second sample, click the slot just below it, and
       then click
       <inlinemediaobject>
         <textobject>
           <phrase>
             Grey button containing the black characters "LOAD LAYER".
           </phrase>
         </textobject>
         <imageobject>
           <imagedata fileref="generated_en/loadLayer_off.png" format="PNG"/>
         </imageobject>
       </inlinemediaobject>
       to bring in another sample.
       </para>

       <para>After bringing in both samples, you'll probably notice that only
       the <emphasis>first</emphasis> sample is being played whenever you
       trigger the instrument.  This is because you need to set the
       <emphasis>velocity</emphasis> ranges for the layers.  Move your mouse to
       the sides of the light blue rectangles and you see that you get a
       <emphasis>left-right drag</emphasis> cursor.  Now <emphasis>drag</emphasis> the sample to the left or right (like
       a curtain).  You will now see Layer 2 appear.</para>

       <para>The velocity setting for the layer is 0-velocity on the left, and
       full velocity on the right.  Set up Layer 1 to sound for soft notes, and
       Layer 2 to sound for hard notes, i.e. Layer 1 on the left and Layer 2
       on the right (see <link linkend="chpt.instrument_editor.layers.sample_selection">Sample Selection</link> for further info).</para>

       <para>Now, in the <link linkend="chpt.pattern_editor.drumkit">Drumkit Editor</link>, set up a simple pattern that plays this
       instrument.  Adjust the velocity settings on each note in the <link linkend="chpt.pattern_editor.note_properties">Note Properties Editor</link> so that you can
       get the different samples to sound.  Now, set the playback to <link linkend="sect.main_toolbar.transport_control">loop</link> and
       notice how your different samples are getting triggered. To learn
       about editing a pattern, see <xref
       linkend="chpt.pattern_editor"/>.</para>

       <para>For each layer, you can set the <guibutton>Gain</guibutton> and
       the <guibutton>Pitch</guibutton>.  The pitch also has a
       <guibutton>Fine</guibutton> adjustment.</para>

       <para>Use the <link linkend="chpt.instrument_editor.gain_and_mute_group">Gain</link> adjustment to control how loud
       the sample will be played. This is necessary because it's extremely
       difficult to get a set of samples that all sound at about the same
       volume.  By adjusting here, the samples that were recorded too quietly
       can be turned up to match your loud samples (that had to be turned
       down).
       </para>

       <warning>
         <para>It is very easy to set the <guibutton>Gain</guibutton> too high,
         causing your sample to <link linkend="def.clipping">clip</link>.  Remember to test the gain with
         full-velocity using the
         <inlinemediaobject>
           <textobject>
             <phrase>
               Grey button with a filled black triangle pointing to the right.
             </phrase>
           </textobject>
           <imageobject>
             <imagedata fileref="generated_en/btn_play_on_mixer.png" format="PNG"/>
           </imageobject>
         </inlinemediaobject>
         button in the corresponding Instrument Channel Strip.  If you clip your signal here, it will only get
         worse as Hydrogen processes it.</para>
       </warning>

       <para>The pitch of the sample can be modified with the pitch controls.
       The <guibutton>Pitch</guibutton> knob adjust the pitch in musical
       half-steps.  (So, <option>-12</option> is down 1 octave).  The pitch on the right adjusts
       the pitch &#177;50 cents.  (One half-step is 100 cents.)</para>

       <note>
         <para>The pitch is adjusted by playing the sample back faster or
         slower.  This is called the Doppler Effect.  So, if you have a
         1-second sample that you turn down <option>12</option> (1 octave), your sample will
         only last for 0.5-seconds.  If you do not want this to happen you should
         use Rubber Band instead (see <xref linkend="chpt.sample_editor.pitch"/>)</para>
       </note>

       <para>You can hear the sample in a layer by clicking the layer id (just 
       below the 'General' and 'Layers' buttons).</para>
     </sect1>

     <sect1 id="chpt.instrument_editor.tips">
       <title>Tips on Editing Instruments</title>

       <para>With all of the different parameters available to tweak, it can be
       difficult to set up something that sounds nice when you're done.  Here are 
       a few tips on setting up an instrument:</para>

       <para><emphasis role="bold">Turn down the gain.</emphasis> Every gain
       knob (i.e. an amplifier), this is a <emphasis>gain stage</emphasis>.  
       With every gain stage you have, it's
       easy to overdrive your signal - which means the signal gets
       distorted by <link linkend="def.clipping">clipping</link>.  In addition, if you have two samples that, by
       themselves, peg your meters - what do you think happens when you
       combine them?  That's right, you overdrive the signal again.</para>

       <para>If things sound bad and distorted, start by turning down the gain
       setting on the layer... especially if it's larger than 1.0.  Then turn
       down the instrument gain.  Then any gain on a <abbrev>LADSPA</abbrev> effect.  Then the
       fader on the Mixer.  Then the master output fader.</para>

       <para><emphasis role="bold">Test samples at full velocity.</emphasis>
       Your sample will be played louder if the velocity is higher.  So, if you
       set everything to sound nice and full with velocity at 0.7, what will
       happen when you get a full velocity of 1.0?  (<emphasis>Hint:
       <link linkend="def.clipping">clipping</link>.</emphasis>)</para>

       <para><emphasis role="bold">Try to use samples that are -6 dB
       max.</emphasis> Visually, this means samples that peak at only
       1/2 of full scale.  Otherwise, turn your layer gain to about
       .5.</para>

       <para><emphasis role="bold">Remove all DC offsets from the
       sample.</emphasis> In a sample editor, there is usually a line down the
       center of your sample's waveform.  This is the zero-line.  The beginning
       of your sample should be on this line.  The end of your sample should
       also be on this line.  However, if your signal is a little above or a
       little below this line, you will hear a click at the beginning and the
       end of your sample whenever it is played.  If your sample editor doesn't
       provide any tools to fix a DC offset problem, you can eliminate the
       noise by putting a slight fade-in/out at the ends of your sample.</para>

       <para><emphasis role="bold">The ADSR will not be longer than your
       sample.</emphasis> If you have a short sample, it doesn't matter how
       long you set the attack and delay - the sample will stop playing
       at the end.</para>

       <para><emphasis role="bold">Things change with the sample
       rate.</emphasis> If you have a really nice setup with all your
       parameters painstakingly tweaked... things <emphasis>will</emphasis>
       change if you change the sample rate of your audio card.  Many of
       Hydrogen's internal settings and parameters are based on how many
       samples go by, not on how many seconds go by.  The sorts of things
       that change are: anything time-base (like attack and release) and
       anything frequency based (like the cutoff frequency).</para>

       <para>
         Typical samples that are used in Hydrogen are: the sound of a single
         drum hit, the sound of a single cymbal hit, the sound of a single
         cowbell hit.  Whenever you put a note in the pattern (or play a note
         using <abbrev>MIDI</abbrev>), Hydrogen will play whatever sound you have loaded.  So,
         to put together a drum kit you need to gather short recordings of the
         bass drum, each tom, each cymbal, the high hat open, the high hat
         closed, the snare drum (snare on), the snare drum (snare off), rim
         shots, etc.
       </para>

       <para>
         However, there are no rules about what a sample can be.  It's not
         uncommon to use Hydrogen to trigger non-drum sounds like: audio clips
         of people talking, a clip from a song, sound effects, audio clips from
         movies, and famous people speaking.  Be creative!
       </para>

     </sect1>
   </chapter>
 </part>
 <part id="appendix">
   <title>Appendix</title>
   
   <chapter id="chpt.license" xreflabel="Licensing">
     <title>Licensing</title>
     <warning>
       <para>
         No one of us is a lawyer and all information found in this section should be taken with a grain of salt and come with no warranty. But we try our best to condense information we found online.
       </para>
     </warning>

     <para>
       When <link linkend="sect.main_form.export_song">exporting a song</link> or <link linkend="sect.main_menu.drumkits.save_as">saving</link> or <link linkend="sect.main_form.export_drumkit">exporting</link> a drumkit you are reusing and/or redistributing licensed sound samples. Thus you are legally obliged to comply with every license hold by the samples you used.
     </para>
     <para>
       In this chapter we cover how Hydrogen can help you handle and manage the licenses involved and what the most common ones do imply.
     </para>

     <note>
	   <para>
	     Our custom data types <link linkend="chpt.file_types.h2pattern">.h2pattern</link>, <link linkend="chpt.file_types.h2song">.h2song</link>, and <link linkend="chpt.file_types.h2playlist">.h2playlist</link> do not contain any samples and are not affected by the issues described in this chapter.
       </para>
     </note>

     <warning>
       <para>
         If the exact license is not available for a drumkit, do <emphasis role="bold">not</emphasis> assume that it is a <ulink url="https://creativecommons.org/about/cclicenses/">Creative Commons (CC)</ulink> or
         other open and free license.
       </para>
     </warning>

     <sect1 id="chpt.license.parsing">
<title>License Parsing</title>

<para>
  Hydrogen does display some info dialogs in case any of the used samples holds a copyleft license, like <xref linkend="chpt.license.common_licenses.CC_BY_SA"/> or <xref linkend="chpt.license.common_licenses.GPL"/>, holds one that require an attribution of the copyright holder (as CC BY* licenses do), or you are mixing different licenses during drumkit saving or export. But all this is only possible if the licenses of the involved drumkits are correctly parsed (and are one of the supported <link linkend="chpt.license.common_licenses">common licenses</link>).
</para>
<para>
  You can access and alter the license of the drumkit used in the current song via <link linkend="sect.main_menu.drumkits.properties">Drumkits > Properties</link> in the main menu or the license of a stock kit via the <link linkend="chpt.sound_library.drumkits">Sound Library</link>. In addition, you can view all licenses of the contained samples which is especially helpful when mixing instruments of different drumkits in the current song.
</para>

<figure id="fig.license.parsing.drumkit.properties">
<title>Dialog to view and alter the Properties of a Drumkit</title>
<mediaobject>
  <imageobject>
    <imagedata fileref="generated_en/soundLibraryPropertiesDialog.png" format="PNG" />
</imageobject>
</mediaobject>
</figure>

<note>
  <para>
    Samples loaded directly into Hydrogen using the <link linkend="chpt.instrument_editor.layers.layers">Layer section of the Instrument Editor</link> are not associated to any drumkit until you <link linkend="sect.main_menu.drumkits.save">save</link> it and will be handled as if they are unlicensed. Please take extra care of checking which licenses they are distributed with and what implication their presence has for your song/drumkit.
</para>
</note>
</sect1>

<sect1 id="chpt.license.common_licenses">
<title>Common Licenses</title>

<para>
  By default all copyrights of your creative work belongs to you - its creator. But you are obliged to comply with the licenses of the samples you used to create it. In this section you find a list and some short description of the licenses most commonly encountered in Hydrogen drumkits.
</para>
<para>
  Also, you are free to abstain from some or all rights by licensing your work with e.g. one of the licenses provided by Creative Commons (CC). This allows other people to reuse it more easily and in a legally secure way and helps the audio community to prosper.
</para>

<table frame='all'>
<title>Common Licenses</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
  <colspec colname='cName'/>
  <colspec colname='cDescription'/>
  <thead>
    <row>
<entry>Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
  <row id="chpt.license.common_licenses.CC0" xreflabel="CC0">
<entry><ulink url="https://creativecommons.org/publicdomain/zero/1.0/">CC0</ulink></entry>
<entry>The creator choose to give up her copyright and you are free to use, modify, distribute etc. the samples.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY" xreflabel="CC BY">
<entry><ulink url="https://creativecommons.org/licenses/by/4.0/">CC BY</ulink></entry>
<entry>You are free to use, modify, distribute etc. the samples but you are obliged to give attribution to the creator. This can be done in e.g. the info property of the new drumkit or in the liner notes of the song you created by reusing the samples.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY_NC" xreflabel="CC BY-NC">
<entry><ulink url="https://creativecommons.org/licenses/by-nc/4.0/">CC BY-NC</ulink></entry>
<entry>Similar to <xref linkend="chpt.license.common_licenses.CC_BY"/> but you are in addition only allowed to use the result for noncommercial purposes.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY_SA" xreflabel="CC BY-SA">
<entry><ulink url="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA</ulink></entry>
<entry>Similar to <xref linkend="chpt.license.common_licenses.CC_BY"/> but you are obliged to license your work as CC BY-SA as well. This means <emphasis>you have to give the general public permission to modify, redistribute, reuse, and sell it without being able to require them to give royalty to you</emphasis>.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY_NC_SA" xreflabel="CC BY-NC-SA">
<entry><ulink url="https://creativecommons.org/licenses/by-nc-sa/4.0/">CC BY-NC-SA</ulink></entry>
<entry>Similar to <xref linkend="chpt.license.common_licenses.CC_BY_SA"/> but you are in addition only allowed to use the result for noncommercial purposes.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY_ND" xreflabel="CC BY-ND">
<entry><ulink url="https://creativecommons.org/licenses/by-nd/4.0/">CC BY-ND</ulink></entry>
<entry>Similar to <xref linkend="chpt.license.common_licenses.CC_BY"/> but you are not allowed to alter the material and can only use or distribute them in unadapted form.</entry>
</row>
<row id="chpt.license.common_licenses.CC_BY_NC_ND" xreflabel="CC BY-NC-ND">
<entry><ulink url="https://creativecommons.org/licenses/by-nc-nd/4.0/">CC BY-NC-ND</ulink></entry>
<entry>Similar to <xref linkend="chpt.license.common_licenses.CC_BY_ND"/> but you are in addition only allowed to use the result for noncommercial purposes.</entry>
</row>
<row id="chpt.license.common_licenses.GPL" xreflabel="GPL">
<entry><ulink url="https://www.gnu.org/licenses/gpl-3.0.html">GPL</ulink></entry>
<entry>License similar to <xref linkend="chpt.license.common_licenses.CC_BY_SA"/> but targeted on usage with software instead of creative content. It is discouraged to license your newly created drumkit using this license since it's not clear whether it actually can be legally applied to audio samples. Instead, it's recommanded to stick to the Creative Commons (CC) ones covered above. However, most of the drumkits available in Hydrogen <emphasis>are</emphasis> licensed as GPL and require you to adopt this license too in case you reuse their samples. It's a bit of an unpleasant situation but grew naturally. Most importantly, <emphasis>this license also obliges you to make your product (drumkit/music) available for free!</emphasis></entry>
</row>
<row id="chpt.license.common_licenses.AllRightsReserved" xreflabel="All rights reserved">
<entry>All rights reserved</entry>
<entry>You are not allowed to modify, reuse, or distribute the samples without asking the copyright holder for permission first.</entry>
</row>
</tbody>
</tgroup>
</table>
</sect1>
</chapter>

<chapter id="chpt.file_types">
  <title>Used File Types</title>

  <para>Before working with Hydrogen, please familiarize with these
file types:</para>

<itemizedlist>
  <listitem id="chpt.file_types.h2pattern">
    <para><emphasis role="bold">*.h2pattern</emphasis>: <abbrev>XML</abbrev> file
    describing a single pattern. Patterns are group of beats and are
managed in the <link linkend="chpt.pattern_editor">Pattern Editor</link>.</para>
</listitem>
<listitem id="chpt.file_types.h2song">
  <para><emphasis role="bold">*.h2song</emphasis>: <abbrev>XML</abbrev> file describing
  the whole song (or sequence). Songs are groups of patterns managed using the <link linkend="chpt.song_editor">Song Editor</link>, groups of instruments comprising the current drumkit and managed via the <link linkend="chpt.instrument_editor">Instrument Editor</link>, as well as all states not already covered by the <link linkend="chpt.preferences">Preferences</link>.
</para>
</listitem>
<listitem id="chpt.file_types.h2playlist">
  <para><emphasis role="bold">*.h2playlist</emphasis>: <abbrev>XML</abbrev> file
describing a playlist. A Playlist is a (ordered) group of songs.</para>
</listitem>
<listitem id="chpt.file_types.h2drumkit">
  <para><emphasis role="bold">*.h2drumkit</emphasis>: a compressed folder containing all sound samples composing a drumkit and the
description <abbrev>XML</abbrev> file <filename>drumkit.xml</filename> storing the kit's structure and parameters.</para>
</listitem>
<listitem id="chpt.file_types.h2theme">
<para><emphasis role="bold">*.h2theme</emphasis>: <abbrev>XML</abbrev> file describing all preferences available in the <link linkend="chpt.preferences.appearance_tab">Appearance</link> tab of the <link linkend="chpt.preferences">Preferences</link>.</para>
</listitem>
</itemizedlist>
</chapter>

<chapter id="chap.shortcuts">
<title>Shortcut Lists</title>
<table frame='all' id='sect.shortcut.table'>
<title>Shortcut Table</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
  <colspec colname='cShortcut'/>
  <colspec colname='cDescription'/>
  <thead>
    <row>
<entry>Shortcut</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
  <row>
<entry><keycap>Ctrl</keycap> + <keycap>N</keycap></entry>
<entry>New Project</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>O</keycap></entry>
<entry>Open File</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>D</keycap></entry>
<entry>Open Demo</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>S</keycap></entry>
<entry>Save Song</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>Shift</keycap> + <keycap>S</keycap></entry>
<entry>Save Song as</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>P</keycap></entry>
<entry>Export Pattern as</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>M</keycap></entry>
<entry>Export MIDI file</entry>
</row>
<row>
  <entry><keycap>Ctrl</keycap> + <keycap>E</keycap></entry>
  <entry>Export Song (see <xref linkend="sect.main_form.export_song"/>)</entry>
</row>
<row>
  <entry><keycap>Ctrl</keycap> + <keycap>L</keycap></entry>
  <entry>Export LilyPond file</entry>
</row>
<row>
  <entry><keycap>Ctrl</keycap> + <keycap>Q</keycap></entry>
<entry>Quit Hydrogen</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>Z</keycap></entry>
<entry>Undo an action</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>Shift</keycap> + <keycap>Z</keycap></entry>
<entry>Redo an action</entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>D</keycap></entry>
<entry>Show <link linkend="chpt.director">Director</link></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>M</keycap></entry>
<entry>Show <link linkend="chpt.mixer">Mixer</link></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>I</keycap></entry>
<entry>Show <link linkend="chpt.sound_library">Instrument Rack</link></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>A</keycap></entry>
<entry>Show <link linkend="sect.song_editor.automation_path">Automation Path</link></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>F</keycap></entry>
<entry>Toggle fullscreen mode</entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>I</keycap></entry>
<entry>Set <link linkend="chpt.midi.note.input_mode">Input Mode</link> to <option>Instrument</option></entry>
</row>
<row>
<entry><keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>D</keycap></entry>
<entry>Set <link linkend="chpt.midi.note.input_mode">Input Mode</link> to <option>Drumkit</option></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>P</keycap></entry>
<entry>Show <link linkend="chpt.preferences">Preferences</link></entry>
</row>
<row>
<entry><keycap>Alt</keycap> + <keycap>?</keycap></entry>
<entry>Show Manual</entry>
</row>
<row>
<entry><keycap>Backspace</keycap></entry>
<entry>Restart song or pattern from the beginning</entry>
</row>
<row id="chap.shortcuts.space">
<entry><keycap>Space</keycap></entry>
<entry>Play / Pause</entry>
</row>
<row id="chap.shortcuts.ctrl_space">
<entry><keycap>Ctrl</keycap> + <keycap>Space</keycap></entry>
<entry>Starts playback at the current cursor position. If playback is already rolling, it will relocate to the cursor position without pausing or stopping playback. Note that on MacOS this shortcut is bound to <keycap>Alt</keycap> + <keycap>Space</keycap>.</entry>
</row>
<row>
<entry><keycap>,</keycap></entry>
<entry>Use the <link linkend="sect.main_toolbar.tap_tempo_beat_counter.beat_counter">Beat Counter</link></entry>
</row>
<row>
<entry><keycap>\</keycap></entry>
<entry>Use <link linkend="sect.main_toolbar.tap_tempo_beat_counter.tap_tempo">Tap Tempo</link></entry>
</row>
<row>
<entry><keycap>+</keycap></entry>
<entry>Increase tempo by 0.1 BPM</entry>
</row>
<row>
  <entry><keycap>-</keycap></entry>
<entry>Decrease tempo by 0.1 BPM</entry>
</row>
<row id="chap.shortcuts.f5">
<entry><keycap>F5</keycap></entry>
<entry>Jump to previous song in <link linkend="chpt.playlist_editor">playlist</link></entry>
</row>
<row id="chap.shortcuts.f6">
<entry><keycap>F6</keycap></entry>
<entry>Jump to next song in <link linkend="chpt.playlist_editor">playlist</link></entry>
</row>
<row>
<entry><keycap>F9</keycap></entry>
<entry>Jump to previous bar in the song</entry>
</row>
<row>
<entry><keycap>F10</keycap></entry>
<entry>Jump to next bar in the song</entry>
</row>
<row>
<entry><keycap>F12</keycap></entry>
<entry>Panic button (stops the song and mutes all
playing sounds) </entry>
</row>
</tbody>
</tgroup>
</table>    
</chapter>

<glossary id="glossary">
<title>Glossary</title>

<para>This is a glossary of general terms encountered when using Hydrogen,
synthesizers, drums, or samplers. The definitions here provide more
detail and explanation than the simplified ones in the text. For
example, the text of the manual would have you believe that an ADSR is
the only kind of envelope generator and could only ever control the
volume. While the simplified definitions help new users start using
Hydrogen quickly, they can lack the nuances presented here.</para>

<!--  ...  -->

<!--   A   -->

<glossentry id="def.adsr">
<glossterm>ADSR</glossterm>
<glossdef>
  <para>A type of envelope generator that allows you to control the
  <link linkend="def.attack">Attack</link>,
  <link linkend="def.decay">Decay</link>,
  <link linkend="def.sustain">Sustain</link>, and
  <link linkend="def.release">Release</link> parameters.
  Generally, the
  parameters are proportional to
the <link linkend="def.velocity">velocity</link>.</para>
<para>
  After you trigger
  a note, Hydrogen will start the <link linkend="def.attack">attack</link> phase in which the volume of the note is increase from 0 to its full <link linkend="def.velocity">velocity</link>.
  After reaching full velocity, the volume will <link linkend="def.decay">decay</link> until it reaches the
  <link linkend="def.sustain">sustain</link> level. When the note is
  <link linkend="def.release">released</link>, Hydrogen reduces the volume from the
  sustain level back down to 0.
</para>

<para>In Hydrogen, the ADSR envelope generator only controls the volume
(attenuation).</para>

<para>Read more about this in the Wikipedia
Article <ulink url="http://en.wikipedia.org/wiki/ADSR_envelope">ADSR
Envelope</ulink></para>

<glossseealso otherterm="def.envelopegenerator"/>
<glossseealso otherterm="def.attack"/>
<glossseealso otherterm="def.decay"/>
<glossseealso otherterm="def.sustain"/>
<glossseealso otherterm="def.release"/>
</glossdef>
</glossentry>

<glossentry id="def.attack">
<glossterm>Attack</glossterm>
<glossdef>
  <para>This is the first phase of an <link linkend="def.adsr">ADSR</link> envelope. It represents the amount
  of <emphasis>time</emphasis> to increase the volume of a note from
0 (triggering) to full <link linkend="def.velocity">velocity</link>.</para>

<glossseealso otherterm="def.adsr"/>
</glossdef>
</glossentry>

<glossentry id="def.attenuation">
<glossterm>Attenuation</glossterm>
<glossdef>
  <para>In filters and mixers, this the amount that a signal is reduced
(volume).</para>

<glossseealso otherterm="def.rolloff"/>
</glossdef>
</glossentry>

<!--   B   -->

<glossentry id="def.bandpassfilter">
<glossterm>Band-Pass Filter</glossterm>
<glossdef>
  <para>A filter that preserves a certain band of frequencies, and
  attenuates (silences) all others.  This is often done by combining a
high-pass and a low-pass filter.</para>

<glossseealso otherterm="def.filter"/>
<glossseealso otherterm="def.highpassfilter"/>
<glossseealso otherterm="def.lowpassfilter"/>
</glossdef>
</glossentry>

<!--   C   -->

<glossentry id="def.clipping">
<glossterm>Clipping</glossterm>
<glossdef>
  <para>A phenomenon that happens to a signal when its amplitude is too large
  for whatever is receiving it.  The peaks of the signal (which are
  normally smooth curves) get cut off straight at the max volume
(clipped).  This distorts the sound and is usually undesirable.</para>

<para>An example of clipping is when you play music louder than your
speaker can handle.  Parts of the music sound harsh and fuzzy.</para>
</glossdef>
</glossentry>

<glossentry id="def.component">
<glossterm>Component</glossterm>
<glossdef>
  <para>
	A component is a part of Hydrogen's instrument model.
    Instrument consist of one or more components, and each component consists of one or more layers.
</para>

<para>To make an example: A snare could have two components.
One component includes sounds from the top side of the snare drum, and the other component includes
the sounds from the bottom side of the snare drum (where the snare wires are fitted).
Each component can consist of several layers (snare drum hits with different velocities).
Now you can adjust the volume of the two components to build your ideal drum sound.
If you want more of the attack, you can put in more of the "top head" component.
If you want more of the snare wires, you put in more of the bottom component.

<note>
  <para>
	Components will be created for all instruments. So, even if you just want to have two of them in the snare you will automatically have two components in all other instruments. If you thus remove an empty component in one instrument, you will remove it for all other instruments - even if they are non-empty - too.
</para>
<para>
  In addition, all <link linkend="def.layer">layers</link> belonging to the same component do share a common volume fader in the <link linkend="chpt.mixer.component_strips">Component Channel Strips</link> in the Mixer.
</para>
</note>
</para>

</glossdef>
</glossentry>
<glossentry id="def.cutoff">
<glossterm>Cutoff Frequency</glossterm>
<glossdef>
  <para>On high-pass and low-pass filters, this is the frequency that
  divides between those that pass, and those that are attenuated
  (silenced).  In a high-pass resonance filter, or a low-pass resonance
filter, the cutoff is also the frequency zone that gets boosted.</para>

<para>For example, if you have a low-pass filter and you set the cutoff
frequency high (i.e. 20kHz)... the filter will not affect the sound.
All the audible frequencies will pass through undisturbed.  As you lower
the cutoff frequency to something like 40 Hz (the low string on a bass
guitar), it sounds like someone is putting a blanket over the speaker.
The higher frequencies are being attenuated above 30 Hz.</para>

<glossseealso otherterm="def.filter"/>
<glossseealso otherterm="def.highpassfilter"/>
<glossseealso otherterm="def.lowpassfilter"/>
<glossseealso otherterm="def.resonancefilter"/>
</glossdef>
</glossentry>

<!--   D   -->

<glossentry id="def.decay">
<glossterm>Decay</glossterm>
<glossdef>
  <para>After the <link linkend="def.attack">attack</link> phase, this is the amount
  of <emphasis>time</emphasis> for the volume of a note to decrease from full
<link linkend="def.velocity">velocity</link> to the <link linkend="def.sustain">sustain</link> level.</para>

<glossseealso otherterm="def.adsr"/>
</glossdef>
</glossentry>

<glossentry id="def.dc-offsety">
<glossterm>DC-offset</glossterm>
<glossdef>
<para>DC offset, or DC coefficient is the mean value of the waveform.</para>
<para>DC offset is usually undesirable. For example, in audio processing, a 
sound that has DC offset will not be at its loudest possible volume when
<link linkend="def.normalization">normalized</link> (because the offset consumes headroom), and this problem can 
possibly extend to the mix as a whole, since a sound with DC offset and a sound
without DC offset will have DC offset when mixed. It may also cause other artifacts
depending on what is being done with the signal.</para>

</glossdef>
</glossentry>

<!--   E   -->

<glossentry id="def.envelopegenerator">
<glossterm>Envelope Generator</glossterm>
<glossdef>
  <para>A way to control (change) a parameter over time as a response to
triggering, holding, and releasing a note.</para>

<!-- TRANSLATORS: This is a witty English expression that means, "Did I
     just say something really complicated, and you quit paying attention?
     I'll try it again a little more informally." -->
<para>Did your eyes just glaze over? Let's try again:</para>

<para>Imagine that you're playing a note on the keyboard and you have
your other hand on a knob (volume, filter cutoff, etc.).  As you play
the note, you twist the knob (often up, then down... or down, then up).
You do the same thing on each note.  That's what an envelope generator
does.  See also <link linkend="def.adsr">ADSR</link></para>
</glossdef>
</glossentry>

<!--   F   -->

<glossentry id="def.fader">
  <glossterm>Fader</glossterm>
  <glossdef>
    <para>A slider control used to adjust the attenuation (volume) in a
    mixer.  Faders always have an "audio" taper, which means that the
    attenuation amount changes on an exponential scale.</para>
  </glossdef>
</glossentry>

<glossentry id="def.filter">
  <glossterm>Filter</glossterm>
  <glossdef>
    <para>A device that changes a sound by attenuating specific frequencies.
    A tone knob is an example of a simple, low-pass filter.</para>

    <glossseealso otherterm="def.bandpassfilter"/>
    <glossseealso otherterm="def.highpassfilter"/>
    <glossseealso otherterm="def.lowpassfilter"/>
    <glossseealso otherterm="def.resonancefilter"/>
  </glossdef>
</glossentry>

<!--   G   -->

<glossentry id="def.gain">
  <glossterm>Gain</glossterm>
  <glossdef>
    <para>In an amplifier, this adjust how much (or how little) a signal is
    amplified (volume).  A higher gain value is a louder signal.</para>
    <para>
      In Hydrogen there is a plethora of different ways to affect the volume
      of the resulting sound.  Each single note rendered to audio will
      contain contributions of
    </para>

    <itemizedlist>
      <listitem>
        <para>
          Its individual <link
          linkend="chpt.pattern_editor.note_properties">Note Velocity</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its individual <link
          linkend="chpt.pattern_editor.note_properties.pan">Note Pan</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link
          linkend="chpt.instrument_editor.layers.controls.layer_gain">Layer Gain</link>
        </para>
      </listitem>
      <listitem>
        <para>
          The <link
          linkend="chpt.instrument_editor.general.sustain">Sustain</link>
          value of its instrument's <link linkend="def.adsr">ADSR</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link linkend="chpt.mixer.channel_strips">Instrument Pan</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link
          linkend="chpt.instrument_editor.gain_and_mute_group">Instrument Gain</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link linkend="chpt.mixer.channel_strips">Instrument Volume</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link
          linkend="chpt.instrument_editor.layers.controls.component_gain">Component Gain</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Its <link linkend="chpt.mixer.component_strips">Component Volume</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Velocity contributions by the <link linkend="sect.song_editor.automation_path">Automation
          Path</link> when played in <link linkend="chpt.song_editor.editor_modes.song_mode">Song Mode</link>
        </para>
      </listitem>
      <listitem>
        <para>
          Random contributions introduced by <link
          linkend="chpt.mixer.master_fader_strip">Velocity Humanization</link>
        </para>
      </listitem>
      <listitem>
        <para>
          The overall <link linkend="chpt.mixer.master_fader_strip">Song Volume</link>
        </para>
      </listitem>
    </itemizedlist>
    <para>
      Further modifications of the note's audio can be applied using the
      <link linkend="chpt.sample_editor">Sample Editor</link>, the <link
      linkend="chpt.instrument_editor.filter">Low-Pass Resonance
      Filter</link>, and <link linkend="sect.fx_rack_LADSPA">FX Plugins</link>.
    </para>
  </glossdef>
</glossentry>

<!--   H   -->

<glossentry id="def.highpassfilter">
  <glossterm>High-Pass Filter</glossterm>
  <glossdef>
    <para>A filter that attenuates (silences) low frequencies, but allows
    high frequencies to pass through.</para>

    <glossseealso otherterm="def.filter"/>
    <glossseealso otherterm="def.cutoff"/>
  </glossdef>
</glossentry>

<!--   I   -->

<glossentry id="def.instrument">
  <glossterm>Instrument</glossterm>
  <glossdef>
    <para>In Hydrogen, an instrument is a single noise-maker (like a bass
    drum kick, or a tom).</para>
  </glossdef>
</glossentry>
<!--   J   -->

<!--   K   -->

<!--   L   -->

<glossentry id="def.layer">
  <glossterm>Layer</glossterm>
  <glossdef>
    <para>In an instrument you can load several different samples (each one
    called a <emphasis role="bold">layer</emphasis>), and have a different
    sample play depending on the velocity of the note.  Only one sample at a
    time will play.</para>

    <para>Suppose you have a sample of a floor tom being struck softly.  If
    you simply play the sample louder - it will
    <emphasis>not</emphasis> sound the same as a real tom that has been
    struck very hard.  If you wish to mimic this in your instrument, you can
    load one sample for soft playing, and a different sample for loud
    playing.</para>

    <glossseealso otherterm="def.instrument"/>
  </glossdef>
</glossentry>

<glossentry id="def.lowpassfilter">
  <glossterm>Low-Pass Filter</glossterm>
  <glossdef>
    <para>A filter that attenuates (silences) high frequencies, but allows
    low frequencies to pass through.</para>

    <glossseealso otherterm="def.filter"/>
    <glossseealso otherterm="def.cutoff"/>
  </glossdef>
</glossentry>

<!--   M   -->

<glossentry id="def.mute">
  <glossterm>Mute</glossterm>
  <glossdef>
    <para>To make no noise.  A setting on an instrument that prevents any
    audio output.</para>
  </glossdef>
</glossentry>

<glossentry id="def.mutegroup">
  <glossterm>Mute Group</glossterm>
  <glossdef>
    <para>A group of instruments (<link linkend="def.sample">samples</link>) out of which only a single one can be unmuted. If another instrument from the same group is triggered, the former one will be <link linkend="def.mute">muted</link> (stop playing) immediately.</para>

    <para>This is typically used in hi-hats, where there's a different
    instrument (sample) for when the hi-hat is open or closed.  With a real
    hi-hat, the sound of the open hi-hat will stop as soon as you close it.
    However, if you use two samples - the open sound will continue
    even after you have triggered the closed sound.  By placing both
    instruments in the same mute group (group #1, for example)... triggering
    closed sound will immediately stop the open sound (and vice
    versa).</para>
  </glossdef>
</glossentry>

<!--   N   -->

<glossentry id="def.normalization">
  <glossterm>Normalization</glossterm>
  <glossdef>
    <para>Normalization is the process of applying a uniform <link linkend="def.gain">gain</link> to an audio signal in order to make its largest amplitude peak match a predefined value (usually 0dBFS).</para>
  </glossdef>
</glossentry>


<!--   O   -->

<glossentry id="def.octave">
  <glossterm>Octave</glossterm>
  <glossdef>
    <para>A span of frequencies where the top-most frequency is exactly
    twice the frequency of the bottom frequency.</para>

    <para>For example, the range 20 Hz to 40 Hz is an octave.  So is 120 Hz
    to 240 Hz, and 575 Hz to 1150 Hz.  While the frequency differences are
    very different (20 Hz, 120 Hz, and 575 Hz, respectively), to the human
    ear they <emphasis>sound</emphasis> like the same distance.</para>
  </glossdef>
</glossentry>

<!--   P   -->


<glossentry id="def.pan">
  <glossterm>Pan</glossterm>
  <glossdef>
    <para>Panning allows you to change the position of both a mono and stereo sample within the stereo sound field of the resulting audio output. In other words, it controls whether the sound of e.g. the snare is coming from the left or right speaker or somewhere in between. With careful pan adjustments of the different instruments you can make you drumkit sound more natural and simulate the feeling of listening to a real kit in close distance.</para>

    
    <para>
      The effect of <link linkend="chpt.pattern_editor.note_properties.pan">note Pan</link> depends on the <link linkend="chpt.mixer.channel_strips.pan">instrument Pan</link>
      knob, which is set in the <link linkend="chpt.mixer.channel_strips">Mixer</link>.
      Look to next figure to see how the <emphasis role="bold">Resultant Pan</emphasis>
      is determined (from version 1.1):

      <figure id="matryoshkaPanning">
        <title>Visualization of the Interaction of the Different Pan Parameters</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="matrioskaPanH2.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
      
	  This multi-pan model resembles a "matryoshka" in some way: the <emphasis>note Pan</emphasis> value moves the 
	  <emphasis>Resultant Pan</emphasis> in a smaller pan range centered at
	  <emphasis>instrument Pan</emphasis>, whose extension depends on <emphasis>instrument Pan</emphasis> value.
	  Some examples: 
	  if <emphasis>instrument Pan</emphasis> is central, <emphasis>note Pan</emphasis> moves the signal in the
	  whole stereo range (really from Left to Right);
	  if <emphasis>instrument Pan</emphasis> is sided, <emphasis>note Pan</emphasis> moves the signal in a
	  progressively smaller stereo range centered at <emphasis>instrument Pan</emphasis>;
	  if <emphasis>instrument Pan</emphasis> is HARD-sided, <emphasis>note Pan</emphasis> doesn't have any effect.
    </para>

    <para>
	  The way the <emphasis>Resultant Pan</emphasis> will be translated into the volume of each stereo channel is determined by the <link linkend="chpt.mixer.master_fader_strip.mixer_settings">Pan Law</link> in the Mixer settings.
    </para>
    
  </glossdef>
</glossentry>

<!--   Q   -->

<!--   R   -->

<glossentry id="def.release">
  <glossterm>Release</glossterm>
  <glossdef>
    <para>The amount of
    <emphasis>time</emphasis> to reduce the volume of a note from the <link linkend="def.sustain">sustain</link> level
    to 0.</para>

    <glossseealso otherterm="def.adsr"/>
  </glossdef>
</glossentry>

<glossentry id="def.resonance">
  <glossterm>Resonance</glossterm>
  <glossdef>
    <para>When referring to a resonance filter, this is the parameter that
    determines how much of a boost (gain) to give the frequencies at the
    cutoff.</para>

    <glossseealso otherterm="def.resonancefilter"/>
  </glossdef>
</glossentry>

<glossentry id="def.resonancefilter">
  <glossterm>Resonance Filter</glossterm>
  <glossdef>
    <para>A filter that gives a large boost to a very narrow range of
    frequencies.  Typically it will be part of a high-pass or a low-pass
    filter, where the boosted frequencies are centered on the cut-off
    frequency.</para>

    <glossseealso otherterm="def.filter"/>
    <glossseealso otherterm="def.cutoff"/>
    <glossseealso otherterm="def.lowpassfilter"/>
    <glossseealso otherterm="def.highpassfilter"/>
    <glossseealso otherterm="def.resonance"/>
  </glossdef>
</glossentry>

<glossentry id="def.rolloff">
  <glossterm>Roll-off</glossterm>
  <glossdef>
    <para>This is the amount that frequencies are attenuated (suppressed) as
    the frequency changes (typically measured in dB/octave).</para>

    <para>For example, in a low-pass filter the frequencies below the cutoff
    frequency are not attenuated (they pass-through with the same volume).
    Same with the cutoff frequency.  As you go above the cutoff frequency,
    the frequencies that are near the cutoff frequency are not attenuated
    very much at all.  However, the frequencies that are much higher than
    the cutoff are attenuated (suppressed) a lot.  This is usually
    approximated by a straight line (on a log scale) and measured in in dB
    of attenuation per octave of frequency.</para>

    <glossseealso otherterm="def.attenuation"/>
    <glossseealso otherterm="def.filter"/>
  </glossdef>
</glossentry>

<!--   S   -->

<glossentry id="def.sample">
  <glossterm>Sample</glossterm>
  <glossdef>
    <para>A short recording of a sound, typically between .1 and 3.0 seconds
    long. Each time a note is triggered within Hydrogen the corresponding sample will be played back (after applying all customization and effects).</para>
    <para>
      Hydrogen supports the following audio formats:
    </para>
    <itemizedlist>
      <listitem>
        <para>
		      Waveform Audio File (*.wav)
        </para>
      </listitem>
      <listitem>
        <para>
		      Free Lossless Audio Codec (*.flac)
        </para>
        <note>
          <para>
            Your system is required to have <command>libsndfile</command> of at
            least version <emphasis role="bold">1.0.18</emphasis>.
          </para>
        </note>
      </listitem>
      <listitem>
        <para>
		      Compressed Ogg/Opus (*.opus)
        </para>
        <note>
          <para>
            Your system is required to have <command>libsndfile</command> of at
            least version <emphasis role="bold">1.0.29</emphasis>.
          </para>
        </note>
      </listitem>
      <listitem>
        <para>
		      Compressed Ogg/Vorbis (*.ogg)
        </para>
        <note>
          <para>
            Your system is required to have <command>libsndfile</command> of at
            least version <emphasis role="bold">1.0.18</emphasis>.
          </para>
        </note>
      </listitem>
      <listitem>
        <para>
		      Compressed MPEG Layer 3 (*.mp3)
        </para>
        <note>
          <para>
            Your system is required to have <command>libsndfile</command> of at
            least version <emphasis role="bold">1.1.0</emphasis>.
          </para>
        </note>
      </listitem>
      <listitem>
        <para>
		      Apple AIFF (*.aiff, *.aif, *.aifc)
        </para>
      </listitem>
      <listitem>
        <para>
		      Sun/NeXT AU (*.au)
        </para>
      </listitem>
      <listitem>
        <para>
		      Core Audio Format (*.caf)
        </para>
      </listitem>
      <listitem>
        <para>
		      Creative Voice File (*.voc)
        </para>
      </listitem>
      <listitem>
        <para>
		      Sonic Foundrys' 64 bit RIFF/WAV (*.w64)
        </para>
      </listitem>
    </itemizedlist>
  </glossdef>
</glossentry>

<glossentry id="def.sustain">
  <glossterm>Sustain</glossterm>
  <glossdef>
    <para>The <emphasis>level</emphasis> (how loud; volume) to hold the note between the <link linkend="def.decay">decay</link> and the <link linkend="def.release">release</link>. It is given as percentage of the <link linkend="def.velocity">velocity</link> and does not depend on time.</para>
    <glossseealso otherterm="def.adsr"/>
  </glossdef>
</glossentry>

<!--   T   -->

<!--   U   -->

<!--   V   -->

<glossentry id="def.velocity">
  <glossterm>Velocity</glossterm>
  <glossdef>
    <para>How hard you hit a note.</para>

    <para><abbrev>MIDI</abbrev> devices are required to send this information along with the
    note.  Synthesizers use this information to adjust several parameters on
    the sample (typically the volume).  In Hydrogen, it is only used to
    adjust how loud the sample is played back.</para>
  </glossdef>
</glossentry>

<!--   W   -->

<!--   X   -->

<!--   Y   -->

<!--   Z   -->

</glossary>
</part>
</book>