ZX Spectrum TAP Video Capture

This project provides tools to automatically launch the FUSE ZX Spectrum emulator, load TAP files, and capture video of programs running. By default, it emulates the Timex/Sinclair 2068 computer.

Features

• Automatic launching of FUSE emulator with TAP files
• Video capture of running programs
• Support for multiple platforms (macOS, Linux, Windows)
• Window-specific capture to record only the emulator window
• Audio capture support
• Multiple Spectrum model support
• Configurable capture duration and frame rate

Requirements

• Python 3.6+
• FUSE (Free Unix Spectrum Emulator)
• FFmpeg

Installation

macOS

brew install fuse-emulator ffmpeg

Linux (Debian/Ubuntu)

sudo apt-get install fuse-emulator-gtk ffmpeg
# Optional for window capture:
sudo apt-get install xdotool xwininfo

Linux (Fedora)

sudo dnf install fuse-emulator ffmpeg
# Optional for window capture:
sudo dnf install xdotool xorg-x11-utils

Usage

Basic Usage

Capture 60 seconds of a TAP file running on Timex/Sinclair 2068:

./capture_zx_spectrum.py game.tap

Advanced Usage

The advanced script provides more options:

# Capture 2 minutes with window-only capture
./capture_spectrum_advanced.py game.tap -o gameplay.mp4 -d 120 --window

# Capture with audio on a Spectrum 128
./capture_spectrum_advanced.py demo.tap --audio --machine 128

# Auto-start tape loading and capture
./capture_spectrum_advanced.py program.tap --auto-start

Command Line Options

• tap_file: Path to the TAP file to load (required)
• -o, --output: Output video filename (default: capture.mp4)
• -d, --duration: Recording duration in seconds (default: 60)
• -f, --fps: Video frame rate (default: 30)
• --window: Try to capture only the FUSE window (advanced script)
• --audio: Include audio in the capture (advanced script)
• --machine: Spectrum model to emulate (advanced script)
• --auto-start: Automatically start loading the tape
• --capture-delay: Delay before starting capture in seconds

Supported Spectrum Models

• 16 (ZX Spectrum 16K)
• 48 (ZX Spectrum 48K)
• 128 (ZX Spectrum 128K)
• plus2 (ZX Spectrum +2)
• plus2a (ZX Spectrum +2A)
• plus3 (ZX Spectrum +3)
• plus3e (ZX Spectrum +3e)
• se (ZX Spectrum SE)
• tc2048 (Timex Computer 2048)
• tc2068 (Timex Computer 2068)
• ts2068 (Timex/Sinclair 2068) - default
• pentagon (Pentagon)

About the Timex/Sinclair 2068

The TS2068 is used as the default machine because:

• Enhanced graphics capabilities (512×192 hi-res mode)
• 48K RAM standard
• Better compatibility with many programs
• Extended BASIC commands
• Built-in joystick ports

To use a different machine model with the advanced script:

./capture_spectrum_advanced.py game.tap --machine 48  # Use ZX Spectrum 48K

How It Works

1. The script launches FUSE with the specified TAP file
2. Waits for the emulator to start (configurable delay)
3. Begins FFmpeg screen capture
4. Records for the specified duration
5. Saves the video and closes the emulator

Platform-Specific Notes

macOS

• Uses avfoundation for screen capture
• Window detection via AppleScript
• May require screen recording permissions

Linux

• Uses x11grab for screen capture
• Window detection via xwininfo
• Requires X11 display server

Windows

• Uses gdigrab for screen capture
• Full desktop capture only

Tips

1. Performance: Lower the FPS to 15-20 for better performance on slower systems
2. File Size: Longer captures create larger files. Consider using -crf values between 18-28
3. Window Capture: Position the FUSE window before starting capture for best results
4. Auto-start: Some programs may need manual intervention to start loading

Troubleshooting

"FFmpeg error" during capture

• Check screen recording permissions (macOS)
• Ensure display is available (Linux with X11)
• Try without --window flag

FUSE window not found

• Make sure FUSE is fully loaded before capture starts
• Increase --capture-delay value
• Use full screen capture instead of window capture

No audio in capture

• Audio capture requires additional system permissions
• Check FFmpeg audio input devices with ffmpeg -f avfoundation -list_devices true -i ""

License

GNU General Public License v3.0