Online manual

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 forum 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

OPTIONS
    --help | -h
     Prints a brief help message and exits.

    --man
     Displays the manual page and exits.

    <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, unk, 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.


Previous page: Features
Next page: Description of a8cas chunks