                          Mac To Wav  --  ReadMe.TXT
   
                                January 8, 1995

                                Phillip M Hord

                               PhilHord@AOL.com



        DESCRIPTION

        MACTOWAV is a very simple PC utility that searches
        through Macintosh resource files for Sound ("snd ")
        resources and converts them to .WAV files.



        PURPOSE

        I wrote it specifically to swipe a bunch of Mac sounds
        from some applications.  I realize the Mac can write its
        own .WAV files, but I couldn't find a way to do it in
        bulk.  So, being a PC programmer I wrote this utility to
        decode Mac resources and do the conversion for me.



        FEATURES

        o Accepts multiple wildcard filespecs.
        o Automatically determines if a file is a Mac resource 
          file or not.
        o Converts frequencies to allowable Windows frequencies
          (Note: some frequencies might not be supported by 
          16-bit Windows.)
        o Generates long filenames on file systems that support 
          it.
        o Optionally renames files to avoid filename collisions
 

        LIMITATIONS

        o Does not use long filename functions for input files
        o Does not convert PCM data to 22khz (Windows 3.11 can
          play 22khz and 11khz, but maybe not as system sounds.
          Windows 95 can handle any frequency which is an even
          divisor of 44100, as far as I can tell.)
        o Only converts recognizably valid Snd1 and Snd2 
          resource formats.



        DISCLAIMER and WARRANTY

        Phil Hord does not represent or warrant that this
        Software will meet your requirements, that its use or
        operation will be uninterrupted or error free, or that
        the fully operational version of the Software will
        continue to be available in the future.  PHIL HORD WILL
        NOT BE LIABLE FOR ANY LOSS OR DAMAGES DIRECTLY OR
        INDIRECTLY RELATED TO THE USE OF THE SOFTWARE, INCLUDING
        WITHOUT LIMITATION ANY CONSEQUENTIAL DAMAGES OR LOST
        PROFITS.  YOU ASSUME ALL RESPONSIBILITY FOR ANY AND ALL
        LOSSES OR DAMAGES. THE SOFTWARE IS PROVIDED TO YOU "AS
        IS", AND ALL EXPRESS AND IMPLIED WARRANTIES ARE HEREBY
        EXCLUDED, INCLUDING WITHOUT LIMITATION ANY AND ALL
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
        PARTICULAR PURPOSE. If a third party claims that the
        Software infringes that party's United States patent,
        copyright or trade secret, you will immediately stop
        using the Software and destroy all copies.


        
        PLATFORMS

        This should run in any environment that supports DOS 3.x
        function calls.  It specifically targets extended DOS
        function calls for long filenames (output only) and it
        should intelligently fall back to short filenames when
        necessary.  However, I have not tested this on a short-
        filename restricted system (such as Windows 3.1 or DOS
        FAT).  In fact I have only tested it on Windows 95's
        VFAT system (Beta 2) and I am interested in hearing 
        the results of tests on other OS's.
               


        USAGE

        The program takes fairly standard UNIX style arguments.

        MACTOWAV [-O[-] [S[-]] [-V[-]] <filespec> ...
        <filespec> can contain wildcard characters
        -V turns on VERBOSE mode (more info than you probably
                want)
        -N NoOutput; Displays all normal information but does
                not actually generate .WAV files
        -S forces short filenames on NTFS and VFAT systems
        -O overwrites existing files.  (the default behavior
                is to rename the output files to avoid name
                collisions with existing files.  The renaming
                uses *.n.WAV for long filenames and *nn.WAV for
                short filenames, where n and nn are numbers.)

        For example:

        MACTOWAV *.* resource.frk\*.* D:\mac\games\*.*
          will dig through all the files listed and convert their
          SOUND resources to .WAV files.  All the output files go
          into the current directory, not the original source file
          directory.

        MACTOWAV -v -n *.*
          will show the Verbose info on all the mac files in the
          current directory without producing any .WAV files.


        To get Mac files to a PC, just go pop a PC diskette in a 
        Mac and copy the files over.  The Mac is smart enough to
        figure this stuff out.  



        USAGE NOTES

        The files I used were all system sound files.  System 
        sound files store all their data in the Resource Fork.
        For the PC this means that you'll have lots of 0-length
        files in the root directory and lots of actual data 
        files in a subdirectory called "RESOURCE.FRK".  You
        don't want the 0-length files.  Just copy the files over
        from the subdirectory and convert those.

        If you have access to a Mac hard drive through a network,
        please let me know how this stuff works out.  I haven't
        tried it myself.

        The output is a .WAV file whose nams, unfortunately, is 
        not necessarily related to the name of the original Mac
        file.  Mac resources have actual names.  The Mac resource
        names are valid Macintosh filenames.  They are not valid
        DOS 8.3 names.  But they are valid NTFS and VFAT names,
        almost.  So, since I'm running VFAT (Windows 95) I take 
        the Macintosh filename, (fix it up a little bit) and add 
        ".WAV".  The result is that files named "!ANAWESO.MEB"
        get written out as "An awesome buzz.WAV".

        If your version of DOS doesn't support long filenames
        (through the 71xxh extensions) or if you use the -S
        option on the MACTOWAV command line then the original
        Mac converted filename is used with the extension 
        converted to ".WAV".  

        In either case you might have filename collisions if you
        convert several files.  For example, FILE.1 and FILE.2
        will both convert to FILE.WAV.  Last one wins.

        Note: If you extract sound files from a file that
        contains more than one "snd " resource and you're using
        "short filenames", you will wind up overwriting all but
        the last one extracted.  Sorry, but I don't feel the
        urge to do auto-renaming right now.  Consider this "an
        exercise left for the student."



        DOMAIN

        I hereby release this code to the public domain.  Steal
        it, hack it, use it, resell it.  You can also post it on
        Compuserve or any other BBS or online service, ship it
        on disk for any charge, print the source code in a book,
        or use the code as an example of "a true hack".  If you
        do find it at all useful, I would appreciate hearing
        from you.  Drop me some mail to PhilHord on AOL, or to
        PhilHord@aol.com on the internet.  Here's a sample
        message if you aren't feeling creative:


          Dear Phil,
  
          Thanks so much for giving me this wonderful utility
          which, even though this statement was originally
          authored by you, is not warranted to be anything more
          than a random arrangement of electrons.
  
          The MacToWav utility  (check one or more)
  
            [ ] really made my day!
            [ ] made my system sound great!
            [ ] crashed!
            [ ] does not warrant such a complex readme file
            [ ] is unacceptably bad code coming from a 
                      professional programmer such as yourself
            [ ] made me a millionaire!
    

          I plan to (check one more)
      
            [ ] continue using MacToWav personally
            [ ] port MacToWav to another OS
            [ ] recommend MacToWav to all my friends
            [ ] resell MacToWav and keep all the profits
            [ ] include MacToWav on a commercially distributed CD-ROM
            [ ] write about MacToWav in my magazine/periodical
            [ ] delete MacToWav from my system
  

          I think (check one)

            [ ] you don't know what "a true hack" really is
            [ ] you spent way too much time on this readme file
            [ ] your lack of (code) comments is appalling
            [ ] you are a Fine Human Being
  

          Please (check one)

            [ ] continue to write great utilities
            [ ] send me the latest version of MacToWav via e-mail
                    (mine is dated: 01/07/95)
            [ ] send me your resume
            [ ] fix MacToWav to work for me
            [ ] don't ever darken my serial cable again!
            [ ] rot in Hell
  

          Sincerely, (check one)
  
            [ ] Richard M. Nixon
            [ ] Dave Barry
            [ ] Berke Breathed
            [ ] Gary Larson
            [ ] Nicklaus Wirth
            [ ] Bill Gates
            [ ] Other  (Please specify: ______________________________)



        Of course, personal messages will also be accepted.
        If necessary, you can snail-mail me at 

                Phil Hord
                1463 Janice Court
                Lilburn, GA 30247



        NASTY DETAILS

        Since I wrote it on the PC I had to write my own Mac
        resource cracker code.  This wasn't too difficult since
        I had the Mac technical information handy.  The code is
        exceedingly inelegant.  It is truly a hack.  I've
        included the source code in case anyone is interested.

        To make the program more useful I made it a DOS app
        instead of a Windows app (so I could easily run it with
        command line arguments and in batch files and such).

        Since it's a DOS app, though, I had to write my own Wave
        file output routines.  These, too, are an extreme hack.
        Basically I write a straight WAVE header with calculated
        data sizes and what-not, with no "proper" chunk
        formatting to speak of (except that I do have a
        FormatHdr structure).


        Here's a basic run-down of the code, by function:

        MacLong and MacShort convert little-endian numbers to
        big-endian.  This helps in reading Mac files.

        Main parses arguments and produces filenames.

        MacToWave takes a filename, opens the file, reads in 
        the file offset pointers, walks through the Map
        record looking for "snd " types and find names,
        and then it calls CrackSnd for any "snd " types.

        CrackSnd reads in the "snd " resource Format (I
        support both Snd1 and Snd2 formats), reads in each
        of the skips the Data Formats types (I don't know
        what to do with these), reads each of the Sound 
        Commands, and for each one supported, finds the 
        data and calls WriteWave.

        WriteWave figures out the length of the data (still in
        the Resource file), creates an appropriate RIFF/WAVE
        PCM data header for it, writes it, and then copies
        the (presumably) PCM data from the Resource file to
        the Wave.

        longrename and longremove, repsectively, rename and
        remove filenames using long-filename support functions.
        If this fails each function falls back to using the 
        short filename function and the shortfilename alternate
        provided in parameter list.


        A few notes on the Mac resource file format:  

        The Sound Resource documentation I had was very unclear
        about the Sound Commands.  It did imply that any command
        with the 0x8000 bit turned off would not have a raw data
        section from which to read PCM data.  It also implied
        that the PCM data command indicator was 0x8051.  In the
        sound files I looked at I discovered that 0x8050 was 
        also a valid PCM format.  I haven't seen any others.  If 
        anyone has more information on these "commands" please 
        let me know.
