/////////////////////////////////////////////////////////////////////
// TZX to VAV Converter v0.1                                       //
// (C) 2005 Francisco Javier Crespo <tzx2wav@ya.com>               //
//                                                                 //
// Based on these works:                                           //
// PLAYTZX v0.60b (C) 1997-2004 Tomaz Kac                          //
// PLAYTZX Unix v0.12b (C) 2003 Tero Turtiainen / Fredrick Meunier //
/////////////////////////////////////////////////////////////////////

  TZX2WAV is an utility based heavily on Tomaz Kac's PlayTZX 0.60b and it's
designed to create a WAV file instead of replaying through a SoundBlaster
card like its predecessor. When PlayTZX was conceived and designed, the
normal operating systems were MS-DOS and Windows 95, and CDROM burners were
a expensive luxury. Now things have changed drastically: Windows 2000 and XP
are the common environments, and a lot of people were demanding a way to 
store up to 99 tracks in one Audio-CD to use with their real Spectrum at the
higher fidelity. I felt the best way to do this was a tool to create standard
WAV files that could easily be used from any Windows program.

Requirements for the supplied compiled version of TZX2WAV:
- Win32 compatible environment (W95, W98, WMe, NT, W2K, WXP and maybe WinE)
- Enough storage (Hard Drive, Memory Sticks or whatever) for the output file

  This version of TZX2WAV is able to handle .TZX files of version 1.13. It is
still in its BETA stages since not all ZXTape blocks have yet been tested and
some are still not supported (like the Snapshot block).

  The WAV files generated by this version should work with all possible
programs and they have been tested (at least) with SPIN, RealSpectrum and
Spectaculator emulators.

  The CSW 2.0 files generated by this version use RLE compression and they
work well with RealSpectrum, but not with Spectaculator because it seems it's
expecting ZLIB compressed data associated with CSW 2.0 (still to be done).

  All DATA blocks (10-14) should work fine. The Direct Recording block should
work OK if you use the sampling rate that is the same, or a multiply of the
original sampling rate that was used to create the Direct Recording Block
(i.e. if direct recording block was created using 10kHz then use either 10,20
or 40kHz for playback/conversion). Also the Pause and Stop the tape command
work just fine and can be used.

  If you would like to see more information on the INFO blocks then use the
/info command switch which will show you ALL possible info on all the blocks.
Use /p command to pause after each page is displayed. Also a condensed form
of info can be displayed with one line per block (as in replay or conversion)
with the /one switch.

  By default the Groups are not displayed expanded... i.e. Only the Group Name
is shown and not what is in that group. If you would like to see what is in
the groups then use the /x switch. This is only relevant when displaying info
one line per block (or playing/converting the TZX tape) ... in /info mode ALL
blocks are always displayed.
  
  If you don't want to convert or see all blocks then you can specify the
starting and ending block with /b and /e switches.

  
Command Line Syntax: TZX2WAV [switches] FILE.TZX [FILE.WAV|CSW]

Switches: (you can just enter FIRST letter ... i.e. /freq = /f)

/b     n - Start conversion of the tape at block n. The first block has
           number 1. ALL blocks (including Info, group,...) are numbered.
/e     n - Stop conversion of the tape AFTER block n.
           i.e. if you use /b 3 /e 5  then blocks 3,4 and 5 will be played.
/csw     - This will create a .CSW file instead generating a .WAV mono file.
           It can be used only at certain emulators at the moment.
/freq n  - This will set the sampling frequency to n Hz. The default sampling
           frequency for WAV conversion is 44100 Hz, so it doesn't need to be
           resampled for CD Audio, but if you wish higher fidelity or even
           storage for DVD, you can generate 48000 Hz or any other rate.
/info    - This will show very extensive information about all the blocks
           within the TZX file. Some blocks have not yet been tested (such as
           Snapshot, Custom info, ...) but they *should* work OK anyway.
           The starting byte (in HEX form) of each block is written in the
           () brackets.
/one     - Show information ONE line for each block (the same as playing it to
           the soundblaster/VOC file, only without ANY output ...). Could also
           be interpreted as Brief Information. Will also show the starting
           byte of each block in the tape (right after the block number).
/p       - Will make a pause after each page of information is displayed. Use
           this in combination with /info or /one switches.
/x       - Will eXpand the Groups. By default the groups are displayed in
           collapsed mode (i.e. only the group name is displayed and not the
           blocks in it) ... when you use this switch ALL blocks will be
           displayed.
           NOTE: For /info ALL blocks are always displayed ! So this switch
                 is not needed when using /info !
/128     - This will use 128k mode. Only relevant if the TZX file has the
           'Stop the tape if in 48k mode' blocks. i.e. if this option is
           enabled then all these blocks are ignored.
/reverse - This will reverse the signal. If the tape doesn't work on the C64
           then try using this switch !

  If no output file is given, then the program will use the same filename as
the .TZX one and change the extension to .WAV or .CSW accordingly.

  The Amstrad CPC, SAM Coupe, Jupiter ACE, Enterprise & Commodore 64 files  are
identified with the 'Hardware Info' Block ...  The data is taken from the first
record in this block.  If this block is not present then the Filenames won't be
written  for  these  machines!  Only first 10 characters of the block names for
SAM Coupe will be shown!  The Jupiter  ACE tapes are ofcourse supported, but no
Filenames are shown because I have never even seen such file, if you have  some
then please send them to me, so I can add direct support for their filenames :(

  On  Commodore  64  tapes  only  the  Turbo Tape and ROM Loader blocks will be
displayed  with  the  filename.   Other   non-standard  loaders  will  just  be
represented by the length of the block !


HISTORY: - 0.1 (15th January 2005)
           First Public release based on PLAYTZX 0.60b

  Source code is provided with the official archive release, just in case you
would like to port this utility to some other computer or operating system.

  Do not hesitaste to contact me at the address on top of this document for
bug report or other kind of feedback. I'll be busy the next 6 weeks preparing
my Cisco CCNA certification exam, but I may release fixes as needed.

  If you are looking for TZX files then the best place is 'World of Spectrum',
which is mantained by Martijn v.d. Heide, the url is:

  http://www.worldofspectrum.org/

The latest revision of the ZXTape format and of all these utilities together
with others that use this format can be found at that page too (look in the
'Documents' section).
