[ENG]

⏱️ XTimer

XTimer is a compact floating timer for Windows, built to stay visible, predictable, and easy to control. It can sit near the taskbar, snap to any screen edge, switch orientation automatically, and remain accessible through the system tray without cluttering your desktop.

Perfect for work, gaming, streaming, studying, cooking, or any workflow where time must remain in sight.

✨ Features

Floating timer UI

• Frameless and lightweight window
• Hidden from the taskbar
• Designed for always-visible desktop usage
• Controlled through timer surface + tray menu

Smart snapping & orientation

• Horizontal and vertical timer modes
• Automatic orientation switch when snapped to screen edges
• Works near top / bottom / left / right screen sides
• HiDPI-aware positioning and sizing

Appearance customization

• Dark and Light themes
• Custom progress bar color
• User-selected font family
• Separate font size for:
  • UI elements
  • timer text

Time control

• Count-up and count-down modes
• Quick preset menu
• User-editable custom presets
• Auto-start or auto-pause behavior when adding time

System tray integration

• Show / Hide timer
• Open Settings
• Exit application
• Dynamic tray tooltip
• Controlled degraded mode if tray is unavailable

Alerts

• Blinking border animation on timer completion
• Sound notification support:
  • .wav via QSound
  • .mp3 / .ogg / .flac / .m4a via QMediaPlayer
• Safe limits for sound file size and duration

Update check

• Manual and scheduled update checks
• GitHub Releases-based version check
• Tray notification when a new version is available
• Click notification → open release page
• For safety, XTimer does not download or install updates automatically

Localization

• English and Russian languages
• Language persistence between launches
• Safe fallback translation system

Persistence

• Settings and presets are stored automatically
• Uses native QSettings
• No manual config file editing required

📥 Installation

Recommended — Prebuilt EXE

1. Download the latest release
2. Extract the archive
3. Run:

XTimer.exe

4. The application will appear in the system tray

No Python installation is required for end users.

🛠 Run from Source

git clone https://github.com/End1essspace/XTimer.git
cd XTimer
python -m venv .venv
.venv\Scripts\activate
pip install PyQt5
python main.py

📦 Portable Build

XTimer can be packaged as a portable standalone Windows build.

Current packaging target:

• Nuitka
• standalone
• portable folder build

This means the release build contains:

• XTimer.exe
• required Qt runtime files
• icons/
• lang/
• sounds/

The application is designed so runtime assets are resolved relative to the executable directory.

⚙️ Requirements

OS

• Windows 10 / Windows 11 (64-bit)

Hardware

• Any modern PC or laptop
• HiDPI displays supported

Python

• Python 3.10+ for source execution

Dependencies

• PyQt5
• PyQt5.QtMultimedia for extended sound playback

🔧 Settings

From the Settings window you can:

• Enable / disable Always on Top

• Minimize to tray on start

• Choose theme (Dark / Light)

• Change progress bar color

• Select font family

• Configure UI font size

• Configure timer font size

• Switch timer direction:

  • Count Up
  • Count Down

• Configure alerts:

  • border blinking
  • sound file

• Manage quick presets

• Enable / disable scheduled update checks

• Change application language

📦 Update System

XTimer currently uses a safe update-check model.

It can:

• check GitHub Releases for a newer version
• notify the user through the tray
• open the release page when clicked

It does not:

• auto-download updates
• auto-install updates
• replace application files silently

This behavior is intentional for stability and safety.

🗂 Project Structure

XTimer/
├─ icons/                    # App and tray icons
├─ lang/                     # Localization files
├─ sounds/                   # Optional sound files
├─ main.py                   # Entry point
├─ timer.py                  # Core timer logic and rendering
├─ menu.py                   # Preset/context menu UI
├─ dialogs.py                # Settings dialog
├─ i18n.py                   # Localization system
├─ utils.py                  # Settings and presets helpers
├─ update_checker.py         # Update check logic
├─ logging_config.py         # Logging setup and exception wrapper
├─ winapi.py                 # Windows-specific helpers
├─ constants.py              # Constants, settings keys, runtime paths
├─ styles.py                 # Settings window stylesheets
├─ README.md
├─ CHANGELOG.md
└─ LICENSE

📝 License

This project is distributed under the MIT License.

💡 Author

XCON | RX Telegram: @End1essspace GitHub: End1essspace

---

[RUS]

⏱️ XTimer

XTimer — это компактный плавающий таймер для Windows, созданный как предсказуемый и удобный desktop-инструмент, который всегда остаётся под рукой. Он может располагаться рядом с панелью задач, прилипать к любому краю экрана, автоматически менять ориентацию и управляться через системный трей, не засоряя рабочее пространство.

Подходит для работы, игр, стриминга, учёбы, готовки и любых задач, где время должно постоянно оставаться в поле зрения.

✨ Возможности

Плавающий интерфейс таймера

• Безрамочное и лёгкое окно
• Не отображается в панели задач
• Рассчитан на постоянное присутствие на рабочем столе
• Управляется через сам таймер и меню в трее

Умное прилипание и ориентация

• Горизонтальный и вертикальный режимы
• Автоматическая смена ориентации при прилипании к краям экрана
• Корректная работа у верхней / нижней / левой / правой грани
• Поддержка HiDPI и масштабирования

Настраиваемый внешний вид

• Тёмная и светлая темы

• Пользовательский цвет прогресс-бара

• Выбор семейства шрифта

• Раздельный размер шрифта для:

  • интерфейса
  • текста таймера

Управление временем

• Режимы отсчёта вверх и вниз

• Быстрое меню пресетов

• Редактируемые пользовательские пресеты

• Поведение при добавлении времени:

  • автостарт
  • автопауза

Интеграция с системным треем

• Показать / Скрыть таймер
• Открыть настройки
• Выйти из приложения
• Динамический tooltip в трее
• Controlled degraded mode, если system tray недоступен

Оповещения

• Мигание рамки по завершении таймера

• Поддержка звуков:

  • .wav через QSound
  • .mp3 / .ogg / .flac / .m4a через QMediaPlayer

• Безопасные ограничения на размер и длительность звукового файла

Проверка обновлений

• Ручная и периодическая проверка обновлений
• Проверка версий через GitHub Releases
• Уведомление в трее, если найден новый релиз
• Нажатие по уведомлению открывает страницу релиза
• В целях безопасности XTimer не загружает и не устанавливает обновления автоматически

Локализация

• Английский и русский языки
• Сохранение выбранного языка между запусками
• Надёжная fallback-система переводов

Сохранение состояния

• Настройки и пресеты сохраняются автоматически
• Используется стандартный QSettings
• Ручное редактирование конфигов не требуется

📥 Установка

Рекомендуемый способ — готовый EXE

1. Скачайте последний релиз
2. Распакуйте архив
3. Запустите:

XTimer.exe

4. Приложение появится в системном трее

Для обычного пользователя Python не требуется.

🛠 Запуск из исходников

git clone https://github.com/End1essspace/XTimer.git
cd XTimer
python -m venv .venv
.venv\Scripts\activate
pip install PyQt5
python main.py

📦 Portable Build

XTimer может собираться как portable standalone build для Windows.

Текущий packaging target:

• Nuitka
• standalone
• portable folder build

Это означает, что release-папка содержит:

• XTimer.exe
• необходимые Qt runtime-файлы
• icons/
• lang/
• sounds/

Приложение спроектировано так, чтобы runtime-ресурсы искались относительно каталога рядом с исполняемым файлом.

⚙️ Требования

ОС

• Windows 10 / Windows 11 (64-bit)

Железо

• Любой современный ПК или ноутбук
• Поддерживаются HiDPI-дисплеи

Python

• Python 3.10+ для запуска из исходников

Зависимости

• PyQt5
• PyQt5.QtMultimedia для расширенного воспроизведения звука

🔧 Настройки

В окне Settings можно:

• включить / отключить Always on Top

• сворачивать таймер в трей при старте

• выбрать тему (Dark / Light)

• изменить цвет прогресс-бара

• выбрать семейство шрифта

• настроить размер шрифта интерфейса

• настроить размер шрифта таймера

• выбрать направление таймера:

  • Count Up
  • Count Down

• настроить оповещения:

  • мигание рамки
  • звуковой файл

• управлять пресетами

• включить / отключить периодическую проверку обновлений

• сменить язык приложения

📦 Система обновлений

Сейчас XTimer использует безопасную модель проверки обновлений.

Он умеет:

• проверять GitHub Releases на наличие новой версии
• показывать уведомление в системном трее
• открывать страницу релиза по нажатию

Он не:

• скачивает обновления автоматически
• устанавливает их автоматически
• заменяет файлы приложения в фоне

Такое поведение выбрано осознанно ради стабильности и безопасности.

🗂 Структура проекта

XTimer/
├─ icons/                    # Иконки приложения и трея
├─ lang/                     # Файлы локализации
├─ sounds/                   # Необязательные звуки
├─ main.py                   # Точка входа
├─ timer.py                  # Основная логика и отрисовка таймера
├─ menu.py                   # UI меню пресетов
├─ dialogs.py                # Окно настроек
├─ i18n.py                   # Система локализации
├─ utils.py                  # Работа с настройками и пресетами
├─ update_checker.py         # Логика проверки обновлений
├─ logging_config.py         # Логирование и wrapper исключений
├─ winapi.py                 # Windows-специфичные helper-функции
├─ constants.py              # Константы, ключи настроек, runtime-пути
├─ styles.py                 # Стили окна настроек
├─ README.md
├─ CHANGELOG.md
└─ LICENSE

📝 Лицензия

Проект распространяется под лицензией MIT.

💡 Автор

XCON | RX Telegram: @End1essspace GitHub: End1essspace