
 __YMagic32 v2.3__________________________________________________________

  A (small) manipulation utility for ST-Sound's *.YM files.

  Coded by Borgar Thorsteinsson (oedipus)
  Additional XM code by Tero Lindeman (tmb)

  Freeware, so copy as you like!

  email:  oedipus@islandia.is
    web:  http://www.islandia.is/~oedipus


 __What's new_____________________________________________________________

  XM-Exporting added
  Fileselector improoved (slightly)
  LHA packing confirm removed
  Save-unpacked-file added
  ...

  New font & colors
  Optimized print routine (smaller font & faster printing).
  Loop-Searching
  ...


 __What is does___________________________________________________________

 input:  YM2, YM3, YM3b, YM5,
 output: YM5, XM

 Keys: 

  F1       - Display help (keys)

  Return   - Set Start (twice sets loop also)
  F9       - Set Loop
  F10      - Set End 

  S        - Save current selection packed (YM5)
  U        - Save current selection unpacked (YM5)
  L        - Load a new tune

  T        - View time (mm:ss)
  G        - View hex position ($0000)
  R        - Re-comment

  C        - Clear extended registers

  F        - Select Yamaha frequency

  V        - Search for possible loops
  X        - Export to a Fasttracker XM song

  0        - Toggle frequency / note display
  1        - View selection Start
  2        - View selection Loop
  3        - View selection End

  Up       - Scroll up through file
  Down     - Scroll down through file
  Page up  - Scroll one page up file
  Page down- Scroll one page down file

  Left     - Increase quantizing
  Right    - Decrease quantizing
  
  Home     - View beginning of file 
  End      - View end of file



 __Details________________________________________________________________

  The program is will not overwrite or modify any input files.
  Backup files are created if you choose to modify anything!
  (ie. old one becomes "tune.bak" & new one "tune.ym") 

  The ym chip's registers are displayed like this:
 
             Voice 1    Voice 2    Voice 3
   | $0000 | 0000 0 * | 0000 0 * | 0000 0 * |
   | $0000 | 0000 0 * | 0000 0 * | 0000 0 * |
       T       T  T            T
       |       |  |            |
    position   | volume        |
               |             noise
        frequency/note

  Volume is colored depending on level (white=high). This makes it 
  easier to see what is going on!.  Selection is on black background 
  and the cut away parts are dark gray.  Noise is symbolized by *.

  'R' key will prompt you for file's Name, Author & Comment. 
  Alternatively to typing long/frequent names in, the program 
  recognizes the following "shortcuts":

  The program recognizes shorts for authors;

    "ab" for "Allister Brimble"
    "bd" for "Ben Daglish"
    "dw" for "David Whittaker"
    "gg" for "Gunnar Gaubatz (Big Alec)"
    "jh" for "Jochen Hippel (Mad Max)"
    "jo" for "Jean Sebastien Gerard (Jess/Ovr)"
    "pe" for "Pierre-Eric Loriaux"

  The program recognizes shorts for comments;

    "f" for "Converted by Frederic Gidouin"
    "j" for "Converted by Jochen Knaus"
    "l" for "Converted by Leonard"
    "o" for "Converted by Oedipus"
    "s" for "Converted by Stefan Lindberg"
    "v" for "Converted by Senser/Vectronix"
    "u" for "Converter unknown"

  Write to me if you want any specific name in here and I'll add it ASAP.

  A worthwhile feature is YMagic's ability to load non-interleaved 
  files. This means that you can write your YM recorder to output 
  non interleaved files and use YMagic to convert them to the more 
  efficient version of the format!

  Also there is a feature to clear out extended registers. This wipes
  registers 14 & 15 (Sid/Digi) clean. This was included as a sort of 
  repair option.  Since some sloppy ST coders (myself included) forget 
  to clear these on save in their YM conversion utils (causing very 
  large packed files!).

  Another "repair" option is the frequency selector. This was included 
  to counter 2 bugs. Firstly the PSG2YM converter sets the wrong frequency 
  for the MSX chip. And secondly the 0.49 Beta version of Pacifist 0.49 
  sets frequency to Amstrad sync, no doubt this will get fixed, but until 
  then..  

  Some players may set the Envelope control register only at the start of 
  song and never again (or much later).  Setting the starting point behind 
  the change meant that you'd cut away all beginning envelope commands!. 
  This has now (hopefully) been fixed (thanks Stefan!)


 __The Loop Searching Feature_____________________________________________

  If loop searching is selected, then the program will attempt to find
  a register-sequence that matches the sequence at the _loop_ position.
  In most cases, the _start_ & _loop_ position will be the same value.

  Warning:
   Some tunes do not alter all registers immediately on start and may 
   therefore be different on looping...

  Example:
   X tune starts playing on voices 1 & 2, but voice 3 isn't touched 
   until later. Then when the tune restarts the same thing happens but 
   the voice 3 frequency has changed therefore making the loop undetectable.
   the way around this is to set the _loop_ to the 1st position where all
   voices are active and count backwards after loop is found!


 __XM-Exporting___________________________________________________________

  Use Left & Right buttons to find the correct steprate for the song. 
  A typical Hippel track for example has a steprate of 3 or 6.  

  Pressing X will open the export menu. Don't worry, switching to/from the
  export menu will leave all settings intact! (including the export ones).

  The export menu has the following options;  

    Frequency tilt: (+-00)

      Not all players use a correct frequency table (A-4 = 440).
      This may produce a messy XM conversion. Use tilting if vibrating
      leads contain garbage notes or if arpeggios are wrong.
      Tilting option will allow you to shift the center frequency used
      to convert the notes.  (Hippel/Whittaker default!) 

    Volume scale: (curve|line)

      Decides if volume converted should be Linear or Logarithmic.
      I suggest you just leave it on curve (default).

    Arp-conversion: (clean|messy)

      The coolest part of the converter (coders p.o.v). 
      I doubt anyone will use the messy option unless in an emergency.
      but I left it in all the same!  

    Pattern length: ($40)
 
      $40 or 64 lines is the default, but you'll want to set it to $30 
      when you convert 3/4 tunes. (or any tunes in other than 4/4 meter).


   Known bugs are: bad notes may occur if freq.-tilt is too high, 
                   instrument/volume sets are not perfected yet.



 __Future plans?__________________________________________________________

 Some things I might add to future versions are; 
 
  YM6 support
  A minimal YM player for testing loops (in process..)
  yet more shortcuts for common author names.
  Auto detect - frequency offset (
  Auto detect - starting/trailing zeroes


 __Finally________________________________________________________________

 SEND ME YOUR CONVERTED TUNES!!  :)

   oedipus@islandia.is

 please try my webpage (full of retro game music!)
 --> http://www.islandia.is/~oedipus/ 

 check out tmb's page for XM2YM and other goodies!
 --> http://webclub.solutions.fi/~xtmb/

 and thanks to Arnaud for his great STSound Player
 --> http://www.mygale.org/09/leonard/
    
  
