🎯 Ultimate Focus Timer

A comprehensive, cross-platform productivity timer application implementing the Pomodoro Technique with classical music integration, multiple interfaces, and detailed analytics. Built with pure Python for maximum compatibility and ease of use.

✨ Key Features

• 🎮 Multiple Interfaces: GUI, Console, Dashboard, and Interactive Launcher
• 📋 Task Management: Add, complete, and track tasks during focus sessions
• 🎵 Music Integration: Classical music playback with cross-platform audio support
• 📊 Analytics & Tracking: Comprehensive session logging and productivity insights
• 🔔 Smart Notifications: Cross-platform desktop notifications with early warnings
• ⚙️ Highly Configurable: YAML-based configuration with theme support
• 🌍 Cross-Platform: Windows, macOS, and Linux support

💻 Download & Installation

Windows Executable

The easiest way to use Ultimate Focus Timer on Windows is to download the pre-built executable:

1. Go to the Releases page
2. Download the latest UltimateFocusTimer-windows-x64.zip file
3. Extract the ZIP file
4. Run UltimateFocusTimer.exe

No installation or Python environment required!

Other Platforms

For macOS and Linux users, please see the Installation Guide for platform-specific instructions.

📸 Screenshots

GUI Interface

Console Interface

Dashboard Analytics

📋 Task Management

The application includes comprehensive task management capabilities to help you stay organized and productive:

Features

• Always-Visible Task Entry: Input field is permanently visible for quick task entry
• Smart Placeholder: Green "+add (T)" placeholder text that disappears when typing
• Keyboard Shortcuts: Press 'T' to focus on the task entry field instantly
• Real-Time Tracking: Add and complete tasks during your focus sessions
• Visual Feedback: Completed tasks are clearly marked with timestamps

How to Use

1. Type your task directly in the always-visible task entry field
2. Press Enter to add the task to your current session
3. Use keyboard shortcut 'T' for quick task entry focus
4. Mark tasks as complete during or after your work session
5. View task history and completion tracking in your session analytics

The streamlined interface eliminates unnecessary buttons and maximizes your productivity by keeping task management simple and accessible.

🚀 Quick Start

# Clone the repository
git clone https://github.com/ahmelkholy/ultimate-focus-timer.git
cd ultimate-focus-timer

# Set up virtual environment
python -m venv .venv
.venv\Scripts\Activate.ps1  # Windows PowerShell

# Install dependencies
pip install -r requirements.txt

# Run setup
python setup.py

# Launch the application
python main.py

📖 Documentation

• Complete Documentation - Full user guide and features
• Virtual Environment Setup - Detailed environment configuration
• Contributing Guide - How to contribute to the project
• Changelog - Version history and updates

🎯 Quick Launch Commands

python main.py                    # Interactive launcher
python main.py --gui             # GUI interface
python main.py --console         # Console interface
python main.py --dashboard       # Analytics dashboard
python main.py --pomodoro        # Quick 25-minute session
python main.py --work 30         # Custom work session
python main.py --info            # System information

🛠️ System Requirements

• Python 3.8+ (Python 3.10+ recommended)
• MPV Media Player (auto-installed by setup script)
• Supported Platforms: Windows 10/11, macOS 10.14+, Linux

📦 Installation

Automatic Setup (Recommended)

python setup.py

Manual Setup

# Install dependencies
pip install -r requirements.txt

# Install MPV (Windows with Chocolatey)
choco install mpv

# Install MPV (macOS with Homebrew)
brew install mpv

# Install MPV (Linux)
sudo apt install mpv  # Ubuntu/Debian
sudo dnf install mpv  # Fedora

🏗️ Building the Executable

# Ensure dependencies are installed
python -m pip install -r requirements.txt

# Build a standalone one-file executable
python build_config.py

The generated executable will be located in the dist/UltimateFocusTimer directory.

🎵 Music Features

• Classical Music Integration: Automatic background music during work sessions
• Cross-Platform Audio: Powered by MPV for consistent experience across platforms
• Volume Control: Adjustable music levels with smooth fade transitions
• Multiple Playlists: Curated classical, baroque, and piano collections
• Custom Playlists: Support for local files and online streams

📊 Analytics & Insights

• Session Tracking: Automatic logging of all timer sessions
• Productivity Metrics: Completion rates, trends, and scoring
• Visual Analytics: Beautiful charts and graphs
• Export Options: CSV export for external analysis
• Goal Tracking: Progress monitoring and achievement tracking

⚙️ Configuration

Edit config.yml to customize:

# Session Settings
work_mins: 25
short_break_mins: 5
long_break_mins: 15

# Task Management
enable_task_tracking: true
auto_focus_task_entry: true

# Music Settings
classical_music: true
classical_music_volume: 70
fade_music_transitions: true

# Interface Settings
dark_theme: true
accent_color: "#00ff00"
animated_transitions: true

🤝 Contributing

We welcome contributions! See our Contributing Guide for details.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Francesco Cirillo for the Pomodoro Technique
• MPV Media Player for excellent cross-platform audio support
• Python Community for the amazing ecosystem

---

Stay focused and productive! 🎯

Built with ❤️ for productivity enthusiasts worldwide