TapeTool is a command line utility for processing recordings of Microbee tape files with the main objective of recovering lost data.
TapeTool is not an automatic data recovery/repair tool - rather it should be considered a toolkit of useful utilities for data extraction, repair and re-rendering of working audio tape recordings.
Successful use on a damaged recording will generally involve much experimentation.
TapeTool can:
- Read an 8 or 16 bit mono PCM wave file and convert it to text that can be redirected to a text file.
- Depending on the quality and damage to the recording, tapetool can output: - audio sample values - cycle lengths in samples (a cycle is a full 360deg audio wave) - cycle kinds (1200Hz or 2400Hz) - bits - bytes - CRC checked and decode data blocks
- The output text file can be re-read by tape tool - no need to edit the original wave file
- The output text includes detailed information about where in the original recording the each piece of data came from. ie: actual sample numbers. This can be used to inspect the exact location in the audio file in a wave editor to visually determine the data.
- The output text can be generated one byte per line without position information - this allows two or mode recordings of the same file to be compared and merged using a text diff tool.
- Synthesize a new audio recording in 300 or 1200 baud.
- Generate a binary dump of the data ie: .bee and .tap files.
- Repair an original wave recording by copying good sections over bad.
- Works with Microbee and TRS80
Source code:
Windows executable:
Usage:
> tapetool [COMMAND] [ARGS]
In order to process or render cassette audio files, tapetool needs to know the type of machine the tape is intended for. Currently TRS-80 and Microbee are supported, see the command line arguments below.
The text output of tapetool follows a simple format:
- Anything in [square brackets] is a comment. Tapetool generates these to show position information error details, resync data, header information etc...
- A double slash to end of line is also considered a comment
- On reading a text file, all comments are ignored except a square bracket comment [format:] which is used to store the file type of the original file dumped from. (tap, cas, etc...)
- Dumped sample and cycle length data can't be re-read by tape tool.
- Cycle kind data is rendered using the following characters:
S
= a short cycle (2400Hz)L
= a long cycle (1200Hz)?
= an ambiguous cycle (somewhere between 1200 and 2400Hz)<
= a too short cycle (shorter than 2400Hz)>
= a too long cycle (longer than 1200Hz)
- Bit data is rendered as
0
and1
- Byte data is rendered as
0xHH
where HH is the hex value of the byte. - An input text file can contained mixed cyclekind, bit and byte data.
The first command line argument specifies the type of command to execute:
Dumps various statistics about wave data including amplitude ranges, estimated long and short cycle lengths etc...
Renders a new wave file from an input wave file, applying the --smooth, --dcoffset and --amplify manipulations
This can be used to apply multiple smoothing passes for example.
Joins two wave files together - they must have the same sample rate and bit depth.
Deletes a section of a wave file.
Dumps the raw samples of a wave file (can't be used with text input data). If from
is specified
dumps sample starting at that sample number. Use --samplecount to specify how many samples to dump.
The output of this processing kind can't be re-read by tapetool
Dumps the length (in samples) of each cycle in a wave file.
The output of this processing kind can't be re-read by tapetool
Dumps an input file as cycle kinds - short, long, ambiguous etc...
Dumps an input file as a series of 1
and 0
bits.
Dumps the raw bytes of an input file, without checking headers, blocks, checksums
Dumps the input file as a series of data blocks and computes and checks the checksum byte of each block. A full dump from the command wihtout errors indicates a successful load.
The available command line arguments depend on the selected command. For more information on availability
of an option on a command use tapetool COMMAND --help
Specifies the target machine type as "TRS80". Only 500 baud system, basic and source files are supported.
Specifies the target machine type as "Microbee". Only 300 baud input is supported, but 300 and 1200 baud rendering is supported.
Set the format of the input data ("cas", "tap", etc...)
Smooths the input sample data using a moving average of period N, or 3 if N is not specified.
Using this option can:
- eliminate erroneous zero crossings caused by noise
- even out cycle lengths
By default, tapetool analyzes audio files to automatically determine settings for how to best process it. Use this option to prevent this auto analysis and use default settings for the machine type.
Normally an out of range cycle kind <
or >
causes processing of bit data to fail. Use this option
to allow out of range cycle lengths. TapeTool effective ignores these cycles and relies on the surrounding
cycles to determine the bit.
Apply an offset to all samples. Use with pulse based audio (eg:TRS80) to shift the pulses into the zero crossing range. Also useful for shifting noisy silence/hiss out of the zero crossing range.
Amplify the input audio signal by the specified percentage. eg: --amplify:50
will halve the volume of the
input signal.
Note however that amplification rarely has any effect on the ability to decode digital data from a recording.
Explicitly set the short cycle frequency in Hz. (Default for Microbee is 2400Hz, TRS80 is 1024Hz)
Set the cycle detection mode. By default tapetool uses a rising zero crossing to detect cycle boundaries. For badly distorted signals however, sometimes a different approach can work more effectively. The available modes are:
* `zc+` = zero crossing upwards
* `zc-` = zero crossing downwards
* `max` = local maximum
* `min` = local minimum
* `max+` = local maximum with positive sample value
* `max-` = local minimum with negative sample value
Note that the local maximum/minimum options will nearly always require heavy, possibly multiple pass smoothing to work effectively. Use the --filter command to apply multiple smoothing passes.
Available on some commands to specify the sample number in the input wave file to start at.
Available on some commands to specify the sample number in the input wave file to stop at.
Available on some commands to specify the number of samples to process.
TapeTool uses various heuristice to synchronize itself on bit and byte boundaries. Use this option to output the data consumed in performing these synchronization operations.
Synchronization occurs at the start of the file and after any error.
This option causes data elements (cyclekinds/bits/bytes) to output N per line.
Use this option to get detailed sample position information, or combine --perline:1 with --noposinfo to generate data suitable for comparison with a diff program
By default tapetool outputs comments indicating the current position in the input file. This extra information however makes it impossible to compare to files using a text diff tool. --noposinfo suppresses this information.
When output raw sample data, inserts a new line at each detected zero crossing, making it easier to inspect audio wave form data.
Adds N seconds of leading silence to the rendered wave file. The default is 2 seconds if not specified.
Adds N leading zeros to the rendered wave file. By default, no additional leading zeros are written to the file.
Sets the sample rate of the rendered wave file. The default is 24000Hz (because it provides and even division for 1200 and 2400Hz cycles).
Sets the sample size of the rendered wave file. ie: 8 or 16bit PCM data.
Set the volume of the rendered wave file (as a percentage). The default is 10%.
Sets the baud rate of the rendered wave file. This option only works when processing in --blocks mode and will automatically set the appropriate speed byte in the DGOS header.
Renders the wave as a sine waves instead of square waves.
Use with bits
or bytes
commands to generate a bit resolution profile of the data in a wave file. The resulting
profile can then be used to render a repaired version of the original wave file.
Use with bits
or bytes
or cyclekinds
commands to generate a cycle resolution profile of the data in a wave file. The resulting
profile can then be used to render a repaired version of the original wave file.
Render the output wave file using wavefile
as the source for audio waveform data. Tapetool will
look for the longest matching sequences of bits to build a new, restored audio file. The wave file
must have been previously profiled with either --createbitprofile or --createcycleprofile
Used with the join
command to insert a silent gap between the two joined wave file.
Declare that a speed change occurs at sample N.
eg: 1200 baud Microbee files start at 300 baud before switching to 1200 baud. If processing at bit, byte resolutions tapetool doesn't have the required information to determine where the speed change occurs.
Use this option, combined with --speedchangespeed to explicitly declare where the change occurs.
Only a single speed change is supported.
Use with --speedchangepos to declare the baud rate at the change of speed.
Don't include the lead-in noise in a profiled rendering. By default, tapetool will include leading noise before the actual data in a profiled rendering. Use thi option to omit this leading silence/noise.
Don't include the trailing lead-out noise in a profiled rendering.
Generate errors and resync if cycle kinds don't match exactly the type required for a particular bit.
Use with profiled renderings to resample cycles and bit patterns onto the exact timing boundaries required.
Dump the blocks from a clean working wave file:
> tapetool blocks --microbee myfile.wav
Dump the raw bytes from a wave file to a text file
> tapetool bytes --microbee myfile.wav myfile.bytes.txt
Dump the bits from a wave file, smoothing the audio data over 3 samples and using heuristics to calculate cycle lengths by analying the wave data rather than relying on the sample rate:
> tapetool bits --microbee --smooth:3 --analyze myfile.wav myfile.bits.txt
Convert the output of the previous example into a series of bytes:
> tapetool bytes --microbee myfile.bits.txt myfile.bytes.txt
Convert a byte stream into blocks and check the checksums, dump header info etc...
> tapetool blocks --microbee myfile.bytes.txt
Render a wave file:
> tapetool blocks --microbee myfile.bytes.txt myfile.wave
Create a ubee512 .tap file directly from a wave file:
> tapetool blocks --microbee myfile.wav myfile.tap
Create a NanoWasp .mac file from text file: (take note of the header info and enter it into NanoWasp web page where you configure the tape file).
> tapetool blocks --microbee myfile.bits.txt myfile.mac
Create an arbitrary format binary file from a text file of bits:
> tapetool bytes --microbee myfile.bits.txt myfile.bin
Join two wave files:
> tapetool join file1.wav file2.wav joined.wav
Extract a part of a file, and apply an 8 sample smoothing:
> tapetool filter file.wav --startsample:10000 --endsample:20000 --smooth:8 output.wav
Render a new wave file using the sample data from an original recording, assuming game.tap is a tap file with the recovered/repaired data and game.wav is the original damaged recording.
This is very experimental and mileage will vary depending on many factors.
> tapetool bytes --microbee game.wav --createbitprofile
> tapetool blocks --microbee game.tap game.repaired.wav --useprofile:game.wav
If a bit resolution profiled rendering doesn't work, you can try cycle resolution with timing correction:
> tapetool bytes --microbee game.wav --createcycleprofile
> tapetool blocks --microbee game.tap game.repaired.wav --useprofile:game.wav --fixtiming