  ==========================================================================
                                 MIDIG v2.01
             Copyright (c) 1996-2003 Carlos Rodriguez Butragueño
                             All rights reserved

                 MIDIG v2.01 documentation - English version

  ==========================================================================


    DISCLAIMER

    This program is freeware, so it may be freely distributed for
    non-commercial purposes.

    This software is provided "as is" without express or implied warranty.
    The author is not responsible for any damage caused by this program.


  ==========================================================================


    Contents
    =========

        1 - Introduction
        2 - Installation
        3 - Program guide
            3.1 - Command line options
            3.2 - Configuration file
            3.3 - Instruments file
            3.4 - MIDI functions
            3.5 - Current limits
        4 - Credits
        5 - Contact address


  ==========================================================================


    1 - Introduction
    =================

        MIDIG is a MIDI file player that makes use of wavetable synthesis
        and digital effects to generate the sound.

        Requirements:
            Pentium 450, 256 Mb RAM, 150 Mb HD,
            and any DirectSound compatible 16-bit soundcard.

        Works under Win9x/2000/XP (not tested with other platforms)


      Features:
      ----------

        * works at 44100 Hz, 16 bits, stereo
        * up to 64 synthesis channels
        * digital effects: reverb, chorus and echo
        * 8 point interpolation
        * resonant filters
        * SF2 support
        * WAV rendering
        * recognizes more than 30 MIDI messages
        * configurable windows layout
        * compatible with karaoke midi files
        * freeware


    2 - Installation
    =================

        Unzip on any directory and execute the file "midig.exe"
        Use the open dialog (F3) or just drag&drop a midi file over
        the main window.


    3 - Program guide
    ==================

        3.1 - Command line options
        ---------------------------

            Writing 'midig /?' brings up a list with the options of the
            program. Here is a more detailed explanation:

                /rxxx   play the given midi file in single-instance mode.

                    Writing 'midig /r file.mid' the program will play the
                    given midi file but it will try to reuse an open
                    instance of midig if it exist, instead of creating
                    a new instance of the program.

                /lxxx   use the given directory as the local directory.

                    With 'midig /l c:\mid' the program will use 'c:\mid' as
                    the local directory, that is, it will expect to find
                    in 'c:\mid' the following files:

                    (between brackets are the default names for these files)

                        - the configuration file (midig.cfg)
                        - the instruments file (gm.dat)

                    The path for the samples is relative to the local
                    directory (although both this path and the other files
                    can be specified by an absolute path).

                /fxxx   use the specified configuration file.

                    The default name for the config file is 'midig.cfg'.
                    With 'midig /f mid.cfg' the file 'mid.cfg' will be used
                    as the config file.

                /c#     active MIDI channels mask (hexadecimal).

                    Bits set to 1 mean active channels. For example,
                    with 0FFF we leave active 1 to 12, and inactive 13 to 16.

                /gxxx   write a WAV file.

                    Writing 'midig /g record.wav' the program will run
                    as usual, but instead of using the sound card, the
                    program will write the sound to the file 'record.wav'.

                /m#     mixing frequency

                    Sets the mixing frequency for the generated sound.
                    The minimun value is 11025 Hz, and the default value
                    (and recomended) is 44100 Hz, though this value can be
                    exceeded when generating a WAV file.

                /t      load all samples

                    Loads all the samples in memory, instead of loading only
                    the necessary ones for the MIDI file to be played.

                /e#     advance to the given position (in seconds) before
                        starting to play.

                    For example, with 'midig /e 30' the program will advance
                    automatically 30 seconds before starting to play the file
                    (only the first time. If we restart the file, or we load
                    another file, it will be done as usual).

                /n#     main volume (dB)

                    Sets the initial main volume. For example, if we want an
                    initial volume of -3.2 dB, we may type 'midig /n -3.2'.


        3.2 - Configuration file
        -------------------------

            This section describes the parameters of the config file, as
            well as their default values (they all are optional).

            The default name for the config file is 'midig.cfg'.


            version = 1         config file version.
                                Must be 1 for this version of the program.

            main_volume         main volume (dB).
                                range: -79.0 .. 24.0   def: -6.0

            surround            "surround" effect level.
                                range: 0 .. 3   def: 0 (no effect)

            swap_channels       swaps the left and right channels.
                                values: YES / NO   def: NO

            mono_recording      writes a mono WAV instead of stereo.
                                values: YES / NO   def: NO

            dat_file            instruments file name.
                                def: gm.dat

            samples_dir         samples directory.
                                def: .

            channels            maximun number of synthesis channels.
                                range: 1 .. 64   def: 64

            mixing_freq         mixing frequency.
                                range: 11025 .. 44100   def: 44100

            use_digital_effects activates the digital effects.
                                values: YES / NO   def: YES

            max_note_on_msg     maximun of note-on messages processed in
                                each block (3 msec at 44100 Hz)
                                range: 0 .. 1000 (0=inactive)   def: 5

            echo_params         echo parameters (coeff., level, filter)
                                coeff:  coefficient of each repetition
                                        range: -1.0 .. 1.0   def: 0.4
                                level:  effect level
                                        range: 0.0 .. 100000.0   def: 0.3
                                filter: low pass filter level for each repet.
                                        range: 0.0 .. 1.0   def: 0.5


        3.3 - Instruments file
        -----------------------

            In this section are explained the fields and units of the
            instruments file. Every field in the instruments file is a string
            or an integer.

            The default name for the instruments file is 'gm.dat'.


            SAMPLE_WAV
                {
                sample_name = { sample, finetune, note, loop_sta, loop_len }
                ...
                }

            sample    :  name of the file (in WAV or WCS format)
            finetune  :  finetuning in cents of semitone
            note      :  base note of the sample (original note played)
            loop_sta  :  loop start point
            loop_len  :  > 0  number of samples in the loop
                         < 0  loop end point
                         = 0  no loop

            the point format for loops is:
                sample:fraction
            where 'fraction' (0..15) is 1/16 of sample.

            Loops are always forward. Neither backward nor "ping-pong" loops
            are implemented.

            The end point of the loop is calculated this way:

                if loop_len.sample < 0
                    end.sample = -loop_len.sample
                    end.fraction = loop_len.fraction
                else
                    end = loop_sta + loop_len

            examples:

                a 100 samples length sound with the loop starting in the
                second sample (sample 1) to the end of the sound:

                    1:0, 99:0  or  1:0, -100:0
      
                for covering all the sound with the loop:

                    0:0, 100:0  or  0:0, -100:0

                a loop starting at 1:2 with 7:3 samples length:

                    1:2, 7:3  or  1:2, -8:5

                a loop starting at 1:10 with 7:12 samples length:

                    1:10, 7:12  or  1:10, -9:6

            If a sound has 'n' samples, and 'x' is the read position,
            it's always true that:

                0 <= x < n

            the same way, in a sound with 'n' samples, loop start point 'i'
            and loop end point 'f', it's always true that:

                0 <= i < f <= n     ( i >= f  means no loop)
                0 <= x < f          before the first repetition
                i <= x < f          during the repetitions

            for example, if the loop is from 1:2 to 7:3, then always:

                1:2 <= x < 7:3      during the repetitions

            (actually the program may need to read samples beyond the end
            for interpolation, but this is not a problem bacause the program
            adds more samples automatically if necessary).


            SAMPLE_RAW
                {
                sample_name = { sample, bits, sign, channels, freq,
                                  finetune, note, loop_sta, loop_len }
                ...
                }

            sample    :  name of the file (a raw file with no header)
            bits      :  8 / 16 bits
            sign      :  CON_SIGNO / SIN_SIGNO  (signed / unsigned)
            channels  :  MONO / ESTEREO  (mono / stereo)
            freq      :  sample frequency (Hz)
            finetune  :  finetuning in cents of semitone
            note      :  base note of the sample (original note played)
            loop_sta  :  loop start point
            loop_len  :  loop length  /  loop end point


            ENVOLV
                {
                envelope_name = { delay, attack, hold, decay,
                                  sustain, release, overlapping_release }
                ...
                }

            delay       : unit = 4.7 msec.  (0 = 0 msec.)
            attack      : unit = 4.7 msec.  (0 = 0 msec.)
            hold        : unit = 6.5 msec.  (0 = 0 msec.)
            decay       : unit =  36 msec.  (0 = 16 msec.)
            sustain     :  0 ..  96  ->  -97.0 .. -1 dB  (unit = 1 dB)
                          97 .. 127  -> -0.968 ..  0 dB  (unit = 0.032 dB)
            release     : unit =  36 msec.  (0 = 16 msec.)
            overl_rel   : unit =  36 msec.  (0 = 16 msec.)


            MODUL
                {
                modulation_name = { freq, delay, vibrato, tremolo }
                ...
                }

            freq     : frequency (mHz)
            delay    : delay (msec)
            vibrato  : vibrato level (unit = 1 cent of semitone)
            tremolo  : tremolo level (-64..64) (unit = 0.1875 dB approx.)


            INSTRUM
                {
                instr_number = { modul, env, env2, flt_env, flt_env_level,
                              tun_env_level, fltQ, transpos, spec_tuning,
                              (sample,level,flt,last_note)... }
                ...
                }

            modul          : name of the modulation
            env            : name of the volume envelope 1
            env2           : name of the volume envelope 2
            flt_env        : name of the filter/tuning envelope
            flt_env_level  : flt_env to filter (-128..127, u=172.27 Hz)
            tun_env_level  : flt_env to tuning (-128..127, u=1/6 of semitone)
            fltQ           : filter resonance (0..127)
            transpos       : transposition (-120..120 semitones)
            spec_tuning    : special tuning (x=1..10, 1 sem. every x notes)
            sample         : name of the sample
            level          : sample volume level (0..255, 64 = no modify)
            flt            : filter cutoff point (0..127, u = 172.27 Hz)
            last_note      : highest note in the range of the sample


            PERCUSION
                {
                note = { env, env2, flt_env, flt_env_level, tun_env_level,
                         transpos, excl_group, sample, level, flt, pan }
                ...
                }

            grupo_excl  : exclusion group  (0 = no excl.)
            pan         : panning position (-64 .. 64)

            (the other parameters are explained in INSTRUM above)


        3.4 - MIDI functions
        ---------------------

    n: MIDI channel (0..15)


  MIDI message  Code (hex)         Description
 --------------------------------------------------------------------------

  Note on       9nH kk vv          Note kk (0..127) on, velocity vv (1..127)
                                   vv=0 means "Note off"

  Note off      8nH kk vv          Note kk (0..127) off
                                   vv ignored

  Pitch bend    EnH bl bh          Pitch bend. The value specified by
                                   bh|bl (14 bits) allows slides of +/- 2
                                   semitones. Can be changed using "pitch
                                   bend sensitivity".

  Program       CnH pp             Program (instrument) change. If n=9,
  change                           drumset is selected. More channels can
                                   be set as a drum channel using "part to
                                   rhythm allocation".

  CTRL 0        BnH 00H cc         Bank select. Does not take effect until
                                   a program change.

  CTRL 1        BnH 01H cc         Modulation wheel

  CTRL 5        BnH 05H cc         Portamento time

  CTRL 6        BnH 06H cc         Data entry (RPN and NRPN)

  CTRL 7        BnH 07H cc         Volume (def=100)

  CTRL 10       BnH 0AH cc         Pan (def=64 center)

  CTRL 11       BnH 0BH cc         Expression (def=127)

  CTRL 64       BnH 40H cc         Sustain pedal

  CTRL 65       BnH 41H cc         Portamento on/off

  CTRL 91       BnH 5BH vv         Reverb send level (vv=0..127)

  CTRL 93       BnH 5DH vv         Chorus send level (vv=0..127)

  CTRL 98       BnH 62H cc         NRPN low byte

  CTRL 99       BnH 63H cc         NRPN high byte

  CTRL 100      BnH 64H cc         RPN low byte

  CTRL 101      BnH 65H cc         RPN high byte

  CTRL 120      BnH 78H 00H        All sound off

  CTRL 121      BnH 79H 00H        Reset all controllers
                                   (1,5,11,64,65 and pitch bend)

  CTRL 123      BnH 7BH 00H        All notes off

  RPN 0000H     BnH 65H 00H 64H    Pitch bend sensitivity in semitones (def=2)
                00H 06H vv

  NRPN 0120H    BnH 63H 01H 62H    Filter cutoff frequency modify
                20H 06H vv         (vv=40H -> no modify)

  NRPN 0121H    BnH 63H 01H 62H    Filter resonance modify
                21H 06H vv         (vv=40H -> no modify)

  NRPN 0163H    BnH 63H 01H 62H    Envelope attack time modify
                63H 06H vv         (vv=40H -> no modify)

  NRPN 18rrH    BnH 63H 18H 62H    Pitch coarse of drum instrument note rr
                rr 06H vv          (vv=40H -> no modify)

  NRPN 1CrrH    BnH 63H 1CH 62H    Pan of drum instrument note rr
                rr 06H vv          (vv=40H -> middle)

  NRPN 1DrrH    BnH 63H 1DH 62H    Reverb send level of drum instr. note rr
                rr 06H vv          (vv=0..127)

  NRPN 1ErrH    BnH 63H 1EH 62H    Chorus send level of drum instr. note rr
                rr 06H vv          (vv=0..127)

  SYSEX         F0H 41H ?? 42H     Reverb type (vv=0..7)
                12H 40H 01H 30H    3,4 -> "Hall 1"   other -> "Room 3"
                vv xx F7H

  SYSEX         F0H 41H ?? 42H     Part to rhythm allocation
                12H 40H 1pH 15H    p=part (0..15), vv=00/01 (sound/rhythm)
                vv xx F7H          def: part 0 plays drums (MIDI channel 9)
                                        all other parts play sound


        3.5 - Current limits
        ---------------------

            MIDI tracks         :  128
            synthesis channels  :  64
            envelopes           :  512
            modulators          :  256
            samples             :  4096
            samples per instr.  :  192
            instruments         :  1024
            drum instruments    :  1024
            karaoke messages    :  2048


    4 - Credits
    ============

        DEMO.MID, CRDCU.MID and DESENF.MID created by
          Jose A. Rodriguez Butragueño


    5 - Contact address
    ====================

        email:
          carlosprt@terra.es
          butra@casa-de.es

        www:
          http://www25.brinkster.com/midig/

