root/trunk/data/new_manual/index.html @ 308

Revision 308, 36.3 KB (checked in by smoors, 5 years ago)

added new manual
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 
3<head>
4<style type="text/css">
5        img { border: none; }
6        table { border: 1px solid blue; }
7        td { border: 1px solid #5aaaff; padding: 4px; margin: 4px; }
8        .tdcenter { text-align: center; }
9        .tdleft { text-align: left; width: 200px; }
10        .titlechapter { /* margin: 0px 0px 0px 0px; */ font-size: 200%; font-weight: bold; background-color: #5858d0;}
11        .subchapter { background-color: red;}
12        .subsubchapter { background-color: green;}
13        .center { text-align: center; }
14        .imagecenter { padding: 15px; text-align: center; }
15        .note { color: red; font-weight: bold; }
16        .menu { list-style-type: none; }
17        .warn { font-weight: bold; border: 1px solid red; padding: 20px; margin: 20px;}
18        .desc { font-size: 90%;}
19</style>                         
20<title>Hydrogen Manual</title>
21</head>
22<body>
23
24<h1 id="top">Hydrogen Manual</h1>
25
26<h3>Antonio Piraino<br />Alessandro Cominu</h3>
27
28Hydrogen is a software synthetizer which can be used alone, emulating a drum machine based on patterns, or via an external MIDI keyboard/sequencer software. Hydrogen compiles on Linux/x86 and MAC OSX, although the latter is still experimental, so ask in the developers mailing list for further details.
29
30<h4>Table of contents</h4>
31<ol class="menu">
32        <li><a href="#chap1">Chapter 1: Getting started</a></li>
33        <li>
34                <ol style="list-style-type: arabic;">
35                        <li><a href="#download">Download</a></li>
36                        <li><a href="#build">Build</a></li>
37                        <li><a href="#audio">Audio driver configuration</a></li>
38                        <li><a href="#files">Files used</a></li>
39                </ol>
40        </li>
41        <li><a href="#chap2">Chapter 2: Using Hydrogen</a></li>
42        <li>
43       <ol style="list-style-type: arabic;">
44            <li><a href="#menu">Menu</a></li>
45                        <li class="menu">
46                                <ul class="menu">
47                                        <li><a href="#prefs">Audio preferences</a></li>
48                                        <li><a href="#engine">Audio engine info</a></li>
49                                </ul>
50                        </li>
51                        <li><a href="#toolbar">The main toolbar</a></li>
52                        <li><a href="#seditor">Song editor</a></li>
53                        <li><a href="#peditor">Pattern editor</a></li>
54                        <li><a href="#mixer">Mixer</a></li>
55        </ol>
56        </li>
57        <li><a href="#chap3">Chapter 3: Extending Hydrogen</a></li>
58        <li>
59       <ol style="list-style-type: arabic;">
60                        <li><a href="#rack">Instruments and sound libraries</a></li>
61                        <li><a href="#ladspa">LADSPA plugins</a></li>
62                        <li><a href="#playlist">Playlist editor</a></li>
63                        <li><a href="#support">Support and troubleshooting (TODO)</a></li>
64        </ol>
65        </li>
66</ol>
67
68<hr /><br />
69<div class="titlechapter" id="chap1">Chapter 1: Getting started</div>
70<div style="text-align: right;"><a href="#top">[TOP]</a></div>
71
72<h2 class="subchapter" id="download">Download</h2>
73The latest stable version of hydrogen is available at <a target="new" href="http://www.hydrogen-music.org/?p=download">http://www.hydrogen-music.org</a>.<br /><br />
74
75You can download precompiled packages for the following Linux distributions and systems:
76<ul>
77        <li>Slackware </li>
78        <li>Ubuntu</li>
79        <li>MacOSX</li>
80</ul>
81
82Ensure your host meets the following system requirements:
83<ul>
84        <li><a target="new" href="http://trolltech.com">QT libraries</a> (&gt;= 4.x)</li>
85        <li><a target="new" href="http://jackit.sf.net">JACK Audio Connection Kit</a> (&gt;= 0.80)</li>
86        <li><a target="new" href="http://www.alsa-project.com">ALSA</a> (&gt;= 1.x)</li>
87        <li><a target="new" href="http://www.mega-nerd.com/libsndfile">libsndfile</a></li>
88        <li>(optional) <a target="new" href="http://www.portaudio.com">PortAudio</a></li>
89        <li>(optional) <a target="new" href="http://flac.sf.net">flac</a></li>
90        <li>(optional) <a target="new" href="htt://www.ladspa.org">ladspa</a></li>
91        <li>(optional) <a target="new" href="http://lrdf.sf.net">liblrdf</a></li>
92        <li>(optional) <a target="new" href="http://lash.nongnu.org">lash</a></li>
93</ul>
94
95Install Hydrogen according to your distribution's package instructions, then execute:
96<pre>$ hydrogengui</pre>
97Or run <tt>hydrogengui --help</tt> for usage options:
98<pre>
99Usage: hydrogen [-v] [-h] -s file
100   -d, --driver AUDIODRIVER - Use the selected audio driver (jack, alsa, oss, portaudio)
101   -s, --song FILE - Load a song (*.h2song) at startup
102   -n, --nosplash - Hide splash screen
103   -V, --verbose - Print a lot of debugging info
104   -v, --version - Show version info
105   -h, --help - Show this help message
106</pre>
107
108If you prefer compiling Hydrogen, you can download sources from SVN with:<br />
109<pre>$ svn co http://devel.hydrogen-music.org/svn/hydrogen/trunk</pre>
110
111<h2 class="subchapter" id="build">Build</h2>
112If you choose to compile Hydrogen, you need <a target="new" href="http://www.scons.org">SCons</a> and <a target="new" href="http://www.feep.net/libtar">libtar</a> too. Remember to compile using at least <a target="new" href="http://gcc.gnu.org">GCC</a> 3.x to be 100% sure to avoid compiler's issues. Then follow these steps:
113<pre>
114$ cd path/to/src
115$ scons [prefix=/install/path]
116$ su &lt;password&gt; (if performing a system wide installation)
117# scons install
118</pre>
119
120To clean up compiled code:
121<pre>$ scons -c</pre>
122To access optional compilation flags:
123<pre>$ scons --help</pre>
124At the moment the following flags are supported:
125<ul>
126        <li><pre>debug: Set to 1 to build with debug informations</pre></li>
127        <li><pre>lash: Set to 1 to enable lash</pre></li>
128        <li><pre>alsa: Set to 1 to enable alsa</pre></li>
129        <li><pre>jack: Set to 1 to enable jack</pre></li>
130        <li><pre>libarchive: Set to 1 to enable libarchive instead of libtar</pre></li>
131        <li><pre>prefix: Default: /usr/local</pre></li>
132        <li><pre>destdir: Default: none</pre></li>
133</ul>
134
135<h2 class="subchapter" id="audio">Audio driver configuration</h2>
136
137It's very important to choose the proper audio driver for your system, since the choice may influence quite much general performances. The choice is between OSS, ALSA, PortAudio and Jack audio driver.
138
139<div style="width: 80%;">
140<ul>
141        <li><strong>OSS audio driver</strong>: this driver uses /dev/dsp and it's based on the old 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 OSS audio drivers as a last resort.</li>
142        <li><strong>ALSA audio driver</strong>: the new and widely adopted Linux standard audio drivers.</li>
143        <li><strong>Jack audio driver</strong>: JACK is a professional audio server which can plug in other audio software, allowing extremely low lags. <strong>We strongly recommend using this driver</strong> to experience the best out of Hydrogen. JACK server will start automatically if not already running.</li>
144        <li><strong>PortAudio driver</strong>: an open-source multiplatform audio driver.</li>
145</ul>
146If for some reason none of the above mentioned audio driver is available at startup, Hydrogen will start either way, using a <i>null</i> audio driver, but it won't have much use :)
147</div>
148
149<h3 class="subsubchapter" id="prefs">Audio preferences</h3>
150From the "Audio System" tab (Fig. 1) it is possible to modify the audio driver being used (OSS, Jack, ALSA, PortAudio) with its buffer and sampling rate (unless using JACK, in this case the audio driver configuration should happen before starting the JACK server).<br /><br />
151We can set some features of Hydrogen like "Enable track outputs" useful if you want to add effects to a single instrument with jack-rack. "Connect to Default Output Pair" connects the output to the default ports: uncheck this if you want to connect JACK output to other ports without disconnecting them first.<br /><br />
152Keep an eye also on the value of "Polyphony": depending on your CPU you may want to change the max simultaneous notes in order to prevent hydrogen from overunning the audio driver.
153
154<div class="imagecenter">
155        <span class="note">Fig. 1 - The Audio system tab</span><br /><br />
156        <img src="img/PreferencesAudioSystem.png" alt="The Audio system tab" title="The Audio system tab" />
157</div>
158
159The "Midi System" tab (Fig. 2) concerns the MIDI input. You can choose the MIDI driver and input, setup channels, binding actions to MIDI events.
160
161<div class="imagecenter">
162        <span class="note">Fig. 2 - The MIDI system tab</span><br /><br />
163        <img src="img/PreferencesMidiSystem.png" alt="The MIDI system tab" title="The MIDI system tab" />
164</div>
165
166The "Appearance" tab (Fig. 3) let's you to modify Hydrogen and QT graphical properties.
167
168<div class="imagecenter">
169        <span class="note">Fig. 3 - The appeareance tab</span><br /><br />
170        <img src="img/PreferencesAppearance.png" alt="The appeareance tab" title="The appeareance tab" />
171</div>
172
173<h3 class="subsubchapter" id="engine">Audio engine info</h3>
174The audio engine info is a window with various stats about Hydrogen and the audio driver. In case JACK is used, buffer and sampling rate should be set before starting Hydrogen (JACK automatically starts when an application tries to connect).
175
176<div class="imagecenter">
177        <span class="note">Fig. 4 - The Audio Engine Info window</span><br /><br />
178        <img src="img/AudioEngineInfoDialog.png" alt="Fig. 4 Audio engine infos" title="Fig. 4 Audio engine infos" />
179</div>
180
181<h2 class="subchapter" id="files">Files used</h2>
182Before working with Hydrogen, please familiarize with these files:
183<ul>
184        <li><tt>*.h2pattern</tt>: XML file describing a single <strong>pattern</strong>. Patterns are group of beats and are managed in the <a href="#peditor">pattern editor</a>.</li>
185        <li><tt>*.h2song</tt>: XML file describing the whole <strong>song</strong> (or sequence). Songs are group of patterns with their properties and are manager using the <a href="#seditor">song editor</a>.</li>
186        <li><tt>*.h2playlist</tt>: XML file describing a <strong>playlist</strong>. <a href="#playlist">Playlists</a> are group of songs.</li>
187        <li><tt>*.h2drumkit</tt>: <tt>tar</tt> readable file containing all sound samples composing a <strong>drumkit</strong> and a description XML file. Drumkits are basically group of sound samples.</li>
188</ul>
189
190<div class="warn"><img src="img/warn.png" alt="" />Please notice that Hydrogen uses <strong>WELL-FORMED</strong> but <strong>NOT VALID</strong> XML files. If you don't know what this means please check this page on <a target="new" href="http://en.wikipedia.org/wiki/XML#Well-formed_and_valid_XML_documents">Wikipedia</a>.</div>
191
192<hr /><br />
193<div class="titlechapter" id="chap2">Chapter 2: Using Hydrogen</div>
194<div style="text-align: right;"><a href="#top">[TOP]</a></div>
195
196<h2 class="subchapter" id="menu">Menu</h2>
197Here's an overview of Hydrogen's file menu:
198
199<ul class="menu">
200        <li>
201                <strong>Projects</strong>: this menu offers file related functions.
202                <ul class="menu">
203                        <li>New - <span class="desc">Create a new song</span></li>
204                        <li>Show Info - <span class="desc">Set general properties of the song such as name, author, license and generic notes</span></li>
205                        <li>Open - <span class="desc">Open a song</span></li>
206                        <li>Open Demo - <span class="desc">Open a demo song (demo songs are stored in <tt>$INSTALLPATH/share/hydrogen/data/demo_songs</tt>)</span></li>
207                        <li>Open recent - <span class="desc">Open a menu showing last used songs</span></li>
208                        <li>Save - <span class="desc">Save changes to current song</span></li>
209                        <li>Save as - <span class="desc">Save current song specifying a name (default path: <tt>$HOME/.hydrogen/data/songs)</tt></span></li>
210                        <li>Open pattern - <span class="desc">Open a saved pattern belonging to the current drumkit</span></li>
211                        <li>Export pattern as - <span class="desc">Saves a pattern. It will be stored in <tt>$HOME/.hydrogen/data/patterns/drumkit_name</tt></span></li>
212                        <li>Export MIDI file - <span class="desc">Export current song in MIDI format</span></li>
213                        <li>Export song - <span class="desc">Export current song in WAV format</span></li>
214                        <li>Quit - <span class="desc">Quit Hydrogen</span></li>
215                </ul>
216        </li>
217        <li>
218                <strong>Instruments</strong>: this menu offers instruments and drumkit (sound libraries) functions.
219                <ul class="menu">
220                        <li>Add instrument - <span class="desc">Add a new instrument to your current drumkit</span></li>
221                        <li>Clear all - <span class="desc">Delete all instruments from the current drumkit</span></li>
222                        <li>Save library - <span class="desc">Saves all instruments settings (and their sound samples) in <tt>$HOME/.hydrogen/data/library_name</tt></span></li>
223                        <li>Export library - <span class="desc">Compress all instruments samples and settings in a drumkit in <tt>$HOME/.hydrogen/data/library_name</tt></span></span></li>
224                        <li>Import library - <span class="desc">Imports another drumkit from the local filesystem of download it from a remote location through an XML feed. The XML file that should be provided is <strong>NOT</strong> RSS compliant (see <a href="http://www.hydrogen-music.org/feeds/drumkit_list.php" target="new">Hydrogen website</a> for an example). To load another drumkit in your current working session of Hydrogen, read <a href="#rack">here</a>.</span></li>
225                </ul>
226        </li>
227        <li>
228                <strong>Tools</strong>: opens the mixer, the playlist editor, the instrument rack and the general preferences window.
229                <ul class="menu">
230                        <li>Playlist editor - <span class="desc">A tool to manage playlists.</span></li>
231                        <li>Mixer - <span class="desc">Open the mixer window.</span></li>
232                        <li>Instrument rack - <span class="desc">Open the instrument rack panel.</span></li>
233                        <li>Preferences - <span class="desc"></span>Open the main preferences window. Read <a href="#prefs">here</a> on how to configure Hydrogen.</li>
234                </ul>
235        </li>
236        <li>
237                <strong>Debug</strong>: tools mainly for debugging and monitoring Hydrogen.
238                <ul class="menu">
239                        <li>Show audio engine info - <span class="desc">Open a monitor with various <a href="#engine">stats</a></span></li>
240                        <li>debug action - <span class="desc"> Insert debug commands.</span></li>
241                        <li>Print Objects - <span class="desc">Print on stdout current objects map.</span></li>
242                </ul>
243        </li>
244        <li>
245                <strong>Info</strong>
246                <ul class="menu">
247                        <li>User manual - <span class="desc">Open a window with this manual :)</span></li>
248                        <li>About - <span class="desc">The usual window with licence information, acknowledgements, etc.</span></li>
249                </ul>
250        </li>
251</ul>
252
253<h2 class="subchapter" id="toolbar">The main toolbar</h2>
254Before describing the two main panels of Hydrogen, let's take a quick look at the main toolbar and its components. The main toolbar allows a few important functions:
255<ul>
256        <li>Pilot the song using the start, stop, pause, etc. buttons</li>
257        <li>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.</li>
258        <li>An advanced tap tempo function: choose note lenght and how many notes to wait before recalculating BPM, then click the comma key repeatedly until the 'R' letter will appear and the BPM will be updated.</li>
259        <li>Manually set BPM</li>
260        <li>Manage JACK transport</li>
261        <li>Open the mixer and the instrument rack panels</li>
262</ul>
263Hover your mouse on Fig. 5 and for each element a quick description will popup:
264<div class="imagecenter">
265        <span class="note">Fig. 5 - The main toolbar</span><br /><br />
266        <img src="img/MainToolbar.png" title="Main toolbar" alt="Main toolbar" width="934" height="43" usemap="#ToolbarMap" />
267        <map name="ToolbarMap">
268        <!-- #$-:Image Map file created by GIMP Imagemap Plugin -->
269        <!-- #$-:GIMP Imagemap Plugin by Maurits Rijk -->
270        <!-- #$-:Please do not edit lines starting with "#$" -->
271        <!-- #$VERSION:2.0 -->
272        <!-- #$AUTHOR:jman -->
273                <area shape="rect" coords="10,6,148,39" title="Timings of the pattern/song" nohref="nohref" />
274                <area shape="rect" coords="155,17,173,32" title="Rewind a song/pattern" nohref="nohref" />
275                <area shape="rect" coords="180,18,202,33" title="Play / pause song/pattern" nohref="nohref" />
276                <area shape="rect" coords="208,17,227,32" title="Stop playing (will restart from the beginning)" nohref="nohref" />
277                <area shape="rect" coords="233,18,251,32" title="Fast forward playing song/pattern" nohref="nohref" />
278                <area shape="rect" coords="259,18,278,31" title="Enable / disable loop playing" nohref="nohref" />
279                <area shape="rect" coords="298,4,362,13" title="Pattern mode enabled" nohref="nohref" />
280                <area shape="rect" coords="298,15,363,24" title="Song mode enabled" nohref="nohref" />
281                <area shape="rect" coords="299,26,363,39" title="Switch pattern song mode" nohref="nohref" />
282                <area shape="rect" coords="370,0,386,42" title="Open beat counter panel" nohref="nohref" />
283                <area shape="rect" coords="390,7,404,24" title="Change note length" nohref="nohref" />
284                <area shape="rect" coords="405,6,445,39" title="Beat counter (Tap tempo) panel" nohref="nohref" />
285                <area shape="rect" coords="445,7,460,23" title="Set number of hits. 'R' will recalculate BPM" nohref="nohref" />
286                <area shape="rect" coords="447,27,460,39" title="Set BPM / set BPM and play" nohref="nohref" />
287                <area shape="rect" coords="476,5,490,21" title="Set BPM speed (range: 30-400)" nohref="nohref" />
288                <area shape="rect" coords="474,27,492,39" title="Mute / unmute click" nohref="nohref" />
289                <area shape="rect" coords="498,4,586,39" title="BPM meter" nohref="nohref" />
290                <area shape="poly" coords="606,5,689,4,689,22,661,22,661,12,606,12,605,5" title="CPU load" nohref="nohref" />
291                <area shape="rect" coords="605,13,660,23" title="MIDI events" nohref="nohref" />
292                <area shape="rect" coords="606,26,647,38" title="Jack transfer: Hydrogen will work as slave with another master program (e.g. Ardour)." nohref="nohref" />
293                <area shape="rect" coords="648,27,688,39" title="Use Jack as master" nohref="nohref" />
294                <area shape="rect" coords="707,6,779,23" title="Open / close mixer panel" nohref="nohref" />
295                <area shape="rect" coords="781,6,927,22" title="Open / close instrument rack panel" nohref="nohref" />
296                <area shape="rect" coords="708,27,929,39" title="'LCD' panel displaying misc info" nohref="nohref" />
297        </map>
298</div>
299
300
301A few useful keybindings (not customizable for the moment):
302<ul class="menu">
303        <li><strong>[CTRL + O]</strong> Open File</li>
304        <li><strong>[CTRL + S]</strong> Save File</li>
305        <li><strong>[Backspace]</strong> Restart song or pattern from the beginning</li>
306        <li><strong>[Backslash]</strong> A basic tap tempo function: you can follow the beat of a song with this key and Hydrogen with recalculate the BPM.</li>
307</ul>
308
309<h2 class="subchapter" id="seditor">Song editor</h2>
310The panel "Song Editor" (Fig. 6) gives an overview of the whole timeline of the song (e.g. intro, verse, bridge, chorus and so on); each blue coloured square on this panel is a complete bar as shown in the underlying "<a href="#peditor">Pattern Editor</a>" panel. Here we have complete freedom to add, remove or move patterns in any order we prefer. Hover on figure 2 to learn the functions of the song editor panel:
311<div class="imagecenter">
312        <span class="note">Fig. 6 - Move or copy pattern</span><br /><br />
313        <img src="img/SongEditor.png" alt="Song editor panel" usemap="#SeditorMap" /></div>
314        <map name="SeditorMap">
315                <!-- #$-:Image Map file created by GIMP Imagemap Plugin -->
316                <!-- #$-:GIMP Imagemap Plugin by Maurits Rijk -->
317                <!-- #$-:Please do not edit lines starting with "#$" -->
318                <!-- #$VERSION:2.0 -->
319                <!-- #$AUTHOR:jman -->
320                <area shape="rect" coords="4,8,63,27" title="Delete all patterns (asks for confirmation!)"  nohref="nohref" />
321                <area shape="rect" coords="64,10,85,25" title="Add a new pattern (asks for the name and category)"  nohref="nohref" />
322                <area shape="rect" coords="91,12,125,22" title="Move currently selected pattern up or down"  nohref="nohref" />
323                <area shape="rect" coords="131,12,146,23" title="Enable line mode (enable multiple selection for copy and paste)"  nohref="nohref" />
324                <area shape="rect" coords="150,12,165,22" title="Enable draw mode (add or remove patterns)"  nohref="nohref" />
325                <area shape="rect" coords="171,12,188,22" title="Enable single pattern / multiple pattern play at once"  nohref="nohref" />
326                <area shape="rect" coords="2,31,200,228" title="Patterns list (pattern marked will play together)"  nohref="nohref" />
327                <area shape="rect" coords="201,6,389,28" title="Bars numbering"  nohref="nohref" />
328                <area shape="rect" coords="201,33,389,229" title="Patterns timeline"  nohref="nohref" />
329        </map>
330
331Enable "select mode" and perform multiple copy/paste/move operations, enable "draw mode" and insert or delete patterns.<br />
332When in "draw" mode, click on the grid to add and remove patterns.<br />
333When in "select" mode, select one or more patterns (will be marked as selected with a darker blue) and move them around. If you hold the CTRL key while dragging the patterns will copied.
334
335<div class="imagecenter">
336<span class="note">Fig. 7 - Move or copy pattern</span><br /><br />
337        <img src="img/patterns.gif" alt="Copy and move patterns" />
338</div>
339
340<h2 class="subchapter" id="peditor">Pattern editor</h2>
341The "Pattern Editor" panel (Fig. 8) let you create or modify the pattern (bar) which is being played, or add/remove notes and tune intensity as well (provided the instrument has at least one note in the pattern).<br />
342Hover the picture with the mouse to explore the pattern editor.
343
344<div class="imagecenter">
345        <span class="note">Fig. 8 - The pattern editor</span><br /><br />
346        <img src="img/PatternEditor.png" alt="Pattern editor panel" title="Pattern editor panel" usemap="#PeditorMap" />
347        <map name="PeditorMap">
348        <!-- #$-:Image Map file created by GIMP Imagemap Plugin -->
349        <!-- #$-:GIMP Imagemap Plugin by Maurits Rijk -->
350        <!-- #$-:Please do not edit lines starting with "#$" -->
351        <!-- #$VERSION:2.0 -->
352        <!-- #$AUTHOR:jman -->
353                <area shape="rect" coords="182,3,266,21" title="Three beats bars (4T, 8T, 16T and 32T)" nohref="nohref" />
354                <area shape="rect" coords="278,3,379,21" title="Resolution grid (4 to 64 beats)" nohref="nohref" />
355                <area shape="rect" coords="381,3,432,22" title="Hear new notes: play the instrument when its name is clicked"  nohref="nohref" />
356                <area shape="rect" coords="433,4,471,21" title="Record an instrument from an external source"  nohref="nohref" />
357                <area shape="rect" coords="472,3,530,21" title="Quantize instrument: notes added will respect the grid resolution"  nohref="nohref" />
358                <area shape="rect" coords="531,2,603,22" title="Zoom in/out the pattern view"  nohref="nohref" />
359                <area shape="rect" coords="1,24,181,49" title="Current selected pattern name"  nohref="nohref" />
360                <area shape="rect" coords="0,49,150,505" title="Instrument name column"  nohref="nohref" />
361                <area shape="rect" coords="151,50,164,505" title="Red square: mute instrument"  nohref="nohref" />
362                <area shape="rect" coords="165,51,177,505" title="Green square: play solo"  nohref="nohref" />
363                <area shape="rect" coords="182,26,777,506" title="Pattern overview"  nohref="nohref" />
364                <area shape="rect" coords="1,549,178,561" title="Drop down menu to tune velocity, pan, lead&amp;lag" nohref="nohref" />
365                <area shape="rect" coords="181,505,778,602" title="Vertical bars representing velocity, pan, lead&amp;lag" nohref="nohref" />
366        </map>
367</div>
368
369Each instrument has its own set of features accessible right-clicking on it:
370<ul>
371        <li><strong>Lock</strong>: lock that instrument (i.e. the source sound file) even if you change drumkit (this way you can easily mix different drumkit instruments and create your own!)</li>
372        <li><strong>Fill notes</strong>: fills every note of that instrument in the current pattern according to the grid resolution</li>
373        <li><strong>Clear notes</strong>: removes every note of that instrument in the current pattern according to the grid resolution</li>
374        <li><strong>Randomize velocity</strong>: 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 "hard" on that instrument when played.</li>
375        <li><strong>Delete instruments</strong>: delete the instrument</li>
376        <li>And from the dropdown menu:
377                <ul>
378                        <li> <strong>Velocity</strong>: tune velocity (beat hardness).</li>
379                        <li> <strong>Pan</strong>: moves pan left to right.</li>
380                        <li> <strong>Lead&amp;Lag</strong>: allows a slight note <i>lead</i> or <i>lag</i> in respect of the actual beat. The range is � 5 ticks which equals around � 10 ms at a tempo of 120bpm.</li>
381                </ul>
382        </li>
383</ul>
384
385<strong>Rememeber this constraint concerning the grid</strong>: if you are working with a resolution of 16 you can't go back to 8 and remove a 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.<br />
386This contraint 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.<br /><br />
387<span class="warn"><img src="img/warn.png" alt="" />&nbsp;Be sure to select the correct pattern in the song editor before editing!</span>
388<br /><br /><br />
389
390You can set new beats clicking on button [<img src="img/recBtn_on.png" alt="record" title="record" />] which enables direct input through a MIDI event or through a keyboard according to a mapping "key=instrument" (see Fig. 9).
391
392<div class="imagecenter">
393        <span class="note">Fig. 9 - Keyboard reference</span><br /><br />
394        <img src="img/tastiera.png" title="Keyboard reference" alt="Keyboard reference" />
395</div>
396
397<div class="warn"><img src="img/warn.png" alt="" />&nbsp;Note that the name of the instrument depends on the drumkit loaded. This list refers to the GMKit loaded by default. The position of the instrument, however, is the same.</div>
398
399<h2 class="subchapter" id="mixer">Mixer</h2>
400The Mixer is useful for settings such as instrument volumes of the current drumkit, effects and various properties.<br />
401Each instrument has a volume control which can be tuned through its fader knob, and controls for pan, play solo, mute or 'test play' (play that instrument only).<br />
402The graphical volume equalizer may come in handy to keep the max volume in a 0.0 - 1.0 range, otherwise it will get distorted producing a weird sound (especially using OSS audio driver), in this case it's better to set volume down; the equalizer can be disabled clicking on the 'peak' button (saves up something on old CPUs). Hover on Fig. 10 to learn all the functions of the mixer.
403
404By default the drumkit loaded has 16 instruments, but you can add up to 32. Use the mixer's horizontal scrollbar to see them all.
405
406<div class="imagecenter">
407        <span class="note">Fig. 10 - The mixer</span><br /><br />
408        <img src="img/Mixer.png" title="The mixer" alt="The mixer" usemap="#Mixer" />
409        <map name="Mixer">
410                <!-- #$-:Image Map file created by GIMP Imagemap Plugin -->
411                <!-- #$-:GIMP Imagemap Plugin by Maurits Rijk -->
412                <!-- #$-:Please do not edit lines starting with "#$" -->
413                <!-- #$VERSION:2.0 -->
414                <!-- #$AUTHOR:jman -->
415                <area shape="rect" coords="9,15,491,30" title="Play once"  nohref="nohref" />
416                <area shape="rect" coords="9,34,26,45" title="Mute instrument"  nohref="nohref" />
417                <area shape="rect" coords="64,33,83,45" title="Mute instrument"  nohref="nohref" />
418                <area shape="rect" coords="119,33,138,45" title="Mute instrument"  nohref="nohref" />
419                <area shape="rect" coords="177,33,193,45" title="Mute instrument"  nohref="nohref" />
420                <area shape="rect" coords="232,33,250,45" title="Mute instrument"  nohref="nohref" />
421                <area shape="rect" coords="288,33,306,45" title="Mute instrument"  nohref="nohref" />
422                <area shape="rect" coords="344,33,362,45" title="Mute instrument"  nohref="nohref" />
423                <area shape="rect" coords="399,33,418,45" title="Mute instrument"  nohref="nohref" />
424                <area shape="rect" coords="457,33,474,45" title="Mute instrument"  nohref="nohref" />
425                <area shape="rect" coords="32,33,48,45" title="Solo instrument"  nohref="nohref" />
426                <area shape="rect" coords="86,33,104,45" title="Solo instrument"  nohref="nohref" />
427                <area shape="rect" coords="141,33,161,45" title="Solo instrument"  nohref="nohref" />
428                <area shape="rect" coords="198,33,216,45" title="Solo instrument"  nohref="nohref" />
429                <area shape="rect" coords="255,32,272,43" title="Solo instrument"  nohref="nohref" />
430                <area shape="rect" coords="309,33,328,45" title="Solo instrument"  nohref="nohref" />
431                <area shape="rect" coords="367,33,384,45" title="Solo instrument"  nohref="nohref" />
432                <area shape="rect" coords="421,33,440,45" title="Solo instrument"  nohref="nohref" />
433                <area shape="rect" coords="478,33,490,44" title="Solo instrument"  nohref="nohref" />
434                <area shape="rect" coords="6,49,490,77" title="Pan"  nohref="nohref" />
435                <area shape="rect" coords="6,78,491,118" title="LADSPA plugins intensity"  nohref="nohref" />
436                <area shape="rect" coords="6,118,491,267" title="Instrument volumes and peaks"  nohref="nohref" />
437                <area shape="rect" coords="508,85,693,123" title="Plugin #1: Edit effect, set Return or Bypass effect"  nohref="nohref" />
438                <area shape="rect" coords="507,128,694,168" title="Plugin #2: Edit effect, set Return or Bypass effect"  nohref="nohref" />
439                <area shape="rect" coords="507,172,694,211" title="Plugin #3: Edit effect, set Return or Bypass effect"  nohref="nohref" />
440                <area shape="rect" coords="506,214,693,254" title="Plugin #4: Edit effect, set Return or Bypass effect"  nohref="nohref" />
441                <area shape="rect" coords="722,33,765,44" title="Mute master volume"  nohref="nohref" />
442                <area shape="rect" coords="723,49,766,272" title="Master volume and peak"  nohref="nohref" />
443                <area shape="rect" coords="767,88,815,126" title="Humanize velocity"  nohref="nohref" />
444                <area shape="rect" coords="767,126,816,163" title="Humanize timing"  nohref="nohref" />
445                <area shape="rect" coords="767,163,816,199" title="Humanize swing"  nohref="nohref" />
446                <area shape="rect" coords="770,242,812,254" title="Open / close effects panel"  nohref="nohref" />
447                <area shape="rect" coords="771,258,812,271" title="Show / hide peaks"  nohref="nohref" />
448        </map>
449</div>
450
451When an instrument is selected in the pattern editor a blue LED will turn on near its play button.<br />
452The mixer allows applying four LADSPA effects (see <a href="#ladspa">details</a>) and three global effects:
453<ul>
454        <li><strong>Swing</strong>: shifts a few notes back or forward not randomly.</li>
455        <li><strong>Timing</strong>: modify timings of the notes.</li>
456        <li><strong>Humanize</strong>: random velocity editing</li>
457</ul>
458
459<hr /><br />
460<div class="titlechapter" id="chap3">Chapter 3: Extending Hydrogen</div>
461<h2 class="subchapter" id="rack">Instruments and sound libraries</h2>
462You can <strong>customize an instrument</strong> or <strong>create your own instrument from scratch</strong>.<br />
463Open the instrument rack panel from the main toolbar. A new panel with two tabs will appear:
464<ul>
465        <li><strong>Instrument</strong>: edit an instrument and its properties.</li>
466        <li><strong>Sound library</strong>: quickly load songs, drumkits or a just a single instruments. Here is where you will find your imported drumkits too.</li>
467</ul>
468
469<div class="imagecenter">
470        <span class="note">Fig. 11 - Instrument Rack: both tabs</span><br /><br />
471        <img src="img/InstrumentRack.png" alt="Instrument Rack" title="Instrument Rack" />
472</div>
473
474If you want to create or edit an instrument, select an existing instrument or create it (from the "Instruments" <a href="#menu">menu</a>) and select the "Instrument" tab of the rack. This tab shows two further tabs:
475<ul>
476        <li><strong>General</strong>: set specific properties of the instrument</li>
477        <li><strong>Layers</strong>: customize instrument adding further layers that will be played according to the velocity, tune pitch and gain settings for the layer itself. Input filetypes supported depending on how you compiled Hydrogen, by default: WAV, AU, AIFF, FLAC.</li>
478</ul>
479Hover on Fig. 12 to see all the properties.
480
481<div class="imagecenter">
482        <span class="note">Fig. 12 - Both sides of the instrument editor: add effects to your sound!</span><br /><br />
483        <img src="img/instr_editor.png" alt="Instrument Rack" title="Instrument Rack" useMap="#MixerEditMap" />
484        <map name="MixerEditMap" id="MixerEditMap">
485                <!-- #$-:Image Map file created by GIMP Imagemap Plugin -->
486                <!-- #$-:GIMP Imagemap Plugin by Maurits Rijk -->
487                <!-- #$-:Please do not edit lines starting with "#$" -->
488                <!-- #$VERSION:2.0 -->
489                <!-- #$AUTHOR:jman -->
490                <area shape="rect" coords="18,104,228,143" title="Tune Attack, Decay, Sustain and Release"  nohref="nohref" />
491                <area shape="rect" coords="24,150,223,189" title="Tune Gain and mute group of notes"  nohref="nohref" />
492                <area shape="rect" coords="24,197,223,235" title="Set Cutoff and Resonance"  nohref="nohref" />
493                <area shape="rect" coords="25,243,223,281" title="Set a random pitch"  nohref="nohref" />
494                <area shape="rect" coords="256,55,496,243" title="Layers available"  nohref="nohref" />
495                <area shape="rect" coords="255,251,493,311" title="Summary of instrument wave"  nohref="nohref" />
496                <area shape="rect" coords="278,318,472,332" title="Add or remove a sound sample"  nohref="nohref" />
497                <area shape="rect" coords="276,346,473,384" title="Layer gain"  nohref="nohref" />
498                <area shape="rect" coords="275,406,374,444" title="Layer pitch"  nohref="nohref" />
499                <area shape="rect" coords="375,405,474,444" title="Layer fine"  nohref="nohref" />
500        </map>
501</div>
502
503If you want to quickly choose a sound sample from a drumkit, load a full drumkit or a song, select the "Sound library" tab (Fig. 13). Songs shown are located in <tt>$HOME/.hydrogen/data/songs/</tt>. You can have an audio preview of each instrument double-clicking on it or you can quick load a song right-clicking on it:
504
505<div class="imagecenter">
506        <span class="note">Fig. 13 - Sound library panel</span><br /><br />
507        <img src="img/SoundLibrary.png" alt="Sound library" title="Sound library" />
508</div>
509
510<h2 class="subchapter" id="ladspa">LADSPA plugins</h2>
511<a target="new" href="http://www.ladspa.org">LADSPA</a> (Linux Audio Developers Simple Plugin API) libraries can be plugged to Hydrogen to add effects to your instruments.<br />
512You need to have installed the LADSPA package (compiled from sources or find a precompiled binary package for your distribution). While the default plugins shipped will give you a rough idea of how it works you should really have a taste of the real thing installing one or more of these libraries: <strong><a target="new" href="http://plugin.org.uk">SWH-Plugins</a></strong> (requires <a target="new" href="http://www.fftw.org">FFTW</a>), <strong><a target="new" href="http://www.ladspa.org">CMT</a></strong> and <strong><a href="http://tap-plugins.sf.net">TAP</a></strong>.<br /><br />
513Once you have installed a few plugins, open a song you'd like to add an effect to and select an instrument that has a few beats in the pattern. Click the <img src="img/showFX_on.png" alt="" title="" /> button in the mixer and select one of the four available effect line from the LADSPA panel (Fig. 14):
514
515<div class="imagecenter">
516        <span class="note">Fig. 14 - LADSPA plugins mixer panel</span><br /><br />
517        <img src="img/MixerFXPanel.png" alt="" title="" />
518</div>
519
520Click the "Edit" button of one plugin slot and you will be prompted with its properties window (Fig. 15):
521
522<div class="imagecenter">
523        <span class="note">Fig. 15 - LADSPA plugin properties window</span><br /><br />
524        <img src="img/MixerFXProperties.png" alt="" title="" />
525</div>
526
527A plugin, once assigned, can be disabled clicking on its "bypass" button in the mixer or clicking "Deactivate" on the properties window.<br /><br />
528Once openend the plugin window you can add an effect choosing from those installed (clicking on "Select FX"): this will bring up another window (Fig. 16) that lets you choose an effect among those installed (alphabetically sorted and categorized):
529
530<div class="imagecenter">
531        <span class="note">Fig. 16 - LADSPA effects selection</span><br /><br />
532        <img src="img/MixerFXSelect.png" alt="" title="" />
533</div>
534
535To tune the intensity of the effect on your instrument, use the round knobs in the mixer:
536<div class="imagecenter">
537        <span class="note">Fig. 17 - Mixer plugin knobs</span><br /><br />
538        <img src="img/MixerFXKnob.png" alt="" title="" />
539</div>
540
541<h2 class="subchapter" id="playlist">Playlist Editor</h2>
542The playlist editor is useful if you want Hydrogen to play different songs automatically. You can also bind BASH shell script to any item of your playlist (to launch external programs, for example).
543<div class="imagecenter">
544        <span class="note">Fig. 18 - Playlist window</span><br /><br />
545        <img src="img/Playlist.png" alt="Playlist window" title="Playlist window" />
546</div>
547
548<h2 class="subchapter" id="support">Support and troubleshooting</h2>
549* Where do I find help? Forum, mailing-lists, <a target="new" href="http://hydrogen-music.org/devel/wiki">TRAC</a>?<br />
550* If you like Hydrogen contribute, donate, send us your sister, etc. etc.
551
552</body>
553</html>
Note: See TracBrowser for help on using the browser.