Overview

MyTimer is a Python project that aims to provide a simple yet efficient timer for terminal users, particularly targeting the geek community. This project allows users to set timers directly from their command line interface, making it convenient for those who spend a significant amount of time working in the terminal!

The main objective of MyTimer is to offer a minimalistic and distraction-free timer experience. It provides a clean and straightforward interface, ensuring that users can focus solely on tracking time without any unnecessary clutter or distractions.

PyPI Counter
Github Stars

Branch	main	dev
CI

Code Quality

Installation

Source Code

• Download Version 2.7 or Latest Source
• pip install .

PyPI

• Check Python Packaging User Guide
• pip install mytimer==2.7

Usage

ℹ️ You can use mytimer or python -m mytimer to run this program

Version

mytimer --version

Info

mytimer --info

Basic

ℹ️ Press Ctrl + C to exit

mytimer

Time Limit

mytimer --minute=7 --second=30

mytimer --hour=2 --minute=20

Timer Mode

ℹ️ The default mode is countdown

mytimer --minute=7 --second=30 --countdown

mytimer --minute=7 --second=30 --countup

Repeat

ℹ️ The default value is 1

mytimer --repeat=3 --second=4

• Use --repeat=-1 for infinite loop

Alarm

⚠️ This mode may not be supported on all systems

mytimer --minute=7 --second=30 --alarm

Alarm Repeat

ℹ️ The default value is 1

mytimer --minute=7 --second=30 --alarm --alarm-repeat=5

Tone

ℹ️ The default tone is 1

mytimer --minute=7 --second=30 --alarm --tone=2

• Use --tone=-1 for random mode
• Use --test-tone for test
• Tones List

Face

mytimer --minute=7 --second=30 --face=3

• Use --face=-1 for random mode
• Faces List
• mytimer --faces-list

Vertical/Horizontal Shift

ℹ️ The vertical and horizontal shift both have default values of 0

mytimer --v-shift=20 --h-shift=30

Timer Sign

ℹ️ Valid choices: ["", "+", "-"]

mytimer --sign="+"

Keep on

In this mode, the timer will continue running after it times out

mytimer --minute=5 --keep-on

Hide Second

In this mode, the timer seconds counter will not be shown

mytimer --minute=6 --hide-second
mytimer --minute=6 --no-second

Hide Date/Time

In this mode, the date/time will not be shown

mytimer --minute=20 --hide-datetime
mytimer --minute=20 --no-datetime

Date System

ℹ️ Valid choices: [gregorian, jalali]

ℹ️ The default date system is gregorian

mytimer --minute=20 --date-system=jalali

Vertical Mode

mytimer --minute=5 --vertical

Set on

⚠️ Local time

In this mode, the timer sets on the given time. For example, here we set a timer for 15:05:

mytimer --hour=15 --minute=5 --set-on

Program

mytimer --program=black-tea

• Programs List
• mytimer --programs-list

Message

mytimer --minute=7 --second=30 --message="Test message"

Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [black, red, green, yellow, blue, magenta, cyan, white, lightblack, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan, lightwhite, random]

ℹ️ The default color is white

mytimer --minute=7 --second=30 --color="red"

Background Color

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [black, red, green, yellow, blue, magenta, cyan, white, lightblack, lightred, lightgreen, lightyellow, lightblue, lightmagenta, lightcyan, lightwhite, random]

ℹ️ The default background color is black

mytimer --minute=7 --second=30 --bg-color="blue"

Intensity

⚠️ This mode may not be supported on all systems

ℹ️ Valid choices: [normal, bright, dim, random]

ℹ️ The default intensity is normal

mytimer --minute=7 --second=30 --intensity="bright"

Screen Record

Issues & Bug Reports

Just fill an issue and describe it. We'll check it ASAP!

• Please complete the issue template

References

1- Mixkit Free Alarm Sound Effects

2- Online Timer

3- Media College

4- Pomodoro Technique

5- The Rule of 52 and 17: It's Random, But it Ups Your Productivity

6- Desktime’s Productivity Research: An Overview of Our Finds Throughout the Years

7- AnimeDoro Timer

8- Know Your Tea: Your Guide to Tea Steeping Time

9- How Long to Steep Tea: A Complete Guide

10- How Long to Steep French Press: Mastering the Perfect Brew

11- Freesound

12- Online Timer with Alarm and Sound

Show Your Support

Star This Repo

Give a ⭐️ if this project helped you!

Donate to Our Project

Bitcoin

1KtNLEEeUbTEK9PdN6Ya3ZAKXaqoKUuxCy

Ethereum

0xcD4Db18B6664A9662123D4307B074aE968535388

Litecoin

Ldnz5gMcEeV8BAdsyf8FstWDC6uyYR6pgZ

Doge

DDUnKpFQbBqLpFVZ9DfuVysBdr249HxVDh

Tron

TCZxzPZLcJHr2qR3uPUB1tXB6L3FDSSAx7

Ripple

rN7ZuRG7HDGHR5nof8nu5LrsbmSB61V1qq

Binance Coin

bnb1zglwcf0ac3d0s2f6ck5kgwvcru4tlctt4p5qef

Tether

0xcD4Db18B6664A9662123D4307B074aE968535388

Dash

Xd3Yn2qZJ7VE8nbKw2fS98aLxR5M6WUU3s

Stellar

GALPOLPISRHIYHLQER2TLJRGUSZH52RYDK6C3HIU4PSMNAV65Q36EGNL

Zilliqa

zil1knmz8zj88cf0exr2ry7nav9elehxfcgqu3c5e5

Coffeete

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Unreleased

2.7 - 2026-10-09

Added

• --no-second argument
• --no-datetime argument

Changed

• countdown_timer function modified
• countup_timer function modified
• run_timer function modified
• print_mytimer_info function modified
• main function modified
• setuptools deprecation warning fixed
• CLI arguments modified
• Dependencies structure modified
• README.md updated
• Test system modified
• Python 3.7 support dropped

2.6 - 2026-04-23

Added

• 2 new programs
  1. pizza
  2. pancake
• Color random mode
• Background-color random mode
• Intensity random mode

Changed

• README.md updated
• Test system modified

2.5 - 2026-02-10

Added

• --intensity argument
• Light colors

Changed

• README.md updated
• Test system modified
• Background color bug fixed
• set_color function modified
• set_bg_color function modified
• run_timer function modified
• Arguments moved to handle_args function
• main function moved to functions.py
• --set-on flag bug fixed
• Screen record updated

2.4 - 2025-12-04

Added

• --color argument
• --bg-color argument

Changed

• load_program_params function modified
• pomodoro_timer function modified
• two_step_timer function modified
• select_timer_func function renamed to select_timer_function
• mytimer_info function renamed to print_mytimer_info
• run_timer function modified
• Python 3.14 added to test.yml
• README.md updated
• Test system modified

2.3 - 2025-07-17

Added

• 2 new programs
  1. eye-break
  2. power-nap
• Start time

Changed

• README.md updated
• Python typing features added to all modules
• print_date_time function modified
• Test system modified
• Python 3.6 support dropped

2.2 - 2025-03-13

Added

• --date-system argument

Changed

• README.md updated
• Test system modified
• countdown_timer and countup_timer functions updated
• String templates modified
• Input case sensitivity bug fixed

2.1 - 2025-02-28

Added

• 4 new tones
• --vertical argument
• --test-tone argument

Changed

• README.md updated
• Test system modified
• countdown_timer and countup_timer functions updated

2.0 - 2025-01-30

Added

• 2 new programs
  1. coffee-break
  2. meditation
• Clock and date
• --hide-datetime argument

Changed

• README.md updated
• Test system modified
• countdown_timer and countup_timer functions updated

1.9 - 2024-12-18

Added

• 5 new tones
• --info argument
• --hide-second argument

Changed

• GitHub actions are limited to the dev and main branches
• countdown_timer and countup_timer functions updated
• README.md updated
• TONES.md updated

1.8 - 2024-10-23

Added

• 5 new tones
• Face random mode
• Tone random mode
• get_face function
• get_tone function

Changed

• show_faces_list function updated
• README.md updated
• Test system modified
• Python 3.13 added to test.yml

1.7 - 2024-10-09

Added

• 2 new programs
  1. mate
  2. french-press
• 9 new tones

Changed

• README.md updated

1.6 - 2024-08-30

Added

• 2 new programs
  1. puer-tea
  2. purple-tea
• --set-on argument

Changed

• Default mode changed from count-up to countdown
• white-tea program duration changed from 10 minutes to 3 minutes

1.5 - 2024-08-12

Added

• 2 new programs
  1. rooibos-tea
  2. yellow-tea
• --keep-on argument

Changed

• README.md updated
• Programs message updated

1.4 - 2024-07-15

Added

• 1 new program
  1. mid-break
• --repeat argument
• --sign argument

Changed

• long-break program duration changed from 15 minutes to 30 minutes
• README.md updated

1.3 - 2024-05-23

Added

• 1 new program
  1. animedoro
• two_step_timer function
• print_message function
• SECURITY.md

Changed

• Test system modified
• nava added to requirements.txt
• Sound playing system updated
• Python 3.5 dropped
• short-break program duration changed from 10 minutes to 5 minutes
• long-break program duration changed from 30 minutes to 15 minutes
• pomodoro program updated
• pomodoro_timer function modified
• load_params function modified
• README.md updated

Removed

• animedoro_timer function
• _112_26_timer function
• _52_17_timer function

1.2 - 2024-02-05

Added

• feature_request.yml template
• config.yml for issue template
• 2 new programs
  1. 52-17
  2. 112-26

Changed

• Bug report template modified
• run_timer function modified

1.1 - 2023-12-20

Added

• 1 new program
  1. pomodoro

Changed

• TIME_PRINT_TEMPLATE changed
• KeyboardInterrupt exit handling updated
• ADDITIONAL_INFO added to argparser epilog
• Python 3.12 added to test.yml

1.0 - 2023-11-08

Added

• --programs-list argument
• --faces-list argument
• --v-shift argument
• --h-shift argument
• DEFAULT_PARAMS parameter
• PROGRAMS_DEFAULTS parameter
• load_program_params function

Changed

• japanese-green-tea program bug fixed
• README.md updated

0.9 - 2023-10-04

Added

• 4 new faces
• 4 new programs
  1. work
  2. short-break
  3. long-break
  4. noodle

Changed

• PROGRAMS.md updated

0.8 - 2023-08-07

Added

• Logo
• --alarm-repeat argument

Changed

• Tones length modified
• README.md updated

0.7 - 2023-07-23

Added

• --tone argument
• TONES.md
• 9 new tones

Changed

• Test system modified
• input_check decorator renamed to input_handler
• countup_timer function inputs modified
• countdown_timer function inputs modified
• PROGRAMS.md updated
• FACES.md updated

0.6 - 2023-07-04

Added

• --program argument
• PROGRAMS.md
• run_timer function

Changed

• Inputs type changed to int
• README.md updated
• WRONG_INPUT_ERROR renamed to INPUT_ERROR_MESSAGE
• Alarm tone changed

0.5 - 2023-05-25

Added

• 5 new faces
• --message argument

Changed

• play_sound function modified
• playsound removed from requirements.txt
• README.md updated

0.4 - 2023-02-10

Added

• 4 new faces
• Infinite timer mode

Changed

• README.md updated
• Parameters moved to params.py

0.3 - 2022-11-25

Added

• --face argument
• FACES.md

Changed

• README.md updated
• Minimum art library version changed from 1.8 to 2.9

0.2 - 2022-11-03

Added

• --version flag

Changed

• Test system modified
• countdown_timer function modified
• countup_timer function modified

0.1 - 2022-10-18

Added

• Countdown mode
• Count-up mode
• Alarm