Home About this site Sales Trade Wanted Search Links Contact me

Java ZX81 Tape Converter Overview

The Java ZX81 Tape Converter allows you to to convert sampled sounds to ZX81 .P and .TZX files, and vice-versa. It requires Java 1.4 to run.

Latest Update 04/09/2007 to to fix a synchronization issue, and added preferences for the maximum number of allowed errors and warnings.

Here are a couple of screenshots. The first is with the converter running against a single file:

The second illustrates the program running with two samples, where the first difference between them has been located. You can also see where a "0" has been manually added to the second sample where there was a drop-out:

The ZX81 Tape Converter is package as a .JAR file: Click here for the .jar file.

If you have any comments/requests/suggestions, please send a note to Simon Holdsworth


GUI operation

The Converter can be run by executing the .JAR file. This can be done in Windows by double-clicking on the .JAR icon (assuming you have the correct association for .JAR files with javaw.exe).

It can also be run from the command line using:

javaw -jar tapeutils.jar

The help for the program can be found here, as well as within the program itself.

I'd recommend setting the maximum memory usage for the Java program because the default is usually quite low. Also if you hit OutOfMemory errors, then this is something that needs increasing. Assuming you have 1G RAM or more, you can use:

javaw -Xmx750M -jar tapeutils.jar

Command line operation

It is also possible to run the program fully from the command line. Here are the command line arguments:

java -jar tapeutils.jar 
      {-sampleFile |-s} fileName     The name of the sample file (.WAV, .AIFF, etc.)
     [{-sample2File|-2} fileName]    The name of the second sample file (.WAV, .AIFF, etc.)
     [{-pFile      |-p} fileName]    The name of the .P file.
     [{-gui        |-g}]             Display GUI.
     [{-invert     |-i}]             Invert sample.
     [{-noise      |-n} noiseLevel]  Noise threshold.
     [{-minGap     |-m} minGap]      Minimum gap between groups.
     [{-maxGap     |-x} maxGap]      Maximum gap between groups.
     [{-channel    |-h} channel]     Channel number.
     [{-data       |-d} numBytes]    Data only.  Don't interpret as a BASIC program.
     [{-forceWrite |-w}]             Force write of result after errors.        
     [{-begin      |-b} index]       Index within sample to start processing.
     [{-multiFile  |-f} fileNames]   Comma-separated file names for multiple within the sample.
     [{-configFile |-c} configFile]  Name of a properties file with convert parameters.

An example:

java -jar tapeutils.jar -s "3D Monster Maze.wav" -p 3dMonsterMaze.p 

Some tips on using the program

Here's a more detailed explanation of the parameters:
Argument Description
-sampleFile
-s
The file name for the first sample to process.
This sample file can be in any of the formats supported by Java runtime, i.e. .wav and .aiff at least.
The sample can contain multiple ZX81 programs.
Best results are obtained with the volume normalised to be fairly low, muted between the ZX81 programs.
-sample2File
-2
The name of a second sample to process.
This is useful in cases where you have two samples of the same file, but with dropouts in different places. It allows you to see the signals side-by-side and identify bytes that differ between the two.
-pFile
-p
The name of the .P file to be produced, in the case of a single ZX81 program.
If this is specified only the first ZX81 program is processed in the sample.
-gui
-g
If present, displays the graphical represention of the file(s) and analysis after generating the .P files.
-invert
-i
If present, inverts the signal.
This can be useful in some cases where the signal rises at the beginning of a bit sequence rather than dropping.
-noise
-n
Sets the noise threshold.
Any signal that is less than this threshold is ignored.
Default value is 5.
-minGap
-m
The minimum gap (in samples) that must exist between bits.
This can be modified if the tape is slower or faster than normal, or if there is a lot of noise between bits.
Default value is 48.
-maxGap
-x
The maximum gap (in samples) that can exist between bits.
Again useful if the tape is slower or faster than normal.
Default value is 76.
-channel
-h
The number of the channel in the sample to analyse.
Default is 0
-data
-d
Indicates that the ZX81 program is data only, and should not be treated as a normal SAVEd program.
For normal programs, the first bytes are the system variables which can be used to determine the number of bytes to load.
For data blocks, these are not present and so this option gives the number of bytes to analyze.
-forceWrite
-w
Forces writing of the .P file (as much as has been processed) when errors occur in analysis.
-begin
-b
The sample number to begin analysis at.
Can be used to skip noise at the start of the sample.
-multiFile
-f
A comma-separated list of names for .P files to produce when there is more than one ZX81 program in the sample (.P is added to the names).
By default it is assumed that there are multiple programs and the .P files are called p0.p, p1.p, etc.
-configFile
-c
A Java properties file that contains the above settings for a number of .WAV files.
The entries appropriate to the file name given with -sampleFile are used (minus the extension) when analyzing the sample. For example, the file might contain:
Biorhythms.B.noise=19
Biorhythms.B.invert=true
Forth.3.EditorScreen1.numDataBytes=1028
MCoder.minGap=38
Pimania.begin=55700
Games1.A.Multi.fileNames=Orbit,Sniper,Meteors

.P List/Play/Save

This standalone utility allows the contents of a .P file to be listed, played as a sample through the computer speakers, or saved as a sampled sound for later playing.

At the moment this utility can only be run from the command line. It takes the following arguments:

java -classpath tapeutils.jar tapeutils.zx81.PFileUtils
      {-pFile     |-p}  fileName    The name of the .P file.
     [{-sysVars   |-s}]             Output system variables.
     [{-vars      |-v}]             Output program variables.
     [{-display   |-d}]             Output display file.   
     [ -play          ]             Play the file rather than listing it.
     [{-sampleFile|-f}] fileName    The name of the file to write the sample to.
     [{-zx81Name  |-z}] name        The name of the ZX81 file (not needed for list).

If -play is specified, the file is played, rather than being listed; if a sample file name is provided, then the file is saved to the sample file only - the -play option is ignored in that case. Note that you can also play .P and .TZX files from the ZX81 Tape Converter, and save the resulting sample file for later playback too.

An example:

java -classpath tapeutils.jar tapeutils.zx81.PFileUtils -p "3DMonsterMaze.p -play -z "3D MONSTER MAZE"

Note that the ZX81 file name must contain only valid ZX81 characters (so no lower case...).


It's also possible to implement your own classes to analyze sound samples of different types, through the interfaces in the tapeutils package, with ZX81 specific implementations in the tapeutils.impl.zx81 package, although at the moment the conversion utility always uses the ZX81 versions.

Click here for (a .zip of) the javadoc
Home About this site Sales Trade Wanted Search Links Contact me