Vmap 1.3 (June 4, 1993)
=======================

by Phat Tran

MIDI files for Roland (and most other) synths will sound peculiarly
quiet on the Gravis Ultrasound (GUS), with some tracks playing much
softer than others.  This is because the volume response of the GUS is
exponential (or logarithmic?) whereas that of the Rolands is linear.

Vmap transforms the linear volumes in a MIDI file into logarithmic
volumes for the GUS.  To use vmap, invoke it at the command line as
follows:

    vmap [-r] [-t] [-vnnn] [-snnn] <in.mid> <out.mid>

where <in.mid> and <out.mid> are filenames.  Vmap reads in <in.mid> and
outputs the remapped MIDI file as <out.mid>.  The two filenames must be
different!

The types of volumes that vmap processes are:
    a.  note velocities,
    b.  Controller 7's (main channel volume), and
    c.  Controller 11's (expression).

Vmap will also dump to the screen any text it finds in the MIDI file
that it is processing.

COMMAND LINE OPTIONS

    -r

    This mismatched volume curve problem goes both ways.  MIDI files
    that play properly on the GUS will sound dinly loud on the Rolands,
    with background tracks overwhelming the foreground.  The -r option
    tells vmap to remap the log volumes of GUS .mids into linear volumes
    for Rolands.

    -t

    This option will make vmap process <in.mid> without outputting the
    result to a file.  <out.mid> need not be specified when -t is used.

    -v<nnn>

    Vmap will calculate an internal scaling factor that it multiplies
    each linear volume by such that no transformed volume will exceed
    <nnn>.  If -v<nnn> is not explicitly specified, then -v127 is
    assumed.  The value of the internal scaling factor (VFactor) is
    displayed if the -t option is used.

    This option comes in handy if the default -v127 setting results in a
    transformed file that plays too loudly (which may cause clipping).
    In such cases, -v100 helps.

    This option has no effect when remapping log volumes to linear (i.e.
    when the -r option is used).

    -s<nnn>

    Vmap will calculate an internal offset that it adds to each linear
    volume such that no transformed volume will exceed <nnn>.  By
    default, -s127 is assumed.  The value of the internal offset
    (VRShift) is displayed if the -t option is used.

    Because of loss of resolution, linear volumes that are close
    together in the high range (above 100) may "clump" to one value
    after being log transformed.  For example, linear volumes of 120,
    121, 122, 123 and 124 have only one corresponding log volume (126).
    By shifting the linear volumes down the scale before the log
    transform, the log volumes will have better resolution.  However,
    the lin to log transform won't make as much sense then.

    I advise against using this option as it can really trash the
    output.  I don't know why I even implemented it.  I guess it was a
    good idea at the time.

    This option has no effect when remapping log volumes to linear (i.e.
    when the -r option is used).

TECH NOTES

The formula used is:

    logvol = log((linvol * VFactor + VRShift) + 1) * 128 / log(128)

BUGS

Vmap has not been tested very thoroughly, so there may be bugs that will
crop up as the program is exposed to .mids more exotic than the ones I
have to test it with.  Bug reports and/or comments can be sent to
my Internet account (ptran@sciborg.uwaterloo.ca).  Particulary, if vmap
reports "Unexpected EOF." when processing a .mid file that you know is
intact, tell me!  There may be several MIDI messages that I don't know
about which can cause vmap to lose its framing.

REVISIONS

Version 1.0 -- Original release.

Version 1.1 -- New features:
                - GUS to Roland remapping
                - test mode
                - text dump

Version 1.2 -- New features:
                - -v<nnn> and -s<nnn> options
                - used floating point calculations internally
             - never released

Version 1.3 -- New features:
                - controller 11 (expression) processed
                - lookup table calculated once at beginning for improved
                  speed over version 1.2
