A lightweight, modern, and beautiful timer application for your desktop.
- Why TimeRing?
- Features
- Quick Start
- Usage Guide
- Managing Active Timers
- Timer States & Visual Indicators
- Active Timer Block
- Settings & Customization
- Advanced Configuration
- Platform Compatibility
- Contributing
- Roadmap
- Support
- License
- Author
- Acknowledgments
TimeRing transforms how you manage time on your desktop. Whether you're following the Pomodoro Technique, timing cooking recipes, or managing multiple work sessions, TimeRing provides an intuitive and powerful solution that stays out of your way while keeping you on track.
| 🍅 Pomodoro Technique practitioners |
👨💻 Developers managing sprint tasks |
🍳 Cooking enthusiasts |
📚 Students using time-blocking |
🏃♂️ Fitness interval training |
|
|
Install from GitHub Release (.zip)# Download and extract the release zip from GitHub
wget https://github.com/Lusan-sapkota/TimeRing/releases/download/v1.0.0/Application.zip
unzip Application.zip
# Inside the extracted folder, you'll find TimeRing_1.0.0.deb
sudo dpkg -i TimeRing_1.0.0.deb
# Launch the app
timeringUninstall (.deb package)sudo dpkg -r timering |
Prefer a direct .deb file? Install from SourceForge (.deb)# Download the .deb package directly
wget https://sourceforge.net/projects/timering/files/TimeRing_1.0.0.deb/download
# Install
sudo dpkg -i TimeRing_1.0.0.deb
# Launch
timeringUninstall (.deb package)sudo dpkg -r timering |
🔧 Click to expand manual installation instructions
# Ubuntu/Debian
sudo apt update && sudo apt install python3 python3-pip git
# Fedora/RHEL
sudo dnf install python3 python3-pip git
# Arch Linux
sudo pacman -S python python-pip git# 1. Clone the repository
git clone https://github.com/Lusan-sapkota/TimeRing.git
cd TimeRing
# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run the application
python3 main.py|
Give your timer a meaningful name (e.g., "Work Session", "Tea Brewing") |
Set time in hours, minutes, seconds anything you want (or simply use the quick time) |
Click the icon to add max 50 words description (optional) |
Click the icon to select custom sound, can be customized per timer or global deafult (optional) |
Each timer card displays comprehensive information and controls:
|
|
| State | Icon | Color | Available Actions |
|---|---|---|---|
| Running |  |
Green | Pause, Stop, Edit, Change Sound |
| Paused |  |
Orange | Resume, Stop, Edit, Change Sound |
| Ringing |  |
Red | Stop (to silence) |
| Time's Up |  |
Red | Rerun, Edit, Delete |
💡 Pro Tip: Icons provide instant visual feedback - look for the color-coded status indicators to quickly understand your timer states at a glance!
The large, dedicated display at the top shows your current focus timer:
|
|
Access powerful configuration options through the header icons:
|
• Global default notification sound • Desktop notifications toggle • Auto-start timers on launch • Notification urgency levels • Update checks & sound looping |
• User guide & tutorials • Troubleshooting tips • Keyboard shortcuts • Feature explanations • Best practices |
• Version information • Developer details • System compatibility • License information • Credits & acknowledgments |
TimeRing stores all settings in your home directory:
~/.config/TimeRing/
├── settings.json # Application preferences and defaults
└── timers.json # Current timer states (auto-saved)
Personalize TimeRing's appearance by modifying style.qss:
/* Modern button styling */
QPushButton#startButton {
background-color: #4CAF50;
border-radius: 8px;
padding: 8px 16px;
font-weight: bold;
}
/* Custom timer card appearance */
QFrame#timerCard {
background-color: #f5f5f5;
border: 1px solid #e0e0e0;
border-radius: 6px;
margin: 4px;
}
/* Dark theme support */
QMainWindow {
background-color: #2b2b2b;
color: #ffffff;
}
# Start minimized to system tray
python3 main.py --minimized
# Load custom style sheet
python3 main.py --style custom.qss |
# Enable debug logging
python3 main.py --debug
# Set custom config directory
python3 main.py --config-dir ~/.timering |
|
Supported Distributions:
|
Fully Tested:
|
🔧 Windows/macOS Support: While TimeRing may run on other platforms with Python and PyQt5, some features (particularly desktop notifications and audio) are optimized for Linux and may require additional configuration.
We welcome contributions from the community! Here's how you can help make TimeRing even better:
# 1. Fork and clone your repository
git clone https://github.com/Lusan-sapkota/TimeRing.git
cd TimeRing
# 2. Create development environment
python3 -m venv dev-env
source dev-env/bin/activate
# 3. Install dependencies
pip install -r requirements.txt
# 4. Run tests (optional)
python -m pytest tests/
# 5. Start developing!
python3 main.py- Fork the repository and create a feature branch
- Write clear, commented code following PEP 8
- Add tests for new functionality
- Update documentation as needed
- Submit a pull request with a clear description
|
While active development may be limited, maintenance updates and essential patches will be provided as needed to ensure continued stability and usability. |
|
|
Check this README and project wiki |
Join our GitHub Discussions | Use our Issue Tracker |
🔊 Audio notifications not working
Ensure VLC is installed:
# Ubuntu/Debian
sudo apt install vlc
# Fedora
sudo dnf install vlc
# Arch Linux
sudo pacman -S vlc🔔 Desktop notifications not showing
Check that libnotify is installed:
# Ubuntu/Debian
sudo apt install libnotify-bin
# Fedora
sudo dnf install libnotify
# Test notifications
notify-send "Test" "This is a test notification"🐍 Python version compatibility
TimeRing requires Python 3.11+. Check your version:
python3 --version
# If needed, install Python 3.11+
sudo apt install python3.11This project is licensed under the MIT License - see the LICENSE file for details.
 Lusan Sapkota Software Developer & Creator |
|
PyQt5 community for the excellent GUI framework |
All contributors who have helped improve TimeRing |
Beta testers who provided valuable feedback |
Icon designers for beautiful system icons |