
------------------------------------------------------------------
         Sound Player & TSAY Sound Converter for the TS2068

         03-1996  Alvin Albrecht (sealbrec@acs.ucalgary.ca)
------------------------------------------------------------------


        This archive contains the following files:

readme.txt    :  This file.

sndplyr.sna   :  Snapshot of BASIC Sound Player + m/c

ayldr.sna     :  Snapshot of program used to read sound files
                 from MSDOS disk (for JLO disk V2.63+)

splyrsrc.wri  :  Text file containing Z80 source code for
                 Sound Player

tsay.c        :  Text file containing C source code for 
                 TSAY Sound Converter

tsay.exe      :  TSAY Sound Converter DOS executable


0.  CONTENTS

    1.  INTRODUCTION
    2.  INSTALLATION
    3.  USING SOUND PLAYER
    4.  TECHNICAL DETAILS
    5.  TO DO LIST

1.  INTRODUCTION

This package allows you to play just about any sound sample file
available on the Internet on your TS2068.  Playing a sample file
involves the following steps:

a) Get a sound sample file.  You can get sound samples of music,
TV show themes, random sound effects, etc. from several places.
A good starting point is http://themes.parkhere.com/themes/ which
contains a large archive of TV show themes.  It also includes a
bunch of links to sites containing samples of all manner of sounds.
You can also get samples from the alt.binaries.sound.* newsgroups.
Use the yahoo server at http://www.yahoo.com/ and do a search on
"sounds" to get a list of a few hundred other sites.

b) Convert the sound sample file to 8bit unsigned bytes without a
header.  To do this, you need SOX (SOund eXchange), which is a
public domain program available from ftp://ftp.cwi.nl/pub/audio/
SOX is a noble effort whose goal is to provide a single program that
converts sound sample files between all the various formats.  Any
file supported by SOX can be played on your TS2068.  These include
all the most popular formats:  Microsoft RIFF (.wav), SUN (.au),
MacIntosh (.snd & .ub), Amiga (different .snd), etc.  SOX will
convert the sound sample file to 8bit unsigned bytes which is then
further processed by TSAY to generate a .ay file, which is the sound
file format I made up for Sound Player.

c) Transfer the .ay file from the host machine (probably a PC) to
your TS2068.  I've included "ayldr.sna" which will do this job if
you own a JLO V2.63+ disk system.  If you own a Larken disk system,
a brief article in ZQA volume 1, #4 by George Chambers describes how he
transferred MSDOS files on the Larken system.  Otherwise, you're
own your own.

d) Load up Sound Player on your TS2068 and away you go!

Before you go on, you need to get SOX from ftp://ftp.cwi.nl/pub.audio/
There is a self-extracting DOS version called "sox10dos.exe" that you
should get if you own a PC.  For everyone else, the C source code
is in "sox10.tar.gz" or something similar.  A Makefile is included for
many flavours of Unix, the Amiga, Atari ST, etc.  It took about 10
minutes of fiddling around for me to compile under AIX 4.1.  Read the
"cheats.wri" file included to get a quick grasp of what SOX is and how
it works.  There are a few examples here to help you out, too.

If you own a JLO V2.63+ disk system, get "sna2jlo1.zip" from
ftp://ftp.nvg.unit.no/pub/spectrum/utils/ts2068/ (probably right next
to where you got this from).  This will allow you to run the .sna
snapshots included in this archive, plus all the Spectrum games on the
net if you have a Spectrum emulator.

2.  INSTALLATION

(i) ON THE HOST MACHINE

You need SOX and TSAY installed on the host machine.  If you own a PC,
SOX comes with a DOS executable and TSAY.EXE is the DOS executable
of TSAY.  Enter TSAY with no arguments to get a description.
If you don't own a PC, you'll have to compile SOX and then TSAY.C.

(ii) ON THE TS2068

*You need Sound Player.  A snapshot of Sound Player is contained in the
file "sndplyer.sna".  It consists of a BASIC program that cycles through
all the sound files on disk and the Sound Player m/c.

If you own a JLO V2.63+ disk system, you can use sna2jlo to load
and run the snap from Spectrum mode (not TS2068 mode).  When the snap
is loaded, the command line will contain all the SAVE commands to
save Sound Player.  Insert a fresh JLO disk and press enter.

If you don't own a JLO disk system, you will have to load the snap
into an emulator (like Z80), LIST the program and type it into your
TS2068 by hand.  To copy the m/c use:  FOR z=65281 TO 65281+284: PRINT
Z;" ";PEEK Z: NEXT Z.  You must POKE all these values into the 2068's
memory by hand.  Once that's done, save Sound Player to your disk system
with the appropriate SAVE command equivalents of the SAVE commands you
see on loading the snap into the emulator.

*You need some means of loading the sound files from MSDOS disk.

If you own a JLO V2.63+ disk system, load the snap "ayldr.sna".  Once
again, the command line will contain a SAVE command.  Insert a disk
and press enter to save AYLOAD.  This program is a hack that loads .ay
files from MSDOS disk of length 35480 bytes and transfers them to JLO disk.  

For any other system, you will have to find a way to transfer the .ay
file from the host machine to your TS2068 (by disk? by modem? by rs-232?).

3.  USING SOUND PLAYER

Here's a typical example of how to convert a sound sample file to .ay format.

(i) Get sound file.  For this example, I grabbed gilligan.au, which is the
theme from Gilligan's Island from the site mentioned in the introduction.

(ii) Get information about the sound file using SOX:

sox -V gilligan.au -e stat

The pertinent information we are looking for is the #channels, sample
rate and volume control.  For gilligan.au, sox says the sample is mono
(1 channel - if sox says nothing, always assume 1 channel), recorded
at 8012 Hz and volume should be 1.408.  The volume is the amplification
that should be applied to reach full volume.  This is very important
as TSAY uses the top 4 bits of each 8 bit sample.

(iii) Convert to 8 bit unsigned format using SOX:

sox -v 1.408 gilligan.au -t ub gilligan.ub

(iv) Convert to a .ay file using TSAY:

tsay gilligan.ub -r 8012 -c 1 -V -n": Gilligan's Island" isle

MSDOS CAN'T HANDLE STRINGS WITH SPACES IN THEM.  FOR MSDOS TRY:

tsay gilligan.ub -r 8012 -c 1 -V -n:*Gilligan's*Island isle

TSAY will set the sample rate as close to 8012 Hz as it can.  The -V
option lets you know what the actual sample rate will be, the # channels
coded and the header string put into the .ay file (set by the -n option).

TSAY will automatically break up the resulting .ay file into up to 26
.ay files of maximum length 35480 bytes (can be reset via -f option).
35480 bytes happens to be 7 cylinders on JLO disk; I chose that size
to maximize the use of disk space on the JLO disk system.  The .ay file
will be at least 50% smaller than the corresponding .ub file, and will
tend to be about 40% of the original size.

(v) Transfer the .ay files to your 2068.

If you own a JLO V2.63+ disk system, format a fresh MSDOS data disk and
copy the .ay files.  I use a 5.25" DSDD disk drive with my 2068, so I
format the disk with format b:/4 and copy the files with copy *.ay b:

With the MSDOS disk in your TS2068's active disk drive, run AYLOAD.
AYLOAD will load each .ay file and then transfer it to JLO disk.
Remember to BREAK the program after AYLOAD has transferred all the ay
files.  If you don't, it will transfer ay files that don't exist (are
empty) and will attempt to load files past the number of tracks on
your disk.  This is probably not healthy for your disk drive.

Copy SNDPLAYER (BASIC) and sndplayer (CODE) to the disk with all the
.ay files.  Make mods in the BASIC program so that it loads all the
.ay files you have on disk (line 17: this means setting b$ and c$ to
the letters 'A' to whatever the last letter of the .ay files is, and
setting a$ to the base name).  For example, tsay broke gilligan.ub into
ten files named isleA.ay, isleB.ay, ... isleJ.ay.  a$="isle", b$="A",
c$="J".  Save this modified prog to disk and run.  Sound player will
play each file in sequence, with options for repeating a file, jumping
to a file or quitting.

*** Sound Player is capable of playing mono and stereo samples.  99%
of sound samples fall into these categories.  A few are quad channel
and fewer still are some other oddball # of channels.  SOX is capable
of reducing the # of channels in a sample (simply averages a few channels
together).

*** Sound Player can play samples at a rate between 1 and 54kHz for mono
and between 1 and 24kHz for stereo.  This is actually better than most
modern computer systems.  It is unlikely you will find a sound file
recorded at more than 44kHz (CD quality) so you're not likely to
find a file that can't be played in mono.  In stereo, it is unusual to find
sound files at greater than 22kHz.  Once in a while you might.  If that
is the case, you will need to resample the sound file at a lower rate
supported by Sound Player.  SOX will do a linear resampling for you
if necessary.  Resampling will introduce noise into the sample and
possibly aliasing.  To avoid aliasing, apply a low pass filter with a
bandwidth of around 40% of the new sample rate before resampling. SOX
will also do this for you, but it only implements a 1st order
digital filter.  If you hear high frequency background noise in the
sample played, you may want to put the sound file through the filter
a few more times.

4.  TECHNICAL DETAILS

The .ay file format (file format played by Sound Player) and relevant
timing information is fully described in "splyrsrc.wri".  Information
on standard sound file formats can be found in the Audio FAQ at 
ftp://ftp.cwi.nl/pub/audio/

5. TO DO LIST

* The TS2068 needs more memory.

* We need a good DOS file utility for JLO disk.

* The new wave in audio is audio sequencers.  It would be very difficult
to implement audio sequencing on the 2068 because all the timing must
be handled in software.  It would be much easier if a sound card was
built equipped with an interrupt driven FIFO acting as a buffer.
