Online manual

a8cas-util.pl manpage

NAME

a8cas-util.pl - the utility for manipulating 8-bit Atari tape images.

DESCRIPTION

a8cas-util.pl can do conversion from/to audio/cas/hex/bin. More conversion capabilities and various operations on Atari 8-bit tape images in extended CAS format (A8CAS) will be addedd in the (near) future.

LICENSE

Copyright (C) 2009-2013 by FUJI

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Nick 'FUJI' was registered at atari.area (http://atariarea.krap.pl/) in 2009. You can contact FUJI through the forums or by writting to fuji at arus dot net dot pl.

Requirements

If You want to use a8cas-util to convert from/to audio files, the following software must be installed in Your system: Ecasound (http://www.eca.cx/ecasound/) (LADSPA) SWH plugins (http://plugin.org.uk/) (LADSPA) Blop plugins (http://blop.sourceforge.net/index.html) (LADSPA) CMT plugins (http://www.ladspa.org/cmt/) (LADSPA) Omins plugins (http://www.nongnu.org/om-synth/omins.html#plugins)

Additionally Ecasound uses mpg321 to decode mp3 files

Otherwise plain perl 5.8 or newer should be sufficient.

SYNOPSIS

a8cas-util.pl [global options] <command> [command options] <input_file>[:option[=value][:option[=value] ...]] [input_file[:option[=value][:option[=value] ...]] ...] <output_file>

Global options:

--help | -h - brief help

--man - full documentation

--syscheck - check for required system components

OPTIONS

--help | -h

Prints a brief help message and exits.

--man

Displays the manual page and exits.

--syscheck

Checks whether required helper programs and LADSPA plugins are installed before any operation is started.

<command>

Required. Specifies the desired action. Valid commands (for now) are: conv, squarify, info.

Commands:

conv

Converts data provided in <input_file> to another format.

squarify

This command is for standard tapes only. It allows converting FSK signal to square wave, which shows zeros and ones as low and high states instead of mark/space frequencies. It is usefull for debugging and recovery purposes. Also, You can compare audio file produced by "squarify" command with the one created from cas/hex with the use of "--squarify" option. Such comparision allows precise adjustments (in HEX file) of IRG and baud rates, which in turn helps to match all timings between CAS file and left audio track from original tape.

info

Prints informations about cas/hex file.

input_file

Name of input file to process. This is required. Input format is determined by file extension: anything other than cas,hex,com,xex,bas and bin is treated as an audio file. When multiple input files are specified, they all are "merged" together and stored in one output file. Each input file can have it's own set of processing options (without leading dashes). All options specified below can be used. Options have to be delimited by ":" (colon). If an option takes a value, the "=" must be placed between the option name and it's value. Example:

a8cas-util.pl conv a.wav:resistor=0.01 b.wav:turbo=turbo2000 output.cas

output_file

Name of output file. Required. The default output format is cas. Otherwise output format is determined by given file extension (cas,hex,bin,wav). The script tries to NEVER overwrite existing files by adding numeric suffixes to file's base name if <output_file> already exists.

conv options

--title | -t <Title>

Provides the main name (description) of tape image.

--skipshorter <bytes>

Use it if You want to skip obviously wrong, short data records, don't store them in .cas file. Standard tapes only.

--maxgap <miliseconds>

Specifies the minimum length of IRG (silence) which separates tape "files" from each other. This option is relevant when converting to binary format. The default is 5000 (5 seconds).

--autoadjust

Automatically adjust speed changes (when tape is old and damaged). For tapes in turbo format, but only for recovery purposes (can cause unpredictable, unwanted results, will be very rarely needed).

--mark <frequency>

The frequency of "mark" signal in Hz. 5327 by default. For FSK encoded tapes.

--space <frequency>

The frequency of "space" signal in Hz. 3995 by default. For FSK encoded tapes.

--bandwidth <frequency>

Bandwidth of the bandpass filter. Specifying value lower than default (1000) can help sometimes. For FSK encoded tapes.

--resistor <value>

This is the most usefull command line option for standard format (FSK encoded) tapes. It corresponds to resistor connected to output of comparator in real hardware, causing the output value to shift towards logical "1". The default value (0.05) will work most of the time for good quality tape dumps. You may need to adjust this, if a8cas-util.pl reports checksum errors. Values may range from 0.001 to 0.2, sometimes small negative values may be needed for recovery purposes.

--allfsk

For standard (FSK) format only. All FSK signals, which don't belong to data blocks, will be stored in CAS/HEX file. Usually You don't want it, use only for recovery purposes. By default only significant FSK signals (like long space signals, which are elements of tape protection) are stored in output file.

--minfsk

For standard (FSK) format only. For recovery purposes mostly, sometimes helps with certain types of protected tapes. Tries to convert to bytes as many signals as possible instead of saving them in 'fsk ' chunks.

--minsignals

For standard (FSK) format only. Minimal number of signals used to detect a width of a bit. Should always be >=4. The default value is 20, Should be changed only for very unusual recordings (protections) or for recovery purposes.

--maxbauddiff <difference>

For standard (FSK) format only. Maximum difference of baud rate between start of data record and any part of it. If bigger change of baud rate is detected, a new data block is started.

--squarify

Standard (FSK encoded) tapes only. It can be used to produce audio files, in which "mark" and "space" tones are represented by low and high levels of signal instead of different frequencies; this is mostly for debugging purposes, see also description of command "squarify".

--turbo|-t <format>

Required for turbo formats. Specifies a kind of turbo format of sound file (input or output). Valid formats are: blizzard, turbo2000, ast, att, um, turborom, mkturbo, cs2000, csst, cstt, csbtape, autoturbo, tapewiz, lowsil2000, generic.

--noise <level>

Optional, turbo only. Specifies noise cut-off level. Default is 0. Removes unwanted noise. Can remove weak signal too, so use with care.

--amplify <level>

Optional, turbo only. How mutch to amplify the sound before processing. This is quite important option, can greatly improve the results, but also can break things. The default is 1 (no amplification).

--mindiff <difference>

Optional. For turbo formats only. Specifies minimum difference in signal level which triggers the edge detection. Values may vary from 1 to 65535 (16-bit samples are used for turbo formats). When this option is used, dynamic adjustments to signal amplitude are turned off. Use it when automatic procedures fail.

--invert

Optional, turbo only. Allows to choose which signal edge (raising or falling) starts the impulse. The default is to use the hard coded setting, depending on the tape format.

--lowpass

Optional, turbo only. Resonant lowpass filter can be used to selectively amplify amplitude of weak impulses without clipping of the rest of the signal. Turned off by default. Experimental.

--highpass

Optional, turbo only. Highpass filter is used to filter out low frequency components of signal, which means centering it towards level zero. Turned off by default. The filter sometimes may reverse the phase of the signal, use --invert to compensate.

--lqresample

Optional, turbo only. Makes ecasound to use low quality resampling algorithm. Sometimes it gives better results than default one.

--hqresample

Optional, turbo only. Makes ecasound to use highest quality resampling algorithm. Sometimes it gives better results than default one.

--shape <square|sine|sawtooth>

Optional, turbo only. Allows to choose the shape of the wave during conversion cas/hex -> audio. The default is square.

--left|-l <filename>

Only for cas/hex/audio -> audio conversion. Allows to mix data track and audio track into one stereo file. <filename> is a name of file containing left audio track.

--mono

Only for cas/hex/audio -> audio conversion. Make monophonic audio file.

--cksum <checksum type>

Allows to change default checksum type for non-standard recordings (for example protections in Turbo 2000). Valid types are: sum255carry, modulo256 and xor.

--autofuji

Automatically adds FUJI blocks between parts of tape. Part detection is currently based only on length of gap between subsequent data blocks (determined by --maxgap).

--starttime|--st <seconds>

Sets the position (in seconds) in audio file, where the processing should start. Usefull for processing only parts of audio files (recovery, tape images containing different formats).

--endtime|--et <seconds>

Sets the position (in seconds) in audio file, where the processing should stop. Usefull for processing only parts of audio files (recovery, tape images containing different formats).

--pilot <miliseconds>

Sets the length (in miliseconds) of pilot signal. Applicable only to conversion from binary files (bin/xex/com/bas) to cas/hex/wav and only to standard (fsk) format. If not defined, the pilot length is set to 20 seconds.

info options

--detail |-d

Optional. Prints detailed report about all blocks found in cas.

squarify options

All options valid for "conv" command, applicable to audio->cas/hex conversion can be used, though some of them will be ignored. Use of the following options makes sense: --resistor, --mark, --space, --bandwidth.

---