Command-line interface for engine-sim audio generation.

This tool allows you to generate high-quality engine audio from command line with real-time playback, WAV export, and professional-grade audio quality.

WAV export works on all platforms regardless of audio hardware support.

• ✅ Real-time Audio Playback - Hear engine sounds as they're generated (macOS)
• ✅ WAV Export - Render high-quality engine audio to WAV files
• ✅ Sine Wave Test Mode - Test audio pipeline with clean sine waves
• ✅ Engine Configuration Support - Load any .mr engine configuration file
• ✅ Real-time Statistics - Monitor RPM, load, exhaust flow, etc.
• ✅ Crackle-Free Audio - Professional-quality audio output
• ✅ Audio Strategies - Choose between sync-pull (on-demand) or threaded (buffered) rendering

# Clone the repository (includes engine-sim-bridge submodule)
git clone --recursive https://github.com/danieljsinclair/engine-sim-cli.git
cd engine-sim-cli

# Build the application
make

# Run with default engine (real-time playback)
./build/engine-sim-cli --default-engine --rpm 2000 --play

# Run with sine wave test
./build/engine-sim-cli --sine --rpm 2000 --play

# Export audio to WAV file
./build/engine-sim-cli --default-engine --rpm 3000 --output engine.wav --duration 5

• macOS only — Linux and Windows builds are currently blocked (no audio hardware provider)
• CMake 3.20 or higher
• C++17 compatible compiler (Clang/AppleClang)
• macOS: AudioUnit framework (built-in, no extra install needed)

# Install build tools
brew install cmake bison flex boost

For ESP32-S3 target with I2S audio output:

# Install ESP-IDF via EIM (Espressif Installation Manager)
brew tap espressif/eim
brew install eim
eim install          # installs ESP-IDF and toolchain

# Build firmware
make esp32

# Flash to connected ESP32-S3
make deploy_esp32

# Flash + serial monitor
make run_esp32

Hardware: ESP32-S3 DevKit + MAX98357A I2S amp. Wiring: GPIO 4=BCLK, GPIO 5=LRCLK, GPIO 6=DIN, GND, 3V3.

# Play default engine at 2000 RPM
./build/engine-sim-cli --default-engine --rpm 2000 --play --duration 10

# Play sine wave test at 2000 RPM
./build/engine-sim-cli --sine --rpm 2000 --play --duration 10

# Use custom engine configuration
./build/engine-sim-cli --config path/to/engine.mr --rpm 3000 --play --duration 5

# Interactive mode with keyboard control
./build/engine-sim-cli --default-engine --interactive --play

# Export to WAV file
./build/engine-sim-cli --default-engine --rpm 2000 --output engine.wav --duration 5

# Export with custom config
./build/engine-sim-cli --config assets/engines/chevrolet/engine_03_for_e1.mr --rpm 3000 --output my_engine.wav --duration 10

# Real-time playback of default engine (threaded mode - recommended)
./build/engine-sim-cli --default-engine --rpm 2000 --play --threaded

# Real-time playback with sine wave test
./build/engine-sim-cli --sine --rpm 1000 --play --duration 20

# Export 10 seconds of audio to WAV
./build/engine-sim-cli --default-engine --rpm 3000 --output engine.wav --duration 10

# Use custom engine configuration
./build/engine-sim-cli --config my_engine.mr --rpm 1500 --output my_engine.wav --duration 5

# Lower physics frequency for faster processing (reduces CPU load)
./build/engine-sim-cli --default-engine --rpm 3000 --play --sim-freq 5000

The CLI tool provides a clean command-line interface to the engine-sim audio generation library:

1. Initialization - Set up simulator with appropriate audio parameters
2. Configuration - Load engine .mr file or use default
3. Audio Pipeline - Process engine simulation through audio synthesizer
4. Output - Either stream to audio hardware (macOS AudioUnit) or write to WAV file

threaded (default): Pre-fills audio buffer, runs physics in separate thread

• ✅ Reliable, GUI model
• ✅ May work better on some platforms

sync-pull: Renders on-demand in audio callback

• ✅ Simpler, synchronous
• ✅ Default

This tool uses the same .mr format as the main engine-sim project. You can find example configurations in engine-sim repository.

See V8_ENGINE_GUIDE.md for detailed instructions on running V8 engine configurations like Ferrari F136 and GM LS.

The CLI tool depends on the engine-sim-bridge submodule which wraps the core engine-sim library:

• engine-sim - Core engine simulation library
• macOS: CoreAudio / AudioUnit framework (built-in)
• iOS: AVAudioEngine (see escli-ios/)

The bridge provides a platform-agnostic IAudioHardwareProvider interface. New hardware targets (ESP32, Android) need only implement this interface — the factory and build system stubs are already in place.

The bridge submodule handles all audio rendering and engine simulation logic. The CLI simply provides configuration, presentation, and user interaction layers.

See LICENSE file for details.

Contributions are welcome! Please feel free to submit a Pull Request.

• Audio on macOS uses CoreAudio/AudioUnit for real-time playback
• iOS uses AVAudioEngine (see escli-ios/)
• Linux and Windows are not currently supported — the CMake build will error with a clear message
• WAV export works on any platform that can compile the project
• Adding a new hardware target requires implementing IAudioHardwareProvider in engine-sim-bridge and registering it in AudioHardwareProviderFactory
• See V8_ENGINE_GUIDE.md for V8 engine configuration details