anchor:cassette_tape[]

=== Cassette Tape Interface

The Apple ][ and Apple ][ plus machines have 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 commands
+R+ and +W+, or the 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 Apple ][ has two cassette ports, CASSETTE IN and CASSETTE OUT. To save a program to
tape, the user would attach a cassette recorder to the CASSETTE OUT port, load a blank
cassette into the recorder, press RECORD (and PLAY), then on the Apple type SAVE. When
finished, the user would press STOP, and eject the tape.

To load a previously saved program
from tape, the user would attach the player to the CASSETTE IN port, then load and REWIND
the tape. The user would PLAY the tape until the header tone could be heard, then STOP.
On the Apple ][ the user would type LOAD and immediately press PLAY on the cassette player.
After the file loaded, the user would STOP and eject the tape.

The Epple ][ emulates the cassette interface, using a standard WAVE (PCM) file to
hold the recorded portion of the tape. It provides two ports, one for CASSETTE IN and
a separate one for CASSETTE OUT. Generally you'll use only one at a time. Use CASSETTE IN
for LOADing a program, or CASSETTE OUT for SAVEing a program.

To load a program from a cassette image WAVE file, use +cassette load+
to put the tape into the cassette player. The tape will automatically rewind and
advance to the header tone. Then use the Apple LOAD command to load the program
from the tape. If the Apple gives you +ERR+, that means it could not interpret the
WAVE audio correctly.
If you want to rewind the tape, you can use the +casssette rewind+ command.
Use +cassette eject in+ to close the file.

To save an in-memory program to a cassette tape image WAVE file, use
+cassette blank <file-path>+ to put a new blank tape image into
the cassette recorder. Then use the Apple SAVE command to record to the tape, and then
+cassette save+ to save the WAVE file. Use +cassette eject out+ to close the file.

The emulator will not overwrite existing data in a tape image file.

==== Commands

+cassette load [ <file-path> ]+

This loads an existing WAVE file (from the host computer) containing a cassette tape image
onto the CASSETTE IN port,
in preparation for loading the program from it. If +file-path+
is omitted, a dialog box will be presented to select the file to load.
The tape is automatically positioned at the first header tone.

+cassette rewind+

This command rewinds the tape currently on the CASSETTE IN port. After rewinding
the tape, you will typically need to fast-forward to the head tone using
the +cassette tone+ command.

+cassette tone+

If more than one program is stored in one WAVE file, then after loading the first
program, you may need to fast-forward to the next header tone. This command will
do just that.

+cassette blank <file-path>+

This creates a new empty file (on the host computer) that represents a cassette tape image,
and loads it onto the CASSETTE OUT port,
in preparation for saving a program to it.
The file must not already exist. The file type should be +.wav+ to indicate a WAVE format file.

+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.

+cassette eject { in | out }+

This removes the file from the specified cassette port (CASSETTE IN port, or CASSETE OUT port).

==== 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 blank hello.wav
------------------------

This will create a new, empty tape file image named +hello.wav+
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.

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.

[source,vbs]
------------------------
]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
------------------------

Now do a NEW to clear the program, and LIST to prove that it's gone.

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

]LIST
------------------------

We can now eject the tape (close the file).

------------------------
command: cassette eject out
------------------------

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

This will bring up the Open File dialog box. Choose
hello.wav file you just saved. Notice the
emulator now displays the name of the tape image file, along with the
position and length of the tape image. Notice the emulator automatically
advances the tape to the first header section.

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.

[source,vbs]
------------------------
]LOAD
------------------------

It will take several seconds 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
------------------------
