<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook V3.1-Based Variant V1.0//EN" [
 <!ENTITY kappname "&kmidi;">
 <!ENTITY % addindex "IGNORE">
 <!ENTITY % English "INCLUDE">
 <!ENTITY % ents PUBLIC "-//KDE//ENTITIES Documentation V1.0//EN">
 %ents; 
]>

<book lang="&language;">
<bookinfo>
<title>The &kmidi; Handbook</title>
<authorgroup>
<author>
<firstname>Bernd Johannes</firstname>
<surname>Wuebben</surname>
<affiliation>
<address><email>wuebben@kde.org</email></address>
</affiliation>
</author>
<author>
<firstname>Greg</firstname>
<surname>Lee</surname>
<affiliation>
<address><email>lee@hawaii.edu</email></address>
</affiliation>
</author>
</authorgroup>

<copyright>
<year>1999</year>
<year>2000</year>
<holder>Greg Lee</holder>
</copyright>

<date>16/12/2000</date>
<releaseinfo>1.03.00</releaseinfo>
<abstract>
<para>KMidi plays midi files using instrument patches. It does in software what
a soundcard like the GUS (Gravis UltraSound) or Sound Blaster AWE does in
hardware.</para>

</abstract>
<keywordset>
<keyword>KMidi</keyword>
<keyword>Midi</keyword>
<keyword>Player</keyword>
<keyword>Timidity</keyword>
<keyword>Midi</keyword>
<keyword>to</keyword>
<keyword>Wav</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>KMidi plays midi files using instrument patches. It does in software what
a soundcard like the GUS (Gravis UltraSound) or Sound Blaster AWE does in hardware.
So, the only hardware you need is a simple soundcard or chip. Even if you have
a GUS or AWE, you might still like to try KMidi, since it sounds pretty good.
And it has the advantage that, if you'd like it to sound better, you can just
roll up your sleeves and rewrite it, because of course you get the source code
free.</para>

<para>It does, however, need some cpu time. I find that starting up new windows
or sometimes just scrolling my screen causes dropouts in the music. Also, you'll
want to get yourself some patchsets (see below). They're too bulky (10-12 megs)
to include as part of the regular KDE distribution, so I've include only 5
patches as examples. KMidi can handle 257 banks of 128 instruments each.</para>

<para>KMidi is based on Tuukka Toivonen's wonderful program TiMidity, which does
most of the work. KMidi is a GUI front end for TiMidity, and TiMidity itself,
with other alternative user interfaces, is included in the source distribution
of KMidi. Thanks, Tuukka!</para>

<para>KMidi supports at the moment (Version 1.3) the following platforms:</para>

<para><itemizedlist>
<listitem>
<para>Linux </para>
</listitem>
<listitem>
<para>FreeBSD </para>
</listitem>
<listitem>
<para>DEC OSF/1 </para>
</listitem>
<listitem>
<para>HP UX </para>
</listitem>
<listitem>
<para>SUN</para>
</listitem>
<listitem>
<para>SUN SOLARIS </para>
</listitem>
</itemizedlist>
</para>

<para>Ports to other platforms should be easy. Please contact me if you ported
KMidi to another platform.</para>

<para>For details about usage that may not be covered in this manual, see the
timidity(1) man page.</para>

<para>Remember Midi files are typically around 50k or less and are therefore
so easily downloaded that you will never run out of great midi's to play.</para>

<para>Have fun with KMidi!</para>

<para><literal remap="tt">Bernd Johannes Wuebben</literal> <ulink url="mailto:wuebben@kde.org">wuebben@kde.org</ulink></para>
</chapter>

<chapter id="usage">
<title>Usage
 </title>
<sect1 id="getting-started">
<title>Getting Started
 </title>

<para>If you haven't used KMidi before, you'll see the name of one of the example
midi files I included in the black window. Click the play button to play it.
Move the mouse pointer around from button to button to get a brief ``tooltip''
description of what each button does when clicked on.</para>

<para>Click on the ``KMidi'' logo at the upper left to make the bottom panel
visible. There you'll see a black window, the ``channel meter'', which shows
a bar graph of notes being played on the 16 midi channels. To its left is a
patchset selector and a song selector. Click on the song selector to see a
list of the other example midi files I included with the KMidi distribution.
Click on another, if you like, to play it.</para>

<para>Click on the Info button to see information about the midi file you're
playing and ``Karaoke'' lyrics (if the midi file has any).</para>

<para>Click the playlist button to look around your filesystem for midi files
and compose your own list of files to play. Unless you click off the filter
button, only midi files will be shown (regardless of whether they have a <literal remap="tt">.mid</literal>
or <literal remap="tt">.kar</literal> suffix). Double click a filename on the left part of the screen to
add the file to your playlist (shown on the right).</para>

<para>Don't be surprised or chagrined if some midi files produce little or no
sound. KMidi as distributed has a pitifully small number of instrument patches.
Sorry about that. Please see the section of this document on how to obtain
patchsets on the net.</para>
</sect1>
<sect1 id="Playlists">
<title>Playlists
 </title>

<para>Click on the ``eject'' button to open the playlist manager. At the left
you'll see the content of the directory you were in the last time you edited
your playlist. At the right you see your current playlist. Select a midi file
on the left to append to the playlist by double clicking on it. Or single click,
then click on Add.</para>

<para>The only files shown on the left are midi files. Compressed midi files
will not be recognized, unfortunately, so if you've used, say, gzip to compress
the files, you'll want to click off the Filter button at the bottom. Then all
files become visible. KMidi does not decide whether a file is a midi file or
not by looking at the name; instead, it reads a bit of the file to see whether
it appears to be a midi file. So there's no need to name your midi files with
a <literal remap="tt">.mid</literal> suffix.</para>

<para>Toward the bottom of the screen are your current playlists. When you first
start, there will be only one, called ``default'' with the sample midis from
the KMidi distribution. You change the contents of this by clicking once on
the name ``default'' (if it is not already selected) then clicking File-&gt;Save
to replace the contents of the playlist file with your current playlist. Or
click File-&gt;Append to concatenate your current playlist onto the end of
a playlist file. To create a new playlist, click File-&gt;Save as ... instead
and fill in the new name you've chosen into the little box that appears. Double
click on the name of a playlist to replace your current playlist with the contents
of the one you've saved. This can also be done from the front panel by single
clicking on the name of a playlist in the ``Select Playlist'' box.</para>

<para>Remove a playlist by clicking on its name, then clicking File-&gt;Remove.</para>

<para>The vertical bar separating the directory list from the playlist can be
dragged from left to right with the mouse. The horizontal bar separating these
from the playlist names can be dragged up and down.</para>
</sect1>
<sect1 id="midi-filenames">
<title>Midi file names
 </title>

<para>The names of midi files you see on the front panel may differ slightly
from the actual file names. For readability, KMidi replaces any `_' in the
midi file name by spaces and chops off the .mid/ .MID ending if present.</para>
</sect1>
<sect1 id="configuring">
<title>Configuring
 </title>

<para>Clicking the configure button on the panel takes you to a configure screen
where you can choose the background color of the panel's two windows and the
``led'' color. At the moment, the color used for percussion in the channel
meter is not configurable -- it's always yellow.</para>
</sect1>
<sect1 id="patchsets">
<title>Patchsets
 </title>

<para>On the bottom panel at the top left you'll find the patchset selector.
For KMidi as distributed, you'll see three patchset options: <literal
remap="tt">piano+guitar</literal>, <literal remap="tt">piano</literal>, and
<literal remap="tt">guitar</literal>. There isn't any real point to selecting
the piano or guitar patchsets; the choices are there merely as an
illustration. When you acquire a bunch of patchsets, you can set things up so as
to switch between them from the panel. Here is how to do that:</para>

<para>For each patchset, create a <literal remap="tt">cfg</literal> file
describing the patches and their banks and instrument (midi ``program'')
numbers. Then in the file <literal remap="tt">timidity.cfg</literal>, enter a
line <literal remap="tt">source</literal> &lt;filename&gt; and a preceding line
if &lt;n&gt;, where &lt;filename&gt; is the name you gave to the file describing
the patches, and &lt;n&gt; is the line where &lt;filename&gt; will appear in
KMidi's panel in the ``Select Patchset'' box. Clicking on this name will select
the patchset. The numbering of the patchsets starts with number 0.</para>

<para>In <literal remap="tt">cfg</literal> files, the banks/drumsets and names
of patches must be given, since those that are not declared will not be loaded
from files (GUS patch files or sound fonts) even though the patches are
available. This way it's easy to exclude certain patches from a sound font so as
to load better ones from a subseqently loaded font. Just don't declare them
before you've asked to load the font. .</para>

<para>When the same patch of the same bank or drumset is declared more than once,
only the first declaration counts. So put your best fonts first.</para>

<para>There is a utility <literal remap="tt">sf2cfg</literal> to construct a
<literal remap="tt">cfg</literal> file for a <literal
remap="tt">sbk/sf2</literal> sound font, which spits out all the patches that
are present in the font. Also, I've included sample <literal
remap="tt">cfg</literal> files for <literal remap="tt">chaos8m.sf2</literal> and
<literal remap="tt">chaos12m.sf2</literal>.</para>
</sect1>
<sect1 id="polyphony">
<title>Polyphony
 </title>

<para>Do you hear dropouts in the music? It's possible for KMidi to get behind
in doing the many calculations required to adjust the pitch of instrument
patches, filter the signal, combine notes, and so on. If this happens, you may
be able to improve the situation by using the spinbox on the lower panel to the
right.  This adjusts the maximum number of polyphonic ``voices'' used at the
same time.  When you lower the maximum polyphony, you lighten KMidi's burden at
the cost of some chorus or reverb effect being lost, or some notes being cut
short or actually being omitted altogether. (In some circumstances, KMidi
generates extra notes to approximate the effect of midi chorus and
reverberation.)</para>
</sect1>
<sect1 id="Effects">
<title>Effects
 </title>

<para>Effects modify the sound in various ways, some of which I'm not too clear
about. There are four ways effects may be requested and two ways you can control
them.</para>

<para>A midi song may specify an effect for all the instruments playing on any
particular one of the 16 midi channels. Or, it may specify several effects for
several channels. When you click down the panel's ``eff'' button, the signal is
filtered to approximate the midi effects: chorus, reverberation, celeste, and
phaser. But there won't be any effects unless the song in the midi file asks for
them. Two of the standard midi effects, harmonics and brightness, are not yet
implemented by filters. (The filters were coded by Nicolas Witczak.)</para>

<para>When you don't click down the ``eff'' button, you still get some chorus
and reverberation on channels where it's requested, but it's done in a different
way. Now, instead of using filters, extra notes are generated. They are detuned
slightly for chorus effect and delayed slightly for reverberation. There are
also some adjustments made to note envelopes and vibrato. With ``eff'' turned
off, you get no channel celeste or phaser effects.</para>

<para>A second way effects may be requested is by a patch. That is, an
instrument patch may contain a suggested chorus and/or reverb level. AWE patches
generally do specify effects, but Gravis-Forte patches don't. (That's why AWE
patchsets tend to sound a bit fruity.) Effects requested this way are done by
the ``ghost note'' method, and are unaffected by the ``eff'' button.</para>

<para>Thirdly, you may request effects. Notice the four checkboxes at the right
of the panel. Each has three states: ``normal'' (the default), "extra'', and
``off''. The middle two checkboxes control chorus and reverb. If they are set to
``normal'', effects are treated as described above. Set to ``extra'', extra
notes are generated for chorus or reverb for all instruments and all channels,
and this is in addition to the effects filters if they are requested by clicking
``eff''. When they are set to ``off'', no extra chorus or reverb notes are
generated.</para>

<para>Finally, effects may be requested by midi system exclusive message in a
midi file -- ``sysexes''. These are intended to control the hardware of specific
synthesizers. KMidi does a certain amount of decoding of sysexes for Roland GS
synths and Yamaha XG synths and does its best to modify the sound accordingly.
Chorus, reverb, and variations on these are done by the ``ghost note'' method
and can be switched off with the checkboxes just mentioned. However, when the
celeste variation of chorusing is requested in an XG sysex, this invokes
Witczak's celeste filter, provided the ``eff'' button is clicked on.</para>
</sect1>
<sect1 id="command-line-options">
<title>Command Line Options
 </title>

<para>Except for giving the names of one or more midi files on the command line,
the material in this section is probably not very useful to know about. If
you have a need for these options, you'd probably prefer to use
the command line version of this program: ``timidity''.</para>

<para><variablelist>
<varlistentry>
<term>kmidi</term>
<listitem>
<para>&lsqb;options&rsqb; filename &lsqb;...&rsqb;</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Use &quot;-&quot; as filename to read a MIDI file from stdin</para>

<para><variablelist>
<varlistentry>
<term>Options:</term>
<listitem>
<para></para>
</listitem>
</varlistentry>
<varlistentry>
<term>-o filename</term>
<listitem>
<para>Place output on filename, which may be a file, device,
or HP-UX audio server, depending on the output mode selected with the <emphasis remap="bf">-O</emphasis> option.
The special filename ``-'' causes output to be placed on stdout. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>-O mode</term>
<listitem>
<para>Selects the output mode from the compiled-in alternatives.
mode must begin with one of the supported output mode identifiers. Run TiMidity
with the <emphasis remap="bf">-h</emphasis> option to see a list. </para>
</listitem>
</varlistentry>
<varlistentry>
<term>-sf</term>
<listitem>
<para>Set sampling frequency to f (Hz or kHz) Not all sound devices
are capable of all frequencies -- an approximate frequency may be selected,
depending on the implementation.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-a</term>
<listitem>
<para>Enable the antialiasing filter. Samples are run through a lowpass
filter before playing, which reduces aliasing noise at low resampling frequencies.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-f</term>
<listitem>
<para>Enable fast decay mode. Toggles fast envelopes. Some MIDI files
sound better when notes decay slower -- it gives the impression of reverb.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-pn</term>
<listitem>
<para>Sets polyphony (maximum number of simultaneous voices).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-An</term>
<listitem>
<para>Amplify volume by n percent (may cause clipping)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Cn</term>
<listitem>
<para>Sets the ratio of sampling and control frequencies. This determines
how often envelopes are recalculated -- small ratios yield better quality but
use more CPU time.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-E</term>
<listitem>
<para>Turns on Witczak's effect filters for chorus, reverb, phaser,
and celeste.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-&num;n</term>
<listitem>
<para>Select patch set</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-L dir</term>
<listitem>
<para>Append dir to search path</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-c file</term>
<listitem>
<para>Read extra configuration file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-In</term>
<listitem>
<para>Use program n as the default</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-P</term>
<listitem>
<para>file Use patch file for all programs</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Dn</term>
<listitem>
<para>Play drums on channel n</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Qn</term>
<listitem>
<para>Ignore channel n</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-F</term>
<listitem>
<para>Enable fast panning</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-U</term>
<listitem>
<para>Unload instruments from memory between MIDI files</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-i mode</term>
<listitem>
<para>Select user interface (see below for list)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Bn</term>
<listitem>
<para>Set number of buffer fragments</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>Display this help message</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Available output modes (-O option):</para>

<para><variablelist>
<varlistentry>
<term>-Od</term>
<listitem>
<para>Linux dsp device</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Ow</term>
<listitem>
<para>RIFF WAVE file</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Or</term>
<listitem>
<para>raw waveform data</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Output format options (append to -O? option):</para>

<para><variablelist>
<varlistentry>
<term>`8'</term>
<listitem>
<para>8-bit sample width</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`1'</term>
<listitem>
<para>16-bit sample width</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`U'</term>
<listitem>
<para>uLaw encoding</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`l'</term>
<listitem>
<para>linear encoding</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`M'</term>
<listitem>
<para>monophonic</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`S'</term>
<listitem>
<para>stereo</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`s'</term>
<listitem>
<para>signed output</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`u'</term>
<listitem>
<para>unsigned output</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`x'</term>
<listitem>
<para>byte-swapped output</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Available interfaces (-i option):</para>

<para><variablelist>
<varlistentry>
<term>-iq</term>
<listitem>
<para>kmidi qt interface</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-id</term>
<listitem>
<para>dumb interface</para>
</listitem>
</varlistentry>
</variablelist>
</para>

<para>Interface options (append to -i? option):</para>

<para><variablelist>
<varlistentry>
<term>`v'</term>
<listitem>
<para>more verbose (cumulative)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`q'</term>
<listitem>
<para>quieter (cumulative)</para>
</listitem>
</varlistentry>
<varlistentry>
<term>`t'</term>
<listitem>
<para>trace playing</para>
</listitem>
</varlistentry>
<varlistentry>
<term>-i</term>
<listitem>
<para>mode Select user interface (see below for list) </para>
</listitem>
</varlistentry>
<varlistentry>
<term>-Bn</term>
<listitem>
<para>Set number of buffer fragments </para>
</listitem>
</varlistentry>
<varlistentry>
<term>-h</term>
<listitem>
<para>Display this help message</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>

<chapter id="questions-and-answers">
<title>Questions and Answers
 </title>
<sect1 id="where-to-get-a-full-patchset">
<title>Where to get a full patch set?
 </title>

<para>Please refer to the corresponding &lt;ref id=&quot;patches&quot; name=&quot;section&quot;&gt;
in the kmidi installation chapter.</para>
</sect1>
</chapter>


<chapter id="design">
<title>Design
 </title>
<sect1 id="processes">
<title>Processes
 </title>
<para>
KMidi is the user front end which handles the screen display and button
presses, etc.  It executes as a separate process from TiMidity, which
reads midi files and plays them.
</para>
</sect1>

<sect1 id="synthesis-model">
<title>Synthesis Model
 </title>
<para>
TiMidity has a tone generator, two envelope generators, three low frequency
sine-wave oscillators, a low pass filter, and an effects unit.  (The low pass
filter is used only when KMidi's fourth interpolation option is chosen and the
"filt" button is depressed -- at present it doesn't work well.)
</para>

<para>
The tone generator resamples instrument patches at the basic frequencies
appropriate for specific notes being played.  (The interpolation algorithm used
is selectable using the four checkboxes on the upper panel.)
</para>

<para>
The envelope generators modulate each note with successively: an attack phase, a
hold phase, a decay, and a release.  One of the generators affects amplitude,
and the other affects pitch and/or the cutoff frequency of the low pass filter.
</para>

<para>
The low frequency oscillators modulate amplitude (for tremolo), frequency (for
vibrato), and the low pass filter cutoff frequency (XG "rezo sweep").
</para>

<para>
The effects unit supplies echo, detuning, reverberation, chorusing, celeste, and
phaser effects.  Echo (done by generating extra echo notes) and reverbration
(done with a filter) implement midi reverberation.  Detuning (done by generating
extra pitch bent notes) and chorusing (done with a filter) implement midi
chorusing.  (The effects filters are active only when KMidi's "eff" button is
pressed on.  Echo and detuning can be controlled with the middle two checkboxes
on the right of the lower panel and from the Chorus and Reverb menus.)
</para>

<para>
Instruments may have either one or two tone elements, and for each of these, a
patch set may provide separate patches for different note-velocity ranges
(commonly for pianos) and for different note-pitch ranges.  GUS patch sets,
however, provide only one tone element and one velocity range per instrument.
(If you click the rightmost checkbox at the right of the lower panel, KMidi will
display in its info window the names of patches as it loads them, a "(2)" if
they have two tone elements, and the velocity range.)
</para>
</sect1>

<sect1 id="midi-implementation">
<title>Midi Implementation
 </title>

<para>Almost all midi messages and controllers that I'm aware of are implemented somehow
(meaning that they cause something to happen, if not necessarily the right thing).
NRPN controllers for setting attack and decay time are not implemented, because
I haven't found any midi files that use them.  The flanging controller is not
implemented (though flanging requested in an XG sysex dump is implemented).  Only
a few of the hardware oriented controls in Roland and Yamaha system exclusive
dumps are implemented.
</para>

<para>TiMidity can handle midi files meant to play on up to four synthesizers, keeping
separate the four sets of 16 channels for each synth.  However, in the midi file,
the synths have to be selected using port commands (in either Roland-GS or
Yamaha-XG sysex dumps).  Some midi files intended for multiple synths don't have
port commands.  (The info window shows port commands when present.)
</para>

<para>The KMidi vertical-bar display of channel activity is limited to two sets of 16
channels.  The channel chart of patches with horizontal bars for controller values
is limited to just one set of 16 channels.
</para>
</sect1>

<sect1 id="volume">
<title>Volume
 </title>

<para>I've reduced the volumes levels TiMidity generates quite a lot, as compared with
the original implementation.  This minimizes clipping and gives an increased
dynamic range.  (There may be some artifacts now at low volumes, unfortunately.)
If you need more volume, I suggest you turn up the volume somewhere else, either
use KMix to turn up the line volume, the mixer volume for /dev/dsp, or turn up earphones,
amplified speakers, or whatever.
</para>
</sect1>

<sect1 id="computation-issues">
<title>Computation Issues
 </title>

<para>TiMidity can fall behind in computing data to send out to the sound
driver, and then there are dropouts in the music.  TiMidity tries to anticipate
the possibility of a dropout by monitoring the state of its output buffer and
those of the sound driver, and when there is not much in the buffers, it tries
to catch up by minimising the calculations it has to do: it uses a cruder
interpolation routine in resampling, stops doing extra echo and detuned notes
for reverb and chorus effects, and starts terminating notes early, or even
skipping notes altogether.  So, depending on midi song, patchset, how fast your
system is, even if you don't hear dropouts, you will notice a loss in quality as
TiMidity gets busier.  KMidi's front panel lights give some picture of how
desperate TiMidity is becoming in its effort to keep the music playing.  (Signs
of desperation: the buffer led goes from healthy greenish to busy orangeish, the
interpolation led turns off (meaning linear interpolation is being used for
resampling), the echo led goes off, or the detuning led goes off (meaning no
extra echo or detuned notes are being played).
</para>

<para>Monitoring the output buffer involves calling the sound driver to find out
how much data it has buffered up.  I know how to do this for Hannu Savolainen's
OSS driver (Linux and some other systems), perhaps for older Suns (it used to
work), but not for other drivers.
</para>

<para>You can lighten TiMidity's computational burden by various maneuvers: (1)
reduce the permitted polyphony (spin box on lower panel), (2) press off the
"eff" button, (3) choose cheaper resampling interpolation (one of the checkboxes
on the upper panel further to the left), (4) turn off echo, detuning, or stereo
using the left three checkboxes on the lower panel, (5) choose the "dry" setting
on the Reverb menu.  Of course, there is generally some attendant loss in
quality.  Having the "filt" button on doesn't cost anything unless you've also
chosen the "cspline+filter" interpolation option.
</para>
</sect1>

<sect1 id="memory-issues">
<title>Memory Issues
 </title>

<para>It's possible for TiMidity to use an excessive amount of memory for
patches.  Symptoms are your window system becoming very sluggish, or crashing.
This is probably only a problem when using big sf2 soundfonts of 30+ megabytes.
For instance, the piano patches in Personal Choice's PC400 soundfont can occupy
25 megs each.  After playing a list of midi files which use three of these
pianos, well, that's 75 megs of ram right there.  In its configuration dialog,
KMidi lets you set a maximum number of megs to be used to keep patches used in
playing previous midi files; when this maximum is exceeded, TiMidity will unload
least recently used patches, returning ram to the system.  The default maximum
is 60 megs, which works ok on my system (I have 48 megs ram and 196 megs cache).
Setting this to a lower value means that more patches have to be reloaded from
patch files as you play through a list of midi songs, which slows things up.  If
you're ram rich, you can set it to "no limit".  If you allowed enough room,
entire soundfont files are read at once, instead of patch by patch.  Setting the
maximum too low can be counterproductive, because soundfont files occupy much
less memory in toto when the entire file is read than when the patches are read
individually (I don't know why).
</para>

<para>For little-endian systems like x86, rather than being read in, sf2 soundfonts are
mmapped.  This is much faster on startup.  I haven't figured out a way to do this
for big-endian systems.
</para>

<para>After playing each midi file, KMidi will report in the info window on how much memory
is currently occupied by patches.
</para>

<para>If you don't have much ram or cache memory, setting a low maximum for patch memory
might not prevent KMidi from crashing your system.  So be careful using big soundfonts.
</para>
</sect1>

</chapter>

<chapter id="credits">
<title>Credits
 </title>

<para>KMidi uses Tuukka Toivonen's TiMidity 0.2i engine Copyright (C) 1995 <ulink url="mailto:toivonen@clinet.fi">Tuukka Toivonen</ulink>.
In fact, an enhanced version of Tuukka's original program with five other alternative
user interfaces is included with the KMidi distribution. (See below for information
on compiling TiMidity.) KMidi and TiMidity use AWE SoundFont extensions done
by <ulink url="mailto:iwai@dragon.mm.t.u-tokyo.ac.jp">Takashi Iwai</ulink> and AMD InterWave extensions done by <ulink url="mailto:lee@hawaii.edu">Greg Lee</ulink>, which enable you to use SoundFonts
(.sbk/.sf2 files) and IW patchsets (.fff/.dat files) in addition to Gravis/Forte
.pat files.</para>


</chapter>


<chapter id="copyright">
<title>Copyright
 </title>

<para>KMidi Copyright 1997 Bernd Johannes Wuebben <ulink url="mailto:wuebben@kde.org">wuebben@kde.org</ulink></para>

<para>KMidi uses Tuukka Toivonen's timidity 0.2i engine, Copyright (C) 1995 Tukka
Toivonen <ulink url="mailto:toivonen@clinet.fi">(email)</ulink>.</para>

&underFDL;
&underGPL;

</chapter>


<appendix id="installation">
<title>Installation
 </title>
<sect1 id="how-to-obtain-kmidi">
<title>How to obtain KMidi</title>

<para>KMidi is part of the KDE project <ulink
url="http://www.kde.org"></ulink>. KMidi can be found on <ulink
url="ftp://ftp.kde.org/pub/kde/"></ulink>, the main ftp site of the KDE
project. </para>
</sect1>
<sect1 id="requirements">
<title>Requirements
 </title>

<para>In order to successfully compile KMidi, you need appropriate versions of
the program libraries in
<literal remap="tt">kdelibs</literal>. All required libraries as well as KMidi itself can
be found on <ulink url="ftp://ftp.kde.org/pub/kde/"></ulink>. </para>

<para>To compile the ``dumb'' commandline interface of TiMidity, any standard
Unix-type system should do. The other interfaces have special
requirements (see the various README files in the distribution). The Motif
interface works reasonably well with Lesstif, but better with Motif.</para>
</sect1>
<sect1 id="compilation-and-installation">
<title>Compilation and installation
 </title>

<para>If you previously installed KMidi, it would be wise to move your
configuration directory (probably &dollar;KDEDIR/share/apps/kmidi/config/)
before installing this version, since the files that go here have changed, and
you'll want to use or at least look at the new versions. Similarly, before
installing the non-KDE version of TiMidity, back up
/usr/local/lib/timidity/*. On the other hand, for a completely fresh install you
should remove any files in these two directories, since the old files might not
be replaced by new versions. </para>

<para>If you have the entire kdemultimedia distribution, cd to the kdemultimedia
directory and</para>

<para><programlisting>&percnt; ./configure
 </programlisting>
</para>

<para>Alternatively, to include all of the other user interfaces:</para>

<para><programlisting>&percnt; ./configure --enable-interface=ncurses,xaw,gtk,tcltk,slang,motif
 </programlisting>
</para>

<para>Then to make all the multimedia programs, stay in that directory, or to
make just KMidi, cd to the kmidi directory, and</para>

<para><programlisting>&percnt; make
&percnt; make install
 </programlisting>
</para>

<para>The non-KDE version of TiMidity, <literal remap="tt">timidity</literal>,
is compiled and installed at the same time as KMidi.  (The man page
<literal remap="tt">timidity.1</literal> is not, however, automatically
installed in <literal remap="tt">/usr/man/man1/</literal>, )
</para>

</sect1>
<sect1 id="patches">
<title>Where to get a full set of patches?
 </title>

<para>There are two sorts of patches that KMidi/TiMidity can use: GUS patches
and AWE32 SoundFonts (<literal remap="tt">sf2</literal> files).  A set of
samples and parameters for a single instrument, a patch, is in a separate file
for GUS patches, but AWE SoundFonts put everything in a single<literal
remap="tt"> .sf2</literal> file (or <literal remap="tt">.sbk</literal>). </para>

<para>I recommend <literal remap="tt">.sf2</literal> SoundFonts, and of those,
the Chaos fonts mentioned below, in preference.)</para>

<para>Open up KMidi's configuration window for pointers to some web pages
with patch sets.  Here are some other places to get patches:</para>

<para><ulink url="mailto:goemon@anime.net">Dan Hollis</ulink> has put together a
patch set. Please visit his page at <ulink
url="http://www.anime.net/~goemon/timidity">http://www.anime.net/~goemon/timidity</ulink>
and help him make this the best set available.</para>

<para><emphasis remap="bf">New:</emphasis> I have uploaded the above patchset to
ftp.kde.org. It is currently in <ulink
url="ftp://fiwi02.wiwi.uni-tuebingen.de/pub/kde/stable/Beta2/apps/multimedia/sound/">ftp://fiwi02.wiwi.uni-tuebingen.de/pub/kde/stable/Beta2/apps/multimedia/sound/</ulink>&lt;but
I expect we will move it around a bit until we found a good location for it. So
just poke around a bit on ftp.kde.org, if the set can no longer be found at the
above mentioned location by the time you read this.</para>

<para>Patches can also be found packaged as dep or rpm modules on the Sunsite
archive:</para>

<para><itemizedlist>
<listitem>
<para>Debian: <ulink url="ftp://sunsite.unc.edu/pub/Linux/distributions/debian/bo/source/sound/timidity-patches_0.1.tar.gz">timidity-patches_0.1.tar.gz</ulink>u</para>
</listitem>
<listitem>
<para>RPM: <ulink url="ftp://sunsite.unc.edu/pub/Linux/distributions/redhat/contrib/oldrpms/contrib-2.0.x/RPMS/timidity-patches-1-1.i386.rpm">timidity-patches-1-1.i386.rpm</ulink>u</para>
</listitem>
<listitem>
<para>RPM: <ulink url="ftp://sunsite.unc.edu/pub/Linux/distributions/redhat/contrib/oldrpms/contrib-2.0.x/SRPMS/timditiy-patches-1-1.src.rpm-try2">timidity-patches-1-1.src.rpm-try2</ulink></para>
</listitem>
</itemizedlist>
</para>

<para>I have not tried the above (yet), and personally use the Midia patch set
together with a few additional patches and a couple of additional drum sets.
The Midia patch set can be found at: <ulink
url="ftp://archive.cs.umbc.edu/pub/midia/">ftp://archive.cs.umbc.edu/pub/midia/</ulink>.</para>

<para>For additional patches and drum sets: (get the gsdrum and wow patches)
<ulink
url="ftp://ftp.cdrom.com/pub/gus/sound/patches/files/">ftp://ftp/cdrom.com/pub/gus/sound/patches/files/</ulink>.</para>

<para>Vincent Pagel has put together a collection of patches. This link can only
be reached during night hours (Paris). <ulink
url="ftp://sig.enst.fr/pub/midi/instruments/">ftp://sig.enst.fr/pub/midi/instruments/</ulink>. The
config file that goes with his patch set can be found <ulink
url="ftp://sig.enst.fr/pub/midi/timidity_pagel.cfg">here</ulink>.</para>

<para>Also check the <ulink
url="http://www.clinet.fi/~toivonen/timidity/">Timdity Page</ulink></para>

<para>and <ulink
url="bahamut.mm.t.u-tokyo.ac.jp/~iwai/midi.html#TiMidity">Takashi's
page</ulink>. Takashi's page recommends the 8 meg AWE32 SoundFont <literal
remap="tt">chaos8m.sf2</literal> and the 12 meg AWE32 SoundFont <literal
remap="tt">chaos12m.sf2</literal> available at <ulink
url="http://soback.kornet.nm.kr/~chaos/sbawe32/sbawe32.htm"></ulink>, which are
very nice.  (They are packaged as self-decompressing <literal
remap="tt">.exe</literal> files.)</para>

<sect2 id="patch-set-installation">
<title>Patch set installation</title>

<para>Some of the above patch sets come with a <literal
remap="tt">.cfg</literal> configuration file similar to the .cfg files which
come with KMidi and reside in <literal
remap="tt">KDEDIR/share/apps/kmidi/config</literal>.  KMidi has configuration
files ready made for you for a number of common patch sets, such as the media
patch set. For <literal remap="tt">.sf2</literal> SoundFonts, a utility program
is supplied, <literal remap="tt">sf2cfg</literal>, which constructs a <literal
remap="tt">.cfg</literal> file from a <literal remap="tt">.sf2</literal>
font. This is compiled along with timidity.</para>

<para>It is not necessary to give <literal remap="tt">.cfg</literal> files names
with a <literal remap="tt">.cfg</literal> extension. They are ordinary text
files whose structure is described in another section of this manual.</para>

<para>In order to complete the installation of a complete patchset edit the file
<literal remap="tt">timidity.cfg</literal> and source the appropriate config
files for the patch set/sets you downloaded. Look at <literal
remap="tt">timidity.cfg</literal> for an example. That's it. Now you can go
ahead and and play the other midis that are in the KMidi distribution ( and any
others of course).</para>
</sect2>
<sect2 id="miscellaneous">
<title>Miscellaneous
 </title>

<para>Occasionally you will see that KMidi can't find a patch for a particular
instrument. ( Open the Info Window in order to see this information ) In that
case, all you have to do is go out and get yourself the missing patch and
install it by moving the patch into the patch/ directory and editing your patch
set .cfg file to tell KMidi that the new patch is available now. </para>

<para>Sometimes a particular instrument doesn't sound all that well. In that
case, simply go out and get yourself a different patch from any of the
Ultrasound archives and replace the not so optimal patch by a better one. As you
can see, it is totally up to you how good every instrument will sound. You can
even make your own patches with the pat2wav utility which is included in the
KMidi distribution.</para>
</sect2>
</sect1>
</appendix>

</book>
<!--
Local Variables:
mode: sgml
sgml-omittag: nil
sgml-shorttag: t
End:
-->
