WavePlay-SD V2.0	ÁROK®™ party version
    ================

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

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

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:

https://bsz.siz.hu/SD2IEC-FlexSD/

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

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

The WavePlay-SD play 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. But 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 uses 1-bit data transfer with the drive for most tasks (ATN is not
used, there can be multiple drives on the serial bus), but 2-bit transmission
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.

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

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

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 it is not already)
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. This "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,
2022.07.17.