Chess Studio is a modern, high-performance chess analysis and training suite built in Python and Pygame. Designed to bridge the gap between heavy offline engines and sleek web-based GUIs, it features a highly animated interface, dynamic text-to-speech (TTS) bot personalities, and a robust hybrid-engine architecture.
Unlike standard chess GUIs, this application understands the context of the board. It dynamically triggers vocal trash-talk during blunders, draws sleek translucent MultiPV continuation arrows, and seamlessly hot-swaps between local NNUE engines (like Stockfish) and the Lichess Cloud API to protect your CPU during deep analysis.
This project is the culmination of 3-4 months of dedicated, intense development. Building a chess GUI from scratch that can handle asynchronous engine threading, spring-physics UI rendering, and real-time API fallbacks without dropping frames was a monumental challenge.
A massive thank you to the open-source chess community. This project stands on the shoulders of giants, and was heavily inspired by the incredible work done by the developers of LucasChess (for its legendary offline training depth) and En Croissant (for its beautiful, modern approach to UI and database integration).
- 🧠 Hybrid Engine Architecture: Automatically falls back to local engines during heavy Game Reviews to prevent Lichess Cloud API IP bans, while maintaining instant, zero-CPU cloud evaluations for live play.
- 📺 Broadcast-Quality UI: Features a custom spring-physics evaluation bar based on True Win Probability (WDL), fading "ghost" moves, floating evaluation bubbles, and dynamic tactical threat arrows.
- 🗣️ Reactive TTS Personalities: Play against dynamic bots (including a terrifying "Assassin" logic and a low-Elo "Martin" simulator) that vocally react to discovered checks, queen blunders, and brilliant sacrifices in real-time.
- 📖 Grandmaster Explorer: A fully integrated SQLite database explorer that asynchronously fetches master-level continuations and win rates without freezing the main event loop.
- 🎯 Guided Practice Trainer: An interactive opening trainer that uses 3-strike rules and dashed hint arrows to force you to memorize critical lines.
- 📊 Deep Game Review: Post-game analysis generates accuracy scores, categorizes moves (Brilliant, Great, Blunder, etc.), and saves annotated PGNs directly to a local profile archive.
- Note: in the source code, the feature calibrate engine has been retained which works with a terminal, this feature will be removed from the release for normal users who are not developers.
- Store and analyze your games from lichess.org and chess.com
-
Clone the repository:
git clone [https://github.com/neuroflowinfinix/Chess-Studio.git](https://github.com/neuroflowinfinix/Chess-Studio.git) cd Chess-Studio -
Install the required dependencies: Make sure you have Python 3.8+ installed.
pip install pygame chess requests matplotlib numpy joblib
(Note: Ensure you have your preferred TTS library installed if you are using the voice features).
-
Add your Chess Engine: Due to file size limits, chess engines are not included in this repository.
- Download Stockfish (or your preferred UCI engine like RubiChess).
- Place the
.exefile inside theengines/folder. - If using NNUE, place the
.nnuefile inengines/nnue/orassets/evaluationfiles/, make sure the name of .nnue file of an engine is exactly same as that of the engine .exe file.
-
Run the application:
python main.py
- Left Click: Select and move pieces.
- Right Click & Drag: Draw custom tactical arrows on the board.
- Left Click (Off-board): Clear all custom arrows.
- Arrow Keys (Left/Right): Navigate through move history.
- E: Toggle the Grandmaster Opening Explorer overlay.
- Ctrl + Z: Undo move (Takeback).
- Ctrl + F: Flip the board.
- Ctrl + S: Save the current game to PGN.
- Ctrl + R: Reset / New Game.
- H toggle: See the position heatmap in live game.
main.py: The core application loop and event handler.ui_renderer.py: Handles all Pygame drawing, animations, and the WDL evaluation bar.analysis_engine.py: Manages asynchronous communication with UCI engines and move classification.live_evaluator.py: Live-game telemetry and evaluation.popups.py: All UI modal windows (Review, Settings, Profile, etc.).database_explorer.py: SQLite logic for the GM Explorer.account_manager.py: External network status monitoring.assets/: Contains piece images, sounds, TTS voice maps, and archived PGN ledgers.engines/: Directory for your local.exeUCI chess engines.build_db.py: database builder.
Distributed under the MIT License. See LICENSE for more information.
- LucasChess & En Croissant for setting the gold standard in open-source chess software.
- python-chess for the incredibly robust board representation and UCI protocol handling.
- Lichess API for providing world-class cloud evaluation databases.
- Pygame for the rendering framework.
- PGNMentor for pgn files used in making database and .bin files for Checkmate_master bot.