Epple-II/doc/cassette.asciidoc

=== Cassette Tape Interface

The Apple ][ and Apple ][ plus machines had the ability to save and load binary
data to and from cassette tape. The user would attach a standard cassette tape
recorder to the jacks on the back of the Apple ][, and use the monitor +R+ and +W+
commands, or the Applesoft BASIC commands +LOAD+ and +SAVE+, to read and write data
on the cassette tape. The user would have to press the play and/or record buttons
on the player at the right time.

The Epple ][ emulates the cassette interface, using a file to hold the
recorded portion of the tape. The file will grow in length as necessary
to hold data that the emulated Apple is writing to the ``tape.''
The emulator will not overwrite existing data on a tape image.
The emulator will automatically ``press'' the play or record buttons that
would have been necessary when using the original machine.

==== Commands

+cassette new <file-path>+

This creates a new empty file (on the host computer) that represents a cassette tape image.
The file must not already exist.

+cassette load <file-path>+

This loads an existing file (from the host computer) containing a cassette tape image.
The tape is automatically positioned at its beginning (fully rewound).

+cassette unload+

This removes the file from the cassette tape. Note that you must manually save
the file using the +cassette save+ command (described below).

[WARNING]
Unloading an unsaved file will lose any changes made to the file, without warning.

+cassette rewind+

This command ``rewinds'' the cassette tape, positioning it at the beginning
of the tape (for subsequent reading). You do not need to rewind the tape
before saving or unloading it, of course.

+cassette save+

This command saves the changed tape to the file. Note that the display will show
an asterisk +*+ next to the file name if there are unsaved changes that need to
be saved. Unsaved changes will be lost without warning if the file is unloaded
or if you quit the program.

==== Example of Saving to Tape

Start up the emulator with Applesoft ROMs for this tutorial.
Enter a simple Applesoft program, just as an example, that we
are going to save to a cassette tape image file.

[source,vbs]
------------------------
]NEW

]10 PRINT "HELLO"

]20 END

]LIST

10  PRINT "HELLO"
20  END 

]RUN
HELLO

]
------------------------

We first need to load a tape image file into the cassette machine.
Enter command mode by pressing +F5+, then make a new tape
image file.

------------------------
command: cassette new hello.tap
------------------------

This will create a new, empty tape file image named +hello.tap+
in the current default directory. (We could have specified a full path
name for the file if we wanted to place it in a different directory.)
Notice that the emulator now displays the name of the tape image file,
along with the position and length of the tape image, which is now +0/0+.

Next, we tell Applesoft to save the program to the cassette. For this,
we just use the +SAVE+ command. Note that this is not the
DOS +SAVE+ command; the DOS command has a file name after
+SAVE+. We just use +SAVE+ with no file name.

------------------------
]SAVE

]
------------------------

It will take 10 seconds or so for it to save. Notice that the
current position of the tape is counting up as the Apple saves
the program. When it is finished, you need to save the changes
to the file. Press +F5+ and enter the emulator command to save
the tape image file.

------------------------
command: cassette save
------------------------

We can now unload the file from the emulator (which is like ejecting
the tape from the cassette player).

------------------------
command: cassette unload
------------------------

==== Example of Loading from Tape

To load the saved program (from the previous section) into the Apple again,
we will need to first load the tape image file back into the cassette machine.
Press +F5+ to enter command mode and load the image file.

------------------------
command: cassette load hello.tap
------------------------

This will load hello.tap (in the current default directory). Notice the
emulator now displays the name of the tape image file, along with the
position and length of the tape image, which in this case is +0/33481+.

Next, we tell Applesoft to load the program from the cassette. For this,
we just use the +LOAD+ command. Note that this is not the
DOS +LOAD+ command; the DOS command has a file name after
+LOAD+. We just use +LOAD+ with no file name.

------------------------
]LOAD

]
------------------------

It will take 10 seconds or so for it to load. Notice that the
current position of the tape is counting up as the Apple loads
the program. When it is finished, the program will be loaded.

[source,vbs]
------------------------
]LIST

10  PRINT "HELLO"
20  END

]RUN
HELLO

]
------------------------

==== Tape Image File Format

The format of the tape image file is unique to the Epple ][
It is stored in a low-level format that represents the waveform that the Apple writes
to the cassette tape.

The file is a binary format. Each byte in the file represents the length of one half of one cycle
(of voltage level variation) written to the tape. The length is in 10-microsecond units.

For example, a tape image file might have the following binary bytes (in decimal):
+65  65  65  65  65  20  25  50  50  25  25  25  25  50  50+
Since each byte represents a 10-microsecond unit, these bytes represent the following
half-cycle lengths in microseconds:
+650 650 650 650 650 200 250 500 500 250 250 250 250 500 500+
The meaning of these half-cycle lengths to the Apple is as follows:

------------------------
|-------HEADER------|--sync-|-1-bit-|-0-bit-|-0-bit-|-1-bit-|
|                   |       |       |       |       |       |
|650 650 650 650 650|200 250|500 500|250 250|250 250|500 500|
------------------------

where +HEADER+ is a header section the Apple writes (to skip any
unrecordable leader section on a real cassette tape); +sync+ is a
synchronization cycle; and the subsequent cycles are the actual
bits of data saved on the tape. A 500-microsecond cycle (which
is stored in the file as two 250 microsecond half-cycles)
represents a *zero* bit, and a 1-millisecond cycle (which is
stored in the file as two 500 microsecond half-cycles)
represents a *one* bit.