GENERAL:

This program allows you to import output from HARMONIC.EXE to temper pre-existing midi files according to predefined or "roll-your-own" scale tempers. It is provided as an alternative to MidiTemp, and uses a different approach to tempering. Whereas MidiTemp adjusts every note in the midi file, PianoTuner creates a new midi track (each on its own channel) for each of the twelve tones. The notes from the source file are then transferred into the appropriate track.

PianoTuner thus overcomes the chorded and overlapping notes limitation of MidiTemp. However, it is suitable for use only with files that use a single instrument patch. It is primarily intended for piano and harpsichord music (hence the name). However, PianoTuner only works on Type 0 source midis. The automatic conversion facility has been removed because Günter Nagler now demands an exhorbitant payment for the inclusion of his "freeware" conversion utility. I therefore highly recommend that you obtain Jeff Glatt's excellent freeware "Midi File Converter" for easy conversion from Type 1 to Type 0 format as required by this program.

INSTALLATION:

The self-extracting install program will, by default, place the program and all support files into the C:\HARMONIC directory, but you can override this by specifying a different extraction directory. It will also create the following subdirectories:

\DAT - for temperament files exported from Harmonic Analyser, for reimport into Piano Tuner.
\DOCS - Documentation (including this file)
\MIDI - Midi files (source and destination)
\SCL - for "Scala" format .SCL files
\SOURCE- The qbasic source files for these programs. May be deleted if you don't intend to study/modify the programs.

USAGE IN DOS:

See HARMONIC.TXT for instruction on installing the distribution package. After extraction, all you have to do to run the program is enter PIANOTUN at the command prompt.

USAGE UNDER WINDOWS:

This and the other programs in the suite will run fine under most versions of Windows, the notable exception being Win2000 (under which keyboard difficulties have been reported). After running the self-extracting install executable, you can create links ("shortcuts") to your desktop or Start Menu (32 bit Windows versions) or Program Groups (16-bit Windows versions)

WIN3.x

Using File Manager, drag-and-drop pianotun.pif into your desired program group. You'll just have a generic DOS icon at this point. Click on it to select it, then in the Program Manager window click File -- > Properties. Click on "Change Icon", Windows will tell you no icon is associated with that file. Ignore that bit of wisdom, and browse to your directory and select pianotun.ico.

To adjust window/font size, bring up the program by double-clicking its icon, then click the system button at the upper-left corner, select Fonts. . . and adjust according to taste. Windows will remember your settings in the future.

WIN9x

Using Windows Explorer, drag and drop harmonic.pif (usually shows up as just "pianotun") into your destop folder of choice. At this point you'll just have a generic DOS icon. Right-click on it, select Properties. Click the Program tab. Click the Change Icon button. Click Browse. Find your way to the directory (folder) containing pianotun.ico, click on it and then click the Open button. Click OK. Now fill in the "Working" field with the path to pianotun.exe, example: c:\myfiles\music\weirdstuff\. Click OK. You'll now be all set to go.

To adjust font-size, right-click on the icon, select Properties, click on the Fonts tab, and adjust according to taste and proclivity. Windows will remember the setting the next time you use it (if all goes well...)

USING THE PROGRAM:

1. Create your temperament file.
   
   When you first start Piano-Tuner, it asks you to input the filename of the temperament data (.dat) file. Note that default is in the \DAT subdirectory. (If you enter a full path-name, this overrides the default.) If you press ENTER only, the filename HARMONIC.DAT is assumed. If it doesn't find it, you have to exit and create it using HARMONIC.EXE. A sample HARMONIC.DAT file is provided for those who want a quick-start. This is the Werckmeister temperament, centred at A=432, tonic C.
   
   
2. Specify the midi file to process.
   
   The source midi should ideally be in the \MIDI directory, but a full path name is also allowed (re-enabled in V2.3a). The midi file MUST be in Type 0 format (all events on one single track). An excellent freeware utility by Jeff Glatt called "Midi File Converter" is available from his website. Please note also that, although the program will blithely process any valid Type 0 midi file, you will ONLY get proper results if the midi files meet the following criteria:
   
   
   1. The resulting midi will be on a single instrument patch. Multiple patches in the source midi are allowed, but will be reduced to the single patch you specify. (Exception: events on the percussion track channel 10 will be unchanged.)
      
      
   2. There should not be a heavy reliance on volume, pan and other controllers on a per-channel basis, even though some flexibility is provided for handling such events.
   
   
   If the specified filename exists in the \MIDI subdirectory, (or in the path you explicitly define) you'll be prompted to give a different name, or exit.
   
   A simple sample midi file meeting the above requirements is provided in the \MIDI subdirectory as test.mid, again for those who want to jump right in and play.
   
   
3. Specify the output filename.
   
   If the specified filename exists in the \MIDI subdirectory, (or in the path you explicitly define) you'll be prompted to give a different name, or exit. As throughout the program, entering a filename only assumes the default directory (\MIDI in this case), but if a drive spec is included (e.g. C:\MYDIR\... ) then the path is followed. Exception: if the filename exists but has length zero, you will be allowed to use it.
   
   
4. Edit temperament if necessary.
   
   The imported temperament data is now displayed for your edification. If your temperament has less than 12 tones (e.g. the Persian temperaments), you'll be warned that undefined notes will be treated as "no pitch bend from equal-tempered default." The channels associated with these tones will simply be assigned a pitch bend of zero.
   
   If your temperament has more than 12 tones (different values for one or more enharmonics) you'll have to make an editorial decision on which one(s) to use. Too bad that midi only specifies twelve tones.. and too bad that this program isn't smart enough to figure it out for you. For many tempers, the choice shouldn't be too hard, remembering that one enharmonic is usually much more common than the other. For example, in the key of C, it's much more likely to encounter C#, Eb, F#, G# and Bb than the corresponding Db, D#, Gb, Ab and A#. That being said, which ones are correct will depend on the harmonic structure of the piece you're working on.
   
   The problem is especially sticky in fancy temperaments like 19-tone 5-limit Just Intonation, where you have (count 'em) up to three possible pitches for some notes. What can I say, except that perhaps this program is not particularly well suited for such temperaments. Notwithstanding that, real purists can at least get the bulk of the work done automatically, fixing up the oddballs manually using an external sequencer. It should be noted that when PianoTuner gets done with its work, you'll still have three channels available for your enharmonic options.
   
   
5. Select processing options:
   
   You are now presented with several options for handling existing control messages. In almost all cases, it's best to simply use the defaults (by pressing Enter only). The options are provided mainly for advanced users and serious experimenters.
   
   1. Channel volume handling. The default is to import all existing volume controllers into all channels. The other option prompts you for an overall volume level, which is applied to all channels. Any pre-existing volume controllers are removed.
      
      
   2. Channel pan handling. Analogous to volume handling. Again, the default is recommended for most uses.
      
      
   3. Pitch-bend handling. The default recomputes any existing pitch-bends relative to the "unbent" value for each channel, and applies to each channel, the option removes them.
      
      
   4. Other controllers. Again, you can choose to delete other controllers, or to retain them by applying to all channels.
      
      
   5. Sysex commands. You can choose to place them all into the master track, or remove them entirely.
      
      
6. Choose an instrument patch:
   
   You are then asked for an instrument patch. There isn't quite enough room on a single DOS screen to display them all, but rest assured that the ones that aren't shown are very unlikely to benefit from tempering (things like helicopter noises, bird tweets, and gunshots...).
   
   
7. Let 'er rip!
   
   And away it goes. Press any key to start the conversion process.
   
   All events on channel 10 (the percussion track) are left alone. Tempering an atonal instrument is rather pointless, and ignoring channel 10 helps reduce the loading on your synth.
   
   
8. All done!
   
   When complete, the output filename is given (in case you forgot it), and the file written to the \MIDI subdirectory. Press any key to exit the program. If Piano Tuner was called from the Harmonic Analyser End menu, you are returned to that menu for further editing, creating additional tempered midis, or any of the other Harmonic Analyser options.