[ENG]

⏱️ XTimer

XTimer is a compact, highly customizable floating timer for Windows, designed to stay always visible on your screen — near the taskbar or snapped to any screen edge. Perfect for work, gaming, streaming, studying, cooking, or any task where precise time tracking must always be in sight.

---

✨ Features

• Floating always-on-top timer

  • Frameless, lightweight, non-intrusive
  • Hidden from taskbar, controlled via tray

• Smart orientation & snapping

  • Horizontal or vertical layout
  • Automatically switches orientation when snapped to screen edges
  • DPI-safe (fully supports 125% / 150% scaling)

• Customizable appearance

  • Dark / Light themes
  • Custom progress bar color
  • User-selected font family
  • Separate font sizes for UI and timer text

• Advanced time control

  • Count-up and count-down modes
  • Context menu with quick presets (1 second → multiple hours)
  • Fully customizable user presets
  • Auto-start or auto-pause behavior when adding time

• System tray integration

  • Show / Hide timer
  • Open settings
  • Exit application
  • Tray tooltip updates dynamically

• Notifications & alerts

  • Flashing border animation on completion

  • Sound notifications:

    • .wav via QSound
    • .mp3 / .ogg / .flac / .m4a via QMediaPlayer

  • File size and duration protection (anti-abuse)

• Automatic updates

  • Primary updates from your own server (ZIP)
  • Fallback to GitHub Releases
  • Clickable tray notifications
  • Configurable update interval
  • Enable / disable auto-update

• Internationalization (i18n)

  • English and Russian languages
  • Language persistence
  • Safe fallback system
  • Default language: English

• State persistence

  • All settings and presets are saved between runs
  • Uses native QSettings (no manual config files)

📥 Installation

Recommended (EXE)

1. Download the latest release from GitHub Releases

2. Extract if needed

3. Run:

   XTimer.exe
   

4. The app will appear in the system tray

No Python or additional setup required.

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

⚙️ Requirements

• OS: Windows 10 / 11 (64-bit)
• Python: 3.10+ (only if running from source)
• Dependencies: PyQt5
• Display: Any resolution, HiDPI supported

🔧 Settings

From the Settings window you can:

• Enable / disable Always on Top

• Minimize to tray on start

• Select theme (dark / light)

• Change progress bar color

• Configure fonts and sizes

• Switch count direction (up / down)

• Configure alerts:

  • Border blinking
  • Sound file and volume

• Manage time presets

• Enable / configure auto-updates

• Change application language

📦 Auto-Updates

XTimer can:

• Check for updates from your own server (SERVER_UPDATE_URL)
• Fall back to GitHub Releases automatically
• Notify via system tray
• Install server updates automatically (ZIP)
• Open GitHub release page on click

🗂 Project Structure

XTimer/
├─ icons/              # App and tray icons
├─ sounds/             # Optional notification sounds
├─ lang/               # Localization files (en.json, ru.json)
├─ main.py             # Entry point
├─ timer.py            # Core timer logic and rendering
├─ menu.py             # Context menu UI
├─ dialogs.py          # Settings dialog
├─ i18n.py             # Localization system
├─ utils.py            # Presets & settings helpers
├─ update_checker.py   # Auto-update logic
├─ logging_config.py   # Centralized logging
├─ winapi.py           # WinAPI helpers
├─ constants.py        # Constants and paths
└─ README.md

📝 License

This project is licensed under the MIT License.

💡 Author

XCON | RX TG: @End1essspace GitHub: End1essspace

---

[RUS]

⏱ XTimer

XTimer — это компактный, гибко настраиваемый плавающий таймер для Windows, созданный для того, чтобы всегда оставаться на виду — рядом с панелью задач или «прилипшим» к любому краю экрана. Идеально подходит для работы, игр, стриминга, учёбы, готовки и любых задач, где важен постоянный и наглядный контроль времени.

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

• Плавающий таймер поверх всех окон

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

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

  • Горизонтальный и вертикальный режимы
  • Автоматическое переключение ориентации при перемещении к краям экрана
  • Полная поддержка HiDPI (125% / 150% масштабирование)

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

  • Тёмная / светлая тема
  • Пользовательский цвет прогресс-бара
  • Выбор семейства шрифтов
  • Раздельные размеры шрифтов для интерфейса и текста таймера

• Расширенное управление временем

  • Режимы отсчёта вверх и вниз
  • Контекстное меню с быстрыми пресетами (от 1 секунды до нескольких часов)
  • Полностью настраиваемые пользовательские пресеты
  • Поведение при добавлении времени: автостарт или автопауза

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

  • Показать / скрыть таймер
  • Открыть окно настроек
  • Выход из приложения
  • Динамическое обновление подсказок трея

• Оповещения и уведомления

  • Анимация мигающей рамки по завершении таймера

  • Звуковые уведомления:

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

  • Защита от злоупотреблений (ограничения по размеру и длительности файлов)

• Автоматические обновления

  • Основной источник — ваш собственный сервер (ZIP-обновления)
  • Резервная проверка через GitHub Releases
  • Уведомления через системный трей с возможностью клика
  • Настраиваемый интервал проверки обновлений
  • Возможность полностью отключить автообновление

• Локализация (i18n)

  • Поддержка английского и русского языков
  • Сохранение выбранного языка между запусками
  • Надёжный fallback-механизм переводов
  • Язык по умолчанию — English

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

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

📥 Установка

Рекомендуемый способ (EXE)

1. Скачайте последнюю версию из GitHub Releases

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

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

• Операционная система: Windows 10 / Windows 11 (64-bit)
• Python: 3.10+ (только при запуске из исходников)
• Зависимости: PyQt5
• Экран: любое разрешение, полная поддержка HiDPI

🔧 Настройки

В окне настроек вы можете:

• Включить / отключить режим «Всегда поверх окон»

• Сворачивать приложение в трей при запуске

• Выбрать тему оформления (тёмная / светлая)

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

• Настроить шрифты и их размеры

• Выбрать направление отсчёта времени (вверх / вниз)

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

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

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

• Включить и настроить автообновление

• Сменить язык интерфейса

📦 Автообновления

XTimer умеет:

• Проверять обновления с вашего сервера (SERVER_UPDATE_URL)
• Автоматически переключаться на GitHub Releases, если сервер недоступен
• Показывать уведомления через системный трей
• Автоматически устанавливать серверные ZIP-обновления
• Открывать страницу релиза GitHub по клику

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

XTimer/
├─ icons/              # Иконки приложения и трея
├─ sounds/             # Необязательные звуки оповещений
├─ lang/               # Файлы локализации (en.json, ru.json)
├─ main.py             # Точка входа
├─ timer.py            # Основная логика и отрисовка таймера
├─ menu.py             # UI контекстного меню
├─ dialogs.py          # Окно настроек
├─ i18n.py             # Система локализации
├─ utils.py            # Работа с пресетами и настройками
├─ update_checker.py   # Логика автообновлений
├─ logging_config.py   # Централизованное логирование
├─ winapi.py           # Вспомогательные функции WinAPI
├─ constants.py        # Константы и пути
└─ README.md

📝 Лицензия

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

💡 Автор

XCON | RX TG: @End1essspace GitHub: End1essspace