!SampleCD v1.16   A sound sample creator for Acorn Risc Computers
 Paul Wilkinson 1997

About !SampleCD
===============

**********************************************************************
Read the distribution conditions below.  Under *NO* circumstances must 
!SampleCD be used to violate Copyright on audio recordings.
**********************************************************************

N.B. !SampleCD requires RiscOS 3.10+, CDFS 2.21+, CDFSdriver 2.21+ and a CDRom
drive which supports the CD_ReadAudio software interrupt.
     
This program is designed to sample audio data from CDs and convert it into a
variety of formats understood by your Acorn computer.  It can currently save
data in the following formats:-

Raw CD data	 (16 bit stereo, signed linear)
Acorn Replay	 (16 bit stereo)
Armadeus	 (8 bit mono)
Logarithmic	 (8 bit mono representation of 12 bit mono)
Linear unsigned  (8 bit mono)
Linear signed	 (8 bit mono)

Any decent sample editor should be able to handle most of these formats
(commercially Prosound, Sonor or AudioWorks are available, whilst in the public 
domain SampConv, Effex, DSEdit, Sox or SoundCon should suit most requirements).


How to use !SampleCD
====================

The Main Window
---------------

Double click on the !SampleCD icon to launch the program.  The program will
check your system for you before starting up.  Firstly, if you dont have the
modules mentioned above, !SampleCD wont start.  If you have the correct modules
you still wont be able to use the program if your drives do not support the
CD_ReadAudio call.  !SampleCD will test any CDRom drives attached to your
computer and will warn you if any of them dont support this call.  Clicking on
the iconbar icon which appears will open the SampleCD window.  At the top of
this window are a row of CD-style controls.  While the disc is playing, these
act as normal CD player controls (i.e. play, stop, pause, previous track, next
track, rewind, fast forward).  When the disc isn't playing, the last four
controls (ie the track and position ones) affect the Start setting in the
Selection panel (see below).  The action of the play button has three
settings; play entire disc, play selected track and play current sample
selection.  The action can be set by clicking the appropriate radio button under
the CD controls.  Below these radio buttons on the left are the controls for
selecting which drive to create samples from.  On the right are two other icons
which show the currently playing track and time.

Initially, only the first panel is visible.  This is because !SampleCD can 
also be used as a simple CD player, in which case the other functions aren't 
needed.  To access the other panels, click the toggle box in the top right.
The second panel selects the section of the disc you wish to sample.  As
mentioned above, when the disc isn't playing, the CD player icons can be used to
set the start time.  However, there is an easier way to choose which section of
the CD you want to sample.  Set the disc playing and use the CD player icons to
get the disc near to the section you wish to sample.  Then when you hear the
start of this section, press the Set Start button.  Similarly, when you hear
the end of this section, press Set Length.  This automatically enters the
correct values in the writable icons.  For even ner control, these values can
also be typed in.  The format of the writable icons is
Minutes:Seconds:Hundredths.  Note that when entering the time in these icons,
the handler is reasonably intelligent, so you can get away with typing 1:5 and
this will convert to 01:05:00 (one minute and ve seconds into the given track).

The third panel controls the saving of the sample.  The three upper left-hand
icons are a standard RiscOS save box; simply drag the icon to where you want the
sample to be saved.  The uppermost text icon shows the format that the sample
will be saved in.  To change this, click menu over the text icon, or click the
menu icon just to its right.  The sample frequency is selected in exactly the
same manner.  The buffer icon selects whether or not the sample is taken in
sections via a buffer or all in one go.  The advantage of using a buffer is that
your sample can be any length (without using the buffer, only samples that are
short enough to t into the available memory can be taken).  The length of the
buffer sections (in seconds) is displayed in the text icon to the right.  This
can be increased/decreased by clicking the up/down icons respectively.  The last
icon in this panel, labelled Correction is only available if sampling via a
buffer is on.  If this icon is selected, any errors caused by the sample
sections not quite aligning properly will be corrected.  These errors can cause
audible clicks at the edges of each section.  It takes just a little longer
than if no correction is used.

Finally, the main menu has three options.  Info and Quit are the standard
menu entries, and Save Options saves the state of the Sample Type, Frequency
and the three Buffer icons.

Note that Acorns interactive help is supported by SampleCD.

Creating A Sample
-----------------

Set the correct start position and sample length in the writable icons as
described above.  Select the desired sample format and frequency.  If you are
using the buffer, set the desired buffer length and whether you need alignment
correction.  If the CD is playing ******STOP THE DISC****** and let it spin down
for a couple of seconds.  If the disc isnt stopped there is a good chance that
some or all of your sample will be corrupted.  Im not sure why this is but I
guess that the CD driver has some sort of audio buffer that must be allowed to
clear.  Now drag the save icon to a directory viewer or enter a complete path
name in the icon and the sample will be saved.

Help!  The start of my sample is corrupted!
-------------------------------------------

If the sample youve lovingly crafted turns out to have noise in the rst couple
of seconds, dont worry, this is quite common.  To x it you can try two things.
 Firstly, press the Stop CD player control and wait a few seconds.  Now try
taking the sample again (the settings in the Start and Length boxes should
still be the same, so youll get the same sample).  If this doesnt work, click
in the box next to Start that shows the track number and type in the previous
(or next) track number and press Enter (note, dont use the Next and
Previous CD player controls as this sets the start time to zero).  Now take
the sample from this track.  This hopefully will clear out any garbage from the
buffers.  Once this is done, type the original track number back into the
writable icon and save the sample you wanted originally.  It should now be ne.

What are those two les ErrorOn and ErrorOff for?
-----------------------------------------------------

If you happen to have two or more CD players connected to your system, and some
of them arent CD_ReadAudio compatible, the program will warn you of this every
time it starts up.  I reckon this could be quite annoying, so I put in these two
les.  If you want to disable the compatibility warning, simple double click on
ErrorOff.  Similarly, double-clicking ErrorOn reenables this warning.

Finally
-------

!SampleCD was developed on a RiscPC with a Cumana Indigo CD-Rom drive.  The
program should now be able to test your system for compatibility, so if you
dont get any warnings about a particular drive, it should work!  I would be
very interested to know of any drives that slip through this net, or any drives
that do work but claim that they dont!  Especially PLEASE let me know if the
program works (most people only seem to want to get in touch if there is a
problem!)  Please note that this program has been developed without the aid of
the PRMs and in-between times whilst studying for my PhD and doing all the other
interesting and cool things that physicists get up to in their spare time.  If
it works on your system, great.  If not, please get in touch and Ill do my
best, but Im not promising anything.

I can be contacted via the internet at

ppxpbw@ppn1.physics.nottingham.ac.uk

This address is likely to cease being useful after about April 1997.  You may 
not get your mail bounced back, but it certainly won't get answered as I won't 
be there any more.  When I get back on the net, I'll try and make my presence 
known.


Stop Press
----------

There is a problem with the ATAPI driver on newer systems that will cause
SampleCD to think audio CDs are in fact CDRoms.  There is nothing I can do 
about this, it *isn't* my fault!  I have included a posting to C.S.A.Programmer 
which gives a possible fix.  All I can suggest is; try it!


Terms and Conditions
====================

This application is Freeware.  I retain copyright, but it may be freely
distributed as long as:-

1) All the files accompanying this message remain intact and unaltered and are
only distributed together.

2) Only reasonable charges are made for its distribution (I used to define 
reasonable, but I haven't bought stuff from PD libraries for ages.  If you feel 
you've been ripped off, complain loudly and never use them again.  When I 
didn't have net access, I used APDL and I think their prices serve as a good 
guide.)

3) The only exceptions to condition 2) above, are (i) this program may be
distributed on a magazine cover disc by the following publications :-
   
Acorn User
Acorn Archimedes World
Archive
Eureka
Risc User

(ii) SampleCD may be distributed by The Really Good Software Company with their 
AlphaEdit commercial package and (iii) Oregan can do what they like with it as 
they gave me a free copy of Prosound for the privilege.
   
This application is supplied as seen.  No warranty (either implied or stated)
is given concerning the fitness of this program for any particular purpose.  I
will not be liable for any type of damage that the use of this program may
cause.

It is possible to use this program to infringe copyright on commercial material
(audio or otherwise).  This program is distributed with the condition that it
may not, under any circumstances, be used to store, modify or copy in any format
(electronic or otherwise) any material which is protected by copyright.


Known bugs
==========

As far as I know, Ive now got rid of all of em (yes, even the one that left
huge dynamic areas all over the place!).  PLEASE let me know if Im wrong about
this.  The program should now be StrongArm compatible.  This will need sorting 
quickly if it isn't, so please get in touch ASAP if it won't run on your SA 
machine.


Things to do
============

Find some automatic way to avoid the corruption of samples (any ideas?)


History
=======

v1.00 13/03/95  First release version.
v1.01 22/03/95	Now positions window sensibly on the screen and bumps it back if
		the mode changes.  
		Also reduced the wimp slot size to a realistic value.
v1.10 30/05/95	Added some useful error messages (ie program now tells you if
		there isnt enough memory).  
		Also added a variable length sample buffer.  
		Now uses Dynamic Areas on RiscOS 3.50+ instead of increasing the
		wimp slot.  
		Finally sorted out the uneven sample joining when using a buffer
		(this proved to be quite easy in the end!).
v1.12 09/07/95	Fixed whopping great bug, which I *think* was the cause of most
		of the incompatibility problems (in particular, all the clashes 
		with SCSI interfaces).
		Fixed minor (and very rare) bug that used to give extra  second
		of play at the end of Replay files.
		No longer restricted to sampling from drive 0.
v1.14 26/01/96	All allocated memory now freed up on errors.
		Checks each attached drive for CD_ReadAudio compatibility
v1.15 28/02/96	Moved menus to make them more Acorn Style.
		Added easy set start and length buttons.
		Added the facility to turn the compatibility warning off.
		Displays hourglass and percentage when sampling.
		Learnt how to spell application in the interactive help!
v1.16 23/02/97  Should now work on StrongArm machines.
		Time icons no longer get updated if disc is stopped or paused.
		Seconds icon matches the actual elapsed time better.
		Sampling functions initially hidden to make use as a CD player 
		more convenient.
		 
		  
Acknowledgements
================

Thank you to everyone who got in touch with me since the release of v1.00. 
!SampleCD is now a much more polished (and hopefully robust) program than
before, due in no small part to your comments, suggestions and in *two* cases 
now, actual material reward!  Cheers guys, you know who you are.


Compatibility
=============

Ive given up maintaining a list.  The program should now tell you if it will
work or not.  Ive had positive reports on A5000s, RiscPCs and A7000s.  Both IDE
and SCSI seem to work, and so do double and quad speed devices.  Most successes
appear to have been with Cumana and HCCS products so far.


Recommended Software
====================

!Zap v1.35	  Really *fast* text/memory/code editor.  Utterly brilliant and
		  free.
!TemplEd v1.32	  The best, easiest to use and free-est template file editor.
!StrongHlp v2.03  If you cant afford the PRMs (like me!) this contains 
		  mountains of useful information.
!BSquasher v1.18  The most efficient BASIC compressor that Ive found (Ive 
		  tried BasCompress and this is better!)
!SoundCon v1.60	  A very comprehensive sample converter and player.
!Speccy v3.56f	  An *excellent* Spectrum emulator / nostalgia inducer / time
		  waster!
