   Ŀ Ŀ Ŀ Ŀ Ŀ ڿ    Ŀ ڿ       Ŀ    ¿  ڿ
                                           Ĵ
          ¿      Ĵ              
                                     ڿ      
                            
    

                  Written by Roman Dolejsi (RDOS of DIMENSION)

                                August 27, 1996
                   Last update: August 20, 1997


       This is the documentation belonging to and explaining the use of

                             RdosPlay version 0.21b
                   OPL2/OPL3 music module player for MS-DOS


   TOPICS covered in this document:

    DISCLAIMER
    APOLOGIZE
    PURPOSE OF RDOSPLAY
    REQUIREMENTS
    INSTALLATION OF RDOSPLAY
    RDOSPLAY IN ACTION
    PROGRAM KEYS AND DIALOG LINE
    CURRENTLY SUPPORTED MODULE FORMATS
    MODULE INFO
    FREQUENTLY ASKED QUESTIONS
    COPYRIGHT
    WHERE TO FIND RDOSPLAY
    THANX
    CONTACTING ME



DISCLAIMER:
-----------
  Although RdosPlay has been tested on several systems, I cannot guarantee that
it is bugless. Therefore I do not  take  responsibility for any damage directly
or indirectly caused by RdosPlay as a result of known/unknown  errors in it  or
errors caused by its access to your devices.


APOLOGIZE:
----------
  Sorry, english is not my  native language. However, I wrote this nice docy in
english without any help. I APOLOGIZE for any mistakes in the document. Take it
easy... Nobody is perfect.. :-)


PURPOSE OF RDOSPLAY:
--------------------
  RdosPlay is a OPL2/OPL3 music module player for IBM PC  compatible  computers
running MS-DOS operating system. This  means  that  you  can use it for playing
your  favorite  melody  from some music editor, demo or game. It is FIRST known
generic OPL player. I've coded it because of lack of any player of this type in
PC-world.


REQUIREMENTS:
-------------
  RdosPlay is coded in  pure 286-assembler  with  no 386+ optimalizations. This
means  you  can  use  your  old 286 and Adlib card for background playing while
doing some work. So the only required things  it needs  is  OPL2/3/4 compatible
card (Adlib or higher), 286 or higher and about 210kB of free mem. For  graphic
analyzers  you  would  probably  need  at  least 386-sx (not tested) due to the
comuting power required for their refreshing. The other thing you need is  some
music module of course (many of them are supplied with rdosplay).


INSTALLATION OF RDOSPLAY:
-------------------------

- first  you have to make some directory on your drive. Then you have to unpack
  there archive file RPLYxyyz.ZIP. Don't forget  to  unpack it WITH directories
  otherwise you would get a pretty nice garbage :-)
  (you probably did all this when you read these lines :-)

- RdosPlay pack should consist of these files:

    RDOSPLAY.EXE - Main file - OPL player
    RDOSPLAY.DOC - Documentation for RdosPlay (this file)
    RDOSPLAY.REV - RdosPlay changes/revision history file
    FILE_ID.DIZ  - quick info file
    FILES\*      - music module examples

- now you have RdosPlay successfully installed :-)


RDOSPLAY IN ACTION:
-------------------
  Rdosplay  uses  your  sound  card's  OPL chip  for  producing synthetic music
typical  for  these  chips. For  OPL2 (mono) musics it can also simulate stereo
by  distributing  channels  in left/right speakers. It's not possible with OPL3
musics  which  do  their  own (precise) panning. OPL2 stereo and OPL3 modes are
both possible only on OPL3 chip of course.
  When  producing  music  RdosPlay  also  shows  some  analyzers  to make world
brighter :-). This  can  be  supressed  when  using slow computers or slow OPL2
emulation (GUS users).


PROGRAM KEYS AND DIALOG LINE:
-----------------------------
While RdosPlay is running, you can use these keys:
  PgUp   - increase track of music (for ADL/AYM/SID only)
  PgDn   - decrease track of music (for ADL/AYM/SID only)
  Enter  - enter fileselector
  F      - enter fileselector
  F8     - start dos shell
  D      - start dos shell
  Esc    - end of playing (back to fileselector or system)
  F1/F2  - change OPL wave type on the fly
  Down   - double speed
  Up     - quadruple speed

In fileselector, you can use:
  Up     - move to next item
  Down   - move to previous item
  PgUp   - move half page up
  PgDown - move half page down
  Enter  - select item
  Esc    - end fileselector

Dialog line looks as following:
  RDOSPLAY.EXE [/?] [/b] [/l] [/p] [/s] [/t] [/w] <musfile.ext>

  options:
    /?      - shows help screen
    /bXXXX  - specifies starting file offset (for RAW, PSG and YM formats only)
    /lX     - enables LED-meter on LPT port
              X: port number, where:
                 0 = 3BC (EGA's LPT port)
                 1 = 378 (standard LPT1 port)
                 2 = 278 (standard LPT2 port)
    /oXXXX  - number of silent ints to stop after (default 0400h)
    /pXXX:Y - specifies port and type of OPL chip (avoiding autodetection)
              XXX: hexadecimal base port of the chip
                Y: 1 = OPL2 (Adlib compatible)
                   2 = OPL3 (Yamaha YM262 stereo chip)
                   3 = OPL4 (Yamaha OPL4 stereo chip)
    /s      - enables OPL3-stereo for OPL2 musics (omitted with OPL3 musics)
    /tXXX   - specifies track to be played (for ADL,AYM,SID formats, 1..XXX)
    /wX     - specifies OPL wave type (not available for all formats)
              X: wave type 0..3 (OPL2) or 0..7 (OPL3)

CURRENTLY SUPPORTED MODULE FORMATS:
-----------------------------------
  RdosPlay  now  supports these formats (where are they and how to get them you
can read in another section):

   ADL (Adlib format similar to XMI)
   AGD (Herad system - DUNE game)              [OPL3]
   AMD (Amusic tracker packed files)
   AYM (Z80 music code with AY music)
   CAL (ShadowLands game)
   D00 (JCH / Vibrants ver 1, 2 & 4)
   FXM (Fuxoft AY music chip language)
   HSC (HSC music composer)
   LDS (Loudness system - Zeppelin game)
   LEM (SI system - XMasLemmings game)
   MUS (First Samurai game)
   PLX (Palladix system - Logical game)
   PSG (raw AY data - X128 emulator log file)
   RAD (Reality ADlib tracker)
   RAW (raw adlib data)                        [OPL2/3]
   SAT (SAdT music composer)
   SDB (Herad system - DUNE / KGB games)
   SID (Commodore 64 music files)
   SIG (SI system 2 - DIZZY games)
   VIB (JO/Vibrants player)
   YMx (YM2149 raw data (log) file)

RdosPlay also supports some internal file packers. They are:
   HSQ (mainly with SDB,AGD - Dune game)
   SQX (mainly with SDB - KGB game)
   ICE (mainly with CAL - ShadowLands game)


MODULE INFO:
------------

 ADL

   This is  format  used  in  many games. Each  file  can  consist of up to 118
"tracks"  and  every  track  can  contain  separate  music. Default  track  for
RdosPlay is track number 1. Track can be  selected  with parameter /t. RdosPlay
will pack all used tracks so unused tracks won't be in selection field.


 AMD

   This  extension  covers  files from Amusic tracker by Elyssis. There are two
types  of them. Packed and non-packed. RdosPlay currently supports packed files
only.


 AYM

   This format has been developed to  allow replaying of original musics for AY
whose playing routines has been created for Z80 processor. Every file  contains
original Z80 code and data needed to play music on AY 3-891x sound chip. If you
know  what  this  is for and are able to dig musics yourself, feel free to send
them to me! Here is the format used:

AYM file format (created by Roman Dolejsi, comments send to roman@sorry.vse.cz)
-------------------------------------------------------------------------------
name    size    pos    info
---------------------------
'AYM0'	dword	00 ... identifier (AY Music, format revision 0)
name	db 28	04 ... music name
author	db 16	20 ... music author name
init	word	30 ... music init entry (A = music number)
play	word	32 ... interrupt player entry
musmin  byte    34 ... min music number
musmax	byte	35 ... max music number (musmax - musmin = number of musics)
muspos  byte    36 ... starting music number
regpos  byte    37 ... reg in which musnum is stored when entering init (00-0B)
AFreg	word	38 ... AF register before entering init routine
BCreg   word    3A ... BC register
DEreg   word    3C ... DE register
HLreg   word    3E ... HL register
IXreg   word    40 ... IX register
IYreg   word    42 ... IY register
blocks  byte    44 ... number of memory blocks

from pos 45h, rest of the file contains memory blocks each carrying this:
begin   word  b+00 ... where in the memory this block begins (64k addr space)
size    word  b+02 ... how long is this block
bdata  [size] b+04 ... block of Z80 music code data for AY-3-8910
                       (currently for ZX128 envir.: FFFD=Ctrl, BFFD=Data,
                        and for Amstrad CPC envir.: F6=Switch, F4=Ctrl/Data)
---------------------------

 CAL

   This  standard  is  used  in  ShadowLands  game.  Look  there  and find file
TUNE.CAL. It's ICE-packed file and RdosPlay has internal ICE-unpacker.


 D00

   These  files  are  for  JCH / Vibrants player. They are created in Vibrant's
editor  named  EdLib by packing standard *.EDL editor's files. Look for them in
intros or in that editor. Files for player ver 2+ begin with 'JCH' sign.
   Example: intro KUKKO2.EXE, offset B2A (module named CROONER.D00).


 FXM

   These  files  are  special blocks of music code used in Fuxoft SoundTrack on
ZX Spectrum computer. This  computer  has  3-channel sound chip named AY3-8910.
RdosPlay  has  FXM interpreter and AY->OPL2 convertor. All the files that exist
in this format are supplied with RdosPlay standard distribution.


 HSC

   HSC files are commonly used in short demos and intros. The source from where
they  came  is  mainly  HSC composer  which  is  available  on  anonymous FTP's
on I-net. There  you  can  get  most of these files (about 100 modules). If you
grab some file its extension must be HSC otherwise RdosPlay won't recognize it!


 LDS

   These files are used in LOUDNESS system. Look  in  ZEPPELIN game's SOUND dir
and take all *.DAT files.


 LEM

   These  files  are  used  in X-Mas Lemmings game. Grab  them  yourself. Their
sign is [0]=1C 52.


 MUS

   This standard is used in FIRST SAMURAI game. Take file ADLIB.MUS.


 PLX

   This standard is used in LOGICAL game. All  music  files  are stored in file
LOGICAL.EXE. You have  to  grab  them  from this file. Here are file positions:
13310, 165C0, 1B160, 1F320, 50360, 50550, 50730, 50990, 50B90, 50D10, 50FA0,
510F0, 51310, 56620, 59F90.


 PSG

   This  is  log  file  produced  by  X128 (ZX Spectrum emulator) and fMSX (MSX
emulator). Every access to the AY 3-891x (Yamaha's soundchip) is stored in this
file. It's much like RAW format for adlib.
   format1:  [0]=db     'PSG',1ah                  ... file identifier
             [4]=db     data                       ... AY data
   data: command or parameter  command==0-15,byte  ... next byte is data for
                                                       this AY register
                               command==0fdh       ... eom (end of music)
                               command==0feh,byte  ... multiple eoi
                               command==0ffh       ... eoi (end of interrupt,
                                                       current data will be
                                                       send to ay-emulator)

   You can also use utility PSG2.EXE to convert PSG music to another format:
   format2:  [0]=db     'PSG2'    ... file identifier
             [4]=struct data      ... AY data
   data: change_map (word)        ... bit-map specifying which regs will be
                                      changed in this interrupt. Order: L->R
                                      (when 0ffffh, end of music)
         map_size (byte)          ... specifies how many times currently
                                      defined map will be used (ie. how many
                                      times will be data send in this form)
         data (bytes)             ... data for registers, reg. 0 comes first
                                      After receiving all changes for current
                                      interrupt, data are sent to ay-emu.
                                      Map_size is decremented and when not 0,
                                      next interrupt use same change_map as
                                      previous one.


 RAD

   This format came with Reality ADlib Tracker. Tunes often have  RAD extension
and if not, there is a 'RAD' sign at the beginning of the file.


 RAW

   This format is very simple. It  consists  of  commands  directly sent to OPL
port. RAW format is used in STARPRT2.EXE intro (for example).
   format:   [0]=db     'RAWADATA'                 ... file identifier
             [8]=dw     clock                      ... clock (int8) speed
            [10]=dw     data_size dup (data)       ... adlib data
            [..]=dw     0ffffh                     ... end of file
   data: parameter, command.   command==0: data==n ... wait n times.
                               command==2: data==0 ... set speed (next word)
                               command==2: data==1 ... set OPL3 port A default
                               command==2: data==2 ... set OPL3 port B default

   This format is also generated by RAC (Rdos Adlib Catcher).


 SAT

   These  files are made in SAdT music composer. They begin with 'SAdT' sign.


 SDB, AGD

   These files are used in DUNE game. Look  in  game's directory and search for
*.SDB  or  *.AGD  files.  These  are  HSQ-packed.  You  can  unpack  them  with
UNHSQ (RDOS production)  or  use  them  as  they are. RdosPlay has internal HSQ
unpacker and recognizes both packed or unpacked modules. *.AGD files have to be
played on OPL-3  stereo  music  chip (that's why /s parameter doesn't work with
them), *.SDB are for standard AdLib (OPL-2) card.


 SID

   This  format has  been developed  to allow  replaying of original musics for
MOS6581 soundchip  found in  C64 8-bit  computer. Every file contains  original
MOS6510 (C64)  code and data needed to play music on MOS6581. There are MANY of
them (about 3000+ ?), you  can  check  ftp://frodo.hiof.no  for  them. There is
more  than  one  format for these modules but RdosPlay supports only PSID files
which often have DAT extension (file starts with 'PSID'). There  are converters
out  there  which will help you to convert modules among formats. If I remember
it right, some have been in DOS version of sidplay.


 SIG

   These  files  are used in DIZZY games. They are stored in main .EXE file and
you have to grab them. Here are  their respective filenames, offsets and sizes:
  FFOOD=6464E,3B38  KWIKSNAX=73C2E,2BC4  MAGICLND=689EE,4508  YOLK=6571E,33FD


 VIB

   This is standard used in player by JO / Vibrants.
   Example: intro COPPER.EXE, offset 8990.


 YM

   This format covers log files of the YM2149 music chip available  on Atari ST
and  Amstrad CPC. It is much like PSG and PSG2 formats (YM2149 is the same chip
as AY-3-891x). YM files  often  come LHA packed. RdosPlay knows only non-packed
files, so  you  have to unpack them :-( This format is made by Leonard/OXYGENE,
RdosPlay knows only YM1/2/3 formats, YM4+ files  were  not  available when this
format  was  implemented, so they will not be  played correctly. If you want YM
files  look for  package  stsound.zip. This format is very messy and takes much
space in memory (although it's compressed form is very short). When  there will
be XMS swapping support in RdosPlay, YM's XMS swapping will never be  supported
because it's not possible to do it (maybe YMs should be converted to PSG before
they start to play, who knows).


RDOSPLAY FREQUENTLY ASKED QUESTIONS:
------------------------------------

* RdosPlay have not detected my soundcard although I have OPL2 compatible card.
- You have to set sound card manually (ie. /p parameter).
- GUS users with SBOS running may use /p388:1.

* RdosPlay sounds HORRIBLE on GUS !
- That's the fault of OPL2 emulation on GUS, not mine. You have to stay with it
  or to wait until REMUS (Rdos Emulation Sound system) is released. It will
  bring a brand new OPL3 emulation for your GUS (hopefully).

* I have D/A converter (PC Speaker), does RdosPlay support it ?
- No, It does not. You have to wait until REMUS is released.

* I have some SAT modules and it seems some of them aren't played correctly
  with RdosPlay.
- Yes, it's the fault of RdosPlay's SAT playing routine. I have to improve it.


WHERE TO FIND RDOSPLAY:
-----------------------
Each time I have a new version of RdosPlay available, I'll upload it to
this place:

 ftp://sorry.vse.cz/dimension   (Dimension FTP site in Prague, Czech Republic)
http://sorry.vse.cz/dimension   (Dimension Inet HeadQuarters, Czech Republic)

RdosPlay will be probably also available at ftp.cdrom.com or ftp.sunet.se
FTP archives.

Another way is to visit RdosPlay's homepage at address:

   http://sorry.vse.cz/dimension/rdos/rdosplay   (Http site in Prague, CZE)


THANX:
------

Although I did all the programming, there are few friends which helped me
with some things in this program. Thanx must go to:

Frank Littman (F.Littmann developments) - MOS6581 emulation routines!!!
David Voracek (Assassin/Dimension) - testing, suggestions, new formats info..
and also other friends for their (mostly) betatesting and suggestions..

I should thank also people for sending me their suggestions, hints, bug reports
and postcards :-) This is a morale support for me to continue on this project.

CONTACTING ME:
--------------
  If you want to contact me, write to address listed below. If you want to send
me suggestions, tips or simply greets, send it freely. Also some money would be
good as a power and motivation for further work :-)  If you find any new module
format  with  its  player  you can also send it to me. You can also send me any
module you want to be in new version of RdosPlay.

My address: (for postcards :-)          E-Mail:
  Roman Dolejsi (RDOS)                    roman@sorry.vse.cz
  Husova 419                              roman@romeo.pf.jcu.cz
  37382 Vcelna
  Czech Republic

Please do not send me E-mails longer than 1MB (because of our local smtp
server limit).

*** end of RdosPlay documentation ***