summaryrefslogtreecommitdiff
path: root/muse2/doc/html/single
diff options
context:
space:
mode:
Diffstat (limited to 'muse2/doc/html/single')
-rw-r--r--muse2/doc/html/single/developer_docs/developer_docs.css34
-rw-r--r--muse2/doc/html/single/developer_docs/developer_docs.html1745
-rw-r--r--muse2/doc/html/single/developer_docs/img1.pngbin0 -> 853 bytes
-rw-r--r--muse2/doc/html/single/developer_docs/img2.pngbin0 -> 374 bytes
-rw-r--r--muse2/doc/html/single/developer_docs/img3.pngbin0 -> 476 bytes
-rw-r--r--muse2/doc/html/single/developer_docs/index.html1745
-rw-r--r--muse2/doc/html/single/documentation/arrow_tool.pngbin0 -> 258 bytes
-rw-r--r--muse2/doc/html/single/documentation/documentation.css35
-rw-r--r--muse2/doc/html/single/documentation/documentation.html1702
-rw-r--r--muse2/doc/html/single/documentation/img1.pngbin0 -> 613 bytes
-rw-r--r--muse2/doc/html/single/documentation/index.html1702
-rw-r--r--muse2/doc/html/single/documentation/main_window_add_track.pngbin0 -> 101707 bytes
-rw-r--r--muse2/doc/html/single/documentation/main_window_annotated.pngbin0 -> 82252 bytes
-rw-r--r--muse2/doc/html/single/documentation/main_window_with_arrangement.pngbin0 -> 169229 bytes
-rw-r--r--muse2/doc/html/single/documentation/main_window_with_automation.pngbin0 -> 99278 bytes
-rw-r--r--muse2/doc/html/single/documentation/main_window_with_midi_automation.pngbin0 -> 100858 bytes
-rw-r--r--muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.pngbin0 -> 130510 bytes
-rw-r--r--muse2/doc/html/single/documentation/midi_config_window.pngbin0 -> 89152 bytes
-rw-r--r--muse2/doc/html/single/documentation/midi_routing_matrix.pngbin0 -> 18031 bytes
-rw-r--r--muse2/doc/html/single/documentation/mixer.pngbin0 -> 56812 bytes
-rw-r--r--muse2/doc/html/single/documentation/mixer_with_one_input.pngbin0 -> 31360 bytes
-rw-r--r--muse2/doc/html/single/documentation/mixer_with_one_input_buttons.pngbin0 -> 8825 bytes
-rw-r--r--muse2/doc/html/single/documentation/muse2.pngbin0 -> 97657 bytes
-rw-r--r--muse2/doc/html/single/documentation/no_audio.pngbin0 -> 32195 bytes
-rw-r--r--muse2/doc/html/single/documentation/output_routing.pngbin0 -> 27489 bytes
-rw-r--r--muse2/doc/html/single/documentation/project_my_first_song.pngbin0 -> 56152 bytes
-rw-r--r--muse2/doc/html/single/documentation/soloing_window.pngbin0 -> 64983 bytes
-rw-r--r--muse2/doc/html/single/documentation/vam_synth.pngbin0 -> 75861 bytes
28 files changed, 6963 insertions, 0 deletions
diff --git a/muse2/doc/html/single/developer_docs/developer_docs.css b/muse2/doc/html/single/developer_docs/developer_docs.css
new file mode 100644
index 00000000..d3fede21
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/developer_docs.css
@@ -0,0 +1,34 @@
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
+DIV.navigation { }
+SPAN.textit { font-style: italic }
+SPAN.arabic { }
+SPAN.textbf { font-weight: bold }
diff --git a/muse2/doc/html/single/developer_docs/developer_docs.html b/muse2/doc/html/single/developer_docs/developer_docs.html
new file mode 100644
index 00000000..9cf45e45
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/developer_docs.html
@@ -0,0 +1,1745 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<!--Converted with LaTeX2HTML 2008 (1.71)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<HTML>
+<HEAD>
+<TITLE>MusE Documentation</TITLE>
+<META NAME="description" CONTENT="MusE Documentation">
+<META NAME="keywords" CONTENT="developer_docs">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="developer_docs.css">
+
+</HEAD>
+
+<BODY >
+<BR>
+
+<H2><A NAME="SECTION00100000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
+
+<UL CLASS="TofC">
+<LI><A NAME="tex2html22"
+ HREF="developer_docs.html#SECTION00200000000000000000">Internals - how it works</A>
+<UL>
+<LI><A NAME="tex2html23"
+ HREF="developer_docs.html#SECTION00210000000000000000">User interface programming</A>
+<LI><A NAME="tex2html24"
+ HREF="developer_docs.html#SECTION00220000000000000000">Configuration</A>
+<LI><A NAME="tex2html25"
+ HREF="developer_docs.html#SECTION00230000000000000000">User controls and automation</A>
+<UL>
+<LI><A NAME="tex2html26"
+ HREF="developer_docs.html#SECTION00231000000000000000">Handling user input</A>
+</UL>
+</UL>
+<BR>
+<LI><A NAME="tex2html27"
+ HREF="developer_docs.html#SECTION00300000000000000000">Design decisions</A>
+<UL>
+<LI><A NAME="tex2html28"
+ HREF="developer_docs.html#SECTION00310000000000000000">Automation</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html29"
+ HREF="developer_docs.html#SECTION00400000000000000000">Feature requests</A>
+<UL>
+<LI><A NAME="tex2html30"
+ HREF="developer_docs.html#SECTION00410000000000000000">Per-Part automation and more on automation</A>
+<LI><A NAME="tex2html31"
+ HREF="developer_docs.html#SECTION00420000000000000000">Pre-Rendering tracks</A>
+<UL>
+<LI><A NAME="tex2html32"
+ HREF="developer_docs.html#SECTION00421000000000000000">The feature</A>
+<LI><A NAME="tex2html33"
+ HREF="developer_docs.html#SECTION00422000000000000000">Use cases</A>
+<LI><A NAME="tex2html34"
+ HREF="developer_docs.html#SECTION00423000000000000000">Possible scenarios</A>
+<LI><A NAME="tex2html35"
+ HREF="developer_docs.html#SECTION00424000000000000000">Extensions</A>
+</UL>
+<LI><A NAME="tex2html36"
+ HREF="developer_docs.html#SECTION00430000000000000000">Slotted editors</A>
+<LI><A NAME="tex2html37"
+ HREF="developer_docs.html#SECTION00440000000000000000">Controller master values</A>
+<LI><A NAME="tex2html38"
+ HREF="developer_docs.html#SECTION00450000000000000000">Enabled-indicator while recording</A>
+<LI><A NAME="tex2html39"
+ HREF="developer_docs.html#SECTION00460000000000000000">Linear automation editing</A>
+<LI><A NAME="tex2html40"
+ HREF="developer_docs.html#SECTION00470000000000000000">Symbolic names for MIDI ports</A>
+</UL></UL>
+<!--End of Table of Contents-->
+<H1><A NAME="SECTION00200000000000000000">
+Internals - how it works</A>
+</H1>
+This chapter explains how MusE is built internally, and is meant
+to be an aid for developers wanting to quickly start up with MusE.
+For details on <SPAN CLASS="textit">why</SPAN> stuff is done please refer to the following
+chapter.
+
+<P>
+
+<H1><A NAME="SECTION00210000000000000000">
+User interface programming</A>
+</H1>
+We use the QT Toolkit for GUI- and other programming. The <SPAN CLASS="textit">QT-Assistant</SPAN>
+is an important tool for getting help. Almost everything can be looked
+up there.
+
+<P>
+GUIs can be either be hardcoded (see <TT>fterfirsta`a=95 _ `a=58 :
+ `a&gt;64
+ `a&lt;91 aaa
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rranger.cpp</TT> for an example)
+or can be created using <SPAN CLASS="textit">QT-Designer</SPAN> (see the dialogs under
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/function_dialogs/</TT> for mostly cleanly-written examples).
+Don't forget to add your <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>pp</TT>, <TT>fterfirsth`h=95 _ `h=58 :
+ `h&gt;64
+ `h&lt;91 hhh
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>></TT> and <TT>fterfirstu`u=95 _ `u=58 :
+ `u&gt;64
+ `u&lt;91 uuu
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>i</TT> files to the
+corresponding sections in the <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>MakeLists.txt</TT>!
+
+<P>
+Additionally, MusE offers some custom widgets, like menu title items etc.
+Following, there will be a small, unordered list about custom widgets:
+
+<UL>
+<LI><TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MenuTitleItem</TT>: Provides a title-bar in a <TT>fterfirstQ`Q=95 _ `Q=58 :
+ `Q&gt;64
+ `Q&lt;91 QQQ
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>Menu</TT>.
+<BR>
+Usage: <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>omeMenu-&gt;addAction(new MusEGui::MenuTitleItem(tr("fnord"), someMenu));</TT>
+<BR>
+Defined in <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/menutitleitem.h</TT>.
+</LI>
+<LI><TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::PopupMenu</TT>: Provides a <TT>fterfirstQ`Q=95 _ `Q=58 :
+ `Q&gt;64
+ `Q&lt;91 QQQ
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>Menu</TT>-like menu which
+ can stay open after the user checks a checkable action.
+<BR>
+Usage: just create a <TT>fterfirstn`n=95 _ `n=58 :
+ `n&gt;64
+ `n&lt;91 nnn
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ew PopupMenu( true|false )</TT> instead of
+ a <TT>fterfirstn`n=95 _ `n=58 :
+ `n&gt;64
+ `n&lt;91 nnn
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ew QMenu()</TT>. (<TT>fterfirstt`t=95 _ `t=58 :
+ `t&gt;64
+ `t&lt;91 ttt
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rue</TT> means 'stay open')
+<BR>
+Defined in <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/popupmenu.h</TT>.
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00220000000000000000"></A> <A NAME="portconfig_sucks"></A>
+<BR>
+Configuration
+</H1>
+Configuration is a bit pesky in MusE in its current state. If you get
+confused by reading this chapter, that's a sign of a sane mind.
+
+<P>
+There are three kinds of configuration items:
+
+<UL>
+<LI>(1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
+</LI>
+<LI>(2) Per-Song configuration, like whether to show or hide certain track types in the arranger
+</LI>
+<LI>(3) Something in between, like MIDI port settings etc. They obviously actually are
+ global configuration issues (or ought to be), but also obviously must be stored
+ in the song file for portability. (This problem could possibly be solved by
+ the feature proposal in <A HREF="#symbolic_ports">3.7</A>.
+</LI>
+</UL>
+
+<P>
+
+<H4><A NAME="SECTION00220010000000000000">
+Reading configuration</A>
+</H4>
+<TT>fterfirstv`v=95 _ `v=58 :
+ `v&gt;64
+ `v&lt;91 vvv
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>oid MusECore::readConfiguration(Xml&amp;, bool, bool)</TT> in
+<TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>onf.cpp</TT> is the central point
+of reading configuration. It is called when MusE is started first
+(by <TT>fterfirstb`b=95 _ `b=58 :
+ `b&gt;64
+ `b&lt;91 bbb
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ool MusECore::readConfiguration()</TT>), and also when a
+song is loaded.
+<BR>It can be instructed whether to read MIDI ports (3), global configuration
+and MIDI ports (1+3). Per-Song configuration is always read (2).
+
+<P>
+When adding new configuration items and thus altering <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration()</TT>,
+you must take care to place your item into the correct section. The code is
+divided into the following sections:
+
+<UL>
+<LI>Global and/or per-song configuration (3)
+</LI>
+<LI>Global configuration (1)
+</LI>
+<LI>Code for skipping obsolete entries
+</LI>
+</UL>
+
+<P>
+The sections are divided by comments (they contain <TT>--</TT>, so just
+search for them). Please do not just remove code for reading obsolete entries,
+but always add an appropriate entry to the 'skipping' section in order to
+prevent error messages when reading old configs.
+
+<P>
+
+<H4><A NAME="SECTION00220020000000000000">
+Writing configuration</A>
+</H4>
+Global configuration is written using the
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration()</TT> functions, while
+per-song-config is written by <TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MusE::writeConfiguration()</TT>
+(notice the missing <TT>fterfirstG`G=95 _ `G=58 :
+ `G&gt;64
+ `G&lt;91 GGG
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>lobal</TT>; both implemented in <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>onf.cpp</TT>).
+
+<P>
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteConfiguration</TT> is actually just a subset of the code in
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>. <SPAN CLASS="textbf">Duplicate code!</SPAN>
+<P>
+
+<H4><A NAME="SECTION00220030000000000000">
+Song state</A>
+</H4>
+Additionally to per-song configuration, there is the song's state.
+This contains "the song", that is all tracks, parts and note events,
+together with information about the currently opened windows, their
+position, size, settings and so on. Adding new items here is actually
+pretty painless: Configuration is read and written using
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usECore::Song::read</TT> and <TT>fterfirst:`:=95 _ `:=58 :
+ `:&gt;64
+ `:&lt;91 :::
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>:write</TT>, both implemented in
+<TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ongfile.cpp</TT>. There are no caveats.
+
+<P>
+
+<H4><A NAME="SECTION00220040000000000000">
+How to add new items</A>
+</H4>
+When adding global configuration items, then add them into the second
+block ("global configuration") in <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration</TT> and into
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>.
+
+<P>
+When adding just-per-song items, better don't bother to touch the
+"configuration" code and just add it to the song's state (there might
+be rare exceptions).
+
+<P>
+When adding global configuration items, make sure you add them into the
+correct section of <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration</TT>, and into <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>.
+
+<P>
+
+<H1><A NAME="SECTION00230000000000000000">
+User controls and automation</A>
+</H1>
+
+<H2><A NAME="SECTION00231000000000000000">
+Handling user input</A>
+</H2>
+
+<H3><A NAME="SECTION00231100000000000000">
+Plugins and synthesizers</A>
+</H3>
+
+<H4><A NAME="SECTION00231110000000000000">
+Overview</A>
+</H4>
+When the user launches a plugin's GUI, either a MusE-window with
+the relevant controls is shown, or the native GUI is launched. MusE
+will communicate with this native GUI through OSC (Open Sound Control).
+The relevant classes are <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginGui</TT>, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginIBase</TT>
+(in <TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>lugin.h</TT>) and <TT>fterfirstO`O=95 _ `O=58 :
+ `O&gt;64
+ `O&lt;91 OOO
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>scIF</TT> (in <TT>fterfirsto`o=95 _ `o=58 :
+ `o&gt;64
+ `o&lt;91 ooo
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>sc.h</TT>).
+
+<P>
+If the user changes a GUI element, first the corresponding control is
+disabled, making MusE not steadily update it through automation
+while the user operates it. Then MusE will update the plugin's parameter
+value, and also record the new value. When appropriate, the controller
+is enabled again.
+
+<P>
+
+<H4><A NAME="SECTION00231120000000000000">
+Processing the input, recording</A>
+</H4>
+Upon operating a slider, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginIBase::setParam</TT> is called,
+which usually writes the control change into the ringbuffer
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. (<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::apply()</TT>,
+<TT>fterfirstD`D=95 _ `D=58 :
+ `D&gt;64
+ `D&lt;91 DDD
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ssiSynthIF::getData()</TT> will read this ringbuffer and
+do the processing accordingly). Furthermore, <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::recordAutomation</TT>
+is called, which either directly modifies the controller lists or writes
+the change into a "to be recorded"-list (<TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_recEvents</TT>)
+(depending on whether the song is stopped or played).
+
+<P>
+The <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_recEvents</TT> list consists of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlRecVal</TT>
+items (see <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trl.h</TT>), which hold the following data:
+
+<UL>
+<LI>the frame where the change occurred
+</LI>
+<LI>the value
+</LI>
+<LI>the type, which can be <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT>, <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_VAL</TT> or <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT>.
+ <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_VAL</TT> are written by every <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>udioTrack::recordAutomation</TT>
+ call, <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT> and <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT> are generated by
+ <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::startAutoRecord</TT> and <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>topAutoRecord</TT>, respectively.
+</LI>
+<LI>and the id of the controller which is affected
+</LI>
+</UL>
+It is processed when the song is stopped. The call path for this is:
+<TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::stopRolling</TT> calls <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::processAutomationEvents</TT>
+calls <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::processAutomationEvents</TT>.
+This function removes the old events from the track's controller list
+and replaces them with the new events from <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>recEvents</TT>. In
+<TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode, just all controller events within the recorded
+range are erased; in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> mode, the <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT>
+and <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT> types of the <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlRecVal</TT> events are used
+to determine the range(s) which should be wiped.
+
+<P>
+
+<H4><A NAME="SECTION00231130000000000000">
+How it's stored</A>
+</H4>
+Automation data is kept in <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_controller</TT>, which is a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlListList</TT>, that is, a list of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continuous (a new control
+point results in the value slowly sloping to the new value).
+Furthermore, it stores a <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>curVal</TT> (accessed by <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>urVal()</TT>),
+which holds the currently active value, which can be different from the
+actually stored value because of user interaction. This value is also
+used when there is no stored automation data.
+
+<P>
+<TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::addController</TT> and <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>emoveController</TT> are used to add/remove whole controller types; the most important functions which
+access <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>controller</TT> are:
+
+<UL>
+<LI><TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rocessAutomationEvents</TT>, <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ecordAutomation</TT>,
+ <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>tartAutoRecord</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>topAutoRecord</TT>: see above.
+</LI>
+<LI><TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eekPrevACEvent</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eekNextACEvent</TT>, <TT>fterfirste`e=95 _ `e=58 :
+ `e&gt;64
+ `e&lt;91 eee
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>raseACEvent</TT>,
+ <TT>fterfirste`e=95 _ `e=58 :
+ `e&gt;64
+ `e&lt;91 eee
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>raseRangeACEvents</TT>, <TT>fterfirsta`a=95 _ `a=58 :
+ `a&gt;64
+ `a&lt;91 aaa
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ddACEvent</TT>, <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>hangeACEvent</TT>,
+ which do the obvious
+</LI>
+<LI><TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginCtrlVal</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>etPluginCtrlVal</TT>: the first
+ returns the current value according to the <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>controller</TT>
+ list, the second only sets the <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>urVal</TT>, but does not
+ insert any events.
+</LI>
+</UL>
+
+<P>
+Whenever a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> has been manipulated,
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGlobal::song-&gt;controllerChange(Track*)</TT> shall be called,
+which emits the <TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGlobal::song-&gt;controllerChanged(Track*)</TT>
+signal in order to inform any parts of MusE about the change (currently,
+only the arranger's part canvas utilizes this).
+
+<P>
+
+<H4><A NAME="SECTION00231140000000000000">
+Enabling and disabling controllers</A>
+</H4>
+Disabling the controller is both dependent from the current automation
+mode and from whether the GUI is native or not.
+In <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode, once a slider is touched (for MusE-GUIs) or
+once a OSC control change is received (for native GUIs), the control
+is disabled until the song is stopped or seeked.
+
+<P>
+In <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> (and currently (r1492) <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_READ</TT>, but
+that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the
+corresponding control is disabled. Once the slider is released, the
+control is re-enabled again. Checkboxes remain in "disabled" mode,
+however they only affect the recorded automation until the last toggle
+of the checkbox. (Example: start the song, toggle the checkbox, toggle
+it again, wait 10 seconds, stop the song. This will NOT overwrite the
+last 10 seconds of automation data, but everything between the first
+and the last toggle.). For native GUIs, this is a bit tricky, because
+we don't have direct access to the GUI widgets. That is, we have no
+way to find out whether the user doesn't touch a control at all, or
+whether he has it held down, but just doesn't operate it. The current
+behaviour for native GUIs is to behave like in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode.
+
+<P>
+The responsible functions are: <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::oscControl</TT> and
+<TT>fterfirstD`D=95 _ `D=58 :
+ `D&gt;64
+ `D&lt;91 DDD
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ssiSynthIF::oscControl</TT> for handling native GUIs,
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::ctrlPressed</TT> and <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlReleased</TT> for MusE
+default GUIs and <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::guiParamPressed</TT>,
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiParamReleased</TT>, <TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSliderPressed</TT> and
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSliderReleased</TT> for MusE GUIs read from a UI file;
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSlider*</TT> obviously handle sliders, while <TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiParam*</TT>
+handle everything else which is not a slider. They call
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableController</TT> to enable/disable it.
+
+<P>
+Furthermore, on every song stop or seek, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+is called, which re-enables all controllers again. The call paths for
+this are:
+
+<UL>
+<LI>For stop: <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::stopRolling</TT> calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::processAutomationEvents</TT> calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::clearRecAutomation</TT> calls
+ <TT>fterfirstT`T=95 _ `T=58 :
+ `T&gt;64
+ `T&lt;91 TTT
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rack::clearRecAutomation</TT> calls
+ <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+</LI>
+<LI>For seek: <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udio::seek</TT> sends a message ("<TT>fterfirstG`G=95 _ `G=58 :
+ `G&gt;64
+ `G&lt;91 GGG
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>></TT>") to
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::seqSignal</TT> which calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::clearRecAutomation</TT> which calls
+ <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00300000000000000000">
+Design decisions</A>
+</H1>
+
+<H1><A NAME="SECTION00310000000000000000">
+Automation</A>
+</H1>
+As of revision 1490, automation is handled in two ways: User-generated
+(live) automation data (generated by the user moving sliders while playing)
+is fed into <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. Automation data is kept
+in <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_controller</TT>, which is a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlListList</TT>,
+that is, a list of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continous (a new control
+point results in the value slowly sloping to the new value).
+
+<P>
+While <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT> can be queried very quickly and
+thus is processed with a very high resolution (only limited by the
+minimum control period setting), the automation value are expensive to
+query, and are only processed once in an audio <SPAN CLASS="textit">driver</SPAN> period.
+This might lead to noticeable jumps in value.
+
+<P>
+This could possibly be solved in two ways:
+
+<H4><A NAME="SECTION00310010000000000000">
+Maintaining a slave control list</A>
+</H4>
+This approach would maintain a fully redundant slave control list,
+similar to <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. This list must be updated
+every time any automation-related thing is changed, and shall contain
+every controller change as a tuple of controller number and value.
+This could be processed in the same loop as <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>,
+making it comfortable to implement; furthermore, it allows to cleanly
+offer automation-settings at other places in future (such as storing
+automation data in parts or similar).
+
+<P>
+
+<H4><A NAME="SECTION00310020000000000000">
+Holding iterators</A>
+</H4>
+We also could hold a list of iterators of the single <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s.
+This would also cause low CPU usage, because usually, the iterators only
+need to be incremented once. However, it is pretty complex to implement,
+because the iterators may become totally wrong (because of a seek in the
+song), and we must iterate through a whole list of iterators.
+
+<P>
+
+<H4><A NAME="SECTION00310030000000000000">
+Just use the current data access functions</A>
+</H4>
+By just using the current functions for accessing automation data,
+we might get a quick-and-dirty solution, which however wastes way too
+much CPU ressources. This is because on <SPAN CLASS="textit">every single frame</SPAN>, we
+need to do a binary search on multiple controller lists.
+
+<P>
+
+<H1><A NAME="SECTION00400000000000000000">
+Feature requests</A>
+</H1>
+
+<H1><A NAME="SECTION00410000000000000000">
+Per-Part automation and more on automation</A>
+</H1> Automation shall be undo-able. Automation shall reside in parts which
+are exchangeable, clonable etc (like the MIDI- and Wave-Parts).
+Global per-synth/per-audiotrack automation shall also be available, but
+this can also be implemented as special case of part automation (one
+long part).
+
+<P>
+
+<H1><A NAME="SECTION00420000000000000000">
+Pre-Rendering tracks</A>
+</H1>
+
+<H2><A NAME="SECTION00421000000000000000">
+The feature</A>
+</H2>
+All tracks shall be able to be "pre-renderable". Pre-rendering shall
+be "layered". Pre-rendering shall act like a transparent audio cache:
+Audio data is (redundantly) stored, wasting memory in order to save CPU.
+
+<P>
+That is: Each track owns one or more wave-recordings of the length of
+the song. If the user calls "pre-render" on a track, then this track
+is played quasi-solo (see below), and the raw audio data is recorded
+and stored in the "layer 0" wave recording. If the user has any effects
+set up to be applied, then each effect is applied on a different layer
+(creating layer 1, layer 2 etc).
+
+<P>
+This means, that also MIDI and drum tracks can have effects (which
+usually only operate on audio, but we HAVE audio data because of this
+prerendering).
+
+<P>
+Furthermore, MusE by default does not send MIDI events to the synthesizers
+but instead just plays back the last layer of the prerecording (for
+MIDI tracks), or does not pipe the audio data through the whole plugin
+chain (causing cpu usage), but instead just plays back the last layer.
+The hearable result shall be the same.
+
+<P>
+Once the user changes any parameter (automation data or plugins for
+wave tracks, MIDI events or effect plugin stuff for MIDI tracks),
+then MusE shall generate the sound for this particular track in the
+"old" way (send MIDI data to synthes, or pipe audio data through plugins).
+(So that the user will not even notice that MusE actually pre-renderered
+stuff.) Either MusE automatically records this while playback (if possible)
+or prompts the user to accordingly set up his cabling and then record
+it. Or (temporarily) disables prerecording for this track, falling back
+to the plain old way of generating sound.
+
+<P>
+<SPAN CLASS="textit">Quasi-solo</SPAN> means: For wave tracks, just solo the track. For MIDI
+tracks, mute all tracks which are not on the same synth (channel?),
+and mute all <SPAN CLASS="textit">note</SPAN> events which are not on the quasi-soloed track.
+This causes MusE to still play any controller events from different
+tracks, because they might have effects on the quasi-soloed track. (You
+can have notes on channel 1 on one track and controller stuff on channel
+1 on another track; then you would need quasi-solo to get proper results.)
+
+<P>
+
+<H2><A NAME="SECTION00422000000000000000">
+Use cases</A>
+</H2>
+
+<H4><A NAME="SECTION00422010000000000000">
+Saving CPU</A>
+</H4>
+On slow systems, this is neccessary for songs with lots of, or demanding
+(or both) soft synthes / plugins. Even if the synth or plugin is so
+demanding that your system is not able to produce sound in real-time,
+then with this feature you'll be able to use the synth (this will make
+editing pretty laggish, because for a change you need to re-render at
+least a part before you can listen to it, but better than being unable
+to use the synth at all!)
+
+<P>
+
+<H4><A NAME="SECTION00422020000000000000">
+Exporting as audio project</A>
+</H4>
+Using pre-rendering on all tracks, you easily can export your project
+as multi-track audio file (for use with Ardour or similar DAWs).
+Just take the last layer of each track, and write the raw audio data
+into the file, and you're done. (Maybe we are even able to write down
+the raw-raw layer0 audio data plus information about used plugins and
+settings etc..?)
+
+<P>
+
+<H4><A NAME="SECTION00422030000000000000">
+Mobile audio workstations</A>
+</H4>
+You might want to work a bit on your audio projects on your notebook
+while you're not at home, not having access to your hardware synthesizers.
+Using this feature, you could have pre-recorded the stuff in your studio
+before, and now can at least fiddle around with the non-hw-synth-dependent
+parts of your song, while still having your <SPAN CLASS="textit">full</SPAN> song with you.
+
+<P>
+
+<H4><A NAME="SECTION00422040000000000000">
+Applying effects on MIDI tracks</A>
+</H4>
+If you have many physical audio inputs, you might already be able to
+apply effect chains on MIDI tracks, by wiring the synthes' audio
+outputs to your soundcard's inputs, and applying the effects on
+dedicated input tracks you have to create. This requires you to have
+expensive hardware, and is pretty complicated, because you need one
+additional track per MIDI synth.
+
+<P>
+This feature allows you to apply effects on single MIDI tracks, and not
+only on full MIDI synthes, and doesn't require you to be have that
+many physical audio inputs (you need to manually replug your synthes,
+however).
+
+<P>
+
+<H2><A NAME="SECTION00423000000000000000">
+Possible scenarios</A>
+</H2>
+
+<H4><A NAME="SECTION00423010000000000000">
+Setting it up</A>
+</H4>
+Create a wave track, MusE will allow you to set or unset prerendering
+for every plugin in the plugin rack (recording the actual track is
+useless because it would be a plain copy).
+Create a MIDI track, MusE will ask you on which physical audio input
+your synth is connected. Setting up multiple synthes on one physical
+audio in is allowed, see below.
+
+<P>
+
+<H4><A NAME="SECTION00423020000000000000">
+Pre-rendering stuff</A>
+</H4>
+When the user presses the "pre-render" button, all tracks which have
+been changed since their last pre-rendering will be re-rendered.
+If you have multiple hardware synthes set up as they were connected
+to one physical audio input port, MusE will prompt you to first plug
+the proper cable in.
+
+<P>
+
+<H4><A NAME="SECTION00423030000000000000">
+Making changes</A>
+</H4>
+Change a note in a MIDI part, move or delete a part or change automation
+parameters. MusE will temporarily disable the pre-rendered information
+and instead generate the sound via sending out MIDI events, piping stuff
+through effect chains or similar. If you play back the whole song, or
+if you manually trigger a re-rendering of a track via the context menu,
+MusE will play back the stuff, record it again and re-enable the
+pre-rendered information.
+
+<P>
+
+<H2><A NAME="SECTION00424000000000000000">
+Extensions</A>
+</H2>
+
+<H4><A NAME="SECTION00424010000000000000">
+Automatic discovery of physical audio connections</A>
+</H4>
+The user plugs all (or only some) synthes' audio outs into the available
+audio inputs, then runs automatic discovery. This will send MIDI events
+to each synthesizer, and look on which audio in there's activity. Then
+it will assume that the synthesizer is connected to that particular
+audio in. Audio ins which show activity before any MIDI events were
+sent are not considered, as they're probably connected to microphones
+or other noise-generating non-synthes.
+
+<P>
+
+<H4><A NAME="SECTION00424020000000000000">
+Audio export</A>
+</H4>
+As described in the Use cases, MusE can allow you to export your song
+in some multitrack audio format.
+
+<P>
+
+<H4><A NAME="SECTION00424030000000000000">
+Cheap/Faked changes</A>
+</H4>
+For expensive or unavailable synthes, changing the Volume midi controller,
+the Pan controller or similar "easy" controllers will not trigger a
+complete re-rendering, but instead "fake" the change, by changing
+the volume data directly on the recorded wave. This might require some
+learning and might even get pretty complicated.
+
+<P>
+
+<H4><A NAME="SECTION00424040000000000000">
+Intelligent re-recording</A>
+</H4>
+For tiny changes, MusE shall only re-render the relevant part. If you
+change some MIDI notes, then begin re-recording shortly before the
+changes, and end re-recording as soon as the recorded stuff doesn't
+differ to much from the stuff coming from the synth. Then properly
+blend the old recording with the updated part.
+
+<P>
+
+<H1><A NAME="SECTION00430000000000000000">
+Slotted editors</A>
+</H1>
+Currently, MusE has the pianoroll editor, drum editor, score editor,
+then the controller editor which is inside the pianoroll/drum editor.
+All these editors have a very similar concept: the "time axis" is
+vertical and (almost) linear, they handle parts, and events are
+manipulated similarly.
+
+<P>
+A unified editor shall be created which allows you to combine different
+kinds of editors in one window, properly aligned against each other.
+These "different kinds of editors" shall be handled as "slots"; one
+unified editor window consists of:
+
+<UL>
+<LI>A menu bar, containing stuff suitable for the complete window,
+ which might include window name, MDI-ness etc.
+</LI>
+<LI>A toolbar which contains controls suitable for every single slot.
+</LI>
+<LI>A container with one or more slots; the slots can be scrolled in
+ y-direction if there are multipe slots.
+</LI>
+<LI>A time-scrollbar with zoom
+</LI>
+</UL>
+
+<P>
+Each slot contains the following:
+
+<UL>
+<LI>A menu button, button box or control panel for setting up this
+ particular slot. This could contain "note head colors", "show
+ a transposing instrument" etc for score edit slots, "event
+ rectangle color", "grid size" and "snap to grid" for pianoroll/
+ drum editors.
+</LI>
+<LI>The actual canvas
+</LI>
+<LI>A y-direction scroll bar, possibly with zoom control (for
+ pianoroll editor)
+</LI>
+</UL>
+
+<P>
+The main window does not show its scroll bar if there is only one slot,
+because the slot's scrollbar is sufficient then.
+
+<P>
+Slots can be added, destroyed, moved around, maybe even merged (if the
+slot types allow it); basically, you can compare them with the staves
+in the score editor.
+
+<P>
+The slots shall align against each other, that is, if a score editor
+slot displays a key change with lots of accidentials, then all other
+slots shall either also display the key change (if they're score slots)
+or display a gap. Events which happen at the same time shall be at the
+same x-coordinate, regardless which slot they are.
+
+<P>
+
+<H1><A NAME="SECTION00440000000000000000">
+Controller master values</A>
+</H1>
+All controllers (MIDI-controllers and also automation controllers)
+shall have one set of "master values" which allow you to set a gain and
+a bias. Instead of the actual set value, <!-- MATH
+ $\textrm{value} * \textrm{bias}
++ textrm{bias}$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="180" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img1.png"
+ ALT="$\textrm{value} * \textrm{bias}
++ textrm{bias}$"></SPAN> shall be sent to the MIDI device / the plugin. For
+controllers like "pan", the unbiased values shall be transformed, that
+is, a pan of 64, with <!-- MATH
+ $\textrm{bias}=2$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="61" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
+ SRC="img2.png"
+ ALT="$\textrm{bias}=2$"></SPAN> and <!-- MATH
+ $\textrm{gain}=0.5$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="75" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img3.png"
+ ALT="$\textrm{gain}=0.5$"></SPAN>, shall
+be transformed to 66 (because 64 is actually 0, while 0 is actually -64).
+These values shall be set in the arranger and whereever the actual
+controller/automation values can be edited.
+
+<P>
+
+<H1><A NAME="SECTION00450000000000000000">
+Enabled-indicator while recording</A>
+</H1>
+The MusE-plugin-GUIs shall display a small LED displaying whether a
+controller is currently enabled or disabled. By clicking this LED, the
+enabled state shall be switched.
+
+<P>
+Furthermore, there shall be a dedicated window which only lets you switch
+enabled/disabled states. This will be useful when using external GUIs
+or the MIDI-controller-to-automation feature, to re-enable a controller
+when in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> mode.
+
+<P>
+
+<H1><A NAME="SECTION00460000000000000000">
+Linear automation editing</A>
+</H1>
+While holding some modifier key (like shift), operating the MusE-native-
+GUI sliders shall only generate control points when clicking and when
+releasing the slider. This will result in linear graphs for continous
+controllers, and in large steps for discrete controllers (which is in
+particular useful for stuff like "which low/high-pass filter type to use").
+
+<P>
+Maybe make this behaviour default for discrete controllers?
+
+<P>
+
+<H1><A NAME="SECTION00470000000000000000"></A> <A NAME="symbolic_ports"></A>
+<BR>
+Symbolic names for MIDI ports
+</H1>
+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7").
+The mapping between these symbolic names and the hardware port (like
+"ALSA midi out port") is stored in the global configuration.
+
+<P>
+Song files only specify the symbolic names as the ports associated with
+their tracks. No information about physical devices/port names, but only
+symbolic names are stored in the song file.
+
+<P>
+This resolves the issues mentioned in <A HREF="#portconfig_sucks">1.2</A>, and also
+allows the user to share his pieces with other people: They would only
+have to set up that symbolic-to-hardware mapping once (collisions are
+unlikely, because an equal symbolic name should usually mean the same
+device) and are happy, instead of having to re-map <SPAN CLASS="textit">every</SPAN> port
+for <SPAN CLASS="textit">every</SPAN> song.
+
+<P>
+<BR><HR>
+
+</BODY>
+</HTML>
diff --git a/muse2/doc/html/single/developer_docs/img1.png b/muse2/doc/html/single/developer_docs/img1.png
new file mode 100644
index 00000000..85b2087d
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/img1.png
Binary files differ
diff --git a/muse2/doc/html/single/developer_docs/img2.png b/muse2/doc/html/single/developer_docs/img2.png
new file mode 100644
index 00000000..b5a0cc4b
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/img2.png
Binary files differ
diff --git a/muse2/doc/html/single/developer_docs/img3.png b/muse2/doc/html/single/developer_docs/img3.png
new file mode 100644
index 00000000..ac4a584a
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/img3.png
Binary files differ
diff --git a/muse2/doc/html/single/developer_docs/index.html b/muse2/doc/html/single/developer_docs/index.html
new file mode 100644
index 00000000..9cf45e45
--- /dev/null
+++ b/muse2/doc/html/single/developer_docs/index.html
@@ -0,0 +1,1745 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<!--Converted with LaTeX2HTML 2008 (1.71)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<HTML>
+<HEAD>
+<TITLE>MusE Documentation</TITLE>
+<META NAME="description" CONTENT="MusE Documentation">
+<META NAME="keywords" CONTENT="developer_docs">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="developer_docs.css">
+
+</HEAD>
+
+<BODY >
+<BR>
+
+<H2><A NAME="SECTION00100000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
+
+<UL CLASS="TofC">
+<LI><A NAME="tex2html22"
+ HREF="developer_docs.html#SECTION00200000000000000000">Internals - how it works</A>
+<UL>
+<LI><A NAME="tex2html23"
+ HREF="developer_docs.html#SECTION00210000000000000000">User interface programming</A>
+<LI><A NAME="tex2html24"
+ HREF="developer_docs.html#SECTION00220000000000000000">Configuration</A>
+<LI><A NAME="tex2html25"
+ HREF="developer_docs.html#SECTION00230000000000000000">User controls and automation</A>
+<UL>
+<LI><A NAME="tex2html26"
+ HREF="developer_docs.html#SECTION00231000000000000000">Handling user input</A>
+</UL>
+</UL>
+<BR>
+<LI><A NAME="tex2html27"
+ HREF="developer_docs.html#SECTION00300000000000000000">Design decisions</A>
+<UL>
+<LI><A NAME="tex2html28"
+ HREF="developer_docs.html#SECTION00310000000000000000">Automation</A>
+</UL>
+<BR>
+<LI><A NAME="tex2html29"
+ HREF="developer_docs.html#SECTION00400000000000000000">Feature requests</A>
+<UL>
+<LI><A NAME="tex2html30"
+ HREF="developer_docs.html#SECTION00410000000000000000">Per-Part automation and more on automation</A>
+<LI><A NAME="tex2html31"
+ HREF="developer_docs.html#SECTION00420000000000000000">Pre-Rendering tracks</A>
+<UL>
+<LI><A NAME="tex2html32"
+ HREF="developer_docs.html#SECTION00421000000000000000">The feature</A>
+<LI><A NAME="tex2html33"
+ HREF="developer_docs.html#SECTION00422000000000000000">Use cases</A>
+<LI><A NAME="tex2html34"
+ HREF="developer_docs.html#SECTION00423000000000000000">Possible scenarios</A>
+<LI><A NAME="tex2html35"
+ HREF="developer_docs.html#SECTION00424000000000000000">Extensions</A>
+</UL>
+<LI><A NAME="tex2html36"
+ HREF="developer_docs.html#SECTION00430000000000000000">Slotted editors</A>
+<LI><A NAME="tex2html37"
+ HREF="developer_docs.html#SECTION00440000000000000000">Controller master values</A>
+<LI><A NAME="tex2html38"
+ HREF="developer_docs.html#SECTION00450000000000000000">Enabled-indicator while recording</A>
+<LI><A NAME="tex2html39"
+ HREF="developer_docs.html#SECTION00460000000000000000">Linear automation editing</A>
+<LI><A NAME="tex2html40"
+ HREF="developer_docs.html#SECTION00470000000000000000">Symbolic names for MIDI ports</A>
+</UL></UL>
+<!--End of Table of Contents-->
+<H1><A NAME="SECTION00200000000000000000">
+Internals - how it works</A>
+</H1>
+This chapter explains how MusE is built internally, and is meant
+to be an aid for developers wanting to quickly start up with MusE.
+For details on <SPAN CLASS="textit">why</SPAN> stuff is done please refer to the following
+chapter.
+
+<P>
+
+<H1><A NAME="SECTION00210000000000000000">
+User interface programming</A>
+</H1>
+We use the QT Toolkit for GUI- and other programming. The <SPAN CLASS="textit">QT-Assistant</SPAN>
+is an important tool for getting help. Almost everything can be looked
+up there.
+
+<P>
+GUIs can be either be hardcoded (see <TT>fterfirsta`a=95 _ `a=58 :
+ `a&gt;64
+ `a&lt;91 aaa
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rranger.cpp</TT> for an example)
+or can be created using <SPAN CLASS="textit">QT-Designer</SPAN> (see the dialogs under
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/function_dialogs/</TT> for mostly cleanly-written examples).
+Don't forget to add your <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>pp</TT>, <TT>fterfirsth`h=95 _ `h=58 :
+ `h&gt;64
+ `h&lt;91 hhh
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>></TT> and <TT>fterfirstu`u=95 _ `u=58 :
+ `u&gt;64
+ `u&lt;91 uuu
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>i</TT> files to the
+corresponding sections in the <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>MakeLists.txt</TT>!
+
+<P>
+Additionally, MusE offers some custom widgets, like menu title items etc.
+Following, there will be a small, unordered list about custom widgets:
+
+<UL>
+<LI><TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MenuTitleItem</TT>: Provides a title-bar in a <TT>fterfirstQ`Q=95 _ `Q=58 :
+ `Q&gt;64
+ `Q&lt;91 QQQ
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>Menu</TT>.
+<BR>
+Usage: <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>omeMenu-&gt;addAction(new MusEGui::MenuTitleItem(tr("fnord"), someMenu));</TT>
+<BR>
+Defined in <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/menutitleitem.h</TT>.
+</LI>
+<LI><TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::PopupMenu</TT>: Provides a <TT>fterfirstQ`Q=95 _ `Q=58 :
+ `Q&gt;64
+ `Q&lt;91 QQQ
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>Menu</TT>-like menu which
+ can stay open after the user checks a checkable action.
+<BR>
+Usage: just create a <TT>fterfirstn`n=95 _ `n=58 :
+ `n&gt;64
+ `n&lt;91 nnn
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ew PopupMenu( true|false )</TT> instead of
+ a <TT>fterfirstn`n=95 _ `n=58 :
+ `n&gt;64
+ `n&lt;91 nnn
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ew QMenu()</TT>. (<TT>fterfirstt`t=95 _ `t=58 :
+ `t&gt;64
+ `t&lt;91 ttt
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rue</TT> means 'stay open')
+<BR>
+Defined in <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>idgets/popupmenu.h</TT>.
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00220000000000000000"></A> <A NAME="portconfig_sucks"></A>
+<BR>
+Configuration
+</H1>
+Configuration is a bit pesky in MusE in its current state. If you get
+confused by reading this chapter, that's a sign of a sane mind.
+
+<P>
+There are three kinds of configuration items:
+
+<UL>
+<LI>(1) Global configuration, like coloring schemes, plugin categories, MDI-ness settings
+</LI>
+<LI>(2) Per-Song configuration, like whether to show or hide certain track types in the arranger
+</LI>
+<LI>(3) Something in between, like MIDI port settings etc. They obviously actually are
+ global configuration issues (or ought to be), but also obviously must be stored
+ in the song file for portability. (This problem could possibly be solved by
+ the feature proposal in <A HREF="#symbolic_ports">3.7</A>.
+</LI>
+</UL>
+
+<P>
+
+<H4><A NAME="SECTION00220010000000000000">
+Reading configuration</A>
+</H4>
+<TT>fterfirstv`v=95 _ `v=58 :
+ `v&gt;64
+ `v&lt;91 vvv
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>oid MusECore::readConfiguration(Xml&amp;, bool, bool)</TT> in
+<TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>onf.cpp</TT> is the central point
+of reading configuration. It is called when MusE is started first
+(by <TT>fterfirstb`b=95 _ `b=58 :
+ `b&gt;64
+ `b&lt;91 bbb
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ool MusECore::readConfiguration()</TT>), and also when a
+song is loaded.
+<BR>It can be instructed whether to read MIDI ports (3), global configuration
+and MIDI ports (1+3). Per-Song configuration is always read (2).
+
+<P>
+When adding new configuration items and thus altering <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration()</TT>,
+you must take care to place your item into the correct section. The code is
+divided into the following sections:
+
+<UL>
+<LI>Global and/or per-song configuration (3)
+</LI>
+<LI>Global configuration (1)
+</LI>
+<LI>Code for skipping obsolete entries
+</LI>
+</UL>
+
+<P>
+The sections are divided by comments (they contain <TT>--</TT>, so just
+search for them). Please do not just remove code for reading obsolete entries,
+but always add an appropriate entry to the 'skipping' section in order to
+prevent error messages when reading old configs.
+
+<P>
+
+<H4><A NAME="SECTION00220020000000000000">
+Writing configuration</A>
+</H4>
+Global configuration is written using the
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MusE::writeGlobalConfiguration()</TT> functions, while
+per-song-config is written by <TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGui::MusE::writeConfiguration()</TT>
+(notice the missing <TT>fterfirstG`G=95 _ `G=58 :
+ `G&gt;64
+ `G&lt;91 GGG
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>lobal</TT>; both implemented in <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>onf.cpp</TT>).
+
+<P>
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteConfiguration</TT> is actually just a subset of the code in
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>. <SPAN CLASS="textbf">Duplicate code!</SPAN>
+<P>
+
+<H4><A NAME="SECTION00220030000000000000">
+Song state</A>
+</H4>
+Additionally to per-song configuration, there is the song's state.
+This contains "the song", that is all tracks, parts and note events,
+together with information about the currently opened windows, their
+position, size, settings and so on. Adding new items here is actually
+pretty painless: Configuration is read and written using
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usECore::Song::read</TT> and <TT>fterfirst:`:=95 _ `:=58 :
+ `:&gt;64
+ `:&lt;91 :::
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>:write</TT>, both implemented in
+<TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ongfile.cpp</TT>. There are no caveats.
+
+<P>
+
+<H4><A NAME="SECTION00220040000000000000">
+How to add new items</A>
+</H4>
+When adding global configuration items, then add them into the second
+block ("global configuration") in <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration</TT> and into
+<TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>.
+
+<P>
+When adding just-per-song items, better don't bother to touch the
+"configuration" code and just add it to the song's state (there might
+be rare exceptions).
+
+<P>
+When adding global configuration items, make sure you add them into the
+correct section of <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eadConfiguration</TT>, and into <TT>fterfirstw`w=95 _ `w=58 :
+ `w&gt;64
+ `w&lt;91 www
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>riteGlobalConfiguration</TT>.
+
+<P>
+
+<H1><A NAME="SECTION00230000000000000000">
+User controls and automation</A>
+</H1>
+
+<H2><A NAME="SECTION00231000000000000000">
+Handling user input</A>
+</H2>
+
+<H3><A NAME="SECTION00231100000000000000">
+Plugins and synthesizers</A>
+</H3>
+
+<H4><A NAME="SECTION00231110000000000000">
+Overview</A>
+</H4>
+When the user launches a plugin's GUI, either a MusE-window with
+the relevant controls is shown, or the native GUI is launched. MusE
+will communicate with this native GUI through OSC (Open Sound Control).
+The relevant classes are <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginGui</TT>, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginIBase</TT>
+(in <TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>lugin.h</TT>) and <TT>fterfirstO`O=95 _ `O=58 :
+ `O&gt;64
+ `O&lt;91 OOO
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>scIF</TT> (in <TT>fterfirsto`o=95 _ `o=58 :
+ `o&gt;64
+ `o&lt;91 ooo
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>sc.h</TT>).
+
+<P>
+If the user changes a GUI element, first the corresponding control is
+disabled, making MusE not steadily update it through automation
+while the user operates it. Then MusE will update the plugin's parameter
+value, and also record the new value. When appropriate, the controller
+is enabled again.
+
+<P>
+
+<H4><A NAME="SECTION00231120000000000000">
+Processing the input, recording</A>
+</H4>
+Upon operating a slider, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginIBase::setParam</TT> is called,
+which usually writes the control change into the ringbuffer
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. (<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::apply()</TT>,
+<TT>fterfirstD`D=95 _ `D=58 :
+ `D&gt;64
+ `D&lt;91 DDD
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ssiSynthIF::getData()</TT> will read this ringbuffer and
+do the processing accordingly). Furthermore, <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::recordAutomation</TT>
+is called, which either directly modifies the controller lists or writes
+the change into a "to be recorded"-list (<TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_recEvents</TT>)
+(depending on whether the song is stopped or played).
+
+<P>
+The <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_recEvents</TT> list consists of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlRecVal</TT>
+items (see <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trl.h</TT>), which hold the following data:
+
+<UL>
+<LI>the frame where the change occurred
+</LI>
+<LI>the value
+</LI>
+<LI>the type, which can be <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT>, <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_VAL</TT> or <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT>.
+ <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_VAL</TT> are written by every <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>udioTrack::recordAutomation</TT>
+ call, <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT> and <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT> are generated by
+ <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::startAutoRecord</TT> and <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>topAutoRecord</TT>, respectively.
+</LI>
+<LI>and the id of the controller which is affected
+</LI>
+</UL>
+It is processed when the song is stopped. The call path for this is:
+<TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::stopRolling</TT> calls <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::processAutomationEvents</TT>
+calls <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::processAutomationEvents</TT>.
+This function removes the old events from the track's controller list
+and replaces them with the new events from <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>recEvents</TT>. In
+<TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode, just all controller events within the recorded
+range are erased; in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> mode, the <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_START</TT>
+and <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>RVT_STOP</TT> types of the <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlRecVal</TT> events are used
+to determine the range(s) which should be wiped.
+
+<P>
+
+<H4><A NAME="SECTION00231130000000000000">
+How it's stored</A>
+</H4>
+Automation data is kept in <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_controller</TT>, which is a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlListList</TT>, that is, a list of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continuous (a new control
+point results in the value slowly sloping to the new value).
+Furthermore, it stores a <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>curVal</TT> (accessed by <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>urVal()</TT>),
+which holds the currently active value, which can be different from the
+actually stored value because of user interaction. This value is also
+used when there is no stored automation data.
+
+<P>
+<TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::addController</TT> and <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>emoveController</TT> are used to add/remove whole controller types; the most important functions which
+access <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>controller</TT> are:
+
+<UL>
+<LI><TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rocessAutomationEvents</TT>, <TT>fterfirstr`r=95 _ `r=58 :
+ `r&gt;64
+ `r&lt;91 rrr
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ecordAutomation</TT>,
+ <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>tartAutoRecord</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>topAutoRecord</TT>: see above.
+</LI>
+<LI><TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eekPrevACEvent</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>eekNextACEvent</TT>, <TT>fterfirste`e=95 _ `e=58 :
+ `e&gt;64
+ `e&lt;91 eee
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>raseACEvent</TT>,
+ <TT>fterfirste`e=95 _ `e=58 :
+ `e&gt;64
+ `e&lt;91 eee
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>raseRangeACEvents</TT>, <TT>fterfirsta`a=95 _ `a=58 :
+ `a&gt;64
+ `a&lt;91 aaa
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ddACEvent</TT>, <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>hangeACEvent</TT>,
+ which do the obvious
+</LI>
+<LI><TT>fterfirstp`p=95 _ `p=58 :
+ `p&gt;64
+ `p&lt;91 ppp
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginCtrlVal</TT>, <TT>fterfirsts`s=95 _ `s=58 :
+ `s&gt;64
+ `s&lt;91 sss
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>etPluginCtrlVal</TT>: the first
+ returns the current value according to the <TT>fterfirst_`_=95 _ `_=58 :
+ `_&gt;64
+ `_&lt;91 ___
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>controller</TT>
+ list, the second only sets the <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>urVal</TT>, but does not
+ insert any events.
+</LI>
+</UL>
+
+<P>
+Whenever a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> has been manipulated,
+<TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGlobal::song-&gt;controllerChange(Track*)</TT> shall be called,
+which emits the <TT>fterfirstM`M=95 _ `M=58 :
+ `M&gt;64
+ `M&lt;91 MMM
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>usEGlobal::song-&gt;controllerChanged(Track*)</TT>
+signal in order to inform any parts of MusE about the change (currently,
+only the arranger's part canvas utilizes this).
+
+<P>
+
+<H4><A NAME="SECTION00231140000000000000">
+Enabling and disabling controllers</A>
+</H4>
+Disabling the controller is both dependent from the current automation
+mode and from whether the GUI is native or not.
+In <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode, once a slider is touched (for MusE-GUIs) or
+once a OSC control change is received (for native GUIs), the control
+is disabled until the song is stopped or seeked.
+
+<P>
+In <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> (and currently (r1492) <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_READ</TT>, but
+that's to be fixed) mode, once a MusE-GUI's slider is pressed down, the
+corresponding control is disabled. Once the slider is released, the
+control is re-enabled again. Checkboxes remain in "disabled" mode,
+however they only affect the recorded automation until the last toggle
+of the checkbox. (Example: start the song, toggle the checkbox, toggle
+it again, wait 10 seconds, stop the song. This will NOT overwrite the
+last 10 seconds of automation data, but everything between the first
+and the last toggle.). For native GUIs, this is a bit tricky, because
+we don't have direct access to the GUI widgets. That is, we have no
+way to find out whether the user doesn't touch a control at all, or
+whether he has it held down, but just doesn't operate it. The current
+behaviour for native GUIs is to behave like in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_WRITE</TT> mode.
+
+<P>
+The responsible functions are: <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::oscControl</TT> and
+<TT>fterfirstD`D=95 _ `D=58 :
+ `D&gt;64
+ `D&lt;91 DDD
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ssiSynthIF::oscControl</TT> for handling native GUIs,
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::ctrlPressed</TT> and <TT>fterfirstc`c=95 _ `c=58 :
+ `c&gt;64
+ `c&lt;91 ccc
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlReleased</TT> for MusE
+default GUIs and <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::guiParamPressed</TT>,
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiParamReleased</TT>, <TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSliderPressed</TT> and
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSliderReleased</TT> for MusE GUIs read from a UI file;
+<TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiSlider*</TT> obviously handle sliders, while <TT>fterfirstg`g=95 _ `g=58 :
+ `g&gt;64
+ `g&lt;91 ggg
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>uiParam*</TT>
+handle everything else which is not a slider. They call
+<TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableController</TT> to enable/disable it.
+
+<P>
+Furthermore, on every song stop or seek, <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+is called, which re-enables all controllers again. The call paths for
+this are:
+
+<UL>
+<LI>For stop: <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::stopRolling</TT> calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::processAutomationEvents</TT> calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::clearRecAutomation</TT> calls
+ <TT>fterfirstT`T=95 _ `T=58 :
+ `T&gt;64
+ `T&lt;91 TTT
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>rack::clearRecAutomation</TT> calls
+ <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+</LI>
+<LI>For seek: <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udio::seek</TT> sends a message ("<TT>fterfirstG`G=95 _ `G=58 :
+ `G&gt;64
+ `G&lt;91 GGG
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>></TT>") to
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::seqSignal</TT> which calls
+ <TT>fterfirstS`S=95 _ `S=58 :
+ `S&gt;64
+ `S&lt;91 SSS
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>ong::clearRecAutomation</TT> which calls
+ <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::enableAllControllers</TT>
+</LI>
+</UL>
+
+<P>
+
+<H1><A NAME="SECTION00300000000000000000">
+Design decisions</A>
+</H1>
+
+<H1><A NAME="SECTION00310000000000000000">
+Automation</A>
+</H1>
+As of revision 1490, automation is handled in two ways: User-generated
+(live) automation data (generated by the user moving sliders while playing)
+is fed into <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. Automation data is kept
+in <TT>fterfirstA`A=95 _ `A=58 :
+ `A&gt;64
+ `A&lt;91 AAA
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>udioTrack::_controller</TT>, which is a <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlListList</TT>,
+that is, a list of <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s, that is, a list of lists of
+controller-objects which hold the control points of the automation graph.
+The <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT> also stores whether the list is meant discrete
+(a new control point results in a value-jump) or continous (a new control
+point results in the value slowly sloping to the new value).
+
+<P>
+While <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT> can be queried very quickly and
+thus is processed with a very high resolution (only limited by the
+minimum control period setting), the automation value are expensive to
+query, and are only processed once in an audio <SPAN CLASS="textit">driver</SPAN> period.
+This might lead to noticeable jumps in value.
+
+<P>
+This could possibly be solved in two ways:
+
+<H4><A NAME="SECTION00310010000000000000">
+Maintaining a slave control list</A>
+</H4>
+This approach would maintain a fully redundant slave control list,
+similar to <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>. This list must be updated
+every time any automation-related thing is changed, and shall contain
+every controller change as a tuple of controller number and value.
+This could be processed in the same loop as <TT>fterfirstP`P=95 _ `P=58 :
+ `P&gt;64
+ `P&lt;91 PPP
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>luginI::_controlFifo</TT>,
+making it comfortable to implement; furthermore, it allows to cleanly
+offer automation-settings at other places in future (such as storing
+automation data in parts or similar).
+
+<P>
+
+<H4><A NAME="SECTION00310020000000000000">
+Holding iterators</A>
+</H4>
+We also could hold a list of iterators of the single <TT>fterfirstC`C=95 _ `C=58 :
+ `C&gt;64
+ `C&lt;91 CCC
+
+ <`<=95 _ `<=58 :
+ `<&gt;64
+ `<&lt;91 <<<
+
+ c@amelhyph<269>>trlList</TT>s.
+This would also cause low CPU usage, because usually, the iterators only
+need to be incremented once. However, it is pretty complex to implement,
+because the iterators may become totally wrong (because of a seek in the
+song), and we must iterate through a whole list of iterators.
+
+<P>
+
+<H4><A NAME="SECTION00310030000000000000">
+Just use the current data access functions</A>
+</H4>
+By just using the current functions for accessing automation data,
+we might get a quick-and-dirty solution, which however wastes way too
+much CPU ressources. This is because on <SPAN CLASS="textit">every single frame</SPAN>, we
+need to do a binary search on multiple controller lists.
+
+<P>
+
+<H1><A NAME="SECTION00400000000000000000">
+Feature requests</A>
+</H1>
+
+<H1><A NAME="SECTION00410000000000000000">
+Per-Part automation and more on automation</A>
+</H1> Automation shall be undo-able. Automation shall reside in parts which
+are exchangeable, clonable etc (like the MIDI- and Wave-Parts).
+Global per-synth/per-audiotrack automation shall also be available, but
+this can also be implemented as special case of part automation (one
+long part).
+
+<P>
+
+<H1><A NAME="SECTION00420000000000000000">
+Pre-Rendering tracks</A>
+</H1>
+
+<H2><A NAME="SECTION00421000000000000000">
+The feature</A>
+</H2>
+All tracks shall be able to be "pre-renderable". Pre-rendering shall
+be "layered". Pre-rendering shall act like a transparent audio cache:
+Audio data is (redundantly) stored, wasting memory in order to save CPU.
+
+<P>
+That is: Each track owns one or more wave-recordings of the length of
+the song. If the user calls "pre-render" on a track, then this track
+is played quasi-solo (see below), and the raw audio data is recorded
+and stored in the "layer 0" wave recording. If the user has any effects
+set up to be applied, then each effect is applied on a different layer
+(creating layer 1, layer 2 etc).
+
+<P>
+This means, that also MIDI and drum tracks can have effects (which
+usually only operate on audio, but we HAVE audio data because of this
+prerendering).
+
+<P>
+Furthermore, MusE by default does not send MIDI events to the synthesizers
+but instead just plays back the last layer of the prerecording (for
+MIDI tracks), or does not pipe the audio data through the whole plugin
+chain (causing cpu usage), but instead just plays back the last layer.
+The hearable result shall be the same.
+
+<P>
+Once the user changes any parameter (automation data or plugins for
+wave tracks, MIDI events or effect plugin stuff for MIDI tracks),
+then MusE shall generate the sound for this particular track in the
+"old" way (send MIDI data to synthes, or pipe audio data through plugins).
+(So that the user will not even notice that MusE actually pre-renderered
+stuff.) Either MusE automatically records this while playback (if possible)
+or prompts the user to accordingly set up his cabling and then record
+it. Or (temporarily) disables prerecording for this track, falling back
+to the plain old way of generating sound.
+
+<P>
+<SPAN CLASS="textit">Quasi-solo</SPAN> means: For wave tracks, just solo the track. For MIDI
+tracks, mute all tracks which are not on the same synth (channel?),
+and mute all <SPAN CLASS="textit">note</SPAN> events which are not on the quasi-soloed track.
+This causes MusE to still play any controller events from different
+tracks, because they might have effects on the quasi-soloed track. (You
+can have notes on channel 1 on one track and controller stuff on channel
+1 on another track; then you would need quasi-solo to get proper results.)
+
+<P>
+
+<H2><A NAME="SECTION00422000000000000000">
+Use cases</A>
+</H2>
+
+<H4><A NAME="SECTION00422010000000000000">
+Saving CPU</A>
+</H4>
+On slow systems, this is neccessary for songs with lots of, or demanding
+(or both) soft synthes / plugins. Even if the synth or plugin is so
+demanding that your system is not able to produce sound in real-time,
+then with this feature you'll be able to use the synth (this will make
+editing pretty laggish, because for a change you need to re-render at
+least a part before you can listen to it, but better than being unable
+to use the synth at all!)
+
+<P>
+
+<H4><A NAME="SECTION00422020000000000000">
+Exporting as audio project</A>
+</H4>
+Using pre-rendering on all tracks, you easily can export your project
+as multi-track audio file (for use with Ardour or similar DAWs).
+Just take the last layer of each track, and write the raw audio data
+into the file, and you're done. (Maybe we are even able to write down
+the raw-raw layer0 audio data plus information about used plugins and
+settings etc..?)
+
+<P>
+
+<H4><A NAME="SECTION00422030000000000000">
+Mobile audio workstations</A>
+</H4>
+You might want to work a bit on your audio projects on your notebook
+while you're not at home, not having access to your hardware synthesizers.
+Using this feature, you could have pre-recorded the stuff in your studio
+before, and now can at least fiddle around with the non-hw-synth-dependent
+parts of your song, while still having your <SPAN CLASS="textit">full</SPAN> song with you.
+
+<P>
+
+<H4><A NAME="SECTION00422040000000000000">
+Applying effects on MIDI tracks</A>
+</H4>
+If you have many physical audio inputs, you might already be able to
+apply effect chains on MIDI tracks, by wiring the synthes' audio
+outputs to your soundcard's inputs, and applying the effects on
+dedicated input tracks you have to create. This requires you to have
+expensive hardware, and is pretty complicated, because you need one
+additional track per MIDI synth.
+
+<P>
+This feature allows you to apply effects on single MIDI tracks, and not
+only on full MIDI synthes, and doesn't require you to be have that
+many physical audio inputs (you need to manually replug your synthes,
+however).
+
+<P>
+
+<H2><A NAME="SECTION00423000000000000000">
+Possible scenarios</A>
+</H2>
+
+<H4><A NAME="SECTION00423010000000000000">
+Setting it up</A>
+</H4>
+Create a wave track, MusE will allow you to set or unset prerendering
+for every plugin in the plugin rack (recording the actual track is
+useless because it would be a plain copy).
+Create a MIDI track, MusE will ask you on which physical audio input
+your synth is connected. Setting up multiple synthes on one physical
+audio in is allowed, see below.
+
+<P>
+
+<H4><A NAME="SECTION00423020000000000000">
+Pre-rendering stuff</A>
+</H4>
+When the user presses the "pre-render" button, all tracks which have
+been changed since their last pre-rendering will be re-rendered.
+If you have multiple hardware synthes set up as they were connected
+to one physical audio input port, MusE will prompt you to first plug
+the proper cable in.
+
+<P>
+
+<H4><A NAME="SECTION00423030000000000000">
+Making changes</A>
+</H4>
+Change a note in a MIDI part, move or delete a part or change automation
+parameters. MusE will temporarily disable the pre-rendered information
+and instead generate the sound via sending out MIDI events, piping stuff
+through effect chains or similar. If you play back the whole song, or
+if you manually trigger a re-rendering of a track via the context menu,
+MusE will play back the stuff, record it again and re-enable the
+pre-rendered information.
+
+<P>
+
+<H2><A NAME="SECTION00424000000000000000">
+Extensions</A>
+</H2>
+
+<H4><A NAME="SECTION00424010000000000000">
+Automatic discovery of physical audio connections</A>
+</H4>
+The user plugs all (or only some) synthes' audio outs into the available
+audio inputs, then runs automatic discovery. This will send MIDI events
+to each synthesizer, and look on which audio in there's activity. Then
+it will assume that the synthesizer is connected to that particular
+audio in. Audio ins which show activity before any MIDI events were
+sent are not considered, as they're probably connected to microphones
+or other noise-generating non-synthes.
+
+<P>
+
+<H4><A NAME="SECTION00424020000000000000">
+Audio export</A>
+</H4>
+As described in the Use cases, MusE can allow you to export your song
+in some multitrack audio format.
+
+<P>
+
+<H4><A NAME="SECTION00424030000000000000">
+Cheap/Faked changes</A>
+</H4>
+For expensive or unavailable synthes, changing the Volume midi controller,
+the Pan controller or similar "easy" controllers will not trigger a
+complete re-rendering, but instead "fake" the change, by changing
+the volume data directly on the recorded wave. This might require some
+learning and might even get pretty complicated.
+
+<P>
+
+<H4><A NAME="SECTION00424040000000000000">
+Intelligent re-recording</A>
+</H4>
+For tiny changes, MusE shall only re-render the relevant part. If you
+change some MIDI notes, then begin re-recording shortly before the
+changes, and end re-recording as soon as the recorded stuff doesn't
+differ to much from the stuff coming from the synth. Then properly
+blend the old recording with the updated part.
+
+<P>
+
+<H1><A NAME="SECTION00430000000000000000">
+Slotted editors</A>
+</H1>
+Currently, MusE has the pianoroll editor, drum editor, score editor,
+then the controller editor which is inside the pianoroll/drum editor.
+All these editors have a very similar concept: the "time axis" is
+vertical and (almost) linear, they handle parts, and events are
+manipulated similarly.
+
+<P>
+A unified editor shall be created which allows you to combine different
+kinds of editors in one window, properly aligned against each other.
+These "different kinds of editors" shall be handled as "slots"; one
+unified editor window consists of:
+
+<UL>
+<LI>A menu bar, containing stuff suitable for the complete window,
+ which might include window name, MDI-ness etc.
+</LI>
+<LI>A toolbar which contains controls suitable for every single slot.
+</LI>
+<LI>A container with one or more slots; the slots can be scrolled in
+ y-direction if there are multipe slots.
+</LI>
+<LI>A time-scrollbar with zoom
+</LI>
+</UL>
+
+<P>
+Each slot contains the following:
+
+<UL>
+<LI>A menu button, button box or control panel for setting up this
+ particular slot. This could contain "note head colors", "show
+ a transposing instrument" etc for score edit slots, "event
+ rectangle color", "grid size" and "snap to grid" for pianoroll/
+ drum editors.
+</LI>
+<LI>The actual canvas
+</LI>
+<LI>A y-direction scroll bar, possibly with zoom control (for
+ pianoroll editor)
+</LI>
+</UL>
+
+<P>
+The main window does not show its scroll bar if there is only one slot,
+because the slot's scrollbar is sufficient then.
+
+<P>
+Slots can be added, destroyed, moved around, maybe even merged (if the
+slot types allow it); basically, you can compare them with the staves
+in the score editor.
+
+<P>
+The slots shall align against each other, that is, if a score editor
+slot displays a key change with lots of accidentials, then all other
+slots shall either also display the key change (if they're score slots)
+or display a gap. Events which happen at the same time shall be at the
+same x-coordinate, regardless which slot they are.
+
+<P>
+
+<H1><A NAME="SECTION00440000000000000000">
+Controller master values</A>
+</H1>
+All controllers (MIDI-controllers and also automation controllers)
+shall have one set of "master values" which allow you to set a gain and
+a bias. Instead of the actual set value, <!-- MATH
+ $\textrm{value} * \textrm{bias}
++ textrm{bias}$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="180" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img1.png"
+ ALT="$\textrm{value} * \textrm{bias}
++ textrm{bias}$"></SPAN> shall be sent to the MIDI device / the plugin. For
+controllers like "pan", the unbiased values shall be transformed, that
+is, a pan of 64, with <!-- MATH
+ $\textrm{bias}=2$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="61" HEIGHT="15" ALIGN="BOTTOM" BORDER="0"
+ SRC="img2.png"
+ ALT="$\textrm{bias}=2$"></SPAN> and <!-- MATH
+ $\textrm{gain}=0.5$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="75" HEIGHT="30" ALIGN="MIDDLE" BORDER="0"
+ SRC="img3.png"
+ ALT="$\textrm{gain}=0.5$"></SPAN>, shall
+be transformed to 66 (because 64 is actually 0, while 0 is actually -64).
+These values shall be set in the arranger and whereever the actual
+controller/automation values can be edited.
+
+<P>
+
+<H1><A NAME="SECTION00450000000000000000">
+Enabled-indicator while recording</A>
+</H1>
+The MusE-plugin-GUIs shall display a small LED displaying whether a
+controller is currently enabled or disabled. By clicking this LED, the
+enabled state shall be switched.
+
+<P>
+Furthermore, there shall be a dedicated window which only lets you switch
+enabled/disabled states. This will be useful when using external GUIs
+or the MIDI-controller-to-automation feature, to re-enable a controller
+when in <TT>fterfirstA`A=95 _ `A=58 : A
+ <`<=95 _ `<=58 : <
+ u@nderscorehyph<271>>UTO_TOUCH</TT> mode.
+
+<P>
+
+<H1><A NAME="SECTION00460000000000000000">
+Linear automation editing</A>
+</H1>
+While holding some modifier key (like shift), operating the MusE-native-
+GUI sliders shall only generate control points when clicking and when
+releasing the slider. This will result in linear graphs for continous
+controllers, and in large steps for discrete controllers (which is in
+particular useful for stuff like "which low/high-pass filter type to use").
+
+<P>
+Maybe make this behaviour default for discrete controllers?
+
+<P>
+
+<H1><A NAME="SECTION00470000000000000000"></A> <A NAME="symbolic_ports"></A>
+<BR>
+Symbolic names for MIDI ports
+</H1>
+MIDI ports shall have a user-defined symbolic name (like "Korg" or "Yamaha DX 7").
+The mapping between these symbolic names and the hardware port (like
+"ALSA midi out port") is stored in the global configuration.
+
+<P>
+Song files only specify the symbolic names as the ports associated with
+their tracks. No information about physical devices/port names, but only
+symbolic names are stored in the song file.
+
+<P>
+This resolves the issues mentioned in <A HREF="#portconfig_sucks">1.2</A>, and also
+allows the user to share his pieces with other people: They would only
+have to set up that symbolic-to-hardware mapping once (collisions are
+unlikely, because an equal symbolic name should usually mean the same
+device) and are happy, instead of having to re-map <SPAN CLASS="textit">every</SPAN> port
+for <SPAN CLASS="textit">every</SPAN> song.
+
+<P>
+<BR><HR>
+
+</BODY>
+</HTML>
diff --git a/muse2/doc/html/single/documentation/arrow_tool.png b/muse2/doc/html/single/documentation/arrow_tool.png
new file mode 100644
index 00000000..1ae872fb
--- /dev/null
+++ b/muse2/doc/html/single/documentation/arrow_tool.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/documentation.css b/muse2/doc/html/single/documentation/documentation.css
new file mode 100644
index 00000000..17bee66c
--- /dev/null
+++ b/muse2/doc/html/single/documentation/documentation.css
@@ -0,0 +1,35 @@
+/* Century Schoolbook font is very similar to Computer Modern Math: cmmi */
+.MATH { font-family: "Century Schoolbook", serif; }
+.MATH I { font-family: "Century Schoolbook", serif; font-style: italic }
+.BOLDMATH { font-family: "Century Schoolbook", serif; font-weight: bold }
+
+/* implement both fixed-size and relative sizes */
+SMALL.XTINY { font-size : xx-small }
+SMALL.TINY { font-size : x-small }
+SMALL.SCRIPTSIZE { font-size : smaller }
+SMALL.FOOTNOTESIZE { font-size : small }
+SMALL.SMALL { }
+BIG.LARGE { }
+BIG.XLARGE { font-size : large }
+BIG.XXLARGE { font-size : x-large }
+BIG.HUGE { font-size : larger }
+BIG.XHUGE { font-size : xx-large }
+
+/* heading styles */
+H1 { }
+H2 { }
+H3 { }
+H4 { }
+H5 { }
+
+/* mathematics styles */
+DIV.displaymath { } /* math displays */
+TD.eqno { } /* equation-number cells */
+
+
+/* document-specific styles come next */
+DIV.navigation { }
+DIV.center { }
+SPAN.textit { font-style: italic }
+SPAN.arabic { }
+SPAN.textbf { font-weight: bold }
diff --git a/muse2/doc/html/single/documentation/documentation.html b/muse2/doc/html/single/documentation/documentation.html
new file mode 100644
index 00000000..b24ff0be
--- /dev/null
+++ b/muse2/doc/html/single/documentation/documentation.html
@@ -0,0 +1,1702 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<!--Converted with LaTeX2HTML 2008 (1.71)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<HTML>
+<HEAD>
+<TITLE>MusE Documentation</TITLE>
+<META NAME="description" CONTENT="MusE Documentation">
+<META NAME="keywords" CONTENT="documentation">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="documentation.css">
+
+</HEAD>
+
+<BODY >
+
+<DIV ALIGN="CENTER">
+
+<P><A NAME="fig:MusE"></A></P>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="1030" HEIGHT="722" ALIGN="BOTTOM" BORDER="0"
+ SRC="./muse2.png"
+ ALT="Image muse2">
+
+</DIV>
+<BR>
+
+<H2><A NAME="SECTION00100000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
+
+<UL CLASS="TofC">
+<LI><A NAME="tex2html67"
+ HREF="documentation.html#SECTION00200000000000000000">What is this?</A>
+<LI><A NAME="tex2html68"
+ HREF="documentation.html#SECTION00300000000000000000">User's manual</A>
+<UL>
+<LI><A NAME="tex2html69"
+ HREF="documentation.html#SECTION00310000000000000000">Introduction</A>
+<UL>
+<LI><A NAME="tex2html70"
+ HREF="documentation.html#SECTION00311000000000000000">A brief history of computer audio and MusE</A>
+<LI><A NAME="tex2html71"
+ HREF="documentation.html#SECTION00312000000000000000">Definitions</A>
+<LI><A NAME="tex2html72"
+ HREF="documentation.html#SECTION00313000000000000000">Getting up and running for impatient people</A>
+<LI><A NAME="tex2html73"
+ HREF="documentation.html#SECTION00314000000000000000">Getting up and running</A>
+<LI><A NAME="tex2html74"
+ HREF="documentation.html#SECTION00315000000000000000">Beginners tutorial</A>
+</UL>
+<LI><A NAME="tex2html75"
+ HREF="documentation.html#SECTION00320000000000000000">Basic overview</A>
+<UL>
+<LI><A NAME="tex2html76"
+ HREF="documentation.html#SECTION00321000000000000000">Main/Arranger</A>
+<LI><A NAME="tex2html77"
+ HREF="documentation.html#SECTION00322000000000000000">Mixer</A>
+</UL>
+<LI><A NAME="tex2html78"
+ HREF="documentation.html#SECTION00330000000000000000">Tracks and parts</A>
+<UL>
+<LI><A NAME="tex2html79"
+ HREF="documentation.html#SECTION00331000000000000000">Tracks</A>
+<LI><A NAME="tex2html80"
+ HREF="documentation.html#SECTION00332000000000000000">Parts</A>
+</UL>
+<LI><A NAME="tex2html81"
+ HREF="documentation.html#SECTION00340000000000000000">Routes</A>
+<UL>
+<LI><A NAME="tex2html82"
+ HREF="documentation.html#SECTION00341000000000000000">Anti circular routing</A>
+<LI><A NAME="tex2html83"
+ HREF="documentation.html#SECTION00342000000000000000">Soloing chain routes</A>
+</UL>
+<LI><A NAME="tex2html84"
+ HREF="documentation.html#SECTION00350000000000000000">Track soloing</A>
+<UL>
+<LI><A NAME="tex2html85"
+ HREF="documentation.html#SECTION00351000000000000000">Phantom soloing</A>
+<LI><A NAME="tex2html86"
+ HREF="documentation.html#SECTION00352000000000000000">Soloing chains</A>
+</UL>
+<LI><A NAME="tex2html87"
+ HREF="documentation.html#SECTION00360000000000000000">Plugins</A>
+<UL>
+<LI><A NAME="tex2html88"
+ HREF="documentation.html#SECTION00361000000000000000">The audio effects rack</A>
+</UL>
+<LI><A NAME="tex2html89"
+ HREF="documentation.html#SECTION00370000000000000000">Automation</A>
+<UL>
+<LI><A NAME="tex2html90"
+ HREF="documentation.html#SECTION00371000000000000000">Audio automation</A>
+<LI><A NAME="tex2html91"
+ HREF="documentation.html#SECTION00372000000000000000">Midi automation</A>
+</UL>
+<LI><A NAME="tex2html92"
+ HREF="documentation.html#SECTION00380000000000000000">Configuration</A>
+<UL>
+<LI><A NAME="tex2html93"
+ HREF="documentation.html#SECTION00381000000000000000">MIDI ports</A>
+<LI><A NAME="tex2html94"
+ HREF="documentation.html#SECTION00382000000000000000">Global settings</A>
+</UL>
+</UL>
+<BR>
+<LI><A NAME="tex2html95"
+ HREF="documentation.html#SECTION00400000000000000000">Appendix</A>
+<UL>
+<LI><A NAME="tex2html96"
+ HREF="documentation.html#SECTION00410000000000000000">Understanding the effects rack</A>
+</UL></UL>
+<!--End of Table of Contents-->
+<H1><A NAME="SECTION00200000000000000000">
+What is this?</A>
+</H1>
+You are, if you have printed this document, holding in your hand the
+written documentation for the audio and midi sequencer MusE version 2.
+<BR><TT><A NAME="tex2html1"
+ HREF="http://www.muse-sequencer.org">http://www.muse-sequencer.org</A></TT> is MusE's home on the internet where
+everything MusE releated should be possible to find, software, this
+documentation, forums, mailing lists, bug reporting, FAQs. If you have
+this document but not the software head on over there to find what it's
+all about.
+
+<H1><A NAME="SECTION00300000000000000000">
+User's manual</A>
+</H1>
+
+<P>
+
+<H1><A NAME="SECTION00310000000000000000">
+Introduction</A>
+</H1>
+
+<H2><A NAME="SECTION00311000000000000000">
+A brief history of computer audio and MusE</A>
+</H2>
+To quickly summarize over a decades open source development: in 1999 Werner
+ Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first
+few releases (actually not few, Werner relentlessly churned out new releases)
+MusE was only a midi sequencer. The target was to create a fully fledged
+midi sequencer for the Linux operating system. Over the years audio was
+added among with other things implemented and sometimes abandoned.
+Today MusE is a stable and feature rich music creation environment which
+strives to encompass most of the music recording process, creation, editing,
+mastering.
+
+<P>
+
+<H2><A NAME="SECTION00312000000000000000">
+Definitions</A>
+</H2>
+<SPAN CLASS="textbf">CTRL</SPAN> refers to the control key on the keyboard, e.g. <SPAN CLASS="textbf">CTRL+C</SPAN>
+means to press and hold the control key while pressing the c key. Make sure
+you know where you have it so you won't accidentally lose control
+(bad jokes are the best jokes, so say we all!).
+<BR><SPAN CLASS="textbf">SHIFT</SPAN> refers to the shift key on the keyboard, see above for usage
+<BR><SPAN CLASS="textbf">ALT</SPAN> refers to the alt key on the keyboard, see above for usage
+<BR><TT><SPAN CLASS="textbf">$&gt;</SPAN></TT> is used as a generic definition for a terminal prompt. When the
+manual lists a command that shall be typed, the prompt is not part of the
+command.
+<BR>
+Keys are always referred to in bold uppercase, e.g. <SPAN CLASS="textbf">A</SPAN>. For instance
+<SPAN CLASS="textbf">SHIFT+A</SPAN> for the key a pressed together with the shift key.
+<BR>
+Sometimes terminal examples are written tabbed in with a fixed font to
+visualize more closely what something looks like on the screen.
+E.g.
+<BR> <TT><SPAN CLASS="textbf">$&gt; muse2</SPAN></TT>
+<BR>
+<P>
+
+<H2><A NAME="SECTION00313000000000000000">
+Getting up and running for impatient people</A>
+</H2>
+Install MusE from the repository of your chosen distribution.
+To get decent performance start http://jackaudio.org/Jack with
+the following command in a terminal:
+<BR> <TT><SPAN CLASS="textbf">$&gt; jackd -d alsa -d hw:0 -p 256</SPAN></TT>
+<BR>
+Or, if you prefer, use the launcher utility
+http://qjackctl.sourceforge.net/QJackCtl to get some
+help starting Jack.
+After this, start MusE from the menu or fire up another terminal and
+type
+
+<P>
+<TT><SPAN CLASS="textbf">muse2</SPAN></TT>.
+<BR>
+If this didn't work out read on for the slightly more complete route for
+getting things started.
+
+<P>
+
+<H2><A NAME="SECTION00314000000000000000">
+Getting up and running</A>
+</H2>
+
+<H3><A NAME="SECTION00314100000000000000">
+Installation from binaries</A>
+</H3>
+There are several ways to install MusE depending on your situation. The
+most convenient way is to install a prepackaged version from your chosen
+distribution. The drawback of this is that it may not be the most recent
+version, though often there is a more recent package from a private packager.
+
+<H3><A NAME="SECTION00314200000000000000">
+Installation from source</A>
+</H3>
+Building MusE from source is not hard, there are a number of prerequistes
+that must be met but the actual building should be painless (ha, famous
+last words).
+<BR>
+Please follow the README in the source package and/or read the instructions
+on the homepage: <TT><A NAME="tex2html2"
+ HREF="http://muse-sequencer.org/index.php/Installation">http://muse-sequencer.org/index.php/Installation</A></TT>
+<P>
+
+<H3><A NAME="SECTION00314300000000000000">
+Hardware</A>
+</H3>
+MusE on the Linux platform supports midi through ALSA and Jack-midi and audio
+through Jack. For information on what hardware is supported there are some
+convenient places to check:
+
+<UL>
+<LI>Alsa soundcard matrix at
+<TT><A NAME="tex2html3"
+ HREF="http://www.alsa-project.org/main/index.php/Matrix:Main">http://www.alsa-project.org/main/index.php/Matrix:Main</A></TT>
+</LI>
+<LI><TT><A NAME="tex2html4"
+ HREF="http://FFADO.org">http://FFADO.org</A></TT> for firewire devices.
+</LI>
+</UL>
+Also, as is often a very good approach for Linux and open source, the
+various forums available on the internet often contain good information.
+Chances are someone has already tried your configuration and/or had your
+specific problem and the solution is already written down.
+
+<H3><A NAME="SECTION00314400000000000000">
+Launching</A>
+</H3>
+After installation the binary muse2 is installed on the computer. If MusE
+was installed from a distribution repository the binary may have a
+different name depending on the distribution policies. Most distributions
+do however install a menu entry so MusE should be conveniently available
+from there.
+
+<H3><A NAME="SECTION00314500000000000000">
+Audio preconditions</A>
+</H3>
+In the standard case MusE expects to find and connect to the Jack audio
+server <TT><A NAME="tex2html5"
+ HREF="http://jackaudio.org">http://jackaudio.org</A></TT>. Make sure jack is installed (if MusE was
+installed with a distribution-package Jack will very likely already be
+installed) For Jack to run with best performance your system should be
+sufficiently tuned to allow it to run with realtime capabilities. The
+realtime configuration is configuration of the operating system and roughly
+consists of two parts.
+
+<OL>
+<LI>By default on most distros only the superuser lets applications setup
+realtime capabilities. Please see the APPENDIX for setting up realtime
+</LI>
+<LI>Maximizing performance. A standard linux installation may not able
+to reach the performance required by a power user. This requires exchanging
+the linux kernel for a so called lowlatency kernel, this is also covered by
+the realtime APPENDIX.
+</LI>
+</OL>
+
+<P>
+
+<H3><A NAME="SECTION00314600000000000000">
+Running MusE</A>
+</H3>
+Find MusE in the menu or open a terminal and enter muse2.
+
+<P>
+<TT><SPAN CLASS="textbf">$&gt; muse2</SPAN></TT>
+<BR>
+A splash screen should pop up followed
+by the main application window and you are off!
+<BR>
+If an error like the screenshot below pops up the Jack audio server is
+either not running or started as a different user than what you are trying
+to start MusE as.
+
+<DIV ALIGN="CENTER"><A NAME="fig:no_audio"></A><A NAME="101"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.1:</STRONG>
+Jack server missing</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="506" HEIGHT="178" ALIGN="BOTTOM" BORDER="0"
+ SRC="./no_audio.png"
+ ALT="Image no_audio"></TD></TR>
+</TABLE>
+</DIV>
+
+<H3><A NAME="SECTION00314700000000000000">
+Midi only</A>
+</H3>
+MusE can be started in Midi-only mode where MusE does not have any external
+dependencies apart from ALSA midi. In this case start MusE from a terminal:
+<TT><SPAN CLASS="textbf">$&gt; muse2 -a</SPAN></TT>
+
+<P>
+
+<H3><A NAME="SECTION00314800000000000000">
+ALSA midi with Jack</A>
+</H3>
+If Jack is running, by default MusE will not use ALSA devices, preferring
+Jack midi instead. To force ALSA devices to be used as well as Jack
+midi, start MusE with the -A option: <TT><SPAN CLASS="textbf">$&gt; muse2 -A</SPAN></TT>
+
+<P>
+
+<H2><A NAME="SECTION00315000000000000000">
+Beginners tutorial</A>
+</H2>
+To get a quick grip of what MusE can achieve please follow this beginners
+tutorial.
+
+<H3><A NAME="SECTION00315100000000000000">
+Midi Setup</A>
+</H3>
+First off, fire up MusE as was described in the previous chapter, making
+sure that the jack audio server is started with sufficient configuration
+to allow for audio output without breakup. Also make sure your system can
+make sound.
+
+<H3><A NAME="SECTION00315200000000000000">
+Soft synth test</A>
+</H3>
+With MusE up and running right click in the Track-pane (see
+Fig. <A HREF="#fig:Main_Window">2.8</A>) and select
+<SPAN CLASS="textbf">Add Synth &gt; MESS &gt; vam soft synth</SPAN>.
+A Soft Synth track called vam-0 should appear as well as a separate GUI
+for the synthesizer.
+
+<P>
+Now right click once more in the Track-pane and select <SPAN CLASS="textbf">Add Midi
+Track</SPAN>. Another track appears called Track 1, and its track list Port
+column should show it is bound to the synth that was just created vam-0.
+If it is not, click on the Track 1 Port column to open a drop-down list
+of available devices and choose vam-0.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.05
+<IMG
+ WIDTH="23" HEIGHT="23" ALIGN="BOTTOM" BORDER="0"
+ SRC="./arrow_tool.png"
+ ALT="Image arrow_tool">
+
+</DIV>
+Now select the drawing tool icon
+from the toolbar, alternatively press the shortcut key <SPAN CLASS="textbf">D</SPAN>.
+Move the mouse over to the arranger canvas as referenced in
+Fig. <A HREF="#fig:Main_Window">2.8</A>
+and point at the midi track, the mouse should have changed to a small pencil.
+Draw a Part along the midi track using the mouse. For this exercise it is
+not important where or how large the drawn Part is. When you are done double
+click on the drawn part. This will open up the Piano Roll editor. To the
+left of the Piano Roll there are piano keys in a vertical line, try clicking
+on the keys in this virtual keyboard each click should be rewarded with a
+synth sound (maybe of questionable quality, a sound nevertheless)
+
+<DIV ALIGN="CENTER"><A NAME="fig:vam_synth"></A><A NAME="123"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.2:</STRONG>
+vam synthesizer</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="750" HEIGHT="560" ALIGN="BOTTOM" BORDER="0"
+ SRC="./vam_synth.png"
+ ALT="Image vam_synth"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H3><A NAME="SECTION00315300000000000000">
+Missing sound</A>
+</H3>
+If you got sound from the previous exercise you can carry on to the next,
+or keep reading for further enlightenment in case you come upon trouble
+later on. If there is no sound we need to do some fault hunting. First
+off, click on Arranger window once more and select the vam-0 track in the
+track-pane.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Midi_editor"></A><A NAME="129"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.3:</STRONG>
+Midi editor view</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="914" HEIGHT="679" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_midi_editor_vam.png"
+ ALT="Image main_window_with_midi_editor_vam"></TD></TR>
+</TABLE>
+</DIV>
+Now bring back Piano Roll window and align the windows so you
+can see the piano keys as well as the Meter on the Mixer Strip (see the
+5 Function by function chapter for more information on these windows).
+The result should be something like the following:
+
+<P>
+When pressing one of the keys on virtual Keyboard the Meter on the Mixer
+Strip should light up in green to visualize that the Synth is making
+sound, if it is not try to trace back your steps and and see if you did
+anything differently than described.
+Now, if the Meter lights up but there is still no sound we need to
+check the routing between the tracks. Click on the Arranger window again
+and select the Out 1 track, this is the predefined output which MusE by
+default loads at startup, at the bottom of Mixer Strip there are two
+buttons looking like tele- jacks, these bring up the inputs and outputs
+of the track, click on the right one, the output and make sure that it is
+connected to some valid outputs on your system.
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="231" HEIGHT="318" ALIGN="BOTTOM" BORDER="0"
+ SRC="./output_routing.png"
+ ALT="Image output_routing">
+
+</DIV>
+Click on the outputs to select them, if you did changes here go back and
+try clicking on the Piano Roll keyboard again, hopefully it helped. If there
+still are problems make sure your system actually can make sound through
+Jack, this is however getting outside the scope of this manual.
+<BR>
+<BR><SPAN CLASS="textit">This might be the time to bring up the concept of community support.
+Open source software could never be what it is without the support given by
+individuals on forums and mailinglists, if the information given in this
+document is not enough, try googling your problem and/or get in touch with
+one of the online forums for MusE or Linux audio in general. See some pointers
+in the Support chapter.</SPAN>
+
+<P>
+
+<H3><A NAME="SECTION00315400000000000000">
+Recording Midi</A>
+</H3> TBD
+
+<H3><A NAME="SECTION00315500000000000000">
+Recording Audio</A>
+</H3>
+At this point we'll make a a slight detour into full on audio recording. Getting
+audio out of MusE has already been covered in the previous chapters so we will
+concentrate on the additional steps needed to record onto an audio track.
+<BR>
+<BR>
+When MusE is first fired up, the
+output track has already been created (more about this in the chapter about
+templates), to proceed with audio recording we need to add two additional tracks, a
+wave track and an input track.
+<BR>
+When MusE is first started right click in an empty space on the track view
+
+<DIV ALIGN="CENTER"><A NAME="fig:Add_track"></A><A NAME="142"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.4:</STRONG>
+Add track</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="782" HEIGHT="498" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_add_track.png"
+ ALT="Image main_window_add_track"></TD></TR>
+</TABLE>
+</DIV>
+and select <SPAN CLASS="textbf">Add Audio Input</SPAN>. Right click again and also select
+<SPAN CLASS="textbf">Add Wave Track</SPAN>. Two additional tracks are now visible in the Arranger,
+"Input 1" and "Track 1", bring up the mixer with <SPAN CLASS="textbf">F10</SPAN> and you should see
+the following configuration.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Mixer_with_one_input"></A><A NAME="150"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.5:</STRONG>
+Mixer with one input</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="216" HEIGHT="418" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer_with_one_input.png"
+ ALT="Image mixer_with_one_input"></TD></TR>
+</TABLE>
+</DIV>
+
+<BR>
+Note the buttons on each mixer strip. hover over them to see their
+functionality. For more information on all the buttons see coming chapters
+about the mixer. For now lets just do what we must.
+<BR>
+1. click on the stereo symbol over the slider to change the input to a mono track.
+<BR>
+2. do the same for the wave track (optional)
+<BR>
+3. click on the Mute (gray speaker) icon on the input track to unmute it.
+<BR>
+4. click on the input routing button (see the tooltip, it looks like a tele plug)
+on the input track and select an appropriate connection from your system.
+<BR>
+5. click on the output routing button on the input track and select
+<SPAN CLASS="textbf">Track 1</SPAN>
+<BR>
+<BR>
+Already after the meter on the input track should be able to display that there
+is incoming sound from your sound source. If there actually is sound coming
+from your sound source, that is.
+<BR>
+We are now nearly ready to start recording. First we need to select a location
+to store the files. MusE does not use a centralized storage of soundfiles but
+uses the path of the song-file (extension .med) as guidance as to where the
+audio files should be placed. Now as it happens MusE will prohibit us from
+starting a recording until the songfile has been stored. So lets take advantage
+of this behaviour and just go ahead and try to record. Let's get started.
+<BR>
+In the mixer click on the red <SPAN CLASS="textbf">record</SPAN> dot on the Audio Track to arm it
+for recording (or enable if you will). Now when there is audio coming into the
+input it will also show up on the Audio Track. Also note that all the input and
+output routing buttons on the tracks now have the same gray color, this means
+that all of the tracks have a proper connection.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Mixer_buttons"></A><A NAME="157"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.6:</STRONG>
+Mixer buttons</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="217" HEIGHT="166" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer_with_one_input_buttons.png"
+ ALT="Image mixer_with_one_input_buttons"></TD></TR>
+</TABLE>
+</DIV>
+
+<BR>
+All fine and dandy. Now bring up the arranger window and find the round, red on
+white <SPAN CLASS="textbf">record</SPAN> button and click on it. This is your queue to MusE to
+prepare for recording. However since we have not saved our song we are presented
+with a dialog to do just that.
+<BR>
+<DIV ALIGN="CENTER"><A NAME="fig:Save_song"></A><A NAME="163"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.7:</STRONG>
+Save song</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="575" HEIGHT="405" ALIGN="BOTTOM" BORDER="0"
+ SRC="./project_my_first_song.png"
+ ALT="Image project_my_first_song"></TD></TR>
+</TABLE>
+</DIV>
+Note the check box for creating a project folder, when working with audio this
+is very much recommended or you may soon loose track of what audio files belong
+to which song.
+<BR>
+Finally we are ready to start recording! The process is completed by clicking
+on the <SPAN CLASS="textbf">Play</SPAN> button in the Arranger. If all went well MusE then starts
+to record a wave file from the Input Track placed in your song directory.
+<BR>
+When you wish to stop recording press <SPAN CLASS="textbf">Stop</SPAN> in the Arranger, now the
+resulting waveform should be visible in the Arranger. After rewinding the Play
+position and pressing <SPAN CLASS="textbf">Play</SPAN> again the resulting sound should be audible
+through the connected output.
+
+<P>
+
+<H1><A NAME="SECTION00320000000000000000">
+Basic overview</A>
+</H1>
+In this section we will make a step by step walk-through of all the
+different editors, their purpose and what functions they support.
+
+<P>
+
+<H2><A NAME="SECTION00321000000000000000">
+Main/Arranger</A>
+</H2>
+
+<P>
+<A NAME="Main_Arranger"></A>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Main_Window"></A><A NAME="174"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.8:</STRONG>
+MusE main window</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="846" HEIGHT="571" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_annotated.png"
+ ALT="Image main_window_annotated"></TD></TR>
+</TABLE>
+</DIV>
+Above is the main window of MusE, the Arranger, this is what greets you
+when launching MusE. The Arranger consists of two main parts, the Track-pane
+and the Arranger canvas. The Track-pane lists all currently visible tracks
+and the Arranger canvas contains all Parts of the composition. The
+screenshot above shows an empty project. Below is MusE with a song in
+progress, turns out it wasn't a very good song, but for our purposes it
+is fine. In the below screenshot there are a lot of tracks visible in the
+Track-pane, each have an icon which indicate it's type, wave-track, input,
+output etcetera, more about that later. In the Arranger canvas a number of
+parts are visible, the ones in yellow are in this composition wave files,
+the multicolored line are different Parts of a drum track.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Main_Window_with_arrangement"></A><A NAME="179"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.9:</STRONG>
+MusE main window with arrangement</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="1051" HEIGHT="635" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_arrangement.png"
+ ALT="Image main_window_with_arrangement"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00322000000000000000"></A> <A NAME="mixer"></A>
+<BR>
+Mixer
+</H2>
+Choosing <SPAN CLASS="textbf">View &gt; Mixer A</SPAN> or <SPAN CLASS="textbf">B</SPAN> from the menu in the main
+window will bring up the mixer as viewed below. The mixer will open with
+all options enabled, showing channel strips for all tracks in the current
+setup, depending on how far you have gotten this view may become very large,
+at which point it may be a good idea to limit what is viewed in the Mixer.
+From the view menu all the different kinds of tracks can be toggled on/off
+from the mixer. Some may find it a good idea to use the two mixers A and B
+setup with different setup and store this in your song template(s), more
+about this in the Song Template section. It can be argued that everything
+in MusE is a track analogous to the Unix idiom that everything is a file.
+The types of tracks visible in the mixer (and track-pane) are:
+
+<DIV ALIGN="CENTER">
+r0.5
+<IMG
+ WIDTH="672" HEIGHT="424" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer.png"
+ ALT="Image mixer">
+
+</DIV>
+
+<UL>
+<LI>Audio output
+</LI>
+<LI>Audio input
+</LI>
+<LI>Group track
+</LI>
+<LI>Aux track
+</LI>
+<LI>Wave track
+</LI>
+<LI>Synth track
+</LI>
+<LI>Midi track
+</LI>
+</UL>
+
+<P>
+There is also a Midi Track variation called Drum Track, they are
+however not distinguishable from Midi Tracks in the Mixer. Also the
+strips for midi tracks are different in the Mixer than in the
+Track-pane view.
+
+<P>
+
+<H1><A NAME="SECTION00330000000000000000">
+Tracks and parts</A>
+</H1>
+MusE arranges your music in <SPAN CLASS="textit">tracks</SPAN> and <SPAN CLASS="textit">parts</SPAN>. The following
+section shall provide you an overview of how things are done with MusE.
+If you are or were a Cubase or Cakewalk user, you will feel familiar with
+this.
+
+<P>
+
+<H2><A NAME="SECTION00331000000000000000">
+Tracks</A>
+</H2>
+There are two general classes of tracks: MIDI tracks and audio
+tracks. MIDI tracks (and drum tracks which are internally MIDI tracks)
+can hold note data. The Wave track is a type of audio track which holds
+wave data. There are also several other kinds of audio tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331010000000000000">
+MIDI tracks</A>
+</H4>
+MIDI and drum tracks hold MIDI event data. They don't differ much,
+except that drum tracks offer a special editor which is more suitable
+for drum editing.
+
+<P>
+
+<H4><A NAME="SECTION00331020000000000000">
+Wave tracks</A>
+</H4>
+They hold audio data which can be just played back or be piped through
+effect plugin chains. They offer automation for these plugins.
+
+<P>
+
+<H4><A NAME="SECTION00331030000000000000">
+Audio input tracks</A>
+</H4>
+These provide the path for your audio data from outside into your
+project. Set up the physical audio inputs you want to connect your
+audio input track with, and then route the input tracks to various
+other tracks such as wave tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331040000000000000">
+Audio output tracks</A>
+</H4>
+These provide the path for your project's audio data to outside. Set
+up the physical audio outputs you want to connect your audio out track
+with, and then route various other tracks, such as wave tracks, to
+the output tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331050000000000000">
+Audio group tracks</A>
+</H4>
+Group tracks are like busses, where you can route other tracks to
+them, then route the groups to other tracks. Since group tracks have
+all the features of other audio tracks, like volume and pan, they
+provide a convenient common routing point where you have control of
+the sound before it is passed to other tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331060000000000000"></A> <A NAME="aux_tracks"></A>
+<BR>
+Audio aux tracks
+</H4>
+These provide a more convenient way to mix several audio tracks
+together. With each audio aux track added, other audio tracks will
+gain a common send knob for adjusting the level sent to the aux
+track. This can be more convenient than using several group tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331070000000000000">
+Synthesizer tracks</A>
+</H4>
+This type of track is a software synthesizer which MIDI and drum tracks
+can be assigned to.
+
+<P>
+
+<H4><A NAME="SECTION00331080000000000000">
+Creation</A>
+</H4>
+You can create a track by either right-clicking in the arranger's track list and then adding the desired track, or via the edit menu.
+
+<P>
+
+<H4><A NAME="SECTION00331090000000000000">
+Attributes</A>
+</H4>
+Tracks have several attributes:
+<DL>
+<DT><STRONG>Mute:</STRONG></DT>
+<DD>If you click on the <SPAN CLASS="textit">Mute</SPAN> field (denoted with
+a "M" column header), the track gets muted and stops producing sound.
+</DD>
+<DT><STRONG>Solo:</STRONG></DT>
+<DD><A NAME="track_attr_solo"></A> The solo button ("S" column
+header) singles out a track for listening. It mutes
+some other tracks but may phantom solo others.
+For more info see the section on soloing: <A HREF="#track_soloing">2.5</A> and
+phantom soloing: <A HREF="#phantom_soloing">2.5.1</A>
+</DD>
+<DT><STRONG>Record:</STRONG></DT>
+<DD>The R column "arms" your track for recording.
+When you rec-arm your song and have no tracks rec-armed, you won't be
+able to record anything. See also the config option "move rec-arm with selection".
+</DD>
+<DT><STRONG>Track name:</STRONG></DT>
+<DD>Double-click to edit the track name.
+</DD>
+<DT><STRONG>Port:</STRONG></DT>
+<DD>For MIDI tracks, this lets you select the MIDI
+port to which the events should be routed. This can be your physical
+synthesizer or a software synthesizer. For soft synths, this is the
+port the synth is associated to. For other track types, this is disabled.
+</DD>
+<DT><STRONG>Channel:</STRONG></DT>
+<DD>For MIDI tracks, this is the MIDI channel the
+output is sent to. For any kind of audio tracks, this is the number of
+channels (mono, stereo).
+ </DD>
+<DT><STRONG>Automation:</STRONG></DT>
+<DD><A NAME="track_attr_automation"></A> For audio tracks,
+this lets you set up the automation display in the arranger.
+(See automation <A HREF="#audio_automation">2.7.1</A>). Clicking this will provide you
+with a popup menu with lots of submenus. Clicking on a submenu will
+select or unselect it showing or hiding the automation parameter as a
+graph overlaid on top of the track.
+<BR>
+The submenus let you select the color you want to associate with the
+automation parameter. There you can also assign midi controllers to
+the parameters, a dialog is shown where you can manually choose the
+midi controller, with a <SPAN CLASS="textit">learn</SPAN> button to 'listen for' and
+automatically recognize any midi controller operated by you.
+
+<P>
+</DD>
+<DT><STRONG>Clef:</STRONG></DT>
+<DD>For MIDI tracks, you can specify a clef here. This
+only affects the score editor.
+
+<P>
+</DD>
+</DL>
+
+<P>
+
+<H3><A NAME="SECTION00331100000000000000">
+The trackinfo side bar</A>
+</H3>
+In the arranger and the part editors, you'll have a trackinfo sidebar
+on the left side. You can set up track-type specific things there.
+
+<P>
+
+<H4><A NAME="SECTION00331110000000000000"></A> <A NAME="midi_trackinfo_sidebar"></A>
+<BR>
+MIDI trackinfo sidebar
+</H4>
+The MIDI trackinfo sidebar lets you change program, volume, pan and
+more. This sidebar can also be viewed at the left of the pianoroll
+editor.
+
+<H5><A NAME="SECTION00331111000000000000">
+Old style drum tracks:</A>
+</H5>
+These are MIDI tracks as well, but with a few differences. They allow
+you to map certain drum sounds with different input notes, and you
+can change the output settings of a certain "drum instrument" without
+having to alter each single event.
+
+<P>
+However, they have certain limitations: They only can handle 128 sounds
+(even if you have more synthes), they aren't really compatible with
+MIDI tracks (you can interchange parts between them, but if you touched
+the drum list, you'll get unexpected results), you can't set a program
+for the used channel and more.
+
+<P>
+
+<H3><A NAME="SECTION00331200000000000000">
+New style drum tracks</A>
+</H3>
+Because of these limitations, we introduced the new-style drum tracks.
+They're not fully compatible with the old drum tracks, so the old are
+still retained. Under "Global Settings", "GUI settings", you can set
+up whether you prefer the old or new.
+
+<P>
+They are handled exactly like plain MIDI tracks (staying compatible with
+them), and offer all of the functionality, though in a different way.
+They allow you to re-order the drum map efficiently, you can open parts
+from multiple drum tracks in <SPAN CLASS="textit">one</SPAN> drum editor (MusE will separate
+the sounds from different tracks according to your settings, see the
+"Window Config" menu), and you can set programs as with normal MIDI tracks.
+
+<P>
+
+<H5><A NAME="SECTION00331201000000000000">
+MIDI trackinfo controls:</A>
+</H5>
+<DL>
+<DT><STRONG>Output port:</STRONG></DT>
+<DD>This drop-down list selects the midi port
+to send midi output from this track.
+</DD>
+<DT><STRONG>Output channel:</STRONG></DT>
+<DD>This box selects the midi channel to be
+used on the output port.
+</DD>
+<DT><STRONG>Input and output routing:</STRONG></DT>
+<DD>Selects midi ports and
+channels to receive midi from, and soloing paths. (See Routes
+<A HREF="#routes">2.4</A>).
+</DD>
+<DT><STRONG>Midi through:</STRONG></DT>
+<DD>This button selects whether midi input is
+passed through to the selected output port.
+<BR>
+Depending on your midi devices and settings, there are cases when
+this should be off such as using the same port and channel for
+input and output (otherwise a double-note <SPAN CLASS="textit">echo</SPAN> will be heard),
+and cases when it must be on such as when using a synthesizer track
+as output device.
+</DD>
+<DT><STRONG>Input detect indicator:</STRONG></DT>
+<DD>Blinks when midi activity is
+detected on the selected midi channels on the selected midi input
+ports.
+</DD>
+<DT><STRONG>Transpose:</STRONG></DT>
+<DD>This transposes midi input notes up or down
+in pitch. This is very useful if your midi keyboard hasn't enough
+keys or the selected output device plays an octave too low or high,
+and you would like to shift the octave of the incoming notes to
+compensate.
+</DD>
+<DT><STRONG>Delay:</STRONG></DT>
+<DD>Adjusts the delay of the notes.
+</DD>
+<DT><STRONG>Length:</STRONG></DT>
+<DD>Adjusts the length of the notes.
+</DD>
+<DT><STRONG>Velocity:</STRONG></DT>
+<DD>Adjusts the velocity of incoming notes.
+Use it to compensate for a too-loud or too-soft keyboard.
+</DD>
+<DT><STRONG>Compression:</STRONG></DT>
+<DD>Adjusts the compression of incoming note
+velocities. Use it to make soft incoming notes louder, and loud
+notes not so loud.
+</DD>
+<DT><STRONG>Instrument:</STRONG></DT>
+<DD>Selects the midi instrument patch to be used
+by the selected output port. This is equivalent of dialing the patch
+in the bank and program boxes, except it displays a more friendly
+patch <SPAN CLASS="textit">name</SPAN> as defined by the selected output port's midi
+instrument. See instruments, or port configuration
+<A HREF="#midi_port_config">2.8.1</A>
+</DD>
+<DT><STRONG>H-Bank:</STRONG></DT>
+<DD>Selects the high bank number of the current patch.
+</DD>
+<DT><STRONG>L-Bank:</STRONG></DT>
+<DD>Selects the low bank number of the current patch.
+</DD>
+<DT><STRONG>Prog:</STRONG></DT>
+<DD>Selects the program number of the current patch.
+</DD>
+<DT><STRONG>Volume:</STRONG></DT>
+<DD>Adjusts the midi volume controller.
+</DD>
+<DT><STRONG>Pan:</STRONG></DT>
+<DD>Adjusts the midi pan controller.
+</DD>
+</DL>
+The buttons beside the Prog, Volume, and Pan boxes store the value,
+at the current transport position, for midi automation. (See
+automation <A HREF="#midi_automation">2.7.1</A>).
+
+<P>
+Note that the 'Prog' button stores H-Bank and L-Bank along with
+'Prog' value, so there are no H-Bank and L-Bank buttons.
+
+<P>
+The 'All' button simply stores all three Program (and banks), Volume,
+and Pan values at once.
+
+<P>
+<SPAN CLASS="textit">Tip:</SPAN> If the Song Type is GM, GS, or XG, you may need to store
+desired values at transport position zero, otherwise your adjustments
+may be overriden by the instrument when the transport is moved back
+to position zero. If this behaviour is undesired, you can set the
+Song Type to 'NO' meaning no song type.
+
+<P>
+
+<H4><A NAME="SECTION00331210000000000000">
+Audio trackinfo sidebar</A>
+</H4>
+Unlike the midi trackinfo sidebar, the audio trackinfo side bar
+is nothing more than an embedded audio mixer strip, the exact same
+strip as found in the mixers. (See mixer <A HREF="#mixer">2.2.2</A>).
+
+<H5><A NAME="SECTION00331211000000000000">
+Effects rack:</A>
+</H5>
+On the top of the audio trackinfo sidebar, there is an effects rack
+which allows you to apply various plugins on the audio. For more
+information on this, refer to <A HREF="#effects_rack">2.6.1</A>.
+
+<P>
+
+<H2><A NAME="SECTION00332000000000000000">
+Parts</A>
+</H2>
+Within MIDI, drum and wave tracks, you can create <SPAN CLASS="textit">parts</SPAN>. Parts
+are chunks of coherent notes or wave data which can be moved around,
+copied, cloned and deleted independent from other parts.
+
+<P>
+Parts are created by selecting the pencil tool and then drawing onto
+the right part area in the arranger. You can move them with the arrow
+tool, delete them using the <SPAN CLASS="textbf">DEL</SPAN> key, and a right-click opens
+a popup menu. This menu allows you even more stuff, such as setting
+the part's color, saving the part to disk etc.. You can use
+<SPAN CLASS="textbf">CTRL+C</SPAN> and <SPAN CLASS="textbf">CTRL+V</SPAN> for copying and pasting parts.
+<SPAN CLASS="textbf">CTRL+B</SPAN> pastes the part as a clone. Pressing <SPAN CLASS="textbf">SHIFT</SPAN>
+additionally provides you a dialog which allows you to paste the part
+multiple times and set more stuff.
+
+<P>
+You can also copy parts with the mouse by moving the part with the mouse
+while holding down the <SPAN CLASS="textbf">CTRL</SPAN> key.
+
+<P>
+
+<H1><A NAME="SECTION00340000000000000000"></A> <A NAME="routes"></A>
+<BR>
+Routes
+</H1>
+Routes are how tracks are connected together and to the outside world.
+(They are also how Jack midi ports connect to the outside world. See
+midi port configuration <A HREF="#midi_port_config">2.8.1</A>).
+Each track strip has two buttons whose icons look like plugs. One button
+is for input routing and the other is for output routing. Clicking on
+these buttons will pop up a menu of available input or output routes that
+you can connect to. Most audio tracks list other tracks to connect to,
+but audio input and output tracks are special: Audio input track input
+routing menus list available Jack audio input ports. Conversely audio
+output track output routing menus list available Jack audio output ports.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="231" HEIGHT="318" ALIGN="BOTTOM" BORDER="0"
+ SRC="./output_routing.png"
+ ALT="Image output_routing">
+
+</DIV>
+
+<P>
+Meanwhile MIDI and drum tracks allow you to route available MIDI ports
+and channels to the track using a handy popup matrix.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="522" HEIGHT="158" ALIGN="BOTTOM" BORDER="0"
+ SRC="./midi_routing_matrix.png"
+ ALT="Image midi_routing_matrix">
+
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00341000000000000000"></A> <A NAME="anti_circular_routing"></A>
+<BR>
+Anti circular routing
+</H2>
+Any routing menu item which would cause a circular routing condition
+is grayed out. Find out why the condition would exist by examining
+routing paths involved and correct the situation if required.
+
+<P>
+Also, you cannot use a track's aux sends if the track has an input
+route path from ANY Aux Track. (See aux tracks <A HREF="#aux_tracks">2.3.1</A>).
+Aux send knobs and labels are disabled in that case.
+
+<P>
+
+<H2><A NAME="SECTION00342000000000000000"></A> <A NAME="soloing_chain_routes"></A>
+<BR>
+Soloing chain routes
+</H2>
+Soloing chains (see solo chains <A HREF="#soloing_chains">2.5.2</A>) are really just
+routes like any other. The available solo chaining paths are displayed
+in the routing popup menus.
+
+<P>
+
+<H1><A NAME="SECTION00350000000000000000"></A> <A NAME="track_soloing"></A>
+<BR>
+Track soloing
+</H1>
+Soloing allows you to single out a track for listening while muting others,
+without you having to mute the other tracks. (See soloing track attribute
+<A HREF="#track_attr_solo">2.3.1</A>).
+
+<P>
+
+<H2><A NAME="SECTION00351000000000000000"></A> <A NAME="phantom_soloing"></A>
+<BR>
+Phantom soloing
+</H2>
+In order to solo a track and mute others so that it is heard, MusE
+employs 'phantom' soloing: When a track is soloed, MusE automatically
+solos all tracks routed to and from this track. (See routes
+<A HREF="#routes">2.4</A>). A phantom soloed track is indicated by a black square
+in the track pane solo column. (See track attributes
+<A HREF="#track_attr_solo">2.3.1</A>).
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Soloing"></A><A NAME="295"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.10:</STRONG>
+Soloing, with phantom soloing</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="529" HEIGHT="476" ALIGN="BOTTOM" BORDER="0"
+ SRC="./soloing_window.png"
+ ALT="Image soloing_window"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00352000000000000000"></A> <A NAME="soloing_chains"></A>
+<BR>
+Soloing chains
+</H2>
+When an audio output track sends audio to some external entity, such
+as an external running application, and audio from the external entity
+is fed back into a MusE audio input track, solo chains allow you to
+solo the input or output, and MusE will complete the path automatically
+soloing the other, and all paths that came before or after it.
+
+<P>
+Solo chains also work with MIDI tracks chained to audio inputs:
+When a MIDI track drives some MIDI device whose audio is fed into MusE,
+solo chains allow the entire chain to be soloed.
+
+<P>
+Solo chains are accessed via routing menus. (See solo chain routes
+<A HREF="#soloing_chain_routes">2.4.2</A>).
+
+<P>
+
+<H1><A NAME="SECTION00360000000000000000"></A> <A NAME="plugins"></A>
+<BR>
+Plugins
+</H1>
+Plugins are small add-ons which can process a track's data.
+
+<P>
+MIDI plugins operate on midi and drum tracks, and are found in
+the <SPAN CLASS="textbf">Midi</SPAN> menu.
+
+<P>
+Audio plugins can be applied to any track handling audio (that is,
+inputs, outputs, wave tracks, synth tracks). The effects rack
+section describes this. (See effects rack <A HREF="#effects_rack">2.6.1</A>).
+
+<P>
+
+<H2><A NAME="SECTION00361000000000000000"></A> <A NAME="effects_rack"></A>
+<BR>
+The audio effects rack
+</H2>
+All audio track types (Input, Output, Group, Wave, Synth, and Aux) have
+an effects rack into which audio plugins can be inserted in a chain.
+Currently each rack can accomodate up to four plugins.
+
+<P>
+MusE currently supports LADSPA plugins and DSSI synth and effects
+plugins.
+
+<P>
+Plugins can be added by double-clicking on an entry in the effect rack
+in the track info pane (which is shown at the left side of the arranger
+when the according track is selected). Right-clicking the rack items
+offers a self-explanatory popup menu.
+
+<P>
+All plugin controls can be automated. (See audio automation
+<A HREF="#audio_automation">2.7.1</A>).
+
+<P>
+One must carefully consider how many audio inputs and outputs a plugin
+has, and how may channels the particular audio track has (1 mono or
+2 stereo), and how MusE uses the plugins in the rack.
+
+<P>
+Learn more about this in the appendix Understanding the Effects Rack:
+<A HREF="#apx_effects_rack">3</A>
+
+<P>
+
+<H3><A NAME="SECTION00361100000000000000"></A>
+<A NAME="plugin_guis"></A>
+<BR>
+Audio plugin Graphical User Interfaces (GUIs)
+</H3> Once a plugin is added, you need a way to
+manipulate its controls, which affect its behaviour and operate
+on the sound.
+
+<P>
+MusE can show a generic GUI which contains all of the
+plugin's controls arranged in a rather plain generic fashion.
+
+<P>
+Some plugins may also have a native GUI which looks much better (it
+was specifically designed for the plugin).
+
+<P>
+Both GUI types are opened from the effects rack right-click popup menu.
+
+<P>
+
+<H1><A NAME="SECTION00370000000000000000"></A> <A NAME="automation"></A>
+<BR>
+Automation
+</H1>
+Automation is the ability to record (or construct) and playback
+exact sequences of control movements.
+
+<P>
+MIDI and audio automation are each currently uniquely different,
+but share some similarities.
+
+<P>
+
+<H2><A NAME="SECTION00371000000000000000"></A> <A NAME="audio_automation"></A>
+<BR>
+Audio automation
+</H2>
+Almost all graphical audio controls in MusE can be automated.
+
+<P>
+This includes an audio track's volume and pan, and the controls
+of any plugins in the effects rack, and if the track is a
+synthesizer track, all of the synth's controls.
+
+<P>
+Each control has a manual adjustment value. This value is shown
+when there is no automation data at all, or automation has been
+disabled.
+
+<P>
+For plugin and synth controls, it is usually more desirable to
+manipulate automation with the generic plugin GUIs, because
+MusE has full control over their behaviour. (See plugin GUIs
+<A HREF="#plugin_guis">2.6.1</A>).
+
+<P>
+There are a few ways to enter audio automation data:
+
+<UL>
+<LI>By adjusting audio controls while the transport is rolling.
+MusE will record the exact movements.
+</LI>
+<LI>By adjusting audio controls while the transport is stopped,
+at different transport positions. TOUCH mode allows this.
+</LI>
+<LI>By right-clicking any audio control and choosing an operation
+from the automation popup menu. This includes storing, erasing,
+and clearing automation events, and seeking the next or previous
+event.
+</LI>
+<LI>By drawing the data on the audio track's automation graphs.
+(See track automation <A HREF="#track_attr_automation">2.3.1</A>).
+</LI>
+</UL>
+<H4><A NAME="SECTION00371010000000000000">
+Audio automation modes</A>
+</H4>
+Each audio track strip has an automation mode button
+at the bottom. There are four automation modes:
+<DL>
+<DT><STRONG>OFF:</STRONG></DT>
+<DD>Disables all automation, uses manual value always.
+</DD>
+<DT><STRONG>READ:</STRONG></DT>
+<DD>Automation data is applied to controls. If any
+automation data exists, the manual value is overridden and has
+no effect.
+</DD>
+<DT><STRONG>TOUCH:</STRONG></DT>
+<DD>Allows you to alter a control at any time, while
+transport is stopped or rolling, If rolling, when the control is
+released it returns to reading from automation data.
+</DD>
+<DT><STRONG>WRITE:</STRONG></DT>
+<DD>Allows to adjust an initial value before rolling
+the transport. While rolling, when the control is released it does
+not return to reading from automation data.
+</DD>
+</DL>
+Here is a screenshot of automation WRITE mode, and some automation
+data, with the track pane automation popup menu showing (see track
+automation <A HREF="#track_attr_automation">2.3.1</A>):
+
+<DIV ALIGN="CENTER"><A NAME="fig:audio_automation"></A><A NAME="329"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.11:</STRONG>
+Audio automation graphs</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="782" HEIGHT="524" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_automation.png"
+ ALT="Image main_window_with_automation"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+<A NAME="midi_automation"></A>
+<H2><A NAME="SECTION00372000000000000000">
+Midi automation</A>
+</H2>
+MIDI automation is a slightly different concept: Unlike audio
+automation, currently there is no automation 'mode' and it doesn't
+record graphical control movements. Data is viewed from within
+the pianoroll and drum editors, by clicking on the 'Ctrl' button
+on those canvases.
+
+<P>
+Similar to audio controls, each midi control has a manual adjustment
+value. This value is overridden when there is midi automation data.
+
+<P>
+There are a few ways to enter MIDI automation data:
+
+<UL>
+<LI>By adjusting external MIDI controls (such as a midi keyboard
+pitch or modulation wheel) while the transport is rolling and both
+the transport and midi track are in record mode. MusE will record
+the exact movements. As mentioned earlier, note that graphical control
+movements are not recorded.
+</LI>
+<LI>By right-clicking any midi control and choosing an operation
+from the automation popup menu. This includes storing and erasing
+automation events.
+</LI>
+<LI>By adjusting volume, pan, bank or program boxes in the midi
+trackinfo panel and clicking the corresponding volume, pan, or
+program buttons. (See midi trackinfo <A HREF="#midi_trackinfo_sidebar">2.3.1</A>).
+</LI>
+<LI>By drawing the data on a midi part's automation graphs.
+</LI>
+</UL>
+Here is a screen shot of a midi track, containing a midi part
+which has been opened with the pianoroll editor and automation
+data showing.
+
+<P>
+The 'Ctrl' popup menu (bottom left) shows available midi controllers
+and the green dot indicates there is some data.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:midi_automation"></A><A NAME="339"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.12:</STRONG>
+MIDI automation graphs</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="628" HEIGHT="620" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_midi_automation.png"
+ ALT="Image main_window_with_midi_automation"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H1><A NAME="SECTION00380000000000000000">
+Configuration</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00381000000000000000">
+MIDI ports</A>
+</H2>
+MIDI ports provide an abstraction layer for your MIDI hardware and
+synthesizers (which can be both software and hardware synthesizers),
+and other MIDI applications. Port are numbered. In order to produce
+sound, each MIDI track is assigned to exactly one MIDI port, to which
+the MIDI events are then sent.
+
+<P>
+The advantage of this abstraction layer is that if your system changes,
+for example you change MIDI hardware, then you need only modify the
+ports instead of all the tracks using those ports. This is similar
+to the audio input and output track abstraction to the outside world.
+
+<P>
+<A NAME="midi_port_config"></A>
+<H4><A NAME="SECTION00381010000000000000">
+MIDI port configuration</A>
+</H4>
+In the midi/softsynth configuration menu, you must map the port numbers
+to the actual devices (by selecting ALSA or jack midi ports, or synth
+plugins).
+
+<P>
+Try left-clicking on the "Ports" column of some MIDI track.
+If you use a soft synth, right-clicking the Ports column of the synth
+or any track using the synth lets you launch the synth's GUI.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:midi_config_window"></A><A NAME="348"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.13:</STRONG>
+Midi configuration window</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="865" HEIGHT="597" ALIGN="BOTTOM" BORDER="0"
+ SRC="./midi_config_window.png"
+ ALT="Image midi_config_window"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H4><A NAME="SECTION00381020000000000000">
+Columns in the MIDI configuration ports list:</A>
+</H4>
+<DL>
+<DT><STRONG>GUI:</STRONG></DT>
+<DD>For synthesizer devices, indicates if a gui is available
+and if it is showing. Click to show.
+</DD>
+<DT><STRONG>I:</STRONG></DT>
+<DD>If present, the port can accept MIDI input. Click to
+enable or disable it.
+</DD>
+<DT><STRONG>O:</STRONG></DT>
+<DD>If present, the port can send MIDI output. Click to enable
+or disable it.
+</DD>
+<DT><STRONG>Instrument:</STRONG></DT>
+<DD>Selects the instrument to be used when MIDI is
+played through the port.
+</DD>
+<DT><STRONG>Device name:</STRONG></DT>
+<DD>Selects or creates a MIDI device assigned to the
+port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is
+enabled), or soft synthesizers. Jack MIDI devices are created by selecting
+Create Jack Device from the Device name drop-down menu. Jack MIDI devices
+can be renamed as you wish by clicking the device name. Soft synthesizers
+are created by clicking in the soft synthesizer list and then Add
+Instance. Or you can simply create a new synthesizer track from the
+arranger track list, or even the mixer menus.
+</DD>
+<DT><STRONG>In and Out routes:</STRONG></DT>
+<DD>These are for Jack MIDI devices, they are
+the routes to and from available Jack MIDI ports. Jack may provide
+different alias names for these ports, you can select which alias
+is shown.
+</DD>
+<DT><STRONG>Default in channels:</STRONG></DT>
+<DD>Auto-connect these port channels to
+new midi or drum tracks.
+</DD>
+<DT><STRONG>Default out channel:</STRONG></DT>
+<DD>Auto-connect new midi or drum tracks
+to this channel on the port.
+</DD>
+<DT><STRONG>State:</STRONG></DT>
+<DD>Indicates the state of the port including any errors
+opening it.
+</DD>
+</DL>
+
+<P>
+
+<H2><A NAME="SECTION00382000000000000000">
+Global settings</A>
+</H2>
+
+<H3><A NAME="SECTION00382100000000000000">
+Audio settings</A>
+</H3>
+
+<H4><A NAME="SECTION00382110000000000000">
+Minimum control period</A>
+</H4>
+Plugins can usually process an arbitrarily small (or large) amount
+of samples. If some plugin control value changes continously, to provide
+ideal listening experience, MusE would need to call the plugin 44100
+times a second, asking for one single value at a time. With the minimum
+control period setting, the user can force MusE to ask the plugin for
+at least N values. Setting this value to 64 would in this situation
+make MusE call the plugin <!-- MATH
+ $689=\frac{44100}{64})$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="91" HEIGHT="35" ALIGN="MIDDLE" BORDER="0"
+ SRC="img1.png"
+ ALT="$689=\frac{44100}{64})$"></SPAN> times a second,
+asking for 64 values at a time. While doing this will reduce accuracy
+of control changes, it may also reduce CPU usage, because calling
+the plugin more often, requesting smaller chunks, is more expensive
+than calling it seldomly, requesting larger chunks.
+
+<H5><A NAME="SECTION00382111000000000000">
+Recommendation</A>
+</H5>
+If you have no performance problems, or if you want to do the final
+downmix of your project, set this to a low value. If you're experiencing
+performance problems, increasing this value might help.
+
+<P>
+
+<H1><A NAME="SECTION00400000000000000000"></A>
+<A NAME="apx_effects_rack"></A>
+<BR>
+Appendix
+</H1>
+<H1><A NAME="SECTION00410000000000000000">
+Understanding the effects rack</A>
+</H1>
+One must carefully consider how many audio inputs and outputs a plugin
+has, and how may channels the particular audio track has (1 mono or
+2 stereo), and how MusE uses the plugins in the rack.
+
+<P>
+MusE will try to internally create as many independent copies
+(instances) of a plugin as necessary, to satisfy the number of channels
+in the audio track.
+Basically it divides the number of track channels by the number of
+plugin audio inputs or outputs to determine how many copies to make.
+First it examines the number of plugin audio outputs, and if there are
+none, it will examine the number of audio inputs, and if there are
+none, it will simply use just one plugin copy.
+
+<P>
+For mono tracks with plugins having more than one audio input or
+output, MusE uses the first input or output and ignores the rest.
+
+<P>
+For stereo tracks:
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="CENTER">plugin inputs</TD>
+<TD ALIGN="CENTER">outputs</TD>
+<TD ALIGN="CENTER">copies</TD>
+<TD ALIGN="CENTER">track in route channels</TD>
+<TD ALIGN="CENTER">track out route channels</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">1 (L only)</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+</TABLE>
+
+<P>
+Notice that on a stereo track with a plugin having one audio input and
+two audio outputs, only the first track input route channel is used
+(left only).
+
+<P>
+These same rules apply to inter-plugin audio when more than one plugin
+is in the rack chain. Extra audio outputs of one plugin may be ignored
+by the next plugin if not used.
+
+<P>
+Currently specialized plugins with many inputs and/or outputs are not
+really useful in MusE.
+
+<P>
+Nor are so-called 'realtime' control plugins which use audio inputs
+and outputs for control signals.
+
+<P>
+Loud noise alert! Beware of using such plugins in an audio effects
+rack.
+
+<P>
+Example: Consider a stereo Audio Input track with these effect rack
+ LADSPA plugins:
+
+<P>
+
+<UL>
+<LI>comb_splitter Comb Splitter by Steve Harris
+</LI>
+<LI>tap_stereo_echo Tap Stereo Echo by Tom Szilagyi
+</LI>
+</UL>
+
+<P>
+The Comb Splitter has one audio input and two audio outputs.
+The Stereo Echo has two audio inputs and two audio outputs.
+
+<P>
+The stereo Audio Input track will therefore ignore its second
+input route connection. It will process the left input only,
+separating it into stereo with the Comb Splitter, passing the
+split stereo signal into the Stereo Echo, finally producing
+stereo output available at the Audio Input track's output routes.
+
+<P>
+One improvement would be not creating unused redundant plugin copies
+between plugins in stereo tracks.
+For example, for a plugin having one audio input and one audio output,
+feeding a plugin having one audio input and two audio outputs,
+the extra copy of the first plugin is redundant and not required,
+but currently it is created anyway.
+<BR><HR>
+
+</BODY>
+</HTML>
diff --git a/muse2/doc/html/single/documentation/img1.png b/muse2/doc/html/single/documentation/img1.png
new file mode 100644
index 00000000..36e71d7e
--- /dev/null
+++ b/muse2/doc/html/single/documentation/img1.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/index.html b/muse2/doc/html/single/documentation/index.html
new file mode 100644
index 00000000..b24ff0be
--- /dev/null
+++ b/muse2/doc/html/single/documentation/index.html
@@ -0,0 +1,1702 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+
+<!--Converted with LaTeX2HTML 2008 (1.71)
+original version by: Nikos Drakos, CBLU, University of Leeds
+* revised and updated by: Marcus Hennecke, Ross Moore, Herb Swan
+* with significant contributions from:
+ Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
+<HTML>
+<HEAD>
+<TITLE>MusE Documentation</TITLE>
+<META NAME="description" CONTENT="MusE Documentation">
+<META NAME="keywords" CONTENT="documentation">
+<META NAME="resource-type" CONTENT="document">
+<META NAME="distribution" CONTENT="global">
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=utf-8">
+<META NAME="Generator" CONTENT="LaTeX2HTML v2008">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="documentation.css">
+
+</HEAD>
+
+<BODY >
+
+<DIV ALIGN="CENTER">
+
+<P><A NAME="fig:MusE"></A></P>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="1030" HEIGHT="722" ALIGN="BOTTOM" BORDER="0"
+ SRC="./muse2.png"
+ ALT="Image muse2">
+
+</DIV>
+<BR>
+
+<H2><A NAME="SECTION00100000000000000000">
+Contents</A>
+</H2>
+<!--Table of Contents-->
+
+<UL CLASS="TofC">
+<LI><A NAME="tex2html67"
+ HREF="documentation.html#SECTION00200000000000000000">What is this?</A>
+<LI><A NAME="tex2html68"
+ HREF="documentation.html#SECTION00300000000000000000">User's manual</A>
+<UL>
+<LI><A NAME="tex2html69"
+ HREF="documentation.html#SECTION00310000000000000000">Introduction</A>
+<UL>
+<LI><A NAME="tex2html70"
+ HREF="documentation.html#SECTION00311000000000000000">A brief history of computer audio and MusE</A>
+<LI><A NAME="tex2html71"
+ HREF="documentation.html#SECTION00312000000000000000">Definitions</A>
+<LI><A NAME="tex2html72"
+ HREF="documentation.html#SECTION00313000000000000000">Getting up and running for impatient people</A>
+<LI><A NAME="tex2html73"
+ HREF="documentation.html#SECTION00314000000000000000">Getting up and running</A>
+<LI><A NAME="tex2html74"
+ HREF="documentation.html#SECTION00315000000000000000">Beginners tutorial</A>
+</UL>
+<LI><A NAME="tex2html75"
+ HREF="documentation.html#SECTION00320000000000000000">Basic overview</A>
+<UL>
+<LI><A NAME="tex2html76"
+ HREF="documentation.html#SECTION00321000000000000000">Main/Arranger</A>
+<LI><A NAME="tex2html77"
+ HREF="documentation.html#SECTION00322000000000000000">Mixer</A>
+</UL>
+<LI><A NAME="tex2html78"
+ HREF="documentation.html#SECTION00330000000000000000">Tracks and parts</A>
+<UL>
+<LI><A NAME="tex2html79"
+ HREF="documentation.html#SECTION00331000000000000000">Tracks</A>
+<LI><A NAME="tex2html80"
+ HREF="documentation.html#SECTION00332000000000000000">Parts</A>
+</UL>
+<LI><A NAME="tex2html81"
+ HREF="documentation.html#SECTION00340000000000000000">Routes</A>
+<UL>
+<LI><A NAME="tex2html82"
+ HREF="documentation.html#SECTION00341000000000000000">Anti circular routing</A>
+<LI><A NAME="tex2html83"
+ HREF="documentation.html#SECTION00342000000000000000">Soloing chain routes</A>
+</UL>
+<LI><A NAME="tex2html84"
+ HREF="documentation.html#SECTION00350000000000000000">Track soloing</A>
+<UL>
+<LI><A NAME="tex2html85"
+ HREF="documentation.html#SECTION00351000000000000000">Phantom soloing</A>
+<LI><A NAME="tex2html86"
+ HREF="documentation.html#SECTION00352000000000000000">Soloing chains</A>
+</UL>
+<LI><A NAME="tex2html87"
+ HREF="documentation.html#SECTION00360000000000000000">Plugins</A>
+<UL>
+<LI><A NAME="tex2html88"
+ HREF="documentation.html#SECTION00361000000000000000">The audio effects rack</A>
+</UL>
+<LI><A NAME="tex2html89"
+ HREF="documentation.html#SECTION00370000000000000000">Automation</A>
+<UL>
+<LI><A NAME="tex2html90"
+ HREF="documentation.html#SECTION00371000000000000000">Audio automation</A>
+<LI><A NAME="tex2html91"
+ HREF="documentation.html#SECTION00372000000000000000">Midi automation</A>
+</UL>
+<LI><A NAME="tex2html92"
+ HREF="documentation.html#SECTION00380000000000000000">Configuration</A>
+<UL>
+<LI><A NAME="tex2html93"
+ HREF="documentation.html#SECTION00381000000000000000">MIDI ports</A>
+<LI><A NAME="tex2html94"
+ HREF="documentation.html#SECTION00382000000000000000">Global settings</A>
+</UL>
+</UL>
+<BR>
+<LI><A NAME="tex2html95"
+ HREF="documentation.html#SECTION00400000000000000000">Appendix</A>
+<UL>
+<LI><A NAME="tex2html96"
+ HREF="documentation.html#SECTION00410000000000000000">Understanding the effects rack</A>
+</UL></UL>
+<!--End of Table of Contents-->
+<H1><A NAME="SECTION00200000000000000000">
+What is this?</A>
+</H1>
+You are, if you have printed this document, holding in your hand the
+written documentation for the audio and midi sequencer MusE version 2.
+<BR><TT><A NAME="tex2html1"
+ HREF="http://www.muse-sequencer.org">http://www.muse-sequencer.org</A></TT> is MusE's home on the internet where
+everything MusE releated should be possible to find, software, this
+documentation, forums, mailing lists, bug reporting, FAQs. If you have
+this document but not the software head on over there to find what it's
+all about.
+
+<H1><A NAME="SECTION00300000000000000000">
+User's manual</A>
+</H1>
+
+<P>
+
+<H1><A NAME="SECTION00310000000000000000">
+Introduction</A>
+</H1>
+
+<H2><A NAME="SECTION00311000000000000000">
+A brief history of computer audio and MusE</A>
+</H2>
+To quickly summarize over a decades open source development: in 1999 Werner
+ Schweer released the first version of MusE, muse-0.0.1.tar.gz, in it's first
+few releases (actually not few, Werner relentlessly churned out new releases)
+MusE was only a midi sequencer. The target was to create a fully fledged
+midi sequencer for the Linux operating system. Over the years audio was
+added among with other things implemented and sometimes abandoned.
+Today MusE is a stable and feature rich music creation environment which
+strives to encompass most of the music recording process, creation, editing,
+mastering.
+
+<P>
+
+<H2><A NAME="SECTION00312000000000000000">
+Definitions</A>
+</H2>
+<SPAN CLASS="textbf">CTRL</SPAN> refers to the control key on the keyboard, e.g. <SPAN CLASS="textbf">CTRL+C</SPAN>
+means to press and hold the control key while pressing the c key. Make sure
+you know where you have it so you won't accidentally lose control
+(bad jokes are the best jokes, so say we all!).
+<BR><SPAN CLASS="textbf">SHIFT</SPAN> refers to the shift key on the keyboard, see above for usage
+<BR><SPAN CLASS="textbf">ALT</SPAN> refers to the alt key on the keyboard, see above for usage
+<BR><TT><SPAN CLASS="textbf">$&gt;</SPAN></TT> is used as a generic definition for a terminal prompt. When the
+manual lists a command that shall be typed, the prompt is not part of the
+command.
+<BR>
+Keys are always referred to in bold uppercase, e.g. <SPAN CLASS="textbf">A</SPAN>. For instance
+<SPAN CLASS="textbf">SHIFT+A</SPAN> for the key a pressed together with the shift key.
+<BR>
+Sometimes terminal examples are written tabbed in with a fixed font to
+visualize more closely what something looks like on the screen.
+E.g.
+<BR> <TT><SPAN CLASS="textbf">$&gt; muse2</SPAN></TT>
+<BR>
+<P>
+
+<H2><A NAME="SECTION00313000000000000000">
+Getting up and running for impatient people</A>
+</H2>
+Install MusE from the repository of your chosen distribution.
+To get decent performance start http://jackaudio.org/Jack with
+the following command in a terminal:
+<BR> <TT><SPAN CLASS="textbf">$&gt; jackd -d alsa -d hw:0 -p 256</SPAN></TT>
+<BR>
+Or, if you prefer, use the launcher utility
+http://qjackctl.sourceforge.net/QJackCtl to get some
+help starting Jack.
+After this, start MusE from the menu or fire up another terminal and
+type
+
+<P>
+<TT><SPAN CLASS="textbf">muse2</SPAN></TT>.
+<BR>
+If this didn't work out read on for the slightly more complete route for
+getting things started.
+
+<P>
+
+<H2><A NAME="SECTION00314000000000000000">
+Getting up and running</A>
+</H2>
+
+<H3><A NAME="SECTION00314100000000000000">
+Installation from binaries</A>
+</H3>
+There are several ways to install MusE depending on your situation. The
+most convenient way is to install a prepackaged version from your chosen
+distribution. The drawback of this is that it may not be the most recent
+version, though often there is a more recent package from a private packager.
+
+<H3><A NAME="SECTION00314200000000000000">
+Installation from source</A>
+</H3>
+Building MusE from source is not hard, there are a number of prerequistes
+that must be met but the actual building should be painless (ha, famous
+last words).
+<BR>
+Please follow the README in the source package and/or read the instructions
+on the homepage: <TT><A NAME="tex2html2"
+ HREF="http://muse-sequencer.org/index.php/Installation">http://muse-sequencer.org/index.php/Installation</A></TT>
+<P>
+
+<H3><A NAME="SECTION00314300000000000000">
+Hardware</A>
+</H3>
+MusE on the Linux platform supports midi through ALSA and Jack-midi and audio
+through Jack. For information on what hardware is supported there are some
+convenient places to check:
+
+<UL>
+<LI>Alsa soundcard matrix at
+<TT><A NAME="tex2html3"
+ HREF="http://www.alsa-project.org/main/index.php/Matrix:Main">http://www.alsa-project.org/main/index.php/Matrix:Main</A></TT>
+</LI>
+<LI><TT><A NAME="tex2html4"
+ HREF="http://FFADO.org">http://FFADO.org</A></TT> for firewire devices.
+</LI>
+</UL>
+Also, as is often a very good approach for Linux and open source, the
+various forums available on the internet often contain good information.
+Chances are someone has already tried your configuration and/or had your
+specific problem and the solution is already written down.
+
+<H3><A NAME="SECTION00314400000000000000">
+Launching</A>
+</H3>
+After installation the binary muse2 is installed on the computer. If MusE
+was installed from a distribution repository the binary may have a
+different name depending on the distribution policies. Most distributions
+do however install a menu entry so MusE should be conveniently available
+from there.
+
+<H3><A NAME="SECTION00314500000000000000">
+Audio preconditions</A>
+</H3>
+In the standard case MusE expects to find and connect to the Jack audio
+server <TT><A NAME="tex2html5"
+ HREF="http://jackaudio.org">http://jackaudio.org</A></TT>. Make sure jack is installed (if MusE was
+installed with a distribution-package Jack will very likely already be
+installed) For Jack to run with best performance your system should be
+sufficiently tuned to allow it to run with realtime capabilities. The
+realtime configuration is configuration of the operating system and roughly
+consists of two parts.
+
+<OL>
+<LI>By default on most distros only the superuser lets applications setup
+realtime capabilities. Please see the APPENDIX for setting up realtime
+</LI>
+<LI>Maximizing performance. A standard linux installation may not able
+to reach the performance required by a power user. This requires exchanging
+the linux kernel for a so called lowlatency kernel, this is also covered by
+the realtime APPENDIX.
+</LI>
+</OL>
+
+<P>
+
+<H3><A NAME="SECTION00314600000000000000">
+Running MusE</A>
+</H3>
+Find MusE in the menu or open a terminal and enter muse2.
+
+<P>
+<TT><SPAN CLASS="textbf">$&gt; muse2</SPAN></TT>
+<BR>
+A splash screen should pop up followed
+by the main application window and you are off!
+<BR>
+If an error like the screenshot below pops up the Jack audio server is
+either not running or started as a different user than what you are trying
+to start MusE as.
+
+<DIV ALIGN="CENTER"><A NAME="fig:no_audio"></A><A NAME="101"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.1:</STRONG>
+Jack server missing</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="506" HEIGHT="178" ALIGN="BOTTOM" BORDER="0"
+ SRC="./no_audio.png"
+ ALT="Image no_audio"></TD></TR>
+</TABLE>
+</DIV>
+
+<H3><A NAME="SECTION00314700000000000000">
+Midi only</A>
+</H3>
+MusE can be started in Midi-only mode where MusE does not have any external
+dependencies apart from ALSA midi. In this case start MusE from a terminal:
+<TT><SPAN CLASS="textbf">$&gt; muse2 -a</SPAN></TT>
+
+<P>
+
+<H3><A NAME="SECTION00314800000000000000">
+ALSA midi with Jack</A>
+</H3>
+If Jack is running, by default MusE will not use ALSA devices, preferring
+Jack midi instead. To force ALSA devices to be used as well as Jack
+midi, start MusE with the -A option: <TT><SPAN CLASS="textbf">$&gt; muse2 -A</SPAN></TT>
+
+<P>
+
+<H2><A NAME="SECTION00315000000000000000">
+Beginners tutorial</A>
+</H2>
+To get a quick grip of what MusE can achieve please follow this beginners
+tutorial.
+
+<H3><A NAME="SECTION00315100000000000000">
+Midi Setup</A>
+</H3>
+First off, fire up MusE as was described in the previous chapter, making
+sure that the jack audio server is started with sufficient configuration
+to allow for audio output without breakup. Also make sure your system can
+make sound.
+
+<H3><A NAME="SECTION00315200000000000000">
+Soft synth test</A>
+</H3>
+With MusE up and running right click in the Track-pane (see
+Fig. <A HREF="#fig:Main_Window">2.8</A>) and select
+<SPAN CLASS="textbf">Add Synth &gt; MESS &gt; vam soft synth</SPAN>.
+A Soft Synth track called vam-0 should appear as well as a separate GUI
+for the synthesizer.
+
+<P>
+Now right click once more in the Track-pane and select <SPAN CLASS="textbf">Add Midi
+Track</SPAN>. Another track appears called Track 1, and its track list Port
+column should show it is bound to the synth that was just created vam-0.
+If it is not, click on the Track 1 Port column to open a drop-down list
+of available devices and choose vam-0.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.05
+<IMG
+ WIDTH="23" HEIGHT="23" ALIGN="BOTTOM" BORDER="0"
+ SRC="./arrow_tool.png"
+ ALT="Image arrow_tool">
+
+</DIV>
+Now select the drawing tool icon
+from the toolbar, alternatively press the shortcut key <SPAN CLASS="textbf">D</SPAN>.
+Move the mouse over to the arranger canvas as referenced in
+Fig. <A HREF="#fig:Main_Window">2.8</A>
+and point at the midi track, the mouse should have changed to a small pencil.
+Draw a Part along the midi track using the mouse. For this exercise it is
+not important where or how large the drawn Part is. When you are done double
+click on the drawn part. This will open up the Piano Roll editor. To the
+left of the Piano Roll there are piano keys in a vertical line, try clicking
+on the keys in this virtual keyboard each click should be rewarded with a
+synth sound (maybe of questionable quality, a sound nevertheless)
+
+<DIV ALIGN="CENTER"><A NAME="fig:vam_synth"></A><A NAME="123"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.2:</STRONG>
+vam synthesizer</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="750" HEIGHT="560" ALIGN="BOTTOM" BORDER="0"
+ SRC="./vam_synth.png"
+ ALT="Image vam_synth"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H3><A NAME="SECTION00315300000000000000">
+Missing sound</A>
+</H3>
+If you got sound from the previous exercise you can carry on to the next,
+or keep reading for further enlightenment in case you come upon trouble
+later on. If there is no sound we need to do some fault hunting. First
+off, click on Arranger window once more and select the vam-0 track in the
+track-pane.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Midi_editor"></A><A NAME="129"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.3:</STRONG>
+Midi editor view</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="914" HEIGHT="679" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_midi_editor_vam.png"
+ ALT="Image main_window_with_midi_editor_vam"></TD></TR>
+</TABLE>
+</DIV>
+Now bring back Piano Roll window and align the windows so you
+can see the piano keys as well as the Meter on the Mixer Strip (see the
+5 Function by function chapter for more information on these windows).
+The result should be something like the following:
+
+<P>
+When pressing one of the keys on virtual Keyboard the Meter on the Mixer
+Strip should light up in green to visualize that the Synth is making
+sound, if it is not try to trace back your steps and and see if you did
+anything differently than described.
+Now, if the Meter lights up but there is still no sound we need to
+check the routing between the tracks. Click on the Arranger window again
+and select the Out 1 track, this is the predefined output which MusE by
+default loads at startup, at the bottom of Mixer Strip there are two
+buttons looking like tele- jacks, these bring up the inputs and outputs
+of the track, click on the right one, the output and make sure that it is
+connected to some valid outputs on your system.
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="231" HEIGHT="318" ALIGN="BOTTOM" BORDER="0"
+ SRC="./output_routing.png"
+ ALT="Image output_routing">
+
+</DIV>
+Click on the outputs to select them, if you did changes here go back and
+try clicking on the Piano Roll keyboard again, hopefully it helped. If there
+still are problems make sure your system actually can make sound through
+Jack, this is however getting outside the scope of this manual.
+<BR>
+<BR><SPAN CLASS="textit">This might be the time to bring up the concept of community support.
+Open source software could never be what it is without the support given by
+individuals on forums and mailinglists, if the information given in this
+document is not enough, try googling your problem and/or get in touch with
+one of the online forums for MusE or Linux audio in general. See some pointers
+in the Support chapter.</SPAN>
+
+<P>
+
+<H3><A NAME="SECTION00315400000000000000">
+Recording Midi</A>
+</H3> TBD
+
+<H3><A NAME="SECTION00315500000000000000">
+Recording Audio</A>
+</H3>
+At this point we'll make a a slight detour into full on audio recording. Getting
+audio out of MusE has already been covered in the previous chapters so we will
+concentrate on the additional steps needed to record onto an audio track.
+<BR>
+<BR>
+When MusE is first fired up, the
+output track has already been created (more about this in the chapter about
+templates), to proceed with audio recording we need to add two additional tracks, a
+wave track and an input track.
+<BR>
+When MusE is first started right click in an empty space on the track view
+
+<DIV ALIGN="CENTER"><A NAME="fig:Add_track"></A><A NAME="142"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.4:</STRONG>
+Add track</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="782" HEIGHT="498" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_add_track.png"
+ ALT="Image main_window_add_track"></TD></TR>
+</TABLE>
+</DIV>
+and select <SPAN CLASS="textbf">Add Audio Input</SPAN>. Right click again and also select
+<SPAN CLASS="textbf">Add Wave Track</SPAN>. Two additional tracks are now visible in the Arranger,
+"Input 1" and "Track 1", bring up the mixer with <SPAN CLASS="textbf">F10</SPAN> and you should see
+the following configuration.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Mixer_with_one_input"></A><A NAME="150"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.5:</STRONG>
+Mixer with one input</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="216" HEIGHT="418" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer_with_one_input.png"
+ ALT="Image mixer_with_one_input"></TD></TR>
+</TABLE>
+</DIV>
+
+<BR>
+Note the buttons on each mixer strip. hover over them to see their
+functionality. For more information on all the buttons see coming chapters
+about the mixer. For now lets just do what we must.
+<BR>
+1. click on the stereo symbol over the slider to change the input to a mono track.
+<BR>
+2. do the same for the wave track (optional)
+<BR>
+3. click on the Mute (gray speaker) icon on the input track to unmute it.
+<BR>
+4. click on the input routing button (see the tooltip, it looks like a tele plug)
+on the input track and select an appropriate connection from your system.
+<BR>
+5. click on the output routing button on the input track and select
+<SPAN CLASS="textbf">Track 1</SPAN>
+<BR>
+<BR>
+Already after the meter on the input track should be able to display that there
+is incoming sound from your sound source. If there actually is sound coming
+from your sound source, that is.
+<BR>
+We are now nearly ready to start recording. First we need to select a location
+to store the files. MusE does not use a centralized storage of soundfiles but
+uses the path of the song-file (extension .med) as guidance as to where the
+audio files should be placed. Now as it happens MusE will prohibit us from
+starting a recording until the songfile has been stored. So lets take advantage
+of this behaviour and just go ahead and try to record. Let's get started.
+<BR>
+In the mixer click on the red <SPAN CLASS="textbf">record</SPAN> dot on the Audio Track to arm it
+for recording (or enable if you will). Now when there is audio coming into the
+input it will also show up on the Audio Track. Also note that all the input and
+output routing buttons on the tracks now have the same gray color, this means
+that all of the tracks have a proper connection.
+
+<DIV ALIGN="CENTER"><A NAME="fig:Mixer_buttons"></A><A NAME="157"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.6:</STRONG>
+Mixer buttons</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="217" HEIGHT="166" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer_with_one_input_buttons.png"
+ ALT="Image mixer_with_one_input_buttons"></TD></TR>
+</TABLE>
+</DIV>
+
+<BR>
+All fine and dandy. Now bring up the arranger window and find the round, red on
+white <SPAN CLASS="textbf">record</SPAN> button and click on it. This is your queue to MusE to
+prepare for recording. However since we have not saved our song we are presented
+with a dialog to do just that.
+<BR>
+<DIV ALIGN="CENTER"><A NAME="fig:Save_song"></A><A NAME="163"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.7:</STRONG>
+Save song</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="575" HEIGHT="405" ALIGN="BOTTOM" BORDER="0"
+ SRC="./project_my_first_song.png"
+ ALT="Image project_my_first_song"></TD></TR>
+</TABLE>
+</DIV>
+Note the check box for creating a project folder, when working with audio this
+is very much recommended or you may soon loose track of what audio files belong
+to which song.
+<BR>
+Finally we are ready to start recording! The process is completed by clicking
+on the <SPAN CLASS="textbf">Play</SPAN> button in the Arranger. If all went well MusE then starts
+to record a wave file from the Input Track placed in your song directory.
+<BR>
+When you wish to stop recording press <SPAN CLASS="textbf">Stop</SPAN> in the Arranger, now the
+resulting waveform should be visible in the Arranger. After rewinding the Play
+position and pressing <SPAN CLASS="textbf">Play</SPAN> again the resulting sound should be audible
+through the connected output.
+
+<P>
+
+<H1><A NAME="SECTION00320000000000000000">
+Basic overview</A>
+</H1>
+In this section we will make a step by step walk-through of all the
+different editors, their purpose and what functions they support.
+
+<P>
+
+<H2><A NAME="SECTION00321000000000000000">
+Main/Arranger</A>
+</H2>
+
+<P>
+<A NAME="Main_Arranger"></A>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Main_Window"></A><A NAME="174"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.8:</STRONG>
+MusE main window</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="846" HEIGHT="571" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_annotated.png"
+ ALT="Image main_window_annotated"></TD></TR>
+</TABLE>
+</DIV>
+Above is the main window of MusE, the Arranger, this is what greets you
+when launching MusE. The Arranger consists of two main parts, the Track-pane
+and the Arranger canvas. The Track-pane lists all currently visible tracks
+and the Arranger canvas contains all Parts of the composition. The
+screenshot above shows an empty project. Below is MusE with a song in
+progress, turns out it wasn't a very good song, but for our purposes it
+is fine. In the below screenshot there are a lot of tracks visible in the
+Track-pane, each have an icon which indicate it's type, wave-track, input,
+output etcetera, more about that later. In the Arranger canvas a number of
+parts are visible, the ones in yellow are in this composition wave files,
+the multicolored line are different Parts of a drum track.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Main_Window_with_arrangement"></A><A NAME="179"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.9:</STRONG>
+MusE main window with arrangement</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="1051" HEIGHT="635" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_arrangement.png"
+ ALT="Image main_window_with_arrangement"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00322000000000000000"></A> <A NAME="mixer"></A>
+<BR>
+Mixer
+</H2>
+Choosing <SPAN CLASS="textbf">View &gt; Mixer A</SPAN> or <SPAN CLASS="textbf">B</SPAN> from the menu in the main
+window will bring up the mixer as viewed below. The mixer will open with
+all options enabled, showing channel strips for all tracks in the current
+setup, depending on how far you have gotten this view may become very large,
+at which point it may be a good idea to limit what is viewed in the Mixer.
+From the view menu all the different kinds of tracks can be toggled on/off
+from the mixer. Some may find it a good idea to use the two mixers A and B
+setup with different setup and store this in your song template(s), more
+about this in the Song Template section. It can be argued that everything
+in MusE is a track analogous to the Unix idiom that everything is a file.
+The types of tracks visible in the mixer (and track-pane) are:
+
+<DIV ALIGN="CENTER">
+r0.5
+<IMG
+ WIDTH="672" HEIGHT="424" ALIGN="BOTTOM" BORDER="0"
+ SRC="./mixer.png"
+ ALT="Image mixer">
+
+</DIV>
+
+<UL>
+<LI>Audio output
+</LI>
+<LI>Audio input
+</LI>
+<LI>Group track
+</LI>
+<LI>Aux track
+</LI>
+<LI>Wave track
+</LI>
+<LI>Synth track
+</LI>
+<LI>Midi track
+</LI>
+</UL>
+
+<P>
+There is also a Midi Track variation called Drum Track, they are
+however not distinguishable from Midi Tracks in the Mixer. Also the
+strips for midi tracks are different in the Mixer than in the
+Track-pane view.
+
+<P>
+
+<H1><A NAME="SECTION00330000000000000000">
+Tracks and parts</A>
+</H1>
+MusE arranges your music in <SPAN CLASS="textit">tracks</SPAN> and <SPAN CLASS="textit">parts</SPAN>. The following
+section shall provide you an overview of how things are done with MusE.
+If you are or were a Cubase or Cakewalk user, you will feel familiar with
+this.
+
+<P>
+
+<H2><A NAME="SECTION00331000000000000000">
+Tracks</A>
+</H2>
+There are two general classes of tracks: MIDI tracks and audio
+tracks. MIDI tracks (and drum tracks which are internally MIDI tracks)
+can hold note data. The Wave track is a type of audio track which holds
+wave data. There are also several other kinds of audio tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331010000000000000">
+MIDI tracks</A>
+</H4>
+MIDI and drum tracks hold MIDI event data. They don't differ much,
+except that drum tracks offer a special editor which is more suitable
+for drum editing.
+
+<P>
+
+<H4><A NAME="SECTION00331020000000000000">
+Wave tracks</A>
+</H4>
+They hold audio data which can be just played back or be piped through
+effect plugin chains. They offer automation for these plugins.
+
+<P>
+
+<H4><A NAME="SECTION00331030000000000000">
+Audio input tracks</A>
+</H4>
+These provide the path for your audio data from outside into your
+project. Set up the physical audio inputs you want to connect your
+audio input track with, and then route the input tracks to various
+other tracks such as wave tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331040000000000000">
+Audio output tracks</A>
+</H4>
+These provide the path for your project's audio data to outside. Set
+up the physical audio outputs you want to connect your audio out track
+with, and then route various other tracks, such as wave tracks, to
+the output tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331050000000000000">
+Audio group tracks</A>
+</H4>
+Group tracks are like busses, where you can route other tracks to
+them, then route the groups to other tracks. Since group tracks have
+all the features of other audio tracks, like volume and pan, they
+provide a convenient common routing point where you have control of
+the sound before it is passed to other tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331060000000000000"></A> <A NAME="aux_tracks"></A>
+<BR>
+Audio aux tracks
+</H4>
+These provide a more convenient way to mix several audio tracks
+together. With each audio aux track added, other audio tracks will
+gain a common send knob for adjusting the level sent to the aux
+track. This can be more convenient than using several group tracks.
+
+<P>
+
+<H4><A NAME="SECTION00331070000000000000">
+Synthesizer tracks</A>
+</H4>
+This type of track is a software synthesizer which MIDI and drum tracks
+can be assigned to.
+
+<P>
+
+<H4><A NAME="SECTION00331080000000000000">
+Creation</A>
+</H4>
+You can create a track by either right-clicking in the arranger's track list and then adding the desired track, or via the edit menu.
+
+<P>
+
+<H4><A NAME="SECTION00331090000000000000">
+Attributes</A>
+</H4>
+Tracks have several attributes:
+<DL>
+<DT><STRONG>Mute:</STRONG></DT>
+<DD>If you click on the <SPAN CLASS="textit">Mute</SPAN> field (denoted with
+a "M" column header), the track gets muted and stops producing sound.
+</DD>
+<DT><STRONG>Solo:</STRONG></DT>
+<DD><A NAME="track_attr_solo"></A> The solo button ("S" column
+header) singles out a track for listening. It mutes
+some other tracks but may phantom solo others.
+For more info see the section on soloing: <A HREF="#track_soloing">2.5</A> and
+phantom soloing: <A HREF="#phantom_soloing">2.5.1</A>
+</DD>
+<DT><STRONG>Record:</STRONG></DT>
+<DD>The R column "arms" your track for recording.
+When you rec-arm your song and have no tracks rec-armed, you won't be
+able to record anything. See also the config option "move rec-arm with selection".
+</DD>
+<DT><STRONG>Track name:</STRONG></DT>
+<DD>Double-click to edit the track name.
+</DD>
+<DT><STRONG>Port:</STRONG></DT>
+<DD>For MIDI tracks, this lets you select the MIDI
+port to which the events should be routed. This can be your physical
+synthesizer or a software synthesizer. For soft synths, this is the
+port the synth is associated to. For other track types, this is disabled.
+</DD>
+<DT><STRONG>Channel:</STRONG></DT>
+<DD>For MIDI tracks, this is the MIDI channel the
+output is sent to. For any kind of audio tracks, this is the number of
+channels (mono, stereo).
+ </DD>
+<DT><STRONG>Automation:</STRONG></DT>
+<DD><A NAME="track_attr_automation"></A> For audio tracks,
+this lets you set up the automation display in the arranger.
+(See automation <A HREF="#audio_automation">2.7.1</A>). Clicking this will provide you
+with a popup menu with lots of submenus. Clicking on a submenu will
+select or unselect it showing or hiding the automation parameter as a
+graph overlaid on top of the track.
+<BR>
+The submenus let you select the color you want to associate with the
+automation parameter. There you can also assign midi controllers to
+the parameters, a dialog is shown where you can manually choose the
+midi controller, with a <SPAN CLASS="textit">learn</SPAN> button to 'listen for' and
+automatically recognize any midi controller operated by you.
+
+<P>
+</DD>
+<DT><STRONG>Clef:</STRONG></DT>
+<DD>For MIDI tracks, you can specify a clef here. This
+only affects the score editor.
+
+<P>
+</DD>
+</DL>
+
+<P>
+
+<H3><A NAME="SECTION00331100000000000000">
+The trackinfo side bar</A>
+</H3>
+In the arranger and the part editors, you'll have a trackinfo sidebar
+on the left side. You can set up track-type specific things there.
+
+<P>
+
+<H4><A NAME="SECTION00331110000000000000"></A> <A NAME="midi_trackinfo_sidebar"></A>
+<BR>
+MIDI trackinfo sidebar
+</H4>
+The MIDI trackinfo sidebar lets you change program, volume, pan and
+more. This sidebar can also be viewed at the left of the pianoroll
+editor.
+
+<H5><A NAME="SECTION00331111000000000000">
+Old style drum tracks:</A>
+</H5>
+These are MIDI tracks as well, but with a few differences. They allow
+you to map certain drum sounds with different input notes, and you
+can change the output settings of a certain "drum instrument" without
+having to alter each single event.
+
+<P>
+However, they have certain limitations: They only can handle 128 sounds
+(even if you have more synthes), they aren't really compatible with
+MIDI tracks (you can interchange parts between them, but if you touched
+the drum list, you'll get unexpected results), you can't set a program
+for the used channel and more.
+
+<P>
+
+<H3><A NAME="SECTION00331200000000000000">
+New style drum tracks</A>
+</H3>
+Because of these limitations, we introduced the new-style drum tracks.
+They're not fully compatible with the old drum tracks, so the old are
+still retained. Under "Global Settings", "GUI settings", you can set
+up whether you prefer the old or new.
+
+<P>
+They are handled exactly like plain MIDI tracks (staying compatible with
+them), and offer all of the functionality, though in a different way.
+They allow you to re-order the drum map efficiently, you can open parts
+from multiple drum tracks in <SPAN CLASS="textit">one</SPAN> drum editor (MusE will separate
+the sounds from different tracks according to your settings, see the
+"Window Config" menu), and you can set programs as with normal MIDI tracks.
+
+<P>
+
+<H5><A NAME="SECTION00331201000000000000">
+MIDI trackinfo controls:</A>
+</H5>
+<DL>
+<DT><STRONG>Output port:</STRONG></DT>
+<DD>This drop-down list selects the midi port
+to send midi output from this track.
+</DD>
+<DT><STRONG>Output channel:</STRONG></DT>
+<DD>This box selects the midi channel to be
+used on the output port.
+</DD>
+<DT><STRONG>Input and output routing:</STRONG></DT>
+<DD>Selects midi ports and
+channels to receive midi from, and soloing paths. (See Routes
+<A HREF="#routes">2.4</A>).
+</DD>
+<DT><STRONG>Midi through:</STRONG></DT>
+<DD>This button selects whether midi input is
+passed through to the selected output port.
+<BR>
+Depending on your midi devices and settings, there are cases when
+this should be off such as using the same port and channel for
+input and output (otherwise a double-note <SPAN CLASS="textit">echo</SPAN> will be heard),
+and cases when it must be on such as when using a synthesizer track
+as output device.
+</DD>
+<DT><STRONG>Input detect indicator:</STRONG></DT>
+<DD>Blinks when midi activity is
+detected on the selected midi channels on the selected midi input
+ports.
+</DD>
+<DT><STRONG>Transpose:</STRONG></DT>
+<DD>This transposes midi input notes up or down
+in pitch. This is very useful if your midi keyboard hasn't enough
+keys or the selected output device plays an octave too low or high,
+and you would like to shift the octave of the incoming notes to
+compensate.
+</DD>
+<DT><STRONG>Delay:</STRONG></DT>
+<DD>Adjusts the delay of the notes.
+</DD>
+<DT><STRONG>Length:</STRONG></DT>
+<DD>Adjusts the length of the notes.
+</DD>
+<DT><STRONG>Velocity:</STRONG></DT>
+<DD>Adjusts the velocity of incoming notes.
+Use it to compensate for a too-loud or too-soft keyboard.
+</DD>
+<DT><STRONG>Compression:</STRONG></DT>
+<DD>Adjusts the compression of incoming note
+velocities. Use it to make soft incoming notes louder, and loud
+notes not so loud.
+</DD>
+<DT><STRONG>Instrument:</STRONG></DT>
+<DD>Selects the midi instrument patch to be used
+by the selected output port. This is equivalent of dialing the patch
+in the bank and program boxes, except it displays a more friendly
+patch <SPAN CLASS="textit">name</SPAN> as defined by the selected output port's midi
+instrument. See instruments, or port configuration
+<A HREF="#midi_port_config">2.8.1</A>
+</DD>
+<DT><STRONG>H-Bank:</STRONG></DT>
+<DD>Selects the high bank number of the current patch.
+</DD>
+<DT><STRONG>L-Bank:</STRONG></DT>
+<DD>Selects the low bank number of the current patch.
+</DD>
+<DT><STRONG>Prog:</STRONG></DT>
+<DD>Selects the program number of the current patch.
+</DD>
+<DT><STRONG>Volume:</STRONG></DT>
+<DD>Adjusts the midi volume controller.
+</DD>
+<DT><STRONG>Pan:</STRONG></DT>
+<DD>Adjusts the midi pan controller.
+</DD>
+</DL>
+The buttons beside the Prog, Volume, and Pan boxes store the value,
+at the current transport position, for midi automation. (See
+automation <A HREF="#midi_automation">2.7.1</A>).
+
+<P>
+Note that the 'Prog' button stores H-Bank and L-Bank along with
+'Prog' value, so there are no H-Bank and L-Bank buttons.
+
+<P>
+The 'All' button simply stores all three Program (and banks), Volume,
+and Pan values at once.
+
+<P>
+<SPAN CLASS="textit">Tip:</SPAN> If the Song Type is GM, GS, or XG, you may need to store
+desired values at transport position zero, otherwise your adjustments
+may be overriden by the instrument when the transport is moved back
+to position zero. If this behaviour is undesired, you can set the
+Song Type to 'NO' meaning no song type.
+
+<P>
+
+<H4><A NAME="SECTION00331210000000000000">
+Audio trackinfo sidebar</A>
+</H4>
+Unlike the midi trackinfo sidebar, the audio trackinfo side bar
+is nothing more than an embedded audio mixer strip, the exact same
+strip as found in the mixers. (See mixer <A HREF="#mixer">2.2.2</A>).
+
+<H5><A NAME="SECTION00331211000000000000">
+Effects rack:</A>
+</H5>
+On the top of the audio trackinfo sidebar, there is an effects rack
+which allows you to apply various plugins on the audio. For more
+information on this, refer to <A HREF="#effects_rack">2.6.1</A>.
+
+<P>
+
+<H2><A NAME="SECTION00332000000000000000">
+Parts</A>
+</H2>
+Within MIDI, drum and wave tracks, you can create <SPAN CLASS="textit">parts</SPAN>. Parts
+are chunks of coherent notes or wave data which can be moved around,
+copied, cloned and deleted independent from other parts.
+
+<P>
+Parts are created by selecting the pencil tool and then drawing onto
+the right part area in the arranger. You can move them with the arrow
+tool, delete them using the <SPAN CLASS="textbf">DEL</SPAN> key, and a right-click opens
+a popup menu. This menu allows you even more stuff, such as setting
+the part's color, saving the part to disk etc.. You can use
+<SPAN CLASS="textbf">CTRL+C</SPAN> and <SPAN CLASS="textbf">CTRL+V</SPAN> for copying and pasting parts.
+<SPAN CLASS="textbf">CTRL+B</SPAN> pastes the part as a clone. Pressing <SPAN CLASS="textbf">SHIFT</SPAN>
+additionally provides you a dialog which allows you to paste the part
+multiple times and set more stuff.
+
+<P>
+You can also copy parts with the mouse by moving the part with the mouse
+while holding down the <SPAN CLASS="textbf">CTRL</SPAN> key.
+
+<P>
+
+<H1><A NAME="SECTION00340000000000000000"></A> <A NAME="routes"></A>
+<BR>
+Routes
+</H1>
+Routes are how tracks are connected together and to the outside world.
+(They are also how Jack midi ports connect to the outside world. See
+midi port configuration <A HREF="#midi_port_config">2.8.1</A>).
+Each track strip has two buttons whose icons look like plugs. One button
+is for input routing and the other is for output routing. Clicking on
+these buttons will pop up a menu of available input or output routes that
+you can connect to. Most audio tracks list other tracks to connect to,
+but audio input and output tracks are special: Audio input track input
+routing menus list available Jack audio input ports. Conversely audio
+output track output routing menus list available Jack audio output ports.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="231" HEIGHT="318" ALIGN="BOTTOM" BORDER="0"
+ SRC="./output_routing.png"
+ ALT="Image output_routing">
+
+</DIV>
+
+<P>
+Meanwhile MIDI and drum tracks allow you to route available MIDI ports
+and channels to the track using a handy popup matrix.
+
+<P>
+
+<DIV ALIGN="CENTER">
+r0.25
+<IMG
+ WIDTH="522" HEIGHT="158" ALIGN="BOTTOM" BORDER="0"
+ SRC="./midi_routing_matrix.png"
+ ALT="Image midi_routing_matrix">
+
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00341000000000000000"></A> <A NAME="anti_circular_routing"></A>
+<BR>
+Anti circular routing
+</H2>
+Any routing menu item which would cause a circular routing condition
+is grayed out. Find out why the condition would exist by examining
+routing paths involved and correct the situation if required.
+
+<P>
+Also, you cannot use a track's aux sends if the track has an input
+route path from ANY Aux Track. (See aux tracks <A HREF="#aux_tracks">2.3.1</A>).
+Aux send knobs and labels are disabled in that case.
+
+<P>
+
+<H2><A NAME="SECTION00342000000000000000"></A> <A NAME="soloing_chain_routes"></A>
+<BR>
+Soloing chain routes
+</H2>
+Soloing chains (see solo chains <A HREF="#soloing_chains">2.5.2</A>) are really just
+routes like any other. The available solo chaining paths are displayed
+in the routing popup menus.
+
+<P>
+
+<H1><A NAME="SECTION00350000000000000000"></A> <A NAME="track_soloing"></A>
+<BR>
+Track soloing
+</H1>
+Soloing allows you to single out a track for listening while muting others,
+without you having to mute the other tracks. (See soloing track attribute
+<A HREF="#track_attr_solo">2.3.1</A>).
+
+<P>
+
+<H2><A NAME="SECTION00351000000000000000"></A> <A NAME="phantom_soloing"></A>
+<BR>
+Phantom soloing
+</H2>
+In order to solo a track and mute others so that it is heard, MusE
+employs 'phantom' soloing: When a track is soloed, MusE automatically
+solos all tracks routed to and from this track. (See routes
+<A HREF="#routes">2.4</A>). A phantom soloed track is indicated by a black square
+in the track pane solo column. (See track attributes
+<A HREF="#track_attr_solo">2.3.1</A>).
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:Soloing"></A><A NAME="295"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.10:</STRONG>
+Soloing, with phantom soloing</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="529" HEIGHT="476" ALIGN="BOTTOM" BORDER="0"
+ SRC="./soloing_window.png"
+ ALT="Image soloing_window"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H2><A NAME="SECTION00352000000000000000"></A> <A NAME="soloing_chains"></A>
+<BR>
+Soloing chains
+</H2>
+When an audio output track sends audio to some external entity, such
+as an external running application, and audio from the external entity
+is fed back into a MusE audio input track, solo chains allow you to
+solo the input or output, and MusE will complete the path automatically
+soloing the other, and all paths that came before or after it.
+
+<P>
+Solo chains also work with MIDI tracks chained to audio inputs:
+When a MIDI track drives some MIDI device whose audio is fed into MusE,
+solo chains allow the entire chain to be soloed.
+
+<P>
+Solo chains are accessed via routing menus. (See solo chain routes
+<A HREF="#soloing_chain_routes">2.4.2</A>).
+
+<P>
+
+<H1><A NAME="SECTION00360000000000000000"></A> <A NAME="plugins"></A>
+<BR>
+Plugins
+</H1>
+Plugins are small add-ons which can process a track's data.
+
+<P>
+MIDI plugins operate on midi and drum tracks, and are found in
+the <SPAN CLASS="textbf">Midi</SPAN> menu.
+
+<P>
+Audio plugins can be applied to any track handling audio (that is,
+inputs, outputs, wave tracks, synth tracks). The effects rack
+section describes this. (See effects rack <A HREF="#effects_rack">2.6.1</A>).
+
+<P>
+
+<H2><A NAME="SECTION00361000000000000000"></A> <A NAME="effects_rack"></A>
+<BR>
+The audio effects rack
+</H2>
+All audio track types (Input, Output, Group, Wave, Synth, and Aux) have
+an effects rack into which audio plugins can be inserted in a chain.
+Currently each rack can accomodate up to four plugins.
+
+<P>
+MusE currently supports LADSPA plugins and DSSI synth and effects
+plugins.
+
+<P>
+Plugins can be added by double-clicking on an entry in the effect rack
+in the track info pane (which is shown at the left side of the arranger
+when the according track is selected). Right-clicking the rack items
+offers a self-explanatory popup menu.
+
+<P>
+All plugin controls can be automated. (See audio automation
+<A HREF="#audio_automation">2.7.1</A>).
+
+<P>
+One must carefully consider how many audio inputs and outputs a plugin
+has, and how may channels the particular audio track has (1 mono or
+2 stereo), and how MusE uses the plugins in the rack.
+
+<P>
+Learn more about this in the appendix Understanding the Effects Rack:
+<A HREF="#apx_effects_rack">3</A>
+
+<P>
+
+<H3><A NAME="SECTION00361100000000000000"></A>
+<A NAME="plugin_guis"></A>
+<BR>
+Audio plugin Graphical User Interfaces (GUIs)
+</H3> Once a plugin is added, you need a way to
+manipulate its controls, which affect its behaviour and operate
+on the sound.
+
+<P>
+MusE can show a generic GUI which contains all of the
+plugin's controls arranged in a rather plain generic fashion.
+
+<P>
+Some plugins may also have a native GUI which looks much better (it
+was specifically designed for the plugin).
+
+<P>
+Both GUI types are opened from the effects rack right-click popup menu.
+
+<P>
+
+<H1><A NAME="SECTION00370000000000000000"></A> <A NAME="automation"></A>
+<BR>
+Automation
+</H1>
+Automation is the ability to record (or construct) and playback
+exact sequences of control movements.
+
+<P>
+MIDI and audio automation are each currently uniquely different,
+but share some similarities.
+
+<P>
+
+<H2><A NAME="SECTION00371000000000000000"></A> <A NAME="audio_automation"></A>
+<BR>
+Audio automation
+</H2>
+Almost all graphical audio controls in MusE can be automated.
+
+<P>
+This includes an audio track's volume and pan, and the controls
+of any plugins in the effects rack, and if the track is a
+synthesizer track, all of the synth's controls.
+
+<P>
+Each control has a manual adjustment value. This value is shown
+when there is no automation data at all, or automation has been
+disabled.
+
+<P>
+For plugin and synth controls, it is usually more desirable to
+manipulate automation with the generic plugin GUIs, because
+MusE has full control over their behaviour. (See plugin GUIs
+<A HREF="#plugin_guis">2.6.1</A>).
+
+<P>
+There are a few ways to enter audio automation data:
+
+<UL>
+<LI>By adjusting audio controls while the transport is rolling.
+MusE will record the exact movements.
+</LI>
+<LI>By adjusting audio controls while the transport is stopped,
+at different transport positions. TOUCH mode allows this.
+</LI>
+<LI>By right-clicking any audio control and choosing an operation
+from the automation popup menu. This includes storing, erasing,
+and clearing automation events, and seeking the next or previous
+event.
+</LI>
+<LI>By drawing the data on the audio track's automation graphs.
+(See track automation <A HREF="#track_attr_automation">2.3.1</A>).
+</LI>
+</UL>
+<H4><A NAME="SECTION00371010000000000000">
+Audio automation modes</A>
+</H4>
+Each audio track strip has an automation mode button
+at the bottom. There are four automation modes:
+<DL>
+<DT><STRONG>OFF:</STRONG></DT>
+<DD>Disables all automation, uses manual value always.
+</DD>
+<DT><STRONG>READ:</STRONG></DT>
+<DD>Automation data is applied to controls. If any
+automation data exists, the manual value is overridden and has
+no effect.
+</DD>
+<DT><STRONG>TOUCH:</STRONG></DT>
+<DD>Allows you to alter a control at any time, while
+transport is stopped or rolling, If rolling, when the control is
+released it returns to reading from automation data.
+</DD>
+<DT><STRONG>WRITE:</STRONG></DT>
+<DD>Allows to adjust an initial value before rolling
+the transport. While rolling, when the control is released it does
+not return to reading from automation data.
+</DD>
+</DL>
+Here is a screenshot of automation WRITE mode, and some automation
+data, with the track pane automation popup menu showing (see track
+automation <A HREF="#track_attr_automation">2.3.1</A>):
+
+<DIV ALIGN="CENTER"><A NAME="fig:audio_automation"></A><A NAME="329"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.11:</STRONG>
+Audio automation graphs</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="782" HEIGHT="524" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_automation.png"
+ ALT="Image main_window_with_automation"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+<A NAME="midi_automation"></A>
+<H2><A NAME="SECTION00372000000000000000">
+Midi automation</A>
+</H2>
+MIDI automation is a slightly different concept: Unlike audio
+automation, currently there is no automation 'mode' and it doesn't
+record graphical control movements. Data is viewed from within
+the pianoroll and drum editors, by clicking on the 'Ctrl' button
+on those canvases.
+
+<P>
+Similar to audio controls, each midi control has a manual adjustment
+value. This value is overridden when there is midi automation data.
+
+<P>
+There are a few ways to enter MIDI automation data:
+
+<UL>
+<LI>By adjusting external MIDI controls (such as a midi keyboard
+pitch or modulation wheel) while the transport is rolling and both
+the transport and midi track are in record mode. MusE will record
+the exact movements. As mentioned earlier, note that graphical control
+movements are not recorded.
+</LI>
+<LI>By right-clicking any midi control and choosing an operation
+from the automation popup menu. This includes storing and erasing
+automation events.
+</LI>
+<LI>By adjusting volume, pan, bank or program boxes in the midi
+trackinfo panel and clicking the corresponding volume, pan, or
+program buttons. (See midi trackinfo <A HREF="#midi_trackinfo_sidebar">2.3.1</A>).
+</LI>
+<LI>By drawing the data on a midi part's automation graphs.
+</LI>
+</UL>
+Here is a screen shot of a midi track, containing a midi part
+which has been opened with the pianoroll editor and automation
+data showing.
+
+<P>
+The 'Ctrl' popup menu (bottom left) shows available midi controllers
+and the green dot indicates there is some data.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:midi_automation"></A><A NAME="339"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.12:</STRONG>
+MIDI automation graphs</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="628" HEIGHT="620" ALIGN="BOTTOM" BORDER="0"
+ SRC="./main_window_with_midi_automation.png"
+ ALT="Image main_window_with_midi_automation"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H1><A NAME="SECTION00380000000000000000">
+Configuration</A>
+</H1>
+
+<P>
+
+<H2><A NAME="SECTION00381000000000000000">
+MIDI ports</A>
+</H2>
+MIDI ports provide an abstraction layer for your MIDI hardware and
+synthesizers (which can be both software and hardware synthesizers),
+and other MIDI applications. Port are numbered. In order to produce
+sound, each MIDI track is assigned to exactly one MIDI port, to which
+the MIDI events are then sent.
+
+<P>
+The advantage of this abstraction layer is that if your system changes,
+for example you change MIDI hardware, then you need only modify the
+ports instead of all the tracks using those ports. This is similar
+to the audio input and output track abstraction to the outside world.
+
+<P>
+<A NAME="midi_port_config"></A>
+<H4><A NAME="SECTION00381010000000000000">
+MIDI port configuration</A>
+</H4>
+In the midi/softsynth configuration menu, you must map the port numbers
+to the actual devices (by selecting ALSA or jack midi ports, or synth
+plugins).
+
+<P>
+Try left-clicking on the "Ports" column of some MIDI track.
+If you use a soft synth, right-clicking the Ports column of the synth
+or any track using the synth lets you launch the synth's GUI.
+
+<P>
+
+<DIV ALIGN="CENTER"><A NAME="fig:midi_config_window"></A><A NAME="348"></A>
+<TABLE>
+<CAPTION ALIGN="BOTTOM"><STRONG>Figure 2.13:</STRONG>
+Midi configuration window</CAPTION>
+<TR><TD>
+<DIV ALIGN="CENTER">
+
+</DIV><IMG
+ WIDTH="865" HEIGHT="597" ALIGN="BOTTOM" BORDER="0"
+ SRC="./midi_config_window.png"
+ ALT="Image midi_config_window"></TD></TR>
+</TABLE>
+</DIV>
+
+<P>
+
+<H4><A NAME="SECTION00381020000000000000">
+Columns in the MIDI configuration ports list:</A>
+</H4>
+<DL>
+<DT><STRONG>GUI:</STRONG></DT>
+<DD>For synthesizer devices, indicates if a gui is available
+and if it is showing. Click to show.
+</DD>
+<DT><STRONG>I:</STRONG></DT>
+<DD>If present, the port can accept MIDI input. Click to
+enable or disable it.
+</DD>
+<DT><STRONG>O:</STRONG></DT>
+<DD>If present, the port can send MIDI output. Click to enable
+or disable it.
+</DD>
+<DT><STRONG>Instrument:</STRONG></DT>
+<DD>Selects the instrument to be used when MIDI is
+played through the port.
+</DD>
+<DT><STRONG>Device name:</STRONG></DT>
+<DD>Selects or creates a MIDI device assigned to the
+port. These can be Jack MIDI devices or ALSA MIDI devices (if ALSA is
+enabled), or soft synthesizers. Jack MIDI devices are created by selecting
+Create Jack Device from the Device name drop-down menu. Jack MIDI devices
+can be renamed as you wish by clicking the device name. Soft synthesizers
+are created by clicking in the soft synthesizer list and then Add
+Instance. Or you can simply create a new synthesizer track from the
+arranger track list, or even the mixer menus.
+</DD>
+<DT><STRONG>In and Out routes:</STRONG></DT>
+<DD>These are for Jack MIDI devices, they are
+the routes to and from available Jack MIDI ports. Jack may provide
+different alias names for these ports, you can select which alias
+is shown.
+</DD>
+<DT><STRONG>Default in channels:</STRONG></DT>
+<DD>Auto-connect these port channels to
+new midi or drum tracks.
+</DD>
+<DT><STRONG>Default out channel:</STRONG></DT>
+<DD>Auto-connect new midi or drum tracks
+to this channel on the port.
+</DD>
+<DT><STRONG>State:</STRONG></DT>
+<DD>Indicates the state of the port including any errors
+opening it.
+</DD>
+</DL>
+
+<P>
+
+<H2><A NAME="SECTION00382000000000000000">
+Global settings</A>
+</H2>
+
+<H3><A NAME="SECTION00382100000000000000">
+Audio settings</A>
+</H3>
+
+<H4><A NAME="SECTION00382110000000000000">
+Minimum control period</A>
+</H4>
+Plugins can usually process an arbitrarily small (or large) amount
+of samples. If some plugin control value changes continously, to provide
+ideal listening experience, MusE would need to call the plugin 44100
+times a second, asking for one single value at a time. With the minimum
+control period setting, the user can force MusE to ask the plugin for
+at least N values. Setting this value to 64 would in this situation
+make MusE call the plugin <!-- MATH
+ $689=\frac{44100}{64})$
+ -->
+<SPAN CLASS="MATH"><IMG
+ WIDTH="91" HEIGHT="35" ALIGN="MIDDLE" BORDER="0"
+ SRC="img1.png"
+ ALT="$689=\frac{44100}{64})$"></SPAN> times a second,
+asking for 64 values at a time. While doing this will reduce accuracy
+of control changes, it may also reduce CPU usage, because calling
+the plugin more often, requesting smaller chunks, is more expensive
+than calling it seldomly, requesting larger chunks.
+
+<H5><A NAME="SECTION00382111000000000000">
+Recommendation</A>
+</H5>
+If you have no performance problems, or if you want to do the final
+downmix of your project, set this to a low value. If you're experiencing
+performance problems, increasing this value might help.
+
+<P>
+
+<H1><A NAME="SECTION00400000000000000000"></A>
+<A NAME="apx_effects_rack"></A>
+<BR>
+Appendix
+</H1>
+<H1><A NAME="SECTION00410000000000000000">
+Understanding the effects rack</A>
+</H1>
+One must carefully consider how many audio inputs and outputs a plugin
+has, and how may channels the particular audio track has (1 mono or
+2 stereo), and how MusE uses the plugins in the rack.
+
+<P>
+MusE will try to internally create as many independent copies
+(instances) of a plugin as necessary, to satisfy the number of channels
+in the audio track.
+Basically it divides the number of track channels by the number of
+plugin audio inputs or outputs to determine how many copies to make.
+First it examines the number of plugin audio outputs, and if there are
+none, it will examine the number of audio inputs, and if there are
+none, it will simply use just one plugin copy.
+
+<P>
+For mono tracks with plugins having more than one audio input or
+output, MusE uses the first input or output and ignores the rest.
+
+<P>
+For stereo tracks:
+
+<P>
+<TABLE CELLPADDING=3 BORDER="1">
+<TR><TD ALIGN="CENTER">plugin inputs</TD>
+<TD ALIGN="CENTER">outputs</TD>
+<TD ALIGN="CENTER">copies</TD>
+<TD ALIGN="CENTER">track in route channels</TD>
+<TD ALIGN="CENTER">track out route channels</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">1 (L only)</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">0</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">0</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+<TR><TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">&gt;=2</TD>
+<TD ALIGN="CENTER">1</TD>
+<TD ALIGN="CENTER">2</TD>
+<TD ALIGN="CENTER">2</TD>
+</TR>
+</TABLE>
+
+<P>
+Notice that on a stereo track with a plugin having one audio input and
+two audio outputs, only the first track input route channel is used
+(left only).
+
+<P>
+These same rules apply to inter-plugin audio when more than one plugin
+is in the rack chain. Extra audio outputs of one plugin may be ignored
+by the next plugin if not used.
+
+<P>
+Currently specialized plugins with many inputs and/or outputs are not
+really useful in MusE.
+
+<P>
+Nor are so-called 'realtime' control plugins which use audio inputs
+and outputs for control signals.
+
+<P>
+Loud noise alert! Beware of using such plugins in an audio effects
+rack.
+
+<P>
+Example: Consider a stereo Audio Input track with these effect rack
+ LADSPA plugins:
+
+<P>
+
+<UL>
+<LI>comb_splitter Comb Splitter by Steve Harris
+</LI>
+<LI>tap_stereo_echo Tap Stereo Echo by Tom Szilagyi
+</LI>
+</UL>
+
+<P>
+The Comb Splitter has one audio input and two audio outputs.
+The Stereo Echo has two audio inputs and two audio outputs.
+
+<P>
+The stereo Audio Input track will therefore ignore its second
+input route connection. It will process the left input only,
+separating it into stereo with the Comb Splitter, passing the
+split stereo signal into the Stereo Echo, finally producing
+stereo output available at the Audio Input track's output routes.
+
+<P>
+One improvement would be not creating unused redundant plugin copies
+between plugins in stereo tracks.
+For example, for a plugin having one audio input and one audio output,
+feeding a plugin having one audio input and two audio outputs,
+the extra copy of the first plugin is redundant and not required,
+but currently it is created anyway.
+<BR><HR>
+
+</BODY>
+</HTML>
diff --git a/muse2/doc/html/single/documentation/main_window_add_track.png b/muse2/doc/html/single/documentation/main_window_add_track.png
new file mode 100644
index 00000000..7750ca7f
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_add_track.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/main_window_annotated.png b/muse2/doc/html/single/documentation/main_window_annotated.png
new file mode 100644
index 00000000..f8f7701f
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_annotated.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/main_window_with_arrangement.png b/muse2/doc/html/single/documentation/main_window_with_arrangement.png
new file mode 100644
index 00000000..8d391d9f
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_with_arrangement.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/main_window_with_automation.png b/muse2/doc/html/single/documentation/main_window_with_automation.png
new file mode 100644
index 00000000..3930c0da
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_with_automation.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/main_window_with_midi_automation.png b/muse2/doc/html/single/documentation/main_window_with_midi_automation.png
new file mode 100644
index 00000000..5357a6d3
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_with_midi_automation.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png b/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png
new file mode 100644
index 00000000..bedf6250
--- /dev/null
+++ b/muse2/doc/html/single/documentation/main_window_with_midi_editor_vam.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/midi_config_window.png b/muse2/doc/html/single/documentation/midi_config_window.png
new file mode 100644
index 00000000..f979ad34
--- /dev/null
+++ b/muse2/doc/html/single/documentation/midi_config_window.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/midi_routing_matrix.png b/muse2/doc/html/single/documentation/midi_routing_matrix.png
new file mode 100644
index 00000000..ac080a92
--- /dev/null
+++ b/muse2/doc/html/single/documentation/midi_routing_matrix.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/mixer.png b/muse2/doc/html/single/documentation/mixer.png
new file mode 100644
index 00000000..22d9f2b7
--- /dev/null
+++ b/muse2/doc/html/single/documentation/mixer.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/mixer_with_one_input.png b/muse2/doc/html/single/documentation/mixer_with_one_input.png
new file mode 100644
index 00000000..629328d7
--- /dev/null
+++ b/muse2/doc/html/single/documentation/mixer_with_one_input.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png b/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png
new file mode 100644
index 00000000..c6ad7b0c
--- /dev/null
+++ b/muse2/doc/html/single/documentation/mixer_with_one_input_buttons.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/muse2.png b/muse2/doc/html/single/documentation/muse2.png
new file mode 100644
index 00000000..84a28d8a
--- /dev/null
+++ b/muse2/doc/html/single/documentation/muse2.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/no_audio.png b/muse2/doc/html/single/documentation/no_audio.png
new file mode 100644
index 00000000..1e62245c
--- /dev/null
+++ b/muse2/doc/html/single/documentation/no_audio.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/output_routing.png b/muse2/doc/html/single/documentation/output_routing.png
new file mode 100644
index 00000000..08af67fa
--- /dev/null
+++ b/muse2/doc/html/single/documentation/output_routing.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/project_my_first_song.png b/muse2/doc/html/single/documentation/project_my_first_song.png
new file mode 100644
index 00000000..488faad2
--- /dev/null
+++ b/muse2/doc/html/single/documentation/project_my_first_song.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/soloing_window.png b/muse2/doc/html/single/documentation/soloing_window.png
new file mode 100644
index 00000000..72b72d63
--- /dev/null
+++ b/muse2/doc/html/single/documentation/soloing_window.png
Binary files differ
diff --git a/muse2/doc/html/single/documentation/vam_synth.png b/muse2/doc/html/single/documentation/vam_synth.png
new file mode 100644
index 00000000..f2e3bad4
--- /dev/null
+++ b/muse2/doc/html/single/documentation/vam_synth.png
Binary files differ