
---------------------------  !Midiphile  (0.25)  ---------------------------

                         Copyright : Somascape 1997

                               Author : Lenny

----------------------------------------------------------------------------

0.0  Contents
     ========

     1.0  Overview
     2.0  A Quick Operational Outline
     3.0  The Iconbar Icon and Menu
     4.0  The Panel Window
     5.0  Configuration of Options
     5.1    'Describe' options
     5.2    'Clean' options
     6.0  MIDI File Structure
     7.0  MIDI File Description
     8.0  Miscellaneous / Technical
     8.1    Pre-scanning files
     8.2    Output files
     8.3    The 'Process' operation and hanging notes
     8.4    Functions disabled during 'Process'
     8.5    Cleaning Duplicate and Excess Note events
     8.6    Note Re-triggering (overlapping notes)
     8.7    Problems with Cleaning Duplicate events
     9.0  User Options in the Messages file
    10.0  Further reading

----------------------------------------------------------------------------

1.0  Overview
     ========

This application is a utility for those wishing to :

  a) investigate the contents of MIDI files,
  b) clean redundant/unwanted data from MIDI files.
 
It has two distinct modes of operation, reflecting these two functions :

  Describe : A Text file is produced containing an interpreted description
             of the contents of the file.  Note that the resultant files
             can be quite large (10x or more bigger than the source MIDI
             file).

  Clean :    Redundant (or just unwanted) events will be removed from the
             file.

For each mode, it is possible to restrict the range of tracks to be
processed.  There are also filters (specific to each mode) which can be
used to target specific types of event for description / removal.

The program is controlled via two main windows - a main Panel window and an
Options window.  The program fully multi-tasks whilst processing a file.

----------------------------------------------------------------------------

2.0  A Quick Operational Outline
     ===========================

 1  Open the Panel and Options windows (click SELECT and then MENU on the
    iconbar icon, and then select 'Options...' from the iconbar menu).
 2  Set the required mode (Describe or Clean) in the Panel window.
 3  Ensure that the required Describe/Clean options are set, to target the
    required data types (see section 5.0, below).
 4  Drag the MIDI file to be processed onto the 'in' drop icon.
 5  Restrict the range of tracks, as required.
 6  Optionally amend the output filename, and drag the 'out' file icon to
    the required destination directory.
 7  Click on 'Process'.

This sequence of events does not need to be tightly adhered to, steps 2-4
may be performed in any order.  Whenever dragging a source file to the
'in' icon, the track range is initially set to include all tracks within
that source file.


The function of the 'Remember destination path' toggle is to aid batch
processing.  When it is ticked, the path part of the output
filename will remain fixed, though the leafname will change whenever
dragging another MIDI file to the 'in' icon.

Eg.  To remove (Clean) AllNotesOff (Controller 123) events from a number
     of MIDI files and place the cleaned versions of the files in a newly
     created directory (ie leaving the original files intact) :

      * Drag the first MIDI file to the 'in' icon;
      * Set Clean mode; Ensure Clean options (Filtered, ANO);
      * Drag the 'out' icon to your chosen output directory;
      * Click on 'Process';
      * Ensure 'Remember destination path' is ticked;
      * Then for each remaining MIDI file, drag it in and click 'Process'.

     Without 'Remember destination path' ticked, you would have to drag
     out the 'out' icon after dragging in each MIDI file (unless you don't
     mind the output files appearing in the source directory).

A similar procedure applies if you want to Describe a batch of MIDI files.


It is also possible to process PC-sourced MIDI files that have a Data
filetype and a leafname ending '/MID' (or a case independant truncated
version of that).  Many of the MIDI files to be found on the net are
available in this form within zip archives, and using SparkFS, Midiphile
is able to process such files whilst they are still within the archive.

----------------------------------------------------------------------------

3.0  The Iconbar Icon and Menu
     =========================

Click SELECT on the iconbar icon to open/surface the main Panel window.
Using ADJUST will open/close the Panel window.

Click Ctrl-SELECT on the iconbar icon to open/surface the Options window.
Using Ctrl-ADJUST will open/close the Options window.

Click MENU on the iconbar icon to popup the iconbar menu, containing three
items :

 * Info : The usual.  Additionally, it contains a pair of buttons :
   * Email : Attempts to open a Write email window (addressed to me).
   * Web   : Attempts to log onto my web site (software area).

 * Options : Open the Options window.

 * Quit : The usual.

----------------------------------------------------------------------------

4.0  The Panel Window
     ================

Working down from the top of the window ...

  Input Drop Zone : The MIDI file to be processed should be dropped onto
    this icon.  When this is done, the three icons immediately below
    update to show the file's leafname, format type, and the number of
    tracks within it (strictly the number of MTrk chunks).

  Operating mode : These two radio icons set the operating mode : Describe
    or Clean.

    Note that if a source MIDI file has been dragged to the dropzone and
    if the output filename has not been manually edited, the output
    filename will be recalculated according to the relevant 'Output
    filename' setting in the Describe/Clean Options.

  Process tracks : These two numeric fields show the range of tracks to be
    processed.  The values may be altered by clicking on them with SELECT
    or ADJUST (to decrease or increase, respectively).

    Note that when Cleaning a file, all tracks will be copied, though only
    those specified by the range will be processed (cleaned).

  Include track 0 : Only relevant for 'Describe' operations, and then
    only for format 1 MIDI files.  For format 1 files, the first track
    (track 0) is a global tempo track.  Ticking this option ensures that
    the tempo track is included in the output file, irrespective of the
    specified track range.

  out : This draggable file icon will be a Text file icon (&FFF) if the
    operating mode is 'Describe', otherwise it will be a MIDI file icon
    (&FD4).  It should be dragged to a filer window.  You will be
    prevented from dragging it to an application, as the output file is
    generated byte-by-byte using File_Write type commands (ie direct to
    disc).

  Output filename : This is a writable text icon enabling you to specify
    the filename of the output file.

  Remember destination path : When this is ticked it serves as an aid to
    batch processing by fixing the path element of the output filename. 
    Refer to section 2.0 for an example of its usage.

At the bottom of the window are three buttons :

  Cancel : Nulls all of the fields in this window and then closes it.  If
    the ADJUST button is used, the window will not be closed.

    If you just want to close the window without also clearing its
    contents, then use the window's close icon (or click ADJUST on the
    iconbar icon).

  Options... : Clicking with SELECT opens/surfaces the Options window. 
    Using ADJUST opens/closes it.

  Process : Starts the Describe or Clean operation. The window is extended
    revealing a moving bar which indicates progress.  Note that whilst a
    file is being processed, the 'Process' button is relabled 'Abort'.

    When aborting a Describe operation, the text 'Process aborted' is
    appended to the output file.

    When aborting a Clean operation, the partial output file is deleted.

    If the output filename field contains the caret, then pressing the
    RETURN key will also start the process.


Note that there is a subtle difference between closing the Panel window
with the window's close icon and with the Cancel button.  The latter nulls
all of the fields in the Panel window (which you won't notice until you
re-open the Panel - unless you clicked with ADJUST).

----------------------------------------------------------------------------

5.0  Configuration of Options
     ========================

The Options window can be opened either from the iconbar menu or from the
'Options...' button in the Panel window.

There are two groups of options, one for each mode (Describe and Clean).
Each group is accessed using the two radio icons on the right in the
Options window.

Below these two radio icons are four buttons :

  Default : This will reload any previously saved Options file.  If the
    Options file does not exist then an internal set of defaults are used.

  Save : Saves the current settings in an Options file.  This will be used
    as the default when next loading the program.

  Cancel : Closes the Options window leaving the settings in their
    previous state.

  Set : The current settings for both 'Describe' and 'Clean' options will
    be adhered to for any subsequent file processing.

Using ADJUST (on any of these buttons except 'Cancel') will not close the
window.

The state of the 'Include track 0' and 'Remember destination path' settings
(in the Panel window) are also saved as part of the Options.

Note that as of version 0.21, !Midiphile will make use of Boot:Choices to
store its Options file, if the new boot structure is detected.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

5.1  'Describe' options
     ~~~~~~~~~~~~~~~~~~
These are grouped into 4 sections : Describe, Timing, Filter settings and
Output filename :

 * Describe  (what data is interpreted and shown in the output file)
   ~~~~~~~~
   * All data      : Each and every event (MIDI, SysEx and Meta), for the
                     range of tracks specified, will be described.
   * Filtered data : Only those events targetted by the filter settings
                     will be described.
   * Totals        : If ticked, the totals of each type of event (that is
                     ticked in the filter settings) will be shown at the
                     end of each track.
   * inc Zeros     : If ticked, then even zero-totals will be reported.
                     Again, this only applies to events specified by the
                     Filter settings (ie ticked).

 * Timing
   ~~~~~~
   * Delta     : The delta time associated with each event (ie since the
                 previous event) will be shown.  Note that if 'Filtered
                 data' is selected, then delta time reporting is
                 disallowed.  (Knowing the delta-time of a specific event
                 is of little use without knowing all of the preceding
                 delta-times.)
   * Interpret : The delta-times are interpreted in metrical or timecode
                 format, as determined by the MIDI file's Header chunk.
                   Metrical : "Bar:Beat:Tick"         ('000:00:000'     )
                   Timecode : "Hr:Min:Sec:Frame:Tick" ('00:00:00:00:000')
                 In each case, 'Tick' is the MIDI file tick resolution.
                 With this setting, the musical time position will be
                 shown for each described event.

 * Filter settings (see also sections 8.5, 8.6 and 8.7)
   ~~~~~~~~~~~~~~~
   If 'Filtered data' (see above) is ticked, then the following settings
   determine which events are described, ie included in the output file.

   * Duplicate events     : Refers to identical events occuring at the
                            same instant in time.  All types of MIDI
                            events are considered.
   * Overlapping NoteOns  : Refers to a Note On event occuring for a note
                            which has already received a Note On event,
                            without an intervening Note Off.
   * Surplus NoteOffs     : Refers to a Note Off event occuring for a note
                            which is already Off.
   * Channel independant  : This applies to the above 3 settings.
                            When ticked the MIDI channel component of the
                            events is ignored.
                            This is to accomodate situations where the
                            MIDI data within a track is the result of a
                            Merge operation leaving multi-channel data,
                            and where the outgoing data would be forced to
                            a specific MIDI channel (by a sequencer).
   * All Notes Off        : This does not imply all Note Off events -
                            instead it refers to the specific controller
                            number 123 (ANO).
                            These events can cause problems when sending
                            data from two or more sequencer tracks to the
                            same MIDI channel, where the ANO event in one
                            track may cut off a note which was still
                            playing on another track.
   * Ctlr                 : Refers to all occurences of either a specific
                            Controller event or all Controller events (as
                            specified via the Controller popup menu).
   * Program Change       : Refers to all Program Change events.
   * Sys Ex               : Refers to all Sys Ex events.
   * Meta                 : Refers to all Meta events : Tempo, Special,
                            etc.

   If 'Filtered data' is selected, though none of the filters are ticked,
   then you will just get a brief track list showing the byte size of each
   track.

 * Output filename  (see also 'Remember destination path', in section 4.0)
   ~~~~~~~~~~~~~~~
   * Capture : The suggested filename will have the same leafname as the
               source file, though if a file extension is present, it will
               be forced to '/TXT'.
   * Suffix  : The suggested filename will have the same leafname as the
               source file, though with a 'D' suffixed (though preceding
               any file extension which, as above, is forced to '/TXT'). 
               If the leafname is already 10 characters long, then the
               last character is replaced with a 'D'.
               NB.  Users of filing systems that support long filenames
                    (eg RISC OS 4) who do not want this name truncation,
                    can set a user option within the Messages file (see
                    section 9.0).

Any events which are ticked are tagged in the output file, irrespective of
whether 'All data' or 'Filtered data' is selected.  The tags comprise a
single letter, and a key is shown within the output file itself.  This key
only details events that were ticked at the time in the 'Filter settings'
section of the 'Describe' options.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

5.2  'Clean' options
     ~~~~~~~~~~~~~~~
These are grouped into 4 sections : Strip events, Output filename, Hanging
notes and Track duration :

 * Strip events (see also sections 5.1, 8.5, 8.6 and 8.7)
   ~~~~~~~~~~~~
   The options available here are almost the same as the Filter settings
   section in 'Describe' options, except here they determine which events
   are to be removed (rather than described).

   The events in common with Describe :

   * Duplicate events     }
   * Overlapping NoteOns  }
   * Surplus NoteOffs     }
   * Channel independant  }  Refer to section 5.1 above :
   * All Notes Off        }  ('Describe' options : Filter Settings)
   * Ctlr                 }
   * Program Change       }
   * System Exclusive     }

   The only difference in the list of events is that instead of Describe's
   'Meta' filter setting, here that is replaced with :

   * Inspiration specific : This is of use with files saved from Pandora's
                            (now long dead) 'Inspiration' sequencer and
                            does the following :
                            * During the initial scan (ie when dropping a
                              file onto the dropzone) :
                              * If a Meta event 3 (TrackName) with text
                                starting with "!i - " is found, then it
                                sets a flag that this *is* an Inspiration
                                file, and this event will be removed
                                during a Clean process.  Inspiration
                                (wrongly) used this Meta event to store
                                sequencer specific information.
                            * During the Clean process (if the above
                              mentioned flag and this option are set) :
                              * The initial TimeSig Meta event in track 0
                                is moved to the start of the track.
                                (Another of Inspiration's 'features' is
                                that it puts it's initial TimeSig event 96
                                ticks after the start of the track.)
                              * Any Meta Text events (Meta type = 1), are
                                patched to become Meta TrackName events
                                (Meta type = 3), as that is their usage !

 * Output filename  (see also 'Remember destination path', in section 4.0)
   ~~~~~~~~~~~~~~~
   * Capture : The suggested filename will have the same leafname as the
               source file, though if a file extension is present, it will
               be forced to '/MID'.
   * Suffix  : The suggested filename will have the same leafname as the
               source file, though with a 'C' suffixed (though preceding
               any file extension which, as above, is forced to '/MID'). 
               If the leafname is already 10 characters long, then the
               last character is replaced with a 'C'.
               NB.  Users of filing systems that support long filenames
                    (eg RISC OS 4) who do not want this name truncation,
                    can set a user option within the Messages file (see
                    section 9.0).

 * Hanging notes
   ~~~~~~~~~~~~~
   * Leave         : Any hanging notes will be left in the MIDI file.
   * Remove        : Any hanging notes will be removed from the MIDI file.
   * Add a NoteOff : A NoteOff event will be inserted after each lone
                     NoteOn event, thus 'fixing' these hanging notes.
                     The duration of each fixed note is dependant on a
                     number of factors, see section 8.3.
   * Prompt each   : For each occurance of a hanging note, the user will
                     be offered the following choice of actions :
                       Leave, Remove, Add a NoteOff, Abort
                     the first 3 of which each act as above.  Abort stops
                     the process (handy if you've found a file with dozens
                     of hanging notes).

 * Track duration
   ~~~~~~~~~~~~~~
   * Ensure whole number of bars : Forces the EndOfTrack Meta event along
                                   to the next end of bar.  This only works
                                   if the file is Metrical (and not
                                   TimeCode) based, as specified in the
                                   Header chunk.
                                   This option is mainly of use if you wish
                                   to play the MIDI file as a loop.

----------------------------------------------------------------------------

6.0  MIDI File Structure
     ===================

Note that this section is only an overview of the MIDI File Standard, and
as such is incomplete.  If you want more detail, refer to the documents
mentioned in section 10.0.

Chunks
~~~~~~
MIDI files contain a series of chunks of which there are two types :

  MThd : Header chunk
  MTrk : Track chunk

Each chunk has an 8 byte header :

  bytes 0 - 3 : identifier (either "MThd" or "MTrk")
  bytes 4 - 7 : chunklen (the number of bytes comprising the following
                data)

followed by 'chunklen' bytes of data.  Ie a chunk is (8 + chunklen) bytes
long.

Header Chunks
~~~~~~~~~~~~~
The first chunk in the file should be a Header chunk.  This should be the
only occurrence of a 'MThd' chunk in the file, ie all subsequent chunks
should be 'MTrk' chunks.

The header chunk always contains 6 bytes of data (3 16-bit values) :

  * format : (can take one of 3 values)

    0 : A single multi-channel track
    1 : 'tracks' simultaneous tracks
    2 : 'tracks' independent patterns

  * tracks : the number of MTrk chunks following this chunk.

  * tickdiv : the timing interval to be used.  Bit 15 is a flag indicating
    whether timecode (Hrs.Mins.Secs.Frames) or Metrical (Bar.Beat) format
    is to be used.

Track Chunks
~~~~~~~~~~~~
The role of the second chunk (ie the first Track chunk) depends on the
MIDI file's 'format' (as defined in the Header chunk).

For format 0 MIDI files, the first Track chunk is the only one, and
contains all Tempo, TimeSig and Note (possibly multi-channel) data.

For format 1, the first Track chunk is a global Tempo track and should not
contain any Note data.  All TimeSig and Tempo Meta events should be in
this track, only.  There then follows 'n' more Track chunks.  These are
the 'n' tracks that would be seen if the file were loaded into a
sequencer, and none of these tracks should contain any timing related
data.

For format 2, each track is a separate entity (like drum patterns within a
drum machine), and can each contain timing related events (which are then
specific to the track in which they occur).


The actual data within the MTrk chunk takes the following form :

  delta-time   a variable length variable
  event        there are three main types of event : Midi, SysEx and Meta.

repeated for 'chunklen' bytes.

The delta-time is the number of 'tickdiv' intervals since the previous
event.  It is a 'variable length quantity', comprising 1, 2, 3 or 4 bytes,
depending on the size of the value being represented.

The event data shares the concept of 'status' and 'data' bytes as are
found in MIDI generally, with status bytes being identified by their
having bit 7 set.  The main diversion is that the MIDI Reset status byte
(&FF) is used here to specify that a Meta event follows.

 * Midi events are identified by the standard Midi status bytes for
   Channel messages, ie &8n to &En, where n would be the MIDI channel
   (0-15).  Running status is supported and is identified by the absence
   of a status byte (ie a value less than &80 where a status byte was
   expected).  Both SysEx and Meta events will interrupt running status.

 * SysEx events are identified by either &F0 or &F7 status byte.  The &F0
   status is used for normal SysEx messages, whereas the &F7 status is
   used for packetised SysEx messages (to allow for Casio's deviation from
   the SysEx standard) or escape sequences (a group of bytes which
   couldn't normally be included within a MIDI file, eg System Real Time
   and System Common messages).

 * Meta events (identified by &FF status byte) contain additional
   information which would not be in the MIDI data stream itself.  Eg.
   TimeSig, KeySig, Tempo, TrackName, Text, Marker, Special, EOT (End of
   Track) events being some of the most common.


Midi Status bytes
~~~~~~~~~~~~~~~~~
  CHANNEL MESSAGES    : data bytes following
  -------------------------------------------------------------------
  &8n : Note Off      : 2 : note (0-127), velocity (0-127)
  &9n : Note On       : 2 : note (0-127), velocity (1-127) / Off (0)
  &An : Poly Pressure : 2 : note (0-127), pressure (0-127
  &Bn : Controller    : 2 : controller (0-127), value (0-127)  (#1)
  &Cn : Prog Change   : 1 : program (0-127)
  &Dn : Chan Pressure : 1 : pressure (0-127)
  &En : Pitch Bend    : 2 : LSB (0-127), MSB (0-127)
  -------------------------------------------------------------------
  SYSTEM COMMON MESSAGES (#2)
  -------------------------------------------------------------------
  &F0 : Start of SysEx (SOX)         : 0 :
  &F1 : MIDI Time Code Quarter Frame : 1 : 0ttt vvvv  (Type, Value)
  &F2 : Song Position pointer        : 2 : LSB (0-127), MSB (0-127)
  &F3 : Song Select                  : 1 : Song number (0-127)
  &F4 : Undefined                    : - :
  &F5 : Undefined                    : - :
  &F6 : Tune Request                 : 0 :
  &F7 : End of SysEx (EOX)           : 0 :
  -------------------------------------------------------------------
  SYSTEM REAL TIME MESSAGES (#3)
  -------------------------------------------------------------------
  &F8 : MIDI Timing clock            : 0
  &F9 : Undefined                    : -
  &FA : Start                        : 0
  &FB : Continue                     : 0
  &FC : Stop                         : 0
  &FD : Undefined                    : -
  &FE : Active Sensing               : 0
  &FF : System Reset                 : 0 (#4)
  -------------------------------------------------------------------

Notes :

 #1 : Controllers 120-127 are Channel Mode messages.
 #2 : The System Common messages &F1 to &F6 inclusive cannot occur within
      a MIDI file (unless sent as an escape sequence).
 #3 : The System Real Time messages &F8 to &FE inclusive cannot occur
      within a MIDI file (unless sent as an escape sequence).
 #4 : As mentioned above, within a MIDI file the System Reset status byte
      (&FF) is used to signify a Meta event.

----------------------------------------------------------------------------

7.0  MIDI File Description
     =====================

The output file generated by a Describe operation contains a header
comprising :

 * The version of Midiphile which was used to create the file;
 * The full filename of the processed MIDI file;
 * The date and time the file was processed;
 * The track range processed, and whether 'All data' or 'Filtered data'
   (in 'Describe' options) was set;
 * The key of tags (only those which were ticked in the 'Describe'
   Options' Filter settings section).

Then follows a series of chunks, starting with the Header chunk, followed
by Track chunks for each one falling within the specified range of tracks.
For full details of chunks and their contents, refer to my 'MIDI Files
Specification' document mentioned in section 10.0.

Header chunk
~~~~~~~~~~~~
  File format (0-2); Number of Track chunks in the file;
  'Metrical' or 'Timecode' time-format; Timing resolution (TickDiv)

Track chunk
~~~~~~~~~~~
  Each line of text generated in the output file, which meets the
  criterion of an active filter switch, is tagged with a single letter,
  indicating which filter action picked up that particular event
  (summarised at the head of the output file).  This is true even when the
  'All data' option is selected, and with either Delta or Interpreted
  timing selected.

  Each line shows an event (Midi, SysEx or Meta) and either the associated
  delta time or the interpreted time at which the event occurs.

  In the case of Midi events, the type is decoded (eg NoteOn, Pitch Bend,
  etc), and controllers are decoded by name (as listed in the '!Controls'
  file).  The presence of running status is indicated by enclosing the
  decoded MIDI channel within brackets (to show that it is implied).

  Sys Ex messages are decoded into 3 classes : Universal SysEx (Real Time
  and Non Real Time) and Manufacturer specific.  Only a small selection of
  manufacturers are identified, with 'Manu ??' being reported for those not
  recognised.  The entire message is then decoded as a hex dump.

  Meta events are also decoded.  Note that for format 1 MIDI files, a
  TrackName Meta event occuring in track 0 (the global tempo track) is
  actually the Sequence Name.

  Track summary showing totals of each type of event found (which were
  ticked in the Options' filter settings).  The number of hanging notes
  found is always reported.

----------------------------------------------------------------------------

8.0  Miscellaneous / Technical
     =========================

8.1  Pre-scanning files
     ~~~~~~~~~~~~~~~~~~
When a MIDI file is dragged to the dropzone, the file is loaded into
memory and scanned to test that it is a valid MIDI file.  The header chunk
is read to determine the MIDI file format, number of tracks and certain
timing information.

If it is a format 1 MIDI file (where track 0 is the global tempo track), a
Time Sig map is generated based on TimeSig events in track 0, and this
will be used when Describe'ing any tracks (ie not just for track 0, in
which these events occured).

If there are 2 or more tracks, then track 1 is scanned for a TrackName
Meta event (3) with text starting with "!i - ".  If this is found, then a
flag is set to indicate that this is an Inspiration file.  This will be
used in association with the 'Inspiration specific' (Clean) option.

If an error message reporting that a TimeSig Meta event was found, but not
at the start of a track, then this could indicate that the file was
created by Inspiration.  In such cases the file should be cleaned with the
'Inspiration specific' option set.

  Bad MIDI files
  ~~~~~~~~~~~~~~
  Format 0 files with more than one track (MTrk chunks) are rejected.

  If there is no TimeSig Meta event at 'time = 0' in track 0 (the tempo
  track), then a default time signature of 4/4 is assumed.

  If an 'unrecognised chunk' is found then the user is offered the choice
  of :
    a) accepting the file up to the point where the unrecognised chunk
       occurs.  Note that when Cleaning such files, any valid chunks
       occuring after the unrecognised chunk will be lost.
    b) discarding the file.
  An example of such a MIDI file is 'Rondeau' as sourced via ESP.  (It has
  114 excess '00' bytes at the end of the file.  Clearly this is an
  example of a corrupted file rather than an unrecognised chunk, as such.)

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.2  Output files
     ~~~~~~~~~~~~
The 'out' fileicon must be dragged to a filer window, and not directly
into an application.

If the returned filename (as a consequence of dropping the 'out' icon
somewhere) starts with '<Wimp$ScrapDir>' or 'Blinds:' these are trapped
and prevented.

   Note that dragging the 'out' fileicon (or any object) into a Blinds
   window will cause Blinds to set itself to Icon mode.  This doesn't
   affect Midiphile at all, though is something that Blinds users should
   be aware of.

DragASprite SWIs (solid dragging) are used, where the user's OS and CMOS
settings allow this.

A warning is given if the output file would overwrite the input file.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.3  The 'Process' operation and hanging notes
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For both Describe and Clean operations, the MIDI file is processed a track
at a time with two passes per track.  The first pass ignores the 'Channel
independant' setting, and looks for any hanging notes (ie notes for which
there is a NoteOn but for which there is no associated NoteOff before the
end of the track).

 * For a Describe operation, any hanging notes are always detected and
   tagged, irrespective of any filter settings (there is no specific
   filter for hanging notes).  The second pass then takes the 'Channel
   independant' setting into account and applies the active 'Describe'
   filters to the data.

 * For a Clean operation, the action depends on the setting of the Hanging
   notes (Clean) options (see section 5.2).

   Leave, Remove and Add a NoteOff act globally for all tracks within the
   specified range, whereas Prompt allows the user to make the same choice
   (Leave, Remove or Add a NoteOff) for each individual hanging note. 
   These hanging notes are then either left, removed or fixed during the
   second pass when the active 'Strip' filters are also applied.

   The duration given to fixed hanging notes depends on a number of
   factors :

   * If the file is TimeCode based (as defined in the Header chunk), it is
     given a fixed duration, as determined by a user option in the
     Messages file (see section 9.0).

   * If the file is Metrical timing based :
     * If the hanging note occurs just before the bar end, it is assumed
       that it was intended to be on the bar, and is given a duration of 1
       beat (minus 1 tick), ie into the next bar.
     * Otherwise the hanging note is given a duration that takes it up to
       the end of the bar (minus 1 tick).

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.4  Functions disabled during 'Process'
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Whilst processing a file, the following aspects of the program are
disabled :

 * Iconbar menu.
 * Closing the Panel window.
 * Response to dropping a file on the 'in' icon.
 * All Panel window icons (inc drag Out) except 'Abort'.
 * 'Load', 'Save' and 'Set' buttons in the Options window.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.5  Cleaning Duplicate and Excess Note events
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some sequencers make a complete mess of merging tracks, leaving you with
tracks containing duplicated events and/or overlapping NoteOn/NoteOff
pairs.

The three filter settings 'Duplicate events', 'Overlapping NoteOns' and
'Surplus NoteOffs' (along with the 'Channel independant' modifier) enable
these events to be detected and/or removed.

Note that the 'Duplicate events' option will remove *any* duplicate
events, not just note events.  (Though see section 8.7 below.)

Also, the presence of overlapping NoteOns may be intentional, to cause a
re-triggering effect (see section 8.6 below).

Surplus NoteOff events will not generally cause any problems, though they
are totally redundant, and hence a waste of space.

It is advisable (though not essential) to use the 'Surplus NoteOffs'
option whenever cleaning either of 'Duplicate events' or 'Overlapping
NoteOns'.  This should ensure that the output file contains a matching
number of NoteOns and NoteOffs.

Using both of the 'Overlapping NoteOns' and 'Surplus NoteOffs' options
will also remove any duplicate NoteOn or NoteOff events.

Many sequencers allow the user to force a specific MIDI channel for each
sequencer track, in which case all data within that track is channel
independant.  When the 'Channel independant' modifier is ticked, the MIDI
channel component of the events is ignored.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.6  Note Re-triggering (overlapping notes)
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some synthesisers can accept a NoteOn event for a note that is already on,
ie without an intervening NoteOff event.  In such instances the
synthesiser may re-trigger the attack phase of a voice's amplitude
envelope.

In such situations, the 'Duplicate events', 'Overlapping NoteOns' and
'Surplus NoteOffs' filters are of somewhat dubious use.  In Describe mode
there is no problem as these 're-triggering' events are merely identified. 
However, in Clean mode the resultant file will have any retriggered events
removed, as they will be considered to be excess NoteOns.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

8.7  Problems with Cleaning Duplicate events
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because a note is actually two events (a NoteOn and a subsequent NoteOff),
using the 'Duplicate events' option in isolation can cause problems.

Eg where two NoteOns for the same note occur at the same time though their
respective NoteOffs are not themselves duplicate events (ie the notes are
of different durations).  In this instance a redundant NoteOff would be
left.

Additionally using the 'Surplus NoteOffs' option will remove any stray
NoteOffs left from using the 'Duplicate events' option.

Ie. Don't Clean duplicate events without also cleaning surplus NoteOffs.

Duplicate events are considered before Overlapping Note Ons and Surplus
Note Offs, which prevents revealing fresh redundancies, which would
otherwise require another pass through the data.  This is also true for
Describe mode.

----------------------------------------------------------------------------

9.0  User Options in the Messages file
     =================================

There are three parameters in the Messages file that you may alter :

 * UserOpt.EvntPoll:

   This sets the number of MIDI events to be processed per WimpPoll.  On
   my RiscPC-SA, a value of 80 gives a smooth progress bar and a
   responsive desktop.  On different machines a different value may be
   more suitable.

   Range : 20-300;  Default : 80

 * UserOpt.HangNDur:

   This sets the duration (in frames) of 'fixed' (ie repaired) hanging
   notes, for timecode based files.

   Range : 1-30;  Default : 12

 * UserOpt.LongName:

   This determines whether or not the output leafname is truncated to 10
   characters.  If you are using a filing system that supports long
   filenames, you can set this option to TRUE.

   Range : TRUE | FALSE;  Default : FALSE

----------------------------------------------------------------------------

10.0  Further reading
      ===============

Some MIDI-related documents are available from my web site, notably :

 * 'The MIDI Software Specification' :

   http://www.somascape.org/midi/tech/spec.html

 * 'MIDI Files Specification' :

   http://www.somascape.org/midi/tech/mfile.html

Both of these documents are detailed and rather technical in nature.

----------------------------------------------------------------------------
