/////////////////////////////////////////////////////////////////////
// TZX to VAV Converter v0.2 for Bloodshed Dev-C++ compiler        //
// (C) 2005-2006 Francisco Javier Crespo <tzx2wav@ya.com>          //
//                                                                 //
// Originally based on source code from these works:               //
// PLAYTZX v0.60b for Watcom C compiler (C) 1997-2004 Tomaz Kac    //
// PLAYTZX Unix v0.12b (C) 2003 Tero Turtiainen / Fredrick Meunier //
/////////////////////////////////////////////////////////////////////

  TZX2WAV is an utility mainly designed to generate audio WAV files from TZX 
data files used in 8-bit computers emulators. A lot of people were demanding a 
way to create Audio CD tracks that could be hooked with their real ZX Spectrum 
at the highest fidelity.

  TZX2WAV is based on Tomaz Kac's PlayTZX 0.60b, an original tool to replay 
TZX through an ISA SoundBlaster card. When PlayTZX was conceived and designed, 
the normal operating systems were MS-DOS and Windows 95, and CDROM burners 
were a expensive luxury. Now Windows 2000 and XP are the common environments, 
and I felt the best way to achieve our aim, was a tool to create standard WAV 
files that could be easily imported into any CD burning program.

These are the only requirements for the supplied executable 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 Revision 1.13 files. The next 
release will be compatible with TZX Revision 1.20 Draft, which will support 
some encoding methods not available in the current specification.

  Mono WAV files generated by this version should work with all emulators.
I have tested them with R80, EmuZWin, SPIN, RealSpectrum and Spectaculator.

  TZX2WAV 0.2b is able to create both CSW 1.01 (RLE compression) and CSW 2.00
(ZLIB compression) files so they should work in all CSW-aware emulators.

  All data blocks (10-14) should work fine. "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 was created using 11025 Hz, you may use 22050 or 44100 Hz). Also the 
"Pause" and "Stop the tape" commands work just fine and can be used.

  TZX2WAV can display information on internal TZX file structure, instead of
creating any output file, using "-i" switch. A verbosely extended information
is available using "-v" switch, for those interested in the inners of TZX.

  By default, the groups are not displayed expanded, i.e. only the group name
is shown and not what is inside that group. If you would like to expand the 
groups, then use the "-x" switch. This is only relevant when displaying info 
one line per block (or converting the TZX tape). In verbose mode, ALL blocks 
are always displayed.
  
  Some Amstrad CPC, SAM Coupe and Commodore 64 files are identified with 
specific "Hardware Info" block. Some internal header names in these platforms 
are able to be displayed if recognized. Non-standard loaders will just be 
represented by the length of the block and names won't be displayed on screen, 
but correct WAV/CSW files will be created.

  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.

  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]

-f 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.

-s    : This NEW switch will automatically generate STEREO WAV files that
        can be directly imported into any burning CD program without any
        further processing, or channel duplication.

-r    : This will reverse the signal of the whole wave data. If a C64 tape
        does not work on the C64, then try using this switch !

-c1   : This will create a .CSW file instead generating a .WAV mono file.
        CSW v1.01 was the first specification of these format. The highest
        frequency that can be used here is 65535 Hz (16-bit counter).

-c2   : This will create a .CSW file instead generating a .WAV mono file.
        CSW v2.00 offers far more compression than CSW v1.01 format.
        When converting extremely high-speed loading files, it's suggested to
        use 96000 Hz sampling frequency with CSW 2.00, as size won't increase.
                
-i    : This will show ONE line of information per block, just displaying the
        same output when in normal operation, but the WAV/CWS files will NOT
        be created. The starting byte (in hexadecimal format) of each block
        is written after the block number.

-v    : This will show very extensive information about all the blocks within
        the TZX file. Some blocks have not yet been tested (such as Snapshot,
        or Custom Info) but they *should* work OK anyway. The starting byte
        of each block is also written in the () brackets.

-x    : Will expand the tape groups. By default the groups are displayed in
        collapsed mode (i.e. only the group name is displayed and not the
        blocks in it) but with this switch ALL blocks will be displayed.

-b n  : Start conversion of the tape at block n. The first block got the
        number 1. ALL blocks (including Info, group,...) are numbered.

-e n  : Stop conversion of the tape AFTER block n. Block n will be played.
        (i.e. if you use -b 3 -e 5  then blocks 3, 4 and 5 will be played)
        
-p    : This NEW switch changes its meaning. Now when used, the pause value of
        the last block in TZX file is overridden and set to zero, in order to
        deal with some malformed TZX files. Anyway, TZX2WAV will *always* add
        200 milliseconds of silence at the end of the wave file.

-128  : This will activate 128K mode. Only relevant if the TZX file has any
        "Stop the tape if in 48K mode" special block. If enabled, this
        switch will ignore all these blocks. Otherwise 5 seconds of silence.
        will be generated in the wave file.

-----------------------------------------------------------------------------

* TZX2WAV 0.2 Beta (25th February 2006)
  - Stereo WAV files can be created for direct import into CD burning tools.
  - CSW 2.0 ZLIB comppresed files can be generated with "-c2" switch.
  - We can override the pause information of the last block with "p" switch.
  - The program C source has been optimized and severely reorganized.

* TZX2WAV 0.1 Beta (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.
The zlib library source MUST be downloaded separately from http://www.zlib.net

  Do not hesitate to contact me at the address on top of this document for
bug report or other kind of feedback.

  The latest revision of TZX2WAV, the TZX format docs and other TZX utilities
amongst other TZX game files, should be available at "World of Spectrum" web,
which is mantained by Martijn van der Heide:

  http://www.worldofspectrum.org/

-----------------------------------------------------------------------------

Francisco Javier "Black Hole" Crespo
Madrid @ Spain - 2006
