Documentation - Turbo Tape Loader V1.3, Copyright 1999 by Sami Silaste

VERSION HISTORY

New Features / Bug Fixes From Version V1.2:

Automatic mode where no user input is required has been implemented.
Stereo and 16 bit WAV support have been added.
Waveform inversion added as some tape decks or sound cards inverse waveforms.
Decoding from left, right or combined stereo channels added. This is useful if the recording is not 
perfectly balanced.
Automatic recovery of checksum errors.
Re-organised source-code (now actually almost legible).
Better structured log files and improved screen output layout.
Graphics support and sound throughput removed, as these did not add much value.
Still much improved speed from V1.2 as all input is now buffered.

New Features / Bug Fixes From Version V1.1:

Now supports long Windows95/98 filenames (but not NT!)
Output (error messages) can be recorded to a log file
Improved speed (about 400% faster than V1.1)
Source code included

New Features / Bug Fixes From Version V1.0

1) The one major improvement is the fact that the original checksum calculation method used by Turbo 
Tape has been implemented. This means that ?LOAD ERROR(s) can be determined reliably (or as 
reliably as in the original C64 Turbo Tape).
2) Sound throughput has been implemented. This makes it possible to 'listen to' the sampled recording 
whilst loading is in process (toggle sound throughput on/off by pressing 'S').
3) Automatic threshold level calculation has been disabled. After many hours of testing (well.. almost 
one hour) it was seen that by way the best threshold setting (nearly always) is zero. Turbo Tape Loader 
now uses 0 by default and does not try to automatically determine the best value. The user can still set a 
different value using the command line parameter -Tn.

WHAT DOES IT DO?
Turbo Tape Loader uses a sound card to read in Commodore 64 Turbo Tape format files from a 
cassette. These are files which were saved on the tape using such programs as "Turbo Tape" or "Copy 
190" or "Turbo 232 (by Mr. Z)" where programs were saved using the <-S (left arrow S) command. 
Turbo Tape Loader analyses a sound file (e.g. WAV or VOC) of the original recording and saves all 
recorded files within it on your PC's hard drive. You can then import these binary files into your 
favourite Commodore 64 emulator. CCS 2.0 (or beta) can use these .PRG files directly. If you are using 
another emulator you have to put these files into a suitable .D64 or .T64 file (Star Commander - 
available from http://sta.c64.org/scnews.html, for example, will do this).

WHAT DOES IT NOT DO?
Turbo Tape Loader is only capable of handling files in the Turbo Tape format. It cannot load any 
programs recorded using other formats e.g. such as those used with many game fast-loaders (Novaload 
etc.). It also cannot load programs saved using the normal Commodore 64 SAVE command or 
programs saved with other, Turbo Tape incompatible fast-loaders. Turbo Tape Loader does not digitise 
or create the sound files for you, you need to have a separate program for recording (e.g. Sound 
Recorder or other utility that comes with your Windows or sound card).

RECORDING

Required Format
The preferred format is an 8 bit mono PCM encoded WAV sound file with 44100 samples per second, 
but you can record your sample either in 8 bit or 16 bit PCM (WAV) format.  You can also record 
either in stereo or in mono as Turbo Tape Loader can process both formats. Please note, however, that 
processing 8 bit mono recordings is approximately four times faster than processing 16 bit stereo 
recordings.

If you are not using a WAV format sound file, then make sure you use 8 bit mono PCM format. In this 
case Turbo Tape Loader will ignore all sound file header information and treat the file as raw sample 
data.

Sample Rate
For Turbo Tape Loader to successfully extract files from a sound file it needs to be recorded with a 
high enough sampling rate. The minimum rate recommended is above 22,000 samples per second 
although the safest choice is 44,100 samples/sec. If your sound card allows a higher rate (some modern 
cards offer at least a rate of 48,000 samples per second) you can use it for increased accuracy. 

At a sampling rate of 44,100 the 0-bit (low bit) is represented by approximately by 9 samples and the 1-
bit (high bit) by 14 samples. However, there is always some variation (by as many as 2 or 3 samples). If 
these variations, which are often caused by stretched tapes or poor quality cassette decks, grow too 
large then Turbo Tape Loader will not be able to reliably distinguish between 0 and 1 bits and thus 
extracted files are prone to contain errors. With an increased sampling rate (>44,100) the likelihood of 
reliable bit distinction increases as the average bit lengths grow.

If you are in a hurry and are a proud owner of a double-speed cassette deck (for hi speed cassette -> 
cassette copying) then you can try recording at double speed using > 44,100 sampling rate. I have used 
this method successfully and it is quite handy as it halves the recording time. However your tape needs 
to be in a fairly good condition for this to work.

Volume
For Turbo Tape Loader to reliably extract files you will need to use a suitable volume (or gain) in the 
recording. You should make a few test recordings before sampling your favourite tape to a 5-giga file - 
as you need to establish a suitable recording volume level. Use the graphical display of your recording 
software to make an estimate of the loudest and quietest values in your recording.

What is too loud?
The minimum sample volume values should be below a value of 40% and the maximum volume values 
below 90%. Otherwise the peak volume values will be truncated as they go off the scale. This just 
means that you should not use too loud a recording volume - if the sample goes off the scale on the 
graphical display, it is too loud.

What is too quiet?
The minimum sample volume values should not fall below a value of 12.5% and the maximum volume 
values should not fall below 50%. Otherwise the peak and minimum volume values might become 
swamped by noise.

What is good?
Try to use as much volume as possible without truncating the peak values. Please take into account that 
the volume of the original recording can change by several percentages at different time points. So 
leave a bit of a safety margin so that the peak volume does not go off the scale even if the recording is 
somewhat louder at a later point. Turbo Tape Loader will give you a warning and a recommendation of 
action if the sample volume is either too quiet or too loud - You should take these warnings seriously as 
the there will be a marked degradation in reliability if the sample volume is not suitable.

COMMAND LINE PARAMETERS
Turbo Tape Loader is an MS-DOS program and thus it has not got a 'nice' graphical user interface. You 
need to go to the DOS prompt when using this program from Windows 95 / 98. If you are using 
Windows 3.x, just exit to DOS. When in DOS prompt, change into the directory where 
TAPELOAD.EXE is located and type TAPELOAD followed by the sound file name. If the sound file is 
not saved in the same directory as Turbo Tape Loader then you will need to prefix the filename with the 
path to it. 

To make usage easy, make sure that TAPELOAD.EXE is saved in the current directory or is found on 
the path - also save your sound file in the same directory. All the files that will be extracted will also be 
saved in the same (current) directory.

The syntax is as follows:

TAPELOAD [-Tn] [-C[l,r,b]] [-I] [-A] [-S:Save as name] [-L:Log file name] [-95] 
INPUTSOUNDFILE.WAV
 
Where SOUNDFILE is the name of the sample file you have used in recording. You need to type the 
filename in full, including the extension (e.g. .WAV). Under Win95/98 you can use longer than 8+3 
character filenames - i.e. you do not need to use the abbreviated "soundf~1.wav" form - Turbo Tape 
Loader understands long filenames in all parameters.

-Tn allows you to set a threshold value (n). The threshold value is the value by which the volume level 
has to change before Turbo Tape Loader decides whether a peak maximum or peak minimum volume 
level has been reached. Normally Turbo Tape Loader uses a value of 0 and you need not to worry about 
setting it. This option has been made available because some sound cards are somewhat imprecise in 
sampling. For example, if the volume level of the original recording is, say, steadily increasing over the 
time, for example from 100 to 120 over 10 samples (at a rate of two volume units per sample) with 
some (read cheap) sound cards the actual sampled values can 'snake' a bit up and down. This might 
sometimes make Turbo Tape Loader think that a peak maximum or peak minimum volume has been 
reached, which leads it into thinking that the current bit has ended. If you get messages like 'dodgy bit, 
decided...' , 'too long bit sequence' or  'too short bit sequence' then you might want to consider using  a 
higher threshold value than 0 (default). Maximum value for the threshold is 16 - although in practice 
values above 5 are unlikely to work reliably. However you should also examine if the possible cause of 
problems is either a too low or a too high recording volume (see the discussion above). For example, if 
you want to set a threshold value of 2, enter it as -T2 where two follows immediately after T. Example: 
TAPELOAD pacman.wav -T2. Please note there is no semicolon between T and 2.

-C allows you to choose which stereo channel to use for decoding. For example -Cr uses the right 
channel only and -Cl uses the left channel only. The default is -Cb i.e. both channels averaged out. This 
is quite a useful thing as often old tapes are a bit wobbly and stereo channels can wander up and down a 
bit. If you get lots of errors when decoding a certain tape then try decoding using either the left or right 
channel only. This option has no effect if your recording is in mono.

-I option inverses the waveform. This option was added because some sound cards or tape decks give 
an ascending wave when it really should be descending and vice versa. If you get nothing extracted and 
Turbo Tape Loader is complaining about incorrect bit lengths then this option is worth trying.

-A option automates all interactions. This means that no confirmation is asked for anything and any 
output files are overwritten by default. This option also copies all detailed information normally written 
only to log file onto screen as well.

Use -S:SAVE AS NAME to tell Turbo Tape Loader what MS-DOS filename you want to use for the 
file to be extracted. By default Turbo Tape Loader uses the original C64 file names on the tape, 
truncated to eight characters if needed. The default extension is .PRG. Please note that if more than one 
file is found in the recording, this option will be ignored for all the files extracted following the first 
one. If you give a filename that is longer than 8 characters, Turbo Tape Loader will assume you are 
running Win95/98, even if you did not specify the -95 option (however, subsequent files are truncated 
to 8 characters unless -95 is specified). Example: TAPELOAD pacman.wav -S:pacman.prg.

-95 lets you use filenames that are longer than 8+3 characters. For this to work, you need to be running 
Turbo Tape Loader under Win95/98. Trying to use this option under Windows NT, MS-DOS (or 
Windows 3.1) will prevent any files from being created (i.e. it will not work!). Example: TAPELOAD 
pacman.wav -95.

-L:logfile lets you specify a file where all the on-screen messages are shown and lots of other extra 
information is written. This lets you view the error messages when the whole sampled record has been 
processed - useful if you are using a slower computer as you do not need to hang around to see what is 
going on. If you are using Win95/98 (but not NT!) you can use log names longer than 8+3 characters. 
Example: TAPELOAD pacman.wav -L:pacmantape.log.

Parameters, including the sound file name, can be given in any order. Some examples:

Extract all files from sound file TAPE1.WAV under Win95/98 and write all events to a logfile 
TAPE1LOG.TXT:

	TAPELOAD TAPE1.WAV -95 -L:TAPE1LOG.TXT

Extract all files from sound file TAPE2.WAV under Win95/98 and rename the first extracted file to 
Apple_Cider_Spider.prg:

	TAPELOAD TAPE2.WAV -95 -S:Apple_Cider_Spider.prg

Extract all files from sound file TAPE3.WAV inverting waveform, and using automatic mode:

	TAPELOAD TAPE3.WAV -A -I

Extract all files from sound file TAPE4.WAV using threshold value 1, use left stereo channel only, use 
Win95/98 long filenames and write log to TAPE4.LOG:

	TAPELOAD TAPE4.WAV -T1 -Cl -95 -L:TAPE4.LOG


Or...

Use TAPELOAD -INFO to see information about the copyright and the disclaimer.

OPTIONS AND MESSAGES WHEN PROCESSING


Stopping
You can stop the processing any time by pressing Q or ESC - all files extracted prior to this point will 
be left intact.

File Names
Filenames - Turbo Tape Loader will show you the original C64 file name and use it as the basis for the 
MS-DOS (or Windows) name. The MS-DOS name will be truncated to eight characters (unless -95 
option is specified) and all C64 special characters will be filtered out. You can provide your own MS-
DOS filename for the first file to be extracted by using the -S:save as name parameter of the command 
(see syntax). Turbo Tape Loader will not overwrite any files without confirmation if a duplicate file 
name is found (unless in automatic mode). If you answer N to "Overwrite (y/n/s/q)/?", you will be 
prompted for an alternative filename. If Turbo Tape Loader finds a file that was saved without a name 
(quite possible!) you will also be prompted for a new filename (except in automatic mode where a file 
name 'NO_NAME', followed by the file number is used as name). Answering S will skip the current file 
and answering Q will quit Turbo Tape Loader.

The Extraction Process
Extraction will start by an assessment of the sound file where several variables (e.g. average bit lengths) 
will be determined. This can take some time on a slow computer. If this seems to take a very long time 
then you are likely to have long periods of silence in your sample - the remedy is to listen to the sample 
with some suitable player and cut out silent bits or record the sample again. 

The next thing Turbo Tape Loader does is finding out the tape file header, this has been done when a 
message showing file name and length is shown. After this Turbo Tape Loader will seek for the actual 
beginning of the program. When a message saying 'Saving PACMAN.PRG' is shown, the extraction of 
the file (Pacman) is ongoing. When the extraction is complete, Turbo Tape Loader will return to 
seeking the header of the next file and extract it. All files in the recording will be extracted until the end 
of the sound file is reached. If you know that the last file has been extracted, you can stop the extraction 
process by pressing Q. Any files that Turbo Tape Loader fails to extract without errors or files that are 
incomplete (e.g. recording runs out before the extracted file ends) are saved 'as they are'. Beware of 
using these on your emulator as they might crash unexpectedly.

If you encounter too many errors (see below) during the extraction, you will be prompted to skip the 
file (except in automatic mode). Skipping the file will abandon that extraction and Turbo Tape Loader 
will start seeking for the next file immediately.

If the checksum for the file fails then Turbo Tape Loader will attempt to recover the file by figuring out 
which bits might have been interpreted incorrectly. This will only attempted if there is a reasonable 
change of recovering the file. There are two levels of recovery, an 'easy' level where only one bit is 
attempted to be corrected - any files recovered with this methods are likely to be OK. The 'hard' 
recovery option will only be attempted if the easy recovery fails. This method is far slower and will 
often produce 'false positives' where a correct checksum is achieved even though the file remains 
corrupt. This is because the C64 Turbo Tape format uses only 8 bits in the checksum.  So there is 
always one chance in 256 of getting a 'false positive' and hard recovery may attempt thousands of 
different recovery configurations. You can press S or Q during the recovery to skip the file or quit.

ERRORS AND OTHER MESSAGES

Loading was unsuccessful. Error: Unexpected end of sound file
Description: The Sound file ended before program(s) in it could be extracted.
Solution: Resample sound file making sure you catch all of the intended files. A Turbo Tape file starts 
with a high pitched signal lasting for a few seconds followed by a short burst of noise (the file header). 
After this another high pitched signal follows, after which you hear a long stretch of noise (actual 
program data). When this ends with a characteristic 'pop' noise (when STOP was hit after recording on 
the cassette unit) you know that the end of recording is reached.

Loading was unsuccessful. Error: User interrupt
Description: The user got bored and stopped the process.
Solution: Try not to fall asleep on the keyboard?

Loading was unsuccessful. Error: Could not create MS-DOS file
Description: There was an error during MS-DOS file creation.
Solution: This can be caused if you are running out of space on your hard drive or if you enter illegal 
characters in the MS-DOS filename prompt (such as *, ? or space) or enter a filename that is already in 
use when prompted for one. This error will also be shown if you try to use the -95 option under MS-
DOS, Windows 3.1 or Windows NT.

Warnings / Errors written into the log only:

WARNING: Dodgy bit, decided 1 on volume <File position/Program position/Bit number> 
Description: There was a problem deciding whether the bit was 0 or 1. This is usually decided on the 
basis of the length of the bit, but sometimes the length of a 0 bit is too close to the length of a 1 bit and 
Turbo Tape Loader cannot make a reliable decision based on length only. It will then look into the peak 
volume of the bit and if it is above average (as it is usually for 1 bits) the bit is deemed to be 1 bit. What 
this means is that you probably should use a slightly higher sampling rate. Also it can mean that the tape 
in question has been stretched or chewed in use or that your audio cassette deck has less than reliable 
tape speed control. This problem can also be caused by unreliable analogue to digital conversion by 
your sound card, see the discussion about volume above. 'File position' in the message gives you the 
location in the sound file (in bytes) where the problem was encountered and 'Program position' and 'Bit 
number' refer correspondingly to the affected byte and bit in the file currently being extracted.

If the checksum at the end of loading is OK then you probably do not have any problem at all.
 
Solution: Resample with adjusted volume and/or higher sampling rate. Try another cassette deck. Get a 
new sound card.

WARNING: Dodgy bit, decided 0 on volume <File position/Program position/Bit number>
Description: There was a problem deciding whether the bit was 0 or 1 and it was decided that it was 0 
after all. See above.
Solution: See above.

ERROR: Too long bit sequence, size: <Size> <File position/Program position/Bit number>
Description: Turbo Tape Loader could not determine the end of bit before the maximum length of any 
bit was exceeded.
Solution: This can be caused by either too low or too high recording volume - resample with adjusted 
volume. 'File Position' in the message gives you the location in the sound file (in bytes) where the 
problem was encountered, 'Program position' and 'Bit number' specify the affected byte and bit in the 
current program being extracted and 'Size' is the length of the bit. This error is more likely to occur if 
you are using high threshold values.

ERROR: Too short bit sequence, size: <Size> <File position/Program position/Bit number>
Description: Turbo Tape Loader thought that the bit ended before it can possibly end.
Solution: This is possibly more serious than the too long bit seq. warning. The extracted file will almost 
certainly contain errors. Resample with adjusted volume, you should probably try a higher recording 
volume first. Also a higher sampling rate can help. However, if the checksum is OK then you might just 
be fine.

More solutions: If you are a true hacker then you can note down the affected Program Position and Bit 
number and figure out what the correct byte value is in a machine code monitor. Alternatively you can 
note down the affected sound file position and edit the 0 or 1 bit peaks in your favourite WAV (or 
other) editor (for example CoolEdit). Please note that to get the true sample position you have to deduct 
the length of a WAV header (normally 52 bytes) from the given file position.

Pacman: Loading ready - Checksum OK.
Description: Turbo Tape Loader completed extracting a file (Pacman) successfully.
Solution: Everything went OK and you can use the extracted file in your favourite emulator (after 
importing it to a suitable .T64 (tape) or .D64 (disk) image file - unless you are running CCS64 2.0 
where it can be used as it is). 

Pacman: Load error: Checksum failed
Description: Turbo Tape Loader completed extracting a file (Pacman) unsuccessfully. If there were no 
major errors, recovery is attempted (see above). If recovery is successful, the file might be OK.
Solution: If recovery was successful and file runs OK on emulator then probably everything is OK. 
Otherwise try with different -T (threshold) parameters and if the sampled recording is in stereo then try 
extracting from the left and right channels separately (-Cl or -Cr options).


KNOWN PROBLEMS

Sample Rate
It is more reliable to differentiate between 0 and 1-bits when the recording has been done with 44,100 
samples per second, although you can use other sample rates as well (e.g. 22,000). This is due to the 
fact that the original CN-2 cassette unit is a 'sort of' digital device when your sound card is essentially 
an analog to digital converter and it only offers an approximation of the original signal. So, if you get 
loads of error messages, you should try sampling the tape again and maybe tweak a little with the 
recording volume. If problems persist, try another tape deck or sound card and if possible a slightly 
higher sampling rate than 44,100. Also avoid using the 'microphone-in line' in your sound card and use 
the 'line-in' instead. Also check that only the input line is active (i.e. that if you are sampling through 
line-in check that microphone-in is muted) as unused but active input lines might cause 'hissing'.

COPYRIGHT
This Software is copyright by Sami Silaste 1999. You may use and distribute it freely as long as you 
distribute all the files attached (including the source code). You may use the source code in you own 
developments - if you do so, a note to me prior to publication would be appreciated.

DISCLAIMER
This software is provided on an 'as is basis' and whilst running it the user accepts full responsibility.  
The author accepts no responsibility for any damage, either direct or consequential, to the user's 
equipment, person, family or pets. 

PROBLEMS? COMMENTS? SUGGESTIONS?
If you like this program, please send a postcard to: Sami Silaste, Clifford House, 152 Redland Road, 
Redland,  BRISTOL, BS6 6YD, UNITED KINGDOM or email your comments or suggestions to: 
samis@aethos.co.uk or sami@semaphore.demon.co.uk.
