Provided by: xtrs_4.9c-3.5ubuntu1_amd64 bug

Name

       cassette - data cassette image manipulator for xtrs TRS-80 emulator

Syntax

       cassette

Description

       To  control  the  emulated  cassette  used  by  xtrs, a file called ".cassette.ctl" in the
       current directory keeps track of what file is currently "loaded" as the cassette tape  and
       the  current  position  within  that  file.  The  cassette  shell script provides a way to
       manipulate this file; typing "help" at its prompt shows its commands.  You  may  use  this
       script  to  load  and  position cassette tape files. The operation works very much like an
       actual tape recorder.

       This manual page also describes the image formats that the  emulator  supports  and  their
       limitations.

Commands

       pos generates a status message including the filename being used as the cassette image and
       the current position within the image, in bytes.

       load [filename] changes the cassette image currently being used to the file specified, and
       resets the position counter to zero.

       type  typename  tells the emulator what type of image is loaded.  Usually this is detected
       from the file extension, but you can override the detected value with this  command.   The
       supported types are listed in the next section.

       rew  [position] changes the position counter to the position specified.  If no position is
       given, the counter is reset to zero.

       ff [position] changes the position counter to the position specified.  If no  position  is
       given, the counter is set to the end of the file.

       quit exits the cassette shell script.

Types

       xtrs  supports  several  different  types  of  cassette  images,  each of which represents
       cassette data in a different format.

       cas format is fairly compact and is compatible  with  other  TRS-80  emulators  that  have
       cassette  support.   This  format represents the bit stream that (the emulator thinks) the
       TRS-80 cassette routines were trying to save  to  the  tape,  not  the  actual  electrical
       signals on the tape.

       On  writing,  the  emulator monitors the values that the TRS-80 software is sending to the
       cassette port and their timing, auto-recognizes whether a 250-bps,  500-bps,  or  1500-bps
       format is being written, decodes the signals into a string of 0 and 1 bits, packs the bits
       into bytes, and writes them to the  cas  file.   On  reading,  the  emulator  auto-detects
       whether  software  is  trying to read at 250, 500, or 1500 bps and encodes the 0's and 1's
       back into the signals that the TRS-80 software is  expecting.   This  somewhat  roundabout
       method  should  work  with  most  TRS-80  cassette  routines  that  read and write signals
       compatible with the ROM cassette routines, but it may fail with custom routines  that  are
       too different.

       Note  that  generally  nothing  useful  will happen if you try to write a cas image at one
       speed and read it at another.  There are  differences  in  the  actual  bit  streams  that
       standard  TRS-80  software  records  at  each  of  the  three  different  speeds, not just
       differences in encoding the electrical signals on the tape.  Thus an incoming  bit  stream
       that  was  originally  recorded at one speed will not be understood when read back in at a
       different speed.  For example, Level 2 Basic programs are tokenized, while Level  1  Basic
       programs are not, and the two Basic implementations record different binary information at
       the start of the program and between lines.  Also, when a  file  is  saved  at  1500  bps,
       standard TRS-80 software puts an extra 0 bit after every 8 data bits, and these extra bits
       are packed into the cas file along with the data bits.

       cpt format (for "cassette pulse train") encodes the exact values and timing of the signals
       that  the  TRS-80 cassette routine sends to the cassette output port to be recorded on the
       tape.  Timing is to the nearest microsecond.  This format emulates a  perfect,  noise-free
       cassette,  so  any cassette routines that even halfway worked on real hardware should work
       with it.

       wav format is a standard sound file format.  The wav format is intermediate  in  emulation
       accuracy between cas and cpt.  It does represent actual signals, not decoded bits, but its
       timing precision is limited by the sample rate used.  The default rate for new  wav  files
       is 44,100 Hz; you can change this with the -samplerate command line option to xtrs.

       You  can  play  wav  files written by xtrs through your sound card and hear roughly what a
       real TRS-80 cassette sounds like.  A real TRS-80 should be able to read wav files  written
       by  xtrs if you copy them to a cassette or connect the TRS-80 directly to the sound card's
       output.  This feature has not been tested extensively, but it does seem to work, at  least
       for short programs.

       xtrs  can  also  read  wav  files.   It can read back the wav files that it writes without
       error.  Reading wav files sampled from real cassettes is more  difficult  because  of  the
       noise  introduced,  but  in  brief  testing  it  does seem to work.  The signal processing
       algorithms used are very crude, and better ones could probably do a better job of  reading
       old,  noisy  cassettes, but I don't have any such cassettes to test with (and I don't know
       much about signal processing!).  Help in this area would be welcome.

       The wav file parsing code has several limitations.  Samples must be 8-bit  mono,  and  the
       wav file must contain only one data chunk and no extra optional RIFF chunks in the header.
       If you have a wav file whose header xtrs rejects, try using sox(1) to convert it to a more
       vanilla format.

       direct  format is similar to wav format, except that the samples go to (or come from) your
       sound card directly, not a wav  file.   Direct  format  requires  the  Open  Sound  System
       /dev/dsp  device.   Extending  the code to work with other sound interfaces would probably
       not be hard, but is left as an exercise for the reader.  Please send me the changes if you
       do this.

       debug  format  is the same as cpt format except that the data is written in human-readable
       ASCII.  The cassette output is assumed to be 0 initially.  Each line of output gives a new
       value  (0,  1, or 2), and the amount of time (in microseconds) to wait before changing the
       output to this value.

Authors

       xtrs 1.0 was written by David Gingold and Alec Wolman.  The current  version  was  revised
       and  much extended by Timothy Mann (see http://tim-mann.org/).  An initial version of this
       man page, and the translation from C-shell (cassette) to Bourne shell  (cassette.sh),  are
       due to Branden Robinson.

                                                                                      cassette(1)