<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter
[
<!ENTITY ags "Advanced Gtk+ Sequencer">
<!ENTITY images "images">
]>

<!-- Copyright (C) 2005-2018 Jo\u00EBl Kr\u00E4hemann -->
<!-- Permission is granted to copy, distribute and/or modify this document -->
<!-- under the terms of the GNU Free Documentation License, Version 1.3 -->
<!-- or any later version published by the Free Software Foundation; -->
<!-- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. -->
<!-- A copy of the license is included in the section entitled "GNU -->
<!-- Free Documentation License". -->

<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" xml:lang="en">
  <title>The menubar</title>
  <para>
    Within the menubar you may do basic tasks like open/close files. In this section we cover
    briefly the the different entries. The menus have mnemonics e.g. press ALT and F key in order
    to open File menu.
  </para>

  <sect1>
    <title>File</title>
    <para>
      The file menu lets you do maintenance related to files or quit application. Note there was a simple
      XML file format introduced in 0.7.x to speed up things. The advanced file format needs optimization
      work to fulfill. The file format can be modified by configuration file located in your home directory
      $(HOME)/.gsequencer/ags.conf. The simple file interface is defaulted and can be altered by section
      generic and simple-file key set to false.
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<para>
	  Open - open an &ags; XML file. Uses per configuration the simple XML Input/Ouput interface.
	</para>
      </listitem>
      <listitem>
	<para>
	  Save - save your current work. Uses per configuration the simple XML Input/Ouput interface.
	</para>
      </listitem>
      <listitem>
	<para>
	  Save as - save your current work as a different filename. Uses per configuration the simple
	  XML Input/Ouput interface.
	</para>
      </listitem>
      <listitem>
	<para>
	  Export - export to PCM audio file.
	</para>
      </listitem>
      <listitem>
	<para>
	  Quit - leave &ags;.
	</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>Open file</title>
      <mediaobject>
	<imageobject>
	  <imagedata width="100%" scalefit="1" fileref="../&images;/ags_file_open_dialog.png" format="PNG" />
	</imageobject>
	<caption>
	  <para>
	    The file open screenshot
	  </para>
	</caption>
      </mediaobject>
      <para>
	Open files using dialog window.
      </para>
    </sect2>

    <sect2>
      <title>Export to PCM audio file</title>
      <mediaobject>
	<imageobject>
	  <imagedata width="100%" scalefit="1" fileref="../&images;/ags_export_window.png" format="PNG" />
	</imageobject>
	<caption>
	  <para>
	    The export window screenshot
	  </para>
	</caption>
      </mediaobject>
      <para>
	This shows you the export dialog. Exclude sequencers affect mainly AgsDrum and AgsMatrix pattern sequencers
	to be started to output. You may select filename to export to and duration of the exported track. BPM adjustment
	is take from the navigation. Basically &ags; exports what you hear of the speakers.
      </para>
      <para>
	With the export toggle button you can start exporting to PCM audio file or stop it at an arbitrary time.
      </para>
    </sect2>
  </sect1>

  <sect1>
    <title>Edit</title>
    <para>
      The edit menu lets you add audio machines of the related submenu, open automation window or preferences dialog.
    </para>

    <itemizedlist mark="bullet">
      <listitem>
	<para>
	  Add - select of different machines. You might want to add the bridged machines of plugins like LADSPA, DSSI or
	  Lv2. Instrument plugins are available within notation editor.
	</para>

	<itemizedlist mark="bullet">
	  <listitem>
	    <para>
	      Panel - acts as your default sink.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Mixer - enables you to bundle your different output engines.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Spectrometer - enables you to visualize played frequency using FFTW3.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Equalizer - enables you to adjust 10 band equalizer.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Drum - is used to do pattern editing using PCM audio files. 
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Matrix - is used to pattern editing, intended to be linked against Synth.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Synth - is a software synthesizer supporting variable oscillator count. Use with Matrix.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      FM Synth - is a frequency modulation software synthesizer supporting variable oscillator count.
	      Use with Matrix.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Syncsynth - is a software synthesizer supporting variable oscillator count. Use with notation
	      editor.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      FM Syncsynth - is a frequency modulation software synthesizer supporting variable oscillator count.
	      Use with notation editor.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Hybrid Synth - is a software synthesizer supporting 2 oscillators with relative phase modulation.
	      Use with notation editor.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Hybrid FM Synth - is a frequency modulation software synthesizer supporting 3 oscillators.
	      Use with notation editor.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      FFPlayer - may be used to open Soundfont2 audio file container format in order to do
	      notation.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      SF2 Synth - may be used to open Soundfont2 audio file container format in order to do
	      notation. Computation just-in-time.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Sampler - may be used to open SFZ audio file container format in order to do
	      notation.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      SFZ Synth - may be used to open SFZ audio file container format in order to do
	      notation. Computation just-in-time.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Audiorec - can be used to edit wave form or capture audio from your microphone
	    </para>
	  </listitem>
	</itemizedlist>
	
      </listitem>
      <listitem>
	<para>
	  Preferences - open preferences dialog.
	</para>
      </listitem>
    </itemizedlist>

    <sect2>
      <title>Preferences dialog</title>
      <para>
	Within preferences dialog you may choose between different topics. For each one one tab. The configuration
	is applied in place after click Apply or OK. There is no need to restart the application.
      </para>

      <sect3>
	<title>Generic</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_generic_preferences.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The preferences dialog screenshot - generic tab
	    </para>
	  </caption>
	</mediaobject>

	<para>
	  The autosave thread option enables auto-saving to $HOME/.gsequencer directory. Segmentation is
	  used as a delay factor, you can do tactation with it.
	</para>
      </sect3>

      <sect3>
	<title>Audio</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_audio_preferences.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The preferences dialog screenshot - audio tab
	    </para>
	  </caption>
	</mediaobject>
	<para>
	  Sound card is your physical devices to do playback.
	</para>
	<para>
	  Audio channels specifies the audio channels to allocate for output device.
	</para>
	<para>
	  Samplerate affects the entire project. Your audio files have to be at very same rate further
	  your device has to support the given rate. Like buffer size this affects the thread&apos;s related to
	  audio processing their frequencies. Note a too low frequency may cause unexpected behavior like
	  no proper velocity.
	</para>
	<para>
	  Buffer size is used for all audio buffers. Your soundcard has to support the passed buffer size.
	  This preference affects thread&apos;s frequencies.
	</para>
	<para>
	  Format determines the storage size of one frame. All available formats are signed integers. The
	  following sizes in bits are available: 8, 16, 24, 32 and 64. Your hardware has a need to support
	  the format in order to get sounds.
	</para>
      </sect3>

      <sect3>
	<title>MIDI</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_midi_preferences.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The preferences dialog screenshot - midi tab
	    </para>
	  </caption>
	</mediaobject>
	<para>
	  You can add MIDI sequencers to the configured project. These are intended to connect by the MIDI
	  dialog, later.
	</para>
	<para>
	  There is a combo box availabe to choose your backend like ALSA, OSS or JACK.
	</para>
	<para>
	  The second combo box lets you choose the device. The JACK backend allows you to add MIDI ports.
	</para>
      </sect3>

      <sect3>
	<title>Performance</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_performance_preferences.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The preferences dialog screenshot - performance tab
	    </para>
	  </caption>
	</mediaobject>
	<para>
	  Auto-sense on stream is required for certain plugins and recalls but may cause additional performance
	  losses.
	</para>
	<para>
	  The maximum precision of threads allows you to fine tune performance. A higher frequency allows you
	  to use smaller buffer size and a higher samplerate. But causes a higher synchronization over-head.
	</para>
      </sect3>

    </sect2>
  </sect1>

  <sect1>
    <title>MIDI</title>
    <para>
      The MIDI sub-menu provides functionality related to MIDI like the import or export wizards.
    </para>
    
    <sect2>
      <title>The MIDI import wizard</title>
      <para>
	The MIDI import wizard allows you to import Standard MIDI Files. You might choose
	the machine which will be added after import. The notation is available within the
	pattern or notation editor.
      </para>

      <sect3>
	<title>Step #1 - file chooser</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_midi_import_wizard_no1.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The MIDI import wizard - step #1
	    </para>
	  </caption>
	</mediaobject>	
	<para>
	  First you have to choose the Standard MIDI File you would like to import. As selected
	  the desired file you might want to click Forward.
	</para>	
      </sect3>
      
      <sect3>
	<title>Step #2 - mapping</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_midi_import_wizard_no2.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The MIDI import wizard - step #2
	    </para>
	  </caption>
	</mediaobject>
	
	<para>
	  After parsing the MIDI file there is one more step involved. You have to enable the
	  appropriate track. There are 2 labels visible showing meta information. Below there is
	  a combo box allowing you to choose the machine getting mapped. The spin buttons let you
	  adjust the number of audio channels to create. As well the first offset.
	</para>	

      </sect3>

    </sect2>
    <sect2>
      <title>The MIDI export wizard</title>
      <para>
	The MIDI export wizard allows you to export Standard MIDI Files. You might choose
	the machine which will be exported.
      </para>

      <sect3>
	<title>Step #1 - select machines</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_midi_export_wizard_no1.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The MIDI import wizard - step #1
	    </para>
	  </caption>
	</mediaobject>	
	<para>
	  First you have to enable the machines you wish to export. The entry allows you to
	  set the sequence meta information.
	</para>	
      </sect3>

      <sect3>
	<title>Step #2 - file chooser</title>
	<mediaobject>
	  <imageobject>
	    <imagedata width="100%" scalefit="1" fileref="../&images;/ags_midi_export_wizard_no2.png" format="PNG" />
	  </imageobject>
	  <caption>
	    <para>
	      The MIDI import wizard - step #2
	    </para>
	  </caption>
	</mediaobject>
	
	<para>
	  After enabled the machines to export you shall specify the filename. As next you
	  click OK in order to write the MIDI file.
	</para>	

      </sect3>

    </sect2>
  </sect1>

</chapter>