<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY legal SYSTEM "legal.xml">
+
]>
<article id="index" lang="en">
<articleinfo>
<copyright>
<year>1999</year>
+
<year>2000</year>
+
<year>2001</year>
+
<year>2002</year>
+ <year>2003</year>
+
<holder role="mailto:alex@lisas.de">Alexander König</holder>
</copyright>
- <releaseinfo>Version 3.73</releaseinfo>
-
- &legal;
+ <releaseinfo>Version 3.80</releaseinfo>
+
+ <legalnotice id="legalnotice">
+ <para>Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License (GFDL),
+ Version 1.1 or any later version published by the Free Software
+ Foundation with no Invariant Sections, no Front-Cover Texts, and no
+ Back-Cover Texts. You can find a copy of the GFDL at this <ulink
+ url="ghelp:fdl" type="help">link</ulink> or in the file COPYING-DOCS
+ distributed with this manual.</para>
+
+ <para>Many of the names used by companies to distinguish their products
+ and services are claimed as trademarks. Where those names appear in any
+ ScrollKeeper documentation, and the members of the ScrollKeeper Project
+ are made aware of those trademarks, then the names are in capital
+ letters or initial capital letters.</para>
+
+ <para>DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT ARE PROVIDED UNDER
+ THE TERMS OF THE GNU FREE DOCUMENTATION LICENSE WITH THE FURTHER
+ UNDERSTANDING THAT: <orderedlist><listitem><para>DOCUMENT IS PROVIDED ON
+ AN "AS IS" BASIS, WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+ OR IMPLIED, INCLUDING, WITHOUT LIMITATION, WARRANTIES THAT THE DOCUMENT
+ OR MODIFIED VERSION OF THE DOCUMENT IS FREE OF DEFECTS MERCHANTABLE, FIT
+ FOR A PARTICULAR PURPOSE OR NON-INFRINGING. THE ENTIRE RISK AS TO THE
+ QUALITY, ACCURACY, AND PERFORMANCE OF THE DOCUMENT OR MODIFIED VERSION
+ OF THE DOCUMENT IS WITH YOU. SHOULD ANY DOCUMENT OR MODIFIED VERSION
+ PROVE DEFECTIVE IN ANY RESPECT, YOU (NOT THE INITIAL WRITER, AUTHOR OR
+ ANY CONTRIBUTOR) ASSUME THE COST OF ANY NECESSARY SERVICING, REPAIR OR
+ CORRECTION. THIS DISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF
+ THIS LICENSE. NO USE OF ANY DOCUMENT OR MODIFIED VERSION OF THE DOCUMENT
+ IS AUTHORIZED HEREUNDER EXCEPT UNDER THIS DISCLAIMER; AND</para></listitem><listitem><para>UNDER
+ NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER IN TORT (INCLUDING
+ NEGLIGENCE), CONTRACT, OR OTHERWISE, SHALL THE AUTHOR, INITIAL WRITER,
+ ANY CONTRIBUTOR, OR ANY DISTRIBUTOR OF THE DOCUMENT OR MODIFIED VERSION
+ OF THE DOCUMENT, OR ANY SUPPLIER OF ANY OF SUCH PARTIES, BE LIABLE TO
+ ANY PERSON FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR
+ CONSEQUENTIAL DAMAGES OF ANY CHARACTER INCLUDING, WITHOUT LIMITATION,
+ DAMAGES FOR LOSS OF GOODWILL, WORK STOPPAGE, COMPUTER FAILURE OR
+ MALFUNCTION, OR ANY AND ALL OTHER DAMAGES OR LOSSES ARISING OUT OF OR
+ RELATING TO USE OF THE DOCUMENT AND MODIFIED VERSIONS OF THE DOCUMENT,
+ EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH
+ DAMAGES.</para></listitem></orderedlist></para>
+ </legalnotice>
</articleinfo>
<sect1 id="INTRODUCTION">
<sect2 id="WHATITIS">
<title>What it is</title>
- <para><application moreinfo="none">terminatorX</application> is a
- realtime audio synthesizer that allows you to "scratch" on
- digitally sampled audio data (*.wav, *.au, *.mp3, *.ogg etc.) the way
- hiphop-DJs scratch on vinyl records. It features multiple turntables,
- realtime effects (built-in as well as LADSPA plugin effects), a
- sequencer and an easy-to-use gtk+ GUI.</para>
+ <para><application moreinfo="none">terminatorX</application> is a real
+ time audio synthesizer that allows you to "scratch" on digitally
+ sampled audio data (*.wav, *.au, *.mp3, *.ogg etc.) the way Hiphop DJs
+ scratch on vinyl records. It features multiple turntables, real time
+ effects (built-in as well as LADSPA plugin effects), a sequencer and an
+ easy-to-use gtk+ GUI.</para>
<para>This is <emphasis>beta</emphasis> Software please help me fix
bugs. See <xref linkend="CONTACT" /> (Contact/Download). Please read
<title>Quickstart</title>
<para>Try the following steps:</para>
- <orderedlist inheritnum="ignore" continuation="restarts">
+
+ <orderedlist continuation="restarts" inheritnum="ignore">
<listitem>
<para>If you don't have <application moreinfo="none">LADSPA</application>
(Linux Audio Developer's Simple Plugin API) installed, go and
</listitem>
<listitem>
- <para>Install terminatorX (see <filename moreinfo="none">INSTALL</filename>)</para>
+ <para>Install terminatorX (see <filename moreinfo="none">INSTALL</filename>
+ file)</para>
</listitem>
<listitem>
<sect2 id="FEATURES">
<title>Features</title>
- <para>The following list summarizes terminatorX' main features:</para>
+
+ <para>The following list summarizes terminatorX' main features:</para>
<itemizedlist>
<listitem>
<para>Built-in Sequencer</para>
</listitem>
+ <listitem>
+ <para>MIDI Interface (Input)</para>
+ </listitem>
+
<listitem>
<para>Pitch / Volume settings for each turntable</para>
</listitem>
</listitem>
<listitem>
- <para>Recording (straight to disk now)</para>
+ <para>Recording to</para>
</listitem>
<listitem>
<sect2 id="REQUIREMENTS">
<title>Requirements</title>
-
- <para>To run terminatorX a system should meet the following requirements:</para>
+
+ <para>To run terminatorX a system should meet the following
+ requirements:</para>
<itemizedlist>
<listitem>
</listitem>
<listitem>
- <para>The Gimp Toolkit: gtk+ (>= 1.2.5) - Version 2 of
- gtk+ is supported, too. If your distribution doesn't
- provide a current version of gtk+ get it from the <ulink
- url="http://www.gtk.org">gtk+ homepage</ulink>.</para>
+ <para>The Gimp Toolkit: gtk+ (>= 2.0). If your
+ distribution doesn't provide a current version of gtk+
+ get it from the <ulink url="http://www.gtk.org">gtk+
+ homepage</ulink>.</para>
</listitem>
<listitem>
</listitem>
<listitem>
- <para>optional</para>
+ <para>optional (but highly recommended)</para>
<itemizedlist>
<listitem>
- <para><ulink
- url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
- for enhanced audio file support</para>
+ <para><ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
+ for easier handling of LADSPA plugins</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.mars.org/home/rob/proj/mpeg/">mad</ulink>
+ for loading mp3 files.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.xiph.org/ogg/vorbis/">libvorbis</ulink>
+ for loading ogg files.</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink url="http://www.68k.org/~michael/audiofile/">libaudiofile</ulink>
+ for loading misc other audio files.</para>
</listitem>
<listitem>
<para><ulink
url="http://www-ti.informatik.uni-tuebingen.de/~hippm/mpg123.html">mpg123</ulink>
- for mp3 support</para>
+ for mp3 pre-listening (and fallback loading if mad is not
+ installed).</para>
</listitem>
<listitem>
<para><ulink url="http://www.xiph.org/ogg/vorbis/">ogg123</ulink>
- for Ogg Vorbis support</para>
+ for ogg pre-listening (and fallback loading if libvorbis is
+ not installed).</para>
+ </listitem>
+
+ <listitem>
+ <para><ulink
+ url="http://home.sprynet.com/~cbagwell/sox.html">sox</ulink>
+ for misc files pre-listening (and fallback loading of misc
+ files).</para>
</listitem>
</itemizedlist>
</listitem>
<itemizedlist>
<listitem>
- <para>An OSS compatible soundcard capable of stereo output. This
- includes <emphasis>all</emphasis> <ulink
- url="http://www.alsa-project.org">ALSA-driven</ulink> soundcards
- as this enhanced audio device interface includes support for the
- OSS API.</para>
+ <para>An <ulink url="http://www.alsa-project.org">ALSA</ulink>
+ or OSS compatible soundcard capable of stereo output.</para>
</listitem>
<listitem>
controls. Each turntable has it's own GUI split up into control and
audio panel.</para>
+ <sect2>
+ <title>Menu</title>
+
+ <para>To clean-up the user interface a bit further some functions have
+ been moved into a more standard menu bar for the main window (with
+ release 3.80). The following sub-menus are available:</para>
+
+ <sect3>
+ <title><emphasis>File</emphasis> Menu</title>
+
+ <para>The <emphasis>File</emphasis> menu features these functions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>New</emphasis></para>
+
+ <para>Erases all existing turntables and sequencer events and
+ creates a new and untouched turntable.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Open</emphasis></para>
+
+ <para>Allows restoring of a previously saved terminatorX set file.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Save</emphasis></para>
+
+ <para>Saves the current turntables and events in a terminatorX set
+ file.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Save As</emphasis></para>
+
+ <para>Like <emphasis>Save</emphasis> but prompts for a new file
+ name.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Quit</emphasis></para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title><emphasis>Turntables</emphasis> Menu</title>
+
+ <para>The <emphasis>Turntables</emphasis> menu features these
+ functions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Add Turntable</emphasis></para>
+
+ <para>Adds a new turntable to the current set of turntables.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Record Audio to Disk</emphasis></para>
+
+ <para>On activation of this option, terminatorX will prompt for a
+ file name for the RIFF/Wave file to create. Once activated
+ terminatorX will start recording audio to disk the next time the
+ audio engine is started - either by pressing the Power or the Play
+ button. Recording will stop when the audio engine is stopped
+ again. The created RIFF/Wave file will be a 16Bit/Stereo wave-file
+ with the sampling rate selected for the current audio backend.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title><emphasis>Options</emphasis> Menu</title>
+
+ <para>The <emphasis>Options</emphasis> menu features these functions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Fullscreen</emphasis></para>
+
+ <para>Maximizes the terminatorX main windows to use the complete
+ screen. Note that this requires a NETWM compliant window manager
+ to work (GNOME2's metacity works nicely, while openbox 2.x
+ does not for example). By choosing this option again
+ terminatorX' window can be resized back to the previous state
+ again. The setting will be stored in the <filename>~/.terminatorXrc</filename>
+ file.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Preferences</emphasis></para>
+
+ <para>Will pop up the Preferences dialog. For more details on
+ configuration itself see the <xref linkend="CONFIGURATION" />
+ section.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title><emphasis>Help</emphasis> Menu</title>
+
+ <para>The <emphasis>Help</emphasis> menu features these functions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Contents</emphasis></para>
+
+ <para>Starts a <emphasis>gnome-help</emphasis> (aka
+ <emphasis>yelp</emphasis>) process to display the very manual you
+ are reading right now.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>About</emphasis></para>
+
+ <para>Selecting this menu item will cause a small dialog to pop up
+ that contains some information on the compile time settings for
+ the terminatorX binary as well as the license.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis>Visit terminatorX.cx</emphasis></para>
+
+ <para>Will try to spawn a browser process to load the URL
+ "http://terminatorX.cx" - for easy update checking or just
+ unecessary bloat.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+ </sect2>
+
<sect2 id="MAINCONTROLS">
<title>Main Controls</title>
- <para>The controls of the master gui are located in the top and the
+ <para>The controls of the master GUI are located in the top and the
right bar of the terminatorX main window.</para>
<itemizedlist>
Mode Operation) to find out how to control the software then.</para>
</listitem>
- <listitem>
- <para><emphasis>Record (Audio Engine)</emphasis></para>
-
- <para>To enable recording you have to enable the
- "Record"-toggle button BEFORE you start the audio engine.
- You will be prompted for a filename after enabling the button. Audio
- will then be recorded to that file in stereo RIFF/WAV format from
- the moment you turn the audio engine on until you turn it off again.
- Please be aware of the fact that recording audio requires
- <emphasis>a lot</emphasis> of harddisk space!</para>
- </listitem>
-
<listitem>
<para><emphasis>Sequencer Play / Record / Stop</emphasis></para>
relative to these master settings. This information will be stored
within the .tX set files.</para>
</listitem>
-
- <listitem>
- <para><emphasis>Add Turntable</emphasis></para>
-
- <para>Oh well, it says it all: adds a (new) turntable to the current
- set.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Save Set</emphasis></para>
-
- <para>With this button you can save your current set and all related
- settings to a .tX set file. Note that the audiofiles themselves will
- not be stored within these files but only references to them.
- Therefore on loading the set the audiofiles have to be at the same
- location in the filesystem as they were when putting that set
- together.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Load Set</emphasis></para>
-
- <para>Loads a previously saved set (see above). The current set will
- be destroyed!</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Options</emphasis></para>
-
- <para>Displays the options dialog. See <xref linkend="CONFIGURATION" />
- (Options/Configuration).</para>
- </listitem>
-
- <listitem>
- <para><emphasis>About/Legal</emphasis></para>
-
- <para>Displays a dialog with some info about the prog and the binary
- itself plus the good old GPL.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Quit</emphasis></para>
-
- <para>No comment.</para>
- </listitem>
</itemizedlist>
</sect2>
<sect2 id="TURNtableCONTROLS">
<title>Turntable Controls</title>
- <para>The turntable GUI contains multiple controls and the realtime
+ <para>The turntable GUI contains multiple controls and the real time
displays for each turntable. To save some space on your desktop and to
give terminatorX the traditional audio-application look, terminatorX
features "knob"-widgets. These widgets work pretty
indicate the current position within the sample with a red cursor (a
blue/green cursor indicates the turntable is muted).</para>
- <para>Additionaly there are some controls above the audio-display:</para>
+ <para>Additionally there are some controls above the audio-display:</para>
<itemizedlist>
<listitem>
that qualify as "mappable". Note that this includes
plugins' controls as well.</para>
</listitem>
+
+ <listitem>
+ <para><emphasis>MIDI Mapping</emphasis></para>
+
+ <para>This button is available only if terminatorX was built with
+ ALSA MIDI support and the sequencer input port was created
+ successfully on startup. For more information on terminatorX'
+ MIDI interface see <xref linkend="MIDI" /> section.</para>
+ </listitem>
</itemizedlist>
</sect3>
<listitem>
<para><emphasis>Delete Button</emphasis></para>
- <para>Pressing this button remove the tunrtable from the current
+ <para>Pressing this button remove the turntable from the current
setup. Note that all sequencer events recorded for this
turntable will be erased, too.</para>
</listitem>
<para><emphasis>Client Button</emphasis></para>
<para>This button marks the turntable as <emphasis>sync-client</emphasis>,
- so it will be triggerd with the master automatically.</para>
+ so it will be triggered with the master automatically.</para>
</listitem>
<listitem>
be triggered. With a setting of zero the sync-client will be
(re-)triggered with <emphasis>every</emphasis> trigger of the
sync-master. A setting of 1 will (re-)trigger the client every
- <emphasis>second</emphasis> master-triger and so on.</para>
+ <emphasis>second</emphasis> master-trigger and so on.</para>
</listitem>
</itemizedlist>
effect-queue. The effect sequence is configurable by the user. To move
an effect to higher position within the queue, press the
<emphasis>blue upward arrow button</emphasis>. This will cause the
- effect to be renderd <emphasis>before</emphasis> the following
+ effect to be rendered <emphasis>before</emphasis> the following
effects. The <emphasis>blue downward arrow button</emphasis> will move
the effect down by one position. It will then be rendered
<emphasis>after</emphasis> the preceding effects.</para>
(Lowpass and Echo) and LADSPA plugins. The built-in effects are always
available and cannot be removed (but disabled). There can be only one
instance of a built-in effect. The LADSPA plugins on the other hand
- may be instanciated multiple times and can be removed from the effect
+ may be instantiated multiple times and can be removed from the effect
queue. Press the <emphasis>blue cross button</emphasis> to achieve
this.</para>
<para>Now since release 3.71 the built-in echo effect is treated
differently from other effects. Where all other effects feed their
signal back into the effect queue the echo effect doesn't touch
- the input signal. It's echo-signal is mixed seperately from the
+ the input signal. It's echo-signal is mixed separately from the
turntable's main signal to allow a different panning value for the
echo-signal. This mode of operation does have some side-effects:
imagine a lowpass filter with a position after the echo effect in the
effect queue. This will result in the turntable's main signal
- being lowpassed but it will leave the echo-signal un-lowpassed.</para>
+ being lowpass-filtered but it will leave the echo-signal
+ lowpass-unfiltered.</para>
<para>Some may call this behaviour a bug - whereas I would consider it
a feature ;). Anyway if the above description didn't clear things
plugins have they sometimes might be hard to control with the knob
widget. In these cases you might want to use the text field to
enter values. For more details on Plugins see <xref
- linkend="LADSPAPLUGINS" /> (LASDPA).</para>
+ linkend="LADSPAPLUGINS" /> (LADSPA).</para>
</listitem>
</itemizedlist>
</sect3>
<sect3>
<title>Lowpass Panel</title>
- <para>terminatorX features a builtin resonating lowpass filter that
+ <para>terminatorX features a built-in resonating lowpass filter that
can be configured with this panel.</para>
<itemizedlist>
<sect3>
<title>Echo Panel</title>
- <para>Additionaly terminatorX features a built-in echo effect. It can
+ <para>Additionally terminatorX features a built-in echo effect. It can
be configured with this panel.</para>
<itemizedlist>
<para><emphasis>Pan Control</emphasis></para>
<para>The echo effect differs from other effects as it's
- output signal will be mixed seperately. The main goal here is to
+ output signal will be mixed separately. The main goal here is to
allow positioning the echo signal at a position in the stereo
- panorama that differs from the main panning positon of the
+ panorama that differs from the main panning position of the
turntable to achieve a somewhat spacial effect. The easy example
is: turntable's panning left, echo's panning right. As
- both pan parameters are sequencable you can create nice motion
+ both pan parameters are sequenceable you can create nice motion
effects from this starting point.</para>
</listitem>
</itemizedlist>
<sect2 id="SYNCHRONIZATION">
<title>Synchronization</title>
- <para>Let's start off with an example: Say you have two drumloops
+ <para>Let's start off with an example: Say you have two drum loops
and one bassline loaded in three turntables. Of course you want these
samples to be triggered at the same time but you don't want to
invest time to cut them to the exact length. Therefore you decide which
- of the drumloops to make the sync master. You'll have to do this
+ of the drum loops to make the sync master. You'll have to do this
before you enable the audio engine (for now). Only one turntable can be
the sync master. Now you can make the other two sync clients which will
cause them to be (re-)triggered whenever the master is (re-)triggered.
<para>After pressing the <emphasis>Mouse Grab button</emphasis>
terminatorX enters "grab mode". This mode actually locks the
- mouse (as this input is now used to control the realtime parameters) and
- therefore you'll have to know some mouse/keyboard shortcuts to
+ mouse (as this input is now used to control the real time parameters)
+ and therefore you'll have to know some mouse/keyboard shortcuts to
control the software without the GUI.</para>
<para>Press <keycap moreinfo="none">ESCAPE</keycap> to quit grab mode.</para>
<para>Select the turntable with input focus: The first turntable to hold
the input focus will be the first turntable. You can now use <keycap
moreinfo="none">TAB</keycap> or right mouse button to switch to the next
- turntable. Alternativley you can use <keycap moreinfo="none">F1</keycap>
- to <keycap moreinfo="none">F12</keycap> to select turtntable 1 to 12.</para>
+ turntable. Alternatively you can use <keycap moreinfo="none">F1</keycap>
+ to <keycap moreinfo="none">F12</keycap> to select turntable 1 to 12.</para>
<para>Now the turntable that has the focus is the one you will
manipulate with your mouse and keyboard inputs: Note that you can
<para>Since V3.55 terminatorX provides multiple DND-Drop-Targets for use
with GNOME / gmc (gmc is the GNU Midnight Commander), Nautilus or the
- Elightenment File Manager (efm). You can load an audiofile into an
+ Enlightenment File Manager (efm). You can load an audiofile into an
existing turntable by dragging it from a gmc (or efm or whatever)-window
and drop it over a. the <emphasis>file button</emphasis> (audio-display)
or b. (the easier target ;) over the audio-display (the green on black
<para>To add a file to the set (== to load the file into a *new*
turntable) simply drop the audiofile over the "New Turntable"
- Button. To load a complete terminatorX-set simply drop the setfile
+ Button. To load a complete terminatorX-set simply drop the set file
(*.tX) over the "Load Set" button.</para>
</sect2>
<para>To record events simply press the <emphasis>Record</emphasis>
button of the sequencer, then press the <emphasis>Play</emphasis>
- button. All actions (for sequencable parameters - see above) you now
+ button. All actions (for sequenceable parameters - see above) you now
take will be recorded into the song list. Press <emphasis>Stop</emphasis>
and <emphasis>Play</emphasis> again to see/hear how terminatorX plays
back the events recorded before. You can now record events again for
e.g. another turntable or record other parameters for the same turntable
- - whatever you want to do. Recording events for parameters for wich
+ - whatever you want to do. Recording events for parameters for which
events have been recorded before will result in dubbing: if you touch a
parameter while recording, events previously recorded will be erased
- from the moment you touch the paramater until you stop recording.</para>
+ from the moment you touch the parameter until you stop recording.</para>
<para>When recording long sequences/songs you can use the
sequencer-scale to start recording/playback from any song-position you
- want. To record a single paramteter value at a certain position simply
+ want. To record a single parameter value at a certain position simply
move the sequencer-scale to that position, press <emphasis>Record,</emphasis>
set the parameter and press <emphasis>Stop</emphasis> again.</para>
load plugins with <emphasis>one</emphasis> audio-in port and
<emphasis>one</emphasis> audio-out port only.</para>
- <para>The decision on wether a plugin is terminatorX-suitable is made on
- terminatorX startup, so only plugins that fit into the effect queue will
- be offered in the plugin-menu that pops up when the
- <emphasis>FX</emphasis> button is clicked. On startup terminatorX will
- print some information on the LADSPA-plugins analysis process to the
- standard output. Watch the terminal you run terminatorX from for that
- info if you have problems loading a plugin.</para>
+ <para>The decision on whether a plugin is terminatorX-suitable is made
+ on terminatorX startup, so only plugins that fit into the effect queue
+ will be offered in the plugin-menu that pops up when the
+ <emphasis>FX</emphasis> button is clicked. Depending on whether the
+ terminatorX binary you're using was built with or without liblrdf (<xref
+ linkend="LIBLRDF" />) support the plugin menu will either contain
+ sub-menus with plugin categories (with liblrdf) or just a single menu
+ with the <emphasis>Unclassified</emphasis> category.</para>
+
+ <para>On startup terminatorX will print some information on the
+ LADSPA-plugins analysis process to the standard output. Watch the
+ terminal you run terminatorX from for that info if you have problems
+ loading a plugin.</para>
<para>As specified in the LADSPA-standard LADSPA-plugins can be located
in multiple directories across the filesystem. To enable LADSPA-hosts to
order for other LADSPA-hosts to work properly, be sure to set your
<envar>LADSPA_PATH</envar> correctly. It is a good idea to do that from
somewhere in your system configuration (either in your rc-scripts or
- <filename moreinfo="none">/etc/profile</filename> or whereever you
- perefer).</para>
+ <filename moreinfo="none">/etc/profile</filename> or wherever you
+ prefer).</para>
+
+ <sect3 id="LIBLRDF">
+ <title>liblrdf support</title>
+
+ <para>Release 3.80 introduces support for Steve Harris' great
+ <ulink url="http://plugin.org.uk/releases/lrdf/">liblrdf</ulink>
+ library which introduces an RDF based scheme to categorize LADSPA
+ plugins. This approach allows storing additional meta-data for LADSPA
+ plugins in separate RDF files. In order to make use of these RDF files
+ a terminatorX binary (compiled with liblrdf support of course)
+ requires the main <filename>ladspa.rdfs</filename> file and additional
+ RDF files containing meta information about the LADSPA plugins
+ installed. Steve Harris' wonderful plugin library comes with such
+ an additional description file for example.</para>
+
+ <para>By default terminatorX will search the directories
+ <filename>/usr/share/ladspa/rdf</filename> and <filename>/usr/local/share/ladspa/rdf</filename>
+ for RDF files. In case the files were installed to other locations it
+ is possible to configure the LADSPA RDF path in the
+ <emphasis>Misc</emphasis> tab of the <emphasis>Preferences</emphasis>
+ dialog.</para>
+
+ <para>If the RDF are read successfully on startup, the LADSPA menu
+ that pops up when clicking a turntable's <emphasis>FX</emphasis>
+ button will feature multiple sub-menus with LADSPA plugin categories
+ (eg <emphasis>Amplitude/Amplifier</emphasis>) in which you will find
+ the according plugins. Plugins not categorized by the RDF files reside
+ in the <emphasis>Unclassified</emphasis> menu.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="MIDI">
+ <title>MIDI Interface</title>
+
+ <para>Aside of controlling terminatorX with a regular mouse and keyboard
+ it is possible to control parameters through MIDI events (since 3.80).
+ The MIDI interface is based upon the ALSA sequencer API. On startup
+ terminatorX creates a MIDI input port called "terminatorX". You
+ can now use for example the <ulink url="alsa-patch-bay link here">alsa-patch-pay</ulink>
+ to connect an output port of your choice (either a hardware MIDI input
+ device or a software generating midi events) to the terminatorX input
+ port.</para>
+
+ <para>Once the connection is set up terminatorX receives MIDI events
+ through the input port. To configure what MIDI events will have which
+ effect on a terminatorX turntable you can bind MIDI events to parameters
+ of your choice by clicking the <emphasis>MIDI Mapping</emphasis> button
+ of the turntable's audio panel. As a result the
+ <emphasis>Configure MIDI Bindings</emphasis> dialog will pop up which
+ features a field labelled <emphasis>Selected MIDI Event</emphasis> that
+ will frequently update to display the contents of the last MIDI event
+ received by terminatorX. So in order to map a MIDI controller to a
+ specific turntable parameter select the parameter of your choice from
+ the parameter list, cause your MIDI event sending device to emit the
+ event you want to map the parameter on and click the
+ <emphasis>Bind</emphasis> button.</para>
+
+ <para>Immediately after binding the event you should see that the
+ <emphasis>Event</emphasis> column entry of the selected parameter is
+ updated to match the selected event. From now on all events matching the
+ selected event will cause the turntable parameter to be updated. The GUI
+ for that parameter will be refreshed accordingly. Note that it is
+ possible to map the same event to multiple parameters.</para>
+
+ <para>The MIDI mappings are stored within terminatorX set files so you
+ wont have to reconfigure your bindings every time you start up
+ terminatorX. If you are unhappy with a chosen binding you can select the
+ parameter and click the <emphasis>Remove Binding</emphasis> button to
+ get rid of the parameter's MIDI mapping.</para>
+
+ <para>If you want to use your joystick to control terminatorX - I wrote
+ a tiny tool to create MIDI events from joystick motion called
+ <emphasis>aseqjoy</emphasis>. It's available from the <ulink
+ url="http://terminatorX.cx/aseqjoy">terminatorX website</ulink>, too.</para>
</sect2>
</sect1>
<sect1 id="CONFIGURATION">
<title>Configuration</title>
- <para>All configuration business now happens in the Options-dialog. The
- features that are not completely self-explaining do have tooltips.</para>
+ <para>The main terminatorX configuration parameters can be set up via the
+ <emphasis>Preferences</emphasis> dialog, which can be activated from the
+ terminatorX menu. The new <emphasis>Preferences</emphasis> dialog features
+ multiple tabs for several aspects of configuration.</para>
- <para>A word on the settings in general: your settings are stored in the
- file <filename moreinfo="none">~/.terminatorX3rc.bin</filename> so if you
- think you completely messed up your settings you will have to exit
+ <para>A word on the settings in general: your settings are stored in an
+ XML file ( <filename moreinfo="none">~/.terminatorXrc).</filename> So if
+ you think you completely messed up your settings you will have to exit
terminatorX - delete this file - and then re-run terminatorX with the
- default settings.</para>
+ default settings. Note: is this file is now an XML file you can edit with
+ an editor of your choice.</para>
- <sect2 id="AUDIOSETUP">
- <title>Audio Setup</title>
+ <sect2>
+ <title><emphasis>Audio</emphasis> Tab</title>
- <para>TerminatorX renders audio blockwise. If you want to have
- near-realtime operation you need to have really small blocks. The values
- of these blocks can be influenced via the <emphasis>buffer size</emphasis>
- option. The setting you select actually results in a 2^x blocksize
- (size-setting == 8 -> true buffer size in bytes is 2^8=256).</para>
+ <para>This tab allows to select which audio backend to use. Currently
+ there are two of these: one for the OSS (Open Sound System) backend and
+ one for ALSA (Advanced Linux Sound Architecture) backend. Hopefully
+ future releases will feature a JACK backend too.</para>
+ </sect2>
- <para>The problem is the smaller the value you select is the faster your
- machine has to be. So if you here "clicks", or "drops"
- in audio output that are not related to your sample-material you will
- have to increase the buffer size. On the other hand if you believe
+ <sect2>
+ <title><emphasis>Audio: OSS</emphasis> Tab</title>
+
+ <para>Select the audio device you are going to use from the available
+ options (or simply enter one yourself). terminatorX renders audio
+ block-wise. In order to achieve close-to-realtime performance it is
+ necessary to keep this blocks as small as possible. The main parameters
+ that determine how close-to-realtime terminatorX will perform are
+ <emphasis>No. of Buffers</emphasis> and <emphasis>Buffersize</emphasis>.
+ The <emphasis>No. of Buffers</emphasis> parameter determines how many
+ buffers the audio driver should use in most cases <emphasis>2</emphasis>
+ should be the best setting and in rare cases <emphasis>3</emphasis>
+ might give better results.</para>
+
+ <para>The value for the <emphasis>Buffersize</emphasis> setting will be
+ evaluated as 2^buffersize by OSS. So if you set the value to
+ <emphasis>8</emphasis> the actual buffer size will be 2^8=256 Bytes. The
+ smaller the buffers' size the better terminatorX will perform. The
+ default setting of <emphasis>9</emphasis> should be acceptable in most
+ conditions, but if you here "clicks", or "drops" in
+ audio output that are not related to your sample-material you will have
+ to increase the buffer size. On the other hand if you believe
terminatorX does not react fast enough you have to decrease this
- parameter. The default value is 8, but as my machine handles 7 nicely
- (running with root privileges for realtime scheduling) I use 7.</para>
+ parameter.</para>
+
+ <para>Additionally you can select the sampling rate you want terminatorX
+ to operate on - note that recording to disk will use the same sample
+ rate.</para>
+ </sect2>
+
+ <sect2>
+ <title><emphasis>Audio: ALSA</emphasis> Tab</title>
+
+ <para>Configuring the ALSA backend works pretty similar to configuring
+ the OSS backend (see above) - except that ALSA doesn't use crappy
+ "2^x" semantics for the buffer size setting: you can specify the
+ buffer size in plain bytes.</para>
</sect2>
- <sect2 id="MOUSEINPUTSETUP">
- <title>Mouse/Input Setup</title>
+ <sect2>
+ <title><emphasis>Input</emphasis> Tab</title>
- <para>Between rendering and outputing these blocks terminatorX checks
+ <para>Between rendering and outputting these blocks terminatorX checks
for mouse motion. The problem with mice is: they don't report when
they have stopped. This is why terminatorX assumes your mouse has
stopped if there is no motion reported for certain amount of
render/output-cycles. This value is configurable via the
<emphasis>Stop-sense-cycles</emphasis> option. If you decrease your
- buffsize of course you shorten the cycle time as well, therefore if you
- here strange stop/run behaviour of the audio ouput while scratching
- after you decreased the buffersize you might have to increase the
+ buffersize of course you shorten the cycle time as well, therefore if
+ you here strange stop/run behaviour of the audio output while scratching
+ after you decreased the buffer size you might have to increase the
stop-sense value too.</para>
- <para>Xinput Device: <emphasis>WARNING:</emphasis> Use this option
+ <para>XInput Device: <emphasis>WARNING:</emphasis> Use this option
*only* if you want to use an input device other than your default-mouse
for scratching. Selecting your default pointer will cause terminatorX to
crash. See the "Using a turntable" section on the terminatorX
homepage for details.</para>
</sect2>
- <sect2 id="GUISETUP">
- <title>GUI Setup</title>
+ <sect2>
+ <title><emphasis>User Interface</emphasis> Tab</title>
<para>With <emphasis>Update Idle</emphasis> / <emphasis>Update Delay</emphasis>
- you can configure GUI resposivness: Higher <emphasis>Update Idle</emphasis>
- will cause the wav-display (position display) and flash-widgets to
+ you can configure GUI responsiveness: Higher <emphasis>Update Idle</emphasis>
+ will cause the wave display (position display) and flash-widgets to
update less often. Higher <emphasis>Update Delay</emphasis> values will
cause the parameter widgets to update less often.</para>
</sect2>
- <sect2 id="SOUNDFILEEDITOR">
- <title>Soundfile-Editor integration</title>
+ <sect2>
+ <title><emphasis>Misc</emphasis> Tab</title>
<para>You can now enter the soundfile editor of your choice in the
- "Soundfile editor" field. This editor will be started when
+ "Sound file editor" field. This editor will be started when
clicking the <emphasis>Edit</emphasis>-button in the main panel of the
vtt-gui. If you enter for example "myeditor" terminatorX will
run "myeditor sample_in_vtt.wav".</para>
<para>Send me comments, bug-reports, patches or scratches (see scratches
section on the terminatorX homepage) at: <email>alex@lisas.de</email></para>
</sect1>
-</article>
+</article>
\ No newline at end of file
git://lisas.de / terminatorX.git / commitdiff