<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
<!ENTITY % version-entities SYSTEM "./version.entities">
%version-entities;
<!ENTITY app "Buzztard">
<!ENTITY rrar "&#8594;">
]>
<!--
  (Do not remove this comment block.)
  Maintained by Buzztard Developer team <buzztard-devel@lists.sourceforge.net>
  Template version: 0.4
  Template last modified: Sep 20, 2008
-->
<!-- ===========Document Header ======================== -->
<article id="index" lang="en">
<!--
  please do not change the id: for translations, change lang to
  appropriate code
-->
<articleinfo>
  <title>&app; manual (&appversion;)</title>

  <copyright>
    <year>&rel_year;</year>
    <holder>Stefan Kost</holder>
  </copyright>

  <!-- translators: uncomment this:
  <copyright>
    <year>2004</year>
    <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
  </copyright>
  -->

  <publisher>
    <publishername>Buzztard Developer Team</publishername>
  </publisher>

  &legal;

  <authorgroup>
    <author>
      <firstname>Stefan</firstname>
      <surname>Kost</surname>
      <affiliation>
        <orgname>Buzztard Developer team</orgname>
        <address> <email>buzztard-devel@lists.sourceforge.net</email></address>
      </affiliation>
    </author>
  </authorgroup>

  <revhistory>
    <revision>
      <revnumber>&app; manual (&appversion;)</revnumber>
      <date>&rel_date;</date>
      <revdescription>
        <para role="author">
          Buzztard Developer team
          <email>buzztard-devel@lists.sourceforge.net</email>
        </para>
      </revdescription>
    </revision>
  </revhistory>

  <releaseinfo>This manual describes version &appversion; of &app;.</releaseinfo>
  <legalnotice>
    <title>Feedback</title>
    <para>
      To report a bug or make a suggestion regarding the &app; application
      or this manual, see the Buzztard website at
      <ulink url="http://www.buzztard.org">http://www.buzztard.org</ulink>.
    </para>
    <!-- Translators may also add feedback address for translations here -->
  </legalnotice>
</articleinfo>

<indexterm><primary>&app;</primary></indexterm>
<indexterm><primary>buzztard</primary></indexterm>

<sect1 id="bt-edit-introduction">
  <title>Introduction</title>
  <para>
    <application>&app;</application> is a music composer for the GNOME desktop.
    It partly follows the concepts of programs like SoundTracker, FastTracker
    and the like, but is based on a modern media engine (<ulink url="http://gstreamer.freedesktop.org">gstreamer</ulink>).
    This engine supports virtual sound generator and effects in the form of
    numerous plugins.
  </para>
  <para>
    During the next section we describe the concept of the <application>&app;</application>
    and also compare it to similar applications. If you are familiar with some
    of those, the retrospective sections should help to understand the way
    <application>&app;</application> works.
  </para>
  <para>
    The main chapter of the help system is separated into these sections:
    <itemizedlist>
      <listitem><para><link linkend="bt-edit-tutorial" endterm="bt-edit-tutorial.title"/></para></listitem>
      <listitem><para><link linkend="bt-edit-main" endterm="bt-edit-main.title"/></para></listitem>
      <listitem><para><link linkend="bt-edit-prefs" endterm="bt-edit-prefs.title"/></para></listitem>
      <listitem><para><link linkend="bt-edit-reference" endterm="bt-edit-reference.title"/></para></listitem>
    </itemizedlist>
    The <link linkend="bt-edit-tutorial" endterm="bt-edit-tutorial.title"/>
    chapter is introducing the <application>&app;</application> in a tutorial
    style. The later chapter have reference character, describing each view and
    dialog.
  </para>

  <sect2 id="bt-edit-intro-concept">
    <title id="bt-edit-intro-concept.title">The concept behind <application>&app;</application></title>
    <para>
      &app; follows the concept of tracker applications. This is quite different
      when compared to other music composers.
      The tracker concept is more focused on the event data. There is no piano roll (at least not now).
      Instead song fragments (patterns) are shown in a tabular way.
    </para>
    <para>
      Important design criteria for <application>&app;</application> are:
      <itemizedlist>
        <listitem><para>fast and system compliant ui</para></listitem>
        <listitem><para>keyboard shortcuts for everything</para></listitem>
        <listitem><para>total recall</para></listitem>
      </itemizedlist>
    </para>
  </sect2>

  <sect2 id="bt-edit-intro-buzz">
    <title id="bt-edit-intro-buzz.title">Comparison to <application>Buzz</application></title>
    <para>
      &app; is inspired of lot by Buzz. Some features are still missing and some
      things already work better.  
      The UI in is not a 1-to-1 copy, for Buzz users the UI will still look familiar.
    </para>
    <para>
      &app;:
      <itemizedlist>
        <listitem><para>can render songs to wav/mp3,ogg-vorbis/... including song-meta-data (tags) and multi track exports</para></listitem>
        <listitem><para>uses color-codes for machine-types through its ui</para></listitem>
        <listitem><para>generates cleaner machine UIs (collapsing parts, more distinct widgets)</para></listitem>
        <listitem><para>has a scalable machine view</para></listitem>
        <listitem><para>can use beats other that 4/4</para></listitem>
        <listitem><para>shows volume and pan on wire</para></listitem>
        <listitem><para>does balance on stereo wires</para></listitem>
        <listitem><para>has analyzers and mixing controls in sequence view</para></listitem>
        <listitem><para>can have multiple wire-analyzers open</para></listitem>
        <listitem><para>can be remote controlled with UPnP a/v software</para></listitem>
        <listitem><para>supports HID input devices for effect control (e.g. joysticks)</para></listitem>
      </itemizedlist>
      <itemizedlist>
        <listitem><para>has only marginal MIDI support</para></listitem>
        <listitem><para>has no pattern recording yet</para></listitem>
        <listitem><para>does not support machine templates</para></listitem>
      </itemizedlist>
    </para>
  </sect2>

  <sect2 id="bt-edit-intro-tracker">
    <title id="bt-edit-intro-tracker.title">Comparison to Tracker applications</title>
    <para>
      While &app; has much in common with tracker applications, there are some notable differences.
    </para>
    <para>
      <itemizedlist>
        <listitem><para>trackers are sample based, buzztard also uses software synthesizers</para></listitem>
        <listitem><para>trackers have a fixed track concept, buzztard uses tracks per machine (source/effect/sink)</para></listitem>
        <listitem><para>trackers do not have the virtual machine routing</para></listitem>
      </itemizedlist>
    </para>
  </sect2>
</sect1>

<sect1 id="bt-edit-tutorial">
  <title id="bt-edit-tutorial.title">Getting started</title>
  <para>
    The below tutorials will introduce <application>&app;</application> by going though a few
	examples. Each example will introduce new features.
  </para>
  
  <sect2 id="bt-edit-tutorial-lifefx">
    <title id="bt-edit-tutorial-lifefx.title">Live Effects</title>
    <para>
      This tutorial demonstrates how to use <application>&app;</application> as
      a toy for live audio effects.
    </para>
    <para>
      Start the graphical editor 'buzztard-edit'. The first tab shows the
      <link linkend="bt-edit-main-view-machines">machine view</link>.
      Here you can create elements (sound generators and effects) and link them together.
      To create an element, right click on the background and select an element
      from the context menu. For the example choose alsasrc.
    </para>
    <note>
      <para>
        Please note, that not all the elements in the list will work perfectly in
        a live situation right now. Also useing livesrc and normal source does
        not work reliable right now. This will be address in a future versions
        of buzztard and gstreamer.
      </para>
    </note>
    <para>
      In your sound card mixer you should enable recording from the microphone or
      provide some music on line-in. Next add audiodelay and equalizer-10band elements.
      Now wire them together by pointing on the source element (alsasrc) and
      dragging a wire to the target (audiodelay), while holding the shift-key pressed.
      The wire will become green when the mouse is over a valid target.
      Releasing the mouse creates the link. Repeat the procedure for audiodelay &rrar; equalizer
      and equalizer &rrar; master. The wires have a pointer shape in the middle,
      showing the direction. A left click onto it allows to change the volume of the link,
      a shift left-click the stereo panorama or balance and a right click shows a
      context menu for disconnecting the elements and for showing an "analyzer dialog".
      Open that one for the link between equalizer and master.
      Finally double click the equalizer and the audiodelay to open their
      <link linkend="bt-edit-dialog-machine-properties">real-time settings windows</link>.
      Now you should see something like this:
    </para>
    <para>
      (FIXME: need screenshot)
    </para>
    <para>
      Now lets give it a try. Activate the loop in the <link linkend="bt-edit-main-toolbar">toolbar</link>
      and press play.
      Now you can tweak the settings of the effects while making some noise.
      The parameter-changes will be effective right away. In the "analyzer window"
      you can see the frequency spectrum of the sound and the volume level.
    </para>
  </sect2>

  <sect2 id="bt-edit-tutorial-synth">
    <title id="bt-edit-tutorial-synth.title">Synthesized Melody Sequence</title>
    <para>
      This tutorial will introduce the sequencer functionality and explain
      patterns.
    </para>
    <para>
      Start the graphical editor 'buzztard-edit'. On the first tab - the
      <link linkend="bt-edit-main-view-machines">machine view</link> - add one
      simsyn. This is a very basic synthesizer. Also add an audiodelay
      and link simsyn &rrar; audiodelay &rrar; master.
      Now switch to the <link linkend="bt-edit-main-view-sequence">sequence view</link>.
      Buzztard has automatically added a track for the
      simsyn. Also the song has a default length of 64 ticks (the time axis goes from top to bottom).
      The track will take patterns. Patterns are the actual building blocks
      of the score. Patterns are a block of control events, like triggering a note
      or changing a machine parameter. The right side shows existing pattern for
      the machine the cursor is in. Simsyn has one called '00'.
      Press '0' four times to fill the sequence track with this pattern. Buzztard
      will repeat the events there 4 times and stop. If you press play now, you won't hear
      anything yet, as we have not recorded any events into the pattern.
      Lets switch to the <link linkend="bt-edit-main-view-patterns">pattern editor</link>.
      This can be done, by just pressing "Enter" in addition to using the tabs.
    </para>
    <para>
      The <link linkend="bt-edit-main-view-patterns">pattern editor</link> shows
      a grid. Again the time goes from top to bottom.
      From left to right the editor shows parameter groups. This simple synthesizer
      has just one. More complex ones have a block with global parameters and one for each voice.
      Each column shows some info in the status bar when the cursor is in there.
      The first column is for entering notes.
      It works like it always worked in trackers - by using the computer keyboard.
      The two rows above the space key form one octave and the two rows above one octave above.
      The lower row is for while keys and the upper row for black keys, y/z &rrar; c, s &rrar; c#,
      x %rrar; d, d &rrar; d#, c &rrar; e, f unused, v &rrar; f and so on.
      Press Ctrl-2 to set cursor stepping to go down 2 rows on each edit and enter "yqy3ywyr".
      If you press play now, you should hear a simple melody.
      (FIXME: patterns + sequence view)
    </para>
  </sect2>
  
  <sect2 id="bt-edit-tutorial-tracker">
    <title id="bt-edit-tutorial-tracker.title">Sampled Sounds</title>
    <para>
      This tutorial explains how to work with sampled sound.
    </para>
    <para>
      (FIXME: wave-table view)
    </para>
  </sect2>
</sect1>

<sect1 id="bt-edit-main">
  <title id="bt-edit-main.title">The main window</title>
  <para>
    After starting the <application>&app; Music Editor</application>, you will see the main window.
    If you start the application without specifying an initial file
    (as a parameter on the command line or by double clicking a song in <application>Nautilus</application>),
    the window will look like this.
  </para>

  <figure id="bt-edit-main-window-fig">
    <title>&app; window</title>
    <screenshot>
      <mediaobject>
        <imageobject>
          <imagedata fileref="figures/main-window.png" format="PNG" contentwidth="65%"/>
        </imageobject>
        <textobject>
          <phrase>Shows &app; main window with menu bar, toolbars, editor views and status area.</phrase>
        </textobject>
      </mediaobject>
    </screenshot>
  </figure>

  <para>
    On the very top of the window is <link linkend="bt-edit-main-menu">the menu bar</link>.
    Below one finds <link linkend="bt-edit-main-toolbar">the toolbar</link>.
    And below again are tabs to switch between various <link linkend="bt-edit-main-views">views</link>.
	Each view is for editing certain aspects of the song.
    On the bottom is a <link linkend="bt-edit-main-statusbar">status bar</link>.
  </para>

  <para>
    Many parts in the UI show tooltips with brief explanations. Hover the mouse
    pointer over the region and wait a moment.
  </para>

  <para>
    The UI uses context menus in several places. Press right mouse button to get
    the menu. The menu offer crucial functionally not available elsewhere right
    now.
  </para>

  <sect2 id="bt-edit-main-menu">
    <title id="bt-edit-main-menu.title">The menu bar</title>
    <indexterm><primary>main menu</primary></indexterm>
    <para>
      The menu bar gives you access to file operations, standard editing function,
      settings and help.
    </para>

    <para>
      The <menuchoice><guimenu>File</guimenu></menuchoice> menu allows to start a new song, load and save
      songs, as well as end the program. Songs need other resources in order to
      be played. These are the sound-generators and effects that are used and
      eventually digital audio-samples. When loading a song &app; checks if all
      needed resources are available and if not lists them in one dialog
      (FIXME: document and link).
    </para>
    <para>
      The <menuchoice><guimenu>Edit</guimenu></menuchoice> menu contains
      clipboard functions and invocation of 
      <link linkend="bt-edit-prefs" endterm="bt-edit-prefs.title"/>.
      <note><title>Limitations</title>
        <para>
          Cut/Copy/Paste functionality in the edit menu is still not implemented.
        </para>
      </note>
    </para>
    <para>
      The <menuchoice><guimenu>View</guimenu></menuchoice> menu offers
      customization for the shown UI elements. It also contains shortcuts to
      the different song-views.
    </para>
  </sect2>

  <sect2 id="bt-edit-main-toolbar">
    <title id="bt-edit-main-toolbar.title">The tool bar</title>
    <para>
      In contrast to <link linkend="bt-edit-main">the menu bar</link> the tool
      bar only shows common operations as shortcuts.
      On the right end the toolbar shows a volume-meter for each audio-channel
      and a volume control.
    </para>
  </sect2>

  <sect2 id="bt-edit-main-views">
    <title id="bt-edit-main-views.title">The song views</title>
    <para>
      Each part of a song is represented by a specialized views which one can
      switch to with the tabs.
      Next we briefly introduce each tab, where in the next sub section they will
      be described in detail.
    </para>

    <sect3 id="bt-edit-main-view-machines">
      <title id="bt-edit-main-view-machines.title">The machine view of a song</title>
      <para>
        A song utilizes sound generators, effects and sinks - all called machines.
        A new machine can be added from the context menu that appear on a right
        click over the page area.
        Machines can be moved around by grabbing them with the mouse and dragging
        them around.
        To connect machines, move pointer over the source, press shift+left mouse-button
        and drag the wire to the target machine. The wire turns green, if the
        connect can be made. Connected machines are shown in bright color and
        disconnected one in a desaturated style.
      </para>
      <figure id="bt-edit-page-machine-view-fig">
        <title>Machine view</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/page-machine-view.png" format="PNG" contentwidth="65%"/>
            </imageobject>
            <textobject>
              <phrase>The songs machine view.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <!--para>
        The machines have a state switch in the upper left corner. You can click
        this to set it to working state. Additionally holding Ctrl, Win (Mod) or
        Ctrl+Win keys sets the machine to mute, solo or bypass.
        Not all machines support all these states.
      </para-->
      <para>
        Wires have volume and panorama control support. A left-click on the
        pointer-shape in the middle of the wire open a volume popup. A click
        outside closes it again. Shift+left-click opens the panorama control. 
      </para>
      <para>
        Machines and wires have context menus. The menu for the wire can be
        accessed by right clicking over the pointer shape in the middle. Not yet
        connected elements can be removed immediately (without any dialogs).
      </para>
      <para>
        A double click on a machine brings up the <link linkend="bt-edit-dialog-machine-properties" endterm="bt-edit-dialog-machine-properties.title"/>.
      </para>
    </sect3>

    <sect3 id="bt-edit-main-view-patterns">
      <title id="bt-edit-main-view-patterns.title">The pattern view of a song</title>
      <para>
        Patterns are the building blocks of a song. They are short snippets of
        events for one machine, that can be reused in the sequence. The vertical
        axis shows ticks (time) and the horizontal axis has the parameters.
        Parameters are organized in groups. There is a group for global settings
        and groups for each voice if the machine is polyphonic.
      </para>
      <figure id="bt-edit-page-pattern-view-fig">
        <title>Pattern view</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/page-pattern-view.png" format="PNG" contentwidth="65%"/>
            </imageobject>
            <textobject>
              <phrase>The songs pattern view.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        In the page toolbar one can select the machine and the pattern for the machine.
        Pattern names in gray color indicated that the pattern is not used in the
        sequence (thus save to be removed or changed). One can also select the
        base octave for entering notes via keyboard and the sample that should
        be used for wave-table based machines.
      </para>
      <para>
        A context menu in the pattern area allows to create new patterns and
        modify existing ones. Unused patterns can be removed immediately
        (without any dialogs). If the machine is polyphonic, one can add or
        remove voices by using the context menu.
      </para>
      <para>
        To switch to the sequence editor press <keycap>Enter</keycap> while the
        pattern editor has focus.
      </para>
      <para>
        (FIXME: write about keyboard short cuts)
      </para>
    </sect3>

    <sect3 id="bt-edit-main-view-sequence">
      <title id="bt-edit-main-view-sequence.title">The sequence view of a song</title>
      <para>
        A song consists of several tracks (columns), where in each track patterns
        are played. The rows are time slots.
      </para>
      <figure id="bt-edit-page-sequence-view-fig">
        <title>Sequence view</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/page-sequence-view.png" format="PNG" contentwidth="65%"/>
            </imageobject>
            <textobject>
              <phrase>The songs sequence view.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        The sequence header for each track shows the name of the machine, mute,
        solo. bypass buttons (depending whether it is a generator, effect or
        sink) and a level-meter.
      </para>
      <para>
        One can navigate around using cursor keys. When changing tracks, the
        list of patterns on the right is updated to show the patterns for the
        current machine. Again gray pattern label color indicates that the
        pattern is not in use.
        Patterns can be entered into tracks by pressing the associated key
        (shown left to the pattern name in the list).
        To switch to the pattern editor with the pattern the cursor is over selected,
        press <keycap>Enter</keycap>.
      </para>
      <para>
        To set play position click with left-mouse button in the first column at the
        desired time location. To modify the loop start/end instead hold down
        the <keycap>Ctrl</keycap> or <keycap>Win</keycap> (<keycap>Mod</keycap>)
        key while clicking.
      </para>
      <para>
        To expand the sequence, scroll down with the cursor and press
        <keycombo><keycap>Ctrl</keycap><keycap>e</keycap></keycombo> to
        set the end-line. If the cursor is above the end-line, pressing
        <keycombo><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>
        will set the loop-end marker. When the cursor is on the loop-end marker
        <keycombo><keycap>Ctrl</keycap><keycap>e</keycap></keycombo> will
        shorten the sequence. To set the loop-begin marker press
        <keycombo><keycap>Ctrl</keycap><keycap>b</keycap></keycombo>.
      </para>
      <para>
        It is also possible to insert and delete full rows or just entries in a
        track. The shortcuts for this are 
        <keycombo><keycap>Ctrl</keycap><keycap>i</keycap></keycombo> to
        insert a full row and 
        <keycombo><keycap>Ctrl</keycap><keycap>d</keycap></keycombo> to
        remove a full row. To only insert or remove inside the current track
        hold the <keycap>Shift</keycap> key in addition.
      </para>
      <para>
        (FIXME: special-patterns = {mute, break, solo, bypass})
      </para>
    </sect3>

    <sect3 id="bt-edit-main-view-waves">
      <title id="bt-edit-main-view-waves.title">The wavetable view of a song</title>
      <para>
        The wavetable hold sampled audio snippet that can be used e.g. from
        tracker sources.
      </para>
      <figure id="bt-edit-page-wavetable-view-fig">
        <title>Wave-table view</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/page-wavetable-view.png" format="PNG" contentwidth="65%"/>
            </imageobject>
            <textobject>
              <phrase>The songs wave-table view.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        The left column is the wavetable. Samples are loaded by double clicking them 
        in the right side file-browser. The toolbar above the browser allows to
        pre-listen before loading. Waves in the table can also be played, renamed
        and removed. 
      </para>
      <para>
        Each wavetable entry can have multiple wave levels, which are shown below
        the wavetable for the selected wave. Some of the details are editable.
        Right to the wave level list is a waveform preview widget. It shows loop
        markers and a playback position indicator.
      </para>
    </sect3>

    <sect3 id="bt-edit-main-view-info">
      <title id="bt-edit-main-view-info.title">The information view of a song</title>
      <para>
        This page allows you to change song parameters, such as speed and
        timing resolutions and to enter information about the song.
        The meta data will be used for the tags when creating a final mix-down.
      </para>
      <figure id="bt-edit-page-info-view-fig">
        <title>Info view</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/page-info-view.png" format="PNG" contentwidth="65%"/>
            </imageobject>
            <textobject>
              <phrase>The songs info view.</phrase>
            </textobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>

  </sect2>

  <sect2 id="bt-edit-main-statusbar">
    <title id="bt-edit-main-statusbar.title">The status bar</title>
    <para>
      The status bar that is located at the bottom of the window.
      On the left side it shows the status of longer operations like saving and
      loading with a text message. It also shows some extra detail in some song
      <link linkend="bt-edit-main-views">views</link>.
      On the right side, it displays the length of the song, the loop range, the
      playback position and the current CPU usage.
    </para>
  </sect2>

</sect1>

<sect1 id="bt-edit-dialogs">
  <title id="bt-edit-dialogs.title">Dialog windows</title>
  <indexterm><primary>main menu</primary></indexterm>

  <para>
    There are various dialogs that are invoked from the main-menu or from
    context menus.
  </para>

  <sect2 id="bt-edit-prefs">
    <title id="bt-edit-prefs.title">The settings window</title>
    <para>
      This window contains all settings for the <application>&app;</application>
      application. All settings are grouped into categories that can be chosen from
      the list on the left side.
    </para>
  
    <figure id="bt-edit-settings-fig">
      <title>Settings dialog</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/settings-audio.png" format="PNG" contentwidth="65%"/>
          </imageobject>
        </mediaobject>
      </screenshot>
    </figure>
  
    <sect3 id="bt-edit-prefs-audio">
      <title id="bt-edit-prefs-audio.title">Audio device settings</title>
  
      <para>
        Select the audiosink to use. It will be changed immediately, except when a
        song is playing (will be switched after stopping).
      </para>
      <figure id="bt-edit-settings-audio-fig">
        <title>Audio device settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-audio.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
      <para>
        All offered audio sinks should be fine for song-playback. One area where
        they differ is latency. Low latency is important when playing machines
        live - that is playing notes in the <link linkend="bt-edit-main-view-patterns">pattern editor</link>
        or changing parameters in the <link linkend="bt-edit-dialog-machine-properties">machine window</link>.
        The lower the latency, the more immediate the changes are. Jack is known
        for being able to achieve a low latency, but also a well configured alsa
        or pulseaudio can achieve a reasonable latency.
      </para>
      <para>
        (FIXME: write more)
      </para>
    </sect3>
  
    <sect3 id="bt-edit-prefs-playback-controller">
      <title id="bt-edit-prefs-playback-controller.title">Playback controller settings</title>
  
      <para>
        UPnP A/V remote control via Coherence.
        (FIXME: explain)
      </para>
      <figure id="bt-edit-settings-pc-fig">
        <title>Playback controller settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-pc.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>
  
    <sect3 id="bt-edit-prefs-interaction-controller">
      <title id="bt-edit-prefs-interaction-controller.title">Interaction controller settings</title>
  
      <para>
        Interactive controller for machine parameters.
        (FIXME: no settings yet)
      </para>
      <figure id="bt-edit-settings-ic-fig">
        <title>Interaction controller settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-ic.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>
  
    <sect3 id="bt-edit-prefs-colors">
      <title id="bt-edit-prefs-colors.title">Color settings</title>
  
      <para>
        (FIXME:)
      </para>
      <figure id="bt-edit-settings-colors-fig">
        <title>Colors settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-colors.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>
  
    <sect3 id="bt-edit-prefs-shortcuts">
      <title id="bt-edit-prefs-shortcuts.title">Shortcut settings</title>
  
      <para>
        (FIXME:)
      </para>
      <figure id="bt-edit-settings-shortcuts-fig">
        <title>Shortcut settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-shortcuts.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>
  
    <sect3 id="bt-edit-prefs-directories">
      <title id="bt-edit-prefs-directories.title">Directory settings</title>
  
      <para>
        Configure default directories used for various file types.
      </para>
      <figure id="bt-edit-settings-directories-fig">
        <title>Directory settings</title>
        <screenshot>
          <mediaobject>
            <imageobject>
              <imagedata fileref="figures/settings-directories.png" format="PNG" contentwidth="65%"/>
            </imageobject>
          </mediaobject>
        </screenshot>
      </figure>
    </sect3>
  </sect2>
<!--
@todo: more dialogs
  machine preferences
  machine rename
  preset properties(name and comment)
  wire analysis
  pattern properties

  about dialog
  missing machines and waves
-->
  <sect2 id="bt-edit-dialog-machine-properties">
    <title id="bt-edit-dialog-machine-properties.title">Machine properties dialog</title>
    <para>
      The main area of the dialog is covered by the parameters of the machine.   
      These parameter control the generated audio or the effects. If parameters
      are controlled by <link linkend="bt-edit-main-view-patterns">patterns</link>,
      the ui will reflect the changes as the music plays.
    </para>
    <para>
      Parameters are grouped. There is a group from global parameters and one
      for each voice (for polyphonic machines). Effects and the master also have
      a group for each input allowing to change volume and panorama. These are
      the same parameters that can be changed in the wire in the
      <link linkend="bt-edit-main-view-machines">machine view</link>.
    </para>
    <para>
      Each parameter has a context menu. The menu allows to bind the parameter
      to a hardware controller and unbind it. If a parameter is bound, the
      changes on the hardware controller will effect the parameter. &app;
      supports hid (e.g joysticks, wiimotes, harddisk accelerometers) and midi
      devices.
    </para>
    <para>
      At the top of the dialog is a small toolbar. One button allows to show or
      hide the right side preset pane. Most machines support presets. Presets
      are a collection of parameter sets.
    </para>
    <figure id="bt-edit-dialog-machine-properties-fig">
      <title>Info view</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/machine-properties.png" format="PNG" contentwidth="65%"/>
          </imageobject>
          <textobject>
            <phrase>Machine properties dialog.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
  </sect2>
  <sect2 id="bt-edit-dialog-machine-preferences">
    <title id="bt-edit-dialog-machine-preferences.title">Machine preferences dialog</title>
    <para>
      Machine preferences are settings that are configured for the whole song.
      These settings can be changed over time.
    </para>
    <note><title>Warning</title>
      <para>
        Right now this contains also some low-level settings, where changing
        them could break playback.
      </para>
    </note>
    <figure id="bt-edit-dialog-machine-preferences-fig">
      <title>Info view</title>
      <screenshot>
        <mediaobject>
          <imageobject>
            <imagedata fileref="figures/machine-preferences.png" format="PNG" contentwidth="65%"/>
          </imageobject>
          <textobject>
            <phrase>Machine preferences dialog.</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </figure>
  </sect2>    
</sect1>

<sect1 id="bt-edit-reference">
  <title id="bt-edit-reference.title">Reference</title>
  <para>
    This chapter contains a few useful lists for reference.
  </para>

  <sect2 id="bt-edit-reference-shortcuts">
    <title id="bt-edit-reference-shortcuts.title">Keyboard shortcuts</title>

    <para>
      Currently keyboard shortcuts are listed on
      <ulink url="http://www.buzztard.org/index.php/Keyboard_shortcuts">the buzztard wiki</ulink>.
      (FIXME:)
    </para>
  </sect2>

</sect1>

<index id="bt-edit-keyword-index">
  <title id="bt-edit-keyword-index.title">Index</title>
</index>

</article>
