Amiga ACS 1997 #4/amigaacscoverdisc1997-041997.iso/w_acs_6'97/smartplay/doc/smartplay.doc

Text File | 1993-06-22 | 24KB | 530 lines

93/06/22

             Documentation for SmartPlay v3.1 by Xtreme Intelligence
            =========================================================


 General About SmartPlay:
 ========================

  SmartPlay is a quite small, and really fast multiformat moduleplayer for
  OS2.0+. SmartPlay supports most moduleformats around, and  will play all
  modules with the _right_ replayroutines. The CPU usage of this player is
  also really low, so  it  will run fine even on a 7MHz Amiga, while doing
  some highspeed serial transfers.

  SmartPlay features a smart way of loading the normal ST/NT/PT/PM modules
  into either  CHIP  or  FAST  memory, loading the samples one by one into
  memory. And as the fastplayer doesn't need the 260K CHIP buffer anymore,
  the new "Chip Save" mode should be quite useful even for daily use.

  Nowadays SmartPlay is really easy to use,  featuring  that  improved CD-
  style userinterface, and  the easy way of selecting the modules to play.
  All kinds of packed modules are also supported; both LhA, XPK and Power-
  Packed modules will automatically be decrunched & played.

  So, SmartPlay v3.1 should  be  the  ultimate moduleplayer for people who
  like  really  small & fast 100% assembler coded programs. SmartPlay v3.1
  is able to play most moduleformats, with _low_ memory  usage,  and  fast
  replayroutines. Like it!


 SmartPlay v3.1 Main Features:
 =============================

     => Supports most moduleformats around. (About 20 different formats)
     => Reliable & Fast FastMemory replayroutine for BIG modules
     => Full LhA, XPK, and PowerPacker support
     => FAST replayroutines. Very low CPU-Usage (Nice for modemtrading)
     => Simple CD-Style userinterface. (Optionally removeable)
     => Logarithmic realtime Volume & Balance controls
     => Nice fast-selection of modules to play, right from the mainwindow
     => Easy to use programlist editor (Featuring multipath programs etc.)
     => Unlimited amount of modules in one programlist
     => Possibility to Save/Load/Play/Link programlists
     => External shared replaylibraries used to reduce memory/disk usage
     => Still possible to use as a simple commandline program
     => SmartPlay is tested on A500-A3000 running OS2.0 and 3.0

  Smart enough? Well, future versions of SmartPlay will include full ARexx
  and  WBench support, an extended programlist editor and many new module-
  formats, to mention a few improvements.  Send  any  ideas,  suggestions,
  possible bugreports, or new/not currently supported moduleformats to the
  author. (Address below)


 Supported ModuleFormats:
 ========================

  These ST/NT/PT/PM formats are replayed using the  internal replayroutine
  in SmartPlay: SoundTracker 31ins., StarTrekker, NoiseTracker, ProTracker
  PowerMusic, and ST/NT/PT SONG files. The following formats are supported
  trough the different SPlay_xxxx replaylibraries:

      Format:              Library Used:       Ver:  VBLPP
    --------------------------------------------------------
      BPSoundMon           SPlay_BPSM.library  v2.0  ----*
      DeltaMusic v2.0      SPlay_DELT.library  v1.0  ----*
      Digital Sound Studio SPlay_DSS!.library  v1.1  *---*
      ST/NT/PT/PM FASTMEM  SPlay_FAST.library  v6.4  *-***
      FutureComposer 1.0-3 SPlay_FC10.library  v1.1  *---*
      FutureComposer 1.4   SPlay_FC14.library  v1.1  *---*
      GMOD                 SPlay_GMOD.library  v1.0  ----*
      Promizer v1.8        SPlay_PROM.library  v1.0  ----*
      (Octa)MED(Pro) 4ch   SPlay_OMED.library  v1.0  *----
      SoundFX v1.3         SPlay_SF13.library  v1.0  ----*
      SIDMon v1.0          SPlay_SM10.library  v1.0  ----*
      SIDMon II            SPlay_SMII.library  v1.0  ----*
      IFF-SMUS             SPlay_SMUS.library  v1.0  *----
      SoundTracker 15inst. SPlay_ST15.library  v1.0  ----*

  The VBLPP support-flags: Volume/Balance/Loop/PositionJump/Pause

  The SPlay_xxxx.libraries should be placed in the LIBS:SmartPlay/ drawer,
  to make them easy to update for future  releases.  It's also possible to
  place them  in  the  LIBS:  root, but if you don't like to have 13 extra
  libraries  right  in your LIBS: drawer, just create that LIBS:SmartPlay/
  drawer, and copy all new SPlay_xxxx.libs into it.

  All kinds of XPK and PowerPacked  modules  are decrunched to a temporary
  directory using the xpkmaster.library v2.0+ and the powerpacker.library.

  Modules  packed  with  LhA  will  be decrunched using an external LhA/LZ
  command (defined in the configuration). SmartPlay  will unpack the first
  file in the archive to a temporary directory,  and  try  to play it as a
  normal module.

  More moduleformats will be supported in future releases of SmartPlay. If
  you have any moduleformats that SmartPlay 3.1 doesn't support right now,
  please  send  some  information  on  them  to the author, so they can be
  implemented in coming releases.

  There is no LhA program included in the  SmartPlay  archive, as most LhA
  versions are  (c) Copyrighted.  Any LhA or LZ  program should  work just
  fine with SmartPlay.


 Using SmartPlay v3.1:
 =====================

  System requirements:   Any Amiga running OS2.0 v37+ (Required to run)
                                ReqTools.library v38+ (Required to run)

  It's possible to run SmartPlay both from CLI and from  Workbench. A CLI,
  or script startup is  recommended  if  you  want  to  have access to the
  different  commandline  arguments, as no WB ToolTypes are supported yet.

  SmartPlay will create a process of it's own, so  there is no need to RUN
  the program. By default, the  mainwindow  will  be opened on the current
  PublicScreen when  run. (Check out the use of the PUBSCREEN and NOWINDOW
  arguments below in this file)

  All modules  entered  on  the  commandline, and/or selected in the file-
  requester, will be present in the programlist. You are able to edit this
  list anytime using the ProgramList Editor.

  The SmartPlay mainwindow contains the following buttons & displays:

     +-----------+-----------------------------------------------+-----+
     |    <1>    |                   <2>                         | <3> |
     +-----------+-----------+-----------------------------------+-----+
     |          <4>          |                                         |
     +-----------------------+                                         |
     |          <5>          |                   <6>                   |
     +-----+-----+-----+-----+                                         |
     | <7> | <8> |    <9>    |                                         |
     +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
     | <A> | <B> | <C> | <D> | <E> | <F> | <G> | <H> | <I> | <J> | <K> |
     +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+

  Explanations for the button functions:

   <1> - This cyclegadget will select what information the <2> area should
         show on the module. There  are  now  four modes available in this
         version: MODULE, AUTHOR, PLAYED, and TYPE.

   <2> - This area  contains  some  information on the current module. You
         are able to select what information to be  shown  here  using the
         <1> button.

         NOTE!!: A click at this button will bring up the SampleInfo list-
         window, containing the samplenames in loaded ST/NT/PT/PM modules!

   <3> - This little I=INFO knob will give some information on SmartPlay.

   <4> - This is the volume gadget, where the replayvolume is selected.

   <5> - This is the balance gadget, where  the  balance between the LEFT,
         and RIGHT audiochannels is selected.  Both  the  Volume  and the
         Balance values are saved in the configurationfile.

   <6> - This is the listgadget, where you may select any of the 5 visible
         modules just by clicking on them. Also, you may scroll up/down in
         the  whole  programlist  and  select any module you want to play,
         right from the  mainwindow. The  current  module  playing will be
         highlighted, so it's  easy  to know the "current position" in the
         list.

   <7> - Loop Modules ON/OFF button. (Highlight = ON)

   <8> - Fader ON/OFF button. (Highlight = ON)

   <9> - Random play ON/OFF button. (Highlight = ON)

   <A> - Load & Play previous module in the programlist.

   <B> - Jump to previous position in module.

   <C> - Load & PLAY current module again if stopped.  Can also be used to
         CONTINUE paused modules. If  there  are  no  modules, or just one
         module present in the program,  SmartPlay  will  bring up a file-
         requester  to  select  some  modules  to  play and include in the
         programlist. If  there  already  is  a  module  playing,  and the
         program  contains  two  or  more modules, you will be able to add
         more modules to the  end  of  the current program using the file-
         requester.

   <D> - Jump to next position in module.

   <E> - Load & Play next module in the programlist.

   <F> - Pause playing. The interrupt will be removed, but the module will
         NOT be deallocated. Press PLAY or PAUSE to continue playing.

   <G> - Stop button. If there is a module playing, the  interrupt will be
         removed and the music will stop, but  the module wont be ejected,
         so it's  possible  to  start  the module again from the beginning
         by pressing PLAY, without  loading it from disk again. The Audio-
         Channels will also be deallocated when  the  module is STOPPED or
         PAUSED.

   <H> - This is the EJECT button. If there is a module loaded, this  knob
         will eject  it  from  memory. If there is NO module playing, this
         EJECT button will clear the whole programlist!

   <I> - This button marked, "><" or "<>", will shrink or expand the main-
         window. This  will save some chipmemory, and all the CD-Interface
         functionbuttons <A-K> will still be visible.

   <J> - This  button,  marked  with  a "?", will bring up the new config-
         window. Read the chapter "Configuration Window" for more info.

   <K> - The  ED  button  will  bring up the ProgramList Editor. Check out
         the chapter "ProgramList Editor" for more information on this.


 Configuration Window:
 =====================

  These  are the explanations for the ON/OFF flags on the left side of the
  configuration window:

  VBLNK Interrupt => If this is ON,  SmartPlay  will use the VerticalBlank
                     interrupt instead of the CIA interrupt. The CIA mode
                     will work on ALL machines, even if the vertical blank
                     frequency is over/under 50Hz.

                     ProTracker  modules using the CIA speed-commands will
                     get some problems in VBlank mode, but for normal mods
                     the VBlank mode is slightly faster than the CIA mode.

                   - CommandLine argument: VB=VBLNK

                   - Default state: OFF

   Error Request. => Enables the various error-requesters.

                   - CommandLine argument: NE=NOERROR

                   - Default state: ON

  Strip MOD. text => This Strip routine will strip the mod. texts from the
                     modulenames in the modulelists.

                   - Default state: ON

   Alloc Channels => Enables the allocation of the AudioChannels.

                   - CommandLine argument: NA=NOALLOC

                   - Default state: ON

   L+R Mouse Stop => Enables the L+R MouseButton STOP function.

                   - CommandLine argument: NM=NOMOUSE

                   - Default state: ON

  DoubleBuffering => Enables the DoubleBuffer function. When DB is active,
                     modules will be  loaded  while the previous module is
                     playing.

                   - Default state: ON

  Flush SPlay_Lib => Enables  the  FLUSH  routine, removing all used SPlay
                     replaylibraries on exit.

                   - Default state: ON

  Explanations  for  the  string-gadgets  on the right side of the config-
  window, containing  all the Default  Paths, and LhA  commandstrings etc.
  used by SmartPlay:

        Def. Path => The Default Path is  used  in the filerequesters when
                     selecting modules to play.

     Def. Pattern => The Default Pattern is  passed  to the filerequesters
                     to prevent modules with the specified extensions from
                     being shown/loaded.

     LhA/XPK Temp => This string contains the name of the Temporary drawer
                     to be used by  SmartPlay  while  decrunching  certain
                     packed  modules. SmartPlay  will  create  a temporary
                     directory of it's own inside  the  specified  one, to
                     prevent   possible   files  already  present  in  the
                     specified drawer from being overwritten by LhA/XPK.

      LhA Command => The LhA Command string should contain the  full path,
                     and  filename  of  the  LhA/LZ  command to be used by
                     SmartPlay to decrunch LhA packed modules.

    LhA Arguments => The  LhA  argument  contains  all  needed  arguments,
                     except  the filenames,  for the LhA  commands extract
                     function. Typical  strings are:  "-N e >NIL:" for LZ,
                     and "-q e" for newer LhA versions.

  The "?" and  disk-pictured  gadgets on  the  right  side  of  the string
  gadgets  are  associated  with  them. By  pressing  the "?"  gadget, the
  default argument  will appear into  the string  gadget in  question. The
  disk-pictured  knobs on  the other  hand, will  let you  define a drawer
  using a filerequester.

  The "Load To Fast" options on the  right  side of the window are used to
  choose  when  modules  should  be  loaded  into  FastMemory  instead  of
  ChipMem.  The Default  setting is  "When Needed", which  will  load  the
  modules to chip as long as there is enough  free chipmemory. The "Never"
  mode will  prevent  SmartPlay from  loading the modules  at all if there
  isn't enough  chipmemory.  "Chip Saver" can  be  used to  keep  down the
  chipmemory  usage of the player, by loading the  modules into fastmemory
  only when the size of  the CHIP  buffers doesn't exceed the total amount
  of chipmemory needed for all the samples in the module.

  The  SAVE  button  will save the SmartPlay configurationfile both to the
  ENV:SmartPlay/SmartPlay.Config and the ENVARC:SmartPlay/SmartPlay.Config
  files. The  USE  button  will only save the config to the ENV:SmartPlay/
  drawer. The  WindowClose  button  will  exit  the  configuration without
  saving anything to disk. The SmartPlay directory in ENV: will be created
  automatically if not found at startup.


 ProgramList Editor:
 ===================

  The  programlist editor is used to  edit  the current list of modules to
  be played, specified  on  the commandline, or in the filerequester.  You
  are able to delete/add entries to  the  list, and to save/load the whole
  program. The programs can also  be loaded  from  the  commandline, as  a
  "module" in the module argument,  or selected in the filerequester using
  the PLAY button.

  The big box in the middle of the  editorwindow is  used  to  display the
  contents of  the  current programlist. When you click on an entry in the
  list, the  entry  will  be  moved to the small box below. From there you
  can insert it into any location in the  list, or delete it using the DEL
  button on the editorwindow.

  Explanations for the button functions on the ProgramList Editor window:

    ADD - Add one or more  modules  to  the  current  programlist, using a
          multiselect filerequester. The modules selected will be appended
          to the end of the list.

    DEL - Delete the current entry in the small box below the actual list.

  CLEAR - Clear the current programlist.

   SAVE - Save the  current  programlist to disk.  The  program  files are
          saved with the .PRG extension, and may be loaded in this editor,
          from the commandline, or using the PLAY button.

   LOAD - Load a new programlist to  SmartPlay.  The previous list will be
          cleared before loading!

    USE - Quit the Editor, and  accept  the  changes  made  to the current
          programlist.

  Well,  if you  don't  understand  how  this  editor really works just by
  reading these tiny DOC's, just go out and try it out for yourself!  It's
  really quite easy to use when you get used to it. Hope you like it..


 CommandLine Arguments:
 ======================

  SmartPlay v3.1 also includes the  possibility  of using some commandline
  arguments. This template contains most of the options in the config, and
  will override all options set in the configurationfile.

  TEMPLATE: MODULE=PROGRAM/M,STOP/S,NEXT/S,LOOP/S,PS=PUBSCREEN/K,
            NA=NOALLOC/S,NM=NOMOUSE/S,NC=NOCONFIG/S,NW=NOWINDOW/S,
            NE=NOERRORS/S,NF=NOFAST/S,VB=VBLANK/S:

    MODULE: Name of module(s) or programfile to play. Multiselection fully
            supported. You can fill the commandline with modulename(s), or
            use the  SHIFT  key  in  the  filerequester to select multiple
            modules! The names you write here  will  be  included with any
            you possibly select in the filerequester.

            If the first entry  in  the  MODULE argument is a programfile,
            SmartPlay  will just load the program from that file, and skip
            all other entries in this argument.

      STOP: Works just as the STOP button on the mainwindow. This argument
            is mostly used when the NOWINDOW argument is active.

            Any new  SmartPlay  started will pop the screen containing the
            SmartPlay window to front, and make the  SmartPlay  Window the
            frontmost & active window on the screen.

      NEXT: Stops current module playing and  loads  next module according
            to the programlist. Equal to the <E> button on the mainwindow.

      LOOP: This will set the  LOOP  flag (toggled from the mainwindow) to
            ON if used. This will cause modules to loop at last pattern.

 PUBSCREEN: This is a keyword for the name of the  publicscreen  SmartPlay
            should  open  it's mainwindow on. If no name is specified, the
            current publicscreen will be used.

   NOALLOC: This flag will prevent the allocation of the AudioChannels.

   NOMOUSE: NoMouse or simply  NM  will set the L+R MOUSE STOP flag in the
            configuration menu to OFF.

  NOCONFIG: Prevents  SmartPlay   from   loading   the  configuration file
            "ENV:SmartPlay/SmartPlay.Config"  when  run. This  will  cause
            SmartPlay to  use  default  settings  and  place the SmartPlay
            window in the center of the screen.

  NOWINDOW: Prevents SmartPlay  from opening the mainwindow containing the
            CD-Interface, and  run  just  like  those stoneage versions of
            SmartPlay.

  NOERRORS: Prevents SmartPlay from showing any errorrequesters.

    NOFAST: Set the "Load to fast: Never" mode in the configuration.

    VBLANK: The VBlank argument will  force  SmartPlay  to use a Vertical-
            Blank interrupt instead of the CIA interrupt. This can also be
            toggled in the configuration.


 FastMemory Replayer Info:
 =========================

  The SPlay_FAST.library makes it possible to play normal ST/NT/PT modules
  right from FAST memory. This routine is quite fast, and should not cause
  any harm to your multitasking system.  A heavily loaded system may cause
  annoying  pauses  in  the music on slow Amigas, but even under highspeed
  serial transfers there is no CPS loss  while  playing  modules from FAST
  memory using this replayer.

  All functions, like  the Balance knob, and  the Fader are not currently
  supported when playing modules trough the fastlibrary. In this  version
  of the library, CIA timing should be fully supported in PT modules, and
  !PM! modules should now work in fastmemory too.


 Known Bugs in v3.1:
 ===================

  There are no serious known bugs in this version of SmartPlay, but..

  As usual  I  cannot  be  held  responsible for possible damage caused by
  SmartPlay nor bugs caused by late-hour coding..

  However,  if  you  do  find  any  Bugs,  Enforcer  hits,  or other nasty
  creatures in SmartPlay, please contact me at the address below so that I
  can fix them in the next version of SmartPlay.


 Credits For BETA-Testing & Spell Checking:
 ==========================================

  Special thanks to the following people:

     Mikael Hjelt (Eagle)
     Faith
     Spock
     Janne Saarme
     Pasi Lahtinen
     Erno Tuomainen

  I don't dare to think of what  SmartPlay  would be like without all this
  BETA testing! Also, this documentation file would probably be a BIG mess
  full of spelling mistakes. Thanx.


 How to reach the Author:
 ========================

  Send possible bug-reports, any new module formats etc. to the author
  (Xtreme Intelligence) by E-Mail at:

     Last Input Ignored (SysOp: Eagle)
     [phone]
     1200-14400 HST DS /w v32bis & v42bis
     Open always except ZMH

  ..or NetMail addressed to Xtreme Intelligence on Last Input Ignored:s
    FidoNet Number 2:220/293.

  ..or by sending snail-mail to the author (Xtreme Intelligence) at the
    following address:

      Peter Hjelt
      Heikelv. 3
      02700 Grankulla
      Finland

  The author is  often available  for chat on  another node  of Last Input
  Ignored. Don't hesitate to call if you have any problems with SmartPlay.

  The  newest  version  of  SmartPlay  is  always FileRequestable with the
  MAGIC name "SPLAY" from 2:220/293.

  If you  want  to  become a SmartPlay BETA tester, or just check out some
  BETA versions, contact the author on the address above.


 Xtreme Intelligence productions Echo.
 =====================================

  A non-backboned Xtreme Intelligence  productions echo named "XI_PROD" is
  available  to  anyone who  want  it. In it,  bugreports,  suggestions or
  problems  concerning  any of  XI's products  can be  discussed  with the
  author  directly.  Information  about  oncoming  versions  will  also be
  available. Unfortunately, as  the echo  isn't  on the backbone, you/your
  SysOp  will have to poll the echo  directly  from 2:220/293.  If you are
  interested in doing so,  please contact the author (Xtreme Intelligence)
  or the SysOp of Last Input Ignored (Eagle) in any of the  ways described
  above.


 Any COPYRIGHTS on SmartPlay v3.1?
 =================================

  Nobody is  obliged  to  pay  for a copy of SmartPlay - the basic idea is
  still to provide a  good & fast  moduleplayer  for _free_ to  the  Amiga
  users. In  other  words,  SmartPlay  is  still  released as FreeWare, or
  GiftWare, and  may be freely distributed as long as the original archive
  is kept intact.

  However, a "shareware" fee is of course appreciated, and  by sending ANY
  amount of money  to  me,  you  can  consider  yourself as a "registered"
  SmartPlay user, and you will eg. be informed about  new  releases trough
  NetMail.

                                        - Signed: Xtreme Intelligence 1993