seppedl
19d2721ff2
Configure Piper TTS synthesis via environment variables (speaker_id, length_scale, noise_scale, noise_w_scale, volume) loaded from .env with python-dotenv. Includes .env.example as reference template. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The Hitchhiker's Guide to the Galaxy
A Python text adventure engine for the classic 1984 Infocom interactive fiction game, built from the original ZIL source code. The long-term goal is an accessible version for blind players via TTS/STT.
Requirements
- Python 3.12+
- uv
Install & Run
# Clone the repo
git clone https://gitea.smashconsult.be/seppedl/h2g2.git
cd h2g2
# Install dependencies and run
uv run h2g2
Or install it into an environment:
uv pip install -e .
h2g2
You can also run it directly as a module without installing:
uv run python -m h2g2.main
Audio features
Text-to-speech (TTS)
The game can read all output aloud using Piper, a fast offline TTS engine. A British English voice model is included in the repo.
uv run h2g2 --audio
Use --voice /path/to/model.onnx to use a different Piper voice model.
Speech-to-text (STT)
You can play the game hands-free using voice input powered by Vosk, a lightweight offline speech recognition engine. The Vosk model (~50 MB) downloads automatically on first use.
uv run h2g2 --stt
Use --stt-model /path/to/vosk-model/ to use a different Vosk model.
Combine both flags for full voice interaction:
uv run h2g2 --audio --stt
Audio prerequisites
STT requires PortAudio for microphone access. Install the system library for your platform before running with --stt:
Linux (Debian/Ubuntu):
sudo apt install libportaudio2 portaudio19-dev
macOS:
brew install portaudio
Windows:
PyAudio ships with PortAudio bundled on Windows, so no extra system package is needed. If you run into build issues, install a prebuilt wheel:
uv pip install pipwin
pipwin install pyaudio
After installing the system dependency, sync the Python packages:
uv sync
What's playable
The Earth opening sequence: wake up in your bedroom, find your gown and aspirin, make your way downstairs, head to the pub, and meet Ford Prefect.
Project structure
h2g2/
engine/ # Core game engine (parser, object model, game loop)
content/ # Game content (rooms, objects, puzzles)
main.py # Entry point
*.zil # Original ZIL source code (Infocom, 1984)
docs/ # Original game manuals, maps, and story file (.z5)