midi_in(1)

NAME
midi_in - plugin midi synthesizer for alsaplayer

SYNOPSIS
midi_in is used by interfaces for alsaplayer(1) to play midi files.

DESCRIPTION
midi_in is derived from TiMidity, which is a MIDI to WAVE converter using Gravis Ultrasound-compatible patch files or AWE-compatible SoundFonts to generate digital audio data from General MIDI, GS, or XG midi files.

When it is plugged in to alsaplayer, it is given file names, and it examines the files to see if they contain midi data (it does not care whether the file name ends in ".mid"). When a file does have midi data, midi_in tells alsaplayer it can handle the file; otherwise, the file name will be passed to some other plugin (or rejected).

Alsaplayer then asks midi_in to open the file and determine some facts about it: title, author, playing time. midi_in can tell the playing time, but usually cannot figure out the author or title, so the playing time is all the alsaplayer interface will display for you.

If you decide to play the file, alsaplayer tells midi_in to play it, and midi_in reads the file, uses it's instrument patches to convert midi events into a stream of samples, and directs this stream back to alsaplayer, which sends the samples to an output plugin. Then, if all goes well, you hear the music.

PANEL DISPLAY
Supposing that you are using the Gtk interface to alsaplayer, as a midi file is playing, you will see on the top line of the little information window either the name of the midi file, or possibly the title and/or author information from inside the midi file, if midi_in could find any.

Below this is a line saying whether the midi file is a GM (General Midi), a GS (with Roland extensions to GM), or an XG file (with Yamaha extensions to GM/GS). The line also says how many tracks the file has and how many midi events are in it.

To the right is a continuously updated display of how many concurrently sounding notes midi_in is dealing with. To make sense of the numbers displayed here (in case you're interested), you should know that midi_in usually works a second or two ahead of the music that you're hearing, and also that extra notes are generated to approximate reverberation and chorus effects, so often the numbers you see reported are much higher than the number of distinct notes that can be picked out by ear. Some instrument patches are in stereo, so this also adds to the number of notes midi_in actually generates, but which merge perceptually. (A single perceived note played with chorus and reverberation on a stereo patch requires at least 6 notes to be played.)

There is only a theoretical limit of 256 simultaneously sounding notes, since before the polyphony gets this high, midi_in has to terminate some notes early, to give itself enough time to calculate samples fast enough to keep up with the music. Unless, I suppose, you have a very powerful computer.

OPTIONS
Currently, it is not possible to pass any options or configuration information to midi_in from alsaplayer. It is possible to set some options for midi_in using a patch configuration file called timidity.cfg. It's rather involved, and I hope you don't need to do it. The details are described later.

FILES

PC42b.sf2

To work at all, midi_in requires instrument patches. It doesn't have any built in, so you have to supply them. That can be done very simply by acquiring the soundfont file PC42b.sf2 and putting it where midi_in can find it. The author of this "Personal Copy" soundfont, Jim Roe, very kindly allowed it to be distributed along with midi_in, so it you don't have it already, look for the file PC42b.tar.gz wherever you got the midi_in distribution, unpack it, and put the soundfont itself, PC42b.sf2 either in the subdirectory .alsaplayer/ of your home directory or else in the directory /usr/local/share/timidity/. (Actually, this last path name is just the default -- midi_in could have been configured to look in some different directory.)

That's the easy way to provide instrument patches. There are alternatives that provide more flexibility but require more work.

xxxx.sf2

If you have your own favorite soundfont of instrument patches, or just want to try some alternatives to PC42b.sf2, you can do that in the following way. Go to your .alsaplayer/ subdirectory of your home directory and move away or delete PC42b.sf2 and any file timidity.cfg that is there. Then put the new soundfont you'd like to use there, or perhaps just a soft link to it. When midi_in is next used, it will notice the new soundfont and construct a file timidity.cfg for it, which contains information about the structure of the soundfont. Then the new soundfont will be used. For this to work, the soundfont file name has to end in either ".sf2" or ".SF2".

Since midi_in has special knowledge of the Personal Copy soundfont, it can make some substitutions appropriate for playing GS and XG midi files when you use PC42b.sf2. For other soundfonts, that can't be done.

The file timidity.cfg that is contructed for a new soundfont and left in .alsaplayer/ is a text file which you can edit to add options, add, remove or modify information about individual patches within the soundfont, or bring in additional soundfonts. There's hardly any end to the possible elaborations for enriching the set of instrument patches available to midi_in as it plays midi files.

timidity.cfg

midi_in looks for the configuration file timidity.cfg at startup, before processing any options.

Configuration files define the mapping of MIDI programs to instrument files. Multiple files may be specified, and statements in later ones will override earlier ones. The following statements can be used in a configuration file:

-p voices
    Sets polyphony (maximum number of simultaneous voices) to voices.

-A amplification
    Multiplies the master volume by amplification%.

-X curve
    With the value 0, the midi expression controller affects the volume linearly. With 1 (the default) or 2, it affects volume exponentially.

-V curve
    With the value 0, the midi volume controller affects the volume linearly. With 1 (the default) or 2, it affects volume exponentially.

-C ratio
    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.

-s frequency
    Sets the resampling frequency. Not all sound devices are capable of all frequencies -- an approximate frequency may be selected, depending on the implementation.

-k  number
    Select interpolation algorithm for resampling: 0 for linear interpolation, 1 for cspline interpolation, 2 for LaGrange interpolation, 3 for cspline interpolation with low-pass filtering.

-r  number
    Set maximum of ram in megabytes to use up keeping patches from previously played midi files. This should presumably be less than your total ram plus disk cache size. The default is 60 megabytes. It probably doesn't matter unless you're using big sf2 soundfont patchsets.

dir directory
    Adds directory to the search path in the same manner as the -L command line option.

source file
    Reads another configuration file, then continues processing the current one.

sf file [option]
    Reads the parameters and waveforms in an AWE-compatible SoundFont file. Both ".sbk" and ".sf2" SoundFonts can be used. Preceding patch mappings must list all patches that are to be loaded from the file, and the preceding bank/drumset keywords must be followed by sf. The options allowed are:

    banknumber
        The bank number given in the first preceding "bank"/"drumset" statement is to be used in place of the bank banknumber given in the SoundFont itself.

bank number [option]
    Selects the tone bank to modify. Patch mappings that follow will affect this tone bank. The options allowed are fff and sbk, which were described above.

drumset number [option]
    Selects the drum set to modify. Patch mappings that follow will affect this drum set. The options allowed are fff and sbk, which were described above.

sfx Selects the XG non-rhythm SFX bank to modify. Patch mappings that follow will affect this tone bank.

drumsfx1

drumsfx2
    Select the XG rhythm SFX banks to modify. Patch mappings that follow will affect these tone banks.

number file [options]
    Specifies that the the MIDI program number in the current tone bank or drum set should be played using the patch file. options may be any of the following:

    amp=amplification
        Amplifies the instrument's volume by amplification percent. If no value is specified, one will be automatically determined whenever the instrument is loaded.

    note=note
        Specifies a fixed MIDI note to use when playing the instrument. If note is 0, the instrument will be played at whatever note the Note On event triggering it has. For percussion instruments, if no value is specified in the configuration file, the default in the patch file will be used.

    tuning=cents
        Changes the pitch of the instrument. cents is a signed quantity in units of 1/100th of a semitone, so, e.g., specify "+1200" to go up an octave. The number must begin with a "+" or a "-".

    pan=panning
        Sets the instrument's default panning. panning may be left, right, center, or an integer between -100 and 100, designating full left and full right respectively. If no value is specified, the default in the patch file will be used. Note that panning controls in MIDI files will override this value.

    keep={loop|env}
        Strangely shaped envelopes are removed automatically from melodic instruments in GUS patches. keep can be used to prevent stripping envelope or loop data. (Stripping envelopes was originally the default for TiMidity, but in this version it's not. So these options are no longer useful -- they are kept for compatibility. G.L.)

    strip={loop|env|tail}
        Force removal of loop or envelope information from all patches in the instrument, or strip the tail, i.e. all data after the loop. Some third-party instruments have garbage after the loop, as evidenced by a clicking noise whenever the instrument is played, so adding the strip=tail option will markedly improve sound quality.

COPYRIGHT
Copyright (C) 1995 Tuukka Toivonen.
See AUTHORS below for additional copyrights.

midi_in is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

midi_in is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

AVAILABILITY
Presently available by cvs from the alsaplayer area at www.sourceforge.net.

BUGS

Eats more CPU time than a small CPU-time-eating animal.

AUTHORS
Tuukka Toivonen <toivonen@clinet.fi>
AWE SoundFont support by Takashi Iwai <iwai@dragon.mm.t.u-tokyo.ac.jp>
IW patchset support, karaoke, AWE/XG enhancements, much reworking of the code, conversion to alsaplayer plugin by Greg Lee <greg@ling.lll.hawaii.edu>
Effects filter by Nicolas Witczak <witczak@geocities.fr>, see URL http://www.geocities.com/SiliconValley/Lab/6307/).
Portamento, mod wheel, and other enhancements from TiMidity++ Copyright (C) 1999 Masanao Izumo <mo@goice.co.jp>. See URL http://www.goice.co.jp/member/mo/hack-progs/timidity.html.