Ditty - loads and plays a list of midi files.
        records live midi events and edits song parameters.

Display:

   

   toolbar buttons - top/left          (hover over them for help)
      SongList  dialog to edit song playlists (and search for songs)
      Sections  dialog to edit a song's sections
      Rate      rate/rename/delete song and current track's sound (if non GM)
      Tinker    view/edit the current song with Tinker.
      Edit      view the current .song file with your text editor.
      MidiCfg   start the midi device config editor.
      Help!     gets you here
   display area - top/right
      Time  in bars.beats
      Bars  duration of song
      Tmpo  current tempo in Beats Per Minute
      TSig  current timesignature
   songlist droplist
      filenames of all songs in your current playlist
      with leading path prefixes removed for easier reading.
      titlebar also shows current song.
      when selected, scrollwheel down or up to change songs, etc
   key [in]put control
      when "green", keyboard can be used for special purposes.
      see keymap near end of this page
   "live editing" category listbox
      picks what the next toolbar's buttons will edit
   "live editing" toolbar buttons
      these let you control many aspects of the song (as does the midi keyboard)
      Hover over them for tooltips  (and see below :)
   Status area for lyrics and misc messages

   

   track display area
     Track      shows you the track names of the song
        > means selected
        # means muted
        + means shares device/channel with previous track
     Sound      which "preset" is assigned to the track
     Device     which device the sound/channel plays on
     Ch         which midi channel (1..16) on the device this track plays on
     Vol        special "preset" volume of SFont drum sounds
     Events     how many midi events are in the track (noteups, downs && CCs)
     SoundDesc  device's sound description

   TODO: Doc the shortcut clicks...
________________________________________________________________________________

The "Edit SongList" dialog consists of...

   
   main toolbar buttons
      Clear     clears the whole list
      Find      searches for songs in a dir and subdirs matching search string
                and rating checkboxes
      Load      loads an existing .songlist file into the list
      Save      saves list to a .songlist file
      ScootDn   scoots the current song down a row in the list
      ScootUp   "      "   "       "    up   " "   "  "   "
      ScootBot  "      "   "       "    to the bottom of the list
      ScootTop  "      "   "       "    "  "   top    "  "   "
      InsSong   picks a new song to insert into the list before current song
      DelSong   deletes the current song from the list
                (does NOT delete the song file from disk, of course)

   close button exits dialog.
   all edits are made "live" to the songlist - no ok/cancel business.

   search edit box and rating checkboxes are used by Find to narrow down the
   songs in the top level dir (and subdirs) you picked.
   ? rating means any non a/b/c/x rating - like space or "undefined" rating.
________________________________________________________________________________

The "Rate song/sound" dialog consists of...

   
   Song fields...
   These format up the song's filename
      Artist:  group/artist who wrote/performed/made song famous
      Rating:  a,b,c,x,{space},d  (click dropdown for decent descriptions)
      Song:    song title
      Lyrics:  y/n  tacks on _lyr to filename for y

   Sound fields...
   (If sound is non GenMidi)
   These format up the sound's filename  (sound of the current track, that is)
      Dir:     GenMidi sound group (or a dir you type in) to categorize sound
               (Are sounds a PAIN to categorize or WHAT!!!)
      Rating:  a,b,c,d  (click dropdown for decent descriptions)
      Sound:   sound's name

   When you rate a sound that's in the SFont\+ dir or SFont\Drum\+ dir,
   ditty assumes you'll be moving it into the main SFont\- or SFont\Drum\- dir.
   And after you've moved it, will start the dialog again with the next sound.
   This makes it MUCH easier to kill off and rate ALL the sounds in those
   consarn SF2 files :)
________________________________________________________________________________

The "edit track name and sound" dialog...

   
   pops up when you doubleclick in the track display on sound or trackname.

   It consists of
      Track:  track name (1st char of it picks channel and can't be mod'd)
      Sound:  pick from the big ole list - easier than using midi keyboard
                                                            - see below for that
________________________________________________________________________________

Playback:

   When Ditty starts, the previous song list is loaded in (if any) and played.

   If Ditty was run via Windows Explorer with double clicking a .song file,
      the file is tacked onto the end of the current song list and starts.
   If a dir in WinExplorer is right clicked and "play these songs via Ditty" is
      picked, a new songlist is made for all songs in the dir and starts.
      Be careful with BIG dirs because it may take a while...

   The current song in the list is loaded in and played.
   This involves
   - loading the .mid file
   - each MidiOut device used by the song is allocated and initialized.
     each track's channel is calculated based on
     - if the sound is Drum\Drum we're forced to use channel #10
     - otherwise the next available midi channel is allocated.
       (channels can be shared by 2 or more tracks if they're next to each
        other in the song file and all tracks after the first have a leading
        + character in the track name.)
   - if the midiout device is a "known" device type (for example, "SFont")
     the sound's patch file is dumped to the synth.
   - the {MidiPath}\Dev\{DeviceType}\sound.txt files are consulted
     to send the correct program changes on the correct channels.
     SFont devices keep track of patch#s auto-magically :)

   The song plays until there are no more midi events, then
      the midi file is closed and the process starts all over with the next
      in the song list.

      Any recording activity or loading songs in the "Compose" dir
         will -keep- Ditty on that song, however.
________________________________________________________________________________

Live Editing:

   Ditty lets you edit many song parameters.
   They're all available from the midi keyboard  (no reeeeaching for the mouse)
   AND from the screen display.            (if you like reaching for the mouse)

   On screen:
      use the Edit: droplist to pick the category of what you want to edit and

      hover over the 8   << < > >>  << < > >>   buttons to find out what they do
                                               (different things per "category")
   On midi keyboard:
      Use MidiCfg to map an input control on your keyboard to send "MENU".
         This control will change the droplist to pick your editing category.
         While you're at it, map a control to "TRAK" to pick the edit track.

      hit one of the top 8 keys (8f..9c) to DO one of the editing functions.
         these 8 keys correspond to the 8 buttons on screen:
         8f 8f# 8g 8g#    8a 8a# 8b 9c
         <<  <  >  >>     <<  <  >  >>

      If you have less than 88 keys,
      you can use MidiCfg to change the max note (EditKey:) to something other
      than the 9c default value.


   There are SHORTCUTS:
   - click on a track in the display to pick it (see the > to it's left now?)
   - click the sound to choose trkSound editing
   - doubleclick a trackname to edit the track's name/sound in a dialog
   - click the time to pause playback


   Full listing of "live editing":
   - PLAY edit keys
      (no editing going on now, so we can record those notes, etc.)

   - Time
      toggle Pause state
      skip back a section
      skip forward a section
      skip back to first bar
      skip back 8 bars
      skip back 1 bar
      skip forward 1 bar
      skip forward 8 bars

   - Tempo
      decrease tempo 10 BPM
      decrease tempo 1 BPM
      increase tempo 1 BPM
      increase tempo 10 BPM

   - TrkEdit
      erase all events in current track  (careful - you can't get em back!)
      append new drum track for recording
      append new melodic track for recording
      pick 1st track
      pick prev track
      pick next track
      pick last track

   - TrkRecord
      prev device(off/*/devName)
      prev channel(*,1..16)
      next channel(*.1..16)
      next device(off/*/devName)
      erase ALL recording track events
      toss all recording track events not in 'keep' state
      mark all recording track events to state of 'keep'
      save the song as next revision

   - TrkSound
      change sound to prev top group (directory)
      change sound to 5th prev one
      change sound to 5th next one
      change sound to next top group (directory)
      change sound to prev group (directory)
      change sound to prev one
      change sound to next one
      change sound to next group (directory)

   - TrkMute
      pick prev track
      pick next track
      toggle mute on current track
      mute all tracks
      mute current track
      unmute current track
      unmute all tracks

   - DrumVol
      pick prev track
      pick next track
      volume down by 8 for current sound
      volume down by 1 for current sound
      volume up by 1 for current sound
      volume up by 8 for current sound


   Just try stuff out and email me if you need better explanations :)
________________________________________________________________________________

Recording from scratch:
   Recording is enabled per track.
      (Use TrkEdit: NewDrum/NewMelo to add a track)

   Pick a track by clicking on it.
   Pick TrkRecord edit category.
      Use the <<,>> buttons to pick input device
      Use the  <,>  buttons to pick midi channel
      device=* and channel=* will record any device or any channel.

   If you're recording into a drumtrack,
      new tracks will be created automatically as you play new drum notes.

   When done recording,
      use TrkRecord: Save to save the song as the next revision.
         An @yyyymmdd.hhmmss.day will be tacked onto the previous song name.
            (so you don't have to bother with a file save dialog)
         A completely new song defaults to
            {MidiPath}\Compose\@yyyymmdd.hhmmss.day.mid
________________________________________________________________________________

Using your pc keyboard as a crappy midi input device:

   AS LONG AS keyboard input is ON,
      (Tab to or click the little "in" control to make it GREEN)
      you can use your pc keyboard as a (fixed velocity) midi input device.
   Here's the key mapping:

      2   3       5   6   7       9   0       =   bsp    upper octave (octave 5)
    q   w   e   r   t   y   u   i   o   p   [   ]   \    q is middle c
                     ||
                     \/
      c#  d#      f#  g#  a#      c#  d#      f#  g#
    c   d   e   f   g   a   b   c   d   e   f   g   a
    _________________________________________________

      s   d       g   h   j       l   ;   '              lower octave (octave 4)
    z   x   c   v   b   n   m   ,   .   /                z is low c
                     ||
                     \/
      c#  d#      f#  g#  a#      c#  d#  e#
    c   d   e   f   g   a   b   c   d   e

    cursor left   moves everything down an octave (slide left on piano keyboard)
    cursor right  "     "          up   "  "       "     right " "     "
    cursor up     increments the velocity (which defaults to 100 of 1..127)
    cursor down   decrements "   "         "     "        "  "   "  "

    F1..F8        do the main toolbar buttons in order
    F9..F12       do the value editing toolbar rightmost set of 4 buttons
    shift F9..F12 "  "   "     "       "       leftmost  "   "  " "

    Drum note mappings...
       HERE.