User Guide for gWave
Copyright (C)1998 Cornel Huth
Last update 15-May-1998


  Technical support for this package is available only for this package;
  everything known about this package is detailed in the pages following,
  or at least as much as I know.

  If you need support in using your sound card, contact the one that
  sold you the card, or the card maker.  Technical support is reserved
  only for those that have registered because time is money and I have
  not as much of either as I could use.

  If you haven't looked over the README yet you're in the wrong place.


This User Guide steps you through installation and basic use, covering
the following:

  I. Basic Setup
     A. Install
     B. Tech Support
     C. What Else Can I Get

 II. Basic Use
     A. gWave MPEG Audio Decoder

III. License Agreement


To make use of this guide load it into any standard text editor and
search on words, error codes, etc., as needed.  It's best to read it
all the way through at least once before using this software and before
requesting support.


             The README file has additional info,
                   such a demo limitations
                   and all recent changes.


---------------------------------------------------------------------
Basic Setup
---------------------------------------------------------------------

Installation is simple and easy; just follow the directions.  To
uninstall just delete all files in this package.  If you did not
just get this package from http://40th.com you should first do so;
current versions will always be there long before anywhere else.

A. Install
   -------

   1. Unzip the package to any empty directory

   2. Move the gwave*.exe files to a directory in PATH

   3. Create program objects for the gwave*.exe files (optional)

   4. At this point the gwave*.exe files are ready to use once you
      read the following documentation


B. Tech Support
   ------------

   If you have registered and have a support question or comment on
   the gWave send e-mail containing as much info as possible to

        gwave@40th.com

   If you are evaluating gWave, no support is available.


C. What Else Can I Get
   -------------------

   Take the Express elevator to

        http://40th.com/

   and have a look around.  Download anything and everything.

   Coming soon are more gWave apps.


---------------------------------------------------------------------
Basic Use
---------------------------------------------------------------------

A. gWave MPEG Audio Decoder
   ------------------------
   gWave MPEG Audio Decoder (gwavemd.exe) plays standard MPEG-1 and MPEG-2
   layer I, II, and III mono and 2-channel stereo files using DART.

   Sample MPEG audio files can be downloaded from hobbes.nmsu.edu in
   /pub/multimedia/wave/mpeg.  MPEG-1 layer III 44.1kHz 128 kbps stereo
   files are (can be) very near-CD quality, at less than 1/10th the size.
   In MPEG-2 files, an 8 MB file could store a medium-quality mono
   recording of nearly an hour.  The trade-off of MPEG is that it requires
   a powerful CPU to decode:  no less than a P5/100 should be used when
   playing back in real-time, and the more power the better if multitasking.

   The key advantage to MPEG audio is that it takes up 1/10th the size of
   PCM/CD files.  This means you can compile your own compilations from
   CD songs you already have and play them from your computer -- the
   ultimate 'Greatest Hits' compilation.  If you have a CD burner, you
   can put more than 10 hours of near-CD quality songs on each CD.  Or,
   you can store about 300 songs per GB of hard disk space.  To create
   an MP3 file you need a program to copy your CD songs (tWaveDAE will
   do that), and an MPEG audio encoder.  There is no current tWave
   encoder but you can find encoders at http://hobbes.nmsu.edu, and
   elsewhere.


   Use the following, optional switches to control initial setup:

     [C:\]gwavemd [-switch] [one_shot_file_play.ext]

   -wd:n    n defaults to 0, or the default wave device.  If you have
            more than one wave device you can specify it here.  For
            example, if you have an OPL3-SA3 as the default device
            and an SB16 as the second device:

            -wd:0  uses the opl3-sa3
            -wd:1  uses the opl3-sa3
            -wd:2  uses the SB16

   -bk:n    n defaults to 12.  Individual sound buffer size, in KB.  Some
            drivers may not like certains sizes.  For example, all Crystal
            1.x drivers sound odd at sizes less than 12 KB.  Soundblaster
            drivers work down to 1 K okay, though that's not recommended.
            The max size is 60.  The larger the buffer the slower the FA
            and VU displays appear, all else the begin equal.

   -bt:n    n defaults to 30.  Number of tenths-of-a-second to buffer sound,
            from 10 to 100 (1 to 10 seconds).

   -p:x     x defaults to 3(00).  This specifies the priority of most secondary
            threads, either 2, 4, or 3.  Priority 3 is the highest.  If you
            prefer you can use the full class:level (e.g., -p:302), instead.
            The watchdog thread is always 0x31F.  A priority of 3 is
            recommended since it often provides better overall system
            performance, even and especially when lots of other stuff is
            going on.  The class (the 3 part of 302) may be changed by menu
            selection though the level (the 02 part of 302) you use here
            remains the same throughout (level=0 is the default).

   -pp:x    x defaults to 3(03).  This specifies the priority of the main,
            PM thread.  Priority 4 is probably not useful for this.  For
            example, -pp:3 would use 300; -pp:303 would use 303.  By default
            the highest non-trivial thread priority used by gWave is 300 in
            normal use and 302 when STOP'ing play.

   -pl:x    x defaults to 2.  This specifies the priority of the initial file
            load and decode (which covers the first -bt: amout of time).  A
            normal priority is recommended here to minimize impact on other
            apps, especially another foreground app.

   -novu    Disengage VU display at startup.

   -noffa   Disengage real-time frequency analysis at startup.

   -ibe     Ignore bad error.  Use this if you do not want to stop on a
            file that was so bad that it cannot be played.  Otherwise play
            stops waiting for input (Next, Play, ...).

   -fad:n   n defaults to 5.  This controls the decay rate of the frequency
            analysis display.  The range is 0 to 10.

   -fft:n   n is the size of the FFT performed, from 7 to 11 (default
            is 10).  When 8 to 11 a high-precision display is used for
            the lower bins.  128,256,512,1024,2048 can be used for
            7,8,9,10,11 (since 2^7=128,...).

            Only 16-bit data is analyzed.  FA is optimized for 44100/
            stereo playback.  For mono or 22050 files, using a smaller
            -bk: will speed up redraws; the displays are updated after
            every buffer is played, so the smaller the buffer the faster
            the display is updated.

   -ext:a   a=extension to scan during list box loads (def=mp3).  Only
            the current directory is scanned.  To scan for all files
            in the current directory use -ext:*.  The extension can be
            up to 15 characters, and is appended to the string "*."
            for searching.

   -xp:n    n defaults to 0, the horizontal screen position to start at,
            in dialog units.

   -yp:n    n defaults to 0, the vertical screen position to start at,
            in dialog units.

   -bg:x    x defaults to CCCCCC hex (gray), the main background color.
            This is an R-G-B color (RRGGBB digits).

   -fg:x    x defaults to 000000 hex (black), the main background color.
            This is an R-G-B color (RRGGBB digits).

   -to:n    n defaults to 11 seconds for the watchdog timeout.  Range
            is 3 to 30 seconds.  If the PM thread has not sent a timer
            message to the watchdog thread over this period the app is
            exited with a rc=640 timeout error message box.  The watchdog
            thread is hit once every two seconds by a PM timer.

   -key:    Reserved for registered users.  tWave users should e-mail
            gwave@40th.com to request a key.


   If a filename is specified (anything on the command line without a
   leading dash is considered a filename), it may include the full path.
   Doing this puts gWaveMD in a one-shot mode -- after play the app exits.
   You may press STOP to prevent the auto-exit.


   To control gWaveMD after startup, right-mouse-button (RMB) in the
   VU/FA display area to bring up the menu for non-listbox related
   settings, or RMB in the listbox to bring up its menu.  You can also use
   Ctrl-V or Ctrl-L, respectively, to bring up the menus.  Pressing
   the Play button while playing pauses.  Press again to resume.

   The VU/FA menu includes VU and FA enable, FFT size, clip correct,
   priorities, and window size.  Clip correct prevents future clipping but
   on -corrupt- files it may reduce the levels too much.  Disable this to
   restore levels for that file (level change delayed for -bt: time).

   The listbox menu includes random play, loop, refresh, de/select all.
   Random play uses the selected files in the list box, and once play
   starts the file is deselected.  Loop, when playback reaches the end of
   the list in non-random mode, loops back to the top of the list.  Refresh
   reloads the listbox from the current directory (removing any current
   selections).  To select files, click on the name.  Re-click to deselect.
   Or, use Select/Deselect All.  If "No File" appears in the lower left box,
   press Next or Prev to position to a file before pressing Play.


   If you have MP3 files spread out in many directories you may not like
   the way gWaveMD operates since it only works in the current directory.
   Typical use would be to create a program object and have that set the
   current, working directory.  Or, you could use a .cmd file and have it
   switch to whatever directory you wanted and then start gWaveMD.


   You should be able to run as many instances of gWaveMD as you need.
   Once play starts on a new instance play on the last playing instance
   stops.  Once you stop play on the new instance play on the previous
   instance resumes.  If you have more than one soundcard you can play
   each at the same time (CPU power willing) by using the -wd: switch.


   Error codes are MCI or MMIO Guru codes.  If you don't see the obvious
   error of the play, send the rc= code, and any other info, to the
   support e-mail address, if registered.  The error code itself is
   usually just in the lower word, so subtract 65536 if above this.

---------------------------------------------------------------------
License Agreement
---------------------------------------------------------------------

 Before using this software you must agree to the following:

    1. You are required to have one license per computer that has the
       software installed.

    2. Technical support is provided free of charge for 14 days from
       the first support question.  Thereafter, $20 for each additional
       2-week support period.  In-version updates of the software are
       free.

    3. The software is owned by the author, Cornel Huth, and is protected
       by United States copyright laws and international treaty provisions.
       You are not permitted to make copies of this software except for 
       archival purposes. 

    4. You may not rent or lease this software. You may not transfer this
       license without the written permission of the author.  If this 
       software is an update or upgrade, you may not sell or give away 
       previous versions. 

    5. You may not reverse engineer, decompile, or disassemble this
       software if the intent or result is to alter the software. 

    6. There are no expressed or implied warranties with this software.

    7. All liabilities in the use of this software rest with the user.

    8. U.S. Government Restricted Rights.  This software is provided
       with restricted rights.  Use, duplication, or disclosure by the 
       Government is subject to restrictions as set forth in 
       subparagraph (c)(1)(ii) of the Rights in Technical Data and 
       Computer Software clause at 52.227-7013. The software is 
       owned by Cornel Huth/6402 Ingram Rd/San Antonio Texas 
       78238/USA.  This agreement is governed by the laws of the 
       Great State of Texas, the United States of America, and all other 
       countries of Earth. 
  
 Any questions concerning this License Agreement should be directed
 to Product Support.

 Failure to comply with any part of this License Agreement may result
 in license revocation.
--
<eof>


