CSW - Compressed Square Wave
Version 1.30 (July 13th 1999)
This document describes the CSW.EXE utility and the new file format created
by us. CSW is strongly based upon the MakeTZX engine and it shares with it various aspects of its behaviour. In the manual of MakeTZX you will find lots of explanations, tips and FAQ that are not reported here, so we recommend you to read it too.
WHAT IS CSW ?
CSW files are a way of storing sample data in a compact form, typically
taking 1/10th of an ordinary VOC. It is used internally by MakeTZX, but
it is also very useful to keep down the disk space taken by your VOC/WAV
files. The CSW utility can handle CSW conversion in both ways (see below).
Of course, MakeTZX itself accepts CSW files for input.
When converting to the CSW format, the sample file is processed through
MakeTZX's internal digital filter which reduces noise and signal distortions
very efficiently. Make a backup copy of the original file if you will need
the original samples later, but remeber that in most cases the CSW will
be a lot better than the original file.
Note that CSWs are intended for use with square waves only (such as
computer tapes)!
The compression ratio depends on many factors; in general, the higher
the sample rate, the higher the ratio. A clean and regular signal helps
too. The ratio for a 44 KHz file will usually be twice the value for a
22 KHz one. The typical gain for a 44 KHz turbo tape is about 93%, which
means a 12:1 compression factor! Normal speed tapes should compress even
better.
Finally, CSW files are highly compressable with the standard PC archivers
such as RAR and ZIP. The packed CSW files are usually smaller than the
zipped original VOCs. You will be able to RAR a 40 MB sample file down
to a few hundreds KB.
CSW.EXE
This small program is intended to provide a basic support for CSW files.
It can compress VOC, WAV, IFF and OUT files to CSW and decompress CSW files back
to VOC format (switch -d). Enter CSW -? or simply CSW for help. At the
moment, CSW.EXE accepts only uncompressed mono 8-bit sample files. Extensions
in filenames can be omitted; in this case, the default extensions will
be appended in turn to match an existing file. The search order is VOC, WAV, IFF and OUT for last. If the output filename is left out, the input file
name with extension .CSW (or .VOC if decompressing) will be used. If the
input filename ends with the extension .CSW, then the switch -d (decompression)
is implicitly assumed.
CSW can also work in DirectMode (switch -r), in which case the input
is taken from your soundcard and conversion is performed on-the-fly in true realtime.
You can stop the conversion by pressing any key at any time. To pause the
recording press 'P', followed by any key to resume. During the pause, the vu-meter is shown again.
Note that, due to MakeTZX's
engine requirements, the samples are written to disk anyway, so the maximum
recording time is limited by the available disk space. If you want, you can keep this samples at the end of conversion and save them in a WAV file (switch -k), just in case something goes wrong and you don't want to repeat the sample. In this way, CSW may also act like a sampler!
You can set the
sampling frequency with switch -s (e.g. -s44100). You can also do programmed
recordings using switch -t and specifying the recording time (in seconds,
e.g. -t60.0 for one minute); in this case, CSW will automatically stop
when the time has elapsed (or when the disk is full), so you can start
it and go away to do better things :)
The DirectMode SoundBlaster driver has been written for 100% compatible soundcards. If you are experiencing problems, try option "-c" which will attempt to access the hardware in a different way. The driver also performs a preliminary stability check; if this fails, CSW exits after two seconds with an error message. All this stuff is extensively covered in MakeTZX's manual, DirectMode section; please read it carefully.
Note: In order to run the CSW utility under plain MS-DOS you
need a DPMI host (such as CWSDPMI.EXE)
Note: DirectMode, OUT files, digital filter and the other features are extensively described into MakeTZX's manual. Please read it.
Note: Although it is possible to specify fractions of seconds,
the effective recording time is subject to DMA buffer size quantums (a
few 1/10ths of sec).
Note: Like MakeTZX, CSW supports long filenames under Windows 9x
THE CSW FILE FORMAT (v1.01)
Here is the CSW implementation chart for anyone who wants to use it in
some utility or emulator (if so, please let us know). The file format is
very simple and the compression scheme used is somewhat based on the RLE
algorithm.
Numbers are hexadecimal unless otherwise stated and words are stored
in Intel (little-endian) byte order.
Reserved fields must be set to 0 for compatibility with future versions.
| Offset |
Size |
Field |
| 0 |
16 |
"Compressed Square Wave" |
| 17 |
1 |
Major format revision (currently 0x01) |
| 18 |
1 |
Minor format revision (currently 0x01) |
| 19 |
2 |
Sampling rate (Hz) |
| 1B |
1 |
Compression type (at the moment only type 0x01 is supported) |
| 1C |
1 |
BIT 0 = Polarity. If set, the signal starts at high level (positive).
BIT 1-7 = Reserved (must be set to zero). |
| 1D |
3 |
Reserved (set to 0 for compatibility) |
| 20 |
??? |
Compressed data |
Compression types:
0x01: RLE (Run Length Encoding)
The data is stored as a sequence of pulse lengths (1 byte per pulse).
Example:
will be represented with the following data:
03 05 01 04 07
Durations greater than 0xFF are represented as 0x00 followed by the
duration represented on 4 bytes, so CDE9 is stored as 00 E9 CD 00 00.
In format revision 1.01 we have introduced a bit to represent the initial signal polarity, which is not important in the Spectrum world but it is for other platforms such as C64. All the Spectrum TZX converters can safely ignore this bit (like MakeTZX does), so any tool supporting CSW 1.00 will also work fine with CSW 1.01 without modifications.
Note that no info about the pulse amplitude is represented because
it is not necessary, since we are dealing with discrete 2-values amplitude
scales.
Credits and contact info.
CSW is a program by RAMSOFT ZX Spectum demogroup. It
can be freely distributed at the condition that the original archive and
its contents are not modified in any form without the written permission
of the authors. If you want to include CSW into any software collection
distributed on CDROM or any other electronic media, contact us first.
The latest versions
of CSW and related stuff (such as this document) are always available
at our official web site World
Wide Ramsoft
For any RAMSOFT documents,
please always check our site only. Mirrored archives may contain outdated
information and, unless explicitly stated as official mirrors, cannot hold
copies without our permission.
For comments/questions, write to:
Please check the contacts page of our site for the latest email addresses.
CSW, this manual and MakeTZX are © 1998-99 RAMSOFT, a ZX Spectrum demogroup.