msx-caster

MSX cassette tape toolbox — play CAS files directly to real hardware, convert between CAS and WAV with customizable audio profiles, decode tape recordings back to CAS, and manage CAS containers.

Features:

• 🎮 Direct CAS playback - Play cassette images on-the-fly without pre-conversion
• 🎛️ MSX remote control - Automated pause/resume via MSX cassette REMOTE signal
• ⚡ Fast loading - Turbo modes at 2400 and 3600 baud
• 🎵 Audio profiles - 21+ optimized presets for different scenarios (standard, fast, compact, problem-solving)
• 🎹 Flexible waveforms - Sine, square, triangle, trapezoid with configurable rise times
• 📦 CAS container tools - List (with extended info) and extract individual files
• 🎨 Interactive playback - Real-time marker display with keyboard controls
• 🔊 Low-pass filtering - Cleaner output for computer audio interfaces
• 📍 WAV markers - Embedded cue points for navigation (disable with --no-markers)
• 🔄 WAV to CAS decoding - Recover CAS containers from tape recordings with auto baud detection
• ✅ Byte-for-byte compatibility - canonical profile matches cas2wav output

Credits

msx-caster builds on the work of two foundational MSX cassette tools:

• castools by Vincent van Dam — the original cas2wav and wav2cas utilities that defined the MSX cassette format handling this project builds upon. The c2w (CAS → WAV) conversion is ported from cas2wav.

• SofaCas by Louthrax — a Windows tool for recording and playing .CAS files using Goertzel-based frequency detection. The w2c (WAV → CAS) decoder is ported from SofaCas.

Quick Start

# Clone and build
git clone https://github.com/xesco/msx-caster.git
cd msx-caster
make

# Play CAS directly to real MSX hardware (converts on-the-fly)
./cast play game.cas

# Or convert to WAV file
./cast c2w game.cas
./cast play game.wav

# Convert a tape recording back to CAS
./cast w2c tape.wav

Requirements

• Build: C11 toolchain (clang or gcc), CMake, and make
• Platforms: macOS (Apple Silicon or Intel), Linux (x86_64)

CMake is used for the build system but make provides a convenient wrapper.

Build

make              # Build cast executable (fast)
make test         # Build and run test suite
make install      # Install to /usr/local/bin (requires sudo)

After installation, use cast instead of ./cast.

Usage

Convert CAS to WAV

# Basic conversion (uses default profile)
./cast c2w game.cas

# Specify output file
./cast c2w game.cas -o output.wav

# Use specific profile (optimized presets)
./cast c2w game.cas --profile default        # Balanced for most MSX machines
./cast c2w game.cas --profile canonical      # cas2wav-compatible output
./cast c2w game.cas --profile turbo          # Fast 2400 baud loading
./cast c2w game.cas --profile conservative   # Maximum compatibility

# Custom settings
./cast c2w game.cas --baud 2400 --wave square
./cast c2w game.cas --lowpass 6000 --amplitude 0.8
./cast c2w game.cas --wave trapezoid --rise 20

Play Audio

# Play CAS directly to real MSX hardware (converts on-the-fly)
./cast play game.cas

# Choose audio profile for CAS playback
./cast play game.cas --profile default        # Balanced for most MSX machines
./cast play game.cas --profile turbo          # Fast 2400 baud loading

# Play pre-converted WAV files
./cast play game.wav
./cast play output.wav

# Interactive controls during playback:
#   Space      - Pause/Resume
#   Left/Right - Seek ±5s
#   Up/Down    - Volume ±10%
#   M          - Mute/Unmute
#   Q          - Quit

List Files and Markers

# List files in CAS container (to see file indices)
./cast list game.cas

# Show extended info with headers, sizes, and hex data
./cast list -e game.cas

# Show extended info for a single file by index (1-based)
./cast list -e -i 2 game.cas

# List cue point markers in a WAV file with timestamps
./cast list game.wav

Extract Files

# Extract all files from container (default behavior)
./cast extract game.cas

# Extract specific file by index (use list output to find index)
./cast extract game.cas --index 1

# Extract to specific directory
./cast extract game.cas --dir output/

# Overwrite existing files without prompting
./cast extract game.cas --force

# Extract with MSX-DOS disk format prefix byte
./cast extract game.cas --disk-format

Audio Profiles

# List all available profiles
./cast profiles

Available Audio Profiles (21 total)

Standard:
  canonical          Byte-for-byte match with cas2wav
  default            Balanced default for most MSX machines

Fast Loading:
  turbo              Fast loading at 2400 baud
  turbo-trim         Fast loading 2400 baud, trimmed leaders
  turbo-3x           Very fast loading at 3600 baud
  turbo-3x-trim      Very fast loading at 3600 baud, trimmed leaders

Space Saving:
  compact-balanced   Space saving with standard speed
  compact-fast       Space saving at 2400 baud
  compact-extreme    Extreme file size reduction

Problem-Solving:
  conservative       Maximum compatibility for problematic hardware
  tape-recording     Recording to physical cassette tape

Testing/Development:
  emulator           MSX emulator (openMSX, blueMSX)
  emulator-trim-raw  Emulator fast square, minimal leader
  emulator-trim-filtered  Emulator fast square, filtered
  fast-trapezoid-36k Fast loading trapezoid at 36kHz
  fast-triangle-48k  Fast loading triangle at 48kHz
  markerless-default Default signal, markers disabled
  trim-quiet-analyzer Short leader, low level, filtered

Quality:
  clean              Maximum signal quality for real hardware
  vintage-tape       Emulate authentic 1980s cassette sound
  radio              Optimized for streaming/broadcast

# Show details for specific profile
./cast profiles default

Profile: default

Category:    Standard
Description: Balanced default for most MSX machines

Use Case:
  Starting point for most MSX hardware, computer-to-MSX playback

Audio Settings:
  Waveform:      sine
  Baud rate:     1200 baud
  Sample rate:   43200 Hz
  Amplitude:     127
  Leader timing: 2.0s / 1.0s (long/short)
  Low-pass:      disabled

Rationale:
  Sine wave for reliable real MSX hardware playback, amplitude 127
  matches cas2wav reference implementation

Convert WAV to CAS

Decode a tape recording or previously generated WAV back into a CAS container. The decoder auto-detects baud rate and handles standard (1200 baud) and turbo recordings.

# Basic conversion (output file auto-named from input)
./cast w2c tape.wav

# Specify output file
./cast w2c tape.wav -o game.cas

# Amplify a weak or quiet recording
./cast w2c tape.wav --volume 2.0

# Relax quality threshold for noisy tapes
./cast w2c noisy.wav --header-quality 50.0

# Tune baud rate search range
./cast w2c slow.wav --min-bauds 300 --max-bauds 2000

Advanced options:

Option	Default	Description
-V, --volume <factor>	1.0	Input signal amplification
-s, --silence <ratio>	0.1	Silence detection threshold (0.0–1.0)
-H, --header-len <sec>	0.5	Header scan duration in seconds
-B, --header-block <sec>	0.2	Frequency analysis block duration
-Q, --header-quality <val>	100.0	Header quality threshold (lower = more lenient)
-r, --resolution <val>	10.0	Frequency scan precision
-w, --scan-ratio <val>	0.9	Coverage of frequency range
-e, --end-sens <val>	0.125	Header end detection sensitivity
-m, --min-bauds <hz>	500.0	Minimum expected baud rate
-M, --max-bauds <hz>	4000.0	Maximum expected baud rate
-p, --phase-adj <val>	0.5	Phase-lock loop adjustment coefficient

Remote Control

Automate multi-stage game loading - let your MSX control playback via its cassette REMOTE signal (connected to your computer's audio input: mic/line-in). The computer detects when the MSX pauses/resumes the tape motor and responds automatically.

# List available audio input devices
./cast remote devices

# Test/monitor REMOTE signal in real-time
./cast remote test

# Play with remote control enabled
./cast play game.wav --remote
./cast play game.cas --remote --profile default

# Play with remote control using a specific input device
./cast play game.wav --remote --remote-device 1

Once configured, the MSX can automatically pause/resume playback during multi-stage loading (e.g., two-sided tapes, level loads) without manual intervention. See config/remote.conf.example for configuration options.

Advanced

Generate Profile Samples

To generate sample WAV files for all audio profiles:

make profile-wavs

Outputs appear in test/profile_wavs/ (git-ignored).

Contributing

See AGENTS.md for development guidelines and build system details.