Voice-Controlled StarCraft II
Speak commands. The bot handles the rest.
SC2 Ultra lets you play StarCraft II using natural language voice commands while the bot handles micro and automation. All three races supported: Zerg, Protoss, and Terran.
- Voice Control - Hold push-to-talk and speak: "build 5 drones", "attack their natural"
- Offline Speech Recognition - Local Whisper AI, no internet required
- Smart Micro - Auto focus fire, spell casting, kiting, and splitting
- All Three Races - Full Zerg, Protoss, and Terran support
- Control Groups - Assign and command unit groups by voice
- Learning Vocabulary - Teaches itself your pronunciation over time
- Online Play - Play against anyone on Battle.net
- StarCraft II (free-to-play version works)
- Python 3.10 or 3.11
- macOS, Windows, or Linux
The free-to-play Starter Edition has everything you need.
- Install the Battle.net launcher
- Install StarCraft II from the game library
- Launch SC2 at least once to complete setup
On Linux, use the Lutris installer and set SC2PATH to your install directory.
git clone --recursive https://github.com/nchudleigh/sc2-ultra.git
cd sc2-ultra
./install.shgit clone --recursive https://github.com/nchudleigh/sc2-ultra.git
cd sc2-ultra
python3.11 -m venv .venv
source .venv/bin/activate
# Core
pip install -e .
# Voice support (optional, ~500MB for Whisper model)
pip install -e ".[voice]"macOS Voice Setup
Grant accessibility permissions for push-to-talk:
System Preferences → Security & Privacy → Privacy → Accessibility → Add your terminal app
source .venv/bin/activate
./voice.sh # Default: Zerg
./voice.sh -r protoss # Play as Protoss
./voice.sh -r terran # Play as Terran
./voice.sh --ptt-key f1 # Different push-to-talk key
./voice.sh --model medium # More accurate speech modelControls: Hold SHIFT (default) and speak your command. Release to execute. Press ESC to stop.
./play.sh # Type commands instead of speaking
./play.sh -r protoss # Play as different race./online.sh # Play on Battle.net| Category | Examples |
|---|---|
| Build Units | "build 5 drones", "make zerglings", "warp in stalkers", "train marines" |
| Buildings | "build a spawning pool", "make a gateway", "build barracks" |
| Army | "attack their natural", "defend", "retreat", "move army to center" |
| Control Groups | "add army to group 1", "select group 1", "group 1 attack" |
| Research | "research zergling speed", "get stim", "research warp gate" |
| Spells | "psi storm", "emp", "fungal", "blink back", "siege up" |
| Micro | "split", "burrow", "unburrow" |
If Whisper mishears a word, type the correction and it learns for next time:
Voice heard: "build a blorfnax"
Unknown: "blorfnax"
Type correction: roach warren
✓ Saved: "blorfnax" → "roach warren"
Corrections are saved to ~/.sc2-ultra/vocabulary.json.
shift (default) · ctrl · alt · caps_lock · f1–f12 · mouse4 / mouse5 (Windows)
| Model | Size | Speed | Accuracy |
|---|---|---|---|
| tiny | 75 MB | Fastest | Basic |
| base | 140 MB | Fast | Good |
| small | 460 MB | Medium | Better |
| medium | 1.5 GB | Slow | Best |
sc2-ultra/
├── bot/ # Bot core
│ ├── base_bot.py # Shared bot logic
│ ├── zerg_bot.py # Zerg race
│ ├── protoss_bot.py # Protoss race
│ ├── terran_bot.py # Terran race
│ ├── nlp.py # Natural language parser
│ ├── voice.py # Voice input (Whisper)
│ └── vocabulary.py # User corrections
├── sharpy-sc2/ # SC2 framework (submodule)
├── voice.sh # Voice control launcher
├── play.sh # Text control launcher
├── online.sh # Online play launcher
├── run.py # Main entry point
└── install.sh # Installer
| Problem | Solution |
|---|---|
| Voice not responding | Check accessibility permissions (macOS). Try ./voice.sh --ptt-key f1 |
| Commands not recognized | Speak clearly. Try ./voice.sh --model medium. Type corrections to teach vocabulary |
| SC2 not launching | Make sure StarCraft II is installed. Try running SC2 manually first, then use --attach mode |
Contributions welcome! Please open an issue or PR.
- python-sc2 - SC2 API client
- sharpy-sc2 - Bot framework
- faster-whisper - Speech recognition