!SampleCD v1.12   A sound sample creator for Acorn Risc Computers
 Paul Wilkinson 1995

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+ and CDFS 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 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.  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).  Note, however, that the last four 
controls (ie the track and position ones) affect the Start setting in the 
Selection panel (see below) whether the disc is playing or not.  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.

The second panel selects the section of the disc you wish to sample.  The 
Previous and Next buttons choose the track, and the Rewind and Fast
Forward buttons choose the position within the track that the sample starts
from.  These values can also be typed in for even ner control.  The length 
of the sample should be typed into the next writable icon.  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.  Now ******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.

Finally
-------

!SampleCD was developed on a RiscPC with a Cumana Indigo CD-Rom drive.  If it
works or fails to work on a different combination, please let me know so that
I can compile a compatibility list.  Especially PLEASE let me know if it
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.  If it works on your system,
great.  If not, please get in touch and I'll do my best, but Im not 
promising anything.

I can be contacted via the internet at

ppxpbw@ppn1.physics.nottingham.ac.uk (should be okay until mid-1996 or so)



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 (by reasonable I 
   mean a maximum limit of 1.75 for a DD disc and 2.25 for a HD disc, 
   allowing for inflation as time rolls on, of course!)
3) The only exception to condition 2) above, is that this program may be
   distributed on a magazine cover disc by the following publications
   provided that I am contacted rst:-
   
   Acorn User
   Acorn Archimedes World
   Archive
   Eureka
   Risc User
   
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 (hah! I thought this after
v1.10!).  PLEASE let me know if Im wrong about this.


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

Find some better way to avoid corrupting samples than waiting for the CD to
 stop rst (any ideas?)

Apart from the above (very minor) points, I consider this program pretty
much complete.  This *may* be the nal release version, although I will 
certainly release updated versions of the compatibility list as it 
(hopefully) continues to expand.


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.
				  

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 and suggestions.  Cheers!
Thanks especially to:-

	Graham Jones	for nding out about the incompatibility with
			his SCSI card.  Hopefully sorted now!
	Marc Evans	for sending me full documentation on over half
			the CDFSdriver SWI calls.
	Chris Poole	for coming up with the same idea for alignment
			correction that I did (!), implementing it, and 
			sending me his patched code so that I could take
			a look.  None of Chris code is actually used in
			this program, but it gave me the incentive to
			ARM code my very slow BASIC routine that was doing 
			the job and nally release v1.10.
			

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

The only set up that I *know* will work is using Cumanas Indigo drive with
CDFSdriver v2.21+.  Hopefully any other set up with CDFSdriver 2.21 or later
(ie which supports the CDRead_Audio call) will work.  However you may nd
problems if you are using a SCSI card in you system (even if the CD drive 
isnt connected to it).  Im afraid I have no idea why this is.  If your CD 
drive isn't a SCSI device, try temporarily *unplugging all the SCSI modules.

Note, I hope that I have now fixed the SCSI problem.  Please can you let me 
know if youre still experiencing problems.	
	
Two recent posts on c.s.a.misc have shed some light on the ReadAudio 
compatibilty issue.  Apparently, the Indigo is the only drive from Cumana at 
the moment that is shipped with ReadAudio support.  Other companies that 
provide up to date versions of the software are HCCS and (possibly) Morley.  
Hope this helps.


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

!Zap v1.30	  Really *fast* text/memory/code editor.  Utterly brilliant
		  and free.
!TemplEd v1.31	  The best, easiest to use and free-est template file editor.
!StrongHlp v2.02  If you can't afford the PRMs (like me!) this contains
		  mountains of useful information.
!BSquahser v1.18  The most efficient BASIC compressor that I've found (I've
		  tried BasCompress and this is better!)
!SoundCon v1.51   A very comprehensive sample converter and player.
