Skip to content

A customizable and cross-platform timer script inspired by the Pomodoro Technique. Perfect for managing work sessions and breaks with notifications and sound alerts.

License

Notifications You must be signed in to change notification settings

Exios66/python-session-timer

Repository files navigation

🕒 Python Session Timer

License Python Documentation Status Pages Build Status GitHub Pages Coverage Status GitHub issues GitHub stars GitHub forks GitHub last commit Code style: black

A customizable and cross-platform timer script inspired by the Pomodoro Technique. Perfect for managing work sessions and breaks with notifications and sound alerts.

📦 Features

  • Customizable Durations: Set your preferred work and break durations.
  • Cycle Management: Define the number of work-break cycles.
  • Notifications: Receive system notifications when timers end.
  • Sound Alerts: Play a sound when a timer concludes.
  • Cross-Platform: Works seamlessly on Windows, macOS, and Linux.
  • Easy to Use: Simple command-line interface with various options.

🚀 Installation

Prerequisites

  • Python 3.8 or higher installed on your system. Download from python.org.

Clone the Repository

git clone https://github.com/Exios66/python-session-timer.git
cd python-session-timer

Install Dependencies

Use pip to install the required Python packages:

pip install -r requirements.txt

Alternatively, install them individually:

pip install plyer simpleaudio

Prepare a Sound File

Ensure you have a sound file (e.g., alarm.wav) in the project directory or specify the path to your preferred sound file when running the script.

📝 Usage

Run the timer with default settings:

python timer.py

Customize Timer Settings

You can customize the timer using command-line arguments:

python timer.py -w 50 -b 10 -c 2 -s bell.wav -m "Work session over!" --title "Break Time"

Command-Line Options

Option Description Default
-w, --work-duration Work duration in minutes 25 minutes
-b, --break-duration Break duration in minutes 5 minutes
-c, --cycles Number of work-break cycles 4 cycles
-s, --sound Path to the sound file to play when timer ends alarm.wav
-m, --message Notification message when timer ends Time is up!
--title Notification title Timer Alert

Example Usage

python timer.py -w 45 -b 15 -c 3 -s notification.wav -m "Time for a break!" --title "Work Session Complete"

📜 Script Overview

```python
#!/usr/bin/env python3
"""
Customizable Timer Script

This script implements a customizable timer similar to a Pomodoro timer.
It allows setting custom work and break durations, number of cycles,
and plays a sound and displays a notification when the timer ends.

Dependencies:
- plyer (for notifications)
- simpleaudio (for playing sound)

Install dependencies with:
pip install plyer simpleaudio

Usage:
python timer.py [options]

Options:
- -w, --work-duration: Work duration in minutes (default: 25)
- -b, --break-duration: Break duration in minutes (default: 5)
- -c, --cycles: Number of cycles (default: 4)
- -s, --sound: Path to sound file to play when timer ends (default: alarm.wav)
- -m, --message: Notification message (default: "Time is up!")
- --title: Notification title (default: "Timer Alert")
"""
import time
import argparse
import sys
import os

def main():
    # Parse command-line arguments
    args = parse_arguments()

    # Check if sound file exists
    if not os.path.exists(args.sound):
        print(f"Sound file '{args.sound}' not found.")
        sys.exit(1)

    # Import plyer and simpleaudio
    try:
        from plyer import notification
    except ImportError:
        print("Module 'plyer' not found. Install it by running 'pip install plyer'")
        sys.exit(1)

    try:
        import simpleaudio as sa
    except ImportError:
        print("Module 'simpleaudio' not found. Install it by running 'pip install simpleaudio'")
        sys.exit(1)

    # Main loop
    for cycle in range(1, args.cycles + 1):
        print(f"Cycle {cycle}/{args.cycles}: Work for {args.work_duration} minutes.")
        countdown(args.work_duration)

        send_notification(args.title, args.message)
        play_sound(args.sound)

        if cycle != args.cycles:
            print(f"Take a break for {args.break_duration} minutes.")
            countdown(args.break_duration)
            send_notification(args.title, 'Break time is over!')
            play_sound(args.sound)
    print("All cycles completed.")

def parse_arguments():
    parser = argparse.ArgumentParser(description='Customizable Timer with Notifications and Sound')

    parser.add_argument('-w', '--work-duration', type=int, default=25,
                        help='Work duration in minutes (default: 25)')
    parser.add_argument('-b', '--break-duration', type=int, default=5,
                        help='Break duration in minutes (default: 5)')
    parser.add_argument('-c', '--cycles', type=int, default=4,
                        help='Number of cycles (default: 4)')
    parser.add_argument('-s', '--sound', type=str, default='alarm.wav',
                        help='Path to sound file to play when timer ends (default: alarm.wav)')
    parser.add_argument('-m', '--message', type=str, default='Time is up!',
                        help='Notification message (default: "Time is up!")')
    parser.add_argument('--title', type=str, default='Timer Alert',
                        help='Notification title (default: "Timer Alert")')

    args = parser.parse_args()
    return args

def countdown(duration):
    total_seconds = duration * 60
    try:
        while total_seconds:
            mins, secs = divmod(total_seconds, 60)
            timer = '{:02d}:{:02d}'.format(mins, secs)
            print(f"Time left: {timer}", end='\r')
            time.sleep(1)
            total_seconds -= 1
        print()  # Move to next line after countdown
    except KeyboardInterrupt:
        print("\nTimer interrupted by user.")
        sys.exit(0)

def send_notification(title, message):
    notification.notify(
        title=title,
        message=message,
        timeout=10
    )

def play_sound(sound_file):
    try:
        import simpleaudio as sa
        wave_obj = sa.WaveObject.from_wave_file(sound_file)
        play_obj = wave_obj.play()
        play_obj.wait_done()
    except Exception as e:
        print(f"Error playing sound: {e}")

if __name__ == "__main__":
    main()

```python

***

### 🔧 Deployment Considerations

• Cross-Platform Compatibility: The script is designed to work on Windows, macOS, and Linux systems.
• Dependencies: Ensure all dependencies are included in your deployment package or specified in your requirements.txt file.
• Error Handling: The script includes error handling for missing dependencies and sound files.
• Customization: All timer settings are easily customizable via command-line arguments.

📄 Requirements

Ensure you have the following dependencies installed:

plyer simpleaudio

You can install them using:

pip install -r requirements.txt

Sample requirements.txt:

plyer simpleaudio

🤝 Contributing

Contributions are welcome! Please follow these steps:

  1. Fork the repository.
  2. Create a new branch (git checkout -b feature/YourFeature).
  3. Commit your changes (git commit -m 'Add some feature').
  4. Push to the branch (git push origin feature/YourFeature).
  5. Open a Pull Request.

Please ensure your code adheres to the project’s coding standards and includes appropriate documentation.

📜 License

This project is licensed under the MIT License.

📫 Contact

Exios66

•GitHub: @Exios66 •Email: youremail@example.com

🎉 Acknowledgements

•Inspired by the Pomodoro Technique. •Utilizes Plyer for notifications. •Utilizes Simpleaudio for sound playback.

Happy Coding!

License

About

A customizable and cross-platform timer script inspired by the Pomodoro Technique. Perfect for managing work sessions and breaks with notifications and sound alerts.

Resources

License

Stars

Watchers

Forks

Packages

No packages published