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.0//EN"
                      "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd">
<book id="Hydrogen-manual" lang="en">

  <bookinfo>
    <title>Hydrogen 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>


    </authorgroup>

    <date>06/september/2016</date>

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

  <!--
      ###################
      # FIRST CHAPTER   #
      ###################
  -->

  <chapter id="chap.introduction">
    <title>Introduction</title>

    <section id="sect.download">
      <title>Download</title>

      <para>
        You can download Hydrogen from 
        <ulink url="http://www.hydrogen-music.org/hcms/node/21">http://www.hydrogen-music.org</ulink>.  
        On the 'Downloads' page you can find several binaries (installers) for Linux, Mac and Windows.  (note that some versions may not be available for Windows and Mac)
      </para>

      <para>
        If you want to compile Hydrogen yourself (see <xref linkend="sect.compilation"/>), you can download the latest source files directly from our
        git repository with:

        <screen><prompt>$</prompt> <command>git clone git://github.com/hydrogen-music/hydrogen.git</command></screen>

        A certain release can be fetched with:

        <screen><prompt>$</prompt> <command>git checkout tags/1.0.0</command></screen>
      </para>

      <para>Compiling Hydrogen depends on the following libraries (among others):</para>

      <itemizedlist mark="opencircle">
        <listitem>
          <para>Qt 5 at <ulink url="http://www.qt.io">http://www.qt.io</ulink></para>
        </listitem>
        <listitem>
          <para>libsndfile at <ulink url="http://www.mega-nerd.com/libsndfile/">http://www.mega-nerd.com/libsndfile/</ulink></para>
        </listitem>
        <listitem>
          <para>ALSA (&gt;= 1.x) at <ulink url="http://www.alsa-project.org">http://www.alsa-project.org</ulink>
          (only if you wish to use ALSA as audio driver)</para>
        </listitem>
        <listitem>
          <para>Jack Audio Connection Kit (&gt;= 0.80) at 
          <ulink url="http://jackaudio.org/">http://jackaudio.org/</ulink>
          (only if you wish to use Jack as audio driver)</para>
        </listitem>
        <listitem>
          <para>PortAudio at <ulink url="http://www.portaudio.com">http://www.portaudio.com</ulink>
          (only if you wish to use PortAudio as audio driver)</para>
        </listitem>
        <listitem>
          <para>PulseAudio at <ulink url="http://www.pulseaudio.org">http://www.pulseaudio.org</ulink>
          (only if you wish to use PulseAudio as audio driver)</para>
        </listitem>
        <listitem>
          <para>Flac at <ulink url="http://flac.sf.net">http://flac.sf.net</ulink> (only if you
          wish to use flac samples)</para>
        </listitem>
        <listitem>
          <para>ladspa at <ulink url="http://www.ladspa.org">http://www.ladspa.org</ulink> (only if you wish
          to use ladspa effects)</para>
        </listitem>
        <listitem>
          <para>liblrdf at <ulink url="http://sf.net/projects/lrdf">http://sf.net/projects/lrdf</ulink> (only if you wish to use lrdf to categorise effects)</para>
        </listitem>
        <listitem>
          <para>lash at <ulink url="http://lash.nongnu.org">http://lash.nongnu.org</ulink> (only if
          you wish to use lash)</para>
        </listitem>
      </itemizedlist>

      <para>Please install them with your distribution's package manager. If
      you're running a Debian-based system, you can install the libraries
      with:</para>

      <screen>
        <prompt>$</prompt> <command>apt-get install qtbase5-dev qtbase5-dev-tools         \
	qttools5-dev qttools5-dev-tools libqt5xmlpatterns5-dev  \
	libarchive-dev libsndfile1-dev libasound2-dev liblo-dev \
	libpulse-dev libcppunit-dev liblrdf-dev                 \
	liblash-compat-dev librubberband-dev libjack-jackd2-dev</command>
      </screen>

    </section>

<!-- COMPILATION  -->

    <section id="sect.compilation">
      <title>Build</title>

      <para>Depending on the branch you are compiling you will need to use cmake. Check the INSTALL.txt and the README.txt files for more info (located in the top level dir once you downloaded the sources).</para>
      

        <para>Compiling with cmake can be done easily by using the build.sh script. Go to the directory where the git repository
        was cloned and run the build.sh script without any arguments to display the help :</para>

        <screen>
           <prompt>$</prompt> <command>./build.sh</command>
        </screen>
      
        <para>The help is now displayed (and is self-explanatory) :
        </para>
      
        <screen>
          <command>   r[m]     => all built, temp and cache files</command>
          <command>   c[lean]  => remove cache files</command>
          <command>   m[ake]   => launch the build process</command>
          <command>   d[oc]    => build html documentation</command>
          <command>   g[raph]  => draw a dependencies graph</command>
          <command>   h[elp]   => show the build options</command>
          <command>   x|exec   => execute hydrogen</command>
          <command>   t[ests]  => execute tests</command>
          <command>   p[kg]    => build source package</command>
          <command>ex: ./build.sh r m pkg x</command>
        </screen>

        <para>To build Hydrogen run the build script with the 'm' option :
        </para>
      
        <screen>
           <prompt>$</prompt> <command>./build.sh m</command>
        </screen>              
      
    </section>

    <section id="sect.preferences" xreflabel="Preferences">
      <title>Preferences</title>

      <para>First of all you should make sure that the audio engine is
      configured properly.  The preferences dialog can be accessed via the tools
      menu (tools -&gt; preferences).</para>

      <section id="sect.preferences.general_tab">
        <title>The General tab</title>
        
        <para>On the "General" tab (<xref linkend="fig.preferences.general_tab"/>) you can 
        choose to automatically reopen the last used song and/or playlist.  This can save you 
        the trouble of having to reopen the song you are working on every time you open 
        Hydrogen.  Auto loading the playlist can come in handy when you are using Hydrogen live.</para>
        <para>If you want to use Lash for session management you should enable 
        it here so Hydrogen allows interaction with Lash.</para>
        <para>The Beat Counter drift compensation and start offset allow you to compensate
         for system latency when you are using the Beat Counter function (see <xref linkend="sect.tap_tempo"/>)</para>
        <para>The Max number of bars in a song can be set here (currently limited to 800) 
        and if you want to use rubberband for sample time-stretching (see <xref linkend="sect.layer_editing.section2"/>)
        you need to enter the path where rubberband is installed on you system here.</para>
        <!-- THIJS : NEED TO AD LINK TO SAMPLE EDITOR -->
        
        <figure id="fig.preferences.general_tab">
          <title>The General Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="img/PreferencesGeneral_V3.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
        

      </section>

      <section id="sect.preferences.audio_tab">
        <title>The Audio System tab</title>

        <para>From the "Audio System" tab (<xref
        linkend="fig.preferences.audio_tab"/>) it is possible to modify the
        audio driver being used (OSS, Jack, ALSA, PortAudio, PulseAudio, CoreAudio, Auto) with its buffer and
        sampling rate (unless you are using JACK, in this case the audio driver
        configuration should happen before starting the JACK server).</para>

        <para>Also keep an eye on the value of "Polyphony": depending on your
        CPU you may want to change the max simultaneous notes in order to
        prevent hydrogen from overrunning the audio driver.</para>
        <para>The "Interpolate resampling" parameter allows you to select your preferred
        interpolation method.</para>

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

        <para>
          The following drivers are available:
        </para>

        <itemizedlist>

          <listitem>
            <para><emphasis role="bold">Auto</emphasis>: Hydrogen will try a
            number of different drivers in a predetermined order, choose the
            first working one, and display the result. This option is
            recommended for beginners.</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">Jack</emphasis>: The Jack driver is a
            professional audio server which permits very low lag and exchanges
            with other audio software. <emphasis>We strongly recommend using
            this driver to have the best out of Hydrogen</emphasis>.  JACK
            server will start automatically if not already running.</para>
            <para>Available options:</para>
            <itemizedlist>
              <listitem>
                <para><emphasis role="bold">Track output</emphasis>: This
                options determines which audio settings will be applied to the
                audio of the per-instrument output ports.</para>

                <para>Post-Fader:</para>
                <itemizedlist>
                  <listitem><para>note velocity</para></listitem>
                  <listitem><para>note and instrument pan</para></listitem>
                  <listitem><para>layer, instrument, and component gain</para></listitem>
                  <listitem><para>instrument and main component volume</para></listitem>
                </itemizedlist>
                <para>Pre-Fader:</para>
                <itemizedlist>
                  <listitem><para>note velocity</para></listitem>
                  <listitem><para>layer gain</para></listitem>
                </itemizedlist>
              </listitem>
              <listitem>
                <para><emphasis role="bold">BBT sync method</emphasis>: If
                Hydrogen uses Jack transport in the presence of an external Jack
                Timebase master (TBM), it will use the provided measure and
                tempo information instead of the local one of either the Song's
                tempo (see <xref linkend="sect.main_toolbar"/>) or the markers
                added to the Timeline (see <xref
                linkend="sect.song_editor.tempo_and_markers"/>).  But due to
                limitations in the current implementation, Hydrogen can not set
                both measure and speed provided by Jack for arbitrary pattern
                combinations. The user has two options. Either drop all measure
                changes in the TBM and work with tempo changes only to support
                arbitrary patterns (using option <emphasis>constant
                measure</emphasis>) or to keep the length of each pattern
                consistent with the corresponding measure in the TBM and to use
                both tempo and measure provided by Jack (option
                <emphasis>matching bars</emphasis>).</para>

                <para>For this option to take effect the J. TRAMS button has to
                be activated and the J. MASTER button deactivated (next to
                having a Jack TBM application). See <xref
                linkend="sect.main_toolbar"/>.</para>
              </listitem>
              <listitem>
                <para><emphasis role="bold">Connect to Default Output
                Pair</emphasis>: Connects the main stereo output of the Mixer to
                the default ports of your system
                (<emphasis>system:playback_1</emphasis> and
                <emphasis>system:playback_2</emphasis>) every time Hydrogen
                starts up or the audio driver is restarted.</para>
              </listitem>
              <listitem>
                <para><emphasis role="bold">Create per-instrument
                outputs</emphasis>: In addition to the main stereo output
                Hydrogen will register Jack output ports for every single
                instrument. This can be useful if you want to add effects to a
                single instrument with jack-rack for example.</para>
              </listitem>
            </itemizedlist>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Alsa</emphasis>: The widely adopted
            Linux standard audio drivers</para>
          </listitem>

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

          <listitem>
            <para><emphasis role="bold">PortAudio</emphasis>: an open-source
            multi platform audio driver</para>
          </listitem>

          <listitem>
            <para><emphasis role="bold">CoreAudio</emphasis>: a driver for Mac
            OS X (experimental)</para>
		  </listitem>

          <listitem>
            <para><emphasis role="bold">PulseAudio</emphasis>: a driver for the cross platform
            PulseAudio sound server.</para>
		  </listitem>


        </itemizedlist>
      </section>

      <section id="sect.preferences.midi_tab">
        <title>The Midi System tab</title>

        <para>The "Midi System" tab (<xref linkend="fig.preferences.midi_tab"/>)
        contains all MIDI settings. Here you can choose the MIDI driver (ALSA, PortMidi, 
        CoreMidi or JackMidi) input, and channel(s) that Hydrogen should respond to.  
        You can also define midi bindings: link a midi note/message to an action. 
        To do this simply press the red 'REC' button left of the event-action binding line.  
        A popup will inform you that Hydrogen is waiting for your input.  Press/hit/turn 
        the key/pad/knob on your midi keyboard (or controller) that you want to link to 
        this action.  The popup will close and the Event Param value will now show the 
        midi note value of the key you pressed.  Once this is done you can select an Action 
        from the action drop-down list.  Note that some actions (like SELECT_NEXT_PATTERN) 
        also require an Action Param that references the pattern you want to select with this midi action.</para>
       <para>See <xref linkend="sect.midi"/> for more info on Midi actions.</para>

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

      <section id="sect.preferences.appearance_tab">
        <title>The Appearance tab</title>

        <para>The "Appearance" tab (<xref
        linkend="fig.preferences.appearance_tab"/>) let's you modify Hydrogen look 
        and feel (font settings and interface style). On this tab you can also change the 
        VU meters fall-off speed and switch between Single pane and Tabbed interface
        mode (see <xref linkend="sect.UIoverview"/>)
        </para>

        <figure id="fig.preferences.appearance_tab">
          <title>The Appearance Tab</title>
          <mediaobject>
            <imageobject>
              <imagedata fileref="img/PreferencesAppearance_V2.png" format="PNG"/>
            </imageobject>
          </mediaobject>
        </figure>
      </section>


      <section id="sect.preferences.audio_engine_tab">
        <title>The Audio Engine tab (debug only)</title>

        <para>The "Audio Engine" tab (<xref linkend="fig.preferences.audio_engine_tab"/>) is a window that shows
        various stats about Hydrogen and the audio driver. In case JACK is used,
        buffer and sampling rate should be set in the configuration of the JACK
        server before starting Hydrogen (JACK automatically starts when an
        application tries to connect).</para>
        <para>Note that the Audio Engine tab is only available if Hydrogen was compiled with 
        debug support.</para>

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


    </section>
  </chapter>


  <!--
      ####################
      # SECOND CHAPTER   #
      ####################
  -->

  <chapter id="chap.using_hydrogen">
    <title>Using Hydrogen</title>

<!-- FILETYPES -->
    <section id="sect.file_types">
      <title>Used Filetypes</title>

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

      <itemizedlist>
        <listitem>
          <para><emphasis role="bold">*.h2pattern</emphasis>: XML file
          describing a single pattern. Patterns are group of beats and are
          managed in the pattern editor.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">*.h2song</emphasis>: XML file describing
          the whole song (or sequence). Songs are group of patterns with their
          properties and are manager using the song editor</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">*.h2playlist</emphasis>: XML file
          describing a playlist. A Playlist is a (ordered) group of songs.</para>
        </listitem>
        <listitem>
          <para><emphasis role="bold">*.h2drumkit</emphasis>: a compressed and
          archived folder containing all sound samples composing a drumkit and a
          description XML file. Drumkits are basically group of sound
          samples.</para>
        </listitem>
      </itemizedlist>
    </section>

<!--   KEYBOARD AND MOUSE -->
    <section id="sect.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>
        The keyboard can also be used for navigating and editing in
        the pattern and song editors, using a combination of 
        <itemizedlist>
          <listitem>
            <para>
              <emphasis role="bold">Arrow keys</emphasis>: move the
              keyboard input cursor's position, or adjust values under
              the cursor.
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Shift + Arrow keys</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">Enter / Return</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">Tab / Shift + Tab</emphasis>: move
              between different areas of the main interface.
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Delete</emphasis>:
              delete notes or patterns.
            </para>
          </listitem>
          <listitem>
            <para>
              <emphasis role="bold">Escape</emphasis>:
              cancels an ongoing selection, move or copy.
            </para>
          </listitem>
        </itemizedlist>
      </para>
      <para>
        Note that 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.
      </para>
      <para>
        Most other keys on the keyboard can be used to play
        samples and enter notes in the same way a MIDI keyboard can be.
      </para>
    </section>

<!--   UI OVERVIEW  -->
    <section id="sect.UIoverview">
      <title>The main User Interface : an overview</title>

      <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>
      <para>
      Below you can see the main UI split up in 5 parts : the Main Menu, Main 
      Toolbar, Song Editor, Pattern Editor and the Instrument and Sound Library Editor.
        These sections will be explained in detail further down in this manual.</para>
      
      <figure id="fig.UI_overview">
        <title>The Main UI in Single Pane mode</title>

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

      <figure id="fig.tabbed_UI_overview">
        <title>The Main UI in Tabbed mode</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="img/MainUI_tabbed.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      
    </section>

<!--  MAIN MENU -->
    <section id="sect.main_menu">
      <title>Main menu</title>

      <para><emphasis role="bold">Projects</emphasis>: this menu offers file
      related functions.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>New</emphasis> - Create a new song</para>
        </listitem>
        <listitem>
          <para><emphasis>Show Info</emphasis> - Set general properties of the
          song such as name, author, license and generic notes</para>
        </listitem>
        <listitem>
          <para><emphasis>Open</emphasis> - Open a song</para>
        </listitem>
        <listitem>
          <para><emphasis>Open Demo</emphasis> - Open a demo song (demo songs
          are stored in
          <emphasis>$INSTALLPATH/share/hydrogen/data/demo_songs</emphasis>)</para>
        </listitem>
        <listitem>
          <para><emphasis>Open recent</emphasis> - Open a menu showing last used
          songs</para>
        </listitem>
        <listitem>
          <para><emphasis>Save</emphasis> - Save changes to current song</para>
        </listitem>
        <listitem>
          <para><emphasis>Save as</emphasis> - Save current song specifying a
          name (default path:
          <emphasis>$HOME/.hydrogen/data/songs)</emphasis></para>
        </listitem>
        <listitem>
          <para><emphasis>Open pattern</emphasis> - Open a saved pattern
          belonging to the current drumkit</para>
        </listitem>
        <listitem>
          <para><emphasis>Export pattern as</emphasis> - Saves a
          pattern. It will be stored in
          <emphasis>$HOME/.hydrogen/data/patterns/drumkit_name</emphasis></para>
        </listitem>
        <listitem>
          <para><emphasis>Export MIDI file</emphasis> - Export current song in
          MIDI format</para>
        </listitem>
        <listitem>
          <para><emphasis>Export song</emphasis> - Export current song in WAV
          format (see <xref linkend="sect.song_editor.export_song"/>)</para>
        </listitem>
        <listitem>
          <para><emphasis>Export Lilypond file</emphasis> - This is a first version of the LilyPond export.
          It has the following limitations: Only GM-kit is supported, No triplets support</para>
        </listitem>
        <listitem>
          <para><emphasis>Quit</emphasis> - Quit Hydrogen</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Undo</emphasis>: Undo/Redo functions.</para>
      
        <itemizedlist>
        <listitem>
          <para><emphasis>Undo</emphasis> - Lets you undo your last action</para>
        </listitem>
        <listitem>
          <para><emphasis>Redo</emphasis> - Lets you redo the last undone action</para>
        </listitem>
        <listitem>
          <para><emphasis>Undo History</emphasis> - Gives you an overview of your previous
          actions</para>
        </listitem>
        </itemizedlist>

      <para><emphasis role="bold">Instruments</emphasis>: this menu offers
      instruments functions.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Add instrument</emphasis> - Add a new instrument to your current drumkit</para>
        </listitem>
        <listitem>
          <para><emphasis>Clear all</emphasis> - Delete all instruments from the current drumkit</para>
        </listitem>
        <listitem>       
            <para><emphasis>Add component</emphasis>: - A component is a part of Hydrogen's instrument model.
                Each instrument consists 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.
            </para>
        </listitem>
      </itemizedlist>
        
      <para><emphasis role="bold">Drumkits</emphasis>: this menu offers drumkit (sound libraries) functions.</para>
      <itemizedlist>
        <listitem>
          <para><emphasis>Save</emphasis> - Saves all instruments settings (and their sound samples) in
            <emphasis>$HOME/.hydrogen/data/library_name</emphasis>
          </para>
        </listitem>
        <listitem>
          <para><emphasis>Export</emphasis> - Compress all instruments samples and settings in a drumkit in
            <emphasis>$HOME/.hydrogen/data/library_name</emphasis>
          </para>
        </listitem>
        <listitem>
          <para><emphasis>Import</emphasis> - Imports another drumkit from the local filesystem.
              To load another drumkit in your
              current working session of Hydrogen, read <xref
              linkend="sect.sound_library"/>.
          </para>
        </listitem>
        <listitem>
          <para><emphasis>Online import</emphasis> - Imports another drumkit from a remote location
              through an XML feed. The XML file that should be provided is <emphasis
              role="bold">NOT</emphasis> RSS compliant (see <ulink
              url="http://www.hydrogen-music.org/feeds/drumkit_list.php" >Hydrogen
              website</ulink> for an example). To load another drumkit in your
              current working session of Hydrogen, read <xref linkend="sect.sound_library"/>.
          </para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">View</emphasis>:Opens the director, the playlist editor, the instrument rack
         and the general preferences window.
      </para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Playlist editor</emphasis> - A tool to manage
          playlists.</para>
        </listitem>
        <listitem>
          <para><emphasis>Director</emphasis> - Open the director window.</para>
        </listitem>
        <listitem>
          <para><emphasis>Mixer</emphasis> - Open the mixer window.</para>
        </listitem>
        <listitem>
          <para><emphasis>Instrument rack</emphasis> - Open the instrument rack
          panel.</para>
        </listitem>
        <listitem>
          <para><emphasis>Automation path</emphasis> - Open the automation path
          panel.</para>
        </listitem>
        <listitem>
          <para><emphasis>Timeline</emphasis> - Open the time line
          panel (auto hiding the playback track)</para>
        </listitem>
        <listitem>
          <para><emphasis>Playback track</emphasis> - Open the time line
          panel (auto hiding the timeline)</para>
        </listitem>
        <listitem>
          <para><emphasis>Full screen</emphasis> - Maximises the window size to the whole screen area</para>
        </listitem>
      </itemizedlist>
      <para><emphasis role="bold">Options</emphasis>: selects the input mode and opens the general preferences
      window.</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Input mode</emphasis> -
               when set to <emphasis>Drumset</emphasis> the keys on your midi keyboard will map to the instruments
               in your drumkit. If you set it to <emphasis>Instrument</emphasis> the keys of your midi 
               keyboard will trigger the instrument that is currently selected.
               The pitch of the instrument will follow the key you press on your keyboard.
               This feature is mainly used for non-drum instruments.
               An example: if you use a sample of a piano for one of your instruments, you will be able to 'play'
                that piano instrument using your keyboard just like you are playing a piano synth.</para>
       </listitem>
  
        <listitem>
          <para><emphasis>Preferences</emphasis> - Open the main preferences
          window. Read <xref linkend="sect.preferences"/> on how to configure
          Hydrogen.</para>
        </listitem>
       </itemizedlist>

      <para><emphasis role="bold">Debug</emphasis>: tools mainly for debugging
      and monitoring Hydrogen (only available when compiled with debug
      support !).</para>

      <itemizedlist>
        <listitem>
          <para><emphasis>Show audio engine info - </emphasis>Open a monitor
          with various <link
          linkend="sect.preferences.audio_engine_tab">stats</link></para>
        </listitem>
        <listitem>
          <para><emphasis>debug action - </emphasis> Insert debug
          commands.</para>
        </listitem>
        <listitem>
          <para><emphasis>Print Objects - </emphasis>Print on stdout current
          objects map.</para>
        </listitem>
      </itemizedlist>

      <para><emphasis role="bold">Info</emphasis></para>

      <itemizedlist>
        <listitem>
          <para><emphasis>User manual - </emphasis>Open a window with this
          manual :)</para>
        </listitem>
        <listitem>
          <para><emphasis>About - </emphasis>The usual window with license
          information, acknowledgments, etc.</para>
        </listitem>
        <listitem>
          <para><emphasis>Report bug - </emphasis> Opens the Hydrogen issue page at github.com in 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>Donate - </emphasis> Make a donation to developers/mantainers</para>
        </listitem>
      </itemizedlist>
    </section>


<!--   MAIN TOOLBAR  -->
    <section id="sect.main_toolbar">
      <title>The main toolbar</title>

      <para>Before analyzing the two main frames of Hydrogen, let's take a quick
      look at the main toolbar and its components:</para>

      <itemizedlist>
        <listitem>
          <para>Pilot the song using the start, stop, pause, etc. buttons</para>
        </listitem>
        <listitem>
          <para>Choose between "pattern" or "song" mode: in "pattern" mode only
          the currently selected pattern will play, while in "song" mode all
          patterns inserted will be played.</para>
        </listitem>
        <listitem>
          <para>An advanced tap tempo function: choose note length and how many
          notes to wait before recalculating BPM, then hit the comma key
          repeatedly until the 'R' letter appears and then the BPM will be
          updated.  (see <xref linkend="sect.tap_tempo"/>)</para>
        </listitem>
        <listitem>
          <para>Manually set BPM</para>
        </listitem>
        <listitem>
          <para>Manage JACK transport</para>
        </listitem>
        <listitem>
          <para>Open the mixer and the instrument rack panels</para>
        </listitem>
      </itemizedlist>

      <figure id="fig.main_toolbar">
        <title>The Main Toolbar</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="img/MainToolbar_V2.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>

      <itemizedlist mark="opencircle">
        <listitem>
          <para><inlinemediaobject><imageobject><imagedata
          fileref="img/background_Control_V2.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Main controls to start <emphasis role="bold">[Hotkey =
          Spacebar]</emphasis>, stop, record, fast forward, rewind, loop a song or a
          pattern.</para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
          <imagedata fileref="img/background_Mode.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Set Pattern/Song Mode. When Song mode is selected Hydrogen will play 
          the complete song. This is the sequence of patterns you have created in the Song 
          Editor (see <xref linkend="sect.song_editor"/>). When Pattern mode is selected 
          Hydrogen will play the pattern that is currently selected, and thus displayed 
          in the Pattern Editor (see <xref linkend="sect.pattern_editor"/>).</para>
        </listitem>
        
        <listitem>
          <para><inlinemediaobject><imageobject>
          <imagedata fileref="img/MeasureSettings.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Set measure type and Beat Counter (see <xref linkend="sect.tap_tempo"/>).</para>
          
        </listitem>
        
        

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/background_BPM.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Set speed of playing (range: 30-400 bpm) <emphasis
          role="bold">[Hotkey = mouse wheel]</emphasis> and button to
          enable/disable metronome</para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
          <imagedata fileref="img/MidiIN_CPU.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

            <para>Shows CPU load and MIDI events.  The CPU bargraph gives you an indication of the CPU load.  The MIDI led lights up every time Hydrogen receives a midi message.</para>
        </listitem>
<!--
        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/midi_in.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Shows MIDI events.</para>
        </listitem>
-->
        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/JackTrans_Master.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>Click J. TRANS to enable Jack transport.  If the J. MASTER button is pressed Hydrogen will work as Jack timebase 'master' by sending additional information, like the current speed, to other Jack clients. Else it will either act as 'slave' in the presence of another timebase master (e.g. Ardour) or as a stand-alone client in the absence of it. Please note that when acting as 'slave' Hydrogen will obey the tempo provided by the timebase master and instead of its own tempo markers (see <xref linkend="sect.preferences.audio_tab"/>).</para>
        </listitem>
        
       <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/mixer-instrrack_btn.png" format="PNG"/>
          </imageobject></inlinemediaobject></para>

          <para>
          The last section gives you quick access to the Mixer window and the Instrument Rack.
            The LCD screen displays what Hydrogen is up to.
          </para>
        </listitem>        
        
      </itemizedlist>


    <!--  TAP TEMPO -->

      <section id="sect.tap_tempo" xreflabel="Tap Tempo and BeatCounter">
        <title>Tap Tempo and BeatCounter</title>

        <para>It is possible to change the tempo at any time using the Tap Tempo and
        BeatCounter features of Hydrogen.  You can do this while the song is playing or
        while the song is stopped.  To change the tempo, hit the
        <keycap>,</keycap> (comma) key in the tempo you want.
        After the correct number of keystrokes have been detected (see 
        below for details), the tempo will change to the average tempo 
        you tapped the comma key.  If you continue to tap,
        these new taps will become a part of a rolling average.  If you tap
        accidentally, or if you wait too long between taps, the tap tempo
        counter will start over.</para>

        <para>The Tap Tempo is a part of the BeatCounter, which is essentially a
        Tap Tempo on steroids.  By default the BeatCounter display is not
        visible.  To see the BeatCounter widget click the upright button
        (<guilabel>BC</guilabel>) between Song/Pattern mode selector and the
        BPM-widget, or, simply press the comma key.
        (<keycap>,</keycap>).</para>

        <para>The tempo that you tap will be considered 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 +/- buttons.  To change
        the Countdown Counter value, use the right +/- 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 <guilabel>R</guilabel>, it means that the BeatCounter
        is ready to start from 0.  When you tap the comma key, the R will change to
        1, and will increment with every keystroke until it reaches the Countdown 
        Counter value (shown just below the 'R').</para>

        <para>The button in the bottom right-hand controls the auto-start
        feature, and it toggles between <guilabel>S</guilabel> and
        <guilabel>P</guilabel>.  When it shows <guilabel>P</guilabel> 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
        BeatCounter set up for 4/4, you can tap 1-2-3-4, and start playing on
        the next beat.  When it shows <guilabel>S</guilabel> (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 Seq24)... 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 <guilabel>P</guilabel>).  Count off
        the band 1-2-3-4 (while tapping the comma key) &mdash; 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>

        <para>If you are using the JACK Transport, the BeatCounter continues to
        work.  If another program is the JACK Transport Master, Hydrogen will
        respond to tempo change events from that application.  Note that in this
        situation, Hydrogen is supposed to be a <emphasis>slave</emphasis>, so
        some of the BeatCounter features will be disabled or will not work
        properly.  If Hydrogen is the JACK Transport Master, tempo changes from
        Hydrogen will be reflected in those programs (if they support
        it).</para>

        <para>Some of the settings to adjust the BeatCounter's latency
        compensation, are located on the General tab of the Preferences Dialog 
        (see <xref linkend="sect.preferences.general_tab"/>
        ). Here you will find two spinboxes:</para>

        <itemizedlist>
          <listitem><para><emphasis role="bold"><guilabel>Beat counter drift
          compensation in 1/10ms</guilabel></emphasis> &mdash; adjust to
          compensate for latency between the keyboard and the
          program.</para></listitem>

          <listitem><para><emphasis role="bold"><guilabel>Beat counter start
          offset in ms</guilabel></emphasis> &mdash; adjust the time between the
          BeatCounter's last input stroke and when the song starts playing (if
          auto-start is activated).</para></listitem>
        </itemizedlist>

        <para>Note that these can be set to positive (+) or negative (-) values.
        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
        BeatCounter effectively requires practice.</para>

      </section>

    </section>


<!-- SONG EDITOR -->
    <section id="sect.song_editor">
      <title>Song Editor</title>

      <para>The "Song Editor" (<xref linkend="fig.song_editor"/>) gives an
      overview of the whole timeline of the song (e.g. intro, verse, bridge,
      chorus and so on); each blue colored square on this panel represents a complete
      bar as shown in the underlying "Pattern Editor" panel. The song editor gives
      you complete freedom to add/remove patterns to the song and to move or 
      copy any part of your song.
      
           
      <figure id="fig.song_editor">
        <title>The Song Editor</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/SongEditor.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
      </para>

     <section id="sect.song_editor.main_controls">
      <title>Main controls</title>
      <para>
        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/bg_topPanel.png" format="PNG"/>
          </imageobject>
        </inlinemediaobject>
      </para>

      <itemizedlist mark="opencircle">

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_clear_off.png" format="PNG"/>
            </imageobject></inlinemediaobject> Completely delete all patterns
            (asks for confirmation!).
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_new_on.png" format="PNG" />
            </imageobject></inlinemediaobject> Create a new pattern (and asks
            for a name).
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_updown.png" format="PNG" />
            </imageobject></inlinemediaobject> Move currently selected pattern
            up or down.</para>
          <para>Note that you can also just drag-and-drop a pattern up/down in the pattern list.</para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_draw.png" format="PNG"/>
            </imageobject></inlinemediaobject> Enable Draw Mode.  This mode allows
            you to create a song by drawing blocks on the song canvas.</para>
            <para>Clicking a square on the song canvas will add a pattern (the square 
            will turn blue), clicking it again will remove that pattern from the song.
          </para>
          <para>
            Using the arrow keys on the keyboard, and the Return key,
            will also add and remove patterns from the song. The
            keyboard input cursor is usually hidden unless you press
            one of the arrow keys.
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_select.png" format="PNG"/>
            </imageobject></inlinemediaobject> Enable Select Mode.  This mode allows 
            you to select a part of the song and delete/move/copy it.</para>
		<para>Once you have selected a part of your song you can <emphasis role="bold">delete</emphasis> 
			it by pressing the Delete button.  You can <emphasis
             role="bold">move</emphasis> it by simply dragging your selection
            to another location, and you can also <emphasis role="bold">copy</emphasis>
             your selection by Ctrl-dragging it to a new location.
          </para>
          <para>
            Selections can be modified by Ctrl-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 the Return key, to <emphasis
            role="bold">select</emphasis>, <emphasis
            role="bold">move</emphasis> and <emphasis
            role="bold">copy</emphasis> (Ctrl+Return) parts of the
            song.
          </para>
          <para>
            Pressing Escape will cancel an editing operation that's in
            progress, or clear any selection.
          </para>
        </listitem>

        <listitem>
          <para><inlinemediaobject><imageobject>
            <imagedata fileref="img/btn_pattern_mode.png" format="PNG"/>
            </imageobject></inlinemediaobject> set Hydrogen to "Single pattern mode"
            <inlinemediaobject><imageobject>
            <imagedata fileref="img/stacked_mode_V3.png" format="PNG"/>
            </imageobject></inlinemediaobject>
            or to "Stacked pattern mode".</para>
            <para>For more info on this see the SELECT_NEXT_PATTERN midi action in <xref linkend="sect.midi"/>.
          </para>
        </listitem>
      </itemizedlist>

      </section>
      
      
     <section id="sect.song_editor.tempo_and_markers">
     <title>Tempo markers and song Tags</title>
       <para>This section describes how you can define tempo changes and 
       how you can add tags to your song.</para>
       <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 of a song at any given moment in the song.  This is 
       done by adding Tempo change Markers to your song.</para>
       <para>To add a Tempo change marker to your song you first need to enable the 'BPM' option
       (the BPM button is located just above the Song editors main controls).  Once this is done
       the horizontal bar next to the BPM button changes to a ruler with marks at every bar.
       Now simply left-click this ruler at the bar you want the tempo to change and a
       window will pop up where you can enter the new tempo. (Please note that the ruler will not be available while using the Jack transport in 'slave' mode.)
     
        <informalfigure id="fig.add_tempo_change">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/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 tempo ruler.  If you click the Tempo marker again you can edit 
       the tempo, change the bar or delete the tempo marker.

        <informalfigure id="fig.tempo_bar">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/tempo_bar.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>

       </para>

       <para>
       In addition to changing the tempo when the song switches from intro > verse, 
       it is also very handy to have a clear indication of this tempo switch (or any other
       event in the song).  For this purpose you can also add Tags markers to the song.
       These Tags are short text messages you can add to your song at any given 
       moment that will be displayed whenever the song playhead passes by that Tag.</para>
       
       <para>
       To add a Tag to your song simply middle-click on the song ruler (just below the 
       tempo ruler) and a window will pop up where that allows you to add text for any bar.
            
        <informalfigure id="fig.add_tag">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/add_tag.png" format="PNG" />
           </imageobject>
          </mediaobject>
         </informalfigure>

       Once you are done you will see a small blue 'T' in the song ruler for every tag 
       you have entered.  Middle-click anywhere on the song ruler to edit the tags.

         <informalfigure id="fig.tag_bar">
          <mediaobject>
            <imageobject>
              <imagedata fileref="img/tag_bar.png" format="PNG" />
            </imageobject>
          </mediaobject>
         </informalfigure>
       </para>
     </section>

     <section id="sect.song_editor.director" xreflabel="Director">
       <title>Director</title>
       <para>
         Now all we need is a way to see the tags we have entered.  This can be done
         using the Director window.  Open the Director by pressing Alt-D, or Tools- Director :

         <informalfigure id="fig.director">
           <mediaobject>
             <imageobject>
               <imagedata fileref="img/screenshot-director.png" format="PNG" />
             </imageobject>
           </mediaobject>
         </informalfigure>
         
         The Director is your best friend when you need a quick overview of what Hydrogen
         is currently doing.  This comes in very handy when you are recording a song, or
       if you are using Hydrogen live on stage.</para>
       
       <para>
         The Director shows you the song name, a visual metronome and of course the
         song Tags.  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>
     </section>

     <section id="sect.song_editor.playbackTrack">
		 <title>Using a playback track</title>
		 <para>This section describes how you can use a playback track to write drums for an existing track.
				This useful when you want to write a drumtrack to an already existing instrumental track, for example a guitar track.
		 </para>
		 <para>
			To add a playback track to your song, you need to enable the playback track view. This can be done by pressing the small "P" button in the next to the vertical scroll bar of the song editor.

			 <informalfigure id="fig.enablePlaybackTrack">
				 <mediaobject>
					 <imageobject>
						 <imagedata fileref="img/EnablePlaybackTrack.png" format="PNG" />
					 </imageobject>
				 </mediaobject>
			 </informalfigure>

			 An alternative way to enable the playback track view is to enable the option "Playback track" in the "View" menu.

			 If the playback track view is enabled, a visualisation of the currently loaded track is display above the song editor.

			 <informalfigure id="fig.playbackTrack">
				 <mediaobject>
					 <imageobject>
						 <imagedata fileref="img/PlaybackTrack.png" format="PNG" />
					 </imageobject>
				 </mediaobject>
			 </informalfigure>

			Left to the visualisation, the controls for the playback are displayed:

			 <itemizedlist mark="opencircle">
				 <listitem>
					 <para>Edit: Load a new playback track</para> 
					 <para>Mute: Mute the current playback track</para> 
					 <para>Fader: Adjust the volume of the playback track</para> 
				 </listitem>
			 </itemizedlist>

			As an alternative to the use of the Edit Button, you can add a new playback track by drag'n'drop, just drag an audio file to the visualation area.
			 When a playback track track is loaded, it will be played everytime Hydrogen is in "Play" mode and the song mode is activated. 
		</para>
	 </section>

     <section id="sect.song_editor.pattern_options">
     <title>Patterns options</title>

      <para>Right-clicking the name of a pattern 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="img/Virtual_patterns_menu.png" format="PNG"/>
          </imageobject>
        </mediaobject>
      </figure>
      
      
      <itemizedlist mark="opencircle">

        <listitem>
          <para>Edit : will open the selected pattern in the Pattern Editor.
          </para>
        </listitem>
        
        <listitem>
          <para>Copy : will copy the selected pattern to a new pattern in your song.
          </para>
          <para>Note that patterns with the same name are not allowed.</para>
        </listitem>
        
        <listitem>
          <para>Delete : will completely remove the selected pattern from the song.
          </para>
        </listitem>
        
        <listitem>
          <para>Fill/Clear : 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>
              <imageobject>
                <imagedata fileref="img/fill_clear_pattern.png" format="PNG" />
              </imageobject>
            </mediaobject>
            </informalfigure>
          </para>
        </listitem>
        
        <listitem>
          <para>Properties : will open a window where you can change 
          the name of the pattern and also assign it to a certain category.
           <informalfigure id="fig.pattern_properties">
            <mediaobject>
              <imageobject>
                <imagedata fileref="img/pattern_properties.png" format="PNG" />
              </imageobject>
            </mediaobject>
            </informalfigure>
          </para>
          <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>
        </listitem>
        
        <listitem>
          <para>Load Pattern : will open the selected pattern in the Pattern Editor.
          </para>
        </listitem>
        
        <listitem>
          <para>Save Pattern : will open the selected pattern in the Pattern Editor.
          </para>
        </listitem>
        
        <listitem>
          <para>Virtual Pattern : will open the selected pattern in the 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>
        
      


      


     
     </section>

     <section id="sect.song_editor.export_song" xreflabel="Export Song">
     <title>Exporting your song</title>

      <para>Once your song is finished you can export it to an audio file.
      This audio file can then be played on your favorite media player or imported
      in an other audio application.</para>
      <para>
      To do this, go to Project - "Export song" and the following window will pop up:
        <figure id="fig.Export_song">
         <title>Export a song</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/Export_song.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>
      To export a song you need to do 3 things:
     
      </para>
      
       <itemizedlist mark="opencircle">

        <listitem>
          <para>Enter a name and location for the export file in the 'Export filename' field
          </para>
        </listitem>
        
        <listitem>
          <para>Select one of the available templates (e.g. CD, DAT ...) according to your needs:  
          each template has a specific bitrate, resolution, and audio format (WAV, AIFF, FLAC or OGG).
          You can tweak the selected template using the samplerate/sampledepth dropdown boxes
          underneath the template field.
          
          </para>
        </listitem>
        
        <listitem>
          <para>Export mode: 'Export to a single track' will export 1 stereo downmix of your 
          song (= the master output).  'Export to separate tracks' will create files for each 
          instrument/track.  'Both' will create a stereo downmix + audio files for all individual
          instruments.
          </para>
        </listitem>
        
        </itemizedlist>
        
        <para>
        Once all these settings have been configured all you need to do is click the 'Export'
        button and Hydrogen will generate the requested files.
        </para>

      <note>
       <para>
       If you have tempo changes in your song (see <xref linkend="sect.song_editor.tempo_and_markers"/>) 
       these tempo changes will not be exported.  This is a know limitation of the current versions 
       (including 0.9.6)
       </para>
       <para>
       As a workaround you can record the output of Hydrogen with an audio recording
       application (like Ardour, Qtractor ...)
       </para>
      </note>

     </section>


    </section>
    

<!--  PATTERN EDITOR  -->
    <section id="sect.pattern_editor">
    
      <title>Pattern Editor</title>

      <para>The "Pattern Editor" 
      allows you to create or modify the selected pattern by adding/removing notes and tuning 
      a number of per-note properties like velocity and pan.
      The Pattern Editor 
      can be used in 2 modes : 'Drum' mode or 'Piano' mode.  You can switch between these 
      modes by clicking the Drum/Piano button (located on the top-right of the Pattern Editor) 
      <note>
      <itemizedlist mark="opencircle">
      <listitem><para>
      If you are editing a pattern in Single Pattern Mode you will always hear the pattern you are 
      editing when you press play.</para></listitem>
      <listitem><para>If you are working in Stacked Pattern Mode you will hear the <emphasis>active</emphasis> pattern(s), 
      not necessarily the pattern you are currently editing.
      (The active patterns have a small triangle next to the pattern name in the Song Editor). 
      </para></listitem>
      </itemizedlist>
      </note>
      
      </para>
      
      <para>First let's take a look at the (classic) 'Drum' mode :
        <figure id="fig.PatternEditor_DrumMode">
         <title>Pattern Editor in Drum mode</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/PatternEditor_DrumMode.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>
      </para>
      
      <section id="sect.pattern_editor.controls"> 
       
        <title>Pattern Editor Controls</title>
        <para>The top part of the pattern editor contains a number of controls :</para>
      
        <figure id="fig.PatternEditorControls">
         <title>Pattern Editor Controls</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/PatternEditorControls.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>
        
         <para>From left to right : </para>
         <itemizedlist mark="opencircle">
         
          <!-- TODO DEPRECATED widget. MOVE TO OTHER CHAPTER?? <listitem><para><emphasis role="bold">Note Length / Note off</emphasis> : these are 2 different
            ways to define the duration of a note. See <xref linkend="sect.pattern_editor.sequence_area"/> for usage.</para></listitem>  -->

           <listitem>
                <para><emphasis role="bold">SIZE</emphasis>:
                    lets you choose the length of the pattern (in note values)
                </para>
                <para>
                   It will open a dialog to enter the new size as text, in the standard music fractional notation:                  
                </para>
                <informalfigure id="fig.PatternSizeDialog">
                     <mediaobject>
                        <imageobject>
                          <imagedata fileref="img/PatternSizeDialog.png" format="PNG" />
                        </imageobject>
                     </mediaobject>
                </informalfigure>                
                <para>
                   Type '/' to separate numerator and denominator.
                 </para>
                 <para>
                   If you enter just the numerator (e.g. "4"), the current denominator will be assumed.
                </para>
                 <para>
                   You can enter a decimal numerator (e.g. "4.5/4") but since Hydrogen resolution is limited,
                   some values are not supported and will be approximated.
                </para>
                <para>
                   Hydrogen supports (only) the following denominators: 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64, 96, 192,
                     because these are the factors of the maximum resolution (192 ticks per whole note).
                   You can use unsupported denominators, but the size will be approximated almost all the times,
                    hence a warning icon will appear:               
                </para>
                <informalfigure id="fig.DenominatorWarningIcon">
                    <mediaobject>
                        <imageobject>
                            <imagedata fileref="img/DenominatorWarningIcon.png" format="PNG" />
                        </imageobject>
                    </mediaobject>
                 </informalfigure>
           </listitem>

           <listitem>
            <para>
             <emphasis role="bold">RES</emphasis> : this is the current grid resolution (4 through 64)
            </para>
            <para>
                Remember this constraint concerning the grid: if you are working
                with a resolution of 16 you can't go back to 8 and remove an upbeat 16th note. On
                the other hand if you are working with a resolution of 8 and you try to
                insert a note in the middle of two bars (looking for a 16 bars precision),
                notes will be placed in the previous or in the following 8th bar.  This
                constraint can be removed if you disable the whole grid resolution (choose
                "off" from the grid resolution LCD control). Now you'll be able to place
                notes wherever you prefer.</para>
           </listitem>
        
           <listitem><para><emphasis role="bold">HEAR</emphasis> : when enabled Hydrogen 
           will play the sample as it's being added to the pattern.</para></listitem>

           <listitem><para><emphasis role="bold">QUANT</emphasis> : enables/disables quantization.  
           When enabled the beats inserted 
            will automatically respect the grid resolution currently applied.</para></listitem>

           <listitem><para><emphasis role="bold">INPUT</emphasis> : switch Pattern Editor 
           between Drum and Piano mode. (see below)</para></listitem>

         </itemizedlist>

      </section>
      
      <section id="sect.pattern_editor.drumkit">
      <title>Pattern Editor Drumkit</title>
        <para>The section on the left shows you what drumkit is currently selected (GMkit by default) and below that you can see
        the instruments that are part of this kit.</para>
        
        <para>
        <inlinemediaobject id="ifig.pattern_editor_instrument">
          <imageobject>
            <imagedata fileref="img/PatternEditorInstr_V2.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>
        </para>
          
        <para>Each instrument has its own set of features that are accessible by 
        right-clicking the instrument.  From the context menu that pops up you can select </para>
        <itemizedlist mark="opencircle"> 
          <listitem><para><emphasis role="bold">Clear notes</emphasis> : to remove all notes for this instrument in this pattern.  </para></listitem>
          <listitem><para><emphasis role="bold">Fill notes</emphasis> : this allows you to fill
          up the pattern with notes for the selected instrument.  Depending on the choice you make (fill all, fill 1/2, fill 1/4 ...)
          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></listitem>
          <listitem><para><emphasis role="bold">Randomize velocity</emphasis>
          : automatically apply a pseudo-random velocity to each note of that
          instrument in the pattern. The more velocity you set on the instrument,
          the more hydrogen will hit <quote>hard</quote> on that instrument when
          played.
          </para></listitem>
          <listitem><para><emphasis role="bold">Delete Instrument</emphasis> : well, deletes the instrument ;-)</para></listitem>
        </itemizedlist>
        
        <para>The small red and green buttons right of the instrument names are the
        <quote><emphasis role="bold">mute</emphasis></quote> (red) and <quote><emphasis
        role="bold">solo</emphasis></quote> (green) buttons.</para>

        <para>The order of the instruments can be rearranged by simply dragging an instrument 
        up/down in the list and dropping it on a new position within the drumkit.  Doing so 
        will not change anything to the sequence you have created for that instrument, nor will
        it change anything to the song or pattern you are working on.  It <emphasis role="bold">
        will</emphasis> however, have an impact on the <emphasis role="bold">MIDI note 
        mapping</emphasis> : in the table below you can find the link between the instrument
        position, the MIDI note and the qwerty keyboard keys.</para>

      <para><emphasis role="bold">Important Notes</emphasis> :</para>
      <para>The name of the instrument depends on the
      drumkit that is loaded. This list below refers to the GMkit that is loaded by default.
      </para>
      <para>Try to follow the GM midi standard as accurately as possible.  This will ensure that switching between 
      drumkits goes smoothly.  You are of course free to place your instruments anywhere in your drumkit, and
      sometimes it isn't even possible to follow the GM standard, but it makes life a lot easier if you do.</para>
      <para>
      Keep in mind that it is the <emphasis>position</emphasis> of the instrument (within the loaded drumkit) that 
      is linked to a MIDI-note/keyboard-key and <emphasis>not the name</emphasis> of the instrument.
      </para>



      <informalfigure id="fig.InstrumentMapping">
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/InstrumentMapping.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </informalfigure>

      <para>Here's a quick reference of the above bindings for your
      convenience. </para>

      <informalfigure id="fig.letters_keyboard">
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/tastiera.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </informalfigure>
      </section>

      <section id="sect.pattern_editor.sequence_area">
      <title>Pattern Editor Sequence area</title>
        <para>This is where it all happens, this is where you can make music :-)</para>
        <para>In this area you can see your selected pattern and add notes for any instrument. 
        The simplest way to create a pattern is by adding notes using your mouse 
        (and the 'Fill/Clear notes' function described above). Where you can add notes
        depends on the used pattern size and resolution.</para>
        <para>If you are using Hydrogen as a pure 'drum' you just want Hydrogen to 'hit' 
        the instrument wherever there's a 'dot' in the pattern. If you are using Hydrogen as an 'instrument', the 
        length of the note becomes very important. There are 2 ways to define the length of
        a note :
      </para>
        <itemizedlist>
          <listitem>
            <para>
              you can add a note by left-clicking, and then can 'stretch' that note by right-click-dragging it.
              This will change the dot into a rectangle that represents the
              duration of that note.
            </para>
          </listitem>
          <listitem>
            <para>
              Alternatively, you can add a stop-note by
              Shift+left-clicking. This adds a blue dot which
              represents the end of the note.
            </para>
          </listitem>
        </itemizedlist>
        <para>
          <informalfigure id="fig.NoteOff_NoteLength">
            <mediaobject>
              <imageobject>
                <imagedata fileref="img/NoteOff_NoteLength.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>
          (Figure above, from left>right : a 'normal' note, a note in 'note length' mode, a note in 'note off' mode)
        </para>

        <para>
          As in the Song Editor, the arrow keys can also be used to
          move around the pattern, and notes can be placed or removed
          with Return.
        </para>

        <para>
          Notes can be selected by dragging over them with the mouse (or <emphasis
          role="bold">Shift+arrow keys</emphasis>), and can be deleted with 'Delete', or moved by
          dragging (or Return followed by arrow key movements) the notes 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
          resolution, however this can be overridden by holding down <emphasis
          role="bold">Alt</emphasis> while moving notes.
        </para>

        <para>
          Moving a selection of notes with <emphasis role="bold">Ctrl</emphasis> 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 <emphasis
          role="bold">Ctrl+C</emphasis>, and pasted with <emphasis
          role="bold">Ctrl+V</emphasis>. 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>

        <para>So far we have only used the mouse or keyboard editing to create a pattern, but you can also record your beats by clicking the Record button 
         <inlinemediaobject>
          <imageobject>
           <imagedata fileref="img/Rec_button.png" format="PNG"/>
          </imageobject>
         </inlinemediaobject>
        (see <xref linkend="sect.main_menu"/>) and simply playing your pattern on your 
        MIDI drum or your pc keyboard (see instrument mapping above).  This is probably 
        a more musical way of creating a pattern, but it's up to you to decide what works best for you.
        (Also see <xref linkend="chap.create_song"/> for a basic
        walk-through of how the pattern editor works) </para>
 
      </section>
      
      <section id="sect.pattern_editor.note_properties">
      <title>Pattern Editor Note Properties</title>
      <para>Clicking on an instrument or adding/removing a note next to it 
      will select this instrument.  Once an instrument is selected the note properties 
      for this instrument will be shown in the form of vertical lines in the bottom window.  
      The lines represent the value 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).
      There are 4 note properties available : 
      
      <itemizedlist mark="opencircle">
        <listitem>
          <para><emphasis role="bold">Velocity</emphasis> : how hard the note is played (the volume of the note)</para>
          <para>
          Note that the color of the note-dot and the vertical bar will change according to the velocity value you have defined. 
          A light shade of gray means a low velocity (low volume) and the higher you set the velocity the darker the color will be,
          turning red when you reach the point of clipping.
          </para>
        </listitem>
        
        <listitem>
          <para><emphasis role="bold">Pan</emphasis> : with this parameter you can move
           the stereo image position of the note (how loud it will be in the left/right output).</para>
           <para>Note that the effect of <emphasis>note Pan</emphasis> depends on the <emphasis>instrument Pan</emphasis>
            knob, which is set in the mixer.
           Look to next figure to see how the <emphasis role="bold"><emphasis>Resultant Pan</emphasis></emphasis>
           is determined (from version 1.1):
           <informalfigure id="matryoshkaPanning">
            <mediaobject>
              <imageobject>
                <imagedata fileref="img/matrioskaPanH2.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>
           
	       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>
           
        </listitem>
        
        <listitem>
          <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>
          <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>
          <informalfigure id="fig.NoteKey">
            <mediaobject>
              <imageobject>
                <imagedata fileref="img/NoteKey.png" format="PNG" />
              </imageobject>
            </mediaobject>
          </informalfigure>
          <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>
          <para>
            (Note that the pattern editor in piano roll mode (see <xref
            linkend="sect.pattern_editor.piano_mode" />) can also be used to
            change the note value of existing notes)
          </para>
        </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 1.0, a note may be
            randomly skipped: a note with probability 1.0 will
            <emphasis>always</emphasis> be played, a note with
            probability of 0.0 will <emphasis>never</emphasis> be
            played.
          </para>
        </listitem>
      </itemizedlist>
      </para>

      <para>
        Clicking or dragging 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 drag 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 dragging them together. This
              can be useful for creating really consistent quiet grace notes.
            </para>
          </listitem>

        </itemizedlist>
      </para>

      </section>

      <section id="sect.pattern_editor.piano_mode">
      <title>Pattern Editor Piano mode</title>
      <para>Drum mode (see <xref linkend="fig.PatternEditor_DrumMode"/>) focuses on using Hydrogen as a drum machine.
      If you are using Hydrogen as an instrument there is a big chance that the Piano mode is for you.
      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 Note properties Notekey (described above), only here you have a 
      complete piano keyboard, so you don't have to select the octave first.</para>
       <figure id="fig.PatternEditor_PianoMode">
         <title>Pattern Editor in Piano mode</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/PatternEditor_PianoMode.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>
      </section>
     
    </section>


<!-- MIXER -->
    <section id="sect.mixer" xreflabel="Mixer">
      <title>Mixer</title>

      <para>The Mixer window can be opened by pressing Alt+M, by clicking 
      Mixer in the Tools menu, or by clicking the Mixer button on the main toolbar.
      </para>
      <para>The Mixer consists of 3 sections (left>right) : the instrument channel strips, 
      the FX plugin rack and the master fader section.  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.

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

    <section id="sect.mixer.channel_strips">
      <title>Instrument channel strips</title>
       <para>From top to bottom : the 2 top elements on the strip are a 'play' button / 'trig' led combination.
            (
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/btn_play_on_mixer.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>
       )
         The play button lets you trigger the instrument at maximum velocity (handy for checking clipping), 
       and the trig led lights up whenever this instrument is triggered (from the song sequence, 
       or by an external midi controller).  Right of this button/led you will find another led that shows
       you what instrument is currently selected.  This is also the instrument that is selected in the pattern editor.
       As soon as you change one of the settings of a channel strip the instrument will be selected.</para>

       <para>Just below you can find the Mute
       
       <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/btn_mute_on.png" format="PNG" />
        </imageobject>
       </inlinemediaobject>
      
        and Solo
        
       <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/btn_solo_on.png" format="PNG" />
        </imageobject>
       </inlinemediaobject>       

        buttons and the Pan(orama) knob. 
       Note that the Mute and Solo states are also reflected in the Song editor.</para>

      <para>
      Next are 4 pre-fader FX send knobs that determine how much of this instrument will be sent to
      the effect plugins in the FX rack.
      
        <informalfigure id="fig.FX_send_knobs">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/FX_send_knobs.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>
      
      
      
      Just below that you can find an LCD peak-value display,
      and finally the volume fader and VU meter for that instrument.</para>
      <para><emphasis role="bold">IMPORTANT NOTE</emphasis> : keep in mind that the volume and pan settings that you
      find on the Mixer are global settings.  The per-note velocity and pan settings in the Pattern editor
      are settings that are relative to the settings in the Mixer window !</para>


    </section>
    
    <section id="sect.fx_rack_LADSPA">
      <title>FX rack and LADSPA plugins</title>
       <para>The FX rack has 4 bays where you can load a LADSPA effect plugin, but before
        you can load any plugins these must be installed (surprised ?  ;-)</para>
        <para>There are dozens of plugins available for download from various sources :

      <itemizedlist>
        <listitem>
          <para>SWH-Plugins available at <ulink
          url="http://plugin.org.uk">http://plugin.org.uk</ulink>. </para>
          <para>(Note : if you want to compile these plugins
          you need the FFTW tarball from <ulink
          url="http://www.fftw.org">http://www.fftw.org</ulink>)</para>
        </listitem>

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

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

        <listitem>
          <para>Calf plugins <ulink url="http://calf.sourceforge.net/">http://calf.sourceforge.net/</ulink>.</para>
        </listitem>

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

      </itemizedlist>
      </para>
      
      <warning>
        <title>Plugins Kill</title>
        <para>A badly designed LADSPA 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>

      <para>Once you have installed some plugins you can select one by clicking the
      

      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/edit_off.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>

      button.  (if you do not see the FX rack, make sure that the 

      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/showFX_on.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>

      button (in the Master section) is enabled)</para>
      <para>Now the FX selector window will pop up :
      
      <figure id="fig.select_effect">
        <title>Select an Effect</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/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>
           <imageobject>
             <imagedata fileref="img/LADSPA_FX_Properties.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>


      You can select another plugin by clicking the 'Select FX' button. If you quickly want to 
      enable/disable the effect click the 'Deactivate' button (or the Bypass (

      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/bypass_over.png" format="PNG" />
        </imageobject>
        </inlinemediaobject>)

      button in the FX rack).  This can be handy for a quick A/B comparison.</para>
      
      <para>After you have selected the FX and tweaked it's parameters you can use the 
      FX return knob to increase/decrease how much of this FX will be returned to the master output.</para>

    </section>
     
    <section id="sect.master">
      <title>Master section</title>
       <para>
       
      The Master section contains the Master volume fader with VU meters and three global Humanize 
      settings for Velocity, Timing and Swing (in order to add a 'human feel' to the song):
      
     <itemizedlist>
        <listitem>
          <para>Velocity : adds a certain randomness to the note velocity. 
           The higher you turn this knob, the more the velocity will be randomized.
          </para>
        </listitem>

        <listitem>
          <para>Timing : adds a certain randomness to the note timing (lead/lag).  
            The higher you turn this knob, the more the timing will be randomized.
          </para>
          <note><para>Notes are displaced in time (using Gaussian perturbation)
            but the pattern durations or bpm do not change.</para>
          </note>
          
        </listitem>
        
       <listitem>
          <para>Swing : this knob will add a certain amount of swing to the song.</para>
          <note> <para> Swing (a slight time delay) is applied to upbeat 16th-notes,
          and not to 8th-notes as it happens in traditional Jazz.</para> </note>
        </listitem>        
        
     </itemizedlist>
      
      Note that Hydrogen can also be switched to 'per instrument output' mode (see <xref linkend="sect.preferences.audio_tab"/>),
      and in this mode all channel strip outputs will be available in Jack (not just the Master output).  
      This allows you to route the individual instruments directly into any other Jack enabled application (eg Ardour) and gives you
      a lot more flexibility.</para>
      
      <para>On the bottom-right of the Master section the 'FX' button 
        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/showFX_on.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>      
        will show/hide the FX rack, and the 'Peak' button 
       
      <inlinemediaobject>
        <imageobject>
          <imagedata fileref="img/showPeaks_on.png" format="PNG" />
        </imageobject>
      </inlinemediaobject>       
       will enable/disable the VU meters.
       
       <note>
       <para>The VU meter fall off speed can be configured in the preferences window (see <xref linkend="sect.preferences.appearance_tab"/>)</para>
       </note>
       
      </para>
  
      <para>  In the upper part of Master section there is a small "cog" icon button:</para>

        <informalfigure id="mixerSettingsButton">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/mixerSettingsButton.png" format="PNG" />
           </imageobject>
         </mediaobject>
         </informalfigure>
         <para>

         Click it to open the Mixer Settings window:

         <informalfigure id="mixerSettingsDialog">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/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 pan knob and the separate gains of Left and Right 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: <emphasis>linear</emphasis>, <emphasis>polar</emphasis>,
             <emphasis>ratio</emphasis>, <emphasis>quadratic</emphasis>.
             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>
                    <para>Note that some hi-end studio mixers - to be used in well tuned rooms -
                    have center compensation between -3dB and -6dB.
                  </para>
                </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 songfile 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>


    </section>
    
    
    </section>

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

      <para>First of all a little history on the Sound library and Drumkits. Hydrogen began as a 
      dedicated drum machine but has evolved into a versatile 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 Piano mode was added to the pattern editor 
      (see <xref linkend="sect.pattern_editor.piano_mode"/>).</para>
      <para>In this manual (and in other documentation) "Drumkit" and "Soundlibrary" 
      frequently mean the same thing, but not always. The diagram below shows the actual 
      relation between the Soundlibrary and Drumkits:
      <figure id="fig.SoundlibraryHierarchy">
         <title>Soundlibrary/Drumkit hierarchy</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/SoundlibraryHierarchy_V4.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </figure>
      
      As you can see the Soundlibrary contains all Drumkits (System and User drumkits), 
      your saved Patterns and your saved Songs.  Each Drumkit is a collection of a number
      of instruments (snare, kick, sampled voice, bass sound ...) and in its turn an instrument can consist of multiple
      layered samples.  Note that every block has a number of parameters (continue reading for more details).</para>
      <para>This said. let's take a look at the Soundlibrary interface and see what it can do for you:</para>
      <para>The Sound Library saves you time in managing your drum kits,
      favourite patterns, and favourite songs.  When making new songs and new drum
      kits, it allows you to reuse and mix the instruments and patterns from other kits and songs.

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

      <section id="sect.systemdrumkits">
        <title>System Drumkits</title>

        <para>This lists the drumkits that were installed by your system
        administrator.  The location of these System Drumkits 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 users are
        usually not able to add to them.</para>

        <para>To load a drumkit from here, right-click the drumkit and select
        <guimenuitem>Load</guimenuitem>.  This will replace your current drumkit
        with the one that you selected.  To load a single instrument from that
        kit, left-click the <guibutton>plus</guibutton> to the left of the
        drumkit's name to show all the instruments.  With your left mouse
        button, click and drag the instrument into your current kit.  The
        instrument will be added to the drumkit that you currently have
        loaded.</para>
      </section>

      <section id="sect.userdrumkits">
        <title>(Adding) User Drumkits</title>

        <para>These are your own drum kits that you can manage yourself.  They
        are usually stored in <filename
        role="directory">$HOME/.hydrogen/data/drumkits</filename>.  When you are
        creating a new drumkit, you can save it here by selecting
        <menuchoice><guimenu>Instruments</guimenu><guimenuitem>Save
        library</guimenuitem></menuchoice>.</para>

        <para>
        You can import existing drumkits from other users via <menuchoice>
        <guimenu>Instruments</guimenu><guimenuitem>Import library</guimenuitem>
        </menuchoice>.  The Import window will pop up with the Internet tab selected.
        By default the link to the drumkit list (on hydrogen-music.org) will be filled in, 
        and after pressing the 'Update list' button you will get a complete list of all
        drumkits that are available for download.  In the status column you can see
        if a kit is installed or not.

       <figure id="fig.import_drumkit">
         <title>Import Drumkit</title>
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/Sound_Library_import.png" format="PNG" />
           </imageobject>
         </mediaobject>
       </figure>
  
        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 license type.

       <warning>
       <para>If you are using Hydrogen for commercial purposes, (creating songs and 
       selling these on-line or in any other way) you need to pay special attention to the
       license type of the drumkit(s) you are using.
       </para>
       <para>
       If the exact license is not available for a drumkit, do _NOT_ assume that it is a CC (or
       other open and free license type).
       </para>
       <para>
       Even if the kit is CC licensed you should always check with the author before using 
       the kit in your songs.
       </para>
       <para>DISCLAIMER : hydrogen is not responsible for the drumkits that are 
       made available for download by our users, either via the hydrogen-music.org site or
       via any other channel.</para>
       
       </warning>

    
       You can install a drumkit by selecting it and clicking 'Download and Install'.
    
       <informalfigure id="fig.downloading_soundlibrary">
         <mediaobject>
           <imageobject>
             <imagedata fileref="img/Downloading_SoundLibrary.png" format="PNG" />
           </imageobject>
         </mediaobject>
        </informalfigure>
    
       Once the kit has been downloaded it will be available in the Sound Library under "User drumkits".
     
       </para>


      </section>
      <section id="sect.sl.songs">
        <title>Songs in the Sound Library</title>

        <para>To save songs in the Sound Library, put them in your data
        directory underneath the <filename role="directory">songs</filename>
        folder (usually <filename role="directory">$HOME/.hydrogen/data/songs)</filename>.
        To remove them, remove the file from that folder.</para>
      </section>      
      
      <section id="sect.sl.patterns">
        <title>Patterns in the Sound Library</title>

        <para>Before you save a pattern to the sound library, be
        sure to give it a title and a category.  Right-click on the pattern, select
        "<guimenuitem>Properties</guimenuitem>" and enter 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>

        <para>You can add a pattern to the sound library by right
        clicking the title of the pattern in the song editor, and selecting
        "<guimenuitem>Save Pattern</guimenuitem>".  It will now appear in the Sound
        Library underneath "<guilabel>Patterns</guilabel>" and the category that
        you assigned to the pattern.</para>
        </section>
    </section>

    <section id="sect.instrument_editing">
      <title>Drumkits and Instrument Editing</title>


      
      <!-- Need to add an explanation of what the instrument list
           and instrument editor are. -->

      <section id="sect.instrument_editing.concepts">
        <title>Concepts</title>

        <para>
          The synthesizer in Hydrogen is a sample-based synthesizer.  A sample
          is a piece of pre-recorded audio (usually between 0.1 sec and 3 sec).
          To play a note, the sample is simply played back at the right time.
          There are a few concepts and terms that you should understand when you
          are putting together a drumkit.  (See <xref linkend="glossary"/> for
          more detailed explanations.)
        </para>

        <variablelist>
          <title>Sampling Synthesizer Terms</title>
         
          <varlistentry>
            <term>Sample</term><listitem><para>A short recording of a sound,
            typically between 0.1 and 3.0 seconds long.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Gain</term><listitem><para>Volume
            adjustment.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Velocity</term><listitem><para>How hard you hit a
            note.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term> ADSR Envelope Generator</term><listitem><para>An
            Attack/Decay/Sustain/Release envelope generator.  After you trigger
            a note, Hydrogen will <emphasis>attack</emphasis> the note by
            increasing its volume from 0 to the full velocity of the note.
            After reaching full velocity, it will <emphasis>decay</emphasis> the
            note by lowering the volume until it reaches the
            <emphasis>sustain</emphasis> level.  When the note is
            <emphasis>released</emphasis>, Hydrogen reduces the volume from the
            sustain level back down to 0.  See <ulink url="http://en.wikipedia.org/wiki/ADSR_envelope">ADSR
            Envelope</ulink> for more info</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Attack</term><listitem><para>The amount of <emphasis
            role="bold">time</emphasis> to go from 0 to full
            velocity.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Decay</term><listitem><para>The amount of <emphasis
            role="bold">time</emphasis> to go from full velocity to the sustain
            volume.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Sustain</term><listitem><para>The <emphasis
            role="bold">level</emphasis> (how loud) to hold the note between the
            sustain and the release.  It is a percentage of the velocity.  It
            does not depend on time.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>Release</term><listitem><para>The amount of <emphasis
            role="bold">time</emphasis> to go from the sustain volume back down
            to 0.</para></listitem>
          </varlistentry>

        </variablelist>

        <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 MIDI), 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>

      </section>
      <section id="sect.instrument_editing.new_kit">
       <title>Creating a New Drumkit</title>
       <para>In the next paragraphs we will show you how to create a complete drumkit.  
       Keeping in mind the 'Soundlibrary hierarchy' (see <xref linkend="fig.SoundlibraryHierarchy"/>)
       we will use a top-down approach, so we will start at the Drumkit level and work our way 
       down to the samples.</para> 
        
       <para>Creating a new drumkit with Hydrogen is done with the Instrument
       Editor.  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>

       <para>TIP : Instead of creating your own drumkit, you can also use or download
       existing drumkits using the <xref linkend="sect.sound_library"/>.</para>

        <para>Lets make a  brand new drum kit :</para>
        <itemizedlist>
          <listitem><para>select
          <menuchoice>
            <guimenu>Instruments</guimenu>
            <guimenuitem>"Clear All"</guimenuitem>
          </menuchoice>

          .  This will give you a bank of 32 blank instruments.  To delete
          instruments, right-click on on each instrument and select
          "<guimenuitem>Delete Instrument</guimenuitem>".  To add more instruments,
          select

          <menuchoice>
            <guimenu>Instruments</guimenu>
            <guimenuitem>"Add instrument"</guimenuitem>
          </menuchoice>
          .</para>
          </listitem>


          <listitem>
          <para>Select an instrument to start editing it.  This is done by
          left-clicking on the name of the instrument in the instrument list (at
          the left).  You will notice that the name of the instrument in the
          Instrument Editor matches the one that you clicked.</para>
          </listitem>
         
          <listitem>
          <para>Once you have your drum kit working the way you want, select

          <menuchoice>
            <guimenuitem>Instruments</guimenuitem>
            <guimenuitem>"Save library"</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>
         </listitem>

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

         <listitem>
          <para>To export a drumkit (for sharing with others), it must first be
          loaded into your Sound Library.  Then, select

          <menuchoice>
            <guimenuitem>Instruments</guimenuitem>
            <guimenuitem>"Export library"</guimenuitem>
          </menuchoice>

          from the menu.  Select the drum kit that you wish to export, and give it
          a file name to save it to.</para>
          </listitem>
        </itemizedlist>

      </section>
      
      <section id="sect.instrument_editing.parameters">
        <title>Instrument Parameters</title>

        <para>In the instrument editor, click on the
        <guibutton>General</guibutton> button.  Here you can adjust several
        parameters that apply to the instrument (applies to all layers as well).
        
        <figure id="instrumenteditor.general">
        <title>The Instrument editor General view</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/Instrument_General.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </figure>
        
        The parameters are:</para>
        <itemizedlist>
          <listitem>
            <para><emphasis role="bold">Envelope parameters</emphasis>:
            <guibutton>Attack</guibutton>, <guibutton>Decay</guibutton>,
            <guibutton>Sustain</guibutton>, <guibutton>Release</guibutton>.
            (See <xref linkend="def.envelopegenerator"/>)</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Gain</guibutton></emphasis>:
            The overall volume of the instrument.</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Mute
            Group</guibutton></emphasis>: Which mute group this instrument is a
            member of (see <xref linkend="def.mutegroup"/>).</para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Auto Stop-Note</guibutton></emphasis></para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Apply Velocity</guibutton></emphasis></para>
          </listitem>
          <listitem>
            <para><emphasis role="bold">Filter Parameters</emphasis>:
            <guibutton>Byp</guibutton>ass, <guibutton>Cutoff</guibutton>,
            <guibutton>Resonance</guibutton>.</para>
          </listitem>
          <listitem>
            <para>
                <emphasis role="bold">Pitch Shift Parameters</emphasis>:
                <guibutton>Pitch</guibutton>,
                <guibutton>Fine</guibutton>,
                <guibutton>Random</guibutton>     
          </para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Midi out Channel and Note</guibutton></emphasis></para>
          </listitem>
          <listitem>
            <para><emphasis role="bold"><guibutton>Hi-Hat Pressure Group</guibutton></emphasis>:
                Group and Range.
            </para>
          </listitem>
        </itemizedlist>

        <para>It's important that you understand <xref
        linkend="sect.instrument_editing.concepts"/> in order to continue
        on.</para>

        <section id="sect.instrument_editing.envelope_parameters">
          <title>Envelope Parameters</title>

          <para>When the instrument is triggered, its volume is run through an
          ADSR Envelope.  The parameters operate as follows:</para>

          <itemizedlist>
            <listitem>
              <para><emphasis role="bold">Attack</emphasis> &mdash; the amount
              of <emphasis>time</emphasis> that the volume of the sample goes
              from 0 to the full velocity of the note.  If the value is 0, the
              sample will play immediately at full velocity.  If the value is
              1.0, the sample volume will use the maximum time available for the
              attack parameter.
              <footnote id="fn.adsrtimes">
                <para>The attack, decay, and release parameters are all set by
                the number of <emphasis>audio samples</emphasis>.  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
                (typ. 2.27 sec at 44.1 kHz).</para>
              </footnote>
              </para>
            </listitem>
            <listitem>
              <para><emphasis role="bold">Decay</emphasis> &mdash; the amount of
              <emphasis>time</emphasis> for the volume of the sample to go from
              full velocity down to the sustain volume.  If the value is 0, the
              sample will immediately skip from the attack volume to the sustain
              volume.  If the value is 1.0, the sample volume will use the
              maximum time available for the decay parameter.<footnoteref
              linkend="fn.adsrtimes"/></para>
            </listitem>
            <listitem>
              <para><emphasis role="bold">Sustain</emphasis> &mdash; the
              <emphasis>volume</emphasis> to play the note after the decay phase
              is over, and until the note is released.  If set to 0, the note
              will be silent.  If set to 1.0, the note will play at full
              velocity.</para>
            </listitem>
            <listitem>
              <para><emphasis role="bold">Release</emphasis> &mdash; the
              <emphasis>time</emphasis> to fade out the note from the sustain
              volume back down to 0 (silent).  If set to 0, the note will fade
              out in the minimum amount of time (about 5 ms).  If set to 1, it
              will fade out for the maximum time available.<footnoteref
              linkend="fn.adsrtimes"/></para>
            </listitem>
          </itemizedlist>

          <para>If the sample is shorter than the times that you specify, the
          sample will end, regardless of which phase of the ADSR 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 gain (volume)
          parameter during that time.</para>

        </section>

        <section id="sect.instrument_editing.gain_and_mute_group">
          <title>Gain and Mute Group</title>

          <para>The gain sets the overall volume for the sample.  This gain is
          applied after the gain that you set for the layer, and before the gain
          that is set for the mixer.  If the Gain is 0, the instrument will be
          silent.  If the gain is 1.0 the volume of the samples will not be
          adjusted (i.e. 0 dB).  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 clip.  Remember to test the gain with
            full-velocity notes.  If you clip your signal here, it will only get
            worse as Hydrogen processes it.</para>
          </warning>

          <para>Hydrogen provides more mute groups than you know what to do with
          (over 256).  A mute group is a grouping of instruments that are
          mutually exclusive &mdash; only one instrument may be playing at any
          time.  If one is playing and another instrument in the group is
          triggered, it will immediately silence (mute) and start playing the
          other instrument.  This is useful, especially, for instruments like
          hi-hats where the open sound and the closed sound are different
          instruments.</para>

          <para>If the mute group is set to "<guilabel>Off</guilabel>", 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
          1.  To have a snare drum mute group, set their mute group parameters
          to 2.)</para>
        </section>
        
        <section id="sect.instrument_editing.auto_stop_note">
          <title>Auto Stop-Note</title>

          <para>If this box is checked Hydrogen will immediately stop any playing sample that
          belongs to this instrument whenever the instrument is re-triggered.</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>
        </section>
        <section id="sect.instrument_editing.apply_velocity">
          <title>Apply Velocity</title>
          <para>
             This lets the user decide if Hydrogen will apply the note velocity to the sample being played.
          </para>
          <para>
             When activated, Hydrogen will apply the note velocity to the sample gain in addition to the layer gain,
              the instrument gain, the component gain or the instrument volume.
              If all the layer samples are normalized, this option should be used.
                By default this option will be selected as this is the way older version of Hydrogen used to work.
          </para>
          <para>
              When not activated, the note velocity will only be used to select the sample to be played,
              but the sample gain will not be changed.
              This is useful for set of samples that already have their gain "hard-coded".
          </para>
        </section>  

        <section id="sect.instrument_editing.filter">
          <title>Filter parameters</title>

          <para>The filter is a low-pass resonance filter.  If you don't wish to
          use is, click the <guibutton>BYP</guibutton>ass button so that it's
          red.  If it's not red, then the filter is active.  The cutoff
          parameter adjusts the cutoff frequency for the filter.  The resonance
          parameter adjusts how much to resonate the cutoff frequency.  If the
          resonance is set to 0, 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 (0 to 1.0) 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>
        </section>
        
        <section id="sect.instrument_editing.pitch_shift_parameters">
          <title>Pitch Shift parameters</title>
          <para> The first two knobs control the pitch shift offset.
                 You can use it to change the tuning of the instrument.
                "Pitch" is the Coarse control and has quantized steps of half-tones from -24 to +24.
                "Fine" is the Fine control and has quantized steps of cents of half-tones from -0.50 to +0.50.
          </para>
          <para>The "random" parameter allows you to randomly vary the pitch
              of the sample every time it is triggered.  The value is set between 0
              and 1.0.  The pitch change is fairly small, almost always between &plusmn;1 half-steps
              &times; value.  Using this sparingly can help your sequences to sound
              more like a real drummer.
          </para>
        </section>   
        

        <section id="sect.instrument_editing.midi_out_settings">
          <title>Midi out settings</title>

          <para>Hydrogen is capable of generating midi messages that you can use
          to trigger any external midi device or application.  To do this you
          simply need to configure the Midi out channel and Note for every
          instrument.  You need to have a sample loaded (an empty WAV file is
          fine) and make sure the proper Midi routing/wiring is in place and
          you're set.  As you can see this is a very flexible approach that
          enables you to trigger samples or sounds from multiple devices and/or
          apps.</para>

          <para>From now on every time a note is played for that instrument (in the Hydrogen sequencer) 
          a midi 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>

        </section>
        <section id="sect.instrument_editing.HH_pressure_group">
          <title>Hi-Hat Pressure Group</title>
            <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-drummer owner, the hihat pressure group enables to group different hihat instruments
                together, for example closed, half closed, fully open.
            </para>
            <para>Pressure Group: 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 hihat 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>Range: 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 0 to 20,
               when the hi-hat pedal is pressed between 0 and 20 the closed hi-hat is played.
            </para>

        </section>      
        
      </section>
      
      
      <section id="sect.instrument_editing.new_instrument">
        <title>Creating an Instrument and Layers</title>

        <para>For each instrument in a drum kit, you can load several samples
        and set different synthesizer parameters.  This section will step you
        through how to create a new instrument and load the samples.</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.  Any .WAV or .FLAC file will do.
        Hydrogen provides several in the <filename
        class="directory">data/drumkits</filename> directory.</para>

        <para>In the instrument editor, click on <guibutton>Layers</guibutton>.
        You can layer several samples into the instrument.  Which one is played
        depends on the velocity of the incoming note.  Click <guibutton>Load
        Layer</guibutton> and point the <guimenu>Audio File Browser</guimenu> to
        your sample.  Note that the <guimenu>Audio File Browser</guimenu> 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>

        <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 <guibutton>Load Layer</guibutton> 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
        left-right drag cursor.  Now drag the sample to the left or right (like
        a curtain).  You will now see Layer 2 appear.</para>
        
        <figure id="instrumenteditor.layers">
        <title>The Instrument editor Layers view</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/Instrument_Layers.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </figure>

        <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).</para>

        <para>Now, in the pattern area, set up a simple pattern that plays this
        instrument.  Adjust the velocity settings on each note so that you can
        get the different samples to sound.  Now set the pattern to loop and
        notice how your different samples are getting triggered.  (To learn
        about editing a pattern, see <xref
        linkend="sect.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 <guibutton>Gain</guibutton> adjustment to control how loud
        the sample will play.  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).
        <!--
            TODO what is the difference between gain and volume here? 
        -->
        </para>

        <warning>
          <para>It is very easy to set the <guibutton>Gain</guibutton> too high,
          causing your sample to clip.  Remember to test the gain with
          full-velocity notes.  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, -12 is down 1 octave).  The pitch on the right adjusts
        the pitch &plusmn;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 -12 (1 octave), your sample will
          only last for 0.5-seconds.  If you do not want this to happen you should
          use rubberband instead (see <xref linkend="sect.layer_editing.section2"/>)</para>
        </note>

        <para>You can hear the sample in a layer by clicking the layer id (just 
        below the 'General' and 'Layers' buttons) and the 'Delete Layer' button 
        will delete the currently selected layer.</para>
        <section id="sect.instrument_editing.new_instrument.sample_selection">
          <title>Sample Selection</title>
            <para>
                Certain set of samples contain different sample versions of the same sound for the same note/velocity
                in order to make it more natural - drummers for example never hit the drum set twice the same way.
                This functionality is making Hydrogen compatible with this type of sample collection.
            </para>
            <informalfigure id="fig.sample_selection">
             <mediaobject>
               <imageobject>
                <imagedata fileref="img/Instrument_Layers_sampleSelection.png" format="PNG" />
               </imageobject>
             </mediaobject>
            </informalfigure>
                    
            <para>
                To use this functionality, you need to first a few samples that share the same velocity range in Hydrogen.
                The second step is to select how Hydrogen will chose the sample when a note within a certain velocity
                is played.
            </para> 
            <itemizedlist>
                <listitem>
                   <para> <emphasis role="bold">First in Velocity</emphasis> &mdash;
                       will select the first sample available in the velocity set.
                       This is the way previous versions of Hydrogen were working.
                    </para> 
                </listitem>
                <listitem>
                   <para> <emphasis role="bold">Round Robin</emphasis> &mdash;
                      will cycle through the different samples one after another as note in the same velocity range is played.
                   </para> 
                </listitem>
                <listitem>
                   <para> <emphasis role="bold">Random</emphasis> &mdash;
                      will select a random sample inside the velocity range for each note played.
                   </para> 
                </listitem>
            </itemizedlist>
        </section>

        
        

      </section>

      <section id="sect.layer_editing">
        <title>Sample Editor</title>
        <para>So far we have created a multilayered Drumkit, set a number of 
        instrument parameters, played with velocity settings and so on.  Now it's 
        time to go one step deeper and edit the samples using one of the newest
        Hydrogen features: the Sample Editor.</para>
        <para>The Sample Editor allows you to tweak and manipulate your samples.
        This is a function that will really speed up the creation of a drumkit since
        you can do the fine-tuning of the sample within Hydrogen. In pre-0.9.5 builds
        the typical workflow would be to prepare your sample in an external sound editor,
        import the sample in Hydrogen, test it, go back to the audio editor, import again, 
        test ...  The sample editor allows you to do most of the sample manipulation 
        within Hydrogen.  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>
        
        <figure id="sample.editor">
        <title>The Sample Editor</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/SampleEditor_V5.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </figure>        
        
        <para>The Sample Editor consists of 3 sections (as indicated in the figure above):</para>
       
        <section id="sect.layer_editing.section1">
        <title>Sample Editor in/out points</title>
        <para>
        In this section you can set the start, stop and loop points for the sample by dragging the 
        the 3 markers:
        <itemizedlist>
          <listitem><para>S-marker (green) : indicates the Start-point (in-point) of the sample.</para></listitem>
          <listitem><para>E-marker (red) : indicates the End-point (out-point) of the sample.</para></listitem>
          <listitem><para>L-marker (blue) : determines the loop-in point of your sample</para></listitem>
        </itemizedlist>
        You can easily move one of the markers by grabbing them close to the
        letter that marks them.  Whenever you grab one of the markers you will see a detail
        view of the position of that marker on the second (smaller) window on the right, making it easy to 
        find the zero-crossings in the sample.  This detail window also has a slider 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>
        <para>Underneath these 2 windows you can find (from left>right) : the position of the Start
        marker, the position of the Loop marker, the Loop mode, the number of loops and the
        position of the End marker.  The position of the markers is expressed in number of
        samples from the very beginning of the sample.  These values will change if you drag 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>
        <para>Apart from the marker positions there are 2 settings that apply to the Sample
        Editor's loop function: loop mode and loop number.  With the loop function you can
        repeat the part of your sample <emphasis>that is in between the Loop- and the 
        End-marker</emphasis>. The way it is looped is determined by the Loop mode 
        (forward, reverse or ping-pong) and the number of times it is looped is determined
        by the Loop number.</para>
        <para>If you want to hear a preview of the tweaking you have done so far, you first need to
        press the 'Apply Changes' button (@ the bottom of section 3) and then the Play button to
        hear the result.</para>
        </section>
        
        <section id="sect.layer_editing.section2">
        <title>Sample Editor rubberband</title>
        <para>This section of the Sample Editor allows you to control the Rubberband settings.
        Rubberband is a tool that can change the tempo of a sample without changing 
        the sample's pitch (and vice versa).</para>
        <para>If you are using Ubuntu you can install rubberband from the Software Center 
        (rubberband-cli).  For other linux distros check your package manager.  For other platforms
        please check <ulink url="http://breakfastquay.com/rubberband/">the rubberband site
        </ulink>.  After installing rubberband you should check if the path to the rubberband cli is 
        configured correctly (see <xref linkend="sect.preferences.general_tab"/>).</para>
        
        <para>If rubberband is installed correctly you will have access to the rubberband 
        settings, and an extra button named 'RUB' will be available in the Main Toolbar,
        right of the BPM LCD display:
        
       <informalfigure id="rubberband_button">
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/MainControls_Rubberband_btn.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </informalfigure>                
        
        </para>
        <para>Back to the rubberband settings : 
        <itemizedlist mark="opencircle">
         <listitem><para>Sample length to beat : when set to 'off', rubberband functionality is disabled. 
         Normally this parameter should be set to the length of the part of the sample between 
         the Start and End marker, expressed in number of beats.</para>
         </listitem>
         <listitem><para>Pitch : this setting allows you to change the pitch of the sample, expressed in 
         semitones,cent.</para>
         </listitem>
         <listitem><para>Crispness : this setting does not affect tempo or pitch, but changes the way
         the sample sounds.</para>
         </listitem>
        </itemizedlist>
        </para>
        <para><emphasis role="bold">Note</emphasis>: If you want Hydrogen to recalculate the sample length on the fly (using rubberband)
        you must enable the 'RUB' button (see figure above).</para>
        
        </section>
        
        
        <section id="sect.layer_editing.section3">
        <title>Sample Editor volume/pan</title>
        <para>In the bottom section of the Sample Editor you can see the end result 
        of the tweaks you have made by pressing the Apply Changes button.  You can
        also change the the Volume and Panorama (Pan) of your sample here.
        This is done by creating 'envelopes' like the 
        ones you find in numerous DAW's for automation.  To edit an
        envelope you first need to select 'Volume' or 'Panorama'in the upper right 
        corner of section 3.  The Volume envelope is blue, and the pan envelope is yellow.
        Left clicking in the bottom window will ad a node to an envelope and also 
        allows you to drag an existing node.  Right-clicking a node will delete it. 
        Don't forget to Apply Changes before you play your tweaked sample.</para>
        </section>
        
      </section>
      
      <section id="sect.instrument_editing.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 &mdash; which means the signal gets
        distorted by clipping.  In addition, if you have two samples that, by
        themselves, peg your meters &mdash; 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 LADSPA 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:
        clipping.</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 &mdash; 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>

      </section>
    </section>

   
    
    <section id="sect.midi">
      <title>Midi</title>
      
      <para>In this section you can find more info about defining MIDI actions 
       and how they can be useful for you.  Before you can work with midi actions
       you should have your Midi devices, drivers and connections configured
       correctly (see <xref linkend="sect.preferences.midi_tab"/>).
      </para>

      <para>Lets take a look at the available options :
      <informalfigure id="midi_actions">
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/Midi_Actions.png" format="PNG" />
          </imageobject>
        </mediaobject>
        </informalfigure>                
      </para>

      <section id="sect.midi.events">
        <title>Midi Events</title>

        <para>An Event is an incoming Midi message, coming from a MIDI controller or 
        an external sequencer.</para>
        <para>If you look at the Events list you will see that there are 3 types of Events 
        available (as described in the Midi standard): </para>

        
        <itemizedlist mark="opencircle">

         <listitem><para>
	         <emphasis role="bold">NOTE</emphasis>: input coming from a regular black/white key of a keyboard or a drumpad
	       </para></listitem>
	     
         <listitem><para>
	         <emphasis role="bold">CC</emphasis>: controller commands coming from faders or rotary controllers
	       </para></listitem>
	     
         <listitem><para>
	         <emphasis role="bold">MMC_x</emphasis>: <ulink url="http://en.wikipedia.org/wiki/MIDI_Machine_Control">
	         machine control events</ulink> coming from play/stop... buttons on a controller
	       </para></listitem>
	     
        </itemizedlist>
        
        
       <para>
       The Param. (parameter) value to the right of the Event is the identifier of the note/button/controller
       that is linked to this Action.  This parameter can be entered manually, or automatically by 
       using the Midi learn function (see <xref linkend="sect.preferences.midi_tab"/>).
       </para>       
       
       <note><para>You can also activate the Midi learn function by Shift-clicking most of the gui elements.  
       A 'Waiting for Midi input...' popup informs you that Hydrogen is now waiting for you to press
       a key or turn/move a controller.
       </para>
       <para>If you Shift-click on a gui element that does not support Midi automation a popup will
       inform you.
       </para></note>
       
        
       </section>
       

      <section id="sect.midi.actions">
        <title>Midi Actions</title>

        <para>Next is a list of the available Actions: an Action describes what Hydrogen should do 
        when a specific Midi Event is detected.</para>
        
        <note><para>** Some of the Midi Actions require that the Action Parameter is configured.  The
        Parameter usually references a specific channel, instrument, FXsend...  Keep in mind that the 
        Parameter value is <emphasis>zero-based</emphasis>. So if you want to reference channel 1 you 
        have to enter '0' in the Parameter field (1 for channel 2, 2 for channel 3 ...)</para></note>


      <itemizedlist mark="opencircle">
      <listitem><para>
	      <emphasis role="bold">PLAY</emphasis> : start playback
	    </para></listitem>
	    
      <listitem><para>
        <emphasis role="bold">PLAY/STOP_TOGGLE</emphasis> : toggles between PLAY and STOP.  Execute this action will 
        start playback, execute it again and playback will stop + the playhead will return
        to the start of the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">PLAY/PAUSE_TOGGLE</emphasis> : toggles between PLAY and PAUSE.  (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">STOP</emphasis> : stops playback and returns to the start of the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">PAUSE</emphasis> : pauses the song
	    </para></listitem>
	    
      <listitem><para>
        <emphasis role="bold">MUTE</emphasis> : mutes the the Master output (sequencer keeps running)
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">UNMUTE</emphasis> : unmutes the Master output (sequencer keeps running)
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">MUTE_TOGGLE</emphasis> : toggles between MUTE and UNMUTE (sequencer keeps running)
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">NEXT_BAR</emphasis> : jumps to the next bar in the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">PREVIOUS_BAR</emphasis> : jumps to the previous bar in the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">BPM_INCR</emphasis> : increments the tempo of the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">BPM_DECR</emphasis> : decrements the tempo of the song
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">BPM_CC_RELATIVE</emphasis> : changes the tempo relative to the current tempo, using a controller
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">MASTER_VOLUME_RELATIVE</emphasis> : changes the Master output volume, relative
	      to the current setting (e.g. if you are using rotary encoders)
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">MASTER_VOLUME_ABSOLUTE</emphasis> : changes the Master output volume to the 
	      absolute value of the midi control (use with midi fader or pot)
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">STRIP_VOLUME_RELATIVE</emphasis> : see MASTER_VOLUME_RELATIVE, but applies to
	      the channel strip defined in the Action Parameter **
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">STRIP_VOLUME_ABSOLUTE</emphasis> : see MASTER_VOLUME_ABSOLUTE, but applies to
	      the channel strip defined in the Action Parameter **
	    </para></listitem>
	    
      <listitem><para>
        <emphasis role="bold">EFFECTx_LEVEL_RELATIVE</emphasis> : changes the volume level of effect 'x';
         the value you enter in the Action Parameter determines the channel strip this action applies to **
      </para></listitem>
	    
      <listitem><para>
        <emphasis role="bold">SELECT_NEXT_PATTERN</emphasis> : selects the pattern that is defined in the Action Parameter **
      </para></listitem>
	    
      <listitem><para>
        <emphasis role="bold">SELECT_AND_PLAY_NEXT_PATTERN</emphasis> : combines the SELECT_NEXT_PATTERN with PLAY
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">PAN_RELATIVE</emphasis> : changes the panorama setting, relative to the current value;
         the value you enter in the Action Parameter determines the channel strip this action applies to **
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">PAN_ABSOLUTE</emphasis> : changes the panorama setting to the absolute value that the linked controller sends to Hydrogen
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">BEATCOUNTER</emphasis> : sets the tempo (see <xref linkend="sect.tap_tempo"/>
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">TAP_TEMPO</emphasis> : sets the tempo (see <xref linkend="sect.tap_tempo"/>
	    </para></listitem>
	    
      <listitem><para>
	      <emphasis role="bold">SELECT_INSTRUMENT</emphasis> : selects one of the instruments in the drumkit
	    </para></listitem>
	    
   
      </itemizedlist>


     </section>

   </section>
	<section id="sect.osc">
		<title>OSC</title>
		<para>Open Sound Control (OSC) 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 MIDI 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>

        <para>Hydrogen is able to receive OSC messages. This allows you to
        control it using various devices, like hardware OSC controllers,
        smartphones, tablets, or any PC. For Linux-based systems you can test
        these interactions using the command line program
        <emphasis>oscsend</emphasis> and Hydrogen's port number you can find in the OSC tab in the Preferences dialog. </para>

        <para><emphasis>oscsend localhost 9000 /Hydrogen/NEW_SONG s /tmp/new.h2song</emphasis></para>
		
		<para>To enable OSC support in Hydrogen, open the Preferences dialog and switch to the OSC tab. Make sure that the "Enable OSC support" checkbox is activated, otherwise Hydrogen will not listen for 
			incoming OSC messages.</para>
              
            <section id="sect.osc.messages">
              <title>Controlling Hydrogen via OSC</title>
              <para>If you want to control Hydrogen via OSC, you may send messages to the following addresses:
              <itemizedlist>
                <listitem><para>/Hydrogen/STRIP_VOLUME_ABSOLUTE/</para></listitem>
                <listitem><para>/Hydrogen/PAN_ABSOLUTE/</para></listitem>
                <listitem><para>/Hydrogen/FILTER_CUTOFF_LEVEL_ABSOLUTE/</para></listitem>
                <listitem><para>/Hydrogen/STRIP_MUTE_TOGGLE/</para></listitem>
                <listitem><para>/Hydrogen/STRIP_SOLO_TOGGLE/</para></listitem>
                <listitem><para>/Hydrogen/PLAY</para></listitem>
                <listitem><para>/Hydrogen/PLAY_STOP_TOGGLE</para></listitem>
                <listitem><para>/Hydrogen/PLAY_PAUSE_TOGGLE</para></listitem>
                <listitem><para>/Hydrogen/STOP</para></listitem>
                <listitem><para>/Hydrogen/PAUSE</para></listitem>
                <listitem><para>/Hydrogen/RECORD_READY</para></listitem>
                <listitem><para>/Hydrogen/RECORD_STROBE</para></listitem>
                <listitem><para>/Hydrogen/RECORD_STROBE_TOGGLE</para></listitem>
                <listitem><para>/Hydrogen/RECORD_EXIT</para></listitem>
                <listitem><para>/Hydrogen/MUTE</para></listitem>
                <listitem><para>/Hydrogen/MUTE_TOGGLE</para></listitem>
                <listitem><para>/Hydrogen/UNMUTE</para></listitem>
                <listitem><para>/Hydrogen/NEXT_BAR</para></listitem>
                <listitem><para>/Hydrogen/PREVIOUS_BAR</para></listitem>
                <listitem><para>/Hydrogen/BPM_INCR</para></listitem>
                <listitem><para>/Hydrogen/BPM_DECR</para></listitem>
                <listitem><para>/Hydrogen/MASTER_VOLUME_ABSOLUTE</para></listitem>
                <listitem><para>/Hydrogen/MASTER_VOLUME_RELATIVE</para></listitem>
                <listitem><para>/Hydrogen/STRIP_VOLUME_RELATIVE</para></listitem>
                <listitem><para>/Hydrogen/SELECT_NEXT_PATTERN</para></listitem>
                <listitem><para>/Hydrogen/SELECT_NEXT_PATTERN_PROMPTLY</para></listitem>
                <listitem><para>/Hydrogen/SELECT_AND_PLAY_NEXT_PATTERN</para></listitem>
                <listitem><para>/Hydrogen/BEATCOUNTER</para></listitem>
                <listitem><para>/Hydrogen/TAP_TEMPO</para></listitem>
                <listitem><para>/Hydrogen/PLAYLIST_SONG</para></listitem>
                <listitem><para>/Hydrogen/PLAYLIST_NEXT_SONG</para></listitem>
                <listitem><para>/Hydrogen/PLAYLIST_PREV_SONG</para></listitem>
                <listitem><para>/Hydrogen/TOGGLE_METRONOME</para></listitem>
                <listitem><para>/Hydrogen/SELECT_INSTRUMENT</para></listitem>
                <listitem><para>/Hydrogen/UNDO_ACTION</para></listitem>
                <listitem><para>/Hydrogen/REDO_ACTION</para></listitem>
                <listitem><para>/Hydrogen/NEW_SONG s /full/path/to/new.h2song</para></listitem>
                <listitem><para>/Hydrogen/OPEN_SONG s /full/path/to/existing.h2song</para></listitem>
                <listitem><para>/Hydrogen/SAVE_SONG</para></listitem>
                <listitem><para>/Hydrogen/SAVE_SONG_AS s /full/path/to/copy.h2song</para></listitem>
                <listitem><para>/Hydrogen/QUIT</para></listitem>
                <listitem><para>/Hydrogen/TIMELINE_ACTIVATION i 0</para></listitem>
                <listitem><para>/Hydrogen/TIMELINE_ADD_MARKER if 1 120</para></listitem>
                <listitem><para>/Hydrogen/TIMELINE_DELETE_MARKER i 1</para></listitem>
                <listitem><para>/Hydrogen/JACK_TRANSPORT_ACTIVATION i 0</para></listitem>
                <listitem><para>/Hydrogen/JACK_TIMEBASE_MASTER_ACTIVATION i 0</para></listitem>
                <listitem><para>/Hydrogen/SONG_MODE_ACTIVATION i 0</para></listitem>
                <listitem><para>/Hydrogen/LOOP_MODE_ACTIVATION i 0</para></listitem>
                <listitem><para>/Hydrogen/RELOCATE i 4</para></listitem>
              </itemizedlist>

                For more information about the actions invoked, please see the
                corresponding documentation in the source code.
			</para>
		</section>
		<section id="sect.osc.feeback">
			<title>Sending OSC feedback to other applications</title>
			<para>
				Hydrogen is able notify other applications via OSC if a
				parameter changes, for example if a fader has been moved. It
				does not matter at this point if the fader has been moved via
				the GUI, an incoming OSC message or via MIDI.
            </para>
            <para>
				To enable/disable OSC feedback, a checkbox exists on the OSC tab
				of the Preferences dialog. If the checkbox is enabled, Hydrogen
				sends out OSC feedback messages to all OSC client, which are
				known to Hydrogen.
            </para>
			<para>
				Clients are registered automatically by Hydrogen upon the first
				message received from the client.
			</para>
            <para>
              The OSC messages send by Hydrogen will be associated with the
              following paths
              <itemizedlist>
		        <listitem><para>/Hydrogen/MASTER_VOLUME_ABSOLUTE</para></listitem>
		        <listitem><para>/Hydrogen/TOGGLE_METRONOME</para></listitem>
		        <listitem><para>/Hydrogen/MUTE_TOGGLE</para></listitem>
		        <listitem><para>/Hydrogen/STRIP_VOLUME_ABSOLUTE/[x]</para></listitem>
		        <listitem><para>/Hydrogen/PAN_ABSOLUTE/[x]</para></listitem>
		        <listitem><para>/Hydrogen/STRIP_MUTE_TOGGLE/[x]</para></listitem>
		        <listitem><para>/Hydrogen/STRIP_SOLO_TOGGLE/[x]</para></listitem>
              </itemizedlist>
              The last part [x] of the URI specifies a particular instrument.
            </para>
		</section>
	</section>
  </chapter>

  <!--
      ##################
      # THIRD CHAPTER  #
      ##################
  -->

  <chapter id="chap.create_song">
    <title>A new song</title>
    <section id="sect.song_vs_pattern">
      <title>"Song" mode and "Pattern" mode</title>

      <para>This section is a quick-and-dirty walkthrough to Hydrogen. Refer to the
      tutorial for a more detailed overview.</para>

      <para>Hydrogen has 2 main modes: "Pattern" mode and "Song" mode (refer to
      <xref linkend="sect.main_toolbar"/> for the buttons that activate each mode). When
      "Pattern" mode 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 "Song" mode the whole song is played.  
      This is useful when putting together the patterns to create the structure of the song.</para>
    </section>

    <section 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: "pattern" mode should be selected by default. Now
      let's click on the <quote>Play</quote>button, and while the pattern is playing
      let's add notes by left_mouse_clicking in the grid of the Song Editor 
      (<xref linkend="fig.pattern_editor.2"/>). Adjust the grid resolution and BPM
      speed if needed. Remember some constraints of the grid: if you are
      working with a resolution of 16 you can't go back to 8 and remove a
      16th note; same thing happens if you are working with a resolution of
      8 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 <quote>off</quote> from the Grid Resolution LCD in which case
      you're free to place notes wherever you prefer). <emphasis role="bold">Be
      sure to select the correct pattern in the Song Editor before adding notes
      in the Pattern Editor!</emphasis></para>

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

    <section 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 Select Mode (see <xref linkend="sect.song_editor.main_controls"/>).
      </para>

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

    </section>

    <section id="sect.create_song.adjust_mixer">
      <title>Adjust from the mixer</title>

      <para>Of course we can always use the mixer window, either when creating
      or playing patterns.</para>

      <para>The Mixer frame (<xref linkend="fig.mixer.2"/>) is made of 32
      independent tracks, each of these is bound to an instrument, plus a
      "Master Output" control and a "FX" button to show and hide the 
      effects panel.
      Every line features 3 buttons (

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/btn_play_on_mixer.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/btn_solo_on.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/btn_mute_on.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        ), pan adjust (

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/MixerPan.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

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

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/btn_solo_on.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

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

        <inlinemediaobject>
          <imageobject>
            <imagedata fileref="img/btn_mute_on.png" format="PNG" />
          </imageobject>
        </inlinemediaobject>

        , simply mute <emphasis>that</emphasis> instrument. The maximum peak
        indicates the maximum volume reached from the instrument.   The peak must
        be in a range of 0.0 and 1.0 (in <xref linkend="fig.mixer.2"/> you can
        see a few volumes too loud).  Peaks outside that range will get distorted 
        (especially with OSS audio driver). Keep an eye on each vu-meter and
        if distortion appears, turn the volume down for that instrument.
      </para>

      <figure id="fig.mixer.2">
        <title>The Mixer</title>
        <mediaobject>
          <imageobject>
            <imagedata fileref="img/Mixer.png" format="PNG" />
          </imageobject>
        </mediaobject>
      </figure>
    </section>
  </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>[CTRL] + [N]</entry>
            <entry>New Project</entry>
          </row>
          <row>
            <entry>[CTRL] + [O]</entry>
            <entry>Open File</entry>
          </row>
          <row>
            <entry>[CTRL] + [D]</entry>
            <entry>Open Demo</entry>
          </row>
          <row>
            <entry>[CTRL] + [S]</entry>
            <entry>Save Song</entry>
          </row>
          <row>
            <entry>[CTRL] + [SHIFT] + [S]</entry>
            <entry>Save Song as</entry>
          </row>
          <row>
            <entry>[CTRL] + [P]</entry>
            <entry>Export Pattern as</entry>
          </row>
          <row>
            <entry>[CTRL] + [M]</entry>
            <entry>Export MIDI file</entry>
          </row>
          <row>
            <entry>[CTRL] + [E]</entry>
            <entry>Export Song (see <xref linkend="sect.song_editor.export_song"/>)</entry>
          </row>
          <row>
            <entry>[CTRL] + [L]</entry>
            <entry>Export LilyPond file</entry>
          </row>
          <row>
            <entry>[CTRL] + [Q]</entry>
            <entry>Quit Hydrogen</entry>
          </row>
          <row>
            <entry>[CTRL] + [Z]</entry>
            <entry>Undo an action</entry>
          </row>
          <row>
            <entry>[CTRL] + [SHIFT] + [Z]</entry>
            <entry>Redo an action</entry>
          </row>
          <row>
            <entry>[ALT] + [D]</entry>
            <entry>Show Director (see <xref linkend="sect.song_editor.director"/>)</entry>
          </row>
          <row>
            <entry>[ALT] + [M]</entry>
            <entry>Show Mixer (see <xref linkend="sect.mixer"/>)</entry>
          </row>
          <row>
            <entry>[ALT] + [I]</entry>
            <entry>Show Instrument rack (see <xref linkend="sect.sound_library"/>)</entry>
          </row>
          <row>
            <entry>[ALT] + [A]</entry>
            <entry>Show Automation path</entry>
          </row>
          <row>
            <entry>[ALT] + [F]</entry>
            <entry>Toggle fullscreen mode</entry>
          </row>
          <row>
            <entry>[CTRL] + [ALT] + [I]</entry>
            <entry>Set Input mode to Instrument</entry>
          </row>
          <row>
            <entry>[CTRL] + [ALT] + [D]</entry>
            <entry>Set Input mode to Drumkit</entry>
          </row>
          <row>
            <entry>[ALT] + [P]</entry>
            <entry>Show Preferences (see <xref linkend="sect.preferences"/>)</entry>
          </row>
          <row>
            <entry>[ALT] + [?]</entry>
            <entry>Show Manual</entry>
          </row>
          <row>
            <entry>[Backspace]</entry>
            <entry>Restart song or pattern from the beginning</entry>
          </row>
          <row>
            <entry>[Space]</entry>
            <entry>Play / Pause</entry>
          </row>
          <row>
            <entry>[CTRL] + [Space]</entry>
            <entry>Play / Pause at the current cursor position</entry>
          </row>
          <row>
            <entry>[,]</entry>
            <entry>Use Beatcounter (see <xref linkend="sect.tap_tempo"/>)</entry>
          </row>
          <row>
            <entry>[\]</entry>
            <entry>Use Tap Tempo (see <xref linkend="sect.tap_tempo"/>)</entry>
          </row>
          <row>
            <entry>[+]</entry>
            <entry>Increase tempo by 0.1 BPM</entry>
          </row>
          <row>
            <entry>[-]</entry>
            <entry>Decrease tempo by 0.1 BPM</entry>
          </row>
          <row>
            <entry>[F5]</entry>
            <entry>Jump to previous song in playlist</entry>
          </row>
          <row>
            <entry>[F6]</entry>
            <entry>Jump to next song in playlist</entry>
          </row>
          <row>
            <entry>[F9]</entry>
            <entry>Jump to previous bar in the song</entry>
          </row>
          <row>
            <entry>[F10]</entry>
            <entry>Jump to next bar in the song</entry>
          </row>
          <row>
            <entry>[F12]</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>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 ADSR envelope, and is the amount
        of <emphasis>time</emphasis> to turn the parameter up from
        0 to full velocity after triggering the note.</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 the signal 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.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 reaching full velocity from the attack, this is the amount
        of <emphasis>time</emphasis> to turn the parameter down from full
        velocity to the sustain level.</para>

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

    <glossentry id="def.dc-offsety">
      <glossterm>DC-offsety</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
        normalized (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>
      </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 &mdash; 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 (samples) that should mute (stop playing)
        immediately after another instrument in the group is triggered.</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 &mdash; 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   -->

    <!--   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   -->

    <!--   Q   -->

    <!--   R   -->

    <glossentry id="def.release">
      <glossterm>Release</glossterm>
      <glossdef>
        <para>After the note is released, this is the amount of
        <emphasis>time</emphasis> to reduce the parameter from the sustain 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.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.</para>
      </glossdef>
    </glossentry>

    <glossentry id="def.sustain">
      <glossterm>Sustain</glossterm>
      <glossdef>
        <para>The <emphasis>level</emphasis> to hold the parameter after
        finishing the decay time.  This level will be maintained until the not
        is released.</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>MIDI 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>
</book>