- *
- S P E C T E M U *
- *
- Version 0.94 *
- *
This package contains a 48k ZX-Spectrum emulator for Linux and other UNIX operating systems, with full Z80 instruction set, comprehensive screen, sound and tape emulation, and snapshot file saving and loading. It can run on a Linux console, or in an X11 window.
The program is free software and is copyrighted under the GNU General Public License. It comes with absolutely no warranty. See the file COPYING for details.
Written by Miklos Szeredi
Email: mszeredi@inf.bme.hu
It can be downloaded by FTP from:
tsx-11.mit.edu:/pub/linux/ALPHA/spectemu/spectemu-0.94.tar.gz or
sunsite.unc.edu:/pub/Linux/system/emulators/zx/spectemu-0.94.tar.gz
For news and updates have a look at the Spectemu Page:
http://www.inf.bme.hu/~mszeredi/spectemu/
You can also join a mailing list (at the Spectemu Page), to receive a notice when new versions of spectemu are available.
Table of contents
- Requirements
- Recommended
- Features
- Drawbacks
- Compiling and installation
- Using the emulator
6.1 Command line arguments and configuration files (NEW)
6.2 Using the Spectrum keyboard
6.3 Keys that control the emulator
6.4 Effects of changing frame frequency and sound buffer size
7. Where can I get ZX Spectrum games for this emulator
8. Tape files
8.1 Loading a tape file
8.2 Quick loading of tape files
8.3 Saving to a tape file
8.4 Saving a tape file to real tape
8.5 Making a tape file from a real tape
9. Bug reports
10. Credits
1. Requirements
Linux or other UNIX OS.
Color X11 server (depths 8, 16 and 32 bits are supported)
and/or
SVGALIB console graphics library on Linux.
2. Recommended
A sound-card on Linux for wonderful spectrum 1-bit sound. And well, a fast enough processor... (Especially for the X11 version.)
3. Features
- Very fast because of assembly code in emulation (only on Intel processors).
- Emulation also in C, which is slower, but supports any processor.
- X support (with MITSHM if available, optionally double size window)
- Linux console graphics (with SVGALIB)
- Sound support (through Linux kernel sound-card driver, or SUN sound drivers)
- Snapshot saving and loading (.Z80 and .SNA format)
- Tape emulation: loading from tape files (.TAP and .TZX format)
- Optional quick loading of tapes.
- Saving to tape files.
- Separate utility to save tape files to real tape
- Configurable with config files and from command line
4. Drawbacks
- Poor user interface
See the file TODO for a list of things which still need to be done (Maybe by YOU)
5. Compiling and installation
To install the precompiled Linux executables just run 'make install' as root.
To recompile the programs on other platforms first type
./configure
This tries to determine the system type and parameters. Probably you won't have to give any options to configure, but here is the list of the most important options:
--help Print a full list of options
--prefix=PREFIX Install files under PREFIX (default is /usr/local)
Executables go under PREFIX/bin, ...
--without-readline Do not use the readline library (default is to
use it if it's available on your system)
--without-i386asm Do not use the Intel assembly code (default is
to use it, if your system is Intel based)
You may want to have a look at the produced `Makefile' and `config.h'. Then just type
make clean
make
Then to install the program, login as root, and run
make install
(If you want to compile on another machine be sure to `make realclean' before re-configuring and re-making the program!)
At the moment, there are two executable programs for running the emulator:
xspect the X11 version vgaspect the Linux console version
'vgaspect' uses the SVGALIB library. If you do not have this installed on your system 'vgaspect' cannot be started. You MUST have SVGALIB version 1.2.10 or greater installed, and it is STRONGLY recommended, that you get version 1.2.11 or later!
SVGALIB is available at:
sunsite.unc.edu:/pub/Linux/libs/graphics/
If you have SVGALIB version 1.2.11 or later, the emulator can run in background when you switch virtual consoles.
6. Using the emulator
After starting 'xspect' or 'vgaspect' you should get the '(C) 1982 Sinclair Research Ltd' message, and after pressing a key, the flashing cursor. If not, then all I can say, is hard luck to you (if you are ambitious, compile the programs with debug information, and try to figure out what is causing the problem). Do not start the emulator processes in the background, the terminal is needed when loading or saving files.
To load a snapshot immediately after the start of the emulator, you can enter the name of the snapshot file on the command line. (Also see section 6.1)
E.g.
xspect snap/chuckie2
In X you can resize the window. Window size can only be a multiple of the smallest window size (320x256). Smaller window means faster emulation, so if emulation doesn't run at full speed, try making the window smaller.
6.1 Command line arguments and configuration files
You can give options to Spectemu in three different ways:
- In a configuration file (either ~/.spectemurc, or /usr/local/share/spectemu/spectemu.cfg)
- With the X Resource Database (.Xdefaults), this applies only to 'xspect'
- On the command line
Most of the options are common to all three methods, only the syntax differs slightly. Here are examples of the different syntax:
Config File:
scale = 1
private-map = true
sound = false
color-type = grayscale
.Xdefaults:
xspect.scale:1
xspect.privateMap:true
xspect.sound:false
xspect.colorType:grayscale
Command line:
xspect -scale 1 -private-map -no-sound -color-type grayscale
List of common options:
NAME RANGE DEFAULT DESCRIPTION
---- ----- ------- -----------
frame-skip 1... 2 The smaller this is, the more
often the screen is updatated
scale 1..4 2 Window size of 'xspect'
private-map yes/no no Use private colormap in 'xspect'
mit-shm yes/no yes Use MIT-SHM extension in X server
if available
vga-mode 320x200 320x240 Resolution to use in 'vgaspect',
320x240 320x200 is faster (but not so nice)
sound yes/no yes Spectrum sound, if availble
sound-delay 1... 4 The amount of frames (1/50 seconds)
to delay sound. See section 6.4
sound-device filename (system The name of the sound device
dependent)
sound-sample-rate 4000... ~15625 Sample rate of sound device
sound-autoclose yes/no yes Whether to close sound device when
unused (so other programs can use it)
sound-dsp-setfrag yes/no yes Set this to 'no' if you use PCSND
sound driver
keyboard-type extended extended Specifies the mapping of the keys,
spectrum from the PC keyboard to the spectrum
compat keys. See section 6.2
custom
cursor-type shifted shifted How to use the arrow keys on the
raw PC keyboard. See section 6.2
joystick
allow-ascii yes/no yes Interpret other keys on the PC
keyboard. See section 6.2
true-shift <modif>* alt Modifier to get shifted symbol
as on the PC.
func_shift <modif>* control Modifier to get control functions.
color-type normal normal What type of colors to use. Gray-
grayscale scale looks better on monochrome
custom displays.
pause-on-iconify yes/no no Whether to pause emulator, when it
is iconified ('xspect' only)
vga-pause-bg yes/no no Whether to pasue emulator, when you
switch to a different console
quick-load yes/no no Use built in (quick) loader for
tapefiles.
auto-stop yes/no no Pause tape after each segment when
quick loading.
load-immed yes/no no Load tapefile immediately (as if
you typed LOAD "" / ENTER)
pause yes/no no Pause the emulator on startup
- <modif> can be one of: none, shift, lock, control, alt,
mod2, mod3, mod4, mod5
Extra command line parameters:
On the command line you may also use the following options:
-help Prints usage information, and a list of available
options
-version Prints out the version
Also on the command line, a snapshot file and/or a tapefile can be specified. Spectemu figures out the type of file from the extension. You can omit the extension, e.g. you have a snapshot file 'snap.z80' and you start spectemu with 'xspect snap', then it will add the '.z80' extension.
You can specify what type is the file by preceding it with one of '-z80', '-sna', '-tap' or '-tzx' options. This is useful for cases, when the filename does not have an extension (e.g. automatic starting with the midnight commander).
Extra config file options:
Color configuration
'''''''''''''''''''
You can configure the custom colors in the config files (and the X
Resource Database) with:
color[0..15] = R G B
e.g.
color-type = custom
color0 = 10 20 30
color7 = 40 50 60
changes the 0-th (black) and the 7-th (white) colors.
Keyboard configuration
''''''''''''''''''''''
You can set custom key bindings in the config file:
Key_<keysym_name> = K ...
Or in the X resource database:
xspect.keys: <keysym_name> = K ...; ...
The <keysym_name> can be set to any keysym (defined in 'spkey_p.h'). The K arguments are the spectrum keys to be assigned to the given PC key. K can be any letter, number (a..z, 0..9) or the following:
none, space, enter, capsshift, symbolshift, kempston_up, kempston_down, kempston_left, kempston_right, kempston_fire
e.g.
keyboard-type = custom
true-shift = none
Key_Insert = capsshift 9
Key_Tab = capsshift symbolshift
Key_Shift_R = kempston_fire
Key_Alt_L = symbolshift
Key_Alt_R = symbolshift
or as it would appear in a .Xdefaults file:
xspect.keyboardType:custom
xspect.trueShift:none
xspect.keys:Insert = capsshift 9; \
Tab = capsshift symbolshift; \
Shift_R = kempston_fire; \
Alt_L = symbolshift; Alt_R = symbolshift
6.2 Using the Spectrum keyboard
Those of you that have at some time used a Spectrum know, that the keyboard of this little computer is something very strange, with a LOT of keywords and symbols on and around each key. If you have not seen this keyboard (or have somehow managed to forget some bit of information that is on it) we produced quite a good copy of it, found in the 'spectkey.gif' file.
If you are using 'xspect' than pressing 'Ctrl-k' brings up the picture of the spectrum keyboard. You can press keys with the mouse (even more than one if you like), and it also shows which keys are pressed. (You can see what the emulator does when, for example you press 'BackSpace' or a '[' key on the PC keyboard).
The default mapping of the spectrum's keyboard to the PC's is the following:
The numbers, the letters, Enter and Space are the same. The left Shift on the PC corresponds to the CAPS SHIFT key of the Spectrum, and the right Shift corresponds to the SYMBOL SHIFT. This is quite simple and with these keys you can get all the functionality of the original Spectrum (assuming of course, you know how).
But...
To make life a bit easier, you can also use the Backspace, the arrow keys, and the following symbols as on a PC keyboard: ,./;'-=<>?:"_+[]{}\|~ (unless you turn the 'allow-ascii' option off)
To get a symbol which is written above the numbers on the PC, and not the function or symbol that is on the Spectrum, press Alt (actually the value of the 'true-shift' option) instead of Shift.
You can slightly modify the mapping with the 'keyboard-type' and 'cursor-type' options. Every mapping includes the basic keys (letters, numbers, Space and Enter). Here are the mappings special to each keyboard type and cursor type:
PC Key Spectrum Key ------ ------------
(Keyboard Types)
extended: (default)
Left Shift -> Caps Shift
Right Shift -> Symbol Shift
Back Space -> Caps Shift + '0'
Escape -> Caps Shift + '1'
spectrum: (spectrum-like layout, useful for some games, e.g. Jumping Jack)
< same as extended, plus: >
Comma (,) -> Symbol Shift
Period (.) -> Space
Semicolon (;) -> Enter
compat: (similar to other emulators' layouts, e.g. Z80, X128, XZX ...)
Shift (both) -> Caps Shift
Alt -> Symbol Shift
Back Space -> Caps Shift + '0'
Escape -> Caps Shift + '1'
- custom
- Use key bindings specified in the config file (see section 6.1)
(Cursor Types)
shifted: (default)
Left Arrow -> Caps Shift + '5'
Down Arrow -> Caps Shift + '6'
Up Arrow -> Caps Shift + '7'
Right Arrow -> Caps Shift + '8'
- raw
- Left Arrow -> '5' Down Arrow -> '6' Up Arrow -> '7' Right Arrow -> '8'
- joystick
- Left Arrow -> Kempston Left Down Arrow -> Kempston Down Up Arrow -> Kempston Up Right Arrow -> Kempston Right Keypad Ins -> Kempston Fire Keypad Del -> Kempston Fire Keypad Home -> Kempston Up + Left Keypad PgUp -> Kempston Up + Right Keypad End -> Kempston Down + Left Keypad PgDn -> Kempston Down + Right
6.3 Keys that control the emulator
All control keys are produced by pressing the Ctrl key and another key.
Ctrl-c, F10 Quit the emulator immediately
Ctrl-l, F3 Load a snapshot file; you must type the path and
filename on the terminal where you started the emulator,
e.g. 'snap/chuckie2'. The type and extension of the
file is determined automatically (.z80 or .sna).
Ctrl-t, F2 Save the current state of the emulator in a snapshot file.
Format depends on the extension (.z80 or .sna). If no
extension is given, .z80 is appended.
Ctrl-w, Ctrl-F2 Save a snapshot to a temporary file
Ctrl-e, Ctrl-F3 Restore last temporary snapshot saved with 'Ctrl-w'
Ctrl-q, F5 Reset the Spectrum
Ctrl-f Fast mode
Ctrl-n Normal speed mode
Ctrl-b Pause/Unpause emulator (you can do operations like loading
a snapshot file, etc... in paused mode too)
Ctrl-m Toggle sound on/off
Ctrl-h, F1 Print help
Ctrl-k Display (undisplay) keyboard of spectrum. See section 6.2.
Ctrl-p, F4 Play tape. Tape file must be entered on the terminal.
Optionally the starting segment can be entered;
e.g. 'tape/tape1.tap' or 'tape/tape1.tzx 13'
Ctrl-s, F7 Stop tape
Ctrl-y Toggle quick loading
Ctrl-o, F6 Pause and unpause during tapefile playing (restarts the
current segment).
Ctrl-r Record to tape file. See section 8.3.
Ctrl-\, F9 Refresh screen, reset keyboard state and
refresh colors.
Ctrl-j Toggle private colormap mode (only X)
Ctrl-comma Decrease window size (only X)
Ctrl-dot Increase window size (only X)
Ctrl-equals Skip more screen frames
Ctrl-minus Skip less screen frames
Ctrl-] Increase sound buffer size
Ctrl-[ Decrease sound buffer size
6.4 Effects of changing frame frequency and sound buffer size
ONLY READ THIS IF YOU ARE NOT TOTALLY SATISFIED WITH THE EMULATOR'S PERFORMANCE
This should be totally automatic, so I'm now programming you to do what the emulator should. (Luckily you are much easier to program)
Frame skipping determines, after how many frames the emulator displays one on the screen. There are 50 frames in one second, and normally every other frame is displayed (25 per second). If the emulator is too slow under X, increasing frame skipping can have a good effect on performance, but at the cost of poorer quality. But the interesting thing is, that increasing frame skipping may cause a worsening of both performance and of picture quality (I will not explain it here why).
Decreasing frame skipping has the opposite effect of the above.
If the emulator uses sound, but sound is not continuous, then experiment with increasing sound buffer size, and increasing frame skipping. If you are lucky you can make things a bit better. Increasing sound buffer size has also the negative effect of delaying more the sound effects.
7. Where can I get ZX Spectrum games for this emulator
On the Spectemu homepage (http://www.inf.bme.hu/~mszeredi/spectemu/) you can find a list of sites worth checking. Here are some:
http://www.void.demon.nl/spectrum.html
http://www.nvg.unit.no/sinclair/planet/
The fact is, that there were a lot of Spectrum games around on audio tapes, and some of them are really good. There were always cracked and copyable versions around, and nobody was interested in copyrights. Unfortunately the big FTP archives do not allow non free software on their servers, so I can't include any games in this distribution.
(Because Spectrums have died out, and perhaps some of the software companies do not exist any more, probably some games could be distributed freely. But I will not check on those things.)
I've included a program named 'spconv', written by Henk de Groot (hegr@ensae.ericsson.se) which can convert between snapshot file formats.
Alternatively if you have some old spectrum tapes laying around, and you are very brave, you can check out section 8.5.
8. Tape files
8.1 Loading a tape file
The emulator now supports G.A. Lunter's .TAP and Tomaz Kac's .TZX tape files. To load a file, enter
LOAD ""
to the spectrum (by pressing keys j""), then press 'Ctrl-p'. On the terminal enter the name of the tape file to load, e.g.
tape/cnamemat
The emulator will now load from the tape file 'tape/cnamemat.tzx' or 'tape/cnamemat.tap' whichever exists. Playing automatically stops at the end of the tape file. To stop loading before this press Ctrl-s.
The default extensions are '.tap' / '.tzx' or '.TAP' / '.TZX' depending on whether the entered tape file is upper or lower case.
While loading try pressing Ctrl-f, which can speed things up. After loading the file press press Ctrl-n to restore normal speed.
8.2 Quick loading of tape files
Quick loading means bypassing of the tape loading routine in the spectrum ROM, and loading of tape blocks directly into the memory. Some programs use their own tape loading routines, and in that case the tape blocks are always "slow loaded" (see above section).
Quick loading is optional and can be toggled with the 'Ctrl-y' key.
When quick loading is on, after entering 'LOAD ""' you are immediately prompted for a tapefile. If the tapefile can't be loaded, the quick loading of the first header block is cancelled, but you can still load the rest of tape by pressing 'Ctrl-p' and entering the tapefile name.
Even in quick load mode, the playing of tapes is not automatically paused, when the program doesn't load more blocks, so with '.tap' files containing multipart games, you have to pause the tape at the end of each part with 'Ctrl-o' ('.tzx' tapefiles can contain a "Stop the Tape" mark, to automatically pause playing).
8.3 Saving to a tape file
If you want to save something to a tape file using the spectrum's "SAVE" command, do the following:
- Enter 'SAVE "file"' on the spectrum
- press Ctrl-r to start the recording
- on the terminal enter the name of the tapefile to use
- press a key on the spectrum
- wait for the recording to stop
- press Ctrl-s to stop recording
If the specified tape file already exists, the newly saved segments are appended to the old tapefile.
8.4 Saving a tape file to real tape
The utility 'tapeout' enables you to save tape files (.tap and .tzx) to real tape via the soundcard. At the moment it only works on Linux, because it uses the OSS sound driver. (You can compile it for non linux systems, by adding -DNO_SOUNDCARD to CFLAGS in Makefile. Then instead of writing to the sound device, the program writes to a headerless wav file (bits: 8, sample rate: what you've given).)
You can compile 'tapeout' by entering
make tapeout
in the main directory of spectemu. The command line parameters are:
tapeout sample_rate tapefile [start_block [output_file]]
The default value for start_block is 0, for output_file it is "/dev/dsp" (or if compiled -DNO_SOUNDCARD it is "tape.out").
You can stop recording to the tape by pressing Ctrl-C.
8.5 Making a tape file from a real tape
WARNING, ONLY TRY THIS IF YOU REALLY-REALLY WANT TO!
Well it's not so bad as that, I've digitized a lot Spectrum tapes with ease, but I have the advantage of having played with tapes a lot on the real Spectrum, and of being able to modify the code which does the digitization.
First of all you must have a sound-card to do this. If you've got it, then you have a small chance of succeeding.
First get the cassette player which you used to play Spectrum tapes. Then plug it in your sound-card's 'line-in' or 'mic' inputs. Then somehow set the sound driver so that it reads things form the input in which you plugged your cassette (I use 'xmmix' the 'Motif Audio Mixer' to do this). And if you've managed to get this far, go to the directory where you want to store the tape files (remember, there will be a lot of little files: one for each little segment!), and enter the following command:
recs - 32000 | filt | spload tapefile
or
recs - 32000 | spload tapefile
(The first type worked better for me)
Where 'recs', 'filt' and 'spload' are programs found in the utils directory, and 'tapefile' is the name of the tape file without the '.spt' extension.
'.spt' tape files only exist because of historical reasons (the tape digitizing program preceeded the emulator, and also at that time I didn't know of the '.TAP' format), and now it isn't suppurted by the emulator any more. So you must convert '.spt' files to '.tap' with the utility spt2tap (in the utils directory) to use it with the emulator.
(The contents of the utils directory can be remade by changing to that directory and entering the command: 'make realclean; make')
Now you can put your favorite Spectrum cassette in the cassette player, and press the Play button.
'spload' will write a lot of information on the terminal, of which you might try to make some sense. Also you can do a 'tail -f tapefile.spt' in another terminal, to see what is happening. Again if nothing happens, then you are on your own (and most probably at first nothing will happen).
And remember that this digitizer is not better than the real Spectrum, so if you cannot load a program with a Spectrum, you'll most probably will not be able to load it with 'spload'.
Good Luck!
9. Bug reports
Please send bug reports to:
If you make any changes to the source, please mail me the 'diff -u' of the file(s) changed, and also why were the changes needed.
Please also tell me if you would like to maintain, or to continue developing spectemu.
10. Credits
Szeredi Tamas, for testing the emulator, and for helping with the 'spectkey.gif'.
Egmont Koblinger for helping to write some parts of the emulator, and for a lot of useful suggestions.
Dani Nagy and Zsazsa for helping to test the emulator.
G.A. Lunter for a very good description of the Spectrum, the undocumented features of Z80, and the '.z80' snapshot file format.
And lots of others, who sent me good ideas and modifications.