Requirements&Installation.txt

Requirements & Installation

System Requirements

Operating System
- Windows 10 / Windows 11 (64-bit)
- The application uses:
  - Windows system tray
  - WinAPI-based window behavior
  - PyQt5 desktop runtime

Hardware
- Any modern PC or laptop
- Minimum recommended resolution: 1280x720
- HiDPI displays supported:
  - 125%
  - 150%
  - 200%

Software
- Python 3.10 or newer (only if running from source)
- Or a prebuilt portable .exe release for end users


Dependencies (Source Run)

The application requires:
- PyQt5

Used by the project:
- PyQt5.QtMultimedia for extended sound playback
- standard Python library modules
- local project modules (timer.py, menu.py, dialogs.py, etc.)


Recommended Installation - Prebuilt EXE

1. Download the latest release from GitHub Releases
2. Extract the archive
3. Run:
   XTimer.exe
4. The application will start and appear in the system tray

No Python installation is required for normal end users.


Run From Source

1. Clone the repository
git clone https://github.com/End1essspace/XTimer.git
cd XTimer

2. Create and activate a virtual environment
python -m venv venv
venv\Scripts\activate

3. Install dependencies
pip install PyQt5

4. Run the application
python main.py


Portable Build

XTimer is packaged as a portable standalone Windows build.

Current packaging model:
- Nuitka
- standalone
- portable folder build

A release build contains:
- XTimer.exe
- Qt runtime files
- application resources next to the executable

Typical release structure:

XTimer/
├─ XTimer.exe
├─ icons/
├─ lang/
├─ sounds/
├─ PyQt5 / Qt runtime files
└─ required DLLs


Required Project Structure (Source)

Make sure the following files and folders exist next to main.py:

XTimer/
├─ main.py
├─ timer.py
├─ constants.py
├─ menu.py
├─ dialogs.py
├─ update_checker.py
├─ logging_config.py
├─ utils.py
├─ i18n.py
├─ winapi.py
├─ styles.py
├─ icons/
│  ├─ tray_icon.ico
│  └─ settings_icon.png
├─ lang/
│  ├─ en.json
│  └─ ru.json
├─ sounds/    (optional)
└─ README.md

Notes:
- icons/ is required for full tray/window icon behavior
- lang/ is strongly recommended for full localization behavior
- sounds/ is optional
- if some optional assets are missing, the application still falls back safely where supported


First Launch Notes

- Default language on first launch: English
- The application is designed as a floating desktop timer
- The main window does not appear in the taskbar
- The application is controlled through:
  - Right-click on the timer
  - System tray icon
  - Settings window


Update Check Model

XTimer currently uses a safe update-check system.

It can:
- check GitHub Releases for a newer version
- notify the user through the system tray
- open the release page when clicked

It does NOT:
- download updates automatically
- install updates automatically
- replace files silently

Update checks can be enabled or disabled in Settings.


Permissions & Security

- No administrator privileges required
- No services or drivers installed
- No background installer behavior
- No registry modification except standard QSettings
- No outbound activity except update checks when enabled


Troubleshooting

Tray icon not visible
- Ensure system tray is enabled in Windows settings
- Restart the application

No sound on timer finish
- Enable sound notifications in Settings
- Ensure the selected sound file exists
- Ensure the file is within allowed size/duration limits

High DPI scaling issues
- Use standard Windows display scaling
- The application supports HiDPI-aware positioning and sizing

Language file missing
- The application can still run with fallback translations
- Restore lang\en.json and lang\ru.json for full localization behavior

Icons missing
- Ensure the icons folder is present next to the executable
- Missing icons can degrade tray/window visuals