🧮 Maths-Tutor-QT-V2

Maths-Tutor-QT-V2 is a desktop-based mathematics learning application built using PyQt5. It provides interactive math practice with text-to-speech, keyboard-first navigation, and multiple learning modes, with a strong focus on accessibility.

---

✨ Features

🎯 Core Features

• Multiple modes:

  • ⚡ Quickplay
  • 🎮 Game Mode
  • 🎓 Learning Mode

• Question categories:

  • Story
  • Time
  • Currency
  • Distance
  • Bell Ring (audio-based counting)
  • Arithmetic operations (Addition, Subtraction, Multiplication, Division, Percentage)

• Multiple difficulty levels

• Randomized question generation

• Excel-based custom question upload

♿ Accessibility

• Text-to-Speech using pyttsx3
• Keyboard-only navigation
• Audio feedback for questions and actions
• Screen-reader friendly UI elements

🌍 Multilingual Support

• English
• Hindi (हिंदी)
• Malayalam (മലയാളം)
• Tamil (தமிழ்)
• Arabic (عربي)
• Sanskrit (संस्कृत)

(Language selectable at startup and via settings)

---

� Getting Started

Follow these steps to set up and run Maths-Tutor-QT-V2 on your local machine.

1. Clone the Repository

Download the application source code to your computer:

git clone https://github.com/Devikavr24/Maths-Tutor-QT-V2.git
cd Maths-Tutor-QT-V2

2. Windows Setup

Prerequisites:

• Windows 10 or later
• Python 3.8+ (Ensure "Add Python to PATH" is checked during installation)

Installation Steps:

1. Open a terminal (Command Prompt or PowerShell) in the project folder.
2. Install the required Python dependencies:

   pip install -r requirements.txt

3. (Optional but Recommended) Install the offline TTS engine for robust language support:
   • Download and run the installer from the eSpeak-NG Releases Page.

Running the Application:

python main.py

---

3. 🐧 Linux Setup

System Prerequisites

Prerequisite	Purpose
espeak-ng	TTS engine — called directly via subprocess on Linux
python3-pyqt5	Qt5 GUI framework (can be installed via pip or system package)

Installation by Distro

Debian / Ubuntu / Linux Mint

# 1. Update package list
sudo apt update

# 2. Install system dependencies
sudo apt install python3 python3-pip espeak-ng python3-pyqt5

# 3. Clone the repo
git clone https://github.com/Zendalona/Maths-Tutor-QT-V2.git
cd Maths-Tutor-QT-V2

# 4. Install Python packages
pip install -r requirements.txt

# 5. Run the application
python3 main.py

Fedora / RHEL / CentOS

# 1. Install system dependencies
sudo dnf install python3 python3-pip espeak-ng python3-qt5

# 2. Clone the repo
git clone https://github.com/Zendalona/Maths-Tutor-QT-V2.git
cd Maths-Tutor-QT-V2

# 3. Install Python packages
pip install -r requirements.txt

# 4. Run the application
python3 main.py

Arch Linux / Manjaro

# 1. Install system dependencies
sudo pacman -S python python-pip espeak-ng python-pyqt5

# 2. Clone the repo
git clone https://github.com/Zendalona/Maths-Tutor-QT-V2.git
cd Maths-Tutor-QT-V2

# 3. Install Python packages
pip install -r requirements.txt

# 4. Run the application
python main.py

openSUSE

# 1. Install system dependencies
sudo zypper install python3 python3-pip espeak-ng python3-qt5

# 2. Clone the repo
git clone https://github.com/Zendalona/Maths-Tutor-QT-V2.git
cd Maths-Tutor-QT-V2

# 3. Install Python packages
pip install -r requirements.txt

# 4. Run the application
python3 main.py

🎮 How to Use

Startup Flow

1. Language selection dialog (optional “Remember my selection”)

2. Mode selection:

   • Quickplay
   • Game Mode
   • Learning Mode

3. Choose difficulty or section

4. Answer questions using the keyboard

---

⌨️ Keyboard Shortcuts

For quick navigation and control, you can use the following keyboard shortcuts:

Shortcut	Action
Ctrl + R	Repeat current question
Ctrl + ;	Decrease speech speed / Re-read slower
Alt + ;	Increase speech speed
Ctrl + Q	Quit Application
Escape	Cancel / Close Dialog (in menus)

---

🔊 Audio & Theme

• Background music with mute/unmute toggle
• Sound effects for UI interactions
• Light and Dark theme toggle
• Theme updates applied dynamically

---

📁 Project Structure

Maths-Tutor-QT-V2/
├── main.py
├── pages/
│   ├── shared_ui.py
│   ├── ques_functions.py
├── question/
│   └── loader.py
├── tts/
│   └── tts_worker.py
├── language/
│   └── language.py
├── styles/
│   ├── app.qss
│   ├── main_window.qss
│   └── language_dialog.qss
├── sounds/
├── images/
├── assets/
└── README.md

---

🧪 Custom Questions (Excel)

• Upload Excel files via the Settings menu
• Questions are processed using the question loader
• Allows extending content without modifying code

---

⚙️ Settings

Accessible from within the application:

• Difficulty level
• Language selection
• Theme toggle

All changes apply instantly.

---

🛠 Development Notes

• UI refreshes dynamically when language changes
• Text-to-Speech is stopped and reset on navigation
• Background music handled via QMediaPlayer
• Modular page-loading architecture

---

🤝 Contributing

Contributions are welcome.

Guidelines:

• Do not break accessibility
• Maintain keyboard navigation
• Avoid hard-coded language strings
• Test TTS before submitting changes

---

🗑️ Uninstall / Remove Maths Tutor

If you no longer need Maths Tutor, you can remove it using the steps below.

Windows

If you cloned the repository and ran it locally, the application is not installed system-wide.

Option 1: Using File Explorer (Recommended)

• Navigate to the folder where you cloned the project
• Delete the Maths-Tutor-QT-V2 folder

Option 2: Using Command Prompt (cmd.exe)

rmdir /s /q Maths-Tutor-QT-V2

📄 License

This project is licensed under the GNU General Public License v3.0.

---

🔗 Links

• Repository: https://github.com/Devikavr24/Maths-Tutor-QT-V2
• Issues: https://github.com/Devikavr24/Maths-Tutor-QT-V2/issues