MAKEUEF 0.3a
============

This program attempts to convert genuine Electron/BBC tapes to tape images via sound samples (WAVs or raw data) or via your sound card.

NOTE OF GREAT IMPORTANCE : The windows version appears very nearly not to work for me (it seems to be able to detect high tone, but always comes up with 'Data ?' very quickly, often before even getting the file name), and the Linux version is untested. The games successfully transferred listed below were done so via the DOS version, on a Dell P166 with a Sound Blaster 16 Vibra on the motherboard.

PLEAD OF GREAT IMPORTANCE : if you intend to convert lots of tapes and make them available on the internet (horay for you!), please release them as tape images rather than state snapshots. As of beta 2 (not uploaded at the time of writing, but sitting on my hard disk in need of only a small bit of extra work) 90% of tape images load near instantaneously anyway.

HOW TO USE
==========

Run the program with no arguments to get a list of possibilities. If all this is a little beyond you, just type this :

	'makuef -o outfile.uef'

And the program will attempt to open your soundcard for reading in order to create a uef file named 'outfile.uef'. Now play your tape, and I hope the on screen prompts are fairly self explanatory.

If in DOS or LINUX :

	Press CTRL+C when tape is finished. 

If in Windows :

	Press ESCAPE or Q when tape is finished. Whatever you do, don't press CTRL+C - you'll lose all your data.

	Of course, if you are using a sound sample then the program will know when to end all on its own.

DETAILED DESCRIPTION OF COMMAND LINE OPTIONS
============================================

-h
--

	Displays the help message, just as passing no command line parameters does.

-f <some number>
----------------

	If working with raw sound files, there is no way for the program to find out at what frequency the sound file is recorded - necessary information if span calibration is set to frequency (see below). The number will be assumed to be in decimal unless preceeded with 0x - making it hexadecimal.

	DEFAULT VALUE is 22050.

-t <u or s>
-----------

	This switch again is only useful for raw sound files. This program supports only mono raw sound files with 8bit samples, but is happy to accept signed or unsigned data. A 'u' here selects unsigned reading of raw data files, an 's' selects signed.

	DEFAULT VALUE is u.

-s <t, f or some number>
------------------------

	On an Electron or BBC, the state of individual bits is determined by the number of wave variations within a given span of time. This switch sets how the program calibrates its interpretation of the length of that span.

	If set to 'f', the program does a calculation on the input wave frequency to determine the correct span to read data stored with the default BBC/Electron timing. This option is probably the best one for most circumstances, and may indeed prove to be correct for all data that also works on an Electron.

	If set to 't', span will be calibrated via the lead-in '2400Hz' tone that exists before every file. In actual fact the lead-in tone will be of a different frequency if the default timing is not being used. If using this option, be aware that the very first thing the program must 'hear' must be some lead-in tone, or calibration will be done by the wrong sound, and unpredictable results (usually failure to load anything) will result.

	Alternatively, if you know better than MakeUEF, you can simply specify the number of samples to consider per bit. This option is principly for debugging!

	DEFAULT VALUE is 'f'

-l <s or p>
-----------

	Decoding tape data relies upon being able to calculate the momentary input wave frequency. The wave frequency can be considered to be the time between 'peaks' of the wave, or the time between the (signed) wave crossing the 0 line.

	The BBC/Electron hardware is most likely to use the latter method (though I can not be sure), however MakeUEF can use the former also. The former method has advantages with older tapes on which the wave has 'drifted' upwards or downwards - a possible effect of tape aging.

	Therefore, the MakeUEF default is peak to peak measurements (option p), but probably the more accurate (and more prone to failure) option is sign measurements (option s).

	However, the description of how data is encoded that I have is fairly vague, and data from some locations may only work with option 's'. Be warned.

	Notice this : option 'p' is highly volume sensitive. Too high a volume, such that many measurements are 'off the scale' or too low a volume, such that the shape of the wave is poorly defined will cause 'Data ?' errors. Conversely, I can think of no reason not to set your volume as high as possible for option 's'.

	DEFAULT VALUE is 'p'

HARDWARE REQUIREMENTS
=====================

All versions should work with no sound card if only being pointed at sound files.

For DOS, besides a 386 or above and a DPMI server, probably a SoundBlaster. The library I am using for sound card access may also support the ESS Audiodrive and/or Ensoniq Soundscape for input, but I can't be sure. If the option exists, it uses the line input rather than the microphone input. Other cards listed by the program refer to a presently non-existant output mode.

The windows version should work with any sound card which has a windows driver and supports 8bit data capture. Unsurprisingly. Adjust your cards mixer via windows to select the input line.

Similarly, the Linux version works via the open sound system. So use a sound card which also works via the open sound system. And again the 8bit data requirement holds.

TAPES I HAVE SUCCESSFULLY CONVERTED
===================================

Games which I have converted and played successfully in the emulator :

	The Introductory Cassette		- Acorn
	Chess					- Acornsoft
	Sphinx Adventure			- Acornsoft
	Hopper					- Acornsoft
	Starship Command			- Acornsoft
	Number Balance				- Acornsoft / ecm
	Chuckie Egg				- A'n'F
	Paperboy				- Elite / Atari
	Yie Ar Kung Fu				- Imagine / Konami
	Jet Power Jack				- Micro Power
	Felix Meets the Evil Weevils		- Micro Power
	Tomcat					- Players
	Spellbinder				- Superior
	Repton 3				- Superior
	Spycat					- Superior
	Crazee Rider				- Superior
	Galaforce				- Superior
	Codename : Droid			- Superior
	Citadel	(+)				- Superior

Games which appeared to convert okay but wouldn't play in the emulator :

	Sphere of Destiny			- Audiogenic
	Strike Force Harrier			- Mirrorsoft
	Ravenskull				- Superior
	Repton 1				- Superior

Games which failed to convert :

	Elite					- Acornsoft

(+) indicates that Citadel is a special case. On the original release, the file 'citam' alternates in name between 'citam ' [sic] and 'CITAM', causing MakeUEF to think you have inadvertently fast forwarded or rewound to a different file, and hence produces an 'expecting' error. However, the 'Play It Again Sam' edition sticks with 'CITAM' all the way through, and hence this version converted fine

HOW TO COMPILE
==============

Just compile all the source files and link together, being sure to set one of the following defines on your compilers command line when compiling card.cpp at least :

	TARGET_OSS	for targetting the Open Sound System
	TARGET_ALLEGRO	for targetting the Allegro library (used in the DOS version)
	TARGET_WIN	for targetting the Windows multimedia functions

OTHER LIBRARIES USED
====================

All builds will require ZLib, and Allegro builds will require Allegro. Both of these are available in source code form via the internet.

COMING IN A LATER VERSION
=========================

The ability to go the other way - UEF to wave file or sound card.

CHANGE LOG
==========

0.3a :

	- thought about it for a second, realised I'm an idiot, and fixed the windows version

0.3 :

	- iterated towards fixing windows version. Does it work for you?
	- added alternate 'peaks' frequency measure for greater reliability on old tapes
	- added alternate 'tones' encoding, someone may want it
	- allowances for surprise non-ending of files (Elite now closer to working)
	- fixed tape image encoding so that high tone hangs for a bit after files, and gaps lie between files - as with real tapes
	- adding filename checking for illegal characters before printing names to the VDU - in particular trying to print the name of the '?' file on Acornsoft titles was causing the on screen prompts not to work

0.2 :

	- completely rewrote data parsing algorithm to sync properly with tape
	- altered sound card code to select > 22050Hz frequencies where possible in DOS & Windows

0.1 :

	- first release

CONTACTING ME
=============

Tell me how it goes, I am T.Harte@excite.com