    WavePlay-SD V2.2	WINTER 2025 EDITION
    ================

  Platforms: C64
	     C128
	     C16+C116 (64K), plus/4 (C264 series)
  Requirements:
    One of the above machines + SD2IEC drive with the appropriate firmware.

===============================================================================

  Preface:

This program is an over-engineered proof-of-concept code. The realisation of an
old idea: play digitised music while loading from drive. With the old floppy
drives this would be too much of a compromise, but nowadays there is an
inexpensive storage for Commodore machines available, this is the SD2IEC in
various versions.

The original firmware of these drives does not allow free programming. For this
reason, a flexible programmable firmware version is needed to run the program,
see:
        https://bsz.amigaspirit.hu/vcpu/
or      https://bsz.siz.hu/vcpu/

for details.

This firmware extension provides a generic virtual running environment.
DOES NOT CONTAIN any specific extensions for WavePlay-SD!

===============================================================================

  Usage:

  General:
  --------
HELP (plus/4, C128), F7 (C64, C128):
  Print help page
CURSOR UP/DOWN/LEFT/RIGHT:
  Move selection
RETURN / ENTER (C128):
  ACTION button:
    Push selected button
    Change directory
    Play files
    Load module

  In file-request mode:
  ---------------------
CURSOR UP / CURSOR DOWN, <, >:
  Move selection
C= + CURSOR UP / CURSOR DOWN:
  Move more
CONTROL + CURSOR UP / CURSOR DOWN:
  Move first/last
RETURN / ENTER (C128):
  Change directory
  Continuous play
  Load module
C= + RETURN / ENTER (C128):
  Play one file
INST/DEL, P:
  Go parent directory
CONTROL + S:
  Go to Setup
CONTROL + R:
  Re-read directory
CONTROL + C= + R:
  Restart program
CONTROL + X:
  Exit

  While playing:
  --------------
RETURN / ENTER (C128):
  Continuous play
C=:
  One file play
SPACE:
  Pause / continue
<:
  Play previous
>:
  Play next
CURSOR UP:
  Stop, go previous
CURSOR DOWN:
  Stop, go next
CURSOR LEFT:
  Rewind 10 secs
CURSOR RIGHT:
  Fast forward 10 secs
RUN/STOP:
  Stop playing

===============================================================================

  Technical details:

This program plays only specially prepared files. These contain 8-bit sound
samples converted to the desired playback frequency. Therefore it is also
possible to playback with an (covox-style) 8-bit D/A converter connected to the
USER port. Different (internal / loadable) D/A modules are available for each
platform.

The playback frequencies are currently fixed, these are adapted to the display
speed of the platform. There are currently 4+4 of these:

              C64       C128      plus/4
Poor:         3909 Hz   3909 Hz   3889 Hz
Low:          5213 Hz   5213 Hz   5185 Hz
Mid:          7819 Hz   7819 Hz   7778 Hz
High:         -        15639 Hz  15556 Hz

The program includes several types of data transfer protocols for these speeds:

			C64          C128           plus/4
 3909 Hz /  3889 Hz:   SER1B     SER1B,  FSER1      SER1B
 5213 Hz /  5185 Hz:   SER1B     SER1B,  FSER1      SER1B
 7819 Hz /  7778 Hz:   SER2B*    SER2B*, FSER1      SER1B
15639 Hz / 15556 Hz:     -       SER2B*, FSER2      SER2B*

The program uses 1-bit data transfer with the drive for most tasks (SER1B; ATN
is not used, there can be multiple drives on the serial bus), but 2-bit
transmission (SER2B) is required for higher playback frequencies (ATN used,
only one device allowed on the serial bus). In the table above, "*" indicates
the need for 2-bit transmission. The C128 version includes two Fast Serial
protocols (FSER1, FSER2) too, which also do not use ATN, allowing playback with
multiple devices connected to the bus. Remember: Fast Serial data transfer is
in experimental state! Always use the latest firmware for your drive!

"High" quality playback is only available on the C128 / plus/4. (Unfortunately,
the C64 is not fast enough for this job.) At this speed, the speed of the
SD-card is also important. An another important factor is the "complexity" of
the file system, in case of buffer underflow, an attempt can be made to
increase the cluster size.

===============================================================================

  I want my own music:

To convert your music, you need your favourite sound editor. (I used an older
version of Audacity.) Follow these steps:

1. Load the music
2. Convert it to mono (if necessary)
3. Boost the volume it enough to take full advantage of the dynamics
4. Resample with one of the frequencies in the table above (what you need)
5. Export music to an uncompressed 8-bit Riff Wav file
6. Convert this Wav file to a format suitable for the WavePlay-SD

For step 6, the package contains a simple (command line) python tool:
"audiofilegen.py". (Python3 runtime required!) Usage:

$ ./audiofilegen.py outfile.seq w wavfile.wav artist title

Parameters:

"outfile.seq": Target music file name. This file is played directly by the
               WavePlay-SD. (The ".seq" file extension is not important.)

"w": Wav-file mode. The "w" indicates that the source file is a Wav file.
     It is also possible to convert RAW data, in which case this parameter
     can be "s:freq" (signed BYTEs) or "u:freq" (unsigned BYTEs). The "freq"
     is the sampling frequency, one of the above table can be used. In
     Wav-file mode, this data comes from the header of the Wav file.

"wavfile.wav": Source music file, the previously prepared Wav (or RAW) file.

"artist" / "title": The artist and title of the music. These can be up to 32
                    characters long. (32 the artist, 32 the title.) These are
                    displayed by the WavePlay-SD. For this reason, only the
                    basic ASCII characters can be used: Letters, numbers,
                    basic signs. (The lower case letters in the file will be
                    replaced by capital letters!) Use underline symbol ("_")
                    instead of space in these parameters. The underline symbol
                    in the file will be replaced by a space.

This tool will also convert audio files with unknown playback frequencies, but
they will not be recognized by WavePlay-SD! (Warning: This converter utility is
for personal use, so error handling is not complete.)

===============================================================================

  Acknowledgements:

Special thanks to Larry for the various SID + TED D/A codes + tables and for
all the testing!

Also thanks to Siz and TLC for the beta tests!

===============================================================================

BSZ,
2025.12.20.
