AYPLAY V0.3 by James McKay (C) 2000
===================================
Date : 26/03/2000

V0.2 was released on the 26/08/1998.


V0.3 Features:
==============
* SB16 support.
* Can use IRQs 8-15 under Windows DOS shell or other DPMI server.
* Can dump AY files into the INI/BIN format for AYMAKE.


V0.2 Features:
==============
* Capable of playing 48K tunes.
* ACB/ABC stereo for SB Pro *ONLY*!
* INI file.
* Now recognises multiple blocks per song - more tunes work.
* Bugfix which should have been in place in V0.1 finally implemented!
* Bugfix - hopefully no more SB lockups!


This software allows you to play AY-3-8912 Spectrum tunes through the SB,
output can be up to 44Khz, you can also output the sound to a VOC file.
Stereo is only guaranteed to go up to 22Khz.
It's a bit like SIDPlay (or PlaySID) in operation.  This program is for DOS,
uses non-portable assembly code (for some parts) and is proud of it!

This is basically a snippet of the current version of x128, which features
the same sound routines.

Also features:

* No scrolly.

* No background processing, multitasking or anything like that.

* No nothing!


Requirements
============

A SB 2.0 or above, although an SB 2.0 may not be able to go above 22Khz.
A 486 can handle up to 44Khz, maybe a 386?  If the PC is too slow, then fuzz
and crackle will creep into the tune, try using a lower sampling rate.

NOTE : A 48K (beeper) tune will take up a LOT more CPU time.

MAKE SURE THAT YOU HAVE DOS4GW.EXE IN THE PATH OR IN THE DIRECTORY.

Also make sure that you have set up your BLASTER environment variable
correctly.


Limitations
===========

* AYplay requires a minimum of a 386 (just to work, this is not a comment on
  speed).
* AYplay can use IRQs 8-15 for generating sound, but only with a DPMI server.
* Soundcard sticking is now rare, but the variations between cards cause
  problems.  If you have any difficulty, try setting the INI file with
  SampleRate=22050, SBpro=NO, SB16=NO.
* No long filename support.


What files can it play?
=======================

The tunes that this can play are those that are used on the Amiga's DeliAY,
part of the DELI-Tracker.  On the Amiga they would be called something like:

AY.NeverEndingStory

or...

EMUL.NeverEndingStory

but for this you'll just have to rename it to:

NEVEREND.AY

Only files with a .AY extension will be accepted, also only files of the type
ZXAYEMUL will work.  Note, "ZXAYEMUL" are the first 8 bytes of the file.


Controls
========

F1 - Help.
F5 - Load.
F10- Quit (Instant).
F11- Sound Options.
Cursor Left - Play the previous tune.
Cursor Right - Play the next tune.

Secret Option - Shift-F5 - Load any file as an AY, regardless of extension.

F1 - Help.
* You can select all the options from here, but it serves the additional
  purpose of allowing you to start the VOC file output exactly from the start
  of a tune.  So F1, load tune, select tune, sound options, open VOC, type
  name, Esc, Esc.  You'll see what I mean!  Selecting a tune is done by going
  to "Tune :" and pressing left or right.

F5 - Load.
* Just select the file.

F10- Quit.
* An immediate quit without prompting for confirmation.

F11- Sound Options.
* Open/Close VOC file.
* Open/Close PSG file.

When opening a file the extension is automatically added, so you don't need
to type it.  You may be prompted if you want to overwrite an existing file,
can you figure out what to do?  If you quit the emulator then all files will
be closed even if you had forgotten to do it yourself.

The VOC file is saved at the same sampling rate as is being played, it is
also mono, unpacked and 8-bit.  Technically, it consists of one big block.
If you are playing the tune in stereo then it will be saved in
stereo, unpacked and 8-bit - possibly incompatible with a lot of things.

WARNING!  If you are in stereo mode with Mono selected then the output
will still be in stereo, but with the same thing coming out of both
speakers.  The result would be a double sized VOC file!  If you are making a
mono VOC then make sure that you have disabled stereo (some options will be
unselectable in the F11 menu).

A PSG file is an old file format which just takes the register outputs of the
AY chip and notes interrupt positions, the PSG file format went through many
changes in it's tiny lifespan, and this is a really old one - there is no
info in the header.  The only purpose it serves is to be used with PSG2YM
(available separately) which allows you to play the tunes on the STSound
program.  Note: there are two PSG2YM programs.  One is a tiny command line
thing written by me, the other one is a big fancy one by someone else.

There are no known PSG players.  PSG format cannot handle 48K tunes or any
samples.

* 48K Volume : LOW or REAL.  You may want quieter 48K sound to avoid starkly
  contrasting volumes between a 128K and a 48K tune, but if the tune uses
  both the AY chip and the internal speaker then you will probably need the
  accuracy of REAL for it to play correctly.

The following options will only be available if you have activated the stereo
mode from the command line or INI file (and have appropriate BLASTER
environment variable).

* Stereo : Mono, ABC or ABC.

Allows you to choose the stereo mode.
Mono - As we all know it, or "Monaural" as some people know it.
(Normal for most models of Spectrum).

ABC has A - left, B - both, C - right.
(Like the Pentagon and Scorpion).

ACB has A - left, C - both, B - right.
(Like the Amstrad CPC and modified Spectrums).

* Speakers : Normal or Swapped.
If "Swapped" then left output will play from right speaker and vice versa.

* Dump AY File. (Available if an AY file is opened).

This breaks the AY file down into INI and BIN files for AYMAKE to
reconstruct.  The files are put into the same directory as the AY file.


Command Line
============

If you enter no parameters then the loading menu pops up automatically.

/?  - Lists available options.
/hz - Select sampling rate, anything from 4000 to 45454 is accepted.
      The default sampling rate is 22050.
/sbpro - Activate stereo mode, but you must also have T4 or greater in your
      BLASTER environment variable.
/sbclone - If you are trying to go above 22050hz and you do not have a 100%
      SB or compatible, then it may not recognise the Auto-Init High Speed
      DMA command (0x90), if you find that your PC completely locks up when
      you try to go above 22050hz then use the /sbclone option as well.
/sb16 - Uses SB16 commands to play sound.  If you want stereo then you have
      to set /sbpro as well.
/swapspk - Swaps the output of left and right speakers in stereo mode.
/audio <mono|acb|abc> - Select the audio output mode.
/48vol <low|real> - Set the 48K (internal speaker) volume.

You can also do:

AYPLAY tune.ay

And it will load and play without going to any menus.

You should supply a full pathname if you're planning to dump it, eg:
AYPLAY c:\ay\tune.ay


INI File
========

The same options as the command line are available and are commented in the
INI file, so you should have no problems changing it...


AY File Format
==============

Download AYmake if you want to try and make some AY files yourself, although
bear in mind that you must already be capable of hacking out tunes, AYmake
only helps you to turn them into AY files.


Credits
=======

James McKay (me).
Duncan McKay (Original web page designer (but not any more)).

AYplay and AYmake now live on the World Of Spectrum site!
http://www.void.demon.nl/spectrum.html

Patrik Rax - Author of the ZXAYEMUL format.

SB playing library generously donated from Tomaz Kac's PlayTZX utility.

The square wave generator, random number generator and method of counting are
from Ville Halik's AY emulation for fMSX Unix, although I have modified the
rest fairly substantially.

Ulrich Doewich for his Ensoniq soundcard testing.
The guys on the TAPER mailing list for their comments and info.
