     Micro Speccy
 An .AY and .AYM-files
player for Win95/98/NT
     Version 1.0
  2 of September 2001
  Author Sergey Bulba
Graphics Graham Goring
(c)2000,2001 S.V. Bulba

Features:

Emulating sound chip:	AY-3-8910 and YM2149F, linear interpolation,
			no filtering
Emulating Z80:		Most documented and some undocumented
			features, maskable interrupts
AY clock frequency:	1773400 Hz for ZX Spectrum and
			1000000 for Amstrad CPC (auto selection)
Channels allocation:	All standard combinations
Z80 clock frequency:	3494400 Hz
Interrupt period:	69888 T-States
INT signal length:	21 Z80 T-States (calculated by Pentagon 128K scheme)
.AY-files:		Only EMUL type is supported
.AYM-files:		Only format revision 0 is supported
Beeper sound:		Supported, simplified linear interpolation,
			no filtering
Amstrad CPC ports:	Emulate only writing to AY ports F6xx and F4xx
CPC frequency model:	Not supported, used ZX Spectrum model
Drug & Drop:		Supported
Command line:		Supported

Send any comments to Sergey Bulba, vorobey@mail.khstu.ru
Visit http://bulba.at.kz/ for other AY programs.

System requirements:
- Main processor
  For working - i80386 compatible
  For stable sound - Pentium 120 for playing CPC tunes
		     Pentium 133 for playing ZX AY tunes
                     Pentium 150 for playing ZX beeper tunes
		     Some beeper tunes require Pentium 166 and higher
- Sound card
  Any Windows compatible digital sound card

Note:
- Command line using

             MicroSpeccy.exe [FileName] [/key1] [/key2] ...

  for start playing from command line or (and) set parameters to values
  corresponding to keys. Available keys:
	h - chip type and channels allocation. After h use one of next
            predefined patterns:
		AYMONO
		YMMONO
		AYABC
		YMABC
		AYACB
		YMACB
		AYBAC
		YMBAC
		AYBCA
		YMBCA
		AYCAB
		YMCAB
		AYCBA
		YMCBA
	r - priority. After r use n for normal and h for high application
	    priority class
	u - beeper level. After u use decimal number from 0 to 32768 to set
	    absolute value of beeper volume level
	p - set standard skin bitmap. You can define bitmap file name after p
	    parameter for setting non-standard skin
  Example:
   MicroSpeccy.exe /u32000 /rh /hYMMONO "AY File.ay" /p"c:\AY Skins\Example.bmp"

- For playing .AY and .AYM-files by double-clicking in Windows Explorer or
  Far Manager you must register files with extension .AY and .AYM in system
  register. Follow next steps to do it:
   
   1) Run Micro Speccy and press 'Parameters' button (P).
   2) Check AY and (or) AYM option in System Register control group.

- To play file do one of following:

   1) Type in command line
	MicroSpeccy.exe FileName
   2) Drag and drop file on Micro Speccy main window
   3) Open file by pressing 'Load' button on Micro Speccy main window
   4) Double click or press Enter on selected file in Windows Explorer or
      in any other file manager

- Z80 emulation is very bad. But all of today existing .AY and .AYM-files are
  playing correctly in this version. I placed Z80 emulation source at
  http://bulba.at.kz/. Maybe some of you will found serious bugs and let me
  know to fix it.

- There are some AY-files exist on the world, which are not playing in Micro
  Speccy (and in DeliAY too). They are corrupted and I'll not be fix this
  problem. To fix these files see AY-file format and loading AY-file
  descriptions.

- Micro Speccy emulates ZX Spectrum port addresses by next scheme. Initially,
  all ports are emulating: ZX (AY and beeper) and CPC. During first writing
  to any ZX AY ports emulation switches to ZX mode (only ZX AY and beeper ports
  emulation). Otherwise, during first writing to F6xx port emulation switches
  to CPC mode (only F4xx and F6xx ports emulation at AY frequency 1000000 Hz).
  As you can see, during playing only beeper sound Micro Speccy forced to
  emulate all described ports, unfortunately. So, if you want to speed up
  emulation during playing only beeper sound, write to any ZX AY ports
  something in INIT routine of AY-file.

- MicroSpeccy.exe contents 6 icons inside of itself: from 0 to 3 by Graham
  Goring and from 4 to 5 by bcass. Icon number 0 is used as main icon.
  Icon number 4 is used for AY Files registering. All other ones you can use
  for own needs.

- You can download from http://bulba.at.kz/ skins for main window of Micro
  Speccy (in BMP format). Use any of them to create own skins if you want. And
  send me skins which you'll make to me, please. I'll be publishing them on
  http://bulba.at.kz/ site.

- Micro Speccy is controls by left mouse button clicking on main window active
  zones: header, buttons, labels and volume bar and by special keys
  combinations. If you want to move window, click on header and move mouse to
  desired position. To scroll long label text line click on it and move mouse
  to the right or left. To change volume, simply click on volume bar in desired
  point. You can also move mouse up or down before unclicking volume bar.

- Key combinations:

	F1			About program
	CTRL+P			Parameters box
	ALT+F4			Close Micro Speccy
	Z or numpad 4		Play previous tune
	X or numpad 5		Play current tune
	C or numpad 6		Play next tune
	V			Pause/Unpause playing
	B			Stop playing
	L or numpad 0		Load AY or AYM file
	Cursor up or
	numpad 8		Increase volume
	Cursor down or
	numpad 2		Decrease volume
	

- AY-file format (thanks to Patrik Rak for help).

  Originally this format was supporting on Amiga's DeliTracker (DeliAY plug-in).
  Therefore, all word data is in Motorola order (from hi to lo). Also, all
  pointers are signed and relative (from current position in file to pointed
  data). So, AY-file is sequences of records. First record is header. Here you
  are:

  TAYFileHeader=packed record
   FileID,			//'ZXAY'
   TypeID:longword;		//'EMUL'
   FileVersion,			//Version of song file (release version)
   PlayerVersion:byte;		//Required player version. Micro Speccy
				//works as player of version 3.
				//Now available values:
				//0       Use zero, if you do not
				//        know what player version
				//        you need
				//All other player versions and short
				//description of these players next:
				//1       initial player version
				//2       first 256 bytes is
				//        filled with 0xC9 (ret),
				//        not just last init byte
				//3       PC rewrite, different
				//        Z80 init routine, full
				//        Z80 emulation, supports
				//        48k tunes.
   PSpecialPlayer,		//It's for tunes which contained "custom
				//player" in m68k assembly. As Patrik Rak
				//is saying, exists only one AY-file of this
				//kind. So, can be simply ignored.
   PAuthor,PMisc:smallint;	//Relative pointers to the
				//Author and Misc NTStrings
   NumOfSongs,FirstSong:byte;	//Number of songs and first song values, both
				//are decreased by 1
   PSongsStructure:smallint;	//Relative pointer to song structure
  end;

  Next is song structure (repeated NumOfSongs + 1 times):

  TSongStructure=packed record
   PSongName,PSongData:smallint;//Relative pointers to NTStr song
				//name and song data
   end;

  All described above is rightly for any AY-file. Following data only for
  TypeID = 'EMUL'. Next is song data:
 
  TSongData=packed record
   AChan,BChan,
   CChan,Noise:byte;		//These are actually four bytes which specify
				//which Amiga channels will play which AY
				//channel (A,B,C and Noise, respectively). The
				//legal value is any permutation of 0,1,2,3.
				//The most common is 0,1,2,3. Not used in
				//Micro Speccy, of course
   SongLength:word;		//Song duration in 1/50 of second. If ZERO then
				//length is unknown (infinitely). Not used in
				//Micro Speccy
   FadeLength:word;		//Duration of volume fade after end of song in
				//1/50 of second. Not used in Micro Speccy
   HiReg,LoReg:byte;		//HiReg and LoReg for all common registers:
				//AF,AF',HL,HL',DE,DE',BC,BC',IX and IY
   PPoints,			//Relative pointer to points data
   PAddresses:smallint;		//Relative pointer to blocks data
  end;

  Next is points data:

  TPoints = packed record
   Stack,Init,Inter:word;	//Values for SP, INIT and INTERRUPT addresses
  end;

  Next is blocks data (words, offsets are signed):

      Address1			//Address of 1st block in Z80 memory
      Length1			//Length of 1st block
      Offset1			//Relative offset in AY-file to this block
      Address2                  //and for 2nd block
      Length2
      Offset2
      ...
      AddressN			//and for Nth (last) block
      LengthN
      OffsetN
      ENDWORD                   //ZERO word (end of blocks data)
				//so block can't have ZERO
				//address

  Notes from Patrik Rak:
  The word values should be always aligned at 2 byte offsets. Otherwise the
  DeliAY will crash (it's the limitation of the m68000).

  In case Address+Length > 65536, DeliAY decreases the size to make it
  == 65536.

  From me:
  In case CurrPositionInAYFile+Offset+Length > AYFileSize, MicroSpeccy
  and AYPlay decreases the size to make it == AYFileSize. I must to say,
  that if it is then this is broken AY-file. But there are many that ones
  in the world.

- How player of version 3 must play one of songs of AY File

    a) Fill #0000-#00FF range with #C9 value
    b) Fill #0100-#3FFF range with #FF value
    c) Fill #4000-#FFFF range with #00 value
    d) Place to #0038 address #FB value
    e) if INIT equal to ZERO then place to first CALL instruction address of
       first AY file block instead of INIT (see next f) and g) steps)
    f) if INTERRUPT equal to ZERO then place at ZERO address next player:

		DI
		CALL    INIT
	LOOP:	IM      2
		EI
		HALT
		JR      LOOP

    g) if INTERRUPT not equal to ZERO then place at ZERO address next player:

		DI
		CALL    INIT
	LOOP:	IM      1
		EI
		HALT
		CALL INTERRUPT
		JR      LOOP

    h) Load all blocks for this song
    i) Load all common lower registers with LoReg value (including AF
       register)
    j) Load all common higher registers with HiReg value
    k) Load into I register 3 (this player version)
    l) load to SP stack value from points data of this song
    m) Load to PC ZERO value
    n) Disable Z80 interrupts and set IM0 mode
    o) Emulate resetting of AY chip
    p) Start Z80 emulation

  As you can see, blocks of AY files can to rewrite standard player routine
  with own one. So, if you can not adapt some of tunes to standard player,
  you can write own player and place it at INIT address or even at 0x0001
  address (block of AY-file can be loaded at any address except 0x0000).
    
Links:
- Micro Speccy supporting site
  http://bulba.at.kz/
- Micro Speccy author
  Sergey Bulba, vorobey@mail.khstu.ru
- Micro Speccy designer
  Graham Goring, grahamg@zedtwo.com
- .AY files and AYmake V0.11 by James McKay (24/05/2000)
  http://www.void.jump.org/projectay
- .AYM files
  http://sorry.vse.cz/dimension/rdos/rdosplay
- Amstrad CPC .AY files (1.3 Mb archive)
  http://cracktros.planet-d.net/cpc/emulcpc.zip
- Project AY site developer
  bcass, bcass01@hotmail.com

Thanks to:
- Ivan Yuskin. Thank you for that you convinced me to start working under
  Micro Speccy. Also, thanks for testing and bugs founding.
- Milan Matousek. Thanks for some ideas in improvement of Micro Speccy and for
  sending to me new AY-files. Also big thanks for sending to me your AY-files
  collection. Your AY-files in Micro Speccy package and your testing of beta
  versions was helping me to do more perfect AY-files player.
- Patrik Rak. Thanks for info about AY-file format and AY-files playing.
  Also thanks for AY-files and DeliAY idea.
- Graham Goring. Thank you for designing Micro Speccy. Very nice job!
- James McKay. Thanks for docs in AYMake and AYPlay packages. Also thanks for
  the AYMake utility. I am sorry for my mistakes in information about AYMake
  utility in previous readme.txt of Micro Speccy.
- Andrey Gayvoronsky. Thanks for the info about existing AYM files and its
  player (RDOSPLAY). Also thanks for sending to me some AYM files.
- Hacker KAY. Thanks for help with AY and YM emulation. I used emulation of
  AY Emulator.
- Mr. Kirill. Thanks for debugger in Z80 Stealth Speccy emulator. I found a
  lot of bugs in Z80 emulation of Micro Speccy with helpful of your debugger.
- bcass. Thanks for Project AY site and two icons for Micro Speccy. I
  hope, you'll restore all lower quality AY-files on your site in near future.
- Stefano PUCINO. Thank you for report about bug in CPC-mode noise emulation.
  I fix it already.

Q1:
- What is CPC frequency model and why it is not supported?
A1:
- Frequency model for playing AY files is totality of next parameters:
  1) Z80 processor clock frequency
  2) Number of T-States between interrupts
  3) INT signal length in T-States
  4) AY chip clock frequency
  I have no information about these parameters at Amstrad CPC (except AY). From
  Patrik Rak I know that 1) and 2) parameters are not fixed on CPC.
Q2:
- Are you plan to support all Z80 and AY/YM based platforms?
A2:
- Yes, of course. But I need your help: any documentation, description,
  drawings and so on of Amstrad CPC, MSX and other. Send all to my e-mail.
  I need info even about Atari ST and MC68000 (I am planing to do Micro ST for
  playing SNDH files).
Q3:
- I have (made) several AY files, which does not exist in Micro Speccy package
  and on Project AY site. Can I erase it from my disk?
A3:
- Yes, of course. But send they all to me before, please.
Q4:
- I like Speccy music and want to rip some tunes from games into AY files, but
  I don't know well this stupid Z80 assembler. What shall I do?
A4:
- You can ask me or bcass to rip it. But in any way, do not do this by
  yourself: there are a lot of bad ripped AY-files on the world and without
  yours ones.
Q5:
- I know Z80 assembler and ZX Spectrum very well. How can I make own rips of
  AY tunes?
A5:
- Best way is to read AY files format and playing description and make it
  manually. Strongly recommended calculate duration of tune and fill field
  SongLength with non-ZERO value. And please, do not place to information
  fields strings such as "Ripped by Vasya Pupkin/Hackers Group/2001". This kind
  of information is not interesting for all other peoples, trust me.
  Second way is to use AYMake utility from Project AY site, but this utility
  has limitation to number of blocks (only 4 blocks maximum). Most now existing
  AY-files was produced by AYMake utility. Now you can also use my AY-files
  utilities: AYMakeR for making AY-files and aysplitr for splitting AY-files
  for remaking with AYMakeR. Download both from http://bulba.at.kz/.
Q6:
- What about next version of Micro Speccy?
A6:
- I think this is first and last version. Bugs removing and player improvement
  I shall be doing in AY files supporting part of my AY Emulator.
Q7:
- Micro Speccy is totally bad program: it's slow, low quality Z80, AY and
  beeper emulation, big executable file size. Give me Micro Speccy sources and
  I'll make it better.
A7:
- Hmm, seems, you are good programmer, write own code (why to copy my bugs and
  errors?). You can download Z80 emulation of Micro Speccy sources. What about
  size, you can decrease it by any EXE-packer very well.

Appendix:
OPERWOLF.AYM - this is one of modules are sent to me by Andrey Gayvoronsky.
        Use it for testing CPC AY ports emulation.
All other AY-files in this package are sent to me by Milan Matousek.

Ŀ
              RIP              
          MICRO SPECCY         
   An AY and AYM files player  
September 2000 - September 2001

